The most straightforward DICOM loading method is the IServerContext::LoadDicomDirectory() method. This method will load a single DICOM series contained in a single directory. The directory should contain only a single DICOM series: no other files (such as index files or files from other series) should be present in the directory, or loading errors may result. The IServerContext::LoadDicomDirectory() method takes as an output parameter the address of a pointer to an IVolumeDataContext object, and takes as an input parameter the path to the dataset. The IServerContext::LoadDicomDirectory() method will load the series, allocate the IVolumeDataContext object, and fill it with the volume data.

When using the IServerContext::LoadDicomDirectory() method, the target directory should contain only a single DICOM series: no other files (such as index files or files from other series) should be present in the directory, or loading errors may result.

IVolumeDataContext *pVolumeData = NULL;

pServerContext->LoadDicomDirectory(&pVolumeData, "/data/DICOM/dataset1");

Several of the C++ methods in this section make use of ILiteDICOMFileContext objects. The ILiteDICOMFileContext class stores the header data associated with an individual DICOM file. The IServerContext::LoadDICOMFromFileList() and IServerContext::ScanDICOMDirectory() methods are used to build an array of ILiteDICOMFileContext objects that represent either a single DICOM series, or a collection of series in a list or hierarchy of directories. The IServerContext::LoadDICOMFromFileList() method is then used to load the actual DICOM dataset associated with some or all of the ILiteDICOMFileContext objects generated from the IServerContext::LoadDICOMFromFileList() or IServerContext::ScanDICOMDirectory() methods.

A search for DICOM file tags may be performed using the ILiteDICOMFileContext::GetTags() method. This method will search the ILiteDICOMFileContext objects generated from the IServerContext::LoadDICOMFromFileList() or IServerContext::ScanDICOMDirectory() methods. This method takes as input parameters the array of ILiteDICOMFileContext objects generated from a directory search, the number of ILiteDICOMFileContext objects in the array, an array of DICOM_TAG_REQUEST structures that designate a set of DICOM tags to search for, and the number of DICOM_TAG_REQUEST structures in the array. The final parameter is the address of a DICOM_TAG_DATA array that will receive the DICOM tags found in the search.

The DICOM_TAG_REQUEST structure has three members. The DICOM_TAG_REQUEST::m_dataType member is a value from the ENUM_DICOM_TAG_DATA_TYPES enumeration that designates the type of data in the requested tag (integer, float, string, etc.). The DICOM_TAG_REQUEST::m_index member stores the index of the data to be retrieved from the tag. Most DICOM tags have only a single value, so this will generally be 0, but some tags have more than one data value associated with them. The DICOM_TAG_REQUEST::m_tag member is a DICOM_TAG structure that is set with the element and group number (in hexadecimal) associated with the searched-for tag.

The result of the search will be stored in a two dimensional array of DICOM_TAG_DATA objects. The size of each array depends on the number of ILiteDICOMFileContext objects to be searched and the number of DICOM_TAG_REQUEST objects to be searched for. Each DICOM_TAG_DATA object consists of the different data types that may comprise a DICOM tag. The appropriate DICOM_TAG_DATA member field is determined by the data type in the corresponding DICOM_TAG_REQUEST::m_dataType member. See Loading DICOM Data from a Header List for an example of how to use the ILiteDICOMFileContext::GetTags() method.

The IServerContext::LoadDICOMFromFileList() method is used to create an array of ILiteDICOMFileContext objects with information describing the properties of DICOM files that are stored in a list of directories. The IServerContext::LoadDICOMFromFileList() method takes as input parameters an array of character strings representing the directories containing DICOM files to be analyzed, the number of directories stored in the array, and a pointer to the IAllocator object used to allocate the ILiteDICOMFileContext array. The IServerContext::LoadDICOMFromFileList() method takes as an output parameter a pointer to an array that will be filled with ILiteDICOMFileContext object pointers. The output array will have one object pointer per file. The array of ILiteDICOMFileContext objects can then be processed to determine which DICOM files should be loaded. The loading of DICOM files represented by ILiteDICOMFileContext objects is handled by the IServerContext::LoadSeriesFromDICOMList() method, described below.

// Specify directories to scan for DICOM files.

char *dicomPaths[] = { 

   "/data/DICOM/dataset1",

   "/data/DICOM/dataset2"

};

// Get array allocator.

IAllocator *pAllocator;

pLibrary->GetAllocator(HCAP_GENERAL, &pAllocator);

// Load DICOM headers.

ILiteDICOMFileContext **pDicomFileHeaders;

pServerContext->LoadDICOMFromFileList(&pDicomFileHeaders, dicomPaths, 2, pAllocator);

