Data Loading and Saving

There are two major types of data that can be loaded to Slicer: DICOM and non-DICOM.

DICOM data

DICOM is a widely used and sophisticated set of standards for digital radiology.

Data can be loaded from DICOM files into the scene in two steps:

  1. Import: add files into the application’s DICOM database, by switching to DICOM module and drag-and-dropping files to the application window

  2. Load: get data objects into the scene, by double-clicking on items in the DICOM browser. The DICOM browser is accessible from the toolbar using the DICOM button .

Data in the scene can be saved to DICOM files in two steps:

  1. Export to database: save data from the scene into the application’s DICOM database

  2. Export to file system: copy DICOM files from the database to a chosen folder in the file system

More details are provided in the DICOM module documentation.

Non-DICOM data

Non-DICOM data, covering all types of data ranging from images (nrrd, nii.gz, …) and models (stl, ply, obj, …) to tables (csv, txt), point lists (json), etc.

Load data

To load data:

  • drag&drop file on the application window, or

  • in application menu: File -> Add Data (or Add Data toolbar button)

Save data

To save the entire scene (all data, visualization and processing settings, etc.):

  • in application menu File -> Save Data, or

  • Save Data toolbar button

Tip

The entire workspace, including all data and settings can be saved into a single, independent, self-contained .mrb file by clicking on the small package icon at the top-left corner. A new copy of all files is written and zipped into a single file, therefore saving takes longer time than an incremental saving of only the modified files.

Export data

To export selected data sets - for sharing with others or for loading into other applications: go to Data module, right-click on an item, and choose Export to file.... Settings used for exporting (file format, filename, options) do not modify settings used for saving.

Tip

Multiple nodes can be exported at once by placing them into a folder and then by exporting the folder. When exporting an entire folder hierarchy the Export folder structure option can be enabled to have the directory structure in the output directory match the subject hierarchy folder structure.

Supported Data Formats

Note

On use of LPS/RAS coordinate systems

DICOM and medical imaging software use the LPS (Left, Posterior, Superior) coordinate system, while Slicer’s internal representation employs RAS (Right, Anterior, Superior). For file compatibility, Slicer assumes data in files are in LPS coordinates and may flip the first two axes during read or write operations.

To learn more, see the Coordinate systems documentation, and the Coordinate system convention in Slicer.

Note

Be careful with uncommon encoding options

Research data formats like NRRD and NIfTI, and even widely used clinical formats like DICOM, support many encoding options that are technically valid but are so rarely seen that support libraries and other code in Slicer may not interpret them correctly.

If you are performing data interchange between Slicer and other software, prefer widely used conventions (such as LPS or RAS for coordinate systems) and double-check data integrity if you deviate from them.

Images

