![OCELOT: diffeOmorphiC rEgistration for voxel-wise anOmaly Tracking](OCELOT.jpg)

# OCELOT
**diffeOmorphiC rEgistration for voxel-wise anOmaly Tracking**

**A tool to generate cohort specific normative PET/CT images and allow comparison with patient PET/CT images.**

## 🖥️ System  Requirements and Suggestions
Depending on the images you are processing (FOV, Spacing, Matrix size), it is recommended to use a system that has at least 64GB of RAM.

It is also HIGHLY suggested to use a system with a recent NVIDIA Graphics card. 

## 🛠 Installation Guide
### Virtual Environment Setup

Creating a virtual environment is highly recommended to avoid any potential conflicts with other Python packages.

- **Windows**:
```bash
python -m venv ocelotz_env
.\ocelotz_env\Scripts\activate
```

- **Linux/Mac**:
```bash
python3 -m venv ocelotz_env
source ocelotz_env/bin/activate
```

### Installing OCELOT

With your virtual environment activated, install OCELOT using pip:

```bash
pip install ocelotz # stable recommended version
```

## 📁 Folder Structure
To start processing data with OCELOT (the stratification pipeline, please see below) a simple folder structure is recommend: 
```
stratification_directory
    ├── Subject_1
    │         ├── CT_FOLDER
    │         │    └── DICOM_FILES.dcm
    │         └── PT_FOLDER
    │              └── DICOM_FILES.dcm
    ├── Subject_2
    │         ├── CT_FOLDER
    │         │    └── DICOM_FILES.dcm
    │         └── PT_FOLDER
    │              └── DICOM_FILES.dcm
    .
    .
    .
    └── Subject_N
              ├── CT_FOLDER
              │    └── DICOM_FILES.dcm 
              └── PT_FOLDER
                   └── DICOM_FILES.dcm
```
The naming of the individual folders does not matter. It is only important that two sets of DICOM files exist within the subject directory: CT and PET.

**Note:** OCELOT might fail if specific header tags are not provided with the PET and CT DICOM files. 

Following the stratification, you can then simply run OCELOT within normalization mode on the resulting stratified directory or compare the build NormDB with an incoming patient.

## 📚 Usage Guide
### Getting started
OCELOT has three modes of operation: stratify, normalize and compare. 
To get an overview of the modes, you can simply do:
```bash
ocelot -h
 ```
To get more information for each mode, you can also do:
```bash
ocelot <mode> -h
 ```
So for example:
```bash
ocelot <stratify> -h
```
This will give you more information on the input parameters of the mode. 

### Stratification
The command structure for stratification is:
```bash
ocelot stratify -dir <directory/of/subject/data>
```
OCELOT will attempt to stratify the given presented subjects in `-dir` based on sex, BMI, age and height, standardize them and copy them into a new directory.

### Template creation
```bash
ocelot normalize -sub-dir <directory/of/stratified/subject/data> -clean-up
```
OCELOT will attempt to normalize all subject in the provided `-sub-dir` and create a NormDB from them, including a reference 
- CT
- PET
- SUV-PET
- STD-SUV-PET

### Subject comparison
```bash
ocelot compare -ref-dir <directory/of/template> -sub-dir <directory/of/stratified/subject/data/to/compare> -clean-up -mask-regions [arms | legs | head]
```
OCELOT will attempt to compare all subjects in the `-sub-dir` to the NormDB in the `-ref-dir`. `-clean-up` is optional and removes all intermediate processing data after OCELOT is done. `-mask-regions` is optional and can be used to ignore regions during comparison.

### Output
OCELOT will generate a folder named `OCELOT` in each directory where the results of each processing pipeline can be found.

## 🐾 OCELOT: A part of the [enhance.pet](https://enhance.pet) community

[![Visit: https://enhance.pet](ENHANCE.gif)](https://enhance.pet)
