LAZYGAL(1)

📦
version 0.12 · 6 versions
, in fedora 44, ubuntu stonking

✨ LAZYGAL(1) ✨

okay bestie, welcome to the manual page for lazygal, straight out of the General Commands Manual. it's a whole vibe, it's a whole tool, and by the end of this you're gonna be generating static web galleries like it's nothing. 🫶

🌸 NAME 🌸

lazygal — static web gallery generator. that's it, that's the assignment. 💅

🎀 SYNOPSIS 🎀

lazygal -h | -v | options albumdir

🦋 DESCRIPTION 🦋

This manual page explains the lazygal program, no cap. It's a static web gallery generator written in Python. 🐍✨

So here's how lazygal works, bestie, listen up. You start with an original store of files — possibly with subdirectories inside it (and those directory names serve as headings, unless you're using the album metadata feature). That whole thing is your source file hierarchy, and lowkey the most important part: lazygal will never modify it. Ever. It's sacred. 🙏 It just reads.

Then, when you launch it like this:

$ lazygal -o /var/www/MyAlbum /home/user/SourceDir

lazygal goes and analyzes the contents of the source hierarchy, and then it (re)creates the target hierarchy with all the bells and whistles defined by the templates. Only the missing parts, or the parts that aren't up to date, get generated. Efficient queen. 👑

but there IS a limitation to this mechanism, and you need to know it: updates in the source directory, in the metadata, or in the themes are detected — but changes in command line options and configuration files since the last generation are not detected. so if you change those, you gotta manually delete the files that need to be generated again. periodt. 🗑️

Also (this is so cute of it honestly): lazygal's source directory crawling will follow symbolic links on directories, so you can arrange what you want to publish in literally any way that suits you, without copying data around. the way that works is just chef's kiss. 🤌

💅 OPTIONS 💅

These programs follow the usual GNU command line syntax, with long options starting with two dashes (`-`). A summary of options is included below — but for a complete description, go check the -h switch. 📖✨

  • -v, --version — Show the program's version number and exit. quick little flex. 🎀
  • -h, --help — Show a summary of the options. your bestie when you forget what you're doing. 🫶
  • --quiet — Don't output anything except for errors. silent mode, main character energy. 🤫
  • --debug — Output everything that lazygal is doing. all the tea, every last drop. 🫖
  • -o DEST_DIR, --output-directory=DEST_DIR — the directory where web pages, slides and thumbs get written. default is the current directory. 📁
  • -t THEME, --theme=THEME — the theme name (looked up in the theme directory) or a full theme path. 👗
  • --default-style=DEFAULT_STYLE — the default style to apply to the theme. fr fr, this is actually the filename (no extension) of the CSS stylesheet of the theme that is not marked as alternate — which means it's the one that should get used as default, or as preferred by the web browser. 💄
  • --template-vars=TPL_VARS — common variables to load all templates with, e.g. --template-vars='footer=foo bar,color=baz'. For longer variable contents, it's easier to use a configuration file (see LAZYGAL-CONF). 📝
  • -f, --force-gen-pages — force a rebuild of web pages, regardless of the modification times of their dependencies. super handy when you're changing a configuration option that affects them (theme, directory flattening, etc.). 🔨
  • --clean-destination — clean the destination directory of files that should not be there. bye bye clutter. 🧹
  • --preserve=PATTERN — specify a file pattern (or name) which should be ignored during cleanup of the destination. May be specified more than once. The values you give here are in addition to the ones specified in configuration files. 🛡️
  • --exclude=PATTERN — specify a file pattern (or name) which should be ignored during processing. May be specified more than once. Values given here are, again, in addition to the ones specified in configuration files. 🚫
  • --check-all-dirs — exhaustively go through all directories, regardless of source modification time. no shortcuts, we check everything. 🔍
  • -s IMAGE_SIZE, --image-size=IMAGE_SIZE — the size of images, defined as name=xxy, ..., e.g. small=800x600,medium=1024x768. The special dimensions 0x0 use the original size. Refer to the IMAGE RESIZE DESCRIPTION section for more info on the available syntax. The number of sizes you provide defines the number of sizes that will be generated, so:
    • --image-size="medium=800x600" will only generate all images for a medium size (no small size)
    • --image-size="small=640x480,medium=800x600,large=1024x768" will generate 3 sizes for all images (small, medium, large) ✨
  • -T THUMBNAIL_SIZE, --thumbnail-size=THUMBNAIL_SIZE — the size of thumbnails, e.g. 150x113. Refer to the IMAGE RESIZE DESCRIPTION section for more on the available syntax. 🖼️
  • -q QUALITY, --quality=QUALITY — the quality of generated JPEG images. default is 85. ✨
  • -O, --original — include original photos in the output. keep the OGs around. 📸
  • --orig-base=RELATIVE_PATH — do not copy original photos into the output directory; instead link them using RELATIVE_PATH as the base for those links. (discarded without -O, so don't bother unless you've got -O on.) 🔗
  • --orig-symlink — do not copy original photos into the output directory; instead create symlinks pointing at their original locations. This is useful when you plan transferring the whole directory that was generated to some other location, perhaps with rsync, and you wish to avoid creating an extra copy of each photo. 🪞
