Metadata-Version: 2.1
Name: pumaz
Version: 1.3.1
Summary: PUMA (PET Universal Multi-tracer Aligner) is a robust and efficient tool for aligning images from different PET tracers. It leverages advanced diffeomorphic imaging techniques to offer high-precision alignment for multiplexed tracer images. PUMA aims to significantly enhance the accuracy and reproducibility of PET image studies.
Home-page: https://github.com/QIMP-Team/PUMA
Author: Sebastian Gutschmayer, Lalith Kumar Shiyam Sundar
Author-email: Sebastian.Gutschmayer@meduniwien.ac.at, Lalith.shiyamsundar@meduniwien.ac.at
License: GPLv3
Keywords: PET tracer alignment,diffeomorphic imaging,image processing,multiplexed tracers
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Healthcare Industry
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: nibabel~=3.2.2
Requires-Dist: halo~=0.0.31
Requires-Dist: SimpleITK~=2.2.1
Requires-Dist: pydicom~=2.2.2
Requires-Dist: argparse~=1.4.0
Requires-Dist: numpy
Requires-Dist: mpire~=2.3.3
Requires-Dist: openpyxl~=3.0.9
Requires-Dist: matplotlib
Requires-Dist: pyfiglet~=0.8.post1
Requires-Dist: natsort~=8.1.0
Requires-Dist: pillow>=9.2.0
Requires-Dist: colorama~=0.4.6
Requires-Dist: rich
Requires-Dist: pandas
Requires-Dist: dicom2nifti
Requires-Dist: requests
Requires-Dist: moosez
Requires-Dist: halo
Requires-Dist: psutil
Requires-Dist: gputil
Requires-Dist: lionz

![Puma-logo](Images/Puma-logo.png)

