Skip to content

Commit

Permalink
WIP: DOC: Include description of pre-processing transforms
Browse files Browse the repository at this point in the history
  • Loading branch information
NicerNewerCar committed Aug 28, 2024
1 parent 6183103 commit f99af9b
Show file tree
Hide file tree
Showing 4 changed files with 130 additions and 0 deletions.
1 change: 1 addition & 0 deletions Documentation/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@
"sphinx_rtd_theme",
"sphinxcontrib.autoprogram",
"sphinxcontrib.bibtex",
"sphinxcontrib.mermaid",
]
bibtex_bibfiles = ["refs.bib"]
myst_enable_extensions = [
Expand Down
1 change: 1 addition & 0 deletions Documentation/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ getting-started.md
get-help.md
user-interface.md
shortcuts.md
transforms.md
tutorials/index.md
adv-topics/index.md
file-specifications/index.md
Expand Down
1 change: 1 addition & 0 deletions Documentation/requirements.txt
Original file line number Diff line number Diff line change
Expand Up @@ -6,3 +6,4 @@ sphinx-notfound-page
sphinx-rtd-theme == 1.0.0rc1
sphinxcontrib-autoprogram
sphinxcontrib-bibtex
sphinxcontrib-mermaid
127 changes: 127 additions & 0 deletions Documentation/transforms.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,127 @@
# Transforms

## Background

| ![Coordinate systems](https://github.com/Slicer/Slicer/releases/download/docs-resources/coordinate_systems.png) [^1] |
| -- |
| <p style="text-align: center;"> World coordinate system (left), Anatomical coordinate system (middle), Image coordinate system (right) </p>|

<!-- Proper way to cite the image above? -->

When processing medical image data in 3D Slicer, the Right-Anterior-Superior (RAS) coordinate convention is followed.
However, for compatibility with other software, Slicer assumes that all files are stored in the Left-Posterior-Superior
(LPS) coordinate convention, unless the file explicitly states that the coordinates are in RAS. To achieve this, whenever
Slicer reads or writes a file, it may need to flip the sign of the first two coordinates axes to convert the data to/from
the RAS coordinates system. For further reading on the coordinate systems used in 3D Slicer, please see the
[Slicer wiki](https://slicer.readthedocs.io/en/latest/user_guide/coordinate_systems.html).

The following transformation maxtrix can be used to convert between RAS and LPS coordinates:

![XYZ Axis](https://)

```{math}
\begin{bmatrix}
-1 & 0 & 0 & 0\\
0 & -1 & 0 & 0\\
0 & 0 & 1 & 0\\
0 & 0 & 0 & 1
\end{bmatrix}
```
### Spatial referencing

Spatial referencing data is used to encode voxel to world unit resolution (also referred to as pixel/voxel spacing), origin,
and orientation. In DICOM format, the spatial referencing can be retrieved from the DICOM header meta data. In MATLAB,
the `imref3d` function can be constructed from the DICOM meta data to store the intrinsic - spatial relationship.

Transforming between image and world spaces has a visual proportion change to the image volume:

![Image space to World Space](https://)

We can construct the following matrix to convert from image space to world space. Where `P_{x,y,z}` is the pixel spacing in
each respective dimension and `O_{x,y,z}` is the origin for each respective dimension.

```{math}
\begin{bmatrix}
P_x & 0 & 0 & O_x\\
0 & P_y & 0 & O_y\\
0 & 0 & P_z & O_z\\
0 & 0 & 0 & 1
\end{bmatrix}
```

When importing DICOM data with Slicer, a spatial referencing transform is automatically applied to a CT image volume the
header meta data. Note the RAS anatomical orientation and +X,+Y +Z red/green/blue axes indicators.

<!-- Lots of images/diagrams to bring over -->

## Transforms in SlicerAutoscoperM

SlicerAutoscoperM allows tracking of a rigid body in target 'World' space. Often, more than one rigid body
is tracked, and the relative motion of one rigid body is calculated with respect to a reference.

Within the Autoscoper Pre-processing tab of the AutoscoperM Slicer module, rigid bodies of interest can
be segmented from a CT DICOM automatically. Alternatively, the user can load in previous segmentations from
models. These segmentations are used to generate partial volumes. The density volumetric data in the bounds
of the segmented model are isolated and saved in a TIFF stack. In Autoscoper, this TIFF stack is imported
in a unique orientation, we will refer to this as Autoscoper (AUT) space. The data from the partial volume
is projected onto the target image plane (overlaid with the radiograph of each BVR fram) as a DRR.

As with CT DICOM volume images, a TIFF stack will exist, nativity, in image space and require a
spatial imaging reference transform to describe image to world spacing/location and orientation, in Autoscoper,
the voxel resolution of the TIFF volumes explicitly follows each path line.

To enable users to post-process the output transforms from Autoscoper, at the time of Partial Volume Generation
in SlicerAutoscoperM, the `Models`, `Transforms`, `Tracking`, and `Volumes` folders are populated with the
following information:

```
Output Directory
├── Models
│ └── AUT{bone}.stl
├── Transforms
│ ├── {bone}.tfm
│ ├── {bone}_scale.tfm
│ ├── {bone}_t.tfm
│ ├── {bone}_DICOM2AUT.tfm
│ └── {bone}_PVOL2AUT.tfm
├── Tracking
│ └── {bone}.tra
└── Volumes
└── {bone}.tif
```

* `{bone}.tif` is a non-spatially transformed volumetric data segmented from CT-DICOM.
* `{bone}.tfm` is a non-rigid transform that translates and scales the `{bone}.tif` volume to its spatial location
within the segmented CT-DICOM.
* `{bone}.tra` is the same as the `{bone}_DICOM2AUT.tfm` but in a format which Autoscoper can load.
* `{bone}_t.tfm` is a translation matrix that moves between the world origin and the location of the partial volume
within the segmented CT-DICOM.
* `{bone}_scale.tfm` is a scaling matrix that moves the volume from image space to world space.
* `{bone}_DICOM2AUT.tfm` is a transformation that moves from DICOM space into Autoscoper space.
* `{bone}_PVOL2AUT.tfm` is a transformation that moves from world space into Autoscoper space.

```{note}
The braces {} around the word bone have been omitted below, since they are not supported by mermaid.
```

```{mermaid}
---
title: SlicerAutoscoperM Pre-Processing Transforms
---
flowchart TD
T[TIFF - Image Space]
D[Spacially located PV - DICOM Space]
W[World origin]
M[Model - AUT Space]
W -- bone_t.tfm --> D
T -- bone.tfm --> D
T -- bone_scale.tfm --> W
D -- bone_DICOM2AUT.tfm --> M
W -- bone_PVOL2AUT.tfm --> M
```

0 comments on commit f99af9b

Please sign in to comment.