🐦 CROW - Color Reveal Of Wings

CROW (Color Reveal Of Wings) is an image processing tool that reveals the hidden iridescent colors in crow feathers and other birds with apparently black plumage, and more.

📑 Table of Contents

• About
• Example Results
• Features
• Processing Methods
• Installation
• Usage
• CLI Options
• Supported Image Formats
• Tips for Best Results
• Quick Testing Example
• Interpreting Results
• Scientific Background
• Known Issues
• Contributing
• Testing
• License
• Acknowledgments

🎨 About

Where it started

Crow feathers aren't actually black! When viewed from certain angles, they have an iridescent appearance, similar to oil slicks, with reflections of blue, green, violet, and purple. This tool uses 5 different image processing methods to highlight these subtle colors.

Why it started

Colors are very important to me, and seeing some crows in broad daylight, I've noticed subtle changes in the hue of their feathers, indicating that they might actually not be black at all.

Which led to this proof of concept tool, that basically enhances the subtleties of material coloring, bringing some of the invisible (to us) into view.

This tool, however, could also be called CROM (Color Reveal Of Matter), as it was proven by some of the samples in the input folder.

The iron pan, for instance, is red which is strange, but iron oxyde is also red, which makes this interesting.

📸 Example Results

The image above shows the original (top left), the 5 processing methods, and the final CROW composite image (row 3). Notice how the hidden iridescent colors become visible!

Please see the examples folder for some more samples.

✨ Features

• 5 different processing methods for color enhancement
• Intelligent composite image - combines the best results and applies generic color to areas without detected color
• Multi-threaded parallel processing - fast processing using concurrent execution
• Batch processing - process multiple images simultaneously
• Complete comparison grid - visualize the original, all methods, and the final result in a single image
• Automatic bird detection - identifies the bird shape and processes only the relevant area
• Simple CLI - easy to use from the command line with flexible performance options

🔧 Processing Methods

1. HSV Amplification - Amplifies saturation and brightness based on original black intensity
2. Lab Enhancement - Uses Lab color space for improved perception, optimized for full spectrum
3. Multi-Scale Retinex - Highlights color details at 4 different scales (15, 50, 120, 250)
4. Spectral Enhancement - Analyzes and amplifies all color channels (R, G, B)
5. Edge-Aware Color Boost - Preserves feather structure using Canny edge detection

CROW Composite Image

After applying the 5 methods, CROW creates a final composite image that:

• Selects the most colorful pixels from each method based on saturation and brightness
• Calculates the average color of the object from all detected colored pixels
• Applies this generic color to areas without color (white, gray, black)
• Modulates color intensity based on the original's darkness for naturalness
• Combines the colored bird with the unchanged original background

📦 Installation

# Clone the repository
git clone https://github.com/robintel/crow.git
cd crow

# Install dependencies
pip install -r requirements.txt

🚀 Usage

Single Image Processing

python crow_color_analyzer.py -i crow.jpg

This will create an output/ directory with:

• 5 processed images (one for each method) - optional
• Final CROW composite image (colored bird on original background)
• A comparison grid with the original, all methods, and the final result
• Detected bird mask (for debugging)

Batch Processing (directory of images)

# Process all sample images in parallel (may take a while for large images)
python crow_color_analyzer.py -i input/ -o output/

Note: Batch processing uses parallel execution by default for faster results. Processing large images may take some time, especially when processing multiple images simultaneously.

Advanced Options

# Only comparison grid (without individual results)
python crow_color_analyzer.py -i crow.jpg --no-individual

# Only individual results (without comparison grid)
python crow_color_analyzer.py -i crow.jpg --no-comparison

# Specify output directory
python crow_color_analyzer.py -i crow.jpg -o crow_results/

📋 CLI Options

