Main Content

dicomquery

Query PACS server for DICOM metadata

Since R2024b

collapse all in page

Syntax

returnedKey = dicomquery(dConn,level,keysToReturn)
returnedKey = dicomquery(dConn,level,keysToMatch)
returnedKey = dicomquery(dConn,level,keysToMatch,keysToReturn)
returnedKey = dicomquery(___,Root=root)

Description

returnedKey = dicomquery(dConn,level,keysToReturn) queries the PACS server indicated by the dicomConnection object dConn at the specified query level level, for the specified DICOM attributes keysToReturn, and returns the details of each attribute for each DICOM file.

example

returnedKey = dicomquery(dConn,level,keysToMatch) searches all the DICOM files on the PACS server indicated by the dicomConnection object dConn whose details match those specified by the structure keysToMatch at the specified query level level. If successful, the function returns returnedKey as an empty structure, without error.

returnedKey = dicomquery(dConn,level,keysToMatch,keysToReturn) searches all the DICOM files on the PACS server indicated by the dicomConnection object dConn whose details match those specified by the structure keysToMatch at the specified query level level, and returns the details of the specified attributes keysToReturn.

returnedKey = dicomquery(___,Root=root) specifies the root level of the query, in addition to any combination of input arguments from previous syntaxes.

Examples

collapse all

Open Live Script

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

Query the PACS server for stored DICOM files. Display the information of the queried DICOM files.

returnedKey = dicomquery(dConn,"Patient",["PatientID","PatientName"])
returnedKey=1×3 struct array with fields:
    PatientID
    PatientName

Input Arguments

collapse all

PACS server connection object, specified as a dicomConnection object.

Query level, specified as "Patient", "Study", "Series" or "Image". For more information regarding query levels, refer to the DICOM Query/Retrieve Information Model in the DICOM Standard.

Data Types: char | string

Keys to return, specified as a string scalar, string array, character vector, or cell array of character vectors. The level of the keys to return must be equal to or higher than the query level. Each key must be a DICOM attribute. For more information on DICOM attributes, see Registry of DICOM Data Elements.

Data Types: char | string | cell

Keys to match, specified as a structure. The fields of the structure must specify the keys to match. Each key must be a DICOM attribute. For more information on DICOM attributes, see Registry of DICOM Data Elements.

Data Types: struct

Root level of the query, specified as "Patient" or "Study".

Data Types: char | string

Output Arguments

collapse all

Keys returned from the query, with the corresponding details of the matched DICOM files, returned as a structure array. If you specify the keysToReturn argument, each structure contains the fields specified by keysToReturn. If you specify the keysToMatch argument, but not keysToReturn, and the function successfully matches DICOM files to your query, returnedKey is an empty structure array. If the function does not successfully match DICOM files to your query the function returns an error.

Data Types: struct

Version History

Introduced in R2024b

See Also

Objects

Functions

Topics