Query/Retrieve (Move) Service Examples

The DICOM Query/Retrieve Service provides a mechanism for a service user to query and retrieve the SOP Instances managed by a QR SCP. The QR (Move) SOP classes allow an SCU to request an SCP send matching SOP Instances to a known Storage SCP over a new association. This is accomplished through the DIMSE C-MOVE and C-STORE services.

One limitation of the C-MOVE service is that the Move SCP/Storage SCU must know in advance the details (AE title, IP address, port number) of the destination Storage SCP. If the Move SCP doesn’t know the destination AE then it will usually respond with an 0xA801 status code.

Due to the way pynetdicom is currently implemented it does not support the QR Move SCU being able to also act as the destination Storage SCP. In order to have a destination Storage SCP it is necessary to create it in a separate AE.

Query/Retrieve (Move) SCU

Associate with a peer DICOM Application Entity and request it send all SOP Instances for the patient with Patient ID ‘1234567’ belonging to the series with Study Instance UID ‘1.2.3’ and Series Instance UID ‘1.2.3.4’ to the Storage SCP with AE title b’STORE_SCP’.

from pydicom.dataset import Dataset

from pynetdicom import AE
from pynetdicom.sop_class import PatientRootQueryRetrieveInformationModelMove

# Initialise the Application Entity
ae = AE()

# Add a requested presentation context
ae.add_requested_context(PatientRootQueryRetrieveInformationModelMove)

# Create out identifier (query) dataset
ds = Dataset()
ds.QueryRetrieveLevel = 'SERIES'
# Unique key for PATIENT level
ds.PatientID = '1234567'
# Unique key for STUDY level
ds.StudyInstanceUID = '1.2.3'
# Unique key for SERIES level
ds.SeriesInstanceUID = '1.2.3.4'

# Associate with peer AE at IP 127.0.0.1 and port 11112
assoc = ae.associate('127.0.0.1', 11112)

if assoc.is_established:
    # Use the C-MOVE service to send the identifier
    # A query_model value of 'P' means use the 'Patient Root Query
    #   Retrieve Information Model - Move' presentation context
    responses = assoc.send_c_move(ds, b'STORE_SCP', query_model='P')

    for (status, identifier) in responses:
        print('C-MOVE query status: 0x{0:04x}'.format(status.Status))

        # If the status is 'Pending' then the identifier is the C-MOVE response
        if status.Status in (0xFF00, 0xFF01):
            print(identifier)

    # Release the association
    assoc.release()
else:
    print('Association rejected or aborted')

The responses received from the SCP include notifications on whether or not the storage sub-operations have been successful.

Query/Retrieve (Move) SCP

The following represents a toy implementation of a Query/Retrieve (Move) SCP where the SCU has sent the following Identifier dataset under the Patient Root Query Retrieve Information Model - Move context and the move destination AE title b’STORE_SCP’ is known to correspond to the IP address ‘127.0.0.1’ and listen port number ‘11113’.

ds = Dataset()
ds.QueryRetrieveLevel = 'PATIENT'
ds.PatientID = '1234567'

This is a very bad way of managing stored SOP Instances, in reality its probably best to store the instance attributes in a database and run the query against that.

import os

from pydicom import dcmread
from pydicom.dataset import Dataset

from pynetdicom import AE, StoragePresentationContexts
from pynetdicom.sop_class import PatientRootQueryRetrieveInformationModelMove

# Create application entity
ae = AE(port=11112)

# Add the requested presentation contexts (Storage SCU)
ae.requested_contexts = StoragePresentationContexts
# Add a supported presentation context (QR Move SCP)
ae.add_supported_context(PatientRootQueryRetrieveInformationModelMove)

# Implement the AE.on_c_move callback
def on_c_move(self, dataset, move_aet, context, info):
    """Respond to a C-MOVE request Identifier `ds`.

    Parameters
    ----------
    dataset : pydicom.dataset.Dataset
        The Identifier dataset sent by the peer.
    move_aet : bytes
        The destination AE title that matching SOP Instances will be sent
        to using C-STORE sub-operations. ``move_aet`` will be a correctly
        formatted AE title (16 chars, with trailing spaces as padding).
    context : presentation.PresentationContextTuple
        The presentation context that the C-MOVE message was sent under.
    info : dict
        A dict containing information about the current association.

    Yields
    ------
    addr, port : str, int or None, None
        The first yield should be the TCP/IP address and port number of the
        destination AE (if known) or ``(None, None)`` if unknown. If
        ``(None, None)`` is yielded then the SCP will send a C-MOVE
        response with a 'Failure' Status of ``0xA801`` (move destination
        unknown), in which case nothing more needs to be yielded.
    int
        The second yield should be the number of C-STORE sub-operations
        required to complete the C-MOVE operation. In other words, this is
        the number of matching SOP Instances to be sent to the peer.
    status : pydiom.dataset.Dataset or int
        The status returned to the peer AE in the C-MOVE response. Must be
        a valid C-MOVE status value for the applicable Service Class as
        either an ``int`` or a ``Dataset`` containing (at a minimum) a
        (0000,0900) *Status* element. If returning a ``Dataset`` then it
        may also contain optional elements related to the Status (as in
        DICOM Standard Part 7, Annex C).
    dataset : pydicom.dataset.Dataset or None
        If the status is 'Pending' then yield the ``Dataset``
        to send to the peer via a C-STORE sub-operation over a new
        association.

        If the status is 'Failed', 'Warning' or 'Cancel' then yield a
        ``Dataset`` with a (0008,0058) *Failed SOP Instance UID List*
        element containing the list of the C-STORE sub-operation SOP
        Instance UIDs for which the C-MOVE operation has failed.

        If the status is 'Success' then yield ``None``, although yielding a
        final 'Success' status is not required and will be ignored if
        necessary.
    """
    if 'QueryRetrieveLevel' not in ds:
        # Failure
        yield 0xC000, None
        return

    # Check move_aet is known
    # get_known_aet() is here to represent a user-implemented method of
    #   getting known AEs
    known_aet_dict = get_known_aet()
    if move_aet not in known_aet_dict:
        # Unknown destination AE
        yield (None, None)
        return

    # Assuming known_ae_dict is {b'STORE_SCP       ' : ('127.0.0.1', 11113)}
    (addr, port) = known_ae_dict[move_ae]

    # Yield the IP address and listen port of the destination AE
    yield (addr, port)

    # Import stored SOP Instances
    instances = []
    fdir = '/path/to/directory'
    for fpath in os.listdir(fdir):
        instances.append(dcmread(os.path.join(fdir, fpath)))

    if ds.QueryRetrieveLevel == 'PATIENT':
        if 'PatientID' in ds:
            matching = [
                inst for inst in instances if inst.PatientID == ds.PatientID
            ]

        # Skip the other possible attributes...

    # Skip the other QR levels...

    # Yield the total number of C-STORE sub-operations required
    yield len(instances)

    # Yield the matching instances
    for instance in matching:
        # Pending
        yield (0xFF00, instance)

ae.on_c_move = on_c_move

# Start listening for incoming association requests
ae.start()