Feature Request: Add RGB Composite Image Creation Functionality to PUMA

Description

The purpose of this feature is to enhance the PUMA toolkit by adding the capability to create composite RGB images from multiple NIfTI files. This feature will allow researchers to blend up to three separate images into a single RGB composite, enhancing the visualization of overlapping anatomical or functional data.

Motivation

Currently, PUMA excels at aligning PET tracer images spatially. The next logical step is to offer a seamless way to visualize these alignments. By introducing an RGB composite creator, users can generate a single image that carries detailed channel-wise information, aiding in more intuitive data interpretation and presentation.

Feature Details

The feature will take two or three NIfTI images as input and generate a composite RGB image.
Each input image will correspond to a specific color channel (Red, Green, Blue).
Normalization and scaling will be performed to ensure that the pixel intensity values are correctly represented.
The output will be a new NIfTI file that can be readily opened in standard imaging viewers.
This feature will be accessible via both a Python API and a command-line interface, increasing the tool's usability in various workflows.

Proposed Function Signature

def blend_images(*image_paths, output_path):
    """
    Blends multiple NIfTI images into a single composite RGB image.

    :param image_paths: Paths to NIfTI images to blend.
    :type image_paths: str
    :param output_path: Path to save the blended composite image.
    :type output_path: str
    """

Use Cases

A researcher wants to overlay a PET image showing metabolic activity with another showing blood flow or PSMA expression. Using this feature, they can easily see areas of overlap and distinction in one composite image.
May be - just may be we can visualise the hallmarks of cancer in a single multiplexed image.

Acceptance Criteria

The feature must support exactly two or three images for blending.
The output must be saved in a valid NIfTI format.
The intensity values must be normalized to a range suitable for RGB representation.
The command-line interface must provide clear error messages for invalid inputs.
Documentation must be provided, including Sphinx-compatible docstrings and a tutorial in the README.

Impact

This feature will significantly expand the visualization capabilities of PUMA, making it a more comprehensive tool for medical image analysis. It will facilitate better data interpretation and enhance the ability to communicate findings visually.

ENHANCE-PET / PUMA