# Automated CZI to Ilastik Processing Pipeline

### Author: Pierre Tocquin (University of Liège)

---

## Overview

This script automates the processing of microscopy images in the CZI format. It provides functionalities to:
- Convert CZI files into mosaics stored as TIFF files.
- Perform segmentation of the mosaics using **Ilastik** in headless mode.
- Correct segmentation issues, including:
  - Identifying and preserving true nodes of Ranvier based on size and shape.
  - Filling interruptions in nerve segments caused by gaps in segmentation.
  - Applying morphological operations to refine segmentation results.
- Resize both original and segmented outputs for downstream analysis.
- Optimize disk usage by removing intermediate files.

---

## Features

1. **Mosaic Assembly**: Converts tiled CZI images into complete mosaics stored as TIFF files.
2. **Segmentation**: Leverages Ilastik for pixel classification in headless mode.
3. **Segmentation Correction**:
   - Preserves true nodes of Ranvier based on cluster size and aspect ratio.
   - Removes thin or irregular structures via morphological operations.
   - Fills white gaps in blue regions (nerve interruptions).
4. **Resizing**: Scales the original and segmented images according to user-defined factors.
5. **Intermediate File Cleanup**: Removes intermediate TIFF files to save disk space.

---

## Dependencies

### Python Libraries:
- [PyYAML](https://pyyaml.org/): For reading the YAML configuration file.
  ```bash
  pip install pyyaml
  ```
- [aicspylibczi](https://pypi.org/project/aicspylibczi/): For handling CZI files.
  ```bash
  pip install aicspylibczi
  ```
- [tifffile](https://pypi.org/project/tifffile/): For managing TIFF files.
  ```bash
  pip install tifffile
  ```
- [OpenCV](https://opencv.org/): For image resizing and morphological operations.
  ```bash
  pip install opencv-python-headless
  ```

### Ilastik:
- Ilastik must be installed for pixel classification in headless mode.
- [Download Ilastik](https://www.ilastik.org/download.html).

---

## Setup

### Clone the repository:
```bash
git clone <repository-url>
cd <repository-directory>
```

### Install dependencies:
```bash
pip install -r requirements.txt
```
*(Alternatively, install the dependencies manually as listed above.)*

### Prepare the configuration file:
Create or edit a YAML file (e.g., `config.yaml`) with the following parameters:
```yaml
output_dir: ./output
compression: lzw
resize_factor: 0.25
project: /path/to/ilastik_project.ilp
ilastik: /path/to/ilastik_executable
area_threshold: 50
closing_kernel_size: 11
aspect_ratio_min: 1.5
aspect_ratio_max: 5
```

---

## Usage

Run the script with the following command:

```bash
python process_pipeline.py file1.czi file2.czi ... --config /path/to/config.yaml
```

### Command-Line Arguments:
- `file1.czi file2.czi ...`: List of CZI files to process.
- `--config /path/to/config.yaml`: Path to the configuration file.

### Example:
```bash
python process_pipeline.py sample1.czi sample2.czi --config config.yaml
```

---

## How It Works

1. **CZI File Processing**:
   - The script reads tiled data from the CZI file and assembles it into a mosaic saved as a TIFF.

2. **Segmentation**:
   - The mosaic is passed to Ilastik in headless mode for segmentation.

3. **Segmentation Correction**:
   - **Red Cluster Filtering**: Red clusters (representing nodes of Ranvier) are identified based on:
     - Minimum area (`area_threshold`).
     - Aspect ratio (`aspect_ratio_min`, `aspect_ratio_max`).
   - **Morphological Refinement**:
     - Thin structures are removed using erosion + dilation.
     - Interruptions in nerve segments are filled with morphological closing.

4. **Image Resizing**:
   - Both the original mosaic and segmented outputs are resized using a scaling factor (`resize_factor`).

5. **Intermediate File Cleanup**:
   - Intermediate TIFF files are removed to save disk space.

---

## Configuration Parameters

| Parameter            | Description                                                                 | Example                |
|----------------------|-----------------------------------------------------------------------------|------------------------|
| `output_dir`         | Directory where processed files are saved.                                 | `./output`            |
| `compression`        | Compression type for TIFF files.                                           | `lzw`                 |
| `resize_factor`      | Scaling factor for resizing images.                                        | `0.25`                |
| `project`            | Path to the Ilastik project file (`.ilp`).                                 | `/path/to/project.ilp`|
| `ilastik`            | Path to the Ilastik executable.                                            | `/path/to/ilastik`    |
| `area_threshold`     | Minimum size of red clusters (nodes of Ranvier).                           | `50`                  |
| `closing_kernel_size`| Kernel size for filling interruptions in blue regions (nerve segments).    | `11`                  |
| `aspect_ratio_min`   | Minimum aspect ratio for identifying true nodes of Ranvier.                | `1.5`                 |
| `aspect_ratio_max`   | Maximum aspect ratio for identifying true nodes of Ranvier.                | `5`                   |

---

## Output Files

- **Original TIFF**: The assembled mosaic from the input CZI file.
- **Segmented TIFF**: The output from Ilastik after pixel classification.
- **Corrected TIFF**: The segmented image after corrections for segmentation issues.
- **Resized TIFFs**: Resized versions of the original and segmented images.

---

## Troubleshooting

1. **Error: Ilastik not found**:
   - Ensure the path to the Ilastik executable is correct in the configuration file.

2. **FileNotFoundError for CZI files**:
   - Verify the input file paths and ensure they exist.

3. **Incorrect segmentation**:
   - Adjust the `area_threshold`, `aspect_ratio_min`, and `aspect_ratio_max` in `config.yaml`.

---

## License

This project is licensed under the MIT License. See the `LICENSE` file for details.