Metadata-Version: 2.4
Name: eari-demosaic
Version: 0.1.2
Summary: EARI image demosaicking implementation
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: numpy>=2.4.4
Requires-Dist: opencv-python>=4.13.0.92
Requires-Dist: scipy>=1.17.1

# pyeari - Polarimetric color demosaicking

A package providing a Python implementation of the EARI (Edge-Aware Residual Interpolation) polarimetric demosaicking algorithm. This package implements two specific methods, MEARI, for Monochrome-Polarization Filter Array  and CEARI, for Color-Polarization Filter Array. A method for the standard color demosaciking residual interpolation, ri, is also provided.

These algorithms are based on the work proposed by Morimatsu et al.. 
> M. Morimatsu, Y. Monno, M. Tanaka, and M. Okutomi, "Monochrome And Color Polarization Demosaicking Using Edge-Aware Residual Interpolation," *2020 IEEE International Conference on Image Processing (ICIP)*, 2020. DOI: [10.1109/ICIP40778.2020.9191085](https://doi.org/10.1109/ICIP40778.2020.9191085)

## Installation

You can install the package directly from [PyPI](https://pypi.org/project/eari-demosaic/):

```bash
pip install eari-demosaic

```

## Dependencies

This package requires the following libraries:

* `numpy`
* `scipy`
* `opencv-python` (cv2)

## Available Functions

### Input & Output Data Formats

* **Input:** Raw image arrays provided to the functions must be either `uint8` (values 0-255) or `float32`.
* **Output:** All demosaicking functions return `float32` arrays strictly clipped to the range of `0` to `1`.

The package exposes the following main functions:

* **`CEARI(CPFA, pattern)`**: A demosaicking function for a Color Polarization Filter Array (CPFA).
* **`MEARI(MPFA)`**: A demosaicking function for a Monochrome Polarization Filter Array (MPFA).
* **`ri(cfa, pattern)`**: Standard color demosaicking using Residual Interpolation.
* **`make_cfa(img_path, pattern)`**: A utility function to generate a simulated Color Filter Array (CFA) from a standard image file.

### Supported Bayer & Polarization Patterns

Functions requiring a `pattern` argument accept the following standard Bayer array strings for color:

* `'RGGB'`
* `'BGGR'`
* `'GRBG'`
* `'GBRG'`

**Supported Polarization Pattern:**
Currently, the algorithms support only one polarization arrangement—the standard 2x2 macro-pixel, multiple color arrengements are supported. When combined with a color filter array, it forms a Color Polarization Filter Array (CPFA).

Here is an example of supported CPFA layouts (showing a **RGGB** and **BGGR**color pattern):

```text
RGGB Pattern                             BGGR Pattern
+-------+-------+-------+-------+      +-------+-------+-------+-------+
|  90°  |  45°  |  90°  |  45°  |      |  90°  |  45°  |  90°  |  45°  |
|   R   |   R   |   G   |   G   |      |   B   |   B   |   G   |   G   |
+-------+-------+-------+-------+      +-------+-------+-------+-------+
| 135°  |   0°  | 135°  |   0°  |      | 135°  |   0°  | 135°  |   0°  |
|   R   |   R   |   G   |   G   |      |   B   |   B   |   G   |   G   |
+-------+-------+-------+-------+      +-------+-------+-------+-------+
|  90°  |  45°  |  90°  |  45°  |      |  90°  |  45°  |  90°  |  45°  |
|   G   |   G   |   B   |   B   |      |   G   |   G   |   R   |   R   |
+-------+-------+-------+-------+      +-------+-------+-------+-------+
| 135°  |   0°  | 135°  |   0°  |      | 135°  |   0°  | 135°  |   0°  |
|   G   |   G   |   B   |   B   |      |   G   |   G   |   R   |   R   |
+-------+-------+-------+-------+      +-------+-------+-------+-------+
```

This specific **RGGB** polarimetric arrangement is the industry standard and is used by the most common polarimetric cameras on the market, such as those based on the **Sony IMX250MYR** (color) and **Sony IMX250MZR** (monochrome) sensors.

---

## Usage Examples

### 1. Color Polarization Demosaicking (CEARI)

The `CEARI` function takes a raw CPFA image and a Bayer pattern string. It standardizes the input automatically and returns four separate RGB images corresponding to the 90°, 0°, 45°, and 135° polarization angles.

```python
import cv2
from pyeari import CEARI

# Load your raw Color Polarization Filter Array image
raw_cpfa = cv2.imread("path_to_raw_image.tif", cv2.IMREAD_UNCHANGED)

# Process the image (assuming an RGGB pattern)
RGB90, RGB00, RGB45, RGB135 = CEARI(raw_cpfa, 'RGGB')

# Save or display the resulting images (converting back to uint8)
cv2.imwrite("output_90.png", RGB90 * 255)

```

### 2. Monochrome Polarization Demosaicking (MEARI)

If you are working with monochrome polarization data, use `MEARI`. It takes an MPFA image and returns the four directional intensity images.

```python
from pyeari import MEARI

# Process the monochrome array
I90, I00, I45, I135 = MEARI(raw_mpfa)

```

### 3. Standard Color Demosaicking (RI)

To perform standard residual interpolation on a normal Color Filter Array, you can use the `ri` function.

```python
from pyeari import ri, make_cfa

# Generate a simulated CFA from a ground-truth image for testing
cfa_image = make_cfa("test_image.png", "RGGB")

# Reconstruct the full RGB image
demosaicked_rgb = ri(cfa_image, "RGGB")

```
