Add nice README

2025-07-31 16:39:59 +02:00
parent 687f8c4533
commit b6a37fb93f
9 changed files with 347 additions and 84 deletions
@@ -1,58 +1,362 @@
-# Gallery Application - Restructured
+# 🔬 Scientific Gallery Generator

-This document explains the new modular structure of the gallery application.
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://GitHub.com/Naereen/StrapDown.js/graphs/commit-activity)

-## Project Structure
+A powerful, responsive web-based gallery generator for scientific plots and analysis results. Transform your PDF plots into interactive HTML galleries with search, comparison tools, and hierarchical metadata management.
+
+## ✨ 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
+
+### 📊 Advanced Features
+- **Plot Comparison**: Side-by-side comparison tool for analyzing differences
+- **Metadata Management**: YAML/JSON metadata with inheritance and display
+- **Export Capabilities**: Batch export selected plots
+- **Recent Plots**: Quick access to recently viewed items
+- **Theme Support**: Dark/light theme toggle
+- **Keyboard Shortcuts**: Power-user navigation
+
+### 🔧 Metadata System
+- **Hierarchical Inheritance**: Child directories inherit parent metadata
+- **Multiple Formats**: Support for YAML and JSON metadata files
+- **Interactive Display**: Collapsible metadata sections with copy-to-clipboard
+- **LaTeX Support**: Mathematical expressions rendered with MathJax
+- **Path Information**: Easy access to metadata file locations
+
+## 📸 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">
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+```bash
+# Required system dependencies
+sudo apt-get install imagemagick python3 python3-pip
+
+# Python dependencies
+pip install jinja2 pyyaml
+```
+
+### Installation
+
+1. **Clone the repository**
+   ```bash
+   git clone <repository-url>
+   cd scientific-gallery-generator
+   ```
+
+2. **Configure sources**
+   ```bash
+   config.yaml  # Edit config.yaml to point to your plot directories
+   ```
+
+3. **Generate gallery**
+   ```bash
+   python generate_gallery.py
+   ```
+
+4. **Serve locally** (optional)
+   ```bash
+   python -m http.server 8000 -d /path/to/web/directory
+   ```
+
+## ⚙️ Configuration
+
+### config.yaml Structure
+
+```yaml
+# Gallery configuration
+web_folder: "/web/user/public_html"
+plot_root: "gallery"
+png_dpi: 150  # just the thumbnails
+
+# Source directories
+sources:
+  - name: "analysis_results"
+    path: "/path/to/plots/directory"
+  - name: "specific_plot"
+    path: "/path/to/single/plot.pdf"
+
+# UI settings
+ui:
+  search_debounce_ms: 300
+  max_recent_plots: 20
+
+# Path settings
+paths:
+  work_dir: "/work/directory"
+```
+
+### Metadata Files
+
+Create `metadata.yaml` files in your source directories:
+
+```yaml
+# 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"
+```
+
+## 🎮 User Interface Guide
+
+### Navigation Controls
+
+| Button | Function | Keyboard 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` |
+
+### Metadata Section
+![metadata](docs/images/metadata.png)
+
+- **Toggle Button**: Show/hide folder information
+- **Copy Path**: Quick access to metadata file location
+- **Hover Tip**: Information about metadata file formats
+- **YAML Structure**: Preserves original formatting and indentation
+
+### View Modes
+<img src="docs/images/grid_view.png" width="200px">
+
+- **Grid View**: Thumbnail grid with metadata overlay
+- **Large List**: Detailed list with larger previews
+- **Compact List**: Dense list for quick scanning
+
+## 🛠️ Development Guide
+
+### Project Structure

 ```
