Skip to main content

Python package Upload Python Package PyPI version

slicerio

Python utilities for 3D Slicer interoperability.

The package contains utility functions for reading and writing segmentation files and convenience functions for using 3D Slicer via its web API. More functions will be added in the future.

See this page to learn more about how standard terms can be used to describe content of segmentation files.

Installation

Using pip:

pip install slicerio

Examples

Read segmentation and show some information about segments

import slicerio
import json

segmentation = slicerio.read_segmentation("path/to/Segmentation.seg.nrrd", skip_voxels=True)

number_of_segments = len(segmentation["segments"])
print(f"Number of segments: {number_of_segments}")

segment_names = slicerio.segment_names(segmentation)
print(f"Segment names: {', '.join(segment_names)}")

segment0 = slicerio.segment_from_name(segmentation, segment_names[0])
print("First segment info:\n" + json.dumps(segment0, sort_keys=False, indent=4))

Extract selected segments with chosen label values

Extract segments by terminology

Example for getting a 3D NRRD file that has label values assigned based on standard terminology codes. Terminology is a dict that must specify category and type codes and may optionally also specify typeModifier, anatomicRegion, and anatomicRegionModifier. Each code is specified by a triplet of "coding scheme designator", "code value", "code meaning" in a list.

Coding scheme designator is typically SCT (SNOMED-CT) for clinical images. You can find codes in the SNOMED-CT browser. When code exists for "entire X" and "structure of X" then always use the "structure" code ("entire" code has a very strict meaning that is rarely applicable in practice).

Code meaning (third component of codes, such as "Anatomical Structure", "Ribs", "Right") is informational only, it can be used for troubleshooting or displayed to the user, but it is ignored in information processing (e.g., two codes match if their coding scheme designator and code value are the same even if code meaning is different).

import slicerio

input_filename = "path/to/Segmentation.seg.nrrd"
output_filename = "path/to/SegmentationExtracted.seg.nrrd"
segments_to_labels = [
   ({"category": ["SCT", "123037004", "Anatomical Structure"], "type": ["SCT", "113197003", "Ribs"]}, 1),
   ({"category": ["SCT", "123037004", "Anatomical Structure"], "type": ["SCT", "39607008", "Lung"], "typeModifier": ["SCT", "24028007", "Right"]}, 3)
   ]

segmentation = slicerio.read_segmentation(input_filename)
extracted_segmentation = slicerio.extract_segments(segmentation, segments_to_labels)
slicerio.write_segmentation(output_filename, extracted_segmentation)

Extract segments by name

It is strongly recommended to look up segments by standard terminology codes instead of segment name, as spelling errors and inconsistent use of names often causes mismatch.

import slicerio

input_filename = "path/to/Segmentation.seg.nrrd"
output_filename = "path/to/SegmentationExtracted.seg.nrrd"
segment_names_to_labels = [("ribs", 10), ("right lung", 12), ("left lung", 6)]

segmentation = slicerio.read_segmentation(input_filename)
extracted_segmentation = slicerio.extract_segments(segmentation, segment_names_to_labels)
slicerio.write_segmentation(output_filename, extracted_segmentation)

Get the mask of a segment

import slicerio

segmentation = slicerio.read_segmentation("path/to/Segmentation.seg.nrrd")

# Binary mask (numpy bool array, i, j, k axes) of a segment specified by its ID or name
mask = slicerio.segment_mask(segmentation, "ribs")
ijk_to_lps = segmentation["ijkToLPS"]

Create segmentation file from binary masks

Segments may overlap: each is stored in the first layer where it does not overlap other segments, as 3D Slicer stores them.

import numpy as np
import slicerio

# Image geometry
spacing = [0.5, 0.5, 0.8]
origin = [10, 30, 15]
ijk_to_lps = [[spacing[0], 0., 0., origin[0]],
              [0., spacing[1], 0., origin[1]],
              [0., 0., spacing[2], origin[2]],
              [0., 0., 0., 1.]]

segmentation = slicerio.create_segmentation([100, 120, 150], ijk_to_lps)

ribs = np.zeros([100, 120, 150], bool)
ribs[30:50, 20:60, 70:100] = True
slicerio.add_segment(segmentation, ribs, {"id": "ribs", "color": [0.9, 0.9, 0.6]})

