New features and bug fixes

faststack/README.md

@@ -1,66 +1,67 @@
-# FastStack
-
-# Version 1.3 - November 23, 2025
-# By Alan Rockefeller
-
-Ultra-fast, caching JPG viewer designed for culling and selecting RAW or JPG files for focus stacking and website upload.
-
-This tool is optimized for speed, using `libjpeg-turbo` for decoding, aggressive prefetching, and byte-aware LRU caches to provide a fluid experience when reviewing thousands of images.
-
-## Features
-
-- **Crop:** Added the ability to crop images via the cr(O)p hotkey.   It can be a freeform crop, or constrained to several popular aspect ratios.
-- **Zoom & Pan:** Smooth zooming and panning.
-- **Stack Selection:** Group images into stacks (`[`, `]`) and select them for processing (`S`).
-- **Helicon Focus Integration:** Launch Helicon Focus with your selected RAW files with a single keypress (`Enter`).
-- **Instant Navigation:** Sub-10ms next/previous image switching, high performance decoding via `PyTurboJPEG`.
-- **Image Editor:** Built-in editor with exposure, contrast, white balance, sharpness, and more (E key)
-- **Quick Auto White Balance:** Press A to apply auto white balance and save automatically with undo support (Ctrl+Z).   For better white balance load the raw into Photoshop with the P key.
-- **Photoshop Integration:** Edit current image in Photoshop (P key) - always uses RAW files when available, even for backup files
-- **Clipboard Support:** Copy image path to clipboard (Ctrl+C)
-- **Image Filtering:** Filter images by filename
-- **Drag & Drop:** Drag images to external applications.   Press { and } to batch files to drag & drop multiple images.
-- **Theme Support:** Toggle between light and dark themes
-- **Delete & Undo:** Move images to recycle bin (Delete/Backspace) with undo support (Ctrl+Z)
-- **Has Memory:** Starts where you left off, tells you which images have been edited, stacked and uploaded
-- **RAW Pairing:** Automatically maps JPGs to their corresponding RAW files (`.CR3`, `.ARW`, `.NEF`, etc.).
-- **Configurable:** Adjust cache sizes, prefetch behavior, and Helicon Focus / Photoshop paths via a settings dialog and a persistent `.ini` file.
-- **Accurate Colors:** Uses monitor ICC profile to display colors correctly.
-
-## Installation & Usage
-
-1.  **Install Dependencies:**
-    ```bash
-    pip install -r requirements.txt
-    ```
-
-2.  **Run the App:**
-    ```bash
-    python -m faststack.app "C:\path\to\your\images"
-    ```
-
-## Keyboard Shortcuts
-
-- `J` / `Right Arrow`: Next Image
-- `K` / `Left Arrow`: Previous Image
-- `G`: Go to image #
-- `S`: Toggle selection of current image for stacking 
-- `B`: Toggle selection of current image for batch drag & drop
-- `[`: Begin new stack group
-- `]`: End current stack group
-- `{`: Begin new drag & drop batch
-- `}`: End current drag & drop batch
-- '\': Clear drag & drop batch
-- 'U': Toggle uploaded flag
-- 'Ctrl+E': Toggle edited flag
-- 'Ctrl+S': Toggle stacked flag
-- `Enter`: Launch Helicon Focus with selected RAWs
-- `P`: Edit in Photoshop (uses RAW file if available)
-- `Delete` / `Backspace`: Move image to recycle bin
-- `Ctrl+Z`: Undo last action (delete or auto white balance)
-- `A`: Quick auto white balance (saves automatically)
-- `E`: Toggle Image Editor
-- 'O': Crop image
-- `Ctrl+C`: Copy image path to clipboard
-- `Ctrl+0`: Reset zoom and pan
-- `C`: Clear all stacks
+# FastStack
+
+# Version 1.4 - December 1, 2025
+# By Alan Rockefeller
+
+Ultra-fast, caching JPG viewer designed for culling and selecting RAW or JPG files for focus stacking and website upload.
+
+This tool is optimized for speed, using `libjpeg-turbo` for decoding, aggressive prefetching, and byte-aware LRU caches to provide a fluid experience when reviewing thousands of images.
+
+## Features
+
+- **Crop:** Added the ability to crop images via the cr(O)p hotkey.   It can be a freeform crop, or constrained to several popular aspect ratios.
+- **Zoom & Pan:** Smooth zooming and panning.
+- **Stack Selection:** Group images into stacks (`[`, `]`) and select them for processing (`S`).
+- **Helicon Focus Integration:** Launch Helicon Focus with your selected RAW files with a single keypress (`Enter`).
+- **Instant Navigation:** Sub-10ms next/previous image switching, high performance decoding via `PyTurboJPEG`.
+- **Image Editor:** Built-in editor with exposure, contrast, white balance, sharpness, and more (E key)
+- **Quick Auto White Balance:** Press A to apply auto white balance and save automatically with undo support (Ctrl+Z).   For better white balance load the raw into Photoshop with the P key.
+- **Photoshop Integration:** Edit current image in Photoshop (P key) - always uses RAW files when available, even for backup files
+- **Clipboard Support:** Copy image path to clipboard (Ctrl+C)
+- **Image Filtering:** Filter images by filename
+- **Drag & Drop:** Drag images to external applications.   Press { and } to batch files to drag & drop multiple images.
+- **Theme Support:** Toggle between light and dark themes
+- **Delete & Undo:** Move images to recycle bin (Delete/Backspace) with undo support (Ctrl+Z)
+- **Has Memory:** Starts where you left off, tells you which images have been edited, stacked and uploaded
+- **RAW Pairing:** Automatically maps JPGs to their corresponding RAW files (`.CR3`, `.ARW`, `.NEF`, etc.).
+- **Configurable:** Adjust cache sizes, prefetch behavior, and Helicon Focus / Photoshop paths via a settings dialog and a persistent `.ini` file.
+- **Accurate Colors:** Uses monitor ICC profile to display colors correctly.
+- **RGB Histogram:** Pressing H brings up a RGB histogram which is designed to show even a little bit of highlight clipping and updates as you zoom in.
+
+## Installation & Usage
+
+1.  **Install Dependencies:**
+    ```bash
+    pip install -r requirements.txt
+    ```
+
+2.  **Run the App:**
+    ```bash
+    python -m faststack.app "C:\path\to\your\images"
+    ```
+
+## Keyboard Shortcuts
+
+- `J` / `Right Arrow`: Next Image
+- `K` / `Left Arrow`: Previous Image
+- `G`: Go to image #
+- `S`: Toggle selection of current image for stacking 
+- `B`: Toggle selection of current image for batch drag & drop
+- `[`: Begin new stack group
+- `]`: End current stack group
+- `{`: Begin new drag & drop batch
+- `}`: End current drag & drop batch
+- '\': Clear drag & drop batch
+- 'U': Toggle uploaded flag
+- 'Ctrl+E': Toggle edited flag
+- 'Ctrl+S': Toggle stacked flag
+- `Enter`: Launch Helicon Focus with selected RAWs
+- `P`: Edit in Photoshop (uses RAW file if available)
+- `O`: Toggle crop mode (cr(O)p hotkey; Enter to crop, Esc to cancel)
+- `Delete` / `Backspace`: Move image to recycle bin
+- `Ctrl+Z`: Undo last action (delete or auto white balance)
+- `A`: Quick auto white balance (saves automatically)
+- `E`: Toggle Image Editor
+- `Ctrl+C`: Copy image path to clipboard
+- `Ctrl+0`: Reset zoom and pan
+- `C`: Clear all stacks

