dicomConnection

Establish connection with PACS server

Since R2024b

Description

Healthcare organizations use the picture archiving and communication system (PACS) for secure storage and transmission of digital medical images and clinical reports. The PACS server stores medical data in the Digital Imaging and Communications in Medicine (DICOM) format. You can establish a connection with a PACS server by creating a dicomConnection object. Further, you can test the connection with the PACS server, and conveniently store, query, and get DICOM data from the server, using the functions associated with the dicomConnection object. The algorithms for the dicomConnection object and its related functions are based on the DICOM Toolkit (DCMTK).

Creation

Syntax

dConn = dicomConnection(peerName,portNum,key,certificate,trustedCertificate)

dConn = dicomConnection(peerName,portNum,EnableTLS=false)

dConn = dicomConnection(___,Name=Value)

Description

dConn = dicomConnection(peerName,portNum,key,certificate,trustedCertificate) establishes a secure Transport Layer Security (TLS) connection with the PACS server host peerName through the port portNum using the specified TLS key, TLS certificate, and the PACS trusted certificate, and returns a dicomConnection object, dConn, with the details of the connection. The peerName, portNum, key, certificate, and trustedCertificate arguments set the PeerName, PortNum, Key, Certificate, and TrustedCertificate properties, respectively.

dConn = dicomConnection(peerName,portNum,EnableTLS=false) establishes a non-TLS connection with the PACS server.

dConn = dicomConnection(___,Name=Value) sets the properties of the dicomConnection object using one or more name-value arguments, in addition to any combination of input arguments from previous syntaxes. For example, ConnectionTimeOut=30 limits the time out period for a connection request to 30 seconds.

Properties

PeerName — DNS name or IP address of PACS server

string scalar | character vector

This property is read-only.

DNS name or IP address of the PACS server, specified as a string scalar or character vector.

Data Types: char | string

PortNum — TCP/IP port number of PACS server

positive integer

This property is read-only.

TCP/IP port number of the PACS server, specified as a positive integer.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Key — Private key file for TLS connection

string scalar | character vector

This property is read-only.

Private key file for a TLS connection, specified as a string scalar or character vector. The file must be in the local folder of your client system with read access. The private key file protects the certificate of your client system and must be kept confidential.

Data Types: char | string

Certificate — Certificate file for TLS connection

string scalar | character vector

This property is read-only.

Certificate file for a TLS connection, specified as a string scalar or character vector. The file must be in the local folder of your client system with read access. The PACS server must have this certificate of the client system in its list of trusted certificates for bidirectional verification.

Data Types: char | string

TrustedCertificate — Trusted certificate file of PACS server

string scalar | character vector

This property is read-only.

Trusted certificate file of the PACS server, specified as a string scalar or character vector. The file must be in the local folder of your client system with read access. The object adds this file to the list of trusted certificates for bidirectional verification.

Data Types: char | string

EnableTLS — TLS connection

true or 1 (default) | false or 0

This property is read-only.

TLS connection, specified as a numeric or logical 1 (true) or 0 (false). Specify EnableTLS as true for a secure connection to the PACS server.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical

AETitle — Title of calling application entity

"MATLAB_QR" (default) | string scalar | character vector

This property is read-only.

Title of calling application entity, specified as a string scalar or character vector. The calling application entity is your client system. Hence, AETitle is the title of your client system in the established connection.

Data Types: char | string

RetrieveAETitle — Title of called application entity

"ANY-SCP" (default) | string scalar | character vector

This property is read-only.

Title of called application entity, specified as a string scalar or character vector. The called application entity is the PACS server. Hence, RetrieveAETitle is the title of the server in the established connection.

Data Types: char | string

ConnectionTimeOut — Time out period for connection request

Inf (default) | positive numeric scalar

This property is read-only.

Time out period for a connection request, in seconds, specified as a positive numeric scalar.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

ResponseMessage — Response message

character vector

This property is read-only.

Response message sent by the PACS server, returned as a character vector. The dicomConnection object updates the response message after each transaction with the PACS server.

Data Types: char

Object Functions

testConnection	Test connection with PACS server
dicomstore	Store DICOM files to PACS server
dicomquery	Query PACS server for DICOM metadata
dicomget	Retrieve DICOM files from PACS server

Examples

Connect to PACS Server

Before running this example, you must get access from the administrator of the PACS server with which you intend to connect. Alternatively, you may consider setting up a local PACS server on your machine, as demonstrated in Working with PACS Server for DICOM Image Retrieval.

Establish a secure TLS connection with the PACS server using the key and certificate of your client system and the trusted certificate of the server. Display the response message of the DICOM connection.

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

I: Requesting Association
I: Association Accepted (Max Send PDV: 16372)
I: Sending Echo Request (MsgID 1)
I: Received Echo Response (Success)
I: Releasing Association

Test the connection with the PACS server.

testConn = testConnection(dConn)

testConn = logical
   1

Store an MRI volume to the PACS server.

dicomstore(dConn,"dog")

Query the PACS server for the patient ID and patient name of the stored DICOM files. Retrieve the DICOM files of the MRI volume using the patient ID.

returnedKey = dicomquery(dConn,"Patient",["PatientID","PatientName"])

returnedKey=1×3 struct array with fields:
    PatientID
    PatientName

filelist = dicomget(dConn,"Patient",returnedKey(1).PatientID);

Read the MRI volume from the retrieved DICOM files.

medVol = medicalVolume(filelist{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]

Version History

Introduced in R2024b