sct_label_utils

Utility functions for label images.

usage: sct_label_utils [-i <file>] [-o <file>] [-ilabel <file>]
                       (-add <int> | -create <list> | -create-add <list> | -create-seg <list> | -create-seg-mid <int> | -create-viewer <list> | -cubic-to-point | -disc <file> | -project-centerline <file> | -display | -increment | -vert-body <list> | -vert-continuous | -MSE <file> | -remove-reference <file> | -remove-sym <file> | -remove <list> | -keep <list>)
                       [-msg <str>] [-qc <folder>] [-qc-dataset <str>]
                       [-qc-subject <str>] [-h] [-v <int>]
                       [-profile-time [<file>]] [-trace-memory [<folder>]]

REQUIRED I/O

-i

Input image (Required) Example: t2_labels.nii.gz

OPTIONAL I/O

-o

Output image. Note: Only some label utilities create an output image.

Default: “labels.nii.gz”

-ilabel

File that contain labels that you want to correct. It is possible to add new points with this option. Use with -create-viewer. Example: t2_labels_auto.nii.gz

LABEL FUNCTIONS

-add

Add value to all labels. Value can be negative.

-create

Create labels in a new image. List labels as: x1,y1,z1,value1:x2,y2,z2,value2. Example: 12,34,32,1:12,35,33,2

-create-add

Same as -create, but add labels to the input image instead of creating a new image. Example: 12,34,32,1:12,35,33,2

-create-seg

Create labels on a cord segmentation (or centerline) image defined by -i. Each label should be specified using the form v1,v2 where v1 is value of the slice index along the inferior-superior axis, and v2 is the value of the label. Separate each label with :.

Example: -create-seg 5,1:14,2:23,3 adds three labels at the axial slices 5, 14, and 23 (starting from the most inferior slice).

-create-seg-mid

Similar to -create-seg. This option takes a single label value, and will automatically select the mid-point slice in the inferior-superior direction (so there is no need for a slice index).

This is useful for when you have centered the field of view of your data at a specific location. For example, if you already know that the C2-C3 disc is centered in the I-S direction, then you can enter -create-seg-mid 3 for that label. This saves you the trouble of having to manually specify a slice index using -create-seg.

-create-viewer

Manually label from a GUI a list of labels IDs. Provide a comma-separated list containing individual values and/or intervals. Example: -create-viewer 1:4,6,8 will allow you to add labels [1,2,3,4,6,8] using the GUI.

-cubic-to-point

Compute the center-of-mass for each label value.

Default: False

-disc

Project disc labels (-disc) onto a spinal cord segmentation (-i) within the axial plane to create a labeled segmentation.

  • Note: Unlike sct_label_vertebrae -discfile, this function does NOT involve cord straightening.

  • Note: This method does NOT involve orthogonal projection onto the cord centerline. Details: https://github.com/spinalcordtoolbox/spinalcordtoolbox/issues/3395#issuecomment-1478435265

The disc labeling follows the convention: https://spinalcordtoolbox.com/user_section/tutorials/vertebral-labeling/labeling-conventions.html

-project-centerline

Project disc labels onto the spinal cord centerline.

-display

Display all labels (i.e. non-zero values).

Default: False

-increment

Takes all non-zero values, sort them along the inverse z direction, and attributes the values 1, 2, 3, etc.

Default: False

-vert-body

From vertebral labeling, create points that are centered at the mid-vertebral levels. Separate desired levels with ,. Example: 3,8

To get all levels, enter 0.

-vert-continuous

Convert discrete vertebral labeling to continuous vertebral labeling.

Default: False

-MSE

Compute Mean Square Error between labels from input and reference image. Specify reference image here.

-remove-reference

Remove labels from input image (-i) that are not in reference image (specified here).

-remove-sym

Remove labels from input image (-i) and reference image (specified here) that don’t match. You must provide two output names separated by ,.

-remove

Remove labels of specific value (specified here) from reference image.

-keep

Keep labels of specific value (specified here) from reference image.

OPTIONAL ARGUMENTS

-msg

Display a message to explain the labeling task. Use with -create-viewer

-qc

The path where the quality control generated content will be saved.

-qc-dataset

If provided, this string will be mentioned in the QC report as the dataset the process was run on.

-qc-subject

If provided, this string will be mentioned in the QC report as the subject the process was run on.

MISC ARGUMENTS

-v

Possible choices: 0, 1, 2

Verbosity. 0: Display only errors/warnings, 1: Errors/warnings + info messages, 2: Debug mode.

Default: 1

-profile-time

Enables time-based profiling of the program, dumping the results to the specified file.

If no file is specified, human-readable results are placed into a ‘time_profiling_results.txt’ document in the current directory (’/home/docs/checkouts/readthedocs.org/user_builds/spinalcordtoolbox/checkouts/stable/documentation/source’). If the specified file is a .prof file, the file will instead be in binary format, ready for use with common post-profiler utilities (such as snakeviz).

-trace-memory

Enables memory tracing of the program.

When active, a measure of the peak memory (in KiB) will be output to the file peak_memory.txt. Optionally, developers can also modify the SCT code to add additional snapshot_memory() calls. These calls will ‘snapshot’ the memory usage at that moment, saving the memory trace at that point into a second file (memory_snapshots.txt).

By default, both outputs will be placed in the current directory (’/home/docs/checkouts/readthedocs.org/user_builds/spinalcordtoolbox/checkouts/stable/documentation/source’). Optionally, you may provide an alternative directory (-trace-memory <dir_name>), in which case all files will be placed in that directory instead. Note that this WILL incur an overhead to runtime, so it is generally advised that you do not run this in conjunction with the time profiler or in time-sensitive contexts.