Skip to content

00_Quick_Tutorial.md

Latest commit

 

History

History
263 lines (163 loc) · 7.38 KB

00_Quick_Tutorial.md

File metadata and controls

263 lines (163 loc) · 7.38 KB

🔄 Quick Tutorial: Plate Registration and Fit Comparison

(~10–20 minutes, depending on your familiarity with 3D Slicer)

This quick tutorial walks you through registering two preformed orbital plates and comparing their fit using sample data prepared with this extension.

No external data preparation is required.

Overview of the workflow

You will:

  1. Install the extension and download prepared sample data
  2. Register a large and a small preformed orbital plate
  3. Generate quantitative plate-to-orbit fit metrics
  4. Compare plate fit across candidates

1. Install the Extension

  1. Download and install 3D Slicer 5.10.0 from:
    https://download.slicer.org/

  2. Open Extension Manager (top-right corner of Slicer).

  3. Search for SlicerOrbitSurgerySim, install it, and restart Slicer.

Note
The SlicerMorph extension is a dependency and will be installed automatically.
If it fails to install, please install SlicerMorph manually from Extension Manager.

2. Load Sample Data

This tutorial uses open-source segmentations derived from the CBCTDental Surgery dataset from Slicer's Sample Data module.

  1. Open Module Finder → Sample Data.
  2. Locate PlateRegistrationSampleDataFiles.
  3. Click it and select a directory to download and unzip the sample data.

Load the following files into Slicer

From the unzipped folder, drag and drop below files into Slicer:

  • skull_sample_left_fracture.ply
  • left_orbit_lm.mrk.json
  • synth_plate_large_left.ply
  • synth_plate_large_left_lm.mrk.json

Click OK when prompted.

Load the reference CT volume

In Sample Data, click CBCTDental Surgery.

  • The CT volume will load automatically (the skull model is segmented from the 'PostDentalSurgery' volume).
  • Scroll through slices or drag the slice offset (top-bar of a slice window) to locate the orbit.
  • Hold right mouse button and drag: zoom
  • Hold middle mouse button and drag: move slice position

(Optional) Switch to Conventional or Conventional Widescreen layout for better 2D/3D visualization.

3. Open PlateRegistration and Select Inputs

  1. Open Module Finder, type PlateRegistration, and switch to the module.

First-time use notice
Required Python packages will be installed automatically.
This may take a few minutes. Please do not close Slicer.

  1. In the Input section:
    • Select the orbit model
    • Select the plate model
    • Select the corresponding landmark files

4. Initial Registration

  1. In Initial Registration, click:
    • Initial registration
    • Registration posterior stop

The plate should now be roughly aligned with the orbit.

A new folder will appear in the Node Viewer to store registration results.
Folder name format: plate_model_name_timestamp

  • A timestamp is appended to ensure unique folder names

5. Manual Plate Adjustment

  1. In Plate interactive adjustment, check
    Enable 3D interaction transform handle.

Additional Python packages may be installed on first use.

  1. A transform handle appears:
    • Rotation center: posterior stop landmark
    • Subsampled plate shown in blue

Use the handles in 3D or slice views to rotate or translate the plate.

  1. Click Mark intersection to detect plate–orbit intersections:
    • Yellow line: 3D view
    • Yellow dots: 2D slices
    • Intersection percentage shown in the info box

Note
The sample plates were manually created for demonstration purposes and may not perfectly fit the orbit.
Minor intersections are acceptable for this tutorial.

6. Save Registration Results

  1. Click Finalize Registration.

  1. Choose a root directory (e.g., ~/Downloads/test_orbitSim).

  2. Click Save current plate registration results.

7. Register a Second Plate

Drag the following files into Slicer:

  • synth_plate_small_left.ply
  • synth_plate_small_left_lm.mrk.json

Repeat Steps 3–6, saving results into the same root directory.

8. Generate Fit Metrics

Fit metrics are computed using:

  1. Vertex-to-surface distances (adapted from Model-to-Model Distance)
  2. Distances from plate-edge points projected onto the reconstructed orbit

Prepare margin points

Copy the folders:

  • synth_plate_large_left
  • synth_plate_small_left

from: ./plateRegistrationSampleData/plateMarginPtsForProj into: ./your_root_folder/points_for_projection.

Load reconstructed orbit

Drag skull_sample_left_orbit_recon.ply into Slicer.

Generate fit metrics

Switch to the Plate fit metrics tab.

Ensure:

  • Plate margin points root directory points to ./your_root_folder/points_for_projection
  • Reconstructed orbit model is selected

Click:

  • Compute distance map
  • Project points from each plate

Results are saved under: ./your_root_folder/fit_output/fit_metrics

Optional visualization of fit metrics

To visualize plate-to-orbit heatmap and point projection results, select a plate folder under ./your_root_folder/fit_output/fit_metrics, and click the two visualization buttons.


Tips: You can hide loaded files by clicking and closing the "eye" icon to turn off visualizations in the top "Node" box or simply right click and delete them.


9. Compare Plate Fit

Switch to Compare fit tab.

Ensure:

  • Compare distances between plate margins and orbits is checked
  • Directory points to ./your_root_folder/fit_output/fit_metrics

Click Compare fitness.

Outputs include:

  • Plate rankings (mean & per-edge distances)
  • Scatter plot comparing plates

Results are saved under: ./your_root_folder/fit_output/compare_fit_comparison

Optional visualization

  • Enable Visualize existing results
  • Show superimposed plates and margin points