119 lines
4.5 KiB
Markdown
119 lines
4.5 KiB
Markdown
# 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.
|