<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.
- **Import/Export Settings:** Save your HSV ranges, exclusion zones, and weighting preferences 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 and a categorized menu bar.
  - Window size and position persistence between launches.
  - Keyboard shortcuts for rapid workflow.
- **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.

## 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.