Revision as of 16:27, 14 May 2014 by Evast (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

It is possible for radiology workstations to communicate with XNAT via the DICOM interface.



For uploading data to XNAT, the following settings should be used:

  • Address: bigr-xnat.erasmusmc.nl
  • Port 8104
  • AETitle is XNAT

All data uploaded is send to the prearchive, see here to move this data to the archive.

Project selection

XNAT looks at several DICOM tags to automatically move the data to the correct project, subject and session. It is important that these tags are correctly set!. The following tags are used, and also in this order. If option one is set correctly, it uses this tag, otherwise it continues to option two, and so on.

  1. (0010,4000): Project: {Project_ID}; Subject: {Subject_ID}; Session: {Session_ID}
  2. (0032,4000): Same as 1.
  3. Stores the information in three separate tags:
    1. (0008,1030): Project ID
    2. (0010,0010): Subject ID
    3. (0010,0020): Session ID


  1. Option 1 should include the titles and excluse the brackets. E.g: Project:exoticproject; subject:John_Other; Session: EMC001 . Spaces are not allowed in the values. The values should only contain letters, digits, and the underscore character. The Project_ID should be the abbreviated name for an existing project (source: XNAT Basic Dicom object identification). The Third pass: Custom identification rules in the XNAT manual is not used for our XNAT service.
  2. Option 3 should only include the appropriate values in the listed tags, no labels as in option 1.

If no tags are set, the data will go to the project undefined, and only the administrator can see this data. This automatic selection also only works if the project is created beforehand.


To download data via the DICOM protocol to workstations or applications supporting the DICOM protocol, a special XNAT Gateway has to be installed from here: XNAT Gateway. It is not possible to download images from XNAT via the DICOM interface directly, and therefore this program acts as a gateway between the user's application and XNAT. The gateways acts as a DICOM server and translates the DICOM requests into REST requests which XNAT understands. Vice versa, the XNAT results are converted to DICOM responses for the application. This way, it is possible to search and download images from XNAT into DICOM specific tools.

After downloading XNAT gateway, open the application (gatewaye.jar) with Java (should be in your PATH). When the gateway is opened, two configurations should be set:

  • Current XNAT server:
  • AE Configuration (applications that should have access to the gateway):
    • Gateway settings:
      • AE Title: XNAT
      • Listening port: 4008
      • Allow C-GET retrieve from remote AEs: false
    • Remote devices (add one for an application):
      • Name: Application's name
      • AE Title: [Application short name] . This should be exactly the same as (calling AETitle) in the settings in the application.
      • Hostname:
      • Port: 104 (could be different for specific applications)

Now the server can be started with the button Start in the graphical interface. The logs can be seen when clicking the button View Logs.

In the application that should download the images via DICOM, the gateway has to be added to the application's DICOM interfaces. The exact location of this setting in the graphical interface is application specific, but the following should be set:

  • Name: XNAT Gateway
  • Called AE Title: XNAT . This should be exactly the same as the AETitle of the gateway.
  • Calling AE Title: [Application short name] This should be exactly the same as application's settings of the gateway.
  • Hostname:
  • Port: 4008

[Application short name] should be a short simple name without spaces to identify the application.

Scripted upload (Linux)

It is possible to upload DICOMs from a scripted languages. There are three advantages for this approach:

  • Uploading imaging (derived) data can be done in a larger scripted workflow
  • Uploading large datasets
  • To bypass XNAT project selection in the dicom tags

As described above, XNAT looks at several tags to select the correct project. It may not always be possible or preferred to change the dicom tag(s). With the scripted setup, this can be bypassed because the project can be given separatly. The creation of the project beforehand is still required. The subject and session can also be given. If it is not given, XNAT will look at the DICOM tags.

Pyxnat has no built-in command to upload DICOMs via the prearchive. This means that the session is not built, and therefore not all information is extracted from the DICOMs. If DICOMs are uploaded via Pyxnat like other files, most variables will be empty in the webinterface and the viewer will not work. DICOMs can be correctly uploaded via a plain REST call. The most easy solution is via the following bash file. While it is possible to integrate this into Python or another language, more language speicifc code or frameworks are required, because the file to send has to be MIME encoded (i.e. Python can use pycurl). We suggest to call the bash file from the used programming language, and possible program it later in that language if required.



cookie=`curl -s -k -u $user:$password -X POST $xnat/data/JSESSION`


for u in `find $directory -type f | sed 's/ /\ /g'`
    c= # Sometimes the file does not come over (rare). Therefore we try again.
    until [[ -n "$c" ]]; do
        c=`curl  --cookie JSESSIONID=$cookie -s -k -H 'Content-Type: application/dicom' -X POST "$xnat/data/services/import?
          &content=T1_RAW" --data-binary @$u | tr -d [:cntrl:]`

The above script searches through the given directory and uploads any file it encounteres. 7 Arguments are required for this script, listed in the top. The bash file has been simplified, so no checks are performed. Furthermore, the curl command is silent to prevent a lot of logging. This can be disabled by removing the '-s' parameter. The curl command in the loop is split over three lines in this wiki for readability. In the actual bash file this should be combined to one single line.

It is also possible to upload zip files containing DICOMs with the following script.



cookie=`curl -s -k -u $user:$password -X POST $xnat/data/JSESSION`


c= # Sometimes the file does not come over (rare). Therefore we try again.
until [[ -n "$c" [[; do
    c=`curl  --cookie JSESSIONID=$cookie -k -H 'Content-Type: application/dicom' -X POST "$xnat/data/services/import?
       prearchive=true&overwrite=append&format=DICOM&content=T1_RAW" --data-binary @$file | tr -d [:cntrl:]`

This script does not loop a directory. The fourth argument is therefore the location/filename of the zipfile. Furthermore, note that the url now contains the argument import-handler=DICOM-zip. This will make XNAT extract the zip file online and process it further as a directory. As noted before, the curl command in the loop is split over three lines in this wiki for readability. In the actual bash file this should be combined to one single line.

Both scripts behave similarly as when uploading via the webinterface. After the project is moved from the prearchive to the archive, the snapshots are also created after a few seconds.

To call this script from Pyxnat/Python, the following code can be used:

import subprocess
import sys
output,error = subprocess.Popen(["import2XNat.sh", project, subject, session, sessionDirectory, username, password, xnatUrl], stdout=subprocess.PIPE, stderr = subprocess.PIPE).communicate()
print output
print error

The first argument of the Popen call will be used to construct the bash call. In this list, the first file is the file to execute. The import2XNat.sh file should be the location/file with the above bash script. All the variables after the file argument in the Popen call will be passed as arguments to the bash script. After the Popen call, the output/error stream is flushed in printed. In the bash scripts the curl calls are silent, so no output should be given if it executes correctly.

Scripted upload (Windows)

To accomplish the above in Windows, we developed a similar script for Windows. Copy the following code into a file with the extension .bat and execute it from the command line. The arguments have the same structure as with the Linux code found above. As with the linux version, the curl command in the loop is split over three lines in this wiki for readability. In the actual bash file this should be combined to one single line. To execute the script, you also have to install curl and put it in the same dir as the .bat. You can download it here: http://www.paehl.com/open_source/?CURL_7.36.0 . The correct version should be download (Download WITH SUPPORT SSL for 32bit/x86 or Download x64 version for 64bit/x64).

@echo off

SET project=%1
SET subject=%2
SET session=%3
SET directory=%4
SET user=%5
SET password=%6
SET xnat=%7

SET cookieCommand='curl.exe -s -k -u %user%:%password% -X POST %xnat%/data/JSESSION'
FOR /F %%i IN (%cookieCommand%) DO SET cookie=%%i

SET response=

FOR /R %directory% %%i IN (*.*) do (
  echo "Sending file: " %%i
  SET sendCommand='curl.exe --cookie "JSESSIONID=%cookie%" -s -k -H "Content-Type: application/dicom" -X POST 
    prearchive=true&overwrite=append&format=DICOM&content=T1_RAW" --data-binary @%%i'
  FOR /F "delims=" %%k in (!sendCommand!) DO (
    SET response=!response! %%k
  IF !response! == "" GOTO loop

Bulk uploads

To upload large datasets in XNAT, the dcm4che library can be used. Note that this only works if the project tag is correctly set (see Project selection). This library can be download from here. An example command is (from the bin directory of the download binary version):

dcmsnd XNAT@bigr-xnat.erasmusmc.nl:8104 DIRECTORY_TO_UPLOAD

The format of the argument to dcmsnd, the url, is: AET@address:port . The AET title is XNAT, the address is bigr-xnat.erasmusmc.nl and the port is 8104, also listed above in Upload.

Change that last argument to the directory or file to upload. We suggest to first upload a small dataset to test if is uploads correctly, before sending a large dataset.