Working with PACS Server for DICOM Image Retrieval

Since R2024b

This example shows you how to establish a connection with a Picture Archiving and Communication System (PACS) server and retrieve DICOM images from the PACS server. Use a dicomConnection object to set up a connection with a PACS server. Creating the object establishes the connection with the PACS server and returns the details of the connection in the object. Once you establish the connection, you can use the dicomConnection object functions to test the connection, store DICOM images to the PACS, and query or retrieve DICOM images from the PACS server.

Test the connection with the PACS server using the testConnection function.
Store DICOM images to the PACS server using the dicomstore function.
Query attributes of DICOM images, like PatientID, PatientName, StudyInstanceUID, StudyDate, StudyTime, SeriesInstanceUID, Modality, SOPInstanceUID, and InstanceNumber using the dicomquery function.
Retrieve DICOM images from the PACS server using the dicomget function.

This example demonstrates how to perform these processes with a PACS server.

Query and Retrieve DICOM Files at Different Levels in Query/Retrieve Information Model — Query and retrieve DICOM data at different hierarchical levels in the DICOM Query/Retrieve Information Model, such as patient-level data and study-level data.
Query and Retrieve DICOM Files of a Particular Modality — Query and retrieve DICOM images of a particular modality such as MR or CT from the PACS server.

Before running these examples, you must get access from the administrator of the PACS server with which you intend to connect. Alternatively, consider setting up a lightweight, local, standalone PACS server on your machine using the open-source Orthanc service. This example shows how to set up a PACS server connection by using the Orthanc service. The algorithms for the dicomConnection object and its related functions are based on the DICOM Toolkit (DCMTK). MATLAB communicates with PACS servers, such as those set up using the Orthanc service, through DCMTK.

Set Up a Local PACS Server for Testing

You can set up a lightweight, local, standalone PACS server on your machine using the open-source Orthanc service. Download and install Orthanc from the website using the Orthanc documentation.

The default configuration creates these servers.

A local PACS server with the DICOM Application Entity Title (AETitle) of the server set to "Orthanc" that listens on port number 4242.
An HTTP server for the REST API that listens on port number 8042 with the peer name "localhost".

You can modify the default configurations of the local PACS server to suit your needs. To modify the default configuration, you must have administrator privileges and modify the orthanc.json file in the Configuration folder of the Orthanc server installation folder.

To allow the dicomConnection object and related functions to seamlessly access the local PACS server, you must make at least one of these changes to the orthanc.json file and restart the local PACS service.

Add the default client AETitle "MATLAB_QR" of the dicomConnection object, or any other client AETitle you wish to use, to the list of "DicomModalities" allowed to access the server. For example, add the line "sample" : [ "MATLAB_QR", "127.0.0.1", 4242 ] to the list of "DicomModalities".

Set the flags "DicomAlwaysAllowEcho", "DicomAlwaysAllowStore", "DicomAlwaysAllowFind", and "DicomAlwaysAllowGet" to true.

To enable only TLS connections, and block all non-TLS connections, make these changes to the orthanc.json file and restart the local PACS service.

Set the "DicomTlsEnabled" flag to true.
Add the path to the server-side certificate and key to the "DicomTlsCertificate" and "DicomTlsPrivateKey" attributes respectively.
Add the path to the client-side certificate to the "DicomTlsTrustedCertificates" attribute.

For more information related to Orthanc server configuration, refer to the Orthanc Documentation.

Query and Retrieve DICOM Files at Different Levels in Query/Retrieve Information Model

The DICOM Query/Retrieve Information Model has a hierarchy of four levels. The highest level is "Patient", which has attributes such as PatientID and PatientName. The second level is "Study", which has attributes such as StudyInstanceUID, StudyDate, and StudyTime. A patient can have multiple associated studies. The third level is "Series", which has attributes such as SeriesInstanceUID and Modality. A study of a patient can have multiple series of different modalities, such as MR and CT. The lowest level is "Image", which has attributes such as SOPInstanceUID and InstanceNumber. A series can have multiple images of the same modality. You can query the PACS server for information at any of these levels. For more information regarding query/retrieve levels, refer to the DICOM Query/Retrieve Information Model in the DICOM Standard. For more information on DICOM attributes, see the Registry of DICOM Data Elements.

Establish a secure TLS connection with the local PACS server using the key and certificate of your client system and the trusted certificate of the PACS server.

dConn = dicomConnection("localhost",4242,"key.pem","certificate.pem","trusted-certificate.pem");

