thumbspage — Turn Folders into HTML Image Galleries

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.

Contents

• 3.0 Quick Start
• Overview
• Viewing Galleries
  • Index Pages
  • Viewer Pages
  • Viewing Tips
• Building Galleries
  • Installs and Platforms
  • Running thumbspage
  • Customization
  • Building Tips
  • GUI Mode
  • Usage Caution
• Version History
  • 3.0.1: Android Chrome Fix
  • 3.0: Tags, Keys, Swipes
  • 2.3: Notes, Inputs
  • 2.2: Swipes, Configs
  • 2.1: Thumbs, Layout
  • 2.0: Auto, Top, Full
  • 1.7: Info, Exifs, Etc.
  • 1.6: Scaling, Rotation
  • 1.5: Viewer Pages
  • 1.4: Mobile
  • 1.3: Unicode
  • 1.2: Styling
  • 1.1: Subfolders
  • 1.0: The Basics
• Development Notes
• More Resources

3.0 Quick Start

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.

Viewing Galleries

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.

Index Pages

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.

Viewer Pages

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:

• Taps on the display's label, image, and toolbar buttons
• Swipe gestures on touchscreens, touchpads, and mousewheels
• Keyboard key presses, where a keyboard is available

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:

Back to index: Index tap, i key, browser back

To return to the index page, tap 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.

Navigation: Next/Prev tap, left/right swipe, n/p key

To move to the next or prior image, tap 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.

Slideshow: Auto tap, a key

To run a slideshow that advances to each next image after a preset delay, tap 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.

Fullscreen: Full tap, f key

To open the page in temporary fullscreen mode, tap 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).

Image note: Note tap, up swipe, t key

To view a note describing the image where available, tap 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.

Image info: label tap, down swipe, ? key

To view info about the image (from Exif tags, file, and display), tap the image label at top of page, perform a down swipe on the image itself, or press keyboard key ?. Close the info with the popup's bottom OK button, the keyboard Enter key, or a tap anywhere outside the info.

Raw view: image tap, . key, up swipe?

To view the image in raw mode in the host browser, tap the image itself or press the keyboard . 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.

Building Galleries

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:

• The user_configs.py file's assignments
• Command-line arguments of the form option=value
• Console inputs prompted for main options not provided otherwise

Configuration Settings

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.