fnndsc/pl-fetal-cp-surface-extract
Fetal CP Surface Extraction
4.0K
Fetal brain cortical plate surface extraction using CIVET marching-cubes (sphere_mesh
).
pl-fetal-cp-surface-extract
consumes binary volumetric .mnc
brain masks to produce
surfaces as .obj
files with standard connectivity (81,920 triangles). This program is
suitable for targeting the inner cortical plate surface (gray-white matter boundary)
of high-quality human fetal brain MRI segmentation for subjects between 23-35 gestational
weeks of age.
Polygonal surface mesh representations of brain hemispheres are useful for measuring cortical thickness, image registration, and quantitative regional analysis.
We have evaluated two implementations of marching-cubes:
We found that CIVET's implementation of the marching-cubes algorithm, sphere_mesh
, is
more accurate
than scikit-image's implementation, which requires FWHM blurring of the volume.
Moreover, sphere_mesh
guarantees a spherical topology.
mincmorph
to fill in disconnected voxels (improve mask quality)adapt_object_mesh
.While the upstream
marching_cube.pl
script uses ASP (surface_fit
) post-processing to fully converge the surface to the volume boundary,
without the extra step the accuracy is nonetheless sufficient.
pl-fetal-cp-surface-extract
is a ChRIS plugin, meaning it can
run from either within ChRIS or the command-line.
extract_cp
reads mask files from an input directory and creates
the resulting surface files in an output directory.
Input files should be MINC .mnc
files representing a mask of the white matter (WM)
for a single brain hemisphere (either left or right). WM should be indicated by a
value of 1
, background value should be 0
.
If the input directory contains multiple masks, they will all be processed individually and in parallel.
--subsample
It is necessary to use the --subsample
option for fetal brains 29 GA
and older to avoid "bridge" errors between narrow (<1 voxel) sulcal walls.
--mincmorph-iterations
Number of mincmorph
iterations to perform on the mask before marching-cubes.
Use a larger value as a workaround for masks which have missing voxels. However,
extremely bad masks will require external correction, for instance, using mincdefrag
.
Garbage in, garbage out.
extract_cp --mincmorph-iterations 10 /incoming /outgoing
--adapt_object_mesh
Arguments to pass to adapt_object_mesh
, which does mesh smoothing.
Use a larger value if the results are bumpy/voxelated in appearance.
extract_cp --adapt_object_mesh 0,100,0,0 /incoming /outgoing
--inflate_to_sphere_implicit
Arguments to pass to inflate_to_sphere_implicit
. The default value (200, 200)
should work for fetal brains. While it shouldn't be necessary, increasing the
values shouldn't do any harm, and would help compensate for larger brain sizes.
--keep-mask
Copy input mask file to output directory.
--keep-mask
is a workaround for using pl-fetal-cp-surface-extract
as part of a
ChRIS pipeline. It eliminates the need for an extra ts plugin step.
To get started with local command-line usage, use Apptainer
to run pl-fetal-cp-surface-extract
as a container:
apptainer exec docker://fnndsc/pl-fetal-cp-surface-extract extract_cp input/ output/
To print its available options, run:
apptainer exec docker://fnndsc/pl-fetal-cp-surface-extract extract_cp --help
pl-fetal-cp-surface-extract
pl-nums2mask
: create input maskspl-fetal-cp-surface-extract
Instructions for developers.
Build a local container image:
docker build -t localhost/fnndsc/pl-fetal-cp-surface-extract .
Run chris_plugin_info
to produce a JSON description of this plugin, which can be uploaded to a ChRIS Store.
docker run --rm localhost/fnndsc/pl-fetal-cp-surface-extract chris_plugin_info > chris_plugin_info.json
Mount the source code extract_cp.py
into a container to test changes without rebuild.
docker run --rm -it --userns=host -u $(id -u):$(id -g) \
-v $PWD/extract_cp:/opt/conda/lib/python3.10/site-packages/extract_cp:ro \
-v $PWD/in:/incoming:ro -v $PWD/out:/outgoing:rw -w /outgoing \
localhost/fnndsc/pl-fetal-cp-surface-extract extract_cp /incoming /outgoing
docker pull fnndsc/pl-fetal-cp-surface-extract