-i, --input              Path to input image or directory (required)
-o, --output             Output directory for results (default: output/)
--no-individual          Don't save individual method results
--no-comparison          Don't create comparison grid
--no-composite           Don't save final composite image
--no-parallel            Disable all parallel processing
--no-parallel-methods    Disable parallel processing of methods
--no-parallel-images     Disable parallel processing of batch images
-j, --jobs N             Number of parallel workers for batch (default: CPU count)
-h, --help              Show help

Performance Options

CROW supports multi-threaded parallel processing for faster results:

• Parallel Methods: All 5 processing methods run simultaneously (enabled by default)
• Parallel Batch: Multiple images processed at once in batch mode (enabled by default)
• Control Workers: Use -j N to limit parallel workers (useful for memory management)

Examples:

# Default: full parallel processing
python crow_color_analyzer.py -i images/

# Limit to 4 parallel image workers
python crow_color_analyzer.py -i images/ -j 4

# Disable all parallel processing
python crow_color_analyzer.py -i images/ --no-parallel

# Sequential methods, parallel images
python crow_color_analyzer.py -i images/ --no-parallel-methods

🖼️ Supported Image Formats

• JPEG (.jpg, .jpeg)
• PNG (.png)
• BMP (.bmp)
• TIFF (.tiff)
• WebP (.webp)
• AVIF (.avif)

💡 Tips for Best Results

1. Use high-quality images - the higher the resolution, the more visible the color details will be
2. Good lighting - images taken in natural light work best
3. Feather details - images with clear feather details will produce better results
4. Experiment - different methods work better for different images

🧪 Quick Testing Example

The repository includes sample images for quick testing:

# Process sample image 1 (CC BY 2.0 by Ian Kirk)
python crow_color_analyzer.py -i input/1.jpeg

# Check results in output directory
ls output/

# Process sample image 2 (higher resolution, CC BY 4.0 by Alexis Lours)
python crow_color_analyzer.py -i input/2.jpeg

Note: Sample images have their own licenses. See CREDITS.md for full attribution.

Or create a synthetic test image:

# Create a synthetic test image
python test_crow.py

# Process the test image
python crow_color_analyzer.py -i test_crow_image.png

📊 Interpreting Results

Each method highlights colors differently:

• Method 1 (HSV Amplification): Most natural, maintains original hue and amplifies saturation based on darkness
• Method 2 (Lab Enhancement): Improved perception, good for full color spectrum
• Method 3 (Multi-Scale Retinex): More dramatic, highlights subtle contrasts at multiple scales
• Method 4 (Spectral Enhancement): Most aggressive, amplifies all RGB channels independently
• Method 5 (Edge-Aware): Preserves feather structure, ideal for fine details

The CROW composite image combines the best aspects from all methods:

• Automatically selects the most colorful pixels from each method
• Applies the detected average color to areas without color (white/gray)
• Results in the most complete and consistent representation of iridescent colors

Compare all methods and the final result in the comparison grid!

🔬 Scientific Background

Iridescence in bird feathers is caused by the microscopic structure of feathers, which creates optical interference. The colors we see depend on:

• Viewing angle
• Type of lighting
• Structure of melanosomes in feathers

CROW uses advanced image processing techniques to amplify these subtle color variations, making them visible to the human eye.

Technical Methods

CROW implements several established computer vision algorithms:

• HSV Color Space Manipulation - for intuitive color enhancement
• CIELAB Color Space - for perceptually uniform color processing
• Multi-Scale Retinex (MSR) - based on human visual perception theory
• Spectral Channel Enhancement - independent RGB amplification
• Canny Edge Detection - for structure-preserving enhancement
• Morphological Operations - for bird mask detection

For detailed references and academic citations, see CREDITS.md.

🐛 Known Issues

• Very large images may require longer processing time
• Some methods may create artifacts on images with high noise
• WebP is supported through OpenCV (ensure you have OpenCV installed with WebP support)

🤝 Contributing

Contributions are welcome! If you have ideas for new processing methods or improvements:

1. Fork the repository
2. Create a branch for your feature (git checkout -b feature/NewMethod)
3. Commit your changes (git commit -m 'Add new processing method')
4. Push to branch (git push origin feature/NewMethod)
5. Open a Pull Request

