lars/ETPlot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update README

Browse Source
This commit is contained in:
Kylian Schmidt
2026-05-16 15:08:08 +02:00
parent 04e5f79efc
commit 31d33f4f41
1 changed files with 41 additions and 84 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+41 -84
View File
@@ -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
<img src="docs/images/search.png" width="500px">
- 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
<img src="docs/images/search.png" width="500px">
## 🖱️ 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 <subcommand>`.
### 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)