Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Add PACS to XNAT

In order for DQR your XNAT to be able to import from a PACS, DQR first needs to know about it. Go to Administer→ Plugin Settings→ DICOM QRS Settings to tell XNAT what PACS you want to be able to connect to. Below is what the take advantage of the functionality provided by the DQR Plugin, you must first set up a working connection to a PACS or DICOM AE. This requires the coordination of two parties – the XNAT Administrator, and the PACS Administrator. In order to complete this process, you will need to have network information and AE Titles for both systems, and each party will have to configure their system to talk to the other.

Step 1: Register PACS in the XNAT system

1. Go to Administer > Plugin Settings > DICOM Query-Retrieve in the site navigation, and find the "Manage DICOM AE (PACS) Connections section looks like after adding a PACS (and then clicking the pencil to edit that PACS to see properties not shown on the main table):

Image Removed

The AE Title should be whatever AE Title is in the configuration of your PACS, the Host should be the URL or IP address of the PACS. You can set it to localhost if the PACS is installed locally on a machine on which you are running XNAT locally. The port is the port XNAT should use to communicate with the PACS.

Queryable determines whether users should be able to query and import from this PACS. Default Q/R AE determines whether this should be the default option when users are given the option of what PACS to import from. There should only be one PACS configured in your XNAT with this set to "Yes". Storable determines whether users should be able to send data from XNAT to this PACS. Default Storage AE determines whether this should be the default option when users are given the option of what PACS to send data to from XNAT. There should only be one PACS configured in your XNAT with this set to "Yes".

Set PACS Utilization Schedule

In the " panel.

2. Click Add New DICOM AE

3. Enter the network information and configuration for this PACS system in the dialog. Here are the fields that must be entered:

FIELDDEFAULTDESCRIPTION
AE Title
This should be the AE Title broadcast by the PACS or DICOM AE you are connecting to
Host

This is a network address, and could be an IP address, "localhost" for a dev setup, or a URL.

Note: The "http/s" protocol is not required

Label
This is used internally by XNAT to identify this PACS in the UI
Port
This is the network port used by the PACS system to accept requests and send or receive data
QueryableNoToggles whether to allow users to send C-FIND queries and C-MOVE requests to this PACS in order to find and import data
Default Q/R AENoIf multiple PACS are configured to be "Queryable", only one can be the "Default" for querying new data. This affects the select menu on the "Import Studies" UI
StorableNoToggles whether to allow users to push data from XNAT to this PACS
Default Storage AENoIf multiple PACS are configured to be "Storable", only one can be the "Default" for storing data. This affects the select menu on the "Send To PACS" UI

4. Click Save to save this configuration.

Your new PACS configuration will now appear in the table. You can go back and edit this configuration at any time by clicking on the highlighted name of the PACS in the table.

image2020-1-6_16-24-39.pngImage Added

Optional Step: Set PACS Utilization Schedule

In a high-use, data-rich environment, PACS Administrators may have specific business rules regarding how much network traffic they want to allow to and from their PACS system. The "Schedule" setting allows XNAT Administrators to restrict all use of each connected PACS to certain hours of the day. You can also throttle the data transfer rate, if desired. 

In the screenshot above of the PACS table, the second column is titled "Schedule" and there is a "Schedule" link in the row for all PACS that you've added. Clicking this link causes a modal to appear that you can use to configure the PACS' utilization:

Image Removed

By default, new PACS start out with a blue bar and a '1' for every hour of every day. If you mouse over the '1', it should say '1 thread @ 100%'. This means that only one study can be imported from a PACS at a time, but once all the data for that study has been received by XNAT, XNAT can immediately ask the PACS for another study. Changing the '1' to '5' would mean that XNAT can have 5 threads performing imports from the PACS at the same time. If you change the 100% to 20%, this means that your thread(s) will at most import for 20% of the time. This is implemented by waiting after each study is imported (20% utilization means that if a study takes 20 seconds to import, the thread will then wait 80 seconds before requesting another study from the PACS). To edit a schedule entry, double click the number or the bar that contains it. You will then see a modal like this:

