4.5 KiB

Raw Blame History

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

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

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`)

[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

Fork + clone.
Create a feature branch.
Make changes and run python3 -m compileall app main.py.
Submit a PR with a clear description and screenshots if UI changes are visible.

4.5 KiB Raw Blame History Unescape Escape