The HIPpocampal Shape and Thickness Analysis Toolbox (HIPSTA) present a geometry-based method for the analysis of local hippocampal thickness and curvature and constructs an intrinsic coordinate system (unrolling/flattening) for statistical analysis across multiple participants.


What HIPSTA can do for you

HIPpocampal Shape and Thickness Analysis - HIPSTA


This repository contains a collection of scripts for hippocampal shape and thickness analysis as described in our recent publication.


The main analysis script performs the following major processing steps:

  1. preprocess image (cropping, upsampling, automask)
  2. create labels
    1. extract HSF labels from label image
    2. merge individual labels
  3. attach molecular layer to neighboring regions (if present)
  4. create mask
    1. fill holes using dilation and erosion
    2. create final mask
  5. create surface
    1. create initial surface using marching cube algorithm
    2. topology fixing (optional)
    3. smooth (fixed) surface
    4. remesh surface (optional)
  6. create tetrahedral mesh from triangular surface
  7. create label files for tetra mesh
  8. remove boundary mask (preprocessing for mesh cutting)
  9. cut open tetrahedral mesh at anterior and posterior ends
  10. create cube parametrization
  11. compute thickness and curvature
  12. map subfield values (and other volume-based data)
  13. create supplementary files for visualization

Current status and future development:

The hippocampal shape and thickness analysis package is currently in its beta stage, which means that it's open for testing, but may still contain unresolved issues. Future changes with regard to the algorithms, interfaces, and package structure are to be expected.

In the near future, we anticipate the following changes and additions:

  • improved documentation including walk-through examples
  • improved interfaces and installation options; availability as a python package
  • provision of Docker and/or Singularity files to avoid issues with differences in dependencies and enviroments


python3 shapetools.py --filename <filename> --hemi <hemi> --lut <lookup-table> [--outputdir <OUTDIR>] [further options]

Mandatory arguments:Description
--filenameA segmentation file.
--hemiHemisphere. Either 'lh' or 'rh'.
--lutLook-up table. A valid filename or one of the following: 'fs711', 'ashs'.
Optional arguments:Description
--outputdirDirectory where the results will be written. If not given, a subfolder within each subject's directory will be created.
--no-cleanupDo not delete files that may be useful for diagnostic or debugging purposes, but are not strictly necessary otherwise.
Getting help:Description
--helpDisplay this help and exit.
--more-helpDisplay extensive help and exit.
--versionDisplay version number and exit.
Experimental arguments:Description
--no-cropDo not crop image.
--upsample [ <float> <float> <float> ]A list of parameters to fine-tune image upsampling: specify three multiplicative factors to determine the final voxel size. If none are given, resample to the smallest voxel size.
--automated-headAutomatically identify boundary towards hippocampal head.
--automated-tailAutomatically identify boundary towards hippocampal tail.
--margin-head <int>Margin for automated head identification.
--margin-tail <int>Margin for automated tail identification.
--dilation-erosion <int> <int>Settings for dilation-erosion procedure. Specify two numbers for width of dilation and erosion. Default is 0 0.
--no-filterDo not filter image.
--filter <int> <int>A list of parameters to fine-tune image filtering. Specify two numbers for filter width and threshold. Default is 0.5 50
--long-filterFilter image along longitudinal axis, i.e. attempt to create smooth transitions between slices.
--long-filter-sizeSize of longitudinal filter.
--close-mask [<string>]Apply closing operation to mask, i.e. attempt to close small holes. Default is regular, alternative is experimental.
--mca <string>Marching-cube algorithm. Either mri_mc (default) or mri_tessellate.
--mcc <integer>Marching-cube connectivity. Only used for mri_mc algorithm. Default is 1. See mri_mc --help for details.
--topological-fixingUse FreeSurfer's topology fixing program to refine and fix initial surfaces. Can only be used with FreeSurfer-processed data. Expects two files as input, brain.mgz and wm.mgz.
--smooth <integer>Mesh smoothing iterations. Default is 5.
--remesh [ <int> ]Switch on remeshing, i.e. create a regular, evenly spaced surface grid. If a number is given, resample to that
--no-check-surfaceDo not check surface and proceed even if holes are present.
--no-check-boundariesDo not check boundaries and proceed if there are less / more than two continuous boundary loops.
--no-qcDo not perform QC.
--cut-params <float> <float>A list of parameters to fine-tune the cut operation. Default cutting range is [-0.975, 0.975].
--aniso-alpha <float> [ <float> ]Anisotropy parameters. Specify either one or two numbers.
--aniso-smooth <int>Anisotropy smoothing. Specify a number to control the number of smoothing iterations. Default is 10.
--thickness-params <...>A list of parameters to fine-tune the thickness computation. Specify three lists of three numbers: negative extent of x axis, positive extent of x axis, resolution on x axis. Repeat for the y and z axes. Default values are -0.9 0.9 41 -0.975 0.975 21 -0.9 0.9 11.
--allow-raggedAllow ragged mid-surfaces.
--allow-ragged-trianglesAllow triangles for ragged mid-surfaces.


python3 shapetools.py --filename /my/segmentation/file --hemi lh --lut fs711 --outputdir /my/output/directory


  1. The primary output are thickness values that will be computed and stored as CSV or PSOL or MGH overlay files within the 'thickness' folder. The PSOL or MGH files can be overlaid onto the mid-surface vtk file that is also found within the 'thickness' folder.

  2. Intermediate volume and surface files, each prefixed with the particular operation performed. The basic pattern for the filenames is:


lhleft hemisphere
rhright hemisphere
cropcrop image
upsupsample image
amauto-mask for head and tail
mlmerged molecular layer
dedilation and erosion
filtgaussian filtering and thresholding
cmclose mask
lflongitudinal filter
mcmarching cube algorithm
tftopological fixing
tettetrahedral mesh
bndboundary mesh
cutmesh cut at anterior/posterior ends
rmremove free vertices
openremoved anterior/posterior ends to create an open mesh
uvwcube parametrization (xyz --> uvw)
234, 236, etc.several numerics corresponding to the hippocampal subfield segmentation look-up table
assignedmolecular layer split into subregions
mergedmolecular layer subregions merged with other regions
  1. Several folders with intermediate results
StepHSF labelPrefixFolderContents
1<none><none>labelsfiles with volume labels
2HSFLABEL_01mlmerge-mlfiles created during the merging of the molecular layer
3HSFLABEL_02demaskfiles created during creation and post-processing of binary masks
4bHSFLABEL_05tffixed-surfacefiles created during topological fixing (optional)
6<none><none>tetra-labelfiles created during tetrahedral mesh construction
7<none><none>tetra-cutfiles created during preprocessing for tetrahedral mesh cutting
8HSFLABEL_09cuttetra-cutfiles created during tetrahedral mesh cutting
9<none>bnd, open, uvwtetra-cubefiles created during cube parametrization
10+11<none><none>thicknessfolder with thickness overlays and mid-surface files

Supported segmentations:

  • If using the ashs segmentation, additional labels for the hippocampal head (label value: 20) and tail (label value: 5) labels are recommended.
  • Topological fixing (--topological-fixing <filename1> <filename2>) should not be used unless working with FreeSurfer-processed data. <filename1> is the brain.mgz file and <filename2> is the wm.mgz file, both found within the mri subdirectory of an individual FreeSurfer output directory.
  • If using a custom look-up table (--lut <filename>), the expected format for the file is: <numeric ID> <name> <R> <G> <B> <A>. <R>, <G>, <B>, <A> are numerical values for RGB colors and transparency (alpha) and will be ignored. For example, 236 Subiculum 255 0 0 0. Each line may only contain a single anatomical structure. Do not use a header line. The following labels need to be present in the look-up table: presubiculum, subiculum, ca1, ca2, ca3, ca4, head, and tail. Additional labels may be present, but will be ignored. Lines starting with # will be ignored (and can be used for comments).
  • Multiple substructures can have the same numeric ID, e.g. presubiculum and subiculum can have the same numeric ID if these substructures are not distinguished in the segmentation. The head and tail subregions can have multiple labels if these are distinguished in the segmentation, but should be combined for the processing within the hippocampal shapetools.


Use the following code to download this package from its GitHub repository:

git clone https://github.com/Deep-MI/Hipsta.git

You can use the following code to install the required Python depencies:

pip install -r requirements.txt

It is recommended to run this pipeline within its own virtual environment.


  1. A FreeSurfer version (6.x or 7.x) must be sourced, i.e. FREESURFER_HOME must exist as an environment variable and point to a valid FreeSurfer installation.

  2. A hippocampal subfield segmentation created by FreeSurfer 7.11 or later or the ASHS software. A custom segmentation is also permissible (some restrictions and settings apply; see Supported Segmentations).

  3. Python 3.5 or higher including the lapy, numpy, scipy, nibabel, pyvista, and pyacvd libraries, among others. See requirements.txt for a full list.

  4. The gmsh package (verson 2.x; http://gmsh.info) must be installed. Can be downloaded e.g. as binaries for linux or MacOSX . The 'gmsh' binary must be on the $PATH:

    export PATH=${PATH}:/path/to/gmsh-directory/bin

  5. The PYTHONPATH environment variable should include the toolbox directory:

    export PYTHONPATH=${PYTHONPATH}:/path/to/hipsta-package


Please cite the following publications if you use these scripts in your work:

  • Diers, K., Baumeister, H., Jessen, F., Düzel, E., Berron, D., & Reuter, M. (2023). An automated, geometry-based method for hippocampal shape and thickness analysis. Neuroimage, 276:120182. doi: 10.1016/j.neuroimage.2023.120182.

Please also consider citing the these publications:

  • Geuzaine, C., & Remacle, J.-F. (2009). Gmsh: a three-dimensional finite element mesh generator with built-in pre- and post-processing facilities. International Journal for Numerical Methods in Engineering, 79, 1309-1331.

  • Andreux, M., Rodola, E., Aubry, M., & Cremers, D. (2014). Anisotropic Laplace-Beltrami operators for shape analysis. In European Conference on Computer Vision (pp. 299-312). Springer, Cham.

  • Iglesias, J. E., Augustinack, J. C., Nguyen, K., Player, C. M., Player, A., Wright, M., ... & Fischl, B. (2015). A computational atlas of the hippocampal formation using ex vivo, ultra-high resolution MRI: application to adaptive segmentation of in vivo MRI. Neuroimage, 115, 117-137.

  • Yushkevich, P. A., Pluta, J., Wang, H., Ding, S.L., Xie, L., Gertje, E., Mancuso, L., Kliot, D., Das, S. R., & Wolk, D.A. (2015). Automated Volumetry and Regional Thickness Analysis of Hippocampal Subfields and Medial Temporal Cortical Structures in Mild Cognitive Impairment. Human Brain Mapping, 36, 258-287.

Programming language
  • Python 100%
  • MIT
</>Source code

Participating organisations

German Center for Neurodegenerative Diseases
Harvard Medical School



Kersten Diers
German Center for Neurodegenerative Diseases

Related tools



LaPy is an open-source Python package for differential geometry on triangle and tetrahedra meshes. It includes an FEM solver to estimate the Laplace, Poisson or Heat equations, also the computations of gradients, divergence, mean-curvature flow, conformal mappings, geodesics, ShapeDNA and more.

Updated 1 month ago
19 2