Add a visualization tutorial for 3D detection boxes

detection/luna16_visualization/README.md

@@ -0,0 +1,65 @@
+# Tutorial to visualize 3D (detection) boxes using 3D Slicer
+
+Visualizing box prediction/annotation in 3D medical image detection is not straightforward. To better understand model predictions, we provide a way to further visualize detection results/ground truth using the free and open source software [3D Slicer](https://www.slicer.org/). 3D Slicer enables visualization of 3D images, 3D segmentation masks, and 3D meshes with 3D orthographic views. And we convert 3D box annotations/predictions into meshes that can be visualized by cross-sectional curves in three 2D planes.
+
+## Prerequisite
+
+- The Version of 3D Slicer should be **4.11.20210226** or later.
+- Box information should be stored in a ".json" file. The "data\_sample.json" file is an example. The information of *N* boxes is stored under the key "box" as *N* lists. The six values are the *X*/*Y*/*Z* coordinates of the box center and the box length in the *X*/*Y*/*Z* axes. All the coordinate values are in the world coordinate system.
+
+```
+"box": [
+    [
+        -100.312255859375,
+        67.529541015625,
+        -231.97265625,
+        6.328125,
+        6.328125,
+        6.4453125
+    ],
+    [
+        -19.013427734375,
+        10.576416015625,
+        -48.28125,
+        5.09765625,
+        5.09765625,
+        5.3125
+    ]
+]
+```
+
+## Steps
+
+### 1. Create ".obj" file for predictions/annotation using the "save\_obj.sh" script.
+
+```
+#!/bin/bash
+
+INPUT_DATASET_JSON="./data_sample.json"
+OUTPUT_DIR="./out"
+
+python save_obj.py  --input_dataset_json ${INPUT_DATASET_JSON} \
+                    --output_dir ${OUTPUT_DIR}
+```
+
+### 2. Load the original 3D image and the resulting ".obj" file into 3D Slicer.
+
+Image is visualized in 3 2D planes, while boxes are visualized in 3D space.
+
+![Step 2](figures/step-1.png)
+
+### 3. Opens the "Data" tab for box property editing.
+
+![Step 3](figures/step-2.png)
+
+### 4. Change the box color by double-clicking the color tab (for better visualization).
+
+![Step 3](figures/step-3.png)
+
+### 5. Enable in-plane visibility of the box by selecting the "Visible" option.
+
+The following example shows predicted boxed (red) and ground truth boxes (green).
+
+![Step 4](figures/step-4.png)
+
+After completing these steps, the user can analyze the boxes using 3D Slicer's basic visualization capabilities (e.g., zoom in, zoom out).

detection/luna16_visualization/data_sample.json

@@ -0,0 +1,132 @@
+{
+    "validation": [
+        {
+            "label": [
+                0,
+                0,
+                0,
+                0
+            ],
+            "box": [
+                [
+                    -100.312255859375,
+                    67.529541015625,
+                    -231.97265625,
+                    6.328125,
+                    6.328125,
+                    6.4453125
+                ],
+                [
+                    -19.013427734375,
+                    10.576416015625,
+                    -48.28125,
+                    5.09765625,
+                    5.09765625,
+                    5.3125
+                ],
+                [
+                    -53.027099609375,
+                    -79.863037109375,
+                    -221.640625,
+                    5.2734375,
+                    5.2734375,
+                    5.3125
+                ],
+                [
+                    -19.980224609375,
+                    9.785400390625,
+                    -45.3125,
+                    7.03125,
+                    6.6796875,
+                    6.875
+                ]
+            ],
+            "score": [
+                0.99658203125,
+                0.50146484375,
+                0.05975341796875,
+                0.0325927734375
+            ],
+            "image": "/datasets/1.3.6.1.4.1.14519.5.2.1.6279.6001.108197895896446896160048741492/1.3.6.1.4.1.14519.5.2.1.6279.6001.108197895896446896160048741492.nii.gz"
+        },
+        {
+            "label": [
+                0,
+                0,
+                0,
+                0,
+                0,
+                0,
+                0
+            ],
+            "box": [
+                [
+                    46.05921936035156,
+                    48.53294372558594,
+                    -108.6875,
+                    13.5791015625,
+                    13.623046875,
+                    13.75
+                ],
+                [
+                    36.47914123535156,
+                    76.83372497558594,
+                    -123.3359375,
+                    4.5263671875,
+                    4.482421875,
+                    4.375
+                ],
+                [
+                    37.86341857910156,
+                    0.5886077880859375,
+                    -106.265625,
+                    4.21875,
+                    4.21875,
+                    3.90625
+                ],
+                [
+                    20.351211547851562,
+                    52.53196716308594,
+                    -28.765625,
+                    4.7900390625,
+                    4.74609375,
+                    4.84375
+                ],
+                [
+                    -102.71763610839844,
+                    0.7643890380859375,
+                    -36.9296875,
+                    6.328125,
+                    6.328125,
+                    6.484375
+                ],
+                [
+                    -114.14341735839844,
+                    42.86399841308594,
+                    -116.83203125,
+                    4.5703125,
+                    4.5703125,
+                    4.3359375
+                ],
+                [
+                    -95.59849548339844,
+                    39.69993591308594,
+                    -50.171875,
+                    4.74609375,
+                    4.921875,
+                    4.84375
+                ]
+            ],
+            "score": [
+                0.9990234375,
+                0.92578125,
+                0.89208984375,
+                0.8876953125,
+                0.68994140625,
+                0.08538818359375,
+                0.023101806640625
+            ],
+            "image": "/datasets/1.3.6.1.4.1.14519.5.2.1.6279.6001.109002525524522225658609808059/1.3.6.1.4.1.14519.5.2.1.6279.6001.109002525524522225658609808059.nii.gz"
+        }
+    ]
+}

detection/luna16_visualization/save_obj.py

@@ -0,0 +1,104 @@
+#!/usr/bin/env python
+
+# Copyright 2021 - 2022 MONAI Consortium
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#     http://www.apache.org/licenses/LICENSE-2.0
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import argparse
+import csv
+import json
+import nibabel as nib
+import numpy as np
+import os
+
+
+def save_obj(vertices, faces, filename):
+
+    with open(filename, "w") as f:
+
+        for v in vertices:
+            f.write("v {} {} {}\n".format(*np.array(v)))
+
+        for t in faces:
+            f.write("f {} {} {} {}\n".format(*(np.array(t) + 1)))
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--input_dataset_json",
+        action="store",
+        type=str,
+        required=True,
+    )
+    parser.add_argument(
+        "--output_dir",
+        action="store",
+        type=str,
+        required=True,
+    )
+    args = parser.parse_args()
+
+    if not os.path.exists(args.output_dir):
+        os.makedirs(args.output_dir)
+
+    with open(os.path.join(args.input_dataset_json)) as f:
+        input_dataset = json.load(f)
+
+    for key in input_dataset.keys():
+        section = input_dataset[key]
+
+        for _k in range(len(section)):
+            box_data = section[_k]["box"]
+            box_filename = section[_k]["image"]
+            box_filename = box_filename.split(os.sep)[-1]
+            print("-- {0:d}th case name:".format(_k + 1), box_filename)
+
+            vertices = []
+            faces = []
+            _i = 0
+            for vec in box_data:
+                xmin = vec[0] - 0.5 * vec[3]
+                ymin = vec[1] - 0.5 * vec[4]
+                zmin = vec[2] - 0.5 * vec[5]
+
+                xmax = vec[0] + 0.5 * vec[3]
+                ymax = vec[1] + 0.5 * vec[4]
+                zmax = vec[2] + 0.5 * vec[5]
+
+                vertices += [
+                    (xmax, ymax, zmin),
+                    (xmax, ymin, zmin),
+                    (xmin, ymin, zmin),
+                    (xmin, ymax, zmin),
+                    (xmax, ymax, zmax),
+                    (xmax, ymin, zmax),
+                    (xmin, ymin, zmax),
+                    (xmin, ymax, zmax),
+                ]
+
+                faces += [
+                    (0 + 8 * _i, 1 + 8 * _i, 2 + 8 * _i, 3 + 8 * _i),
+                    (4 + 8 * _i, 7 + 8 * _i, 6 + 8 * _i, 5 + 8 * _i),
+                    (0 + 8 * _i, 4 + 8 * _i, 5 + 8 * _i, 1 + 8 * _i),
+                    (1 + 8 * _i, 5 + 8 * _i, 6 + 8 * _i, 2 + 8 * _i),
+                    (2 + 8 * _i, 6 + 8 * _i, 7 + 8 * _i, 3 + 8 * _i),
+                    (4 + 8 * _i, 0 + 8 * _i, 3 + 8 * _i, 7 + 8 * _i),
+                ]
+
+                _i += 1
+
+            save_obj(vertices, faces, os.path.join(args.output_dir, box_filename + ".obj"))
+
+    return
+
+
+if __name__ == "__main__":
+    main()

detection/luna16_visualization/save_obj.sh

@@ -0,0 +1,7 @@
+#!/bin/bash
+
+INPUT_DATASET_JSON="./data_sample.json"
+OUTPUT_DIR="./out"
+
+python save_obj.py  --input_dataset_json ${INPUT_DATASET_JSON} \
+                    --output_dir ${OUTPUT_DIR}