Migration from dcm4che2 to dcm4che3

Question

I have used below mentioned API of dcm4che2 from this repository http://www.dcm4che.org/maven2/dcm4che/ in my java project.

dcm4che-core-2.0.29.jar

org.dcm4che2.data.DicomObject  
org.dcm4che2.io.StopTagInputHandler  
org.dcm4che2.data.BasicDicomObject  
org.dcm4che2.data.UIDDictionary  
org.dcm4che2.data.DicomElement  
org.dcm4che2.data.SimpleDcmElement  
org.dcm4che2.net.service.StorageCommitmentService  
org.dcm4che2.util.CloseUtils  

dcm4che-net-2.0.29.jar

org.dcm4che2.net.CommandUtils  
org.dcm4che2.net.ConfigurationException  
org.dcm4che2.net.NetworkApplicationEntity  
org.dcm4che2.net.NetworkConnection  
org.dcm4che2.net.NewThreadExecutor  
org.dcm4che3.net.service.StorageService  
org.dcm4che3.net.service.VerificationService  

Currently i want to migrate to dcm4che3 but, above listed API is not found in dcm4che3 which i have downloaded from this repository http://sourceforge.net/projects/dcm4che/files/dcm4che3/
Could you please guide me for alternate approach?

Answer 1

As you have already observed, the BasicDicomObject is history -- alongside quite a few others.

The new "Dicom object" is Attributes -- an object is a collection of attributes.

Therefore, you create Attributes, populate them with the tags you need for RQ-behaviour (C-FIND, etc) and what you get in return is another Attributes object from which you pull the tags you want.

In my opinion, dcm4che 2.x was vague on the subject of dealing with individual value representations. dcm4che 3.x is quite a bit clearer.

The migration demands a rewrite of your code regarding how you query and how you treat individual tags. On the other hand, dcm4che 3.x makes the new code less convoluted.

On request, I have added the initial setup of a connection to some service class provider (SCP):

// Based on org.dcm4che:dcm4che-core:5.25.0 and org.dcm4che:dcm4che-net:5.25.0
import org.dcm4che3.data.*;
import org.dcm4che3.net.*;
import org.dcm4che3.net.pdu.AAssociateRQ;
import org.dcm4che3.net.pdu.PresentationContext;
import org.dcm4che3.net.pdu.RoleSelection;
import org.dcm4che3.net.pdu.UserIdentityRQ;


// Client side representation of the connection. As a client, I will 
// not be listening for incoming traffic (but I could choose to do so
// if I need to transfer data via MOVE)
Connection local = new Connection();
local.setHostname("client.on.network.com");
local.setPort(Connection.NOT_LISTENING);

// Remote side representation of the connection
Connection remote = new Connection();
remote.setHostname("pacs.on.network.com");
remote.setPort(4100);

remote.setTlsProtocols(local.getTlsProtocols());
remote.setTlsCipherSuites(local.getTlsCipherSuites());

// Calling application entity
ApplicationEntity ae = new ApplicationEntity("MeAsAServiceClassUser".toUpperCase());
ae.setAETitle("MeAsAServiceClassUser");
ae.addConnection(local); // on which we may not be listening
ae.setAssociationInitiator(true);
ae.setAssociationAcceptor(false);

// Device
Device device = new Device("MeAsAServiceClassUser".toLowerCase());
device.addConnection(local);
device.addApplicationEntity(ae);

// Configure association
AAssociateRQ rq = new AAssociateRQ();
rq.setCallingAET("MeAsAServiceClassUser");
rq.setCalledAET("NameThatIdentifiesTheProvider"); // e.g. "GEPACS"
rq.setImplVersionName("MY-SCU-1.0"); // Max 16 chars

// Credentials (if appropriate)
String username = "username";
String passcode = "so secret";
if (null != username && username.length() > 0 && null != passcode && passcode.length() > 0) {
    rq.setUserIdentityRQ(UserIdentityRQ.usernamePasscode(username, passcode.toCharArray(), true));
}

Example, pinging the PACS (using the setup above):

