Upload DICOMs or other resources

First, import the APIHandler class and create an instance: api_handler = APIHandler(...). This class is responsible for interacting with the Datamint server.

Upload resource files

Use the upload_resources() method to upload any resource type, such as DICOMs, videos, and image files:

# Upload a single file
resource_id = api_handler.upload_resources("/path/to/dicom.dcm")

# Upload multiple files at once
resoures_ids = api_handler.upload_resources(["/path/to/dicom.dcm",
                                             "/path/to/video.mp4"]
                                            )

You can see the list of all uploaded resources by calling the get_resources() method:

resources = api_handler.get_resources(status='inbox') # status can be any of {'inbox', 'published', 'archived'}
for res in resources:
    print(res)
# Alternatively, you can use apihandler.get_resources_by_ids(resources_ids)

Group up resources using channels

For a better organization of resources, you can group them into channels:

# Uploads a resource and creates a new channel named 'CT scans':
resource_id = api_handler.upload_resources("/path/to/dicom.dcm",
                                           channel='CT scans'
                                           )

# This uploads a new resource to the same channel:
resource_id = api_handler.upload_resources("/path/to/dicom2.dcm",
                                           channel='CT scans'
                                           )

# Get all resources from channel 'CT scans':
resources = api_handler.get_resources(channel='CT scans')

Upload, anonymize and add a label

To anonymize and add labels to a DICOM file, use the parameters anonymize and labels of upload_resources(). Adding labels is useful for searching and filtering resources in the Datamint platform later.

dicom_id = api_handler.upload_resources(files_path='/path/to/dicom.dcm',
                                        anonymize=True,
                                        labels=['label1', 'label2']
                                        )

Changing the uploaded filename

By default, the filename that is uploaded is the basename of the file. For instance, if you upload a file named ‘path/to/dicom.dcm’, the filename will be ‘dicom.dcm’. To include the path into the filename, use the mung_filename parameter:

# filename='dicom.dcm' (DEFAULT)
resource_ids = api_handler.upload_resources(files_path='path/to/dicom.dcm',
                                            mung_filename=None,
                                            )

# filename='path_to_dicom.dcm'
resource_ids = api_handler.upload_resources(files_path='path/to/dicom.dcm',
                                            mung_filename='all',
                                            )

# filename='to_dicom.dcm'
resource_ids = api_handler.upload_resources(files_path='path/to/dicom.dcm',
                                            mung_filename=1,
                                            )

Download resources

To download a resource, use the download_resource_file() method:

resources = api_handler.get_resources(status='inbox', mimetype='application/dicom')
resource_id = resources[0]['id']

# returns the resource content in bytes:
bytes_obj = api_handler.download_resource_file(resource_id, auto_convert=False)

# Assuming this resource is a dicom file, it will return a pydicom.dataset.Dataset object.
dicom_obj = api_handler.download_resource_file(resource_id, auto_convert=True)

# saves the file in the specified path.
api_handler.download_resource_file(resource_id, save_path='path/to/dicomfile.dcm')

With auto_convert=True, the function uses the resource mimetype to automatically convert to a proper object type (pydicom.dataset.Dataset, in this case.) If you do not want this, but the bytes itself, use the auto_convert=False.

Publishing resources

To publish a resource, use publish_resources():

resources = api_handler.get_resources(status='inbox')
resource_id = resources[0]['id'] # assuming there is at least one resource in the inbox

# Change status from 'inbox' to 'published'
api_handler.publish_resources(resource_id)

To publish to a project, pass the project name or id as an argument:

api_handler.publish_resources(resource_id, project_name='ProjectName')

You can also publish resources while uploading them:

resource_id = api_handler.upload_resources(files_path='/path/to/video_data.mp4',
                                           publish=True,
                                           # publish_to='ProjectName' # optional
                                           )

Upload segmentation

To upload a segmentation, use upload_segmentations():

resource_id = api_handler.upload_resources("/path/to/dicom1.dcm") # or use an existing resource_id
api_handler.upload_segmentations(resource_id,
                                'path/to/segmentation.nii.gz', # Can be a nifti file or an png file
                                 name='SegmentationName')

If your segmentation has multiple classes, you can pass a dictionary mapping pixel values to class names. Let’s say you have a segmentation with 2 classes, where pixel value 0 is background, 1 is ‘tumor’, and 2 is ‘metal’:

class_names = {
    # Do not specify the background class, it is always 0
    1: "tumor",
    2: "metal",
}

api_handler.upload_segmentations(resource_id,
                                'path/to/segmentation.nii.gz', # Can be a nifti file or an png file
                                 name=class_names
                                )

See also the tutorial notebook on uploading data: upload_data.ipynb