Image Removed

If you want to allow more simultaneous inputs, you can increase the number of threads. If you want the PACS to be hit with fewer requests for data, you can decrease the utilization %. If you do not want the PACS to be available at all during that time period, you can either delete the schedule entry, or set either the threads or utilization to 0 (setting one to 0 sets them both to 0 since threads do nothing with 0 utilization and utilization does nothing with 0 threads). You can also edit the start and end times of the utilization interval. Any times that you remove from the interval will be set to 0 threads and 0 utilization, so data will not be imported from the PACS during those times. Note, that users will still be able to search the PACS and request data, but the DQR plugin will not issue those import requests to the PACS until the PACS is listed as available again.

Let's consider a case where a PACS is heavily used during work hours Monday-Friday 9AM to 5PM, but is used much less outside those hours. The PACS administrator might be okay with some imports during work hours, but not with a constant stream of imports. One way you could set the administrator's mind at ease would be to set up your XNAT so that it will at most be pulling studies from the PACS 1/20th of the time. You would do this by making utilization intervals for those blocks of time with 1 thread and 5% utilization. During the rest of the week, the PACS administrator is fine with heavy usage, so you could have 5 threads and 100% utilization for those times if you wanted to. The easiest way to set this up would be to click the '+' sign next to the bar for Monday, select start time: 9AM, end time: 5PM, threads: 1, utilization: 5 and click save:

Image Removed

That adds a new interval on Monday between 9AM and 5PM with low utilization (so a gray colored bar), with 1 thread, 100% utilization still existing for the time periods before and after that. You could then do the same thing for Tuesday, Wednesday, Thursday, and Friday. If you think your usage might be high enough that you want more than one thread during other times, you can double click on each time bar that is set to 1 thread, 100% utilization, and change the number of threads to 5 (or whatever you want). This process can be a little tedious if you want very finely grained settings for your PACS. Thankfully, you will only need to set this up once for a given PACS. Make sure to talk to your PACS administrator to find out what level of utilization they are comfortable with.

Regardless of what you put for its utilization schedule, you will still be able to search the PACS and see what's on it, you just won't be able to import anything (import requests will be queued for when it is next available).

Configure DICOM AEs

Something else you will need to configure in XNAT are your SCP receivers. These are how XNAT can receive data from PACS and other sources, such as DICOM Browser. You can find your XNAT's currently configured receivers by going to the top bar and clicking on Administer→ Site Administration→ Advanced XNAT Settings→ DICOM SCP Receivers.

Image Removed

