From e3c3fc72549258bace94f4508d108308cce552e6 Mon Sep 17 00:00:00 2001 From: lm Date: Fri, 17 Oct 2025 08:55:17 +0200 Subject: [PATCH] Rewrite README with concise English overview --- README.md | 129 ++++++++++++++---------------------------------------- 1 file changed, 34 insertions(+), 95 deletions(-) diff --git a/README.md b/README.md index 4193d0a..6e39fe9 100644 --- a/README.md +++ b/README.md @@ -1,118 +1,57 @@ -# ColorCalc – Interactive Colour Range Analyzer +# ColorCalc -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. - ---- +ColorCalc is a small Tkinter tool for analysing colour ranges in images. You load a picture, pick or click a reference colour, adjust hue/saturation/value sliders, and the app marks matching pixels while showing quick stats. ## Features +- Two synced previews (original + overlay) +- Hue/Sat/Value sliders with presets and image colour picker +- Exclusion rectangles to ignore regions +- Theme toggle (light/dark) with rounded toolbar buttons +- Quick overlay export (PNG) and optional defaults via `config.toml` -- 🎯 **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`) +## Requirements +- Python 3.11+ (3.10 works with `tomli`) +- Tkinter (install separately on some Linux distros) - Pillow (`pip install pillow`) -### Installation - +## Setup ```bash git clone https://github.com//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 +pip install pillow 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`) +## Workflow +1. Load an image (`πŸ“‚`). +2. Pick a colour (`🎨` dialog, `πŸ–±οΈ` image click, or preset swatch). +3. Fine‑tune sliders; watch the overlay update on the right. +4. Draw exclusions with right drag; reset or save when ready. +## Config Defaults +Optional `config.toml`: ```toml [defaults] -hue_min = 250.0 # 0..360Β° +hue_min = 250.0 hue_max = 310.0 -sat_min = 15.0 # percentage 0..100 +sat_min = 15.0 val_min = 15.0 val_max = 100.0 -alpha = 120 # overlay opacity 0..255 +alpha = 120 ``` -All values are optional; omit them to fall back to built-in defaults. Hue min/max support wrap-around (e.g. 350 to 20). +## Project Layout +``` +app/ + app.py # main app assembly + gui/ # UI, theme, picker mixins + logic/ # image ops, defaults, reset +config.toml # optional defaults +main.py # entry point +``` ---- - -## 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. +## Development +- Quick check: `python3 -m compileall app main.py` +- Contributions welcome; include screenshots for UI tweaks.