Test the connection with the PACS server.

testConnection(dConn)

ans = logical
   1

Store an MRI volume to the PACS server.

dicomstore(dConn,"dog")

Query the PACS server for information about the stored DICOM files. While querying the PACS server for information, the level of the attributes that you match or get details for should be equal to or higher than the query level.

Query and Retrieve DICOM Files at the Patient Level

Query the PACS server for the stored MRI volume at the "Patient" query level. Specify to match the attribute PatientName and get the information PatientID. The level of these attributes is "Patient", which is equal to the query level.

info.PatientName = "GORBERG MITZI";
returnedKey = dicomquery(dConn,"Patient",info,"PatientID")

returnedKey = struct with fields:
    PatientID: '241176-001'

Retrieve the DICOM files of the MRI volume at the "Patient" query level. To retrieve the data at the "Patient" level, uniqueID must be the PatientID value. Retrieving data at the "Patient" level retrieves data of all the studies of the patient specified by the uniqueID.

uniqueID = returnedKey.PatientID;
patientLevelList = dicomget(dConn,"Patient",uniqueID,StorageDirectory="patient");

Import one of the images retrieved at the "Patient" level into the workspace.

medVol = medicalVolume(patientLevelList{1})

medVol = 
  medicalVolume with properties:

                 Voxels: [512×512×22 int16]
         VolumeGeometry: [1×1 medicalref3d]
           SpatialUnits: "mm"
            Orientation: "transverse"
           VoxelSpacing: [0.2734 0.2734 3.3000]
           NormalVector: [0 0.0968 0.9953]
       NumCoronalSlices: 512
      NumSagittalSlices: 512
    NumTransverseSlices: 22
           PlaneMapping: ["sagittal"    "coronal"    "transverse"]
               Modality: "MR"
          WindowCenters: [22×1 double]
           WindowWidths: [22×1 double]

Query and Retrieve DICOM Files at the Study Level

Query the PACS server for the stored MRI volume at the "Study" query level. Specify to match the attribute PatientID and get the information StudyInstanceUID. The levels of these attributes are "Patient" and "Study", respectively, both of which are equal to or higher than the query level.

info.PatientID = returnedKey.PatientID;
returnedKey = dicomquery(dConn,"Study",info,"StudyInstanceUID")

returnedKey = struct with fields:
    StudyInstanceUID: '1.2.840.113619.2.244.3596.11880862.13689.1386517653.214'

Retrieve the DICOM files of the MRI volume at the "Study" query level. To retrieve the data at the "Study" level, uniqueID must be the StudyInstanceUID value. Retrieving data at the "Study" level retrieves data of all the series of the study specified by uniqueID.

uniqueID = returnedKey.StudyInstanceUID;
studyLevelList = dicomget(dConn,"Study",uniqueID,StorageDirectory="study");

Import one of the images retrieved at the "Study" level into the workspace.

medVol = medicalVolume(studyLevelList{1})

medVol = 
  medicalVolume with properties:

                 Voxels: [512×512×22 int16]
         VolumeGeometry: [1×1 medicalref3d]
           SpatialUnits: "mm"
            Orientation: "transverse"
           VoxelSpacing: [0.2734 0.2734 3.3000]
           NormalVector: [0 0.0968 0.9953]
       NumCoronalSlices: 512
      NumSagittalSlices: 512
    NumTransverseSlices: 22
           PlaneMapping: ["sagittal"    "coronal"    "transverse"]
               Modality: "MR"
          WindowCenters: [22×1 double]
           WindowWidths: [22×1 double]

Query and Retrieve DICOM Files at the Series Level

Query the PACS server for the stored MRI volume at the "Series" query level. Specify to match the attribute StudyInstanceUID and get the information SeriesInstanceUID and Modality. The levels of these attributes are "Study" and "Series", respectively, both of which are equal to or higher than the query level.

info.StudyInstanceUID = returnedKey.StudyInstanceUID;
returnedKey = dicomquery(dConn,"Series",info,["SeriesInstanceUID","Modality"])

returnedKey = struct with fields:
    SeriesInstanceUID: '1.2.840.113619.2.244.3596.11880862.13689.1386517653.217'
             Modality: 'MR'

Retrieve the DICOM files of the MRI volume at the "Series" query level. To retrieve the data at the "Series" level, uniqueID must be the SeriesInstanceUID value. Retrieving data at the "Series" level retrieves data of all the images of the series specified by uniqueID.