The IServerContext::ScanDICOMDirectory() method is used to recursively scan a directory structure, and to create an array of ILiteDICOMFileContext objects that contain information describing the properties of the identified DICOM files. The IServerContext::ScanDICOMDirectory() method takes as input parameters the path to the root directory to initiate the search, and a pointer to the IAllocator object used to allocate the ILiteDICOMFileContext array. The method takes as output parameters the address of an array of character strings representing the paths to the DICOM files that have been processed by the function, a pointer to an integer containing the number of processed files, and a pointer to an array that will be filled with ILiteDICOMFileContext object pointers. The output array will have one object pointer per file. The array of ILiteDICOMFileContext objects can then be processed to determine which DICOM files should be loaded. The loading of DICOM files represented by ILiteDICOMFileContext objects is handled by the IServerContext::LoadSeriesFromDICOMList() method described below.

ILiteDICOMFileContext **pDicomFileHeaders;

char **pathList;

h_uint32 numFiles;

IAllocator *pAllocator;

pLibrary->GetAllocator(HCAP_GENERAL, &pAllocator);

pServerContext->ScanDICOMDirectory(&pDicomFileHeaders, &pathList, &numFiles, "/data/DICOM/", pAllocator);

The IServerContext::LoadSeriesFromDICOMList() method is used to load a DICOM dataset from an array of ILiteDICOMFileContext objects created from either the IServerContext::LoadDICOMFromFileList() or IServerContext::ScanDICOMDirectory() methods. The IServerContext::LoadSeriesFromDICOMList() method takes as input parameters a pointer to an array of ILiteDICOMFileContext object pointers, a series UID for the files to be loaded, the number of ILiteDICOMFileContext objects in the input array, and the address of an IVolumeDataContext pointer that will receive the volume data from the input dataset. Only files with the specified series UID will be loaded for inclusion in the dataset. Note that this method releases the ILiteDICOMFileContext objects from memory on the server. You may no longer use any of the objects passed in after calling this method.

pServerContext->ScanDICOMDirectory(&pDicomFileHeaders, &pathList, &numFiles, "/data/DICOM/", pAllocator);

// Configure a DICOM_TAG_REQUEST to retrieve the series UID.

DICOM_TAG_REQUEST request;

request.m_dataType = DCTD_STRING;

request.m_index = 0;

request.m_tag.group = 0x0020;

request.m_tag.element = 0x000E;

// We are examining 1 ILiteDICOMFileContext file and have 1 DICOM_TAG_REQUEST. 

DICOM_TAG_DATA tagData[1][1];

// Retrieve the series UID from the ILiteDICOMFileContext array.

pDicomFileHeaders[0]->GetTags(pDicomFileHeaders, 1, &request, 1, &tagData);

// Load the DICOM series with the designated series UID into an IVolumeDataContext object for rendering.

IVolumeDataContext pVolumeData = NULL;

pServerContext->LoadSeriesFromDICOMList(&pVolumeData, 100, pDicomFileHeaders, tagData.string);

All of the C++ API methods discussed above in this section are synchronous methods. They will block until complete. Because loading a large number of DICOM headers or files can be time-consuming, it may not be optimal to use a synchronous blocking function for these operations. Corresponding asynchronous methods to the above synchronous methods can be used instead. These asynchronous methods have similar names to the synchronous method but begin with 'StartJob' and 'FinishJob'. The table below shows the appropriate asynchronous methods that match the corresponding synchronous counterpart.

Each of the 'StartJob' asynchronous methods takes similar parameters to its synchronous counterpart, but also takes as an output parameter the address of an integer that designates a job ID value. This returned job ID value can be used with the IServerContext::GetJobInfo() method as an input parameter to track the progress and status of the asynchronous loading operation. The IServerContext::GetJobInfo() method returns as an output parameter a pointer to a JOBINFO  structure. The JOBINFO::jobprog value stores the job progress. This value will be 0 to 100, representing percentage of job completion, with a value of 100 indicating completion of the job.

All of the 'FinishJob' asynchronous methods take as an output parameter the address of either an IVolumeDataContext or ILiteDICOMFileContext, as appropriate to the individual method. This output parameter stores the result of the asynchronous operation upon completion. The 'FinishJob' methods also take as an input parameter the job ID value associated with the asynchronous operation. Each of the 'FinishJob' methods will block until the asynchronous operation completes.

h_int64 jobID;

// Start the asynchronous loading operation.

pServerContext->StartJobLoadDicomDirectory(&jobID, "/data/DICOM/dataset1");

JOBINFO jobInfo;

while(jobInfo.jobprog < 100 ) {

   // Get loading progress

   pServerContext->GetJobInfo(jobID, &jobInfo);

} 

// Loading process is complete

IVolumeDataContext *pVolumeData = NULL;

pServerContext->FinishJobLoadDicomDirectory(&pVolumeData, jobID);