-web/
-├── assets/
-│   ├── css/
-│   │   ├── main.css              # Main CSS file (imports all others)
-│   │   ├── variables.css         # CSS custom properties and themes
-│   │   ├── base.css              # Base layout and typography
-│   │   ├── navigation.css        # Breadcrumb and navigation styles
-│   │   ├── search.css            # Search functionality styles
-│   │   ├── folder-tree.css       # Folder tree component styles
-│   │   ├── grid.css              # Plot grid and selection styles
-│   │   ├── sidebar.css           # Recent plots sidebar styles
-│   │   ├── floating-elements.css # Floating buttons and help
-│   │   ├── stats.css             # Gallery statistics styles
-│   │   ├── comparison.css        # Plot comparison overlay styles
-│   │   └── responsive.css        # Mobile and responsive styles
-│   └── js/
-│       ├── main.js               # Main entry point
-│       ├── gallery-app.js        # Main application orchestrator
-│       ├── theme-manager.js      # Theme switching functionality
-│       ├── navigation-manager.js # Breadcrumb and folder tree
-│       ├── search-manager.js     # Search functionality
-│       ├── recent-plots-manager.js # Recent plots sidebar
-│       ├── comparison-manager.js # Plot comparison features
-│       ├── stats-manager.js      # Gallery statistics
-│       ├── keyboard-manager.js   # Keyboard shortcuts
-│       └── utils.js              # Utility functions
+scientific-gallery-generator/
+├── generate_gallery.py          # Main gallery generator
+├── config.yaml                  # Configuration file
 ├── templates/