faststack/faststack.egg-info/PKG-INFO

@@ -1,71 +1,71 @@
-Metadata-Version: 2.4
-Name: faststack
-Version: 1.3
-Summary: Ultra-fast JPG Viewer for Focus Stacking Selection and website upload via drag and drop
-Author-email: Alan Rockefeller <alanrockefeller@gmail.com>
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: Microsoft :: Windows
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: PySide6<7.0,>=6.0
-Requires-Dist: PyTurboJPEG<2.0,>=1.8
-Requires-Dist: numpy<3.0,>=2.0
-Requires-Dist: cachetools<6.0,>=5.0
-Requires-Dist: watchdog<5.0,>=4.0
-Requires-Dist: Pillow<11.0,>=10.0
-Requires-Dist: pytest<9.0,>=8.0
-Dynamic: license-file
-
-# FastStack
-
-# Version 1.3 - November 23, 2025
-# By Alan Rockefeller
-
-Ultra-fast, caching JPG viewer designed for culling and selecting RAW or JPG files for focus stacking.
-
-This tool is optimized for speed, using `libjpeg-turbo` for decoding, aggressive prefetching, and byte-aware LRU caches to provide a fluid experience when reviewing thousands of images.
-
-## Features
-
-- **Instant Navigation:** Sub-10ms next/previous image switching on cache hits.
-- **High-Performance Decoding:** Uses `PyTurboJPEG` for fast JPEG decoding, with a fallback to `Pillow`.
-- **Zoom & Pan:** Smooth, mipmapped zooming and panning.
-- **RAW Pairing:** Automatically maps JPGs to their corresponding RAW files (`.CR3`, `.ARW`, `.NEF`, etc.).
-- **Stack Selection:** Group images into stacks (`[`, `]`) and select them for processing (`S`).
-- **Helicon Focus Integration:** Launch Helicon Focus with your selected RAW files with a single keypress (`Enter`).
-- **Sidecar Metadata:** Saves flags, rejections, and stack groupings to a non-destructive `faststack.json` file.
-- **Configurable:** Adjust cache sizes, prefetch behavior, and Helicon Focus path via a settings dialog and a persistent `.ini` file.
-- **Photoshop Integration:** Edit current image in Photoshop (E key)
-- **Clipboard Support:** Copy image path to clipboard (Ctrl+C)
-- **Image Filtering:** Filter images by filename
-- **Drag & Drop:** Drag images to external applications
-- **Theme Support:** Toggle between light and dark themes
-
-## Installation & Usage
-
-1.  **Install Dependencies:**
-    ```bash
-    pip install -r requirements.txt
-    ```
-
-2.  **Run the App:**
-    ```bash
-    python -m faststack.app "C:\path\to\your\images"
-    ```
-
-## Keyboard Shortcuts
-
-- `J` / `Right Arrow`: Next Image
-- `K` / `Left Arrow`: Previous Image
-- `G`: Toggle Grid View
-- `S`: Toggle selection of current image for stacking
-- `[`: Begin new stack group
-- `]`: End current stack group
-- `Space`: Toggle Flag
-- `X`: Toggle Reject
-- `Enter`: Launch Helicon Focus with selected RAWs
-- `E`: Edit in Photoshop
-- `Ctrl+C`: Copy image path to clipboard
-- `C`: Clear all stacks
+Metadata-Version: 2.4
+Name: faststack
+Version: 1.3
+Summary: Ultra-fast JPG Viewer for Focus Stacking Selection and website upload via drag and drop
+Author-email: Alan Rockefeller <alanrockefeller@gmail.com>
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PySide6<7.0,>=6.0
+Requires-Dist: PyTurboJPEG<2.0,>=1.8
+Requires-Dist: numpy<3.0,>=2.0
+Requires-Dist: cachetools<6.0,>=5.0
+Requires-Dist: watchdog<5.0,>=4.0
+Requires-Dist: Pillow<11.0,>=10.0
+Requires-Dist: pytest<9.0,>=8.0
+Dynamic: license-file
+
+# FastStack
+
+# Version 1.3 - November 23, 2025
+# By Alan Rockefeller
+
+Ultra-fast, caching JPG viewer designed for culling and selecting RAW or JPG files for focus stacking.
+
+This tool is optimized for speed, using `libjpeg-turbo` for decoding, aggressive prefetching, and byte-aware LRU caches to provide a fluid experience when reviewing thousands of images.
+
+## Features
+
+- **Instant Navigation:** Sub-10ms next/previous image switching on cache hits.
+- **High-Performance Decoding:** Uses `PyTurboJPEG` for fast JPEG decoding, with a fallback to `Pillow`.
+- **Zoom & Pan:** Smooth, mipmapped zooming and panning.
+- **RAW Pairing:** Automatically maps JPGs to their corresponding RAW files (`.CR3`, `.ARW`, `.NEF`, etc.).
+- **Stack Selection:** Group images into stacks (`[`, `]`) and select them for processing (`S`).
+- **Helicon Focus Integration:** Launch Helicon Focus with your selected RAW files with a single keypress (`Enter`).
+- **Sidecar Metadata:** Saves flags, rejections, and stack groupings to a non-destructive `faststack.json` file.
+- **Configurable:** Adjust cache sizes, prefetch behavior, and Helicon Focus path via a settings dialog and a persistent `.ini` file.
+- **Photoshop Integration:** Edit current image in Photoshop (E key)
+- **Clipboard Support:** Copy image path to clipboard (Ctrl+C)
+- **Image Filtering:** Filter images by filename
+- **Drag & Drop:** Drag images to external applications
+- **Theme Support:** Toggle between light and dark themes
+
+## Installation & Usage
+
+1.  **Install Dependencies:**
+    ```bash
+    pip install -r requirements.txt
+    ```
+
+2.  **Run the App:**
+    ```bash
+    python -m faststack.app "C:\path\to\your\images"
+    ```
+
+## Keyboard Shortcuts
+
+- `J` / `Right Arrow`: Next Image
+- `K` / `Left Arrow`: Previous Image
+- `G`: Toggle Grid View
+- `S`: Toggle selection of current image for stacking
+- `[`: Begin new stack group
+- `]`: End current stack group
+- `Space`: Toggle Flag
+- `X`: Toggle Reject
+- `Enter`: Launch Helicon Focus with selected RAWs
+- `E`: Edit in Photoshop
+- `Ctrl+C`: Copy image path to clipboard
+- `C`: Clear all stacks