Readers may support 2D, 3D, and 4D images of various types, such as scalar, vector, DWI or DTI, containing images, dose maps, displacement fields, etc.

  • DICOM (.dcm, or any other): Slicer core supports reading and writing of some data types, while extensions add support for additional ones. Coordinate system: LPS (as defined by DICOM standard).

    • Supported DICOM information objects:

      • Slicer core:

        • CT, MRI, PET, X-ray, some ultrasound images

        • DICOM Segmentation objects (SEG modality)

        • Parametric Maps

        • Encapsulated STL (M3D modality)

        • Certain flavors of Structured Reports that follow TID 1500 Measurement report template

        • Secondary capture with Slicer scene (MRB) in private tag

      • SlicerRT extension: DICOM RT Structure Set, RT Dose, RT Plan, RT Image

      • SlicerHeart extension: 2D/3D/4D ultrasound (GE, Philips, Eigen Artemis, and other)

      • SlicerDMRI tractography storage

      • SlicerDcm2nii diffusion weighted MR

    • Notes:

      • For a number of dMRI formats we recommend use of the DICOM to NRRD converter before loading the data into Slicer.

      • Image volumes, RT structure sets, dose volumes, etc. can be exported using DICOM module’s export feature.

      • Limited support for writing image volumes in DICOM format is provided by the Create DICOM Series module.

      • Support of writing DICOM Segmentation Objects is provided by the Reporting extension

  • NRRD (.nrrd, .nhdr): General-purpose 2D/3D/4D file format. Coordinate system: as defined in the file header (usually LPS).

    • NRRD sequence (.seq.nrrd, .nrrd, .nhdr): 4D volume, loaded as a volume sequence. Frames are stored along the axis of list kind. A 4D image without list axis (for example, all axes are domain kind) is also loaded as a volume sequence, with frames along the last axis. See Sequences module documentation.

    • To load an image file as segmentation (also known as label image, mask, region of interest) see Segmentations module documentation

  • MetaImage (.mha, .mhd): Coordinate system: LPS (AnatomicalOrientation in the file header is ignored).

  • VTK (.vtk): Coordinate system: LPS. Important limitation: image axis directions cannot be stored in this file format.

  • Analyze (.hdr, .img, .img.gz): Image orientation is specified ambiguously in this format, therefore its use is strongle discouraged. For brain imaging, use Nifti format instead.

  • Nifti (.nii, .nii.gz): File format for brain MRI. Not well suited as a general-purpose 3D image file format (use NRRD format instead). Only NIfTI-1 files are supported (NIfTI-2 files cannot be loaded).

    • NIfTI sequence (.nii, .nii.gz): 4D image (frames stored along the 4th image axis), loaded as a volume sequence. Sequence index is set from the unit, spacing, and offset of the 4th axis. Volume sequences can be saved in this format, but some sequence properties cannot be stored (use .seq.nrrd format to preserve all properties). See Sequences module documentation.

    • To load an image file as segmentation (also known as label image, mask, region of interest) see Segmentations module documentation

  • Tagged image file format (.tif, .tiff): can read/write single/series of frames

  • PNG (.png): can read single/series of frames, can write a single frame

  • JPEG (.jpg, .jpeg): can read single/series of frames, can write a single frame

  • Windows bitmap (.bmp): can read single/series of frames

  • BioRad (.pic)

  • Brains2 (.mask)

  • GIPL (.gipl, .gipl.gz)

  • LSM (.lsm)

  • Scanco (.isq)

  • Stimulate (.spr)

  • MGH-NMR (.mgz)

  • MRC Electron Density (.mrc)

  • SlicerRT extension

    • Vista cone beam optical scanner volume (.vff)

    • DOSXYZnrc 3D dose (.3ddose)

  • SlicerHeart extension: 2D/3D/4D ultrasound (GE, Philips, Eigen Artemis, and other; reading only)

    • Philips 4D ultrasound: from Cartesian DICOM exported from QLab

    • GE Kretz 3D ultrasound (.vol, .v01)

    • Eigen Artemis 3D ultrasound

    • Any 3D/4D ultrasound image and ECG signal: if the user obtains Image3dAPI plugin from the vendor (GE Voluson, Philips, Siemens, etc.)

  • RawImageGuess extension

    • RAW volume (.raw): requires manual setting of header parameters

    • Samsung 3D ultrasound (.mvl): requires manual setting of header parameters

  • SlicerIGSIO extension:

    • Compressed video (.mkv, .webm)

    • IGSIO sequence metafile (.igs.mha, .igs.mhd, .igs.nrrd, .seq.mha, .seq.mhd, .mha, .mhd, .mkv, .webm): image sequence with metadata, for example for storing surgical navigation and position-tracked ultrasound data

  • OpenIGTLink extension:

    • PLUS toolkit configuration file (.plus.xml): configuration file for real-time data acquisition from imaging and tracking devices and various sensors

  • Sandbox extension:

    • Topcon OCT image file (.fda, reading only)

Models