spine = np.zeros([100, 120, 150], bool)
spine[70:90, 80:110, 60:110] = True
slicerio.add_segment(segmentation, spine, {
    "id": "spine",
    "terminology": {
        "contextName": "Segmentation category and type - 3D Slicer General Anatomy list",
        "category": ["SCT", "123037004", "Anatomical Structure"],
        "type": ["SCT", "122494005", "Cervical spine"]}})

slicerio.write_segmentation("path/to/Segmentation.seg.nrrd", segmentation)

Create segmentation file from numpy array

import numpy as np
import slicerio

# Create segmentation with two labels (1, 3)
voxels = np.zeros([100, 120, 150], dtype=np.uint8)
voxels[30:50, 20:60, 70:100] = 1
voxels[70:90, 80:110, 60:110] = 3

# Image geometry
spacing = [0.5, 0.5, 0.8]
origin = [10, 30, 15]

segmentation = {
   "voxels": voxels,
   "encoding": "gzip",
   "ijkToLPS": [[ spacing[0], 0., 0., origin[0]],
                [ 0., spacing[1], 0., origin[1]],
                [ 0., 0., spacing[2], origin[2]],
                [ 0., 0., 0., 1. ]],
   "containedRepresentationNames": ["Binary labelmap", "Closed surface"],
   "segments": [
      {
         "id": "Segment_1",
         "labelValue": 1,
         "layer": 0,
         "color": [0.9, 0.9, 0.6],
         "name": "ribs",
         "terminology": {
            "contextName": "Segmentation category and type - 3D Slicer General Anatomy list",
            "category": ["SCT", "123037004", "Anatomical Structure"],
            "type": ["SCT", "113197003", "Rib"] }
      },
      {
         "id": "Segment_2",
         "labelValue": 3,
         "layer": 0,
         "color": [0.9, 0.9, 0.6],
         "name": "spine",
         "status": "inprogress",
         "terminology": {
            "contextName": "Segmentation category and type - 3D Slicer General Anatomy list",
            "category": ["SCT", "123037004", "Anatomical Structure"],
            "type": ["SCT", "122494005", "Cervical spine"] }
      },
   ]
}

slicerio.write_segmentation("path/to/Segmentation.seg.nrrd", segmentation)

Create segmentation file from NIFTI labelmap image file

input_nifti_filename = "path/to/Segmentation.nii.gz"
output_filename = "path/to/Segmentation.seg.nrrd"

segmentation = slicerio.read_segmentation(input_nifti_filename)

# Specify segment metadata for each label value
# (NIFTI cannot store segment metadata in the image file)
segmentation["segments"] = [
    { "labelValue": 1,
      "color": [0.9, 0.9, 0.6],
      "name": "ribs",
      "terminology": {
          "contextName": "Segmentation category and type - 3D Slicer General Anatomy list",
          "category": ["SCT", "123037004", "Anatomical Structure"],
          "type": ["SCT", "113197003", "Rib"] } },
    { "labelValue": 3,
      "color": [0.9, 0.1, 0.2],
      "name": "spine",
      "terminology": {
          "contextName": "Segmentation category and type - 3D Slicer General Anatomy list",
          "category": ["SCT", "123037004", "Anatomical Structure"],
          "type": ["SCT", "122494005", "Cervical spine"] } },
   ]

slicerio.write_segmentation(output_filename, segmentation)

Convert legacy markup fiducial file (.fcsv) to current format (.mrk.json)

Older versions of 3D Slicer saved point markup nodes as .fcsv files. Current versions use .mrk.json. Use fcsv_to_markups_json to convert:

import slicerio

# Convert in place — writes F_1.mrk.json next to F_1.fcsv
slicerio.fcsv_to_markups_json("path/to/F_1.fcsv")

# Or specify the output path explicitly
slicerio.fcsv_to_markups_json("path/to/F_1.fcsv", "path/to/output.mrk.json")

To read the control points without writing a file:

import slicerio

markups = slicerio.read_markups_fcsv("path/to/F_1.fcsv")
for cp in markups["markups"][0]["controlPoints"]:
    print(cp["label"], cp["position"])

View files in 3D Slicer

The server module allows using Slicer as a data viewer in any Python environment. All files are loaded into a single Slicer instance, which eliminates the wait time for application startup and also allows analyzing, comparing multiple data sets in one workspace. The feature is implemented by using 3D Slicer's built-in Web Server module, which offers data access via a REST API.