⚠️ Caution ⚠️ This option is not available on Windows. If you try to use it on that operating system, lazygal will immediately exit with an exit status of 1. not even a little bit of wiggle room. 💀
  • --puburl=PUB_URL — the publication URL. only useful for feed generation, bestie. 📡
  • -m, --generate-metadata — generate metadata description files where they don't exist in the source tree, instead of generating the web gallery. This disables all other options. so choose wisely. 🧠
  • -n THUMBS_PER_PAGE, --thumbs-per-page=THUMBS_PER_PAGE — maximum number of thumbs per index page. This enables index pagination (0 is unlimited). 📄📄📄
  • --filter-by-tag=TAG — if set, lazygal will only export the pictures that have one of their (IPTC) tags matching TAG. You can also use an equivalent of AND and OR boolean tests to filter tags. For more details, read the TAG FILTERING section below. 🏷️
  • --pic-sort-by=ORDER — sort order for images in a subgallery, among 'mtime', 'filename', 'numeric', or 'exif'. (default is 'exif', which is by EXIF date if EXIF data is available, filename otherwise — and it sorts EXIF-less images before.) 'numeric' does a numeric sort on the numeric part of the filename. Add ':reverse' to reverse the sort order (e.g. --pic-sort-by=mtime:reverse). 🔀
  • --subgal-sort-by=ORDER — sort order for subgalleries, among 'exif' (the EXIF date of the latest picture in the sub-gallery), 'mtime', 'dirname', or 'numeric' (default is 'dirname'). 'numeric' does a numeric sort on the numeric part of the dirname. Add ':reverse' to reverse the sort order (e.g. --subgal-sort-by=dirname:reverse). 🔄
  • --dir-flattening-depth=LEVEL — the level below which the directory tree is flattened. Default is no flattening ('No'). 🗂️

This option makes the program include the web gallery index of child galleries in their parent's gallery index, if their level is greater than the supplied LEVEL. The level of the album root is 0.

Index pages with multiple galleries (which happens when this section is used) show the pictures links in gallery sections.

The following examples show the produced indexes for a sample album (2 sub-galleries, 1 sub-sub-gallery, 1 picture in each one of those). 👇

Example 1. –dir-flattening-depth=No (default)

index.html <- sub-gallery links
subgal1/index.html <- index with img1
subgal1/img1.html
subgal1/subsubgal1/index.html <- index with img2
subgal1/subsubgal1/img2.html
subgal2/index.html <- index with img3
subgal2/img3.html

Example 2. –dir-flattening-depth=0

index.html <- contains index for all pics
subgal1/img1.html
subgal1/subsubgal1/img2.html
subgal2/img3.html

Example 3. –dir-flattening-depth=1