Surface or volumetric meshes. Where a format description below states that the coordinate system can be specified in the file header, the convention described in Specifying the coordinate system in model files is used.

  • VTK Polygonal Data (.vtk, .vtp):

    • Default coordinate system: LPS. Coordinate system (LPS/RAS) can be specified in header.

    • Full color (RGB or RGBA) meshes can be read and written (color must be assigned as point scalar data of unsigned char type and 3 or 4 components).

    • Texture image can be applied using “Texture model” module (in SlicerIGT extension).

  • VTK Unstructured Grid Data (.vtk, .vtu): Volumetric mesh. Default coordinate system: LPS. Coordinate system (LPS/RAS) can be specified in header.

  • STereoLithography (.stl): Format most commonly used for 3D printing. Default coordinate system: LPS. Coordinate system (LPS/RAS) can be specified in header.

  • Wavefront OBJ (.obj):

    • Default coordinate system: LPS. Coordinate system (LPS/RAS) can be specified in header.

    • Some applications (for example, Materialise Mimics and 3-matic) write the length unit of the vertex coordinates into the file header as a comment, such as vertex coordinates are measured in units, where 1 unit = 1000.000000 mm; if this comment is found then the vertex coordinates are automatically scaled to millimeters when the file is loaded (only mm unit is supported).

    • Texture image can be applied using “Texture model” module (in SlicerIGT extension). The non-standard technique of saving vertex color as additional values after coordinates is not supported - if vertex coloring is needed then convert to PLY, VTK, or VTP format using another software.

  • Stanford Triangle Format (.ply):

    • Default coordinate system: LPS. Coordinate system (LPS/RAS) can be specified in header.

    • Full color (RGB or RGBA) meshes can be read and written (color must be assigned to vertex data in uchar type properties named red, green, blue, and optional alpha).

    • Texture image can be applied using “Texture model” module (in SlicerIGT extension).

  • BYU (.byu, .g; reading only): Coordinate system: LPS.

  • UCD (.ucd; reading only): Coordinate system: LPS.

  • ITK meta (.meta; reading only): Coordinate system: LPS.

  • FreeSurfer extension:

    • Freesurfer surfaces (.orig, .inflated, .sphere, .white, .smoothwm, .pial; reading only)

  • SlicerHeart extension:

    • CARTO surface model (.vtk; writing only): special .vtk polydata file format variant, which contains patient name and ID to allow import into CARTO cardiac electrophysiology mapping systems

Specifying the coordinate system in model files

Most mesh file formats have no standard way of storing the anatomical coordinate system, therefore Slicer uses the following convention: the coordinate system is specified by a SPACE=RAS or SPACE=LPS string (following the NRRD space field naming convention) stored in the file header:

  • VTK legacy files (.vtk): in the header comment (second line of the file), for example: 3D Slicer output. SPACE=RAS

  • VTK XML files (.vtp, .vtu): in a string array named SPACE in the field data of the mesh, containing a single value: RAS or LPS

  • STL (.stl): in the file header (the 80-byte header of binary STL files, or the text after solid in ASCII STL files), for example: 3D Slicer output. SPACE=RAS.

  • Wavefront OBJ (.obj): in a comment line, for example: # 3D Slicer output. SPACE=RAS

  • Stanford PLY (.ply): in a comment line in the file header, for example: comment SPACE=RAS

When reading a file, Slicer searches the header text for the SPACE=RAS or SPACE=LPS string (it may appear anywhere within the header comment, surrounding text is ignored); if neither is found then the coordinates are assumed to be in the LPS coordinate system. When writing a file, Slicer always adds the coordinate system specification to the file header. By default, models are written using the LPS coordinate system; this can be changed in the “Coordinate system” option in the Save dialog.

Segmentations

  • Segmentation labelmap representation (.seg.nrrd, .nrrd, .seg.nhdr, .nhdr, .nii, .nii.gz, .hdr): 3D volume (4D volume if there are overlapping segments) with custom fields specifying segment names, terminology, colors, etc.

  • Segmentation closed surface representation (.vtm): saved as VTK multiblock data set, contains custom fields specifying segment names, terminology, colors, etc.

  • Labelmap volume (.nrrd, .nhdr, .nii, .nii.gz, .hdr): segment names can be defined by using a color table. To write segmentation in NIFTI formats, use Export to file feature or export the segmentation node to labelmap volume.

  • Closed surface (.stl, .obj): Single segment can be read from each file. Segmentation module’s Export to files feature can be used to export directly to these formats.

  • SlicerOpenAnatomy extension:

    • GL Transmission Format (.glTF, writing only)

  • Sandbox extension:

    • Osirix ROI file (.json, reading only)

    • sliceOmatic tag file (.tag, reading only)