String[] TRANSFER_SYNTAX_CHAIN = {
        UID.ExplicitVRLittleEndian,
        UID.ImplicitVRLittleEndian
};

// Define transfer capabilities for verification SOP class
ae.addTransferCapability(
        new TransferCapability(null,
            /* SOP Class */ UID.Verification,
            /* Role */ TransferCapability.Role.SCU,
            /* Transfer syntax */ TRANSFER_SYNTAX_CHAIN)
);

// Setup presentation context
rq.addPresentationContext(
        new PresentationContext(
                rq.getNumberOfPresentationContexts() * 2 + 1,
                /* abstract syntax */ UID.Verification,
                /* transfer syntax */ TRANSFER_SYNTAX_CHAIN
        )
);

rq.addRoleSelection(new RoleSelection(UID.Verification, /* is SCU? */ true, /* is SCP? */ false));

try {
    // 1) Open a connection to the SCP
    Association association = ae.connect(local, remote, rq);

    // 2) PING!
    DimseRSP rsp = association.cecho();
    rsp.next(); // Consume reply, which may fail

    // Still here? Success!
    // 3) Close the connection to the SCP
    if (as.isReadyForDataTransfer()) {
        as.waitForOutstandingRSP();
        as.release();
    }
} catch (Throwable ignore) {
    // Failure
}

Another example, retrieving studies from a PACS given accession numbers; setting up the query and handling the result:

String modality = null; // e.g. "OT"
String accessionNumber = "1234567890";

//--------------------------------------------------------
// HERE follows setup of a query, using an Attributes object
//--------------------------------------------------------
Attributes query = new Attributes();

// Indicate character set
{
    int tag = Tag.SpecificCharacterSet;
    VR vr = ElementDictionary.vrOf(tag, query.getPrivateCreator(tag));
    query.setString(tag, vr, "ISO_IR 100");
}

// Study level query
{
    int tag = Tag.QueryRetrieveLevel;
    VR vr = ElementDictionary.vrOf(tag, query.getPrivateCreator(tag));
    query.setString(tag, vr, "STUDY");
}

// Accession number
{
    int tag = Tag.AccessionNumber;
    VR vr = ElementDictionary.vrOf(tag, query.getPrivateCreator(tag));
    query.setString(tag, vr, accessionNumber);
}

// Optionally filter on modality in study if 'modality' is provided,
// otherwise retrieve modality
{
    int tag = Tag.ModalitiesInStudy;
    VR vr = ElementDictionary.vrOf(tag, query.getPrivateCreator(tag));
    if (null != modality && modality.length() > 0) {
        query.setString(tag, vr, modality);
    } else {
        query.setNull(tag, vr);
    }
}

// We are interested in study instance UID
{
    int tag = Tag.StudyInstanceUID;
    VR vr = ElementDictionary.vrOf(tag, query.getPrivateCreator(tag));
    query.setNull(tag, vr);
}

// Do the actual query, needing an AppliationEntity (ae),
// a local (local) and remote (remote) Connection, and
// an AAssociateRQ (rq) set up earlier.

try {
    // 1) Open a connection to the SCP
    Association as = ae.connect(local, remote, rq);

    // 2) Query
    int priority = 0x0002; // low for the sake of demo :)
    as.cfind(UID.StudyRootQueryRetrieveInformationModelFind, priority, query, null,
            new DimseRSPHandler(as.nextMessageID()) {

                @Override
                public void onDimseRSP(Association assoc, Attributes cmd,
                                       Attributes response) {

                    super.onDimseRSP(assoc, cmd, response);

                    int status = cmd.getInt(Tag.Status, -1);
                    if (Status.isPending(status)) {
                        //--------------------------------------------------------
                        // HERE follows handling of the response, which
                        // is just another Attributes object
                        //--------------------------------------------------------
                        String studyInstanceUID = response.getString(Tag.StudyInstanceUID);
                        // etc...
                    }
                }
            });

    // 3) Close the connection to the SCP
    if (as.isReadyForDataTransfer()) {
        as.waitForOutstandingRSP();
        as.release();
    }
}
catch (Exception e) {
    // Failure
}

More on this at https://github.com/FrodeRanders/dicom-tools