Three.js: Suggestion: Add image thumbnails to examples menu

[callumprentice]

Thumbnails would make browsing the examples more useful

I love spending time browsing the examples and getting inspiration or ideas for my next sketch or experiment but always find it difficult to remember what each one does.

I made a test that optionally displays an image thumbnail with each entry on the main example page. The images can be shown or hidden using the "Image" button to left next to the search filter. Excuse the hastily thrown together SVG file.

I wrote a C++ app that embeds Chromium to render each page of examples and capture the output as a JPEG file and I use that for each thumbnail. It's fully automated so some may not be the best representation of the example but it's straightforward to recapture as necessary.

Is this worth pursuing and if so, I can make a proper pull-request in a fork.

Thank you.

• Example (I made a demo to illustrate what I mean)

Three.js version

• [x] Dev
• [x] r109
• [ ] ...

Browser

• [x] All of them
• [ ] Chrome
• [ ] Firefox
• [ ] Internet Explorer

OS

• [x] All of them
• [ ] Windows
• [ ] macOS
• [ ] Linux
• [ ] Android
• [ ] iOS

Hardware Requirements (graphics card, VR Device, ...)

[looeee]

This is really nice and makes browsing through the examples a lot easier.

There might be some resistance to adding a C++ app here though, I think JS and Python are the only languages currently used in this repo. Would it be possible to write a node.js script to do that instead?

[mrdoob]

Yeah, I would be more comfortable if this was done using https://github.com/GoogleChrome/puppeteer.

As per the design, I think I would just add the thumbnails as a grid in the main page. Similar to https://threejs.org.

[callumprentice]

I should have been more clear - the C++ app embeds Chromium in order to do what it does so it's enormous and not feasible to include here. It was just to make an initial image pass over the examples. Luckily it generated a thumbnail that was acceptable for most of them but I always imagined there would be a manual pass afterwards - e.g. the VR ones that do not render on my system.

Going forwards for new or visually updated examples, I foresaw more of this manual step.

However, I realize that's going to be time consuming to get right - so that the browser size matches size of the other images for example - so I guess we do need a web based method like Puppeteer. I'll take a look.

As for the design, my first pass generated a page like the grid at http://threejs.org but I figured you'd want to keep the examples looking the same - plus the nice benefit of being able to filter was already there.

[callumprentice]

https://3ve.surge.sh/examples/new_example.html

A simple grid layout using existing thumbs but no search.

[mrdoob]

This is what I meant:

[callumprentice]

I see although the grid of images needs to be a standalone page doesn't it or else clicking on a text link on the left will replace it with an example?

I put a v2 test together - is that closer to something that works?

https://3ve.surge.sh/examples/v2.html

An handy additional feature to this or the existing one is a way to show just new and updated examples - tag then with 'new' or 'modified' perhaps and let people search for that too.

Cheers.

[mrdoob]

I see although the grid of images needs to be a standalone page doesn't it

Yep!

[looeee]

This looks amazing! Great job ❤️

[callumprentice]

As far as automated thumbnails go, there might be a way with Puppeteer but grabbing new ones each time without a way to tell if it’s the most representative version would be hard.

Is it a realistic option to manually resize browser, screen cap and resize image for just the new ones? I realize that might be a burden in what must be a complex process. I’m happy to do it for each release but that may not be scalable.

[mrdoob]

Is it a realistic option to manually resize browser, screen cap and resize image for just the new ones? I realize that might be a burden in what must be a complex process. I’m happy to do it for each release but that may not be scalable.

Sounds like a big red flag to me 😅

[looeee]

grabbing new ones each time without a way to tell if it’s the most representative version would be hard.

Are the current thumbnails auto-generated? They look OK to me.

[callumprentice]

Most were but I grabbed a couple by hand - the logic just waits 5 seconds I think after the page load and takes a shot. The ones that look somewhat representative are just lucky :)

[callumprentice]

So I updated the actual display page a little but the main change is a Node script in a new folder under utils/examples that uses Google Puppeteer to generate the thumbnails. Works pretty well.

I had to add some logic to allow "Tweaks" to an experiment - to wait longer once it's loaded before the capture takes place or inject a "click" into the page so that audio examples start etc.

New display page (Preview):
https://3ve.surge.sh/examples/v3.html

Thumbnail:
https://github.com/callumprentice/three.js/blob/dev/utils/examples/generate_thumbs.js

What do you think - getting close to a PR?

[mrdoob]

So much nicer!

[callumprentice]

Yay! I'm making the JS Puppeteer code a lot nicer and trying to see if I can move away from the "wait for N ms before capture" towards something a bit cleverer. Maybe scanning the capture and waiting for a wide range of pixel colors to appear would work - and avoid the flat black/grey captures you can get if the example hasn't loaded or started rendering..

So much fun..

[callumprentice]

I added a link to the GitHub source for each experiment. Not thrilled with the explicit positioning of the GH link but letting the browser lay it out doesn't work well either.

Updated display page with source link
https://3ve.surge.sh/examples/v3.html

Thumbnail generator cleaned up a bit
https://github.com/callumprentice/three.js/blob/dev/utils/examples/generate_thumbnails.js

Should I go ahead and submit a PR ?

[callumprentice]

This has been open a couple of months and I made a PR but no more feedback. Should I assume it's not wanted or not of the necessary quality and close both?

[mrdoob]

Sorry, haven't been able to look at it yet.

It can take a while sometimes... For example, #15121 is more than one year old and it may be merged this month.

[callumprentice]

Understood and no worries. I’ll check back next ~month~ ~year~ decade.

Thanks.