Transforms

  • ITK HDF transform (.h5): For linear, b-spline, grid (displacement field), thin-plate spline, and composite transforms. Coordinate system: LPS.

  • ITK TXT transform (.tfm, .txt): For linear, b-spline, and thin-plate spline, and composite transforms. Coordinate system: LPS.

  • Matlab MAT file (.mat): For linear and b-spline transforms. Coordinate system: LPS.

  • Displacement field: For storing grid transform as a vector image, each voxel containing displacement vector. Voxel values are in physical space (not in voxels).

    • NRRD (.nrrd, .nhdr): Coordinate system: LPS. Metadata: dimension: 4, sizes: 3 I J K, space directions: none (ix, iy, iz) (jx, jy, jz) (kx, ky, kz), kinds: vector domain domain domain

    • MetaImage (.mha, .mhd): Coordinate system: LPS. Metadata: NDims = 3, DimSize = I J K, ElementNumberOfChannels = 3

    • NIFTI (.nii, .nii.gz). Coordinate system: RAS. Metadata: Number of dimensions: 5. Dimensions: [I, J, K, 1, 3]. Intent code: NIFTI_INTENT_DISPVECT (1006).

  • Displacement field sequence: For storing a sequence of grid transforms as a 4D vector image.

    • NRRD sequence (.seq.nrrd, .nrrd, .nhdr): Coordinate system: LPS.

    • NIFTI (.nii, .nii.gz): Coordinate system: RAS. Metadata: Number of dimensions: 5. Dimensions: [I, J, K, N, 3] (N is the number of frames). Intent code: NIFTI_INTENT_DISPVECT (1006). Only transforms that are defined in “from parent” direction (resampling transforms) can be saved in this format.

  • SlicerRT extension

    • Pinnacle DVF (.dvf)

Markups

  • Markups JSON (.mrk.json): point list, line, curve, closed curve, plane, etc. Default coordinate system: LPS. Coordinate system (LPS/RAS) can be specified in image header. JSON schema is available here.

  • Markups CSV (.fcsv): legacy file format for storing point list. Default coordinate system: LPS. Coordinate system (LPS/RAS) can be specified in image header. This format only stores control point coordinates and a limited set of display properties; use Markups JSON format instead. The file format is deprecated and support for it will be removed in future software versions.

  • Annotation CSV (.acsv): legacy file format for storing markups line, ROI.

Scenes

  • MRML (Medical Reality Markup Language File) (.mrml): MRML file is a xml-formatted text file with scene metadata and pointers to externally stored data files. See MRML overview. Coordinate system: RAS.

  • MRB (Medical Reality Bundle) (.mrb, .zip): MRB is a binary format encapsulating all scene data (bulk data and metadata). Internally it uses zip format. Any .zip file that contains a self-contained data tree including a .mrml file can be opened. Coordinate system: RAS. Note: only .mrb file extension can be chosen for writing, but after that the file can be manually renamed to .zip if you need access to internal data.

  • Data collections in XNAT Catalog format (.xcat; reading only)

  • Data collections in XNAT Archive format (.xar; reading only)

Other

  • Text (.txt, .xml., json)

  • Table (.csv, .tsv)

  • Color tables:

    • Slicer color table (.ctbl, .txt)

    • ITK-Snap label description file (.txt, .label) (reading only) This can be used for loading segmentations that were created in ITK-Snap. The color table must be loaded in the scene first. Then, when the label image file is loaded then in Add Data window select Segmentation in the Description column and select the loaded color table in the Color node column.

  • Volume rendering properties (.vp)

  • Volume rendering shader properties (.sp)

  • Terminology (.term.json, .json): dictionary of standard DICOM or other terms

  • Node sequence (.seq.mrb): sequence of any MRML node (for storage of 4D data)

What if your data is not supported?

If any of the above listed file formats cannot be loaded then report the issue on the Slicer forum.

If you have a file of binary data and you know the data is uncompressed and you know the way it is laid out in memory, then one way to load it in Slicer is to create a .nhdr file that points to the binary file. RawImageGuess extension can be used to explore an unknown data set, determining unknown loading parameters, and generate header file.

You can also ask about support for a particular file format on the Slicer forum. There may be extensions or scripts that can read or write additional formats (any Python package can be installed and used for data import/export).