🧪 Testing

CROW includes a comprehensive test suite with 31 unit tests covering all functionality, including combinatorial tests for command line arguments.

Running Tests

Basic test run:

python test_crow_color_analyzer.py

Verbose output (shows each test):

python test_crow_color_analyzer.py -v

Using unittest module:

python -m unittest test_crow_color_analyzer -v

Run specific test classes:

# Run only CLI argument tests
python -m unittest test_crow_color_analyzer.TestCommandLineArguments

# Run only batch processing tests
python -m unittest test_crow_color_analyzer.TestBatchProcessing

Run a specific test:

python -m unittest test_crow_color_analyzer.TestCommandLineArguments.test_cli_combo_1_all_outputs_sequential

Test Coverage

The test suite includes:

• Core functionality tests - All 5 processing methods, image loading, mask detection, composite creation
• Batch processing tests - Sequential and parallel batch processing
• Image format tests - JPEG, PNG format support
• CLI argument tests - 14 combinatorial tests using pairwise testing methodology

Combinatorial Testing: The CLI tests use pairwise (2-way) combinatorial testing to efficiently test all command line option combinations. This approach tests every pair of options at least once, catching most bugs with minimal test cases (14 tests instead of 32 full combinations).

Options tested:

• --no-individual (save/skip individual method results)
• --no-comparison (save/skip comparison grid)
• --no-composite (save/skip composite image)
• --no-parallel-methods (parallel/sequential method processing)
• --no-parallel-images (parallel/sequential batch processing)
• Custom output directories
• Edge cases (no outputs requested)

Test Results

All tests should pass:

Ran 31 tests in ~2s

OK

If any tests fail, please open an issue with the test output.

📝 License

Software License: This project is licensed under the CC BY-NC-SA 4.0 (Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International) - see the LICENSE file for details.

Sample Images: Sample images in the input/ directory have their own licenses - see CREDITS.md for detailed attribution and licensing information for each image. These images are provided as examples only and are not part of the software license.

TL;DR:

• ✅ Free for personal, educational, and research use
• ✅ Must provide attribution (credit to Robin Molnar)
• ✅ Modifications must be shared under the same license
• ❌ Commercial use requires permission - contact @robintel for licensing

This license ensures that corporations cannot take this work without contributing back to the community, like some big trillion-dollar corporation abused FFmpeg by bombarding them with bugs and notices to fix them in 30 days, instead of contributing fixes. This is not how it works, this is not how Open Source is supposed to work.

🙏 Acknowledgments

Inspired by my fascination with hidden colors in nature and the intelligent behavior of crows, and driven by the realization that the world is getting a whole lot less colorful, as confirmed by this stody by the Science Museum Group in the UK.

Image Credits

Sample images used in this repository are credited in CREDITS.md:

• input/1.jpeg - By Ian Kirk, licensed under CC BY 2.0 from Wikimedia Commons
• input/2.jpeg - By Alexis Lours, licensed under CC BY 4.0 from Wikimedia Commons
• input/3.jpeg - "Lilith" by DrL, licensed under CC BY-SA 2.5 from Wikimedia Commons
• input/4.jpeg - By GALAXY 2018 A7, released into Public Domain (CC0 1.0)
• input/5.jpeg - By Lotusgreen, licensed under CC BY-SA 4.0 from Wikimedia Commons
• input/6.jpeg - By Amcyrus2012, licensed under CC BY 4.0 from Wikimedia Commons
• input/7.jpeg - By Evan-Amos, released into Public Domain

Thank you to all photographers who share their work under open licenses!

---

Made in the 🇪🇺 European Union with ❤️ for bird lovers and hidden colors.

If CROW was useful to you, leave a ⭐ on GitHub!

P.S. Did I mention that I ❤️ the 🇪🇺? Yes, I ❤️ the 🇪🇺 because we are preserving colors, nature, culture and all the good stuff that makes life worth living.