How To Download Image Data From XNAT Projects

Users can download image session data via the UI in a variety of ways:

Go to any individual session report page and select Download > Download Images from the actions menu.
Go to the project home page and select Download Images from the actions menu.
Go to any table listing of image sessions (for example, using Browse > Data > MR Sessions in the top navigation or by Using the Advanced Search) and select Options > Download in the data table menu.

Using any of these mechanisms will bring the user to the download UI in the XNAT webapp.

Depending on how many sessions you are downloading, or how granular you want to get concerning which scan or resource files to download, you may consider writing a download script that uses the XNAT REST API instead. See How To Download Files via the XNAT REST API

Downloading Image Sessions via the XNAT UI

The Download Sessions UI consists of a single-screen wizard that walks you through the steps of the process.

Select Sessions to Download From. Each image session found in the project or search listing that you were viewing is listed in the left column.

Select Scan Format and Scan Types. Available scan formats are listed in the center column, with scan types listed below that. Each unique scan type found across all sessions is listed, along with a count of the number of scans of that type. If you find duplicated or redundant scan types in this list, you can use the Scan Type Cleanup functions in XNAT to harmonize your scan type definitions and labels.

Select Download Method. Multiple methods of downloading your selected data are listed in the right hand column. We'll review each of the methods below.

Downloading via the XNAT Desktop Client

The most robust method for downloading large quantities of image data is via the XNAT Desktop Client (DXM). This is an external application that must be installed on the user's local system. When the user submits the data request, XNAT parses the XML catalog entries for each of the selected scan resources and generates a manifest that lists each file that is being requested for download. The user is shown a dialog that contains a "download ID", along with an estimate of the download size.

After the user confirms the download by clicking "Download Via App", XNAT passes that manifest to the Desktop Client, which then works its way through the manifest and downloads each file to a selected location on the user's local system. The Desktop Client shows its progress in a Transfer Monitor.

The XNAT Desktop Client generates its own user session for managing download streams, using an alias token from the logged-in user's credentials. The XNAT user does not need to stay logged into XNAT in order to complete the download when using the Desktop Client.

Downloading a ZIP

The performance or viability of streaming ZIP downloads will be constrained by the size of your selected data, your XNAT server's available memory, and your local storage. We recommend caution when selecting data to download via this method.

XNAT can download image resource files directly to your desktop without the use of an external application, if desired. The XNAT server will stream each resource file into a single ZIP file, which downloads to your local computer. When the user submits the data request, XNAT parses the XML catalog entries for each of the selected scan resources and generates a manifest that lists each file that is being requested for download. The user is shown a dialog that contains a "download ID", along with an estimate of the download size.

After the user confirms the download by clicking "Download ZIP", XNAT begins adding resources from the manifest into a streaming download that uses the browser's native download manager. The user must stay logged in to XNAT to complete this download, but does not need to stay on the Download page.

Downloading an XML Catalog

It may be useful for a user to not actually download the resource files at all, but rather to generate a custom XML catalog that lists only the resources selected. This could be used in a custom download script that uses the REST API. (See How To Download Files via the XNAT REST API.)

An example XML catalog entry looks like this:

CODE

<cat:Catalog>
    <cat:sets>
        <cat:entrySet ID="XNAT_E00014">
            <cat:sets>
                <cat:entrySet ID="RAW">
                    <cat:entries>
                        <cat:entry URI="http://10.1.1.171/data/experiments/XNAT_E00014/scans/2/resources/DICOM/files?format=zip&projectIncludedInPath=true&subjectIncludedInPath=true" format="ZIP"/>
                        <cat:entry URI="http://10.1.1.171/data/experiments/XNAT_E00014/scans/3/resources/DICOM/files?format=zip&projectIncludedInPath=true&subjectIncludedInPath=true" format="ZIP"/>
                        <cat:entry URI="http://10.1.1.171/data/experiments/XNAT_E00014/scans/5/resources/DICOM/files?format=zip&projectIncludedInPath=true&subjectIncludedInPath=true" format="ZIP"/>
                        <cat:entry URI="http://10.1.1.171/data/experiments/XNAT_E00014/scans/6/resources/DICOM/files?format=zip&projectIncludedInPath=true&subjectIncludedInPath=true" format="ZIP"/>
                        <cat:entry URI="http://10.1.1.171/data/experiments/XNAT_E00014/scans/7/resources/DICOM/files?format=zip&projectIncludedInPath=true&subjectIncludedInPath=true" format="ZIP"/>
                        <cat:entry URI="http://10.1.1.171/data/experiments/XNAT_E00014/scans/802/resources/DICOM/files?format=zip&projectIncludedInPath=true&subjectIncludedInPath=true" format="ZIP"/>
                    </cat:entries>
                </cat:entrySet>
            </cat:sets>
        </cat:entrySet>
...

You'll notice that the REST paths contain parameters for file format and structural organization. These parameters and others can be set in REST download actions.

Modifying the Folder Organization of Downloaded Files

There are three options for customizing the folder structure of the files you download (or the XML catalog you generate). These options can be set for any of the file download methods.

Include Project In File Paths – If selected, the outermost folder(s) of the downloaded files will be labeled according to the source project.
Include Subject In File Paths – If selected, sessions will be grouped into subfolders by subject, and labeled by the source project's subject ID.
Simplify Downloaded Archive Structure – If selected, the subfolders "scans" and "resources" that exist in the XNAT file structure will not be included in the downloaded folder structure.

Downloading Individual Files via the Manage Files UI.

If you need to download individual scan or resource files attached to an XNAT Image Session, you can browse the XNAT file system by clicking "Manage Files" in the Actions menu of the image session report page. A popup will open with a file explorer in it.

Clicking on any of the file names will start an HTML-based download of that file. This bypasses the Java applet, but is time-consuming for any series of files.

Downloading Image Session Files via the REST API

If you are comfortable scripting API calls, you will find a great deal more ability to customize your downloads with the available API download parameters.

See: Downloading Image Files via the XNAT API.