Gallery: Scientific Plot Organizer

Create responsive HTML galleries for scientific plot collections. Convert PDFs to PNG, organize plots hierarchically, and generate beautiful static websites.

Features

Core Functionality

• PDF to PNG Conversion using ImageMagick
• Incremental updates only when plot is newer than cached
• Responsive design using Jinja2 (also on mobile)
• Support for nested folder structures
• Search bar
• Breadcrump navigation

Advanced Features

• Compare two plots from the same folder
• YAML/JSON metadata with inheritance and display to properly label each folder
• Recent plots
• Dark and light mode
• Keyboard shortcuts

Developer-Friendly

• Full python API: import gallery
• CLI: gallery
• TUI: gallery tui
• Config file stored under user $HOME/.config/gallery

Installation

From GitLab

Pip install:

pip install git+https://gitlab.etp.kit.edu/kschmidt/web

Or git clone and pip install .. After installation the gallery command is available in your shell. Verify with:

gallery --help

Dependencies

• Python 3.8+
• Python packages are installed automatically by pip (Jinja2, PyYAML, PyMuPDF, Textual, argcomplete, platformdirs)
• ImageMagick is optional — used as a fallback if PyMuPDF is not available

Shell Completion (optional)

Install tab-completion for bash/zsh/fish:

gallery install-completion

Then restart your shell or follow the printed instructions to activate it.

CLI Usage

The gallery command has four subcommands: generate, config, tui, and install-completion.

Quick start

# 1. Set your web output directory
gallery config set paths.web_folder /path/to/your/public_html

# 2. Add one or more plot source directories
gallery config add-source --path /path/to/plots --name my_analysis

# 3. Generate the gallery
gallery generate

gallery generate

# Full regeneration
gallery generate

# Verbose output
gallery generate --verbose

# Clean rebuild (delete output before generating)
gallery generate --clean

# Regenerate a single source only (name will be the basename of the path)
gallery generate --source /path/to/plots

# Use a non-default config file
gallery --config /path/to/config.yaml generate

gallery config

# Show all configuration values
gallery config list

# Show the resolved config file path
gallery config path

# List configured sources
gallery config sources

# Get a single value
gallery config get gallery.png_dpi

# Set a value (all standard YAML types accepted)
gallery config set gallery.png_dpi 300
gallery config set metadata.cache_enabled true

# Add a source directory
gallery config add-source --path /path/to/plots --name my_plots

# Remove a source
gallery config remove-source my_plots

Serving locally

python -m http.server 8000 -d /path/to/public_html

Then open http://localhost:8000/gallery/ in your browser. You can of course use any port you want to.

Screenshots

Main Gallery View

Metadata Display

Plot Comparison Tool

Search Functionality

TUI Usage

The TUI is a terminal user interface built with Textual. It lets you edit the configuration and trigger generation without leaving your terminal.

gallery tui

Configuration

The config file lives at $HOME/.config/gallery/config.yaml by default. You can point to a different file with gallery --config /path/to/config.yaml <subcommand>.

Config structure

paths:
  web_folder: "/web/user/public_html"   # required

gallery:
  plot_root: "gallery"       # subdirectory inside web_folder
  png_dpi: 400               # thumbnail resolution
  backup_folder: ""          # optional backup path

sources:
  - name: "analysis_results"
    path: "/path/to/plots/directory"
  - name: "specific_plot"
    path: "/path/to/another/directory"

metadata:
  cache_enabled: true
  inherit_from_parent: true

Metadata Files

Create metadata.yaml files in your source directories. Fields are arbitrary and rendered via YAML object interpretation (dict, list, …). Lower-level files override parent values, which is useful for labelling specific experiments.

# metadata.yaml
title: "Analysis Results"
description: "Results for my analysis"
experiment: "CMS"
dataset: "Run2_2016_nano_v9"

parameters:
  luminosity: "35.9 fb^{-1}"
  center_of_mass_energy: "13 TeV"
  selection: "baseline"

tags:
  - "physics"
  - "analysis"
  - "cms"

authors:
  - "Researcher A"
  - "Researcher B"

LaTeX formulas are supported in metadata values and rendered with MathJax:

formula: "$$E = mc^2$$"

Shortcuts

Icon	Button	Function	Shortcut
🔍	Search	Real-time plot search	Ctrl+K
📋	Recent	Recently viewed plots	Ctrl+R
⚖️	Compare	Side-by-side comparison	Ctrl+C
☀️	Theme	Toggle dark/light theme	Ctrl+T

Troubleshooting

Common Issues

Issue	(Potential) Solution
gallery command not found	Run pip install -e . from the repo root
PDF conversion fails — no renderer	Install PyMuPDF: pip install pymupdf (or apt-get install imagemagick as fallback)
PDF conversion fails — corrupt file	Verify the PDF opens in a viewer; try pip install --upgrade pymupdf
Permission denied on web dir	Check file permissions and web directory access
Metadata not showing	Check YAML syntax with python -c "import yaml; yaml.safe_load(open('metadata.yaml'))"

ImageMagick memory limits (fallback backend only)

export MAGICK_MEMORY_LIMIT=2GB
export MAGICK_MAP_LIMIT=2GB
gallery generate --verbose

License

This project is licensed under the MIT License — see the LICENSE file for details.

Disclaimer on the use of Artificial Intelligence

This project was made entirely using Claude Sonnet 4.0 and GPT 4.1. 100% of the code was AI generated and no human hand was involved other than prompting the Agent.

Links

• Example Gallery