Simplify README
This commit is contained in:
parent
4d1b97f196
commit
91cc96a631
127
README.md
127
README.md
|
|
@ -1,118 +1,69 @@
|
||||||
# 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 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.
|
||||||
|
|
||||||
---
|
## Kurzüberblick
|
||||||
|
|
||||||
## Features
|
- 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.
|
||||||
|
|
||||||
- 🎯 **Configurable hue detection** – adjust hue, saturation, and value windows or pick colours directly from the image/preset swatches.
|
## Voraussetzungen
|
||||||
- 🪟 **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`)
|
- Pillow (`pip install pillow`)
|
||||||
|
|
||||||
### Installation
|
## Schnellstart
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
git clone https://github.com/<your-org>/ColorCalc.git
|
git clone https://github.com/<dein-org>/ColorCalc.git
|
||||||
cd ColorCalc
|
cd ColorCalc
|
||||||
python3 -m venv .venv
|
python3 -m venv .venv
|
||||||
source .venv/bin/activate # Windows: .venv\Scripts\activate
|
source .venv/bin/activate # Windows: .venv\Scripts\activate
|
||||||
pip install -r requirements.txt # or pip install pillow
|
pip install pillow
|
||||||
```
|
|
||||||
|
|
||||||
### Launch
|
|
||||||
|
|
||||||
```bash
|
|
||||||
python3 main.py
|
python3 main.py
|
||||||
```
|
```
|
||||||
|
|
||||||
The window opens maximized; load an image, tweak sliders, and watch the overlay update in real time.
|
## Bedienung
|
||||||
|
|
||||||
---
|
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 (`🔄`).
|
||||||
|
|
||||||
## Usage Tips
|
## Konfiguration
|
||||||
|
|
||||||
- **Pick colours quickly:** use the 🎨 button to open a colour chooser or click directly inside the left preview (enable 🖱️ first).
|
`config.toml` (optional) mit Default-Werten:
|
||||||
- **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
|
```toml
|
||||||
[defaults]
|
[defaults]
|
||||||
hue_min = 250.0 # 0..360°
|
hue_min = 250.0
|
||||||
hue_max = 310.0
|
hue_max = 310.0
|
||||||
sat_min = 15.0 # percentage 0..100
|
sat_min = 15.0
|
||||||
val_min = 15.0
|
val_min = 15.0
|
||||||
val_max = 100.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).
|
## Code-Struktur
|
||||||
|
|
||||||
---
|
```
|
||||||
|
app/
|
||||||
|
app.py # App-Zusammenbau
|
||||||
|
gui/ # UI-, Theme- und Picker-Mixeins
|
||||||
|
logic/ # Bildverarbeitung, Defaults, Reset
|
||||||
|
config.toml # optionale Startwerte
|
||||||
|
main.py # Einstiegspunkt
|
||||||
|
```
|
||||||
|
|
||||||
## Development Workflow
|
## Pflege
|
||||||
|
|
||||||
- Format: project sticks to standard Python style; no formatter enforced.
|
- Schneller Check: `python3 -m compileall app main.py`
|
||||||
- Testing: primary quick check is compilation via `python3 -m compileall app main.py`.
|
- Pull Requests gerne mit kurzem Screenshot bei UI-Änderungen
|
||||||
- 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.
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue