simplegals 0.1.1

A simple command-line static HTML image gallery generator with a TUI setup utility

README.md

simpleGals is trying to be a very simple command-line driven static HTML image gallery generating tool. simpleGals just like to have fun, it doesn't want you getting bogged down with all the tedious overhead associated with fancy gals, running software that has to get patched, or paying another subscription. simpleGals ain't like that.

simpleGals isn't for album management. You feed simpleGals directories of images and in return you get some simple HTML files with thumbnails.

Tech Stack

• Python >= 3.10

• term-image for terminal image rendering

• A terminal emulator with any of the following:

  • support for the Kitty graphics protocol
  • support for the iTerm2 inline image protocol
  • Unicode and direct-color (truecolor) support

• bitmath for file size printing and math

(I told you, it's simple)

Experience

The fanciest part of simpleGals is the tui setup utility. Launching sgui opens the application in the current working directory, sgui (and the batch-mode simpleGals interface) will create a directory called out and expects to find a directory called in, these directories will be created if they do not already exist. Image metadata and caching files are saved in a .meta directory.

A basic template ships with simpleGals. Your can fork this template and instruct simpleGals to use your template instead with the --template,-t <TEMPLATE_DIR> option flag, or in the setup panel of sgui.

sgui

The sgui launches with a scrollable file tree ('file panel') of discovered images in the in directory listed on the left, just the file names, about 20% of the screen up to a max width of ~=30 characters

• setting: file_panel_width
• desc: width in characters or percent of horizontal area
• types:
  • int for absolute character value (e.g., 30 = 30 characters)
  • int% for max width percent (e.g., 30% = 30% of horizontal space)
• default: 30

Move the selection cursor with with the up/down arrow keys, pausing or stopping on a file name will marquee scroll the file name if it was truncated. The ctrl+n and ctrl+p shortcuts also work for next and previous if you are in the file panel.

• setting: scroll_rate
• desc: scroll rate in chars/second
• type: float
• default: 2.0

On the right using the remainder of the visible space is the general gallery settings input panel. This panel is also where previewing and editing properties of individual images takes place.

Pressing escape at any time shifts focus to the general gallery settings where parameters like max columns/rows/per page/description information can be provided. Press escape again to go back to the selection mode.

When moving the selection cursor between images in the file panel there is a brief delay before the thumbnail is loaded the first time so you can page through several in a row without attempting to generate thumbnails of each image rapidly. Once a thumbnail is generated the delay is 0 if the last-modified metadata has not changed for the input/thumbnail files

• setting: preview_delay
• description: delay before generating image metadata thumbnail the first time
• type: int
• default: 125ms

Image thumbnails are displayed in the console using the term-image library. A preview will take up no more than 55% of the available horizontal/vertical space on the panel on the right.

Pressing tab switches cursor focus between the file panel and the main usage window.

Settings

Settings are saved in JSON format.

Gallery metadata lives in .meta/. For each source image foo.jpg, the directory contains:

• foo.jpg.json — sidecar JSON: records mtime, sha256, settings hash, and paths to generated artifacts
• foo_thumb.jpg — cached thumbnail for the sgui preview panel

Staleness is determined by mtime first (fast), sha256 second (handles touched-but-unchanged files), then a settings hash to detect config changes. Artifact existence is also verified — if a sidecar exists but the output files are gone, they are regenerated. On each build, any .meta/ entries whose source image is no longer present in in/ are pruned, along with their corresponding out/ files.

Reference Material

• base library: https://github.com/AnonymouX47/term-image
• example usage: https://github.com/AnonymouX47/termvisage