![[icon]](https://learning-python.com/thumbspage/docetc/space-monkey.jpg "tap for online demo")
|
|
thumbspage — Turn Folders into HTML Image Galleries |
|---|
| Version: | 3.0.1, August 12, 2025 (changes) |
| License: | Provided freely, but with no warranties of any kind |
| Author: | © M. Lutz (learning-python.com) 2016-2025 |
| Views: | Any PC or mobile browser, local or remote |
| Builds: | Any host that runs Python 3.X and Pillow |
| Installs: | thumbspage, any Python 3.X, and Pillow |
| See also: | web page, live demo, screenshots, client |
Welcome to the thumbspage manual. This guide is meant for content creators and consumers of all kinds. It includes an overview of the program, detailed usage information, and a look at what's been upgraded in each release. Whether you consider yourself a developer or user, you'll find resources here to help you get started building and viewing image galleries with thumbspage.
Because thumbspage adds items to the images source folder and may rotate photos there, you are encouraged to read this guide first—especially its usage caution—before running thumbspage on valued picture collections. But if you're in a hurry: for a quick preview, try a live demo, packaged examples, or the code. You can also click the image above to test-drive the original use case, and take a brief tour of this program at its web page.
Because this program has evolved over time, this section summarizes the current state of using and building galleries as of thumbspage's latest version, 3.0. Later sections of this guide go into more details on this summary's topics. For more context, also see the 3.0 demo and screenshot galleries.
index.html. You can open this file by visiting the gallery's
web URL in your browser or by clicking its local version in a file explorer.
The index.html file is known as the index page; its thumbnails open
viewer pages for individual images when tapped.
Depending on the gallery, both page types may be colorized per the light or dark
display-mode setting on your device. Change your mode to see the effect.
The next sections cover these pages' usage.
An index page displays thumbnails for all the images in a gallery. Depending on how a gallery is built, resizing the window or display either reorganizes thumbnails to fit the new space or makes them accessible with horizontal scrolls as needed.
Scroll index pages vertically to view more thumbnails, using your device's
normal scrolling techniques (e.g., swipe, bar, or mousewheel). Click the
Top button at the bottom when it's available to jump to the top
of the index, and tap any thumbnail to open an image's viewer page.
A viewer page displays one image in the gallery, scaled to fit the view. Resizing the window or display automatically rescales the image to fit the new available space. In a viewer page, navigate and invoke other actions with:
About swipes: For touchscreens, perform swipe gestures on image itself, using one finger. For touchpads and mousewheels, the location of the mouse cursor does not matter for swipes, and swipes may use two fingers on touchpads. Touchpad and mousewheel swipes are more laggy than touchscreen swipes or keyboard presses and best kept short.
Also note that your system settings may invert swipe directions. A down swipe, for instance, may mean swiping toward either the bottom or top of your display, depending on your settings, and the meaning of left and right swipes can be swapped by both your settings and gallery builds. Experiment with swipes on your device to see which actions they trigger.
The following actions are available on all viewer pages:
Index tap, i key, browser back
Index, press
keyboard key i, or use your browser's back action
(a button or gesture also called Back).
Your browser's back action returns to your prior position in
the index page, and the viewer page's button or key returns
to index-page top.
Next/Prev tap,
left/right swipe, n/p key
Next or
Prev, perform a left or right swipe gesture, or
press keyboard keys n or p.
Messages appear when navigation wraps around to the first or
last image in the gallery, and some galleries may have
end-of-gallery pages.
Auto tap, a key
Auto or press keyboard key a.
Repeat to stop the slideshow. Slideshows are an automatic Next
with a delay between images and continue until toggled off.
Full tap, f key
Full
or press keyboard key f. Repeat to close fullscreen mode.
This is a quick zoom but lasts for just one page. Some browsers have
more permanent fullscreen options (e.g., F11 on Windows and Linux,
shift+command+f or upper-left green button on macOS, Hide Toolbar
on iOS, and icons on some Android browsers).
Note tap, up swipe, t key
Note,
perform an up swipe on the image itself, or press keyboard key t.
Close the note with the popup's bottom OK button, the keyboard
Enter key, or a tap anywhere outside the note. Notes remain
open for further reading until closed by the user, even after navigating to
the index or other images, or returning from a link.
? key
?.
Close the info with the popup's bottom OK button, the keyboard
Enter key, or a tap anywhere outside the info.
. key, up swipe?
. key. This action is also
triggered by an up swipe when no image notes are present. Use the
browser's back action to return to the gallery, per the popup reminder message.
Thumbspage is a Python command-line program distributed in source-code form.
To use it to build a gallery, first download and unzip its code
folder,
and install any Python 3.X
and its free
Pillow
extension. Then, run the unzipped folder's thumbspage.py
script in your console (e.g., Terminal, Command Prompt, or app), providing
gallery configuration options in any of the following forms:
user_configs.py file's assignments
option=value
The user_configs.py file resides in
the program's own install folder. It defines all available configuration options
as Python assignment statements (option = value) and documents
their roles and values. The names assigned in this file are the
options' names.
Each option can also be provided as option=value
arguments in the thumbspage.py command line, which override
assignments to same-named options in user_configs.py.
For legacy reasons, a handful of primary options are asked at
the console if their corresponding option remains set to None
in user_configs.py and they are not provided as
option=value arguments.
These inputs all have option names in the user_configs.py file
(e.g., inputThumbMaxSize); set them in that file or pass as
arguments to avoid console inputs (e.g., inputThumbMaxSize=128).
As a special case, if a first argument is passed to
thumbspage.py and it is not of the form
option=value, it is assumed to be the
pathname of the gallery's folder, where your images and configuration
files reside. This can also be provided as option name
inputImagesFolderPath via user_configs.py
or command-line argument.
In sum, option configuration is layered as follows:
user_configs.py provides the preset defaults for options of
all builds, and can be changed by users freely.
option=value arguments may provide
per-build overrides for any of the preset defaults in user_configs.py.
user_configs.py or the build's command-line
arguments.
option=value.
In the following example command lines, thumbspage.py
may be the full pathname to the program's main script, and Windows
typically spans lines with ^ or ` instead of
\ and uses py or py -3 instead
of python3:
Use options in user_configs.py, ask if console inputs are None:
$ python3 thumbspage.py
Also provide the image folder's pathname as the first argument:
$ python3 thumbspage.py folder
Also provide arguments that override user_configs.py settings:
$ python3 thumbspage.py folder option1=value option2=value
Same as prior, in shells that support spanning lines with "\":
$ python3 thumbspage.py folder \
option1=value \
option2=value
A larger example with explicit options and no console inputs:
$ python3 ~/Downloads/thumbspage/thumbspage.py . \
useDynamicIndexLayout=True \
dynamicLayoutPaddingH=\'16px\' \
inputCleanThumbsFolder=True \
inputThumbMaxSize=128 \
inputUseViewerPages=True \
popupFgColor=\'wheat\' \
popupOpacity=0.45 \
omitIndexPageLabels=True
Provide console inputs from a file using stream redirection:
$ python3 ../thumbspage.py mypix popupFgColor=\'#ddd\' < inputs.txt
Provide console inputs with a "here" document in Bash and others:
$ python3 ../thumbspage.py mypix popupFgColor=\'blue\' <<-EOF
(128,128)
EOF
In addition to named configuration options, you may also optionally configure thumbspage galleries by:
imagename.ext.note text files
in the images folder, which give the note text for the corresponding
image file (see also the NOTES.py alternative ahead)
HEADER.html and FOOTER.html
files in the images folder, whose code is added at the top and bottom
of generated index page and replaces default code
ORDER.txt, NOTES.py, and
CAPTIONS.py files in the images folder, to give
image ordering, notes, and labels, respectively
template-*.html files, used
to construct pages in the generated gallery and vital to this
program's operation (please edit with care)
If used, HEADER.html and FOOTER.html contain the
HTML code used above and below the thumbnails table in index pages. They are
advanced tools described ahead.
ORDER.txt lists one filename per line to give an
explicit image order, and NOTES.py and CAPTIONS.py
contain a Python dictionary mapping image filenames to notes and labels.
If provided, these files' content overrides and augments filename
ordering, .note text files, and filename labels.
Whether coded in .note files or the NOTES.py
dictionary, image notes may embed HTML tags and entities passed to the
browser when escaped with a leading underscore. Notes are optional.
See user_configs.py and later
sections of this User Guide for additional details on all of the above.
After running thumbspage.py to build a gallery, open the
image folder's generated file index.html (its default name)
in your browser to view the resulting gallery. To publish a
built gallery, simply install the entire image folder on the local or
remote host, with a copy, zip+unzip, or upload as needed.
Include the image folder's generated _thumbspage subfolder,
which contains scaffolding files needed to view the gallery.
For more ideas, see the 3.0 demo's build and publish scripts.
This section introduces the basics of thumbspage's roles and operation. Read this first if you're looking for a quick summary.
In short, this program allows you to view or display a folder of images in a web browser, using a format which is simple by design yet noticeably better than browser defaults, and does not require a web server except when viewing images online.
thumbspage turns an images folder into an easily viewed gallery. It automatically makes image thumbnails, an HTML thumbnail-links index page, and HTML image-viewer pages for all the images in a source folder, all of which can be broadly customized by content creators. The mostly static results can be viewed offline or online in any web browser.
In a theoretical sense, thumbspage is a program that builds another program: its results are a combination of HTML, CSS, and JavaScript, which are run by a browser. More tangibly, thumbspage simply creates presentation scaffolding for user-friendly views of a folder's images.
In a bit more detail, given a folder of image files, this program generates an HTML index page in one of two flavors, with generated thumbnail links for each image in the folder. This page's links open the full-size images using either browser-native (i.e., built-in) display, or generated HTML viewer pages.
Viewer pages in turn dynamically scale the image to your display; include links for gallery navigation, automatic slideshows, and one-page fullscreen; and open image-info popups on filename clicks, and image-description popups on button taps when enabled. On mobile and PC touch screens, swipe gestures on the image trigger viewer-page actions too.
Apart from image scaling and interactive tools, the net effect is intentionally static: generated results reflect the folder's contents at build time only, but do not require a web server, and can be viewed both offline and online in any desktop or mobile browser. As such, this program can be used both for both websites and non-web use cases, including program documentation, photo sharing, and general viewing.
When run using the techniques explored ahead, the builder program skips non-image files; uses optional header and footer HTML inserts in the index page; uses text note files for any or all images in viewer pages; makes an optional bullet list for subfolders in the images folder; and creates the output index page in the images folder itself, along with a subfolder for thumbnail images and viewer pages. The resulting gallery is complete and self-contained, and ready to be viewed or published.
After running this program, you can view or publish its results in a variety of ways:
index.html
by default).
_thumbspage
and index.html by default, respectively).
As a client example, the website that hosts thumbspage uses it for some 50 galleries today, some of which are viewable both online at the site, and offline in program download packages. For a sampling, see this site's demos. Builders can also find gallery-build pointers in thumbspage's publishing scripts, though its simple console interaction or command lines may suffice for most uses.
thumbspage began as a builder of simple index pages that used generated thumbnail images for their links, but its feature set has evolved over time in response to usage experience. Among its new highlights added in recent releases:
setting=value command-line arguments override config-file
settings;
tooltips can be enabled on all
pages;
and more.
You can read the full story on new releases ahead. Move on to the next section to start learning how to use thumbspage to view and display your photos.
This section covers the basics of viewing the galleries which thumbspage creates. It's oriented towards gallery consumers (a.k.a. users), though creators might find its functionality overview helpful too. If you're looking for details on running the program to make galleries, though, see the builders' section.
By today's standards, thumbspage galleries are straightforward and intuitive to use. They work and may be viewed on any desktop or mobile browser, and both online and offline. No extensions must be installed in browsers to view thumbspage galleries, though JavaScript should be enabled for the best user-interface (UI) experience, and some browsers have known quirks that can impact gallery behavior (there's more on JavaScript and browsers in Viewing Tips ahead).
Once built, a thumbspage gallery consists of an index page opened initially, and one viewer page per image opened from either thumbnails on the index page, or direct page-address URLs. The next sections describe how these two page types are used.
Index pages are the usual entry point into a gallery. Here's one captured on desktop and mobile browsers, and its live version.
Index pages display thumbnail images, either in a fixed table which scrolls both horizontally and vertically as needed, or arranged to fit the display's size per the 2.1 update ahead. Either way, index-page thumbnails normally open the next section's larger image-viewer pages when tapped (or clicked). By default, index pages also display the image folder's basename, and a bullet-list of links that open subfolders nested in the page's folder, if any are present.
Beginning with 2.0, thumbspage index pages also usually display a floating Top button near page bottom after a scroll, much like that in this guide. Click (or tap) Top to jump to the top of the index page immediately—to read its preface or open its first image, for example. Top appears only after you scroll down far enough, so it may not show up on smaller index pages.
An index page's subfolders links
may lead to supplemental info or nested galleries, and their behavior varies per
usage mode. When viewing galleries online, subfolder links typically open
a nested gallery's index page automatically. When viewing
offline, these links open a simple directory listing, and you'll
manually click nested galleries' index pages (e.g., index.html)
if present. These links also open directory listings for non-gallery folders
on some online servers; tap filenames to open. There's more on subfolders
ahead.
While many index pages follow the preceding norm, individual galleries can also customize it with tailored header and footer content above and below the thumbnails table. They might also use thumbnails that open raw displays instead of viewer pages, may display tooltips on mouseovers, and can opt out of either floating Top buttons or subfolder bullet lists. Experiment with galleries you visit to see which options they support.
Update: as of version 2.1, thumbspage index pages may also use either a fixed or dynamic layout. By default, index pages use the original fixed layout, which always displays the same number of columns. In dynamic layout, the thumbnails table does not scroll horizontally; instead, the number of columns is chosen to match the display size, and changes when the display is resized. Dynamic layout is an option which can be enabled when a gallery is built. If you run across this alternative, you can shrink or expand your window on PCs and mobiles with popup app windows to view fewer or more columns. On mobile in general, switching device orientation has a similar effect. See the demo.
Index-page thumbnail clicks and taps by default open viewer pages (a.k.a. image-viewer pages in this doc) to display a single image. Here's one captured on desktop and mobile, along with its live version.
Viewer pages display the image's filename, the image itself, and a bottom toolbar of action buttons, and respond to swipe gestures on the image on touch screens. The image is automatically scaled to fill the window's or display's available space, and grows or shrinks in both directions with desktop-window resizes, mobile-device rotations, fullscreen toggles, and popup or split-screen app-window resizes on some mobiles. The toolbar has four to six named action items (Note and Full are optional), and scrolls horizontally to reveal buttons if needed on smaller displays. Viewer pages may display tooltips on mouseovers too; this is enabled by default when galleries are built.
Everything on a viewer page does something when tapped and images respond to swipes, as the following sections will describe.
All told, there are seven or eight actions available to users on viewer pages, five of which have swipe-gesture equivalents—and two of which are invoked with display widgets instead of buttons:
control or command with +/-),
and may yield a larger image depending on browser and display size.
Use the browser's back action (button or swipe) to return to the gallery's
viewer page. The Full toolbar button also zooms the image in most contexts, but
we have to move ahead to see how.
As of 2.2, the image-tap event is also triggered by an up swipe on the image in
supporting browsers when image notes are unused (see ahead).
The remaining viewer-page actions can all be requested by tapping named toolbar buttons (or swiping equivalently), and one is optional and may be omitted when a gallery is built:
Keep in mind that this feature is optional and new: Note buttons will be present and up swipes will open notes only if notes were enabled at gallery build time. If notes are unused, up swipes open raw views as in 2.2; if notes are used, you can still open raw views with an image tap. Also note that Note popups don't stay open during Auto slideshows; tap Auto to stop and read a note along the way, per the next item here.
When active, a slideshow applies to all thumbspage viewer pages visited in a single browser tab. They stop (really, pause) when you leave a gallery's pages, and may be cancelled or restarted at any time by pressing Auto again in any viewer page. The Prev and Next toolbar buttons work during, and do not cancel, an active slideshow; use these to skip or move to images during the show. You can also use Index or your browser's Back function to pick an image from the gallery's index page at which to continue the slideshow in progress. In most contexts, a Back or any other navigation that reenters a gallery resumes a slideshow left in progress too; press Auto to cancel whenever you like (and see ahead for a rare exception on Safari).
Update: as of version 2.1, the Auto button changes to be underlined as an indicator whenever the slideshow is on, and changes back to normal text when the slideshow is off. This helps make the show's state apparent, especially when it's first started or is resumed on return from another page.
Because of these limitations, the Full button and feature may be omitted on a per-gallery basis (it's enabled by default). When Full is available, it provides a per-image blowup/quick-zoom option (e.g., before and after), that may be easier than raw-image zooming via image taps. Users looking for a true fullscreen experience, however, may be better served by using browsers which support a manual fullscreen that spans multiple pages, including those in thumbspage slideshows; see the next section's fullscreen tip for pointers. Note that Full may be hidden on small displays; scroll the toolbar left as needed.
Update: like Auto, the Full button changes to be underlined as of 2.1 as an indicator that its fullscreen mode is on, and resets its font when its fullscreen is cancelled, whether by Full or outside the page (e.g., with an Escape key). Unlike Auto, though, fullscreen mode is obvious, and Full's font changes are not supported on all browsers. Moreover, even where supported, Full will not change for, and will not cancel, a fullscreen mode started independently of the page; for better or worse, user-initiated and page-initiated fullscreens differ, and browsers handicap the latter in the name of security.
Beginning with version 2.2, thumbspage viewer pages respond to swipe gestures on all devices and browsers which support them. Swipes require a touch screen (update: touchpad and mousewheel swipes are also supported as of version 3.0), but they work broadly on both smartphones and Windows PCs, and in all dozen browsers tested except Internet Explorer (subject to one up swipe limitation covered ahead).
To perform a swipe, start the gesture in the image-display area for touchscreens—that is, on the image itself—in any viewer page. Touchpad and mousewheel swipes may be performed anywhere. The physical direction of the swipe depends on system settings, as noted in the 3.0 Quick Start, but the logical direction of the swipe determines its action:
You can test-drive swipes on a touch-screen device by running any of the demos listed here. Where available, swipes are simply a convenient alternative to other page actions. All former widget and toolbar taps described above still work as they did in prior versions, as do browser long-presses, pinch/spread zooms, and back/forward swipes. Mouse clicks naturally still work on non-touch displays too.
Usage tip: some browsers implement back/forward swipes as an alternative to buttons. thumbspage left/right swipes won't clash with these as long as both are performed well. Be sure to trigger browser back/forward with a short flick from screen edges, and begin thumbspage swipes in the page's image display. If this is difficult, you can also do back/forward by swiping above or below the thumbspage image-display area, or simply use browser back/forward buttons.
As usual with UIs, first-hand experience is also a great way to learn how to use thumbspage galleries; browse the examples in the thumbspage package, and test-drive the live demos at thumbspage's host site for more on index- and viewer-page interaction. The next section provides more info on gallery views.
This section collects additional assorted tips for viewing thumbspage galleries. Content you'll find here:
Because viewer pages suffer most when JavaScript is off, they give you an alert when yours is disabled; here's one on desktop and mobile. JavaScript can be misused, but is fully harmless in code that thumbspage generates itself, and is essential for the sort of interactive-UI functionality offered by thumbspage galleries. In fact, most of today's web isn't quite usable without it—for better or worse. Please turn JavaScript on for the best thumbspage experience.
Update: as of version 2.3, JavaScript is now fully required for using the viewer pages created by thumbspage. This is normal on the web today, and was already effectively required in prior versions, because images did not scale and most widgets were inoperative. 2.3 made it official, with an enhancement that renders navigation buttons no-ops without JavaScript too, leaving no usable content. For more background, see the builder's note.
Caveats: while no browsers or devices are known to be unable to display thumbspage galleries, some browsers have relevant quirks mentioned in other notes ahead; usability is naturally subject to browser and platform changes; and viewability is prone to decline with screen size (all bets are off on your watch). That said, HTML may not be a portability utopia, but thumbspage manages to make it work.
F11 key (with fn if
needed) puts the browser in fullscreen mode, which persists for all
pages visited until explicitly disabled with another F11.
This works in Chrome, Firefox, Edge, Internet Explorer, and likely others,
and allows thumbspage Auto slideshows to run completely in fullscreen mode.
F11 key (with fn if
needed) switches browsers to and from persistent fullscreen mode, just
as it does on Windows. This works in Chromium, Firefox, and likely others,
and, as on Windows, allows thumbspage Auto slideshows to run completely
in fullscreen mode.
control+command+f.
A shift+command+f
may additionally hide the toolbar in Chrome (but not Firefox, currently),
and you can also go fullscreen by clicking the upper-left-corner
green button or using menu fullscreen icons.
For additional tips and other platforms and browsers, try a web search, or consult your browser; browsers change regularly, and new fullscreen options may crop up over time. Manual and persistent fullscreen isn't available everywhere today, but it generally beats thumbspage's one-page Full where possible. You may still find thumbspage's Full useful as a quick zoom, though, especially on browsers that lack a manual option today. With any luck, those browsers will make Full fully superfluous in the not-too-distant tomorrow.
Update: on Android, the Opera web browser recently gained an amazing fullscreen mode for landscape that works much like those in desktop browsers, and spans multiple pages. For details, see this usage note at thumbspage's host site. The Opera browser is largely the same as Chrome under the hood, and runs thumbspage galleries just as well—and arguably better with its landscape fullscreen. Yet another reason to consider parting with the herd on Android.
file:// URLs offer more options. On mobile devices, however,
offline viewing isn't always as seamless, but you'll have to move on to the next
two notes for the Android and iOS offline stories. macOS Safari users: see also the
caveat ahead for the rare use case of
browser Back returns to offline galleries.
content://
URIs.
While these may be spun as security measures, that argument has been tiredly
used for many an Android
breakage.
thumbspage galleries are known to work offline on Androids Nougat, Oreo, Pie, and 10, but its releases and devices vary too widely to give universal advice here. If your offline gallery fails, try the following work-arounds that have proved successful in some contexts:
file://url if present)
file:///sdcard/...)
/storage/emulated/0; see the
primer)
https://...)
Especially on newer Androids, also make sure the browser has permission to access your files in storage. Firefox, for example, may require this on Android 10. Try Settings/Apps and navigate to storage permissions, or similar on your device. This has grown more crucial as later Androids have moved to lock down storage to app-specific sandboxes.
If you're technically inclined, you might also try running a
web-server app
on your device and viewing your gallery on localhost or a
dedicated port number; this is wholly untested (but arguably awesome).
Caveat: the upcoming Android 11 will clamp permissions down further
(read the latest edicts
here),
but its impact on browser apps remains to be seen.
Update: for recent findings on both local-file views and running web-server apps on Android, see the off-page coverage here, which is part of an Android 11 review. In short, you can run a web server on Android, but your functionality may be limited and your disconnections many. Android 11 has also narrowed your options for local-file views in browsers, in the name of a security rationale; inoperable phones may be secure, but they're also inoperable.
Update:
the thumbspage team recently discovered another route to offline viewing on Android.
On Android 11, simply copy your content into the browser's own sandboxed folder, using
a file explorer that has permission to do so (Solid Explorer and Cx File Explorer do
at this writing). Then, use that folder's local path in a file:// URL
in the browser to view offline. For example, copy content to these locations for
Chrome and Opera (alas, this won't work for Firefox on 11, because it strips
the file://):
file:///storage/emulated/0/Android/data/com.android.chrome/your-folder-and-file-here file:///storage/emulated/0/Android/data/com.opera.browser/your-folder-and-file-hereThis works for Chrome on Android 10 too, but isn't required for Opera or Firefox on 10, where they have full access to arbitrary storage paths (unlike both Chrome on 10, and all browsers on 11). This isn't the same as arbitrary file access, of course; you're limited to files dropped into a browser's folder. This is also an arguably terrible idea: your content in the sandbox folder will be deleted if you uninstall the browser, and is prone to being nuked if the browser ever resets its own folder. Hacker beware!
Update: in late 2021, some Android file explorers now provide seemingly heroic work-arounds on Android 11 that allow you to use a browser to view web pages stored locally on your phone—including thumbspage galleries. For example, among file-explorer apps tested:
content:// URIs that implement Android's content-provider paradigm.
This scheme is not a substitute for a web server, opens some complex pages slowly, and
can break down for some nested website content (e.g., folder indexes may oddly invoke
a download that fails). But it also suffices for viewing basic content and thumbspage
galleries on your phone.
Thus, your first step when trying to view locally stored thumbspage galleries on Android 11 and later today is to simply try opening them in a file-explorer app to see if they are supported automatically. For more details on the constantly evolving struggle between Android permissions and file explorers, see also the updates here, here, and here.
Nor is this an isolated case.
As another example, the thumbspage team recently found and reported a
settings-related bug in 2020's Android Firefox—though not
thumbspage specific, this browser sometimes leaves an odd blank
strip at the bottom of thumbspage viewer pages if you enable its
"Scroll to hide toolbar" option (more details
here).
Thumbspage's host site also reported a bug in version 53
of Android Opera—though it does not impact thumbspage galleries (and was
fixed in version 60), this browser strangely truncated the remainder of a page at a
/* character sequence in text formatted with <pre>.
At the end of the day, thumbspage is completely dependent on browsers which change frequently and arbitrarily, and have an unfortunate history of fragility (indeed, at times it seems a website could be laid low by a good sneeze). For best results, clear settings that cause issues on Android, use similarly obscure browser behavioral switches with care, and try other browsers as a last resort when browser bugs—and enhancements—break your viewing experience.
For more tips on using thumbspage galleries, viewers are also encouraged to browse the rest of this document; although it's focused on gallery builds from here on, you can also find usage details along the way.
This section is meant for gallery creators, who run thumbspage to build new galleries. It describes thumbspage install requirements, inputs and results, customization options, and other operational details. It's also a comprehensive tutorial that doesn't assume you are already a command-line wizard—which means more advanced readers may want to skim parts useful to others. If you're looking for info on how to use galleries, try the viewers' section first.
Examples: if you enjoy learning by example, you can also study the thumbspage demo sites online here and here for sparse but fast tutorials. These sites list their run logs, and use custom headers and settings which you don't need to code if the defaults work for your galleries.
This section covers the basic logistics of using the thumbspage program to build galleries. The pages of the galleries it builds work on all browsers and platforms and require no extra installs or infrastructure, as covered earlier.
thumbspage itself is a Python program that runs on all major platforms, and is provided in source-code form which you run with your local Python. To install the program, download its zipfile from the Download section of the following web page and unzip it on your computer:
learning-python.com/thumbspage.htmlThe thumbspage program also requires installs of Python 3.X (any X) to run its source code, plus the third-party Pillow (a.k.a. PIL) image library to extend the installed Python 3.X with image-processing tools. If they're not already present, fetch and install both these items from the following sites, respectively (or search the web for other links):
www.python.org/downloads/ pypi.python.org/pypi/Pillow
thumbspage can be run to build galleries on any platform that runs Python 3.X and Pillow, and has the required folder and file access permissions. For example, this program has been verified to run on Windows, macOS, Linux, and Android. The latter has unique requirements and permission rules; see the notebox below for usage on Android, as well as the similarly constrained iOS. For a related Pillow install pointer, see also this page.
As discussed ahead, as of version 1.7 thumbspage also uses the pure-Python and third-party piexif library to update image Exif tags, but this library's code is included and shipped with thumbspage itself on all platforms, and does not require a separate install.
A note for programmers: Pillow is used from Python for thumbnail generation,
image rotation, and some Exif-tag processing—which all occur at gallery-build
(i.e., program-run) time. Images are scaled at image-display time instead by
JavaScript code in generated viewer pages—which mix HTML, CSS, and
JavaScript in a tangled and browser-specific morass that is the norm
for web development today. The stew manages to work well anyhow.
thumbspage galleries can be both viewed and built on mobile devices.
This guide often focuses on the mobile portability of generated pages viewed, but
it's also possible to run the program itself on your Android smartphone or
tablet from a Python-aware app.
For instance, thumbspage galleries can be built in the
Termux app, after running both
of the following commands (more details via
search or
here,
though the
After this, thumbspage command lines work in Termux the same as elsewhere.
You can also launch thumbspage command lines on Android in
Pydroid 3,
after running the same
Once you've installed thumbspage and its required tools per the preceding
section, you're ready to start
turning your image folders into galleries.
This section demonstrates how to run thumbspage on your computer.
It also goes over command-line basics for users new to the technique.
For a basic launch of thumbspage, run script
thumbspage's main options are selected with five console replies, or their enter-key defaults,
on each run. The following example session gives user inputs in bold font. In its
prompts, inputs are described in
This section documents the input replies in the preceding usage example, numbering
them from the first
Special cases: a solitary
For reply #3, give the number of thumbs you want to display in each
row on the index page. The thumbs table automatically expands and shrinks
with the page, and scrolls both horizontally and vertically
where needed. Note that this input is not requested if you opt to
use 2.1's new dynamic index-page layout alternative,
because this layout determines the number of columns automatically from
page size.
Exception: as of version 2.3, thumb sizes provided as configs by file or
argument can now give a single integer instead of a tuple, if both sizes
are the same. Sizes input at the console, however, must still be 2-tuples
as described here. See 2.3's update for details.
If you change your mind or make a mistake while inputting replies:
you can cancel a run by typing a break or EOF key sequence (e.g., hold
Caution: using precoded console inputs via stream redirection or "here"
documents as described in this section is now discouraged because inputs
may change—and did in 3.0, which made dynamic index layout the preset
default, reducing the number of inputs by one. To avoid build-script changes in
the future, instead pass input options as
Besides the basic console interaction of the prior section, thumbspage also
allows you to pass in the folder name as a sole command-line argument instead
of a prompt reply. This allows you to use shell auto-completion on long folder
names, though it's probably more useful in a console window than an IDE.
Folder argument or not, you can also automate a launch by using command-line
In the last of these modes, parameters in the input file
Naturally, you can combine all these with shell syntax for pipes and output
redirection (
Finally, on Unix systems—and Windows systems that have Unix subsystems or
similar tools—you can also provide console inputs immediately
following a command line, by using "here documents" of the sort available in
Bash and other Unix shells. Using this in a script file allows you to code
canned input parameters in the script itself, without having to juggle a
separate file. The following demos the idea,
but see your shell's docs for more details if needed; in short, it assumes
Fine print: use just
You can catch the last of these ideas in action in the shell and Python scripts
here,
here, and
here, used to
automatically generate thumbspage's example galleries.
thumbspage's full set of build scripts here may
also provide pointers for more advanced automated builds, including
automatic zips and uploads for external thumbspage clients.
Although thumbspage's basic console interaction covered
above
should suffice for many use cases, automating its launches
is straightforward, and may be necessary when thumbspage is used as
a nested tool in a larger build system.
For more background on the shell techniques shown here, try the off-site overviews of
streams,
redirection,
variables, and
here docs.
For more thumbspage usage examples, browse its
Update: thumbspage 1.7 added the optional
folder-name command-line argument. To better reflect
this, 1.7 also moved folder name to be the first prompt when not provided
on the command line; this invalidates some older session logs where folder
name was asked later, but the difference is trivial.
2.0 added nicer input-error reporting,
replacing exception tracebacks. 2.1 omits the thumbs-per-row input
when dynamic layout is chosen, because
the input is moot in this mode, and omits all inputs but the first as
irrelevant for imageless folders.
Update: thumbspage 2.2 added optional
command-line config arguments, of the form
For full coverage of this feature, see the 2.2 release note.
Update: thumbspage 2.3 added new config settings
that can be used to override console inputs. When provided, in the config
file or command-line arguments, input values are taken from the settings, and no input
is requested at the console's stdin. For example, a command line of the following form
overrides two console inputs with arguments:
This provides are portable and uniform alternative
to the shell redirect and here-document techniques described in this section.
For more details, see the 2.3 release note and its command
examples.
As noted above, 2.3 also allows thumbs maximum size to be provided as a single
integer instead of a tuple, when given by configs; see 2.3's note.
Because thumbspage is run from a command line, you need to know the basics
of folder pathnames in the console realm. Luckily, this is much simpler than
it may sound; as noted, the pathname you input at
prompt #1 can be either:
For instance, when running thumbspage via command lines,
you can
Absolute paths are generally required when running thumbspage from an IDE such
as PyEdit, if they run
code in the program's folder. Also see your file explorer's options for copy/paste
of a pathname to which you've navigated; it can often avoid having to type a long
pathname at thumbspage prompts.
As you might expect, the
If you'd like more background on command-line use, you'll find both online and
brick-and-mortar resources that go into more detail. Here, the next section
moves on to show you how to make your galleries more unique,
after a brief technical sidebar.
For console prompt #4, thumbnails sizes are
input as a pair of numeric pixel dimensions,
Without getting into code, here are a few examples of how this works; thumbnail
sizes input on the left of
You can see more results and experiment with this on your own using
this script.
In short, input dimensions you provide are essentially maximums:
they define an area in which to scale thumbs; they are only ever
decreased to match original images; and one may be adjusted down to keep
the aspect ratio the same as the original and avoid distorting the image.
The most common thumbspage customization options are available as console inputs
on each run, as described in the preceding section.
This section covers additional customization options enabled by file edits.
A set of additional customizations are available as Python settings in file
Updates: in addition to the configs file,
thumbspage 2.2 supports config command-line arguments, of the
form
For more custom behavior, add unique HTML code to the top and bottom
of the index page by placing it in files named
Subtlety: galleries which both use a custom footer and enable a floating Top
button for the index page may also need to allow for extra end-of-page
blank space in the footer's code to prevent the button from covering final
non-fixed content; see the version 2.0 note ahead.
The generated thumbnail index table's code is self-contained, and requires
no support code in a custom header.
Conversely, a custom
For an example of this technique in action, see the
online demo site
here.
Beginning with 2.0, it's also possible to code scripts that replace an HTML
comment automatically added to the
As of version 1.6, viewer pages can also be changed arbitrarily by editing
the template file
Starting in 2.0, you can also customize viewer pages by
programmatically replacing the automatic
As of version 2.0, you can also customize the optional floating
Top button of index pages, by editing the new source-code file
As of version 2.3, you can optionally provide plain-text note files for
any or all of your image files, to provide descriptions or narration
for the images in your gallery. These notes are displayed as a
popup in
viewer pages when users tap the tollbar Note
button,
or up swipe on the image on touch
displays.
When present, note files appear alongside images in the images folder,
and are named with a
This feature may be disabled, and Note buttons and their up swipe
appears only if this is enabled and at least on note file
is present in the images folder. For a demo of notes in action,
see this
gallery.
For more details on notes, see the 2.3 release note.
Related: if you use notes, you may also be interested in 2.3's
thumbs-only index pages.
To tie together the ideas covered so far, the following sketches the
structure of an images folder processed by thumbspage, with generated
parts in bold font and default names and behavior applied:
Open the generated
You can view raw examples of generated index and viewer pages and
Updates: in addition to the files and options
covered in this section, version 3.0 adds a new program-folder
template file for dark mode,
This section collects assorted pointers for thumbspage gallery builders.
Though arguably random, it covers some of the most common issues
and border cases that may arise when using the program. Notes you'll
find here (be sure to also browse Version History
for tips omitted in this section):
Update: as of version 1.7, viewer pages are
even more functional—with info-dialog popups on filename taps, and
easier Raw-display access via image clicks—and repair some former
large-font issues (see the release notes).
These pages are now broadly recommended.
Update: as of version 2.0, "Raw" button taps are now
fully replaced by image taps, and new "Auto" and "Full" buttons provide slideshows
and one-page fullscreen, respectively; see 2.0's release notes,
and use viewer pages.
Also note that because filenames used on labels are not line-wrapped, their
width largely determines column spacing on the index page. As a rule of
thumb (pun intended...), use shorter filenames for narrower columns.
Update: on a related point, version 2.0 now wraps or
scrolls absurdly long file and folder names; see the release note.
-y suggested at the latter isn't recommended—it skips asking if
you wish to proceed):
pkg install python ndk-sysroot clang make libjpeg-turbo
pip install Pillow
pip command in its Terminal or using its Pip GUI, and
other Python apps may provide additional options. To sample the flavor of thumbspage
builds in Termux, check out the Android demos
here,
here, and
here, plus the console log
here.
Running thumbspage
Usage Example
thumbspage.py
from a command line with no command-line arguments.
It can be run from a console (e.g., Terminal on macOS
and Linux, Command Prompt on Windows, and whatever qualifies as
a command shell in Android apps); and after opening its file in most Python IDEs
(e.g., PyEdit and
IDLE).
[], and defaults for empty replies are
given in () (Windows users: be sure to use py -3 at the start
of your command line, \ instead of / in your pathnames,
and a C: or other drive letter if needed):
/.../content$ python3 /MY-STUFF/Code/thumbspage/thumbspage.py
Images folder path [. or dir] (enter=.)? trnpix
Clean thumbs folder [y or n] (enter=y)? y
Thumbs per row [int] (enter=4)?
Thumb max size [x, y] (enter=(100, 100))?
Use image-viewer pages [y or n] (enter=y)? y
Running
Cleaning: trnpix/_thumbspage/1996 First Pybook.png
Cleaning: trnpix/_thumbspage/1996 First Pybook.png.html
...
Skipping: .DS_Store
Making thumbnail: trnpix/_thumbspage/1996 First Pybook.png
Making thumbnail: trnpix/_thumbspage/1998 Puertorico 1.jpg
...
Skipping: _cut
Skipping: _HOW.txt
...
Generating thumbnails index page
Generating view page for: 1996-first-pybook.png
Generating view page for: 1998-puertorico-1.jpg
...
Finished: see the results in the images folder, "trnpix".
Prompts and Replies
? prompt to the last. As we'll see in the
next section, the first of these can now
be provided with a command-line argument instead; this bumps the others up
in the list, but the options work the same either way. Here are the
parameters you'll input to run thumbspage:
folder means that
folder in the directory where the script is being run, and
/folder/folder and
C:\folder\folder
denote absolute paths to your image folder on Unix and Windows, respectively.
. here means the directory where the script
is being run, which is also the default for an empty reply (i.e., pressing your enter
key only). You can also use other path syntax such as two dots for one level up
(e.g., ../folder is a sibling); see the pathname primer
ahead if you're new to such things.
Tip: if you name a folder which has no images,
you'll make an index page with a subfolder list.
100,100 makes thumbs 100x100 pixels large, but either side may
be rendered less than 100 large if needed to avoid distortion. There's more on
what that actually means in the sidebar at the end of this
section.
control and type a c or d) at any prompt,
and thumbspage reports input errors nicely as demonstrated in this
console log.
For more examples of console runs on various platforms, see the logs
folder.
Other Usage Modes
setting=value
command-line arguments, along with other per-build configs.
See the updates ahead and the full coverage
here and
here.
< syntax to provide canned input parameters in a text file,
one per line (technically, by redirecting the stdin
stream).
These options yield at least three ways to start the program:
$ python3 thumbspage.py
Images folder path [. or dir] (enter=.)? trnpix
...4 other parameters prompted from input...
$ python3 thumbspage.py trnpix
...4 other parameters prompted from input...
$ python3 thumbspage.py < inputs.txt
inputs.txt
would like look the following; use an empty line to accept a prompt's default,
and omit the first line if you provide the folder name as an argument in the
command line instead:
trnpix
y
4
y
| and > file).
For example, the following Unix session both sends input parameters to the
script from one file, and saves its output to another; it also
assumes shell variable $C has been set to name the folder where
you unzip programs like thumbspage, and opts for 128-pixel thumbnails, 3 per row:
$ cat inputs.txt
y
3
128, 128
y
$ python3 $C/thumbspage/thumbspage.py trnpix < inputs.txt > report.txt
$ more report.txt
...output here...
$C is your install folder again, and provides canned inputs as tabbed
lines between EOF markers:
$ cat generate.sh
#!/bin/bash
python3 $C/thumbspage/thumbspage.py trnpix <<-EOF
2
128, 128
EOF
$ bash generate.sh # or just "generate.sh" if it's made executable via chmod
...output here...
<<EOF and omit tabs if your shell
requires it, and don't expect a 2> /dev/null to suppress
input prompts here. The latter won't work, because Python's input()
function prompts to stdout (well, often; this is inconsistent,
and an open bug).
The tagpix program supports
prompt drops this way, but only because it uses a custom input() that
prompts to stderr. Such redirects are dodgy in any event;
messages for uncaught errors, including Python exceptions,
may also be lost in the bargain.
examples folder.
The console input prompts and arguments we've met in this section are
really just the first level of options in thumbspage.
The sections Customization
and Building Tips that follow
cover additional configuration options and usage details.
First, the next section explores more basics for users new to running
programs from command lines.
setting=value.
When used, these arguments are coded in the command line after the optional folder
path, and override same-named settings in the configs file.
With this extension, thumbspage command lines now take the following general form:
python3 thumbspage.py imagefolder? setting=value setting=value...
python3 thumbspage.py imagefolder inputCleanThumbsFolder=True inputThumbsPerRow=4
A Brief Primer on Pathnames
photos for an item in the folder you're working in;
. for the current folder itself; .. for one level up;
and ../photos for a filesystem sibling
/Users/you/photos
on Unix; C:\Users\you\photos on Windows; and
/sdcard/photos on Android
cd (change directory) to the folder
containing your source image folder,
and give a folder path relative to where you are working:
$ cd /MY-STUFF/camerauploads
$ python3 /Code/thumbspage/thumbspage.py
Images folder path [. or dir] (enter=.)? imagefolderhere
Or, run the program anywhere and give an absolute path to your
images folder:
$ python3 /Code/thumbspage/thumbspage.py
Images folder path [. or dir] (enter=.)? /MY-STUFF/camerauploads/imagefolderhere
thumbspage.py script's path in console command lines
can be relative or absolute too, depending on your console's current directory. For instance,
py -3 thumbspage.py suffices to start the program on Windows if run in
the thumbspage install folder, though your images folder will reside elsewhere—and
may be relative or absolute:
> cd thumbspage-install-folder
> py -3 thumbspage.py
Images folder path [. or dir] (enter=.)? C:\MY-STUFF\camerauploads\imagefolderhere
(width, height),
where parentheses and blank spaces are optional.
The underlying Pillow imaging library
always adjusts your inputs as needed to preserve the original image's aspect ratio,
instead of warping images.
=>
are automatically changed to sizes used on the right:
For an original image of size 100w x 50h (wider):
(300, 100) => (200, 100)
(100, 300) => (100, 50)
(50, 50) => (50, 25)
(100, 100) => (100, 50)
(300, 300) => (300, 150)
For an original image of size 50w x 100h (higher):
(300, 100) => (50, 100)
(100, 300) => (100, 200)
(50, 50) => (25, 50)
(100, 100) => (50, 100)
(300, 300) => (150, 300)
For an original image of size 100w x 100h (square):
(300, 100) => (100, 100)
(100, 300) => (100, 100)
(50, 50) => (50, 50)
(100, 100) => (100, 100)
(300, 300) => (300, 300)
Customization
User Configurations File
user_configs.py.
See that file for its options, documentation on their roles, and
their preset values.
As examples, that file defines Unicode encodings; gives the names of the
generated index page and thumbs folder; turns subfolder-link lists on
or off; as of 1.5, configures most colors; and as of 1.6, allows images
to expand beyond actual sizes, and users to control auto-rotation of
images. Versions 1.7 and
later
add numerous options you'll generally find later in the configs file.
setting=value.
When used, these arguments override same-named settings in the configs
file, and provide an alternative and simpler way to customize settings
that may vary per gallery build.
For more on this feature, see the 2.2 release note.
Header and Footer Insert Files
HEADER.html
and FOOTER.html, respectively, and storing these files
in the images folder alongside your images.
You can use one, both, or neither of these files; if not present, generic
HTML and text is automatically generated in the index page around the
thumbs table. For details on how to code these files, see the demos in
folder examples/ here. In brief:
HEADER.html
<!doctype>,
<html>, and the <head> section with all the usual
components if used by your index page—<meta> tags for mobile viewport
and content-type Unicode encoding, <style>, <title>,
<script>, and so on.
This preamble should be followed by the start of the <body> section
with any informational <p> paragraphs or other content.
<body> margins
(e.g., to appease curved mobile displays), as in
this demo's
source code; default headers do not, because there isn't any substantial text at page top.
<meta>
tag should generally be the same as the outputEncoding setting in the
user configurations file, because the latter is used when
saving the whole index page, including its generated thumbnails table. See version 1.3
release notes ahead. The UTF-8 default is recommended in all contexts.
FOOTER.html
</body> and </html>.
For example, footer content might include navigation-toolbar
links,
or informational text;
see both links for examples.
More Header Options
HEADER.html file can use CSS style code to
alter the thumbs table in ways not supported by basic user settings (e.g.,
to tailor index-table font). The way you'll do this depends on the
index-page layout model chosen:
<td> element for the entire index page, using
CSS code like this in a custom header file's <head>:
<style> td { font-weight: bold; } <style>
<div>,
with CSS code of this sort in a header file:
<style> #thumbslinks { font-style: italic; } <style>
<style> body { font-family: Arial; } <style>
<head> of default index headers
and precoded in viewer pages for this purpose. See this note
ahead for more details, as well as this script
for an example that leverages this hook to insert analytics code in generated index
pages prior to uploads.
More generally, this lets programmers add arbitrarily custom code to default index-page
headers, and may avoid custom headers in some use cases.
Viewer-Page Template File
template-viewpage.html
in this program's install folder
(use "view source" in your browser to see its code).
For example, such edits might add site icons, analytics code,
or navigation widgets specific to your usage or site.
Edit with care (this file's code is fragile!) and rerun thumbspage
to use your customized template.
<head> comments noted in
the prior section and described here. Though this requires some
programming skills, it is probably a
safer option than changing the viewer template in place, especially if you
ever upgrade to a new release (your edits won't be overwritten by an unzip).
Floating-Top Template File
template-floatingtop.html,
which host the button's implementation code. This isn't normally
necessary, because nearly every property of the Top button can be
customized with settings in the configs file, per the 2.0
change note.
Image Note Files
.note extension following the
corresponding image file's name. For instance the note for an image
file photo1.jpg should be named photo1.jpg.note.
Note files may contain any Unicode text, including emojis, though HTML
code is shown verbatim (links won't work). Lines are collapsed into
paragraphs, with the exception that a blank line coded as two adjacent
line breaks (i.e., \n\n) is taken to be a paragraph
separator, and renders as a blank line in the popup.
Summary: thumbspage Folders
Your image source folder/
Your image files...
Optional image.note files...
Optional HEADER.html
Optional FOOTER.html
index.html
_thumbspage/
Thumbnail-image files...
Viewer-page files...
index.html file to view the thumbspage gallery,
and package the entire images source folder to distribute. Exceptions:
HEADER.html, FOOTER.html, and image
.note files, if used, are required at gallery build time only,
and need not be present when a gallery is viewed. This follows from the fact
that header and footer contents are embedded in generated index pages,
and image notes are embedded in generated viewer pages. Shipping these
files to content consumers is optional.
_thumbspage/ folders online
here,
here, and
here,
and their live renditions here.
In addition to the images-folder content sketched above, some files in the thumbspage
install (unzipped) folder are available for user customizations:
thumbspage install folder/
Implementation files...
user_configs.py
template-viewpage.html
template-floatingtop.html
Edit user_configs.py and the HTML template files
as you like for your galleries. Not shown above, your image folders may also
contain subfolders that might show up in bullet lists on the index page;
but to explore special cases like this we have to move on to the next section.
template-autothemes.html, along with the
optional image-folder config files ORDER.txt, NOTES.py,
and CAPTIONS.py, which give
image ordering, notes, and labels, respectively. For more detail, see
the 3.0 Quick Start and
release notes as well as docs in
the user_configs.py file.
Building Tips
"), especially if they are to be
viewed on multiple devices. By contrast, galleries uploaded to a web server need
satisfy only their server's filename rules.
That said, thumbspage galleries can display only image types supported by both the Pillow library used to build their thumbnails, and the web browsers used to view their pages. While Pillow happily creates thumbnails for nearly every image type under the sun (with some exceptions: see the HEIC update ahead), web browsers are much more limited.
TIFFs, for example, yield correct thumbnails and display well in Safari, Edge, and Internet Explorer, but cannot be displayed by Chrome or Firefox. The upstart WebP format similarly is supported by Pillow (and hence by thumbspage builds); but support is an add-on in some versions of Edge and still growing in Safari (and hence in thumbspage views). See this shot for current results in Chrome (top left), Firefox, and Safari (right).
Because of these constraints, the support story today reads as follows:
Some browsers may ask to auto-open some exotic image types in another program, but this isn't the same as in-page support. If your TIFFs (or other) images don't display in a browser you use, your best recourse is to convert them to a more widely supported format for use in thumbspage, such as PNG or JPEG. A "Save as" in your local image editor will generally suffice. For a demo of common supported image types, see examples/mixedtypes. For more on browser image support, try this page or this search.
Also note that the above pertains only to image display. Support for image metadata—of the Exif-tag sort displayed by info popups—varies by image type too. JPEGs are generally tag rich, for example, but PNGs, TIFFs, and WebPs may be more spotty, and image libraries may not recognize newer formats. thumbspage collects metadata where possible, and omits it elsewhere.
One browser-specific caution: a somewhat dated Safari (2015's version 9) on macOS has been seen to crash altogether when trying to display a PBM in the mixed-types demo pages, for unknown reasons that are well beyond the scope of the thumbspage project. Safari updates, image conversions, and other browsers are the suggested remedies.
Update:
in 2021, support for Apple's HEIF/HEIC image format common on iPhones is still not present
in either stock Pillow or Python's mimetypes module (the latter means it won't
appear in galleries at all), but it might be usable in thumbspage with a third-party library and
programming solutions.
Barring such extensions, your best bets may be to convert these images to JPEGs,
or change your Camera or Photos settings to save or transfer in JPEG format, respectively.
Try searches
here and
here for pointers.
Update: beginning in 2.3, files in the images folder
with a .note extension are special, and provide image notes displayed in the UI
when present; see the 2.3 coverage. Technically, header
and footer files are similarly special.
Exception: subfolders named with a leading _ or .
character are not included in the bullet list; the former is considered developer
private per Python convention, and the latter is hidden per Unix convention.
See version 1.1's note ahead for more subfolders lists in general;
version 1.7's update to skip .* subfolders too;
and version 2.1's customizable space between subfolder-list items.
.../folder and .../folder/
work only when a web server is present. Use the more complete and explicit form
...folder/index.html to also (or only) view results offline.
To link to individual images, use either their image-file or viewer-page URLs;
the latter gives access to the gallery and its formatting. In sum:
...folder/index.html # the index page ...folder/image.jpg # an image itself ...folder/_thumbspage/image.jpg.html # an image's viewer page
Because rotation changes the source
image file in-place for browser inline display, the original image
is by default first saved with a .original filename
extension in the source folder as a backup copy. See
user_configs.py for
settings that allow users to disable this feature and/or its backups;
the included simple
utility script
that restores all originals from backups;
and 1.6 release notes and later updates to them in
Version History ahead for more background
(version 2.1, for example, adds deletion of embedded thumbnails on rotations).
Conversely, folder cleaning is not required if images are only added to the images folder—thumbnails will be made for new images only, and thumbs for previously added images will be retained. This can save substantial time when extending large image folders. But when in doubt, clean; this script's work is done once, before any views.
_thumbspage by default, in
user_configs.py. It is not
named with a leading . character to make it a Unix hidden file,
because hidden files are rude (you should really see what programs do to
your computer), and may be skipped by some compression and backup
programs (e.g., see ziptools and Mergeall at
learning-python.com).
The default name can be freely changed to be hidden if .
tradeoffs are acceptable in your usage (but you didn't hear that here).
The issue: when published online, thumbspage's thumbnail-index pages load quickly, but its image-viewer pages must download images in full before scaling them to browser windows. As a consequence, some large images in thumbspage galleries may download slowly on some servers or clients. In early 2020, for example, large (e.g., 2-6M) image transfers on the business-hosting server that houses thumbspage were usually very quick (e.g., 2-3 seconds), but sporadically throttled down to an outright crawl (e.g., 20-30 seconds). It's unclear if this speed hit was due to traffic on the server itself or the broadband and cellular client networks accessing it, but similar delays may occur in other contexts. Such delays can obviously be discouraging to site visitors, and posting large images in general might even be rude to users with limited or metered bandwidth.
The remedy: if the full-size images in galleries you build with thumbspage load too slowly, your recourses include moving to a faster hosting server, and downscaling the size or quality of very large images. Of these, downscaling images may be easiest, cheapest, and politest. The Pillow library, for instance, has tools that you can leverage in a Python script to reduce image filesize by scaling down image dimensions and quality. Better yet, get the new shrinkpix program for a precoded solution that uses Pillow this way to reduce the size of one or all image files in your website. However you opt to shrink, be sure to regenerate thumbspage galleries to reflect your newly shrunk images' information displayed in info popups.
A faster, and perhaps dedicated, server may help too, but not for users on metered connections or slow client networks; for such visitors, smaller images (e.g., < 500K) may be the only fix, and even then will solve speed issues only if network throttling isn't extreme. The website hosting thumbspage has resisted downscaling its images in the past for the sake of both image quality and usage demonstration, but at this writing is in the process of shrinking images globally. Downscaled or not, if images here are still slow for you, you can always view most of this site's thumbspage demos by downloading and unzipping to your machine and viewing locally. This includes thumbspage's own examples—fetch its full package for quick off-line image views.
In a better world, online images would by now be immune to the scourges of metered access and traffic bottlenecks. In the world in which we code, profit will probably always trump societal need, and the web's mass popularity will probably always best its technological progress.
Update: per testing so far, shrinking large images with the shrinkpix program mentioned above both removes observed slowdowns, and seems to yield faster views. The primary downsides are minor and rare reductions in full-size image quality (described in shrinkpix's caveats), and potentially degraded quality for thumbnails. thumbspage 1.7 solved the latter issue by converting some images to "RGBA" color mode temporarily when making their thumbnails; this produces results as good as for unshrunk originals, and has the added benefit of improving thumbnail quality for some unshrunk GIF images too. See the 1.7 update note and shrinkpix docs for more details.
Update: with the benefit of hindsight, most of the speed issues related to images at thumbspage's site stemmed from web-host speed, not image-file size. Speed issues were finally resolved in full in Spring 2020, by moving this site from its former GoDaddy host to an AWS Lightsail VPS server. The speed increase for thumbspage galleries was staggering, and far surpassed the gain from reduced image-file size (which was so overshadowed by host sloth, that it could not be reliably measured). Still, shrinking images was important for users on metered-bandwidth clients; images at this site are all now 500K or less (and average about half that size), and that's much less to ask of casual browsers than the former 6M bandwidth bombs.
Update: for completeness, it's worth noting that you can shrink a website's images dynamically with Apache's mod_pagespeed (a.k.a. PageSpeed) module. This ambitious module attempts to optimize size of fetched images by automatically resizing and caching for future requests. Unfortunately, you have little control over this process—or the quality of the images it produces. Worse, this module also mangles page code for transmission (a rude nonstarter for sites that double as page-coding resources), and abruptly crashed this site's Apache server when applied by default by a Bitnami install stack (despite the module's experimental "Incubating" status). Your mileage may vary, but static image-size reduction seems a more deterministic—and safer—approach.