ilwoolyu/cmorph repository overview

⁠Overview

This image contains shape analysis tools for cortical morphometry including (1) sulcal curve delineation for geometric feature extraction/ROI definition, (2) surface registration for cortical shape correspondence, and (3) local gyrification index for cortical shape quantification. These tools take an input mesh file(s) to generate and capture meaningful shape characteristics. Please check details about implementation, installation, usage, etc. at my GitHub repositories and refer to my recent papers for technical details.

⁠Sulcal curve delineation [code & usage]⁠

TRACE: Topological Graph Representation for Automatic Sulcal Curve Extraction

A proper geometric representation of the cortical regions is a fundamental task for cortical shape analysis and landmark extraction. However, a significant challenge has arisen due to the highly variable, convoluted cortical folding patterns. Here, we propose a novel topological graph representation for automatic sulcal curve extraction (TRACE). In practice, the reconstructed surface suffers from noise influences introduced during image acquisition/surface reconstruction. In the presence of noise on the surface, TRACE determines stable sulcal fundic regions by employing the line simplification method that prevents the sulcal folding pattern from being significantly smoothed out. The sulcal curves are then traced over the connected graph in the determined regions by the Dijkstra’s shortest path algorithm.

⁠Surface registration [code & usage]⁠

HSD: Hierarchical Spherical Defomration for Cortical Surface Registration

We present hierarchical spherical deformation for group-wise shape correspondence to address template selection bias and to minimize registration distortion. In this work, we aim at a continuous and smooth deformation field to guide accurate cortical surface registration. In conventional spherical registration methods, global rigid alignment and local deformation are independently preformed. Motivated by the composition of precession and intrinsic rotation, we simultaneously optimize global rigid rotation and non-rigid local deformation by utilizing spherical harmonics interpolation of local composite rotations in a single framework. To this end, we indirectly encode local displacements by such local composite rotations as functions of spherical locations. Furthermore, we introduce an additional regularization term to the spherical deformation, which maximizes its rigidity while reducing registration distortion. To improve surface registration performance, we employ the second order approximation of the energy function that enables fast convergence of the optimization.

⁠Local gyrification index [code & usage]⁠

LGI: Cortical Shape-Adaptive Local Gyrification Index

The amount of cortical folding, or gyrification, is typically measured within local cortical regions covered by an equidistant geodesic or nearest neighborhood-ring kernel. However, without careful design, such a kernel can easily cover multiple sulcal and gyral regions that may not be functionally related. Furthermore, this can result in smoothing out details of cortical folding, which consequently blurs local gyrification measurements. In this paper, we propose a novel kernel shape to locally quantify cortical gyrification within sulcal and gyral regions. We adapt wavefront propagation to generate a spatially varying kernel shape that encodes cortical folding patterns: neighboring gyral crowns, sulcal fundi, and sulcal banks. For this purpose, we perform anisotropic wavefront propagation that runs fast along gyral crowns and sulcal fundi by solving a static Hamilton–Jacobi partial differential equation. The resulting kernel adaptively elongates along gyral crowns and sulcal fundi, while keeping a uniform shape over flat regions like sulcal banks. We then measure local gyrification within the proposed spatially varying kernel.

⁠Usage

Prerequisite

Pull the Docker image first:

$ docker pull ilwoolyu/cmorph:1.7

After puling the image, each tool can be run with a single command like

$ docker run \
         -v <LOCAL_INPUT_PATH>:/INPUT/:ro \
         -v <LOCAL_OUTPUT_PATH>:/OUTPUT/ \
         --rm ilwoolyu/cmorph:1.7 \
         <CMD: CurveExtraction | HSD | HSD-cuda | lgi> <ARGS>

For interactive environment:

$ docker run \
         -v <LOCAL_INPUT_PATH>:/INPUT/:ro \
         -v <LOCAL_OUTPUT_PATH>:/OUTPUT/ \
         -it ilwoolyu/cmorph:1.7 bash

The executable files are located in $CMORPH_ROOT/bin or /opt/cmorph/bin.

Quick commands

To extract curves output.scurve from input.vtk:

CurveExtraction -i input.vtk -o output --sulcus

To establish shape correspondence across s1.sphere.vtk, s2.sphere.vtk, and s3.sphere.vtk with their associated features s1.curv.txt, s2.curv.txt, and s3.curv.txt, respectively:

