Cloud ASHS Command-Line Tutorial

This tutorial assumes that you are using the ASHS-PMC atlas. Make sure that your MRI data is compatible with this atlas. The procedure is nearly identical for other ASHS atlases based on the combination of T2-weighted and T1-weighted MRI.


Step 1. Create an ITK-SNAP workspace

To send your images to the cloud, you need to create an ITK-SNAP workspace that contains the T2-weighted and T1-weighted images. Here we create the workspace using command-line tools. You can also create the workspace using the ITK-SNAP GUI.

We assume that your MRI scans are named t2_oblique.nii and t1_wholebrain.nii and that these files are in the current directory open in your terminal.

Enter the following command to create a workspace containing these files

itksnap-wt -layers-set-main t2_oblique.nii -tags-add T2-MRI \

-layers-add-anat t1_wholebrain.nii -tags-add T1-MRI \

-layers-list -o mywork.itksnap

This command adds the T2 image to a blank workspace and assigns it the tag "T2-MRI", then adds the T1 image as an additional image and assigns it the tag "T1-MRI", prints out the contents of the workspace, and finally saves the workspace to a file called mywork.itksnap.

Obtain a login token for ITK-SNAP DSS

Before you can send tasks to the distributed segmentation services (DSS) system, you need to authenticate. First, enter this command:

itksnap-wt -dss-auth https://dss.itksnap.org

Then you will need to follow the link printed on the command line, login using your Google account, and paste the token you get on the web page back into the command line prompt.

Create a Ticket for Cloud ASHS

Run the command below to list the services currently available on the cloud:

itksnap-wt -dss-services-list

  • The listing of the services (see figure) includes service name, version, description, and a unique code in the second column that identifies each service. Select and copy the code for the ASHS-PMC service (if there are multiple versions, choose the latest one)

The following command will send the workspace to the cloud and will create a numbered "ticket". Instead of [service_code], paste the unique code of the ASHS-PMC service (see figure).

itksnap-wt -i mywork.itksnap -dss-tickets-create [service_code]

  • It may take a minute or two for the workspace to be uploaded to the server

  • If successful, the number of the ticket will be printed after the 2> prompt

Listing the available services

Creating a ticket (this ticket has number 5)

Monitoring Ticket Status

Once a ticket is created, the easiest way to monitor its status is using the following command:

itksnap-wt -dss-tickets-wait [ticket-id]

  • When you run this command, it will not return until the ticket has finished running.

    • If you want the command to return immediately, enter 0 after the ticket id.

    • You can always interrupt the command using Control-C key. Doing so will not interrupt the processing of your ticket, just the command that monitors progress.

  • The command will present you with log messages and links to image attachments that you can view to see intermediate ASHS results

  • You can submit additional tickets while a ticket is being processed

Output of the -dss-tickets-wait command

Following one of the links shows intermediate results (registration between ASHS template, T1-MRI and T2-MRI)

Downloading ASHS Segmentation Results

Once a ticket completes successfully, you can download the results as an ITK-SNAP workspace. You will need to specify the directory where you want the new workspace to be placed.

itksnap-wt -dss-tickets-download [ticket-id] [directory]

  • The workspace is saved as an ticket_XXXX.itksnap file that can be opened using the ITK-SNAP GUI

Output of the download command

Examining ASHS Results

The easiest way to examine ASHS results is to load the workspace downloaded from the server into the ITK-SNAP user interface.

  • The workspace will contain multiple segmentation layers. You can access the different segmentation layers using the Layer Inspector in ITK-SNAP. See the table below for the explanation.

Viewing segmentation results in ITK-SNAP