diff --git a/CHANGELOG.md b/CHANGELOG.md index cddcb84c828c986fc86514978ec9ba4816e1f8b3..058b31f329f2a63204260566d6d536daff0f4672 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,12 +2,25 @@ ## [Unreleased] - 2024-12-02 +### Enhanced +- **process** + - **Enhancement:** Segmentation correction with additional parameters. + - Added new configuration options: `area_threshold`, `closing_kernel_size`, `aspect_ratio_min`, and `aspect_ratio_max` for improved segmentation correction. + - These changes help in preserving true nodes of Ranvier by filtering based on cluster size and aspect ratio. + - Introduced morphological operations to fill interruptions in nerve segments. + - Updated the function and documentation to reflect these enhancements. + - Overall, this improves the accuracy and reliability of image segmentation results. + ### Refactored - **refactor(image-processing):** Replace cv2 with Tifffile for reading large images to prevent CV_IO_MAX_IMAGE_PIXELS exception with cv2. - Switched from using OpenCV (cv2) to Tifffile for reading images, specifically TIFF files, in the `resize_image` function. - This change was made due to Tifffile's superior capabilities in handling multi-dimensional image data compared to OpenCV. - Removed unnecessary resizing before Ilastik processing to streamline the workflow and avoid redundancy. - The update aims to improve workflow efficiency and maintain image quality handling in microscopy applications. +- **refactor(pipeline):** Using the filename without extension for generating TIFF files. + - This change extracts the base name of the file without its extension when creating output TIFF files. + - Previously, the full path with extension was used, which could lead to redundant extensions in output filenames. + - This update ensures clearer and more concise naming conventions for generated files. ### Added - **feat(image-processing):** Add script for batch processing and resizing images with Ilastik. diff --git a/README.md b/README.md new file mode 100644 index 0000000000000000000000000000000000000000..4bed8b1c7bfe42082feaec174683f8fff786b202 --- /dev/null +++ b/README.md @@ -0,0 +1,173 @@ +# 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.