3 Overview of DICOM Development

This chapter briefly describes developer and administrator tasks that are related to developing applications using Oracle Multimedia DICOM.

Because Oracle Multimedia DICOM is fully functional after installing Oracle Multimedia, developers can begin writing applications immediately using the following application programming interfaces (APIs):

ORDDicom object API
DICOM data model utility API
DICOM relational API
DICOM Java API

Administrators can assist developers by inserting or deleting configuration documents from the data model repository. To accomplish these tasks, administrators can use the ORD_DICOM_ADMIN data model repository API.

Oracle Multimedia DICOM provides capabilities for a number of operations related to DICOM content. For example, administrators can review the Oracle-defined configuration documents in the DICOM data model repository before determining whether to add user-defined documents for your environment. Using information views or invoking data model utility functions, administrators can obtain attributes and other detailed information about these configuration documents. Users can also work directly with the DICOM content, metadata attributes, and other objects to perform various operations.

This chapter includes the following sections:

Loading the Repository
Accessing Information about Documents in the Repository
Loading DICOM Content
Extracting DICOM Metadata
Searching and Retrieving DICOM Attributes
Writing and Editing DICOM Metadata
Processing, Converting, and Compressing DICOM Image Data
Creating DICOM Images from Secondary Capture Images
Validating Conformance with DICOM Constraints
Protecting Private Patient Data

Table 3-1 provides cross-references to other locations within the Oracle Multimedia documentation set where you can access additional information about topics mentioned in this chapter.

Table 3-1 Additional References for Users

Topic	More Information
Reference information for public information views	Chapter 4
Reference information for administrator information views	Chapter 9
Reference information for the DICOM data model utility API	Chapter 4
Reference information for the ORDDicom object API	Chapter 5
Reference information for the DICOM relational API	Chapter 6
Reference information for the ORD_DICOM_ADMIN data model repository API	Chapter 9
Reference information for the DICOM Java API	Oracle Multimedia DICOM Java API Reference
Examples of operations on DICOM content	Chapter 7
Examples of administrative operations in the data model repository	Chapter 10
Information about writing configuration documents	Chapter 11
Listings of the DICOM XML schemas	Appendix B

After installation, each database includes a set of default configuration documents in the Oracle Multimedia DICOM data model repository. See Table 2-1 for a list of these documents.

After installation, administrators can add configuration documents that are specific to a particular organization for the following types of documents:

Anonymity documents - XML documents that can be used to specify the set of attributes to be made anonymous as well as the actions to be taken to make those attributes anonymous.
Constraint documents - XML documents that define a collection of rules, including the relationships and semantic constraints of attributes not expressed by the DICOM metadata schema, to validate the conformance of DICOM content with the DICOM standard.
Mapping documents - XML documents that define how each attribute maps to a particular element in an XML metadata document, and determines the structure of DICOM metadata documents.
Preference documents - XML documents that define run-time parameters, such as turning the logging of warning messages on or off or specifying categories of error messages.
Private dictionary documents - XML documents that can be used to extend the standard dictionary document definitions.
Standard dictionary documents - XML documents that can be used to reflect updates to the DICOM standard.
UID definition documents - XML documents that list the unique identifiers (UIDs) defined by the DICOM standard.

See Appendix A and Chapter 11 for more information about these documents.

See Part III, DICOM Administration for more information about managing configuration documents in the DICOM repository.

3.1 Loading the Repository

At the start of every database session, users and administrators must load the data model repository from the database into memory structures. Users load the data model by calling the setDataModel( ) procedure. Administrators load the data model by calling either the setDataModel( ) procedure or the editDataModel( ) procedure.

After loading the repository into memory, users and administrators can call the setDataModel( ) procedure whenever the application needs to see new data model changes.

Note:

Users and administrators must call the setDataModel( ) procedure before calling any other DICOM methods, functions, or procedures.

Using the DICOM data model utility in the ORD_DICOM package, call the setDataModel( ) procedure as follows:

exec ord_dicom.setdatamodel;

See setDataModel( ) Procedure in Chapter 4 (and editDataModel( ) Procedure in Chapter 9) for reference information.

3.2 Accessing Information about Documents in the Repository

A number of information views are available to users of the DICOM repository. These information views provide details about the documents in the repository, including names of documents, types of documents, names of constraints, and constraint validation messages.

