Metadata-Version: 2.4
Name: propix_gui_analysis
Version: 0.1.0
Summary: GUI analysis tools for Propix JSON processing
Author-email: Gaspard Russias <grussias@photonics-open-projects.com>
License: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.23
Requires-Dist: matplotlib>=3.7
Requires-Dist: pillow>=9.0
Requires-Dist: packaging>=23.0
Requires-Dist: python-dateutil>=2.8
Requires-Dist: six>=1.16

# PROPIX GUI Analysis

A lightweight Python library to **load, inspect, summarize, and visualize JSON frames generated by the PROPIX GUI**.

This package is designed to work directly with PROPIX GUI outputs, including:
- RGB images
- Segmentation masks
- Hyperspectral data (wavelengths and spectra)

It provides a clean, NumPy-friendly API for **analysis, debugging, and visualization**.

---

## ✨ Features

- Load PROPIX GUI JSON frames into Python structures
- Decode base64-encoded RGB images and masks
- Normalize and handle multiple segmentation masks
- Visualize:
  - RGB images
  - Masks (overlayed or individual)
  - RGB + masks
  - Spectral curves
  - RGB + masks + spectra (side-by-side)
- Print a **human-readable frame summary**:
  - Image resolution
  - Mask coverage (percentage of pixels)
  - Spectral range
  - Number of spectral bands
  - Spectral resolution (Δλ)

---

## 📦 Installation

```bash
pip install propix_gui_analysis
```

Or for development:

```bash
pip install -e .
```

---

## 🚀 Quick Start

```python
from propix_gui_analysis.propix_json_analysis import (
    load_frame,
    frame_summary,
    plot_rgb,
    plot_rgb_with_masks,
    plot_masks_only,
    plot_spectra,
    plot_frame_rgb_and_spectra,
)

frame = load_frame("frame.json")
frame_summary(frame)
```

---

## 📂 Frame Structure

```python
frame = {
    "frame_id": int,
    "task_finished": bool,

    "rgb": np.ndarray,          # [H, W, 3]
    "masks": List[np.ndarray],  # list of [H, W] masks (values in [0,1])
    "mask_colors": List[List[float]],  # normalized RGBA colors

    "wavelengths": np.ndarray,  # [N]
    "spectra": {
        "values": np.ndarray,   # [num_masks, N]
        "labels": List[str]
    }
}
```

---

## 🖨️ Frame Summary

```python
frame_summary(frame)
```

---

## 📊 Visualization

- `plot_rgb(frame)`
- `plot_rgb_with_masks(frame)`
- `plot_masks_only(frame)`
- `plot_spectra(frame)`
- `plot_frame_rgb_and_spectra(frame)`

---

## 🔬 Spectral Resolution

Defined as the **average wavelength spacing (Δλ)** between consecutive bands.

---

## 🧰 Dependencies

- Python ≥ 3.8
- NumPy
- Pillow
- Matplotlib

---

## 📄 License

MIT License.