uniqueID = returnedKey.SeriesInstanceUID;
seriesLevelList = dicomget(dConn,"Series",uniqueID,StorageDirectory="series");

Import one of the images retrieved at the "Series" level into the workspace.

medVol = medicalVolume(seriesLevelList{1})

medVol = 
  medicalVolume with properties:

                 Voxels: [512×512×22 int16]
         VolumeGeometry: [1×1 medicalref3d]
           SpatialUnits: "mm"
            Orientation: "transverse"
           VoxelSpacing: [0.2734 0.2734 3.3000]
           NormalVector: [0 0.0968 0.9953]
       NumCoronalSlices: 512
      NumSagittalSlices: 512
    NumTransverseSlices: 22
           PlaneMapping: ["sagittal"    "coronal"    "transverse"]
               Modality: "MR"
          WindowCenters: [22×1 double]
           WindowWidths: [22×1 double]

Query and Retrieve DICOM Files at the Image Level

Query the PACS server for the stored MRI volume at the "Image" query level. Specify to match the attribute SeriesInstanceUID and get the information SOPInstanceUID. The levels of these attributes are "Series" and "Image", respectively, both of which are equal to or higher than the query level.

info.SeriesInstanceUID = returnedKey.SeriesInstanceUID;
returnedKey = dicomquery(dConn,"Image",info,"SOPInstanceUID")

returnedKey=1×22 struct array with fields:
    SOPInstanceUID

Retrieve the DICOM files of the MRI image at the "Image" query level. To retrieve the data at the "Image" level, uniqueID must be the SOPInstanceUID value. Retrieving data at the "Image" level retrieves data of the images specified by uniqueID.

uniqueID = returnedKey(22).SOPInstanceUID;
imageLevelList = dicomget(dConn,"Image",uniqueID,StorageDirectory="image");

Import the image retrieved at the "Image" level into the workspace.

medImg = medicalImage(imageLevelList{1})

medImg = 
  medicalImage with properties:

          Pixels: [512×512 int16]
        Colormap: []
    SpatialUnits: "mm"
       FrameTime: []
       NumFrames: 1
    PixelSpacing: [0.2734 0.2734]
        Modality: 'MR'
    WindowCenter: 924
     WindowWidth: 1849

The DICOM Query/Retrieve Information Model also defines root levels "Patient" and "Study". The query level must be equal to or lower than the root level. If the root level is "Patient", the query level can be "Patient", "Study", "Series", or "Image". However, if the root level is "Study", the query level cannot be "Patient". It must be "Study", "Series", or "Image". If you set the root level as "Study", the patient-level attributes, such as PatientID and PatientName, become the attributes of the study. The default root level for the dicomquery and dicomget functions is "Patient". You can change the root level to "Study" using the root argument of dicomquery or the Root name-value argument of dicomget.

Query and Retrieve DICOM Files of a Particular Modality

Establish a secure TLS connection with the local PACS server using the key and certificate of your client system and the trusted certificate of the PACS server.

dConn = dicomConnection("localhost",4242,"key.pem","certificate.pem","trusted-certificate.pem");

Test the connection with the PACS server.

testConnection(dConn)

ans = logical
   1

Query the PACS server directly at the "Series" query level to get the SeriesInstanceUID of all series that can contain MR images, irrespective of the study or the patient.

clear info
info.Modality = "MR";
returnedKey = dicomquery(dConn,"Series",info,"SeriesInstanceUID")

returnedKey=1×3 struct array with fields:
    SeriesInstanceUID

Using the obtained SeriesInstanceUID values, query the PACS server at the "Image" query level to get the SOPInstanceUID of a particular MR image.

info.SeriesInstanceUID = returnedKey.SeriesInstanceUID;
returnedKey = dicomquery(dConn,"Image",info,"SOPInstanceUID")

returnedKey=1×22 struct array with fields:
    SOPInstanceUID

Retrieve the DICOM files of the MR image at the "Image" query level by specifying the unique SOPInstanceUID.

uniqueID = returnedKey.SOPInstanceUID;
imageLevelList = dicomget(dConn,"Image",uniqueID,StorageDirectory="image");

Import the retrieved image into the workspace.

medImg = medicalImage(imageLevelList{1})

medImg = 
  medicalImage with properties:

          Pixels: [512×512 int16]
        Colormap: []
    SpatialUnits: "mm"
       FrameTime: []
       NumFrames: 1
    PixelSpacing: [0.2734 0.2734]
        Modality: 'MR'
    WindowCenter: 985
     WindowWidth: 1971