faststack/faststack/AGENTS.md

@@ -0,0 +1,19 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+`app.py` is the PySide6 entrypoint that coordinates image indexing, caching, and the QML screens supplied in `qml/`. Supporting modules are grouped by role: `imaging/` manages decode workflow, metadata, editing, and ICC caches; `io/` hosts directory watchers, Helicon Focus integration, executable checks, and RAW indexing; `ui/` contains providers and keystroke maps shared with QML. Configuration defaults live in `config.py`, persisted session data in `faststack.json`, and targeted unit tests plus decode benchmarks in `tests/`.
+
+## Build, Test, and Development Commands
+Run `python -m faststack.app <image_dir>` from the repo root to open the client; add `--debug` or `--debugcache` when you need verbose timings or cache telemetry. Execute `pytest tests/` before every PR, or focus on one area (for example `pytest tests/test_metadata.py -k gps`). Benchmarks in `tests/benchmark_decode*.py` can be invoked directly with `python` to gauge decoder changes without launching the UI.
+
+## Coding Style & Naming Conventions
+Use four-space indentation, trailing commas for multi-line structures, and descriptive snake_case identifiers; CamelCase is reserved for classes and Qt signal names to match existing QML bindings. Type hints are expected (see `models.py` and `AppController`), and new modules should expose a top-level `log = logging.getLogger(__name__)`. Format with Black and lint with Ruff before opening a pull request.
+
+## Testing Guidelines
+Cover every new branch in `imaging/` or `io/` with focused `pytest` cases located beside the existing `test_*.py` files. Mock filesystem and Qt dependencies so tests stay deterministic, and mark anything that performs long disk scans as `pytest.mark.slow`. When adding heuristics that affect performance, pair the change with an updated benchmark script or a note explaining how to validate throughput.
+
+## Commit & Pull Request Guidelines
+Commit subjects follow the observed pattern `Release vX.Y - short result`; use the same `<feature> - <impact>` style even for smaller changes, and keep bodies succinct bullet lists of rationale or testing. Pull requests need: a one- or two-sentence summary, reproduction or validation steps (including `pytest` output), and screenshots/GIFs whenever UI behavior changes. Link issue IDs or TODO references directly so reviewers can trace intent, and never request review until `pytest tests/` passes locally.
+
+## Security & Configuration Tips
+Avoid committing personal state from `faststack.json`, local benchmarking output, or debug captures. Document any new INI key in `config.py`, prefer relative paths, and treat drag-and-drop helpers like `make_hdrop` as security-sensitive—validate all user-supplied paths before invoking external tools such as Helicon Focus.