Color Deconvolution Toolkit

Implements the color separation algorithm from Berger et al., "Color Separation in Forensic Image Processing" (2006) for practical forensic and document-analysis workflows. The repository ships a reusable Python module (color_deconvolution.py) plus a PyQt5 desktop application (app) for interactive deconvolution with pixel-level sampling.

Features

• Algorithmically faithful implementation of the Berger et al. method with cached orthonormal bases, numeric guards, and component exports.
• Interactive desktop tool that shows original and processed views side by side, supports magnified sampling, and toggles between cleaned output and component overlays.
• Automated environment bootstrap via setup_and_test.sh, ensuring every run happens inside a virtual environment and the library tests pass.

Quick Start

./setup_and_test.sh --run-app
source .venv/bin/activate
PYTHONPATH=$(pwd) python -m app.main

The helper script creates .venv, installs dependencies, runs the unit tests under tests, byte-compiles color_deconvolution.py and app, and (with --run-app) launches the desktop GUI. After activation, launch the GUI to load an image, pick paper/ink colors, and apply deconvolution.

Library Module

color_deconvolution.py exposes ColorDeconvolution and deconvolve_colors. Highlights:

• Accepts NumPy or PIL inputs with automatic dtype/range handling.
• Provides sampling helpers (set_colors_from_image, sample_color) and safe component visualisation.
• Includes unit tests under tests (run via python -m unittest discover -s tests).

Desktop App (app)

app/main.py is a PyQt5 application that:

• Enforces virtualenv usage before launch.
• Displays original and processed imagery with a live magnifier.
• Lets analysts switch between processed image, cyan/magenta overlay, desired-only, or undesired-only component maps.

Full usage details live in app/README.md.

Repository Layout

.
├── app/                 # PyQt5 desktop client and docs
├── color_deconvolution.py  # Core deconvolution module
├── tests/               # Unit tests
├── setup_and_test.sh    # Bootstrap script (venv, deps, tests)
├── LICENSE              # MIT License
└── README.md            # This file

License

This project is released under the terms of the MIT License.

Citation

If this toolkit supports your research or casework, cite the original paper:

Berger, C. E. H., de Koeijer, J. A., Glas, W., & Madhuizen, H. T. (2006). Color Separation in Forensic Image Processing.

Contributing

Issues and pull requests are welcome. Please run ./setup_and_test.sh --run-app before submitting changes to confirm the library tests pass.