By default in XNAT, there will be a single SCP receiver with the AE Title set to "XNAT", the port set to 8104, custom processing set to disabled, and the identifier set to dicomObjectIdentifier. While these settings work fine for many XNATs, you will need some different settings in order to take advantage of DQR features. You can either edit the existing SCP receiver to make it work well with DQR (the preferred option if the differences described below won't be a problem for non-DQR imports), or create a new receiver just for DQR.

Let's say you decide to edit the existing SCP receiver. The AE Title and port can probably be left as 'XNAT' and 8104 respectively (unless your XNAT is communicating with PACS that are also communicating with other XNATs, in which case you will want a unique AE for your XNAT). You will just need to make sure that the PACS knows about that AE and port so it sends the data to the right place and make sure that the port is open to receive the data. Custom processing is something that should be turned on when using DQR. A change was made to XNAT to support some of the relabeling DQR wants to do to data as it's coming in. In addition to the existing importer, a new one was added that is essentially identical except it lets you configure additional processing steps to be performed on the data. In order to use the import process that is intended to be used with DQR, you will need to turn custom processing on for the SCP receiver(s) you're using for DQR. When you install DQR, there will be two processors enabled by default, a processor for the existing site-level anonymization in XNAT (when custom processing is turned on, site-level anonymization still gets run at the same place in the import process, but is executed by a processor, allowing you to configure its behavior if desired), and a processor for relabeling data. Processors will be discussed in more detail in a later section, but for now all you need to know is that custom processing should be used for DQR. It is needed for some DQR features, and should not result in different behavior for any non-DQR imports to that receiver. We are first introducing this change to the import process on an opt-in basis (through the custom processing toggle), but the plan is to soon change XNAT so that all imports use the new import code.

Another important option in the add/edit receiver modal is the identifier. As discussed in the "DICOM Object Identifiers" section, you will want the receiver used by DQR to be set to use the dqrObjectIdentifier. The behavior of the dqrObjectIdentifier is discussed in the "DICOM Object Identifiers" section, but in short, the Patient's Name is used for the subject label and the Study ID is used for the session label instead of using a variety of fields like the dicomObjectIdentifier does. If the multi-pass approach that the dicomObjectIdentifier uses is needed for other imports into your XNAT, then make sure you create a new receiver for DQR imports rather than repurposing an existing one.

Configure PACS side

.

To edit the Availability Schedule for a PACS, see: DQR Admin: Setting A PACS Availability Schedule



Step 2: Register XNAT in the PACS system

Tip

PACS Administrators are charged with securing highly sensitive patient data, and are naturally extremely concerned about data security. If you are setting up DQR for the first time on a development XNAT instance, it is doubtful that the PACS Administrator will agree to set up a connection to your XNAT. You may want to set up your own development PACS instance to use in testing, before attempting to connect to a production PACS instance. Here is one example: https://github.com/jodogne/OrthancDocker

It is also essential that the PACS you are trying to communicate with is set up so that it can speak with your XNAT. In addition to making sure there are no network issues with your XNAT communicating with the PACS, you will need to make sure that both the XNAT information about the PACS matches the PACS and that the PACS information about XNAT matches XNAT. The Host, AE Title, and Port of the PACS in the XNAT Plugin Settings should match the URL of the PACS and the AE Title and Port it is configured with. For example, say an Orthanc PACS was configured with these properties in it's orthanc.json file:

"DicomAet": "ORTHANC",
"DicomPort": 4242,

You would then want to make sure XNAT Plugin Settings have a PACS with AE Title "ORTHANC" and Port 4242.

The other part of this is that the PACS must know about your XNAT. When you use DQR to request data from a PACS, XNAT tells the PACS to send the data to a specific AE Title. The PACS will then look at its own configuration, see that the requested AE destination is associated with a specific site and a specific port, and send the data to that site and port.

Note: This is why it is sometimes necessary to use an AE Title other than "XNAT" for your XNAT. If you were to try to connect two XNATs to a PACS and both XNATs only had a single receiver at "XNAT:8104", then when the PACS received a request for data to be sent to the "XNAT" AE, there would be no way to configure the PACS to know which XNAT's receiver it should send the data to.

As an example, if you are working with a local Orthanc PACS, you might want your orthanc.json file to have a block like this:

Code Block
"DicomModalities":

...

 {
        "XNAT":

...

 [
            "{AETITLE}",
            "{ADDRESS}",
            "{PORT}"
        ]
    },

This will route any requests that come into the PACS for data to be sent to an AE named "XNAT" to the XNAT:8104 receiver with your specified "{AE TITLE}", to the SCP Receiver receiver using the specified "{PORT}" on the local XNAT.

Note: Different PACS platforms (Orthanc, DCM4CHEE, etc.) will all each have a little bit different configuration (and the means of configuration. The details of those different configurations is out of the scope of this documentation- consult . Consult the documentation for your PACS). The key is making sure that XNAT knows about the PACS' details and the PACS knows about XNAT's details. If you do not have control over the PACS you are wanting to communicate with, you will need to put in a request to the PACS administrator for it to associate your XNAT with the AE Title your XNAT will be sending to the PACS as the destination AE. If you anticipate that your XNAT may one day need to communicate with a PACS that will also be communicating with one or more other XNATs, it can be helpful to give your XNAT's receiver a more unique AE Title. If you leave it set to "XNAT", you may later need to either add another AE solely to communicate with a PACS that already is configured to talk to another XNAT's "XNAT" receiver, or you may need to change the AE title of your receiver and ask all the other PACS your XNAT communicates with to change the AE they have associated with itor work with your PACS Administrator to complete this step.