For example, an image file can be loaded with the command below. The command starts a new Slicer application instance with the web API enabled.

import os
import slicerio.server

# Load from remote URL
slicerio.server.file_load("https://github.com/rbumm/SlicerLungCTAnalyzer/releases/download/SampleData/LungCTAnalyzerChestCT.nrrd")

# Load from local file
# A Slicer application instance (with Web Server enabled) is automatically started, if it is not running already.
slicerio.server.file_load("path/to/SomeImage.nrrd", slicer_executable=f"{os.environ["LOCALAPPDATA"]}/NA-MIC/Slicer 5.2.0/Slicer.exe")

A segmentation file can be loaded by specifying the SegmentationFile file type:

nodeID = slicerio.server.file_load("path/to/Segmentation.seg.nrrd", "SegmentationFile")

If the loaded file is modified then it can be reloaded from the updated file:

slicerio.server.node_reload(id=nodeID)

Supported file types

  • image files (nrrd, nii.gz, ...): VolumeFile
  • segmentation file (.seg.nrrd, nrrd, nii.gz, ...): SegmentationFile
  • model file (.stl, .ply, .vtk, .vtp, .vtu, ...): ModelFile
  • markup file (.mrj.json): MarkupsFile
  • transform file (.tfm, .h5, .txt): TransformFile
  • spreadsheet file (.csv, .tsv): TableFile
  • text file (.txt, .json, ...): TextFile
  • sequence file (.mrb, .seq.nrrd): SequenceFile
  • Slicer scene file (.mrml, .mrb): SceneFile

Inspect data in 3D Slicer

Metadata of data sets loaded into the server can be obtained using node_properties function:

properties= slicerio.server.node_properties(name="MRHead")[0]
print(properties["ClassName"])
print(properties["ImageData"]["Extent"])

properties = slicerio.server.node_properties(id=segmentationId)[0]
segments = properties["Segmentation"]["Segments"]
for segmentId in segments:
   print(f"Segment name: {segments[segmentId]['Name']} - color: {segments[segmentId]['Color']}")

List of available nodes can be retrieved using node_names and node_idsfunctions:

# Retrieve node names of all images
slicerio.server.node_names(class_name="vtkMRMLVolumeNode")

# Retrieve all node IDs
slicerio.server.node_ids(class_name="vtkMRMLVolumeNode")

Nodes can be removed from the workspace:

# Remove node by name
slicerio.server.node_remove(name="MRHead")

# Clear the whole scene
slicerio.server.node_remove()

Export files from 3D Slicer

Data sets created in Slicer (e.g., segmentations, landmark point sets), which can be retrieved by writing into file.

# Save the node identified by `MRHead` node name, uncompressed, into the specified file.
slicerio.server.file_save("c:/tmp/MRHeadSaved.nrrd", name="MRHead", properties={'useCompression': False})

Metadata

Release files for slicerio 1.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for slicerio 1.3.0
File Size Uploaded Provenance Actions
slicerio-1.3.0.tar.gz 1.9 MB Without provenance Details for slicerio-1.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for slicerio 1.3.0
File Interpreter ABI Platform Actions
slicerio-1.3.0-py3-none-any.whl Python 3 none any Details for slicerio-1.3.0-py3-none-any.whl

Total release size: 2.8 MB

Release files / slicerio-1.3.0.tar.gz

Download URL slicerio-1.3.0.tar.gz
Size 1.9 MB
Tags Source
SHA-256 checksum
How to use checksums
c2d5f736dbab99c8346658149ca32ca9ccf83a62a643fbe98e57a26a2f26022c
BLAKE2b-256 checksum
How to use checksums
47e1d82cce2de1803df4011f7bd4b66e1cf278434e3c5f454d7df861c60c601d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / slicerio-1.3.0-py3-none-any.whl

Download URL slicerio-1.3.0-py3-none-any.whl
Size 814.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
074e782397c6d949a32beef529d34a31c0b5f3cf24bf31536626eb4cb9e014d2
BLAKE2b-256 checksum
How to use checksums
bd61d0400ad18947028fb61912fa16443d84c0f08bdf34e4a126a927a838d335
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for slicerio 1.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page