lm
/
ICRA
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
ICRA/README.md

5.6 KiB
Raw Blame History

ICRA
Interactive Color Range Analyzer (ICRA)
A professional desktop application for high-precision color matching, clustering analysis, and batch statistics generation.

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 for dependency management
  • Works across Windows, macOS, and Linux (requires PySide6 and numpy)

Setup with uv

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.

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.