index.html <- contains index for all pics
subgal1/index.html <- index with img1 and img2
subgal1/img1.html
subgal1/subsubgal1/img2.html
subgal2/index.html <- index with img3
subgal2/img3.html
  • -z, --make-dir-zip — make a zip archive of original pictures for each directory. 🗜️
  • --webalbum-pic-bg=WEBALBUMPIC_BG — the webalbum picture background color. Default is transparent, and that implies the PNG format. Any other value, e.g. red, white, blue, uses JPEG. 🎨
  • --webalbum-pic-type=WEBALBUMPIC_TYPE — what type of web album thumbnails to generate. By default, lazygal generates the well-loved "messy" thumbnails, with randomly selected pictures from the album each rotated by a random amount and pasted together. This default can also be forced by specifying 'messy' as WEBALBUMPIC_TYPE. 🌪️

On the other hand, specifying 'tidy' as the value of this option forces lazygal to skip the rotations, resulting in more regularly shaped thumbnails which can also be more densely packed. This can be an advantage if not all users of your albums have huge screens :-) ✨

  • --keep-gps-data — do not remove GPS data from EXIF tags. By default the location tags are removed for privacy reasons. However, there are situations when having the location data makes sense and is desired — this is mostly meant to be used with holiday photos. 🌍
  • --no-video — do not process videos, nor include them in indexes. 🎥🚫

🌸 THEMES 🌸

