From 31d33f4f410cb03942786d0789681690af1c4bd8 Mon Sep 17 00:00:00 2001 From: Kylian Schmidt Date: Sat, 16 May 2026 15:08:08 +0200 Subject: [PATCH] Update README --- README.md | 125 ++++++++++++++++++------------------------------------ 1 file changed, 41 insertions(+), 84 deletions(-) diff --git a/README.md b/README.md index d6182df..2930f71 100644 --- a/README.md +++ b/README.md @@ -8,39 +8,28 @@ ## Features ### Core Functionality -- **PDF to PNG Conversion**: Automatic high-quality thumbnail generation using ImageMagick -- **Incremental Updates**: Only processes files when source is newer than target -- **Responsive Design**: Mobile-friendly interface with multiple view modes -- **Hierarchical Organization**: Support for nested folder structures -- **Search & Navigation**: Real-time search with fuzzy matching + +- 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 -- **Plot Comparison**: Side-by-side comparison tool for analyzing differences -- **Metadata Management**: YAML/JSON metadata with inheritance and display, to properly label each folder -- **Recent Plots**: Quick access to recently viewed items -- **Theme Support**: Dark/light theme toggle -- **Keyboard Shortcuts**: Power-user navigation + +- 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 -- **Python API**: Import and use programmatically in other projects -- **CLI Interface**: Command-line command `gallery` with subcommands -- **TUI Interface**: Textual-based terminal UI `gallery tui` -- **Configuration Flexibility**: Config file stored under user `$HOME/.config/gallery` -- **Source Override**: Process single directories without full regeneration -## 📸 Screenshots - -### Main Gallery View -![gallery_view](docs/images/main_gallery_view.png) - -### Metadata Display -![metadata](docs/images/metadata_view.png) - -### Plot Comparison Tool -![plot_comparison](docs/images/plot_comparison.png) - -### Search Functionality - +- Full python API: `import gallery` +- CLI: `gallery` +- TUI: `gallery tui` +- Config file stored under user `$HOME/.config/gallery` ## 🚀 Installation @@ -63,7 +52,7 @@ gallery --help - Python 3.8+ - Python packages are installed automatically by pip (Jinja2, PyYAML, PyMuPDF, Textual, argcomplete, platformdirs) -- [ImageMagick](https://imagemagick.org/) is **optional** — used as a fallback if PyMuPDF is not available +- [ImageMagick](https://imagemagick.org/) is **optional** — used as a fallback if `PyMuPDF` is not available ### Shell Completion (optional) @@ -75,7 +64,6 @@ 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`. @@ -105,7 +93,7 @@ gallery generate --verbose # Clean rebuild (delete output before generating) gallery generate --clean -# Regenerate a single source only +# 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 @@ -144,7 +132,21 @@ gallery config remove-source my_plots python -m http.server 8000 -d /path/to/public_html ``` -Then open `http://localhost:8000/gallery/` in your browser. +Then open `http://localhost:8000/gallery/` in your browser. You can of course use any port you want to. + +## 📸 Screenshots + +### Main Gallery View +![gallery_view](docs/images/main_gallery_view.png) + +### Metadata Display +![metadata](docs/images/metadata_view.png) + +### Plot Comparison Tool +![plot_comparison](docs/images/plot_comparison.png) + +### Search Functionality + ## 🖱️ TUI Usage @@ -155,35 +157,11 @@ The TUI is a terminal user interface built with [Textual](https://textual.textua gallery tui ``` -### TUI Overview - -The TUI is divided into collapsible sections and a persistent footer: - -| Section | Contents | -|---------|----------| -| **Paths** | Web output folder | -| **Gallery Settings** | Plot root, PNG DPI, backup folder, cache and metadata options | -| **Sources** | Editable list of source directories — add or remove rows inline | -| **Generation** | Status indicator, scrollable log output | - -The **footer bar** is always visible at the bottom: - -| Button | Keyboard | Action | -|--------|----------|--------| -| Save Config | `Ctrl+S` | Write current values to config file | -| Generate | — | Run `gallery generate` in background | -| Quit | `Ctrl+Q` | Exit the TUI | - -An **unsaved changes indicator** (`● unsaved changes`) appears in the title bar whenever a field has been modified but not yet saved. - -Generation runs in a background thread and streams output line-by-line into the log widget. The status button changes colour: blue (idle) → yellow (running) → green (success) / red (error). - - -## ⚙️ Configuration +## 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 `. -### config.yaml Structure +### Config structure ```yaml paths: @@ -207,7 +185,7 @@ metadata: ### 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 — useful for labelling specific experiments. +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. ```yaml # metadata.yaml @@ -237,10 +215,7 @@ LaTeX formulas are supported in metadata values and rendered with MathJax: formula: "$$E = mc^2$$" ``` - -## 🎮 User Interface Guide - -### Navigation Controls +## Shortcuts | Button | Function | Keyboard Shortcut | |--------|----------|-------------------| @@ -249,12 +224,6 @@ formula: "$$E = mc^2$$" | ⚖️ Compare | Side-by-side comparison | `Ctrl+C` | | ☀️ Theme | Toggle dark/light theme | `Ctrl+T` | -### View Modes - -- **Grid View**: Thumbnail grid with metadata overlay -- **Large List**: Detailed list with larger previews -- **Compact List**: Dense list for quick scanning - ## 🛠️ Development Guide @@ -306,7 +275,7 @@ export class NewFeature { ... } Import in `gallery-app.js` and instantiate in `GalleryApp`. -## 🔧 Troubleshooting +## Troubleshooting ### Common Issues @@ -334,26 +303,14 @@ gallery generate --clean --verbose ``` -## 📄 License +## License This project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details. -## 🙏 Acknowledgments - -### Disclaimer +## 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. I do not claim any part of this project as my own work. -### Packages - -- **PyMuPDF** for PDF to PNG conversion (pure Python, no system dependencies) -- **ImageMagick** as optional fallback PDF renderer -- **Jinja2** for templating -- **Textual** for the terminal UI -- **MathJax** for LaTeX rendering -- **PyYAML** for YAML processing -- **argcomplete** for shell tab-completion - ## 🔗 Links - [Example Gallery](https://etpwww.etp.kit.edu/~kschmidt/gallery/index.html)