diff --git a/README.md b/README.md index 358ac1a..4193d0a 100644 --- a/README.md +++ b/README.md @@ -1,69 +1,118 @@ -# ColorCalc +# ColorCalc – Interactive Colour Range Analyzer -ColorCalc ist ein kleines Desktop-Tool (Python + Tkinter + Pillow), das Farbbereiche in Bildern markiert. Statt nur eine feste Farbe zu prüfen, kannst du jede gewünschte Hue/Saturation/Value-Kombination einstellen, Ergebnisse sofort sehen und als Overlay speichern. +ColorCalc is a desktop app for Windows/macOS/Linux that helps you identify and highlight colours in images. It is built with Python, Tkinter, and Pillow and is tuned for full‑HD screens. Instead of focusing on a single hue (like purple), you can target any colour range, tweak saturation/value thresholds, and export overlays in seconds. -## Kurzüberblick +--- -- Zwei Vorschaubereiche: links Original, rechts Overlay. -- Slider für Hue-/Sat-/Value-Grenzen und Overlay-Alpha. -- Farbwahl per Dialog, Bildklick oder vordefinierten Swatches. -- Rechteckige Ausschlüsse per Rechtsklick ziehen. -- Light/Dark-Theme, Trefferstatistik und Dateiname im UI. -- Einstellungen aus `config.toml` (optional) laden. +## Features -## Voraussetzungen +- 🎯 **Configurable hue detection** – adjust hue, saturation, and value windows or pick colours directly from the image/preset swatches. +- 🪟 **Responsive dual-preview UI** – original image on the left, processed overlay on the right, sized for 1080p. +- 🖱️ **Interactive masks** – draw exclusion rectangles to ignore specific regions when calculating results. +- 🌗 **Light & dark mode** – rounded toolbar buttons adapt to the current theme; toggle any time. +- 🟨 **Real‑time stats** – centre-aligned labels show match ratios with/without exclusions plus filenames and dimensions. +- 💾 **Overlay export** – save PNG overlays blended with the source image for reporting or further editing. +- ⚙️ **Config file defaults** – populate `config.toml` to ship different starting values across machines. +- 🎨 **Preset palette** – one-click access to common colours (red, cyan, grey, black, …). -- Python ≥ 3.11 (bei 3.10: `pip install tomli`) -- Tkinter (unter Linux ggf. `sudo apt install python3-tk`) +--- + +## Getting Started + +### Requirements + +- Python 3.11+ (includes the standard `tomllib`; for 3.10 install `tomli`) +- Tkinter (ships with most Python distributions; on Linux install `python3-tk`) - Pillow (`pip install pillow`) -## Schnellstart +### Installation ```bash -git clone https://github.com//ColorCalc.git +git clone https://github.com//ColorCalc.git cd ColorCalc python3 -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate -pip install pillow +pip install -r requirements.txt # or pip install pillow +``` + +### Launch + +```bash python3 main.py ``` -## Bedienung +The window opens maximized; load an image, tweak sliders, and watch the overlay update in real time. -1. `📂` Bild laden. -2. Farbe wählen (`🎨` oder `🖱️` aktivieren und ins Bild klicken). -3. Slider nach Bedarf anpassen; Trefferquote erscheint unter dem Overlay. -4. Ausschlüsse mit Rechtsklick ziehen, per `🧹` löschen. -5. Overlay speichern (`💾`) oder Slider zurücksetzen (`🔄`). +--- -## Konfiguration +## Usage Tips -`config.toml` (optional) mit Default-Werten: +- **Pick colours quickly:** use the 🎨 button to open a colour chooser or click directly inside the left preview (enable 🖱️ first). +- **Fine-tune defaults:** edit `config.toml` and set keys under `[defaults]`. Restart the app to apply changes. +- **Reset & compare:** `🔄 Slider zurücksetzen` reverts to defaults and clears the status message. +- **Exclude areas:** right-drag on the original preview to mark rectangles; use `↩️` to undo or `🧹` to clear all. +- **Copy stats:** right-click the filename or ratio labels to copy. +- **Export overlay:** `💾` saves a PNG with your overlay merged onto the source image. +- **Theme switch:** `🌓` toggles between light/dark; button palettes update instantly. + +--- + +## Project Structure + +``` +ColorCalc/ +├── app/ +│ ├── app.py # ColorCalcApp composition root +│ ├── __init__.py # Package exports +│ ├── gui/ +│ │ ├── color_picker.py # Colour selection & presets +│ │ ├── exclusions.py # Exclusion rectangle handlers +│ │ ├── theme.py # Theme detection & style updates +│ │ └── ui.py # Tkinter layout and custom widgets +│ └── logic/ +│ ├── constants.py # Config defaults & preview sizing +│ ├── image_processing.py # Loading, overlay creation, stats +│ └── reset.py # Slider reset mixin +├── config.toml # Default HSV/alpha overrides +├── images/ # Optional sample inputs +└── main.py # CLI entry point (`python3 main.py`) +``` + +--- + +## Configuration (`config.toml`) ```toml [defaults] -hue_min = 250.0 +hue_min = 250.0 # 0..360° hue_max = 310.0 -sat_min = 15.0 +sat_min = 15.0 # percentage 0..100 val_min = 15.0 val_max = 100.0 -alpha = 120 +alpha = 120 # overlay opacity 0..255 ``` -## Code-Struktur +All values are optional; omit them to fall back to built-in defaults. Hue min/max support wrap-around (e.g. 350 to 20). -``` -app/ - app.py # App-Zusammenbau - gui/ # UI-, Theme- und Picker-Mixeins - logic/ # Bildverarbeitung, Defaults, Reset -config.toml # optionale Startwerte -main.py # Einstiegspunkt -``` +--- -## Pflege +## Development Workflow -- Schneller Check: `python3 -m compileall app main.py` -- Pull Requests gerne mit kurzem Screenshot bei UI-Änderungen +- Format: project sticks to standard Python style; no formatter enforced. +- Testing: primary quick check is compilation via `python3 -m compileall app main.py`. +- Platform quirks: some theme detection uses Windows registry; errors are swallowed when unavailable. -Viel Spaß beim Einstellen deiner Farbbereiche! +--- + +## Contributing + +1. Fork + clone. +2. Create a feature branch. +3. Make changes and run `python3 -m compileall app main.py`. +4. Submit a PR with a clear description and screenshots if UI changes are visible. + +--- + +## License + +MIT License © 2024 ColorCalc contributors. See `LICENSE` (add one if missing) for details.