HSD \
    -s s1.sphere.vtk s2.sphere.vtk s3.sphere.vtk \
    -p s1.curv.txt s2.curv.txt s3.curv.txt \
    -o s1.sphere.reg.vtk s2.sphere.reg.vtk s3.sphere.reg.vtk

To generate gyrification map of input.vtk:

lgi -i input.vtk

See more options with --help or documentation: TRACE⁠, HSD⁠, and LGI⁠

⁠Version history

v1.7 - 6/6/2021

• Base OS upgrade: Ubuntu 18.04 -> Ubuntu 20.04
• CUDA upgrade: v10.2 -> v11.3
• HSD
  • Fixed spherical harmonics bases
  • Improved initial guess
• LGI
  • Improved performance on klaplace

v1.6d - 10/31/2020

• HSD
  • Added a new executable binary SphericalRemesh to support spherical deformation and data augmentation

v1.6c - 10/12/2020

• LGI
  • Added --intv to generate indices at all intermediate kernels once

v1.6b - 9/22/2020

• CUDA upgrade: v10.1 -> v10.2
• HSD
  • Fixed cache on inputs with inconsistent triangle order

v1.6a - 8/6/2020

• LGI
  • Fixed klaplace correspondence failure under certain circumstances

v1.6 - 7/7/2020

• HSD
  • Improved OpenMP multi-threading
  • Improved CUDA optimization
  • Support CUDA streams
  • Support fast icosahedral resamping
  • Improved performance and numerical accuracy
  • Improved user interface
  • See details at https://github.com/ilwoolyu/HSD/releases/⁠
• TRACE
  • Improved user interface
• LGI
  • Support OpenMP multi-threading
  • Improved user interface
• General
  • Moved cmorph path from /cmorph to /opt/cmorph

v1.5 - 3/30/2020

• HSD
  • Improved multi-threading on gradient computation
  • Switched sysv for 2nd order approximation
• LGI
  • Improved performance and accuracy of the H-J solver
  • Improved memory efficiency in klaplace
  • Fixed klaplace correspondence failure under certain circumstances
• General
  • Switched CLI from SlicerExecutionModel to CLI11

v1.4 - 1/9/2020

• HSD
  • Added an option to load pre-defined icosahedron mesh - use --icomesh
  • Fixed buffer overflow
• LGI
  • Improved performance of the Laplacian trajectory computation
  • Changed the default reference area to 77100 of cerebral hull - use --ref to change this

v1.3 - 8/2/2019

• Base OS upgrade: Ubuntu 16.04 -> Ubuntu 18.04
• CUDA upgrade: v9.0 -> v10.1
• HSD
  • Fixed gradients for the distortion term
  • Added initial guess for rigid alignment by default
  • Improved optimization stability

v1.2 - 11/15/2018

• HSD
  • Fixed static buffer size for gradients
• LGI
  • Changed the default reference area to 166000 - use --ref to change this

v1.1 - 11/7/2018

• TRACE
  • Support OpenMP for graph reconstruction
• LGI
  • Added --out option to the CLI script
  • Added executable binary check
  • Improved outer hull positioning - this results in more accurate quantification
  • Support OpenMP for anisotropic geodesic kernel
• General
  • Added a check routine for potential env_var missing
  • Moved executables from /bin to /cmorph/bin

v1.0 - 10/26/2018

• First release

⁠Docker

v1.7 -

• Base image: 11.3-base-ubuntu20.04 (11.3/base/Dockerfile⁠)

v1.6b - v1.6d

• Base image: 10.2-base-ubuntu18.04 (10.2/base/Dockerfile⁠)

v1.3 - v1.6a

• Base image: 10.1-base-ubuntu18.04 (10.1/base/Dockerfile⁠)
• Test: docker v19.03.1 (it now supports gpu⁠)

v1.0 - v1.2

• Base image: 9.0-base-ubuntu16.04 (9.0/base/Dockerfile⁠)
• Test: docker and nvidia-docker⁠ v18.06.1-ce

⁠License

The source codes in this image are publicly available under the MIT license⁠.

⁠Contact information

ILWOO LYU: [email protected]⁠ or [email protected]⁠ or [email protected]⁠