Okay bestie, a theme maps to a directory, and that directory has to contain these things:

  • theme/SHARED_* — these are the files that get dropped into the web gallery directory shared ✨ like CSS, Javascript, images, or literally any other resource that every single gallery needs to share. Common-good energy fr fr.
  • theme/browse.thtml — the XHTML template for the theme's browse page (the one that shows one picture 🖼️).
  • theme/dirindex.thtml or theme/dynindex.thtml — the XHTML template for the directory index page (that's the one with the pictures and the sub-galleries links).

Now, which index file you've got decides the whole vibe of your theme:

  • dirindex.thtml: fully static — one HTML page per picture, per size, plus one index per size. That's a LOT of pages, and she's earning every one 💅
  • dynindex.thtml: dynamic — only one index per directory is to be generated. Efficient queen 👑

Every theme/*.thtml has to be valid XML, no cap. Peep http://genshi.edgewall.org/wiki/Documentation/xml-templates.html for the syntax, iykyk. Dependencies for statically included templates (i.e. ones with filenames not computed from variables) get computed automatically: the moment an included template gets modified, the software will automatically figure out which pages to re-generate. Iconic behaviour honestly. And if a template file is missing? It gets searched for in the default theme. No stress 🌈

The theme/SHARED_* files — those common resources for the directory shared — get renamed to strip the SHARED_ prefix, and then:

And here's the slay part: using the theme manifest, that's the theme/manifest.json file, you can include files from other directories to be copied into the web album's shared files. Behold:

{
    "shared": [
        # copy as shared/lib.js
        { "path": "../lib-2.1.js", "dest": "lib.js" },

        # copy as shared/js/lib-2.1.js
        { "path": "../lib-2.1.js", "dest": "js/" }

        # copy first found as shared/lib.js
        # instruct ./setup.py dl_assets to download it from url otherwise
        { "path": [ "/usr/share/javascript/lib-2.1.js", "lib.js"],
          "dest": "lib.js",
          "url": "https://lib.com/lib-latest.js"
        },

        # copy prefixed files in shared/
        { "path": "SHARED_*" },
    ]
}

Please go refer to the examples supplied in /usr/share/lazygal/themes, they'll explain it better than I ever could 💖

🎀 ALBUM METADATA 🎀

If a directory from the source album contains a file named album_description, it gets processed as a source of album metadata. The format is borrowed from another album generating tool — Matew. Each line is treated as one possible tag, and unknown lines are simply ignored, bestie. Example content of this file follows:

Album name "My album"
Album description "Description, which can be very long."
Album image identifier relative/path/to/image.jpg

Otherwise (or if that's not your thing), the user can provide metadata in these files:

  • SOURCE_DIR/album-name — the title to use for this album directory.
  • SOURCE_DIR/album-description — the description for this album directory. HTML tags are used verbatim from this file 👀
  • SOURCE_DIR/album-picture — the relative path to the image to use at the top of the album picture stack 🥞
  • SOURCE_DIR/PICTURE_FILENAME.comment — the description to use for this particular image. Please note that HTML tags are taken as provided in this file for output in the templates. Yeah, same deal as above.

Lazygal also extracts information from many metadata tags in image files. And regarding image description specifically, Lazygal searches for comments in this order:

  1. pic.jpeg.comment file
  2. Exif.Photo.UserComment
  3. Exif.Image.ImageDescription
  4. Iptc.Application2.ObjectName
  5. JPEG comment

📁 FILES 📁

  • ~/.lazygal — user configuration directory.
  • ~/.lazygal/themes — user themes directory.

🗂️ CONFIGURATION FILES 🗂️

Multiple configuration files are processed by DHPACKAGE. The configuration is initially set up with the defaults, and those defaults can be found in the DHPACKAGE source distribution in lazygal/defaults.json.

Then the configuration files are processed in the following order, with each newly defined value overloading the formerly defined values. Stacking, babe ✨

Finally, any command-line-provided parameter takes precedence over any configuration file value. CLI always wins, periodt.

  • ~/.lazygal/config — user configuration file. See LAZYGAL-CONF for format.
  • SOURCE_DIR/.lazygal — album root configuration file. See LAZYGAL-CONF for format.
  • SOURCE_DIR/gal/.lazygal — web gallery configuration file. Only the webgal and template-vars sections are red in these files. The configuration applies to the gallery representing the directory of the configuration file, and all of its sub-directories, unless another configuration file in a sub-directory overloads some of the defined configuration values. See LAZYGAL-CONF for format.

📐 SIZE DESCRIPTION 📐

The size string follows the same syntax as ImageMagick's. Here's the whole roster:

  • scale% — height and width both scaled by specified percentage.
  • xscale%yscale% — height and width individually scaled by specified percentages.
  • width — width given, height automatically selected to preserve aspect ratio.
  • xheight — height given, width automatically selected to preserve aspect ratio.
  • widthxheight — maximum values of height and width given, aspect ratio preserved.
  • widthxheight^ — minimum values of width and height given, aspect ratio preserved.
  • widthxheight! — width and height emphatically given, original aspect ratio ignored. She said what she said 💅
  • widthxheight> — change as per the supplied dimensions but only if an image dimension exceeds a specified dimension.
  • widthxheight< — change dimensions only if both image dimensions exceed specified dimensions.
  • pixels@ — resize image to have specified area in pixels. Aspect ratio is preserved.

🔍 TAG FILTERING 🔍

Tag filtering supports regular expression matching thanks to the 're' module of Python. All the filter matchings can be indicated to lazygal by successive uses of the 'filter-by-tag' option, or by giving a coma-separated list of keywords.

We illustrate here how more elaorated tag filtering can be done. Let's get into it 🫶

We want to export only the images that have the tags 'lazygal' AND 'hiking'.

$ lazygal --filter-by-tag=lazygal --filter-by-tag=hiking

or:

$ lazygal --filter-by-tag=lazygal,hiking

We want to export the images that have the tags 'lazygal' OR 'hiking'.

$ lazygal --filter-by-tag="(lazygal|hiking)"

We want to export the images that have one of the tags 'hiking_2012', 'hiking_2013', 'hiking_France', etc.

$ lazygal --filter-by-tag="hiking_.*"

We want to export the images that have the tag 'lazygal', AND one of the tags 'hiking_2012', 'hiking_2013', 'hiking_France', etc.

$ lazygal --filter-by-tag="lazygal,hiking_.*"

👀 SEE ALSO 👀

More information is available on the program website: https://sml.zincube.net/~niol/repositories.git/lazygal/about/.

🫶 AUTHOR 🫶

This manual page was written for the DEBIAN system (but may be used by others). Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License, Version 2 any later version published by the Free Software Foundation.

On Debian systems, the complete text of the GNU General Public License can be found in /usr/share/common-licenses/GPL.

💜 AUTHORS 💜

Alexandre Rossi.

And that's the whole page, bestie — the footer down there just says LAZYGAL(1), which is this very manual for the lazygal program in section 1 of the manual pages. Go make some galleries, you're gonna eat 💖✨

📦 where this page comes from