## PUMA 1.2 🐾 - Agile. Precision-Driven. Empowering 💪
[![PyPI version](https://img.shields.io/pypi/v/pumaz?color=FF1493&style=flat-square&logo=pypi)](https://pypi.org/project/pumaz/) [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-red.svg?style=flat-square&logo=gnu&color=FF0000)](https://www.gnu.org/licenses/gpl-3.0) [![Monthly Downloads](https://img.shields.io/pypi/dm/pumaz?label=Downloads%20(Monthly)&color=9400D3&style=flat-square&logo=python)](https://pypi.org/project/pumaz/) [![Daily Downloads](https://img.shields.io/pypi/dd/pumaz?label=Downloads%20(Daily)&color=9400D3&style=flat-square&logo=python)](https://pypi.org/project/pumaz/)

Get ready for a leap in the world of Positron Emission Tomography (PET) imaging: introducing PUMA 1.2 🚀

PUMA 1.2 (PET Universal Multi-tracer Aligner) has been crafted with a strong focus on the challenges of clinical PET imaging.

⚡ It's Agile: PUMA operates across all operating systems and architectures, from x86 to ARM64 (Apple Silicon). It has no specific hardware needs, and with the requirement for Python 3.9 or above, PUMA 1.2 is ready to perform anywhere, anytime.

🔍 It's Precision-Driven yet blazingly fast: Built upon the bedrock of nnUNet based MOOSE and advanced diffeomorphic registration techniques from the awesome 'greedy' library, PUMA 1.2 aligns multiplexed tracer images with high precision in less than a heartbeat, clocking in at under one minute, offering unrivaled clarity and accuracy in the diagnosis of patient pathology.

🗝️ It's Empowering: PUMA 1.2 enhances diagnostic capabilities with its multiplexed viewing angles, unlocking a new realm of diagnostic possibilities and empowering clinicians.

Join us on this revolutionary journey with PUMA 1.2.

## Requirements ✅

Before stepping into the future with PUMA 1.2, here's what you need for an optimal experience:

- **Operating System**: Windows, Mac, or Linux - PUMA 1.2 is versatile and works across all these platforms.

- **Memory**: Make sure your system has enough memory (8-16 GB) to run the tasks smoothly.

- **GPU**: You need a cuda enabled GPU (NVIDIA), 8 GB or more!

- **Python**: PUMA 1.2 operates with Python 3.9 or above, staying in line with the latest updates.

Once these specifications are met, you're all set to experience PUMA 1.2's capabilities.

## Installation Guide 🛠️

Installation is a breeze on Windows, Linux, and MacOS. Follow the steps below to start your journey with PUMA 1.2.

### For Linux and MacOS 🐧🍏

1. Create a Python environment named 'puma-env' or as per your preference.
   ```bash
   python3 -m venv puma-env
   ```

2. Activate the environment.
   ```bash
   source puma-env/bin/activate  # for Linux
   source puma-env/bin/activate  # for MacOS
   ```

3. Install PUMA 1.2.
   ```bash
   pip install pumaz
   ```

Congratulations! You're all set to start using PUMA 1.2.

### For Windows 🪟

1. Create a Python environment, e.g., 'puma-env'.
   ```bash
   python -m venv puma-env
   ```

2. Activate the environment.
   ```bash
   .\puma-env\Scripts\activate
   ```

3. Install PUMA 1.2.
   ```bash
   pip install pumaz
   ```

You're now ready to experience the precision and speed of PUMA 1.2.

## Usage Guide 📚

Start your journey with PUMA 1.2 by using our straightforward command-line tool. It requires the directory path containing different tracer images, and each image should be stored in separate folders. Here's how you can get started:

```bash
pumaz -d <path_to_image_dir> -ir <regions to ignore: arms,legs,head,none> -m <optional for a multiplexed RGB image output> -cs <optional for a custom color selection when also -m was passed>
```

- `<path_to_image_dir>` refers to the parent directory containing different tracer images in their respective sub-directories.

- `-ir` specifies the regions to be ignored during registration. If you don't want to ignore any regions, use `none`. If you want to ignore the arms, legs, or head during registration, pass the corresponding regions delimited by a `,`. For example: `-ir head,arms` to ignore the head and arms.

- `-m` will activate the output of a multiplexed RGB image of the combined tracer images.

- `-cs`, when passed along with `-m`, PUMA will ask you to provide a custom order of color channels for the corresponding tracer images. That way, you can freely decide which tracer image is associated with which channel. 
For assistance or additional information, you can always type:

```bash
pumaz -h
```

## Directory Structure and Naming Conventions for PUMA 📂🏷️

PUMA 1.2 requires your data to be structured in a certain way. It supports DICOM directories and NIFTI files. For NIFTI files, users need to ensure that the files are named with the correct modality tag at the start.

### Required Directory Structure 🌳

Here is the directory structure that PUMA 1.2 expects:

```
Parent_Directory
│
└───Tracer1
│   │
│   └───PET_DICOM_Directory or PT_xxxx.nii.gz
│   │
│   └───CT_DICOM_Directory or CT_xxxx.nii.gz
│
└───Tracer2
│   │
│   └───PET_DICOM_Directory or PT_xxxx.nii.gz
│   │
│   └───CT_DICOM_Directory or CT_xxxx.nii.gz
...

└───Tracer3
    │
    └───PET_DICOM_Directory or PT_xxxx.nii.gz
    │
    └───CT_DICOM_Directory or CT_xxxx.nii.gz
```

### Naming Conventions 🏷️

- For DICOM directories, no specific naming is required.
- For NIFTI files, the file should start with the DICOM modality tag (e.g., 'PT_' or 'CT_') followed by the desired name. For example, 'PT_MySample.nii.gz'.

Note: All the PET and CT images related to a tracer should be placed in the same directory named after the tracer.

## A Note on QIMP Python Packages: The 'Z' Factor 📚🚀

All of our Python packages here at QIMP carry a special signature – a distinctive 'Z' at the end of their names. The 'Z' is more than just a letter to us; it's a symbol of our forward-thinking approach and commitment to continuous innovation.

Our PUMA package, for example, is named as 'pumaz', pronounced "puma-see". So, why 'Z'?

Well, in the world of mathematics and science, 'Z' often represents the unknown, the variable that's yet to be discovered, or the final destination in a series. We at QIMP believe in always pushing boundaries, venturing into uncharted territories, and staying on the cutting edge of technology. The 'Z' embodies this philosophy. It represents our constant quest to uncover what lies beyond the known, to explore the undiscovered, and to bring you the future of medical imaging.

Each time you see a 'Z' in one of our package names, be reminded of the spirit of exploration and discovery that drives our work. With QIMP, you're not just installing a package; you're joining us on a journey to the frontiers of medical image processing. Here's to exploring the 'Z' dimension together! 🚀
 
