From 635b65b7e119d9dda6ad112fc5d9b7b2a850a9a2 Mon Sep 17 00:00:00 2001 From: lukas Date: Tue, 10 Mar 2026 16:56:01 +0100 Subject: [PATCH] Docs: rewrite README.md for complete PySide6 transition --- README.md | 52 +++++++++++++++++++++++++++++----------------------- 1 file changed, 29 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 0c4e604..89443fc 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,29 @@
ICRA
- Interactive Color Range Analyzer is being reimagined with a PySide6 user interface.
- This branch focuses on building a native desktop shell with modern window controls before porting the color-analysis features. + Interactive Color Range Analyzer (ICRA)
+ A fully-featured, PySide6-powered desktop application for precise color matching, image analysis, and statistics generation.
-## Current prototype -- Custom frameless window with minimise / maximise / close controls that hook into Windows natively -- Dark themed layout and basic image preview powered by Qt -- “Open image” workflow that displays the selected asset scaled to the viewport - -> ⚠️ Legacy Tk features (sliders, exclusions, folder navigation, stats) are not wired up yet. The goal here is to validate the PySide6 shell first. +## Features +- **High-Performance Image Processing:** Native, vectorized NumPy operations for lightning-fast HSV conversion and color matching. +- **Batch Folder Processing:** Load a folder of images and instantly export an aggregated `icra_stats.csv` with localized formatting (dot or comma decimals depending on your language). +- **Eyedropper Tool:** Quickly pick target matching colors directly from the image canvas. +- **Advanced Selection:** Support for exclusion zones (rectangles and free-draw polygons) overlaid on the image, all dynamically rendered via `QGraphicsView`. +- **Modern UI & UX:** + - Drag-and-drop support for files and folders. + - Custom dark and light themes with native-feeling borderless titlebars and a categorized menu bar. + - Window size and position persistence between launches. + - Keyboard shortcuts for rapid workflow. +- **Configurable:** Uses `config.toml` to drive everything from overlay matching colors to default sliders and application language (`en`/`de`). ## Requirements - Python 3.11+ - [uv](https://github.com/astral-sh/uv) for dependency management -- Windows 10/11 recommended (PySide6 build included; Linux/macOS should work but are untested in this branch) +- Works across Windows, macOS, and Linux (requires PySide6 and numpy) -## Setup with uv (PowerShell example) +## Setup with uv ```bash git clone https://git.lukasmahler.de/lm/ICRA.git cd ICRA @@ -28,24 +33,25 @@ uv pip install . uv run icra ``` -The app launches directly as a PySide6 GUI—no browser or local web server involved. Use the “Open Image…” button to load a file and test resizing/snap behaviour. +## Running the Test Suite +The core image processing logic and UI data models are rigorously tested using `pytest`. +```bash +uv run pytest tests/ -v +``` -## Roadmap (branch scope) -1. Port hue/saturation/value controls to Qt widgets -2. Re-implement exclusion drawing using QPainter overlays -3. Integrate existing image-processing logic (`app/logic`) with the new UI - -## Project layout +## Project Layout ``` app/ assets/ # Shared branding - gui/, logic/ # Legacy Tk code kept for reference - qt/ # New PySide6 implementation (main_window, app bootstrap) -config.toml # Historical defaults (unused in the prototype) + lang/ # Localization strings (TOML format) + logic/ # Configuration loading and application constants + qt/ # PySide6 implementation (main_window, custom UI widgets, vectorized image processing) +tests/ # Pytest unit tests +config.toml # Configurable overlay colors, slider defaults main.py # Entry point -> PySide6 launcher ``` -## Development notes +## Development Notes +- The legacy `Tkinter` codebase has been completely removed in favor of `PySide6`. - Quick syntax check: `uv run python -m compileall app main.py` -- Uploaded images are not persisted; the preview uses Qt pixmaps only. -- Contributions welcome—please target this branch with PySide6-specific improvements. +- Contributions welcome!