Metadata-Version: 2.4
Name: simplegals
Version: 0.1.1
Summary: A simple command-line static HTML image gallery generator with a TUI setup utility
Project-URL: Repository, https://github.com/timlnx/simpleGals
Author-email: Tim Case <tim@lnx.cx>
License: MIT
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Multimedia :: Graphics :: Presentation
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: bitmath>=2.0.0
Requires-Dist: jinja2
Requires-Dist: piexif
Requires-Dist: pillow
Requires-Dist: term-image
Requires-Dist: urwid
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Provides-Extra: docs
Requires-Dist: myst-parser; extra == 'docs'
Requires-Dist: sphinx; extra == 'docs'
Requires-Dist: sphinx-autobuild; extra == 'docs'
Requires-Dist: sphinx-rtd-theme; extra == 'docs'
Description-Content-Type: text/markdown

# 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](https://www.python.org/) >= 3.10
- [term-image](https://pypi.org/project/term-image/) for terminal image rendering
- A terminal emulator with **any** of the following:

  - support for the [Kitty graphics protocol](https://sw.kovidgoyal.net/kitty/graphics-protocol/)
  - support for the [iTerm2 inline image protocol](https://iterm2.com/documentation-images.html)
  - Unicode and direct-color (truecolor) support
- [bitmath](https://pypi.org/project/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 
