From 4d1b97f1962faffc7a0533e4e8ab08781fdcf846 Mon Sep 17 00:00:00 2001
From: lm <m@hler.eu>
Date: Wed, 15 Oct 2025 20:22:15 +0200
Subject: [PATCH] Add comprehensive README

---
 README.md | 118 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 117 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 5178ba2..4193d0a 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,118 @@
-# ColorCalc
+# ColorCalc – Interactive Colour Range Analyzer
 
+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.
+
+---
+
+## Features
+
+- 🎯 **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, …).
+
+---
+
+## 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`)
+
+### Installation
+
+```bash
+git clone https://github.com/<your-org>/ColorCalc.git
+cd ColorCalc
+python3 -m venv .venv
+source .venv/bin/activate  # Windows: .venv\Scripts\activate
+pip install -r requirements.txt  # or pip install pillow
+```
+
+### Launch
+
+```bash
+python3 main.py
+```
+
+The window opens maximized; load an image, tweak sliders, and watch the overlay update in real time.
+
+---
+
+## Usage Tips
+
+- **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  # 0..360°
+hue_max = 310.0
+sat_min = 15.0   # percentage 0..100
+val_min = 15.0
+val_max = 100.0
+alpha = 120      # overlay opacity 0..255
+```
+
+All values are optional; omit them to fall back to built-in defaults. Hue min/max support wrap-around (e.g. 350 to 20).
+
+---
+
+## Development Workflow
+
+- 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.
+
+---
+
+## 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.