add generate-viewer - helper for work

2026-06-07 21:02:02 +01:00
parent bea2caba9e
commit c282ff0bf9
4 changed files with 572 additions and 0 deletions
@@ -0,0 +1,88 @@
+# DJI Returns Image Viewer
+
+A self-contained local image reference tool for CMS Distribution's DJI returns inspection workflow. Built for warehouse staff to browse categorised damage photos without needing an internet connection or a web server.
+
+## What it does
+
+Opens as a single HTML file in any browser. Staff can browse 300+ reference photos organised by damage type, search by filename or category, and open images in a full-screen lightbox. Adding new photos is a one-step process.
+
+## Files
+
+| File | Purpose |
+|---|---|
+| `DJI_Returns_Image_Viewer.html` | The viewer — open this in a browser |
+| `viewer_template.html` | HTML/CSS/JS template used by the generator |
+| `generate_viewer.py` | Scans the Images folder and rebuilds the viewer |
+| `Refresh Image Viewer.bat` | Double-click shortcut to run the generator on Windows |
+| `Images/` | All reference photos, organised into subfolders by category |
+
+## Adding new images
+
+1. Drop the new images into the relevant subfolder under `Images/`
+2. Double-click **Refresh Image Viewer.bat**
+3. Open `DJI_Returns_Image_Viewer.html` — done
+
+New subfolders are picked up automatically. If you add a folder that isn't in the category config, it will appear in the sidebar under the **Reference** section using the folder name as the label. No code changes required for basic additions.
+
+## Customising category labels and sections
+
+Open `generate_viewer.py` and edit the `CATEGORY_CONFIG` dictionary near the top of the file. Each entry looks like this:
+
+```python
+'Folder Name': {
+    'label':   'Display name shown in the sidebar',
+    'section': 'accept',       # accept | reject | borderline | reference
+    'dot':     '#2acc94',      # colour of the dot indicator (hex)
+    'desc':    'Short description shown in the category bar',
+},
+```
+
+The key (left side) must exactly match the folder path relative to `Images/`, using forward slashes for subfolders:
+
+```python
+'Excessive Crash Damage':    {'label': 'Excessive Crash Damage', 'section': 'reject', ...},
+'Retail Images/Action':      {'label': 'Action Cameras',         'section': 'reference', ...},
+```
+
+After editing, run the generator to rebuild the viewer.
+
+## Changing the design
+
+All HTML, CSS, and JavaScript lives in `viewer_template.html`. Edit that file, then run the generator to apply changes to the output. Do not edit `DJI_Returns_Image_Viewer.html` directly — it is overwritten every time the generator runs.
+
+## Requirements
+
+- Python 3 (any recent version)
+- No third-party libraries — uses only the standard library
+- Any modern browser (Chrome, Edge, Firefox) to view the HTML
+
+Python must be on the system PATH for the `.bat` file to work. If it isn't, run the script directly from a terminal:
+
+```bash
+python generate_viewer.py
+```
+
+## Sidebar sections
+
+Images are grouped into four sections in the sidebar, controlled by the `section` field in the category config:
+
+| Section | Used for |
+|---|---|
+| `accept` | Damage that is acceptable — product can proceed |
+| `reject` | Automatic reject criteria |
+| `borderline` | Edge cases requiring judgement |
+| `reference` | Retail product shots and other reference material |
+
+## Viewer features
+
+- **Search** — filters by filename or category name
+- **Grid sizes** — three density options (large / medium / small)
+- **Lightbox** — click any image to open full screen; navigate with arrow keys or Prev/Next buttons; close with Escape
+- **Category bar** — shows the active category name, description, and image count
+- **No server required** — runs entirely from the local filesystem
+
+## Notes
+
+- The viewer uses `object-fit: contain` on all thumbnails to prevent portrait-orientation photos from being cropped
+- Scrollbars use `overflow-y: scroll` (always visible) rather than `auto` to prevent layout jump when switching categories
+- Images are not embedded in the HTML — they are referenced by relative path, so the `Images/` folder must stay in the same location as the HTML file