Loading Scans

This section assumes that you have already installed SpineNet, see Getting Started if you have not already done this.

Scan IO

SpineNet interfaces with scans through the spinenet.io.SpinalScan object. This is a simple wrapper class around the three variables SpineNet needs to run,namely the voxel data (volume), spacing between pixels in each slice and the space between each slice.

class spinenet.io.SpinalScan(volume: array, pixel_spacing: Union[array, list], slice_thickness: Union[float, int])
__init__(volume: array, pixel_spacing: Union[array, list], slice_thickness: Union[float, int]) → None

Initialize general class for a spinal scan to be used be SpineNet.

Parameters

  • volume (np.array) – The volume of the scan voxels (of the orientation height x width x sagittal slices).

  • pixel_spacing (Union[np.array, list]) – The pixel spacing of the scan slices in mm. The order is height, width.

  • slice_thickness (Union[float, int]) – The distance between consecutive slices in mm.

You can create members of this class to be run by SpineNet using the above initialisation method, e.g. by

volume = np.random.rand(512,512,12) # random voxel data for scan; 12 slices of size 512x512
pixel_spacing = [0.5, 0.5] # distance between each pixel is to 0.5mm
slice_thickness = 2.0 # distance between slices is 2.0mm
# initialize scan object
scan = spinenet.io.SpinalScan(volume, pixel_spacing, slice_thickness)

However, it is probably better to use the helper functions for loading in DICOMs as scans; spinenet.io.load_dicoms() and spinenet.io.load_dicoms_from_folder(). Both these scans have similar functions; they load DICOM files into a spinenet.io.SpinalScan which can be then used by the rest of SpineNet’s pipeline.

To use a list of DICOM file paths, use spinenet.io.load_dicoms().

spinenet.io.load_dicoms(paths: List[Union[PathLike, str, bytes]], require_extensions: bool = True, metadata_overwrites: dict = {}) → SpinalScan

Generate SpinalScan from paths to each DICOM slice, with checks such as ensure that the correct tags are present and that scan is sagittal

Parameters

  • paths (List[Union[os.PathLike, str, bytes]]) – list of paths to DICOM files

  • require_extensions (bool) – flag to require that all DICOM files in the paths list have the same .dcm extension

  • metadata_overwrites (dict) – dictionary of metadata to overwrite in the scan. This can be PixelSpacing, SliceThickness and ImageOrientationPatient (which should be sagittal)

Returns

Object representing scan from the DICOM files

Return type

SpinalScan

Alternatively, for a folder containing DICOM files, use spinenet.io.load_dicoms_from_folder().

spinenet.io.load_dicoms_from_folder(path: Union[PathLike, str, bytes], require_extensions: bool = True, metadata_overwrites: dict = {}) → SpinalScan

Load a DICOM scan from a folder containing each of the slices.

Parameters

  • path (Union[os.PathLike, str, bytes]) – path to folder containing dicom slices

  • require_extensions (bool) – if True, requires all dicom files in the folder must have the extension .dcm.

Returns

Object representing scan from the DICOM files

Return type

SpinalScan

Example Scans

To try SpineNet on some example data, you can download the example scans from our server via spinenet.download_example_scan() as follows

os.mkdir('example_scans')
spinenet.download_example_scan('t2_lumbar_scan_1', './example_scans')

# some of the example scans do not have the requisite DICOM headers, so
# we can insert our own values using the `metadata_overwrites` argument
overwrite_dict = {'SliceThickness': [2], 'ImageOrientationPatient': [0, 1, 0, 0, 0, -1]}

# load scan
spinenet.io.load_dicoms_from_folder('example_scans',require_extensions=False, metadata_overwrites=overwrite_dict)
spinenet.download_example_scan(example_scan_name: str, file_path: Union[PathLike, str]) → None

Download & unzip example scan DICOM folders from public server for testing and tutorials. The scans are mostly taken from radiopedia.org and are attributed in the project README.md.

Parameters

  • example_scan_name (str) – The example scan name to download locally from the server. Current options are ‘t2_lumbar_scan_1’, ‘t2_lumbar_scan_2’, ‘stir_whole_spine’

  • file_path – the directory to save the scan name to. For example ‘t2_lumbar_scan_1’ would save to file_path/t2_lumbar_scan_1