Table 3-2 lists the public information views that are available to users (and administrators).

Table 3-2 Public Information Views

Name	Access Category
orddcm_conformance_vld_msgs	Public (messages for user's schema only)
orddcm_constraint_names	Public
orddcm_document_types	Public
orddcm_documents	Public

Users (and administrators) commonly use the orddcm_documents and orddcm_document_types views to view details for the documents in the repository. The orddcm_documents view lists details of the documents stored in the repository. The orddcm_document_types view identifies the supported Oracle Multimedia DICOM document types with a list of codes.

Two other public information views are also available that provide information about constraints. The orddcm_constraint_names view lists the names of the constraints installed in the repository. The orddcm_conformance_vld_msgs view lists the constraint messages that are generated for a set of constraints during a validation operation. This view lists only the constraint messages for the current user.

See Chapter 4 for details about public information views.

For administrators only, Oracle Multimedia DICOM provides the orddcm_document_refs information view. This view lists the documents in the repository that are referenced by other documents in the repository. See orddcm_document_refs in Chapter 9 for details about this administrator view.

3.3 Loading DICOM Content

You can use the SQL*Loader utility to load DICOM content into existing tables in Oracle Database.

To load DICOM content, first you must create a table with the appropriate columns and initialize those columns. Then, call the SQL*Loader utility and load the DICOM content from your data files into the table columns as SecureFile LOBs (see Oracle Multimedia User's Guide). Before performing any operations on the DICOM content, you must call the setDataModel( ) procedure to load the DICOM data model.

After the DICOM content is loaded, you can perform other operations, such as extracting DICOM metadata, searching and retrieving DICOM attributes, writing and editing DICOM metadata, creating thumbnail images, validating the conformance of your DICOM content, or making private DICOM content anonymous.

See Section 7.3 for examples that show how to use the SQL*Loader utility to load DICOM content and then make specific metadata attributes in the DICOM content anonymous.

See Oracle Database Utilities for more information about using the SQL*Loader utility to load objects and LOBs into Oracle Database.

3.4 Extracting DICOM Metadata

Oracle Multimedia DICOM provides support for extracting metadata from DICOM content. By searching the extracted metadata, applications can search the DICOM content.

To extract all the DICOM attributes into an XML document that conforms to the default metadata XML schema, first call the setProperties( ) method to store the extracted metadata XML document into the metadata attribute of the ORDDicom object. The default metadata XML schema defines a complete and generalized data model for storing DICOM attributes. A customized metadata schema and corresponding mapping document that is customized for your specific application may yield better performance for indexing and searching than the generalized, default metadata schema. Your custom schemas and mapping documents can be used to define frequently searched DICOM attributes within a hierarchical structure that is optimized for searching.

To extract the DICOM attributes into an application-specific XML document in XMLType, call the extractMetadata( ) method and specify the application-specific mapping document. The resulting application-specific metadata XML document can be stored in a column of the same table where the ORDDicom object is stored. This metadata column can be bound to the application-specific XML schema.

3.4.1 Extracting Metadata - Administrator Tasks

As an administrator, perform the following tasks to initiate the process of extracting DICOM metadata:

Design the XML schema for the extracted metadata. Generally, the most frequently searched DICOM attributes are included in the mapped section of the XML schema.

See Appendix B for more information about XML schemas.
Register the schema with Oracle XML DB as a global XML schema. (See Example 10-1 for a sample of this task.)

See Oracle XML DB Developer's Guide for more information about registering XML schemas.
Create the mapping document for the metadata XML schema.

See Section 11.2.3 for detailed information about creating mapping documents.
Load the mapping document into the data model repository.

See Section 8.5 for information about inserting mapping documents into the repository.

3.4.2 Extracting Metadata - Developer Tasks

As a developer, perform the following tasks to complete the process of extracting DICOM metadata:

Query the orddcm_documents view to ensure that the mapping document is loaded and available.
```
select * from orddcm_documents;
```
See orddcm_documents in Chapter 4 for reference information about this view.
Call the extractMetadata( ) method to extract metadata into an XML metadata document by specifying the name of the mapping document and the appropriate parameters.

See extractMetadata( ) in Chapter 5 for reference information about this method.
Store the returned XML metadata document in a column in the database that is bound to the application-specific XML schema for later searching.

See Oracle XML DB Developer's Guide for more information about this task.

3.5 Searching and Retrieving DICOM Attributes

Oracle Multimedia DICOM provides support for searching and retrieving DICOM attributes .

To extract the SOP instance UID, SOP class UID, study instance UID, and series instance UID attributes into ORDDicom object attributes, first call the setProperties( ) method to populate the attributes of the ORDDicom object. These DICOM attributes can be easily retrieved from within the ORDDicom object. To make searching faster, these attributes can also be indexed by creating indexes on the corresponding object attributes. (See setProperties( ) in Chapter 5 for reference information.)

To search and retrieve attributes within the metadata XML document, call either of these SQL functions: extractValue( ) or extract( ) by specifying the XPath expression for the attributes. (See Oracle Database SQL Language Reference for reference information.) To make searching faster, the attributes in the metadata XML document can also be indexed. (See Oracle XML DB Developer's Guide for more information about indexing XMLType data.)

To retrieve a single DICOM attribute, you can call either the getAttributeByTag( ) or getAttributeByName( ) method. (See getAttributeByTag( ) and getAttributeByName( ) in Chapter 5 for reference information.) This process is not recommended for large tables, or for frequent retrievals of attributes. However, if you do use this process, Oracle recommends building function-based indexes on these methods to make searching faster.

Note:

Before you can retrieve DICOM attributes, you must call the setProperties( ) method to populate the attributes of the ORDDicom object.

3.6 Writing and Editing DICOM Metadata

Oracle Multimedia DICOM provides support for creating new ORDDicom objects from existing ORDDicom objects with metadata embedded within the DICOM content that has been modified or overwritten. The writeMetadata( ) method creates a new copy of the ORDDicom object from the original ORDDicom object and the modified metadata. The original ORDDicom object is preserved.

Perform the following tasks to write and edit DICOM metadata:

Extract the DICOM metadata from DICOM content by calling the extractMetadata( ) method, using the Oracle default mapping document.

See extractMetadata( ) in Chapter 5 for reference information about this method.
Add or modify DICOM attributes in the extracted metadata XML document.

See Chapter 8 for information about working with DICOM metadata in XML documents.
Create an empty ORDDicom object using an empty ORDDicom constructor as the placeholder for the new DICOM content.

See ORDDicom Constructors in Chapter 5 for reference information about constructors.
Call the writeMetadata( ) method to write the modified metadata XML document and the DICOM content from the original ORDDicom object into the newly created ORDDicom object. The metadata XML document is used to overwrite the metadata in the DICOM content and object attributes of the new ORDDicom object.

See writeMetadata( ) in Chapter 5 for reference information about this method.

3.7 Processing, Converting, and Compressing DICOM Image Data

Oracle Multimedia DICOM provides the processCopy( ) method to copy and process the image in the DICOM content and save it as DICOM format or another image format, in accordance with the specified commands. The processCopy( ) method creates a new image and preserves the original DICOM image.

The following list summarizes the processing, converting, and compressing operations supported by Oracle Multimedia DICOM, and includes examples of the command parameter of the processCopy( ) method that corresponds to each operation.

Create a JPEG thumbnail image. For example:
```
'fileFormat=jpeg, maxScale=100 100'
```
Create a JPEG image of the same size as the original DICOM image. For example:
```
'fileFormat=jpeg'
```
Compress the image content within the DICOM content. For example:
```
'compressionFormat=jpeg'
```
Retrieve a specified frame from DICOM multiframe content. For example:
```
'frame=10'
```
Cut a specified region of a DICOM image. For example:
```
'cut=20 20 100 100'
```

See Chapter 5 for reference information about the processCopy( ) methods and supported commands.

3.8 Creating DICOM Images from Secondary Capture Images

Oracle Multimedia DICOM provides the relational procedure createDICOMImage( ) to create DICOM format images from images in formats such as JPEG or TIFF in addition to DICOM metadata in data type XMLType.

Perform the following tasks to create DICOM format images from secondary images and DICOM metadata:

Load the image into a BLOB, or define the image as a BFILE type.
Create an XMLType object from the DICOM metadata of the corresponding image.
Create an empty BLOB object as the placeholder for the new DICOM image.
Create the DICOM format image using the createDICOMImage( ) procedure.

See Chapter 6 for reference information about the createDICOMImage( ) procedure.

3.9 Validating Conformance with DICOM Constraints

Oracle Multimedia DICOM provides support to validate the conformance of your DICOM content, according to DICOM specified constraints, with the following method: isConformanceValid( ). Use this method to check if the embedded DICOM content conforms to a specific set of constraints.

DICOM content can come from many sources. And, this content may or may not be created in accordance with the DICOM standard. Before you decide to store DICOM content in your repository, you may want to check for specific attributes, such as a patient's sex. As defined in the Patient Module Attributes of the DICOM standard, this attribute can have the following values: M (male), F (female), or O (other). You can define constraint rules to check for correct values for specific attributes, such as a patient's sex. Or, you can define a custom set of constraint rules and then ensure that all DICOM content in your repository conforms to those rules.

Conformance constraints are a collection of rules to use for validating the conformance of DICOM content with the DICOM standard and other organization-wide guidelines. These rules are specified in an XML document called a constraint document, which is stored in the repository. The default constraint document shipped with Oracle Multimedia DICOM defines rules that enforce conformance with parts of the DICOM standard.

After installation, you can define constraint documents to include user-defined constraint rules that are specific to your organization. To see a list of constraint names, query the information view orddcm_constraint_names.

During conformance validation, if a constraint rule was defined to generate messages for a specified predicate condition, these messages are generated to indicate the predicate conditions. To see a list of these constraint messages, query the information view orddcm_conformance_vld_msgs.

See Section 3.2 for more information about public information views.

Regardless of the interface you use, validating the conformance of DICOM content requires a combination of administrator and developer tasks. The following subsections describe these tasks. Administrator tasks must always be performed first.

3.9.1 Validating Conformance - Administrator Tasks

As an administrator, perform the following tasks to initiate the process of validating the conformance of DICOM content:

Create a constraint document for your organization. This is the document where you define constraint rules to generate messages for specified predicate conditions.

Example 3-1 shows the constraint rule for the Patient Module of the DICOM standard, which is defined in the Oracle-installed constraint document ordcmcmd.xml.

Example 3-1 Constraint Rule for the Patient Module

<GLOBAL_RULE name="PatientModule">
   <DESCRIPTION>
     A subset of Patient Module defined in DICOM standard, 
     PS 3.3-2007, Table C.7-1
   </DESCRIPTION>
   <PREDICATE>
     <BOOLEAN_FUNC operator="notEmpty">
       <ATTRIBUTE_TAG>00100040</ATTRIBUTE_TAG>
     </BOOLEAN_FUNC>
   </PREDICATE>
   <PREDICATE>
     <DESCRIPTION>Patient's Sex</DESCRIPTION>
     <RELATIONAL operator="in">
       <ATTRIBUTE_TAG>00100040</ATTRIBUTE_TAG>
       <STRING_VALUE>M</STRING_VALUE>
       <STRING_VALUE>F</STRING_VALUE>
       <STRING_VALUE>O</STRING_VALUE>
     </RELATIONAL>
   </PREDICATE>
   <PREDICATE>
     <DESCRIPTION>Referenced patient sequence constraint</DESCRIPTION>
     <LOGICAL operator="derive">
       <PREDICATE>
         <BOOLEAN_FUNC operator="occurs">
           <ATTRIBUTE_TAG>00081120</ATTRIBUTE_TAG>
         </BOOLEAN_FUNC>
       </PREDICATE>
       <PREDICATE>
         <LOGICAL operator="and">
           <PREDICATE>
             <BOOLEAN_FUNC operator="notEmpty">
               <ATTRIBUTE_TAG>00081120.00081150</ATTRIBUTE_TAG>
             </BOOLEAN_FUNC>
           </PREDICATE>
           <PREDICATE>
             <BOOLEAN_FUNC operator="notEmpty">
               <ATTRIBUTE_TAG>00081120.00081155</ATTRIBUTE_TAG>
             </BOOLEAN_FUNC>
           </PREDICATE>    
         </LOGICAL>
       </PREDICATE>
     </LOGICAL>
   </PREDICATE>
   <ACTION action="log" when="false">Validation error: missing mandatory attribute for patient module</ACTION>
   <ACTION action="warning" when="false">Warning: validation failure</ACTION>
 </GLOBAL_RULE>

See Section 11.2.2 for information about how to create constraint documents.

Load the constraint document into the data model repository.

See Section 8.5.1 for information about inserting constraint documents into the repository.

3.9.2 Validating Conformance - Developer Tasks

As a developer, perform the following tasks to complete the process of validating the conformance of DICOM content against your constraint rules:

Query the orddcm_constraint_names view to see the list of available constraint names for your organization as follows:
```
select * from orddcm_constraint_names;
```
See orddcm_constraint_names in Chapter 4 for reference information about this view.
Call the isConformanceValid( ) method to check the conformance of your DICOM content as follows:
```
select t.dicom_src.isConformanceValid('PatientModule') 
   from medical_image_obj t;
```
See isConformanceValid( ) in Chapter 5 for reference information about this method.
Query the orddcm_conformance_vld_msgs view to see the list of constraint messages generated during constraint validation for your data as follows:
```
select * from orddcm_conformance_vld_msgs;
```
See orddcm_conformance_vld_msgs in Chapter 4 for reference information about this view.

If your DICOM content does not conform to the constraint rules defined for your organization, you have the option of writing another ORDDicom object with corrected DICOM metadata. See Section 3.6 for information about writing DICOM metadata.

3.10 Protecting Private Patient Data

Oracle Multimedia DICOM provides support to protect the confidentiality of private patient data with the following methods:

makeAnonymous( ) - Use this method to remove or replace private patient data. This method creates a new ORDDicom object, and preserves the original ORDDicom object.
isAnonymous( ) - Use this method to check if the private patient data for a specified ORDDicom object has been removed or replaced, according to a specified anonymity document. In general, call this method before calling the makeAnonymous( ) method.

Both of these methods use anonymity documents, XML documents that are stored in the repository, to determine the patient identifying information that must be made anonymous. In addition to specifying the set of attributes to be made anonymous, anonymity documents specify the actions to be taken to make those attributes anonymous.

After installation, you can use the default anonymity document shipped with Oracle Multimedia DICOM. Or, you can add customized anonymity documents to overwrite or remove patient identifying information, as necessary.

3.10.1 Protecting Privacy - Administrator Tasks

As an administrator, perform the following tasks to initiate the process of making private patient data anonymous:

Create an anonymity document that defines the DICOM attributes to be removed or replaced.

See Section 11.2.1 for information about how to create anonymity documents.
Load the anonymity document into the data model repository.

See Section 8.5.1 for information about inserting anonymity documents into the repository.

3.10.2 Protecting Privacy - Developer Tasks

As a developer, perform the following tasks to complete the process of making private patient data anonymous:

Query the orddcm_documents view to see the list of anonymity documents that have been loaded into the data model repository as follows:
```
select * from orddcm_documents;
```
See orddcm_documents in Chapter 4 for reference information about this view.
Create an empty ORDDicom object using the empty ORDDicom constructor if you plan to call the makeAnonymous( ) method. The empty ORDDicom object will be used as a placeholder for the new ORDDicom object. Create the empty object as follows:
```
insert into medical_image_obj (id, dicom_src)
    values (3, ORDDicom());
```
Call the isAnonymous( ) method to check if the original ORDDicom object is already anonymous, in accordance with the specified anonymity document.
```
select t.dicom_src.isAnonymous('ordcman.xml') from medical_image_obj t;
```
See isAnonymous( ) in Chapter 5 for reference information about this method.

Call the makeAnonymous( ) method to copy and make the original ORDDicom object anonymous, and then write the new DICOM content into the empty ORDDicom object. Call this method as follows:

declare
   obj_src orddicom;
   obj_dest orddicom;
   dest_sop_instance_uid varchar2(128) := '<unique-UID>';
 begin
   select dicom_src, dicom_dest  into obj_src, obj_dest
   from medical_image_obj where id = 1 for update;
   obj_src.makeAnonymous(dest_sop_instance_uid, obj_dest, 'ordcman.xml');

   update medical_image_obj set dicom_dest = obj_dest where id = 1;
 end;
/

See makeAnonymous( ) in Chapter 5 for reference information about this method.