100 lines
5.6 KiB
Markdown
100 lines
5.6 KiB
Markdown
<div style="display:flex; gap:16px; align-items:center;">
|
|
<img src="app/assets/logo.png" alt="ICRA" width="140"/>
|
|
<div>
|
|
<strong>Interactive Color Range Analyzer (ICRA)</strong><br/>
|
|
A professional desktop application for high-precision color matching, clustering analysis, and batch statistics generation.
|
|
</div>
|
|
</div>
|
|
|
|
## Features
|
|
- **High-Performance Image Processing:** Native, vectorized NumPy operations for lightning-fast HSV conversion and color matching.
|
|
- **Automatic Background Exclusion:** Intelligently ignores background pixels (configurable in `config.toml`) to ensure they don't interfere with your analysis.
|
|
- **Grouping Score (Clustering):** A high-performance 9x9 box-sum algorithm that rewards solid "splashes" of color and penalizes thin lines or fragmented noise.
|
|
- **Batch Processing & Customizable Export:** Load a folder of images and instantly export `icra_stats.csv` and `icra_settings.json`. Features a dedicated **Weighting Dialog** to customize the impact of each core component, outputting precise percentage-based column headers.
|
|
- **Import/Export Settings:** Save your HSV ranges, exclusion zones, weighting preferences, and custom overlay colors to a JSON file and reload them later for consistent analysis across different sessions.
|
|
- **Eyedropper Tool:** Quickly pick target matching colors directly from the image canvas.
|
|
- **Advanced Selection:** Support for exclusion zones (rectangles and free-draw polygons) overlaid on the image, all dynamically rendered via `QGraphicsView`.
|
|
- **Modern UI & UX:**
|
|
- Drag-and-drop support for files and folders.
|
|
- Custom dark and light themes with native-feeling borderless titlebars.
|
|
- Context-aware hover tooltips across the cleanly categorized menu bar.
|
|
- Window size and position persistence between launches.
|
|
- **Configurable:** Uses `config.toml` to drive everything from overlay matching colors to default sliders and application language (`en`/`de`).
|
|
|
|
## Core Concepts
|
|
|
|
### 1. HSV Color Matching
|
|
Instead of simple RGB, ICRA uses the **HSV (Hue, Saturation, Value)** color space. This allows for more intuitive color selection:
|
|
- **Hue (0-360°):** The base "color" (Red, Green, Blue, etc.).
|
|
- **Saturation (0-100%):** The intensity or "vibrancy".
|
|
- **Value (0-100%):** The brightness.
|
|
Matching is performed by checking if each pixel's HSV values fall within your defined ranges.
|
|
|
|
### 2. Scoring Components
|
|
The **Composite Score** is calculated weighted by your preferences:
|
|
- **Match (Keep):** Percentage of matching pixels *after* excluding your manual shapes and background areas.
|
|
- **Match (All):** Percentage of matching pixels across the entire image.
|
|
- **Brightness Score:** Calculated from the average brightness of the "Keep" areas. If "Prefer Dark" is ON, lower brightness results in a higher score.
|
|
- **Grouping Score:** Uses a 9x9 box-sum density check. Higher values indicate that matching pixels are clustered into solid blocks rather than scattered noise.
|
|
|
|
### 3. Background Filtering
|
|
To ensure accurate statistics, ICRA automatically filters out the image background (e.g., the dark grey/black backdrop in weapon screenshots). These settings are fully configurable in `config.toml`, allowing you to adjust the target color and the tolerance required for exclusion.
|
|
|
|
### 4. Exclusion Zones
|
|
Use the **Exclusion Tool** to draw rectangles or polygons over areas you want to ignore. This is essential for focusing your analysis on specific parts of a complex image while ignoring background noise or irrelevant details.
|
|
|
|
### 5. Configuration (`config.toml`)
|
|
The application is highly customizable via `config.toml`. This file is included in the repository and contains detailed comments explaining each available setting—from default sliders and language selection to UI masking colors and initial background exclusion tolerances.
|
|
|
|
## Typical Workflow
|
|
|
|
1. **Load Data:** Drag and drop a folder or use the `File` menu to load your images.
|
|
2. **Pick Color:** Use the Eyedropper tool to select your target color directly from the image.
|
|
3. **Refine HSV:** Fine-tune the Hue, Saturation, and Value sliders to perfect the mask.
|
|
4. **Draw Exclusions:** Add exclusion shapes to ignore parts of the image that shouldn't be counted.
|
|
5. **Export:** Click `Export Folder Stats`. Define your weights (e.g., prioritize the Grouping Score if you want coherent splashes) and save your results.
|
|
6. **Persistent Settings:** Use `File -> Export Settings` to save your configuration, or `File -> Import Settings` to restore a previous setup.
|
|
|
|
## Requirements
|
|
- Python 3.11+
|
|
- [uv](https://github.com/astral-sh/uv) for dependency management
|
|
- Works across Windows, macOS, and Linux (requires PySide6 and numpy)
|
|
|
|
## Setup with uv
|
|
```bash
|
|
git clone https://git.lukasmahler.de/lm/ICRA.git
|
|
cd ICRA
|
|
uv venv
|
|
source .venv/Scripts/activate # macOS/Linux: source .venv/bin/activate
|
|
uv pip install .
|
|
uv run icra
|
|
```
|
|
|
|
## Running the Test Suite
|
|
The core image processing logic and UI data models are rigorously tested using `pytest`.
|
|
```bash
|
|
uv run pytest tests/ -v
|
|
```
|
|
|
|
## Project Layout
|
|
```
|
|
app/
|
|
assets/ # Icons and branding
|
|
lang/ # Translations (TOML)
|
|
qt/ # UI implementation and NumPy processing
|
|
tests/ # Unit tests for core analysis
|
|
config.toml # User-facing configuration
|
|
main.py # Entry point
|
|
LICENSE # GNU GPLv3 terms
|
|
```
|
|
|
|
## Development
|
|
- **Tests**: Run `uv run pytest tests/ -v` to verify the core logic.
|
|
- **Environment**: Managed via `uv`. Run `uv sync` to ensure your environment matches the lockfile.
|
|
|
|
## Contributing
|
|
Contributions are welcome! Open an issue or submit a pull request.
|
|
|
|
## License
|
|
GPLv3 License. See the LICENSE file for details.
|