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 these 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 several 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 their 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 these 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 Content from Secondary Capture Images and Video
Validating Conformance with DICOM Constraints
Protecting Private Patient Data
Improving Storage and Performance When Extracting DICOM Attributes

Table 3-1 provides cross-references to various 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 10
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 10
Reference information for the DICOM Java API	Oracle Multimedia DICOM Java API Reference
Reference information for the Mid-Tier Java API	Oracle Multimedia Mid-Tier Java API Reference
Examples of operations on DICOM content	Chapter 7 and Chapter 8
Examples of administrative operations in the data model repository	Chapter 11
Information about writing configuration documents	Chapter 12
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 and 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.
Stored tag list documents - Optional XML documents that specify the DICOM attributes to be extracted from the embedded DICOM content and stored in the XML metadata attribute of the ORDDicom object when the setProperties( ) method is called.
UID definition documents - XML documents that list the unique identifiers (UIDs) defined by the DICOM standard.

See Appendix A and Chapter 12 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 (see the editDataModel( ) Procedure).

After loading the repository into memory, users and administrators can call the setDataModel( ) procedure whenever the application requires the 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, users and administrators call the setDataModel( ) procedure as follows:

exec ord_dicom.setdatamodel;

See the setDataModel( ) Procedure for reference information.

3.2 Accessing Information About Documents in the Repository

Several 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 examine details of 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. (See orddcm_documents and orddcm_document_types.)

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 orddcm_constraint_names and orddcm_conformance_vld_msgs.)

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.)

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 (see Chapter 4 for reference information).

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 Chapter 7 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 find the specific DICOM content that contains the associated metadata.

To extract all DICOM attributes into an XML document that conforms to the default metadata XML schema, first call the setProperties( ) method to extract and store the 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 table columns. This metadata can be bound to the application-specific XML schema.

See Chapter 5 for reference information about the setProperties( ) and extractMetadata( ) methods.

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 as a global XML schema with Oracle XML DB.

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

See Chapter 12 for more information about creating mapping documents.
Load the mapping document into the data model repository.

See Chapter 9 for more 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 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 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 Chapter 5 for reference information.)

To search and retrieve attributes within the metadata XML document, call the SQL XML functions XMLCast( ), XMLExists( ), XMLQuery( ), and XMLTable( ) 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. This process is not recommended for large tables, or for retrievals of multiple attributes. However, if you do use this process, Oracle recommends building function-based indexes on these methods to make searching faster. (See Chapter 5 for reference information.)

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 a copy of the original DICOM metadata from the original DICOM content by calling the extractMetadata( ) method, using the Oracle default mapping document.

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

See Chapter 9 for more 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 Chapter 5 for reference information about constructors.
Call the writeMetadata( ) method to write the modified copy of the 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 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 command parameters. 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:
```
'fileFormat=dicom, 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'
```
Process multiframe DICOM content into AVI output. For example:
```
'fileFormat=avi, scale=0.5'
```
Write DICOM content with RLE compression. For example:
```
'fileFormat=dicom, compressionFormat=dicomrle'
```
Extract MPEG content from DICOM format and process it into MPEG format. For example:
```
'fileFormat=mpeg'
```

Write DICOM content with DEFLATE compression. For example:

'fileformat=dicom, compressionFormat=deflate, deflateLevel=defaultcompression'

See Chapter 5 for reference information about processCopy( ) methods and supported command parameters. See Appendix D for more information about DICOM processing.

3.8 Creating DICOM Content from Secondary Capture Images and Video

Oracle Multimedia DICOM provides the relational procedure createDicomImage( ) to create DICOM format images and video from secondary capture images and video, including content in formats such as JPEG, TIFF, or MPEG and DICOM metadata in data type XMLType.

Perform the following tasks to create DICOM format content from secondary capture images or video and DICOM metadata:

Load the provided image or video into a BLOB, or define it as a BFILE data type (see Oracle Multimedia User's Guide).
Create an XMLType object from the DICOM metadata of the corresponding image or video.
Create an empty BLOB object as the placeholder for the new DICOM content.
Create the DICOM format image or video 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 isConformanceValid( ) method. 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 the DICOM content may or may not have been created in accordance with the DICOM standard. Before you decide to store DICOM content in your repository, you can check the DICOM content for specific attributes. As an example, you can check the DICOM content for the value of the attribute for a patient's sex. As defined in the Patient Module Attributes of the DICOM standard, this attribute can have these values: M (male), F (female), or O (other). You can define constraint rules to check for correct values for specific attributes. 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 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 and Chapter 4 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 Chapter 12 for information about how to create constraint documents.

Load the constraint document into the data model repository.

See Chapter 9 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 Chapter 4 for reference information about this view.

Call the isConformanceValid( ) method to check the conformance of your DICOM content as follows:

declare
     cursor dicom_src_cur is       
      select dicom_src from medical_image_obj order by id;
   begin
      for rec in dicom_src_cur loop
        dbms_output.put_line('isConformanceValid(PatientModule): ' ||
          rec.dicom_src.isConformanceValid('PatientModule'));
      end loop;
   end;
   /

See 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 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. In general, call the isAnonymous( ) method before calling the makeAnonymous( ) method to check if the private patient data for a specified ORDDicom object has been removed or replaced, according to a specified anonymity document. Call the makeAnonymous( ) method to remove or replace private patient data. This method creates a new ORDDicom object, and preserves the original ORDDicom object.

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 Chapter 12 for information about how to create anonymity documents.
Load the anonymity document into the data model repository.

See Chapter 9 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 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 is 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 anonymous, in accordance with the specified anonymity document.
```
select t.dicom_src.isAnonymous('ordcman.xml') from medical_image_obj t;
```
See 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 Chapter 5 for reference information about this method.

3.11 Improving Storage and Performance When Extracting DICOM Attributes

By default, a call to the setProperties( ) method extracts and stores all the DICOM attributes that are contained in the DICOM content. Thus, later calls to either the extractMetadata( ) method or the isConformanceValid( ) method can access all the required attributes in the ORDDicom metadata attribute, without having to parse the DICOM content again.

Oracle Database 11g Release 2 (11.2) provides the ability to limit the list of DICOM attributes extracted by the setProperties( ) method. Extracting only a selected set of attributes instead of all the attributes improves the performance of the setProperties( ) method and reduces storage requirements. Oracle Multimedia DICOM provides this support with a stored tag list configuration document in the repository. A stored tag list document specifies the DICOM attributes to be extracted from the embedded DICOM content and stored in the XML metadata attribute of the ORDDicom object when the setProperties( ) method is called.

To further improve performance while still saving storage, Oracle Multimedia introduces the mandate attribute tags rule. If this rule is set to true in the preference document, performance for the extractMetadata( ) and the isConformanceValid( ) methods also improves. This rule ensures that all tags used by mapping and constraint documents are included in the stored tag list. Thus, the setProperties( ) method extracts the DICOM attributes required by the extractMetadata( ) method and the isConformanceValid( ) method, and those methods do not have to parse the embedded DICOM content for attributes that are not stored in the ORDDicom object.

See Section 12.1.8 and Section 12.2.8 for more information about creating stored tag list documents. See Section 11.4 for sample sessions that show how to insert a stored tag list document into the repository. See the generateTagListDocument( ) Function for reference information. See also Section B.11 for a listing of the stored tag list document schema (ordcmstl.xsd).