-│   └── gallery.html              # Clean HTML template
-├── template.html                 # Original monolithic file (backup)
-├── config.py
-├── config.yaml
-├── generate_gallery.py
-└── README.md
+│   └── gallery.html             # Jinja2 template
+├── assets/
+│   ├── css/                     # Stylesheets
+│   │   ├── main.css             # Main stylesheet
+│   │   ├── variables.css        # CSS variables
+│   │   ├── metadata-section.css # Metadata styling
+│   │   └── ...
+│   └── js/                      # JavaScript modules
+│       ├── main.js              # Application entry point
+│       ├── gallery-app.js       # Core application
+│       ├── metadata-section.js  # Metadata functionality
+│       └── ...
+├── orchestration/
+│   ├── config.py                # Configuration management
+│   ├── metadata.py              # Metadata handling
+│   └── ...
+└── tests/
+    └── validate_metadata.py     # Metadata validation
 ```

-## Key Improvements
+### Adding New Features

-### 1. **Separation of Concerns**
- **CSS**: Organized into logical components (navigation, search, grid, etc.)
- **JavaScript**: Split into focused managers with single responsibilities
- **HTML**: Clean template focusing on structure
+#### 1. CSS Components
+```css
+/* assets/css/new-feature.css */
+.new-feature {
+    /* Your styles here */
+}
+```

-### 2. **Modular Architecture**
+Add to `assets/css/main.css`:
+```css
+@import url('./new-feature.css');
+```
+
+#### 2. JavaScript Modules
+```javascript
+// assets/js/new-feature.js
+export class NewFeature {
+    constructor() {
+        this.init();
+    }
+    
+    init() {
+        // Initialize your feature
+    }
+}
+```
+
+Import in `assets/js/gallery-app.js`:
+```javascript
+import { NewFeature } from './new-feature.js';
+```
+
+#### 3. Template Extensions
+```html
+<!-- templates/gallery.html -->
+{% if new_feature_enabled %}
+<div class="new-feature">
+    <!-- Your HTML here -->
+</div>
+{% endif %}
+```
+
+### Metadata System Extension
+
+#### Custom Metadata Fields
+```yaml
+# metadata.yaml
+custom_field: "value"
+nested_data:
+  subfield: "nested value"
+  list_data:
+    - "item 1"
+    - "item 2"
+```
+
+#### LaTeX Support
+```yaml
+formula: "$$E = mc^2$$"
+equation: "$$\\sum_{i=1}^{n} x_i = \\bar{x} \\cdot n$$"
+```
+
+## 🔧 Advanced Configuration
+
+### ImageMagick Settings
+```bash
+# Increase memory limits for large PDFs
+export MAGICK_MEMORY_LIMIT=2GB
+export MAGICK_MAP_LIMIT=2GB
+```
+
+### Performance Optimization
+```yaml
+# config.yaml
+png_dpi: 150              # Balance quality vs. file size
+parallel_processing: true  # Enable multi-threading
+cache_enabled: true       # Enable metadata caching
+```
+
+### Custom Styling
+```css
+/* Override theme colors */
+:root {
+  --primary-color: #your-color;
+  --background-color: #your-bg;
+}
+```
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+| Issue | Solution |
+|-------|----------|
+| ImageMagick not found | Install: `sudo apt-get install imagemagick` |
+| Permission denied | Check file permissions and web directory access |
+| PDF conversion fails | Verify PDF is not corrupted, increase memory limits |
+| Metadata not showing | Check YAML syntax and file permissions |
+| JavaScript errors | Clear browser cache and check console |
+
+### Debug Mode
+```bash
+# Enable verbose logging
+python generate_gallery.py --verbose
+
+# Clean regeneration
+python generate_gallery.py --clean
+```
+
+## 🤝 Contributing
+
+**IMPORTANT**: Since this is in part a project made for fun made to test the limits of AI coding agents, all code pushed to this repository must be AI generated. Use your favorite agent of choice, mine was Github Copilot for VSCode. Bonus points if you let the agent write the commit messages too.
+
+1. **Fork the repository**
+2. **Create a feature branch**
+   ```bash
+   git checkout -b feature/amazing-feature
+   ```
+3. **Commit your changes**
+   ```bash
+   git commit -m 'Add amazing feature'
+   ```
+4. **Push to the branch**
+   ```bash
+   git push origin feature/amazing-feature
+   ```
+5. **Open a Pull Request**
+
+### Development Setup
+```bash
+# Install development dependencies
+pip install -r requirements-dev.txt
+
+# Run tests
+python -m pytest tests/
+
+# Validate metadata
+python tests/validate_metadata.py
+```
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. See the Disclaimer section below for more information.
+
+## 🙏 Acknowledgments
+
+### Disclaimer
+
+This project was made *entirely* using Claude Sonnet 4.0 and GPT 4.1. 100% of the code was AI generated an no human hand was involved other than prompting the Agent. I do not claim any part of this project as my own work.
+
+### Packages:
+
+- **ImageMagick** for PDF to PNG conversion
+- **Jinja2** for templating engine
+- **MathJax** for LaTeX rendering
+- **PyYAML** for YAML processing
+
+## 📚 Documentation
+
+Currently empty
+
+## 🔗 Links
+
+- [Example Gallery](https://etpwww.etp.kit.edu/~kschmidt/gallery/index.html)
+
+### 3. **Maintainability**
 - Each JavaScript module handles a specific feature area
 - Modules can be independently maintained and tested
 - Clear dependencies and interfaces between modules
-
-### 3. **Maintainability**
 - Individual files are much smaller and focused
 - Easy to locate and modify specific functionality
 - Reduced cognitive load when working on features
@@ -104,38 +408,3 @@ template_path = 'templates/gallery.html'

 ### CSS Asset Path
 The template expects CSS/JS assets to be served from `/assets/` relative to the gallery pages. Update your web server configuration to serve these static files.
-
-### No Breaking Changes
- All onclick handlers work the same
- All CSS classes remain unchanged  
- All IDs and functionality preserved
- Jinja2 template variables work identically
-
-## Development Workflow
-
-### Adding New Features
-1. Identify which manager should handle the new functionality
-2. Add methods to the appropriate manager class
-3. Update the main GalleryApp class if needed
-4. Add any new CSS to the appropriate CSS module
-
-### Modifying Existing Features
-1. Locate the relevant manager (theme, search, navigation, etc.)
-2. Make changes to the specific module
-3. Test that the feature works as expected
-
-### Styling Changes
-1. Identify the component being styled
-2. Edit the appropriate CSS module
-3. The main.css file will automatically include changes
-
-## Benefits of This Structure
-
-1. **Easier Debugging**: Each feature is isolated in its own file
-2. **Better Performance**: Browser can cache individual modules
-3. **Team Development**: Multiple developers can work on different features simultaneously
-4. **Code Reuse**: Managers can be reused in other projects
-5. **Testing**: Individual modules can be unit tested
-6. **Documentation**: Each file has a clear, focused purpose
-
-This restructuring makes the gallery application much more maintainable while preserving all existing functionality.
@@ -9,12 +9,6 @@ paths:
  # Web hosting directory where gallery files are served
  web_folder: "/web/kschmidt/public_html/"

-  # CGI script path (relative to web folder)
-  cgi_script: "cgi-bin/refresh_gallery.py"
-  
-  # Config file path for CGI scripts
-  config_path: "/work/kschmidt/web"
-
 # Gallery Settings
 gallery:
  # Root folder name for plots in web directory