roi2bb 0.1.0

3D Slicer ROI to YOLO Bounding Box Coordinates Converter for Medical Imaging

roi2bb

"3D Slicer ROI" to "YOLO Bounding Box" Coordinates Converter for Medical Imaging

This repository provides a Python class, roi2bb, bridging the gap between ground truth preparation and model training for 3D volumetric medical imaging, by converting Regions of Interest (ROI) bounding boxes stored in 3D Slicer JSON format into YOLO models input format.

When it comes to volumetric medical imaging data, there are few tools (if any) available for 3D bounding box annotation. 3D Slicer is a robust open-source tool for all types of data visualization, processing and annotation. 3D Slicer's ROI function of markups module, offers a user-friendly interface to generate 3D bounding boxes around the object/region of interest, edit and rotate them in axial, coronal and sagittal planes for object-oriented tasks and visualize them in 3D view. The central coordinates and the dimensions of these ROI boxes can be extracted as a JSON file, but the output is not compatible with the "Image coordinates System", which is the format compatible with the well-known YOLO family of deep learning models.

These two coordinate systems have 3 main differences that should be addressed while converting:

1. The Slicer output follows the "Patient coordinate system", in which its origin is located at an anatomical landmark not necessarily in the image boundaries, while the YOLO-compatible input format is based on the "Image coordinate system", in which its origin is located at the upper-left corner of the image. Also, the axis directions are not the same in different coordinate systems, changing the point coordinate values.

2. The Slicer format dimensions are the actual ROI dimensions, while the Yolo format dimensions are a ratio of ROI dimension to image dimensions.

3. The Slicer output is in JSON format with the ROI 'center' coordinates (x,y,z) and ROI dimensions 'size' (x_length, y_length,z_length) reported under 'markups' tag, while YOLO-compatible input is a text file with each line presenting one ROI containing:

   "class center_z center_x center_y width height depth"

   The Slicer gives a separate JSON file for each ROI, while a single YOLO text file contains multiple ROIs for multiple classes, each class defined by a unique index and each ROI reported in a separate line.

roi2bb offers CLI support for single annotations and python API for several images and multi-class annotations.

Table of Contents:

• Requirements
• Installation
  • Directory Structure
  • Class Index Mapping
  • Example Usage
• License
• Useful Links

Requirements:

• Python 3.x
• os
• glob
• numpy
• json
• argparse
• nibabel/pydicom/PIL/cv2/SimpleITK #depending on your images format

Installation

pip install roi2bb

or

Simply download the roi2bb repository from the upper-right "Code" button dropdown menu, navigate to the roi2bb folder, organize your data to be compatible with the tool (see Directory Structure).

Here is a stepwise guide to use roi2bb:

Directory Structure:

Since, yolo text format contains all classes and all labels per class in a single file, roi2bb has to process the whole directory of all annotations at once. roi2bb expects the below structure for images and labels. It automatically defines unique class IDs (1,2,3) by mapping the unique classes detected in JSON file names. You can also define your desired mapping using the Python API.

project_directory/
├── images/
│   ├── Patient_001.nii or .nii.gz
│   ├── Patient_002.nii
│   │──...
├── labels/
│   ├── Patient_001/
│   │   ├── left_atrium.json
│   │   ├── lymph_node_1.json
│   │   ├── lymph_node_2.json
│   │   ├── lymph_node_3.json
│   │   └── trachea.json
│   ├── Patient_002/
│   │   ├── left_atrium.json
│   │   ├── lymph_node.json
│   │   └── trachea.json
│   │── ...
|   └── Patient_n
└── output/
    │── Patient_001.txt
    │── Patient_002.txt
    |── ...
    └── Patient_n

Class Index Mapping:

converter = roi2bb("path_to_image_file.nii", "path_to_json_folder", "output_yolo_format.txt", class_map:dic = class_map)

class_map = {
    "left_atrium": 1,
    "lymph_node": 2,
    "trachea": 3,
    ...
    }

Example Usage:

Now that you downloaded the repository, organized your data and customized your labels, you can use the following commands in a command line interface (CLI) or the next one in a Python interface to convert ROIs to YOLO format by roi2bb:

CLI

roi2bb example.nii.gz annotations/ output.txt

Python API

from roi2bb.converter import Converter

image_files_list = Path to the medical images
json_folders_list = Folders containing the 3D Slicer JSON annotation files corresponding to ptient_n
output_files_list = Path to save the .txt outputs containing YOLO format annotations

for image_file_path, json_folder_path, output_file_path in zip(image_files_list, json_folders_list, output_files_list)
    converter = Converter(image_file_path, json_folder_path, output_file_path)
    converter.run()

Example Output:

0 0.523 0.312 0.532 0.128 0.276 0.345  # left_atrium
1 0.734 0.512 0.723 0.132 0.254 0.367  # lymph_node_1
1 0.834 0.612 0.823 0.152 0.274 0.447  # lymph_node_2
2 0.634 0.412 0.623 0.112 0.234 0.287  # trachea

License:

roi2bb is released under the MIT License. See the LICENSE file for more details.

Useful Links

3D Slicer web page for volumetric medical imaging annotation

Learn more about the coordinates systems

Contact:

Developer: Elham Mahmoudi

Email: [e-mail]

GitHub: https://github.com/elimah91/roi2bb