fs2dicom

fs2dicom is a tool to convert FreeSurfer outputs to DICOM.

Two subcommands are implemented: create-seg and create-sr, to produce DICOM Segmentation Image objects, and DICOM Structured Report objects, respectively. aseg.stats to DICOM-SR using dcmqi.

Currently, only aseg.mgz and aseg.stats are supported and documented. Future versions may support other FreeSurfer segmentations and parcellations (such as thickness and volumes of different cortical regions)

Dependencies

dcmqi and FreeSurfer are required. Alternatively, instead of installing these programs locally, Docker can be used instead to run the necessary commands. Using Docker is the default.

Note: future updates should be able to remove the FreeSurfer dependency, and replace its functionality with python-based tools.

Installation

Clone the repo, cd into it, and run:

pip install -e .

This will install all python requirements needed to run fs2dicom (listed in requirements.txt).

Usage

fs2dicom base options

Usage: fs2dicom [OPTIONS] COMMAND [ARGS]...

  Create DICOM Segmentation Image and Structured Report objects from
  FreeSurfer segmentations.

  Currently requires either docker OR FreeSurfer and dcmqi installed locally

  Docker is the default way to run FreeSurfer and dcmqi commands needed to
  create DICOM SEG/SR

  A FreeSurfer License key is required to run the docker image. This can be
  downloaded from: https://surfer.nmr.mgh.harvard.edu/registration.html

  FreeSurfer commands are used to resample the aseg to native space Future
  versions may remove this dependency

Options:
  --dcmqi_type [docker|local]     Use docker or local installed version of
                                  dcmqi (default: docker)
  --dcmqi_docker_image TEXT       Name of the dcmqi docker image (default:
                                  qiicr/dcmqi:latest)
  --freesurfer_type [docker|local]
                                  Use docker or local installed version of
                                  freesurfer (default: docker)
  --freesurfer_docker_image TEXT  Name of the FreeSurfer docker image.
                                  Currently only supports
                                  corticometrics/fs6-base (default:
                                  corticometrics/fs6-base:latest)
  --fs_license_key TEXT           Path to FreeSurfer License key file.
                                  (default: path set by environment variable
                                  FS_LICENSE_KEY)
  -h, --help                      Show this message and exit.

Commands:
  create-seg  Creates a DICOM Segementation Image object ...
  create-sr   Creates a DICOM Structured Report object...

create-seg subcommand options

Usage: fs2dicom create-seg [OPTIONS] T1_DICOM_FILE ASEG_IMAGE_FILE
                           [ASEG_DICOM_SEG_OUTPUT]

  Creates a DICOM Segementation Image object from the T1_DICOM_FILE (one of
  the T1w DICOM files processed with FreeSurfer) and ASEG_IMAGE_FILE, and
  outputs to the ASEG_DICOM_SEG_OUTPUT file name (default: ./aseg.dcm)

Options:
  --seg_metadata PATH  Path to the DICOM SEG metadata schema describing the
                       aseg (default: provided within package)
  -h, --help           Show this message and exit.

create-sr subcommand options

Usage: fs2dicom create-sr [OPTIONS] T1_DICOM_FILE ASEG_STATS_FILE
                          [ASEG_DICOM_SR_OUTPUT]

  Creates a DICOM Structured Report object ASEG_DICOM_SR_OUTPUT (default:
  ./aseg-sr.dcm) using the values from the ASEG_STATS_FILE created by
  FreeSurfer. The T1_DICOM_FILE (one of the T1w DICOM files processed with
  FreeSurfer) and aseg_dicom_seg_file (default: ./aseg.dcm, specified with
  --aseg_dicom_seg_file) are needed to provide context for this DICOM SR.
  sr_metadata_output is also created (default: ./fs-aseg-sr.json, specified
  with --sr_metadata_output), containing the values used to create the DICOM
  SR.

Options:
  --aseg_dicom_seg_file PATH  DICOM SEG of the aseg, for example created by
                              `fs2dicom create-seg` (default: ./aseg.dcm)
  --sr_metadata_output PATH   JSON file output containing the values used to
                              create the DICOM SR (default: ./fs-aseg-sr.json)
  --seg_metadata PATH         Path to the DICOM SEG metadata schema describing
                              the aseg (default: provided within package)
  --sr_template PATH          Path to DICOM SR template that is filled in with
                              aseg.stats values (default: provided within
                              package)
  -h, --help                  Show this message and exit.

Descriptions of steps implemented by fs2dicom

Preprocessing (not done by fs2dicom):

• Run Freesurfer's recon-all on your input DICOM(s) to generate aseg.mgz and aseg.stats.

aseg.mgz to DICOM-SEG

1. Call mri_vol2vol from FreeSurfer to resample aseg.mgz from FreeSurfer space to the native space of the input T1 DICOM, and convert to nifti.

mri_vol2vol \
  --mov /path/to/aseg.mgz \
  --targ /path/to/t1/dicom/file \
  --regheader \
  --nearest \
  --o aseg_native.nii.gz

2. Use itkimage2segimage from dmcqi to convert aseg.nii.gz to DICOM-SEG using fs-aseg.json in this repo.

itkimage2segimage \
  --inputDICOMDirectory /path/to/t1/dicom/directory \
  --inputMetadata /path/to/fs2dicom/fs2dicom/templates/fs-aseg.json \
  --inputImageList aseg_native.nii.gz \
  --outputDICOM aseg.dcm
  --skip

fs-aseg.json maps FreeSurfer aseg labels to SNOMED codes and preserves the FreeSurfer's recommended color scheme.

fs-aseg.json has been kindly provided by Emily Lindemer

See the DCMQI gitbook for details

aseg.stats to DICOM-SR

1. Read the aseg.stats file into a pandas dataframe
2. Fill in the fs-aseg-sr-template.json jinja2 template with:

• the T1 DICOM file list,
• the name of the aseg DICOM SEG file, and
• the volume values from the aseg.stats dataframe

3. Create the DICOM SR file using dcmqi's tid1500writer:

tid1500writer \
  --inputImageLibraryDirectory /path/to/t1/dicom/directory \
  --inputCompositeContextDirectory /path/to/aseg_dicom_seg/directory \
  --outputDICOM aseg-sr.dcm \
  --inputMetadata fs-aseg-sr.json  # created in previous step

More information can be found here:

• tid1500writer user guide
• example --inputMetadata json file
• aseg-specific example --inputMetadata json file
  • Subject-specific modifications
    • "compositeContext" needs to point to DICOM-SEG object
    • "imageLibrary" needs to point to list of source MPRAGE dicoms
    • "Measurements"->"measurementItems"-"value" needs to be harvested from aseg.stats
    • "Measurements"->"SourceSeriesForImageSegmentation" needs to be set to the DICOM "Series Instance UID Attribute" (0020,000E)