Overview of DICOM Development

3 Overview of DICOM Development

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

This chapter includes these sections:

3.1 The DICOM Development Environment

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. Administrators can use views or invoke data model utility functions to obtain attributes and other detailed information about these configuration documents. Developers can also work directly with the DICOM content, metadata attributes, and other objects to perform various operations.

After installation, each database includes a set of default configuration documents in the Oracle Multimedia DICOM data model repository. After installation, administrators can add configuration documents that are specific to a particular organization. See Configuration Documents in the Repository for general information about configuration documents. See DICOM Administration Usage and Reference for detailed information about managing these documents in the DICOM repository.

The following subsections describe the DICOM development environment:

3.1.1 APIs for Use With Oracle Multimedia DICOM

Because Oracle Multimedia DICOM is fully functional after installing Oracle Multimedia, developers can begin writing applications immediately. Oracle Multimedia DICOM provides several application programming interfaces (APIs) for developers, which are also available to administrators.

In addition, Oracle Multimedia DICOM provides the ORD_DICOM_ADMIN data model repository API for administrators only. Using this API, administrators can assist developers by inserting or deleting configuration documents from the data model repository.

The following table lists the application programming interfaces that are available for Oracle Multimedia DICOM, indicates who can use them, and points to additional information.

Table 3-1 Application Programming Interfaces for DICOM

Name of API	Type of User	More Information
DICOM data model utility API	Administrators and developers	DICOM Data Model Utility Reference
DICOM PL/SQL API	Administrators and developers	DICOM PL/SQL API Reference
ORDDicom object API	Administrators and developers	ORDDicom Object Type Reference
Mid-Tier Java API	Administrators and developers	Oracle Multimedia Mid-Tier Java API Reference
ORD_DICOM_ADMIN data model repository API	Administrators only	ORD_DICOM_ADMIN Package Reference

3.1.2 Views in the DICOM Repository

Oracle Multimedia DICOM provides views to enable access to specific information about documents in the DICOM repository. Public views are available to users and administrators of the repository. These views provide details such as the names of documents, types of documents, names of constraints, and constraint validation messages. An administrator-only view provides details about document references within the repository.

The following table lists the views, indicates who can access them, and points to additional information.

Table 3-2 DICOM Repository Views

Name	Access	More Information
orddcm_conformance_vld_msgs	Public	DICOM Repository Public Views
orddcm_constraint_names	Public	DICOM Repository Public Views
orddcm_document_types	Public	DICOM Repository Public Views
orddcm_documents	Public	DICOM Repository Public Views
orddcm_document_refs	Administrators only	DICOM Repository Administrator Views

orddcm_conformance_vld_msgs

The orddcm_conformance_vld_msgs view lists the constraint messages that are generated for a set of constraints during a validation operation.

Note:

This view lists the constraint messages for the current user's schema only.

orddcm_constraint_names

The orddcm_constraint_names view lists the names of the constraints installed in the repository.

orddcm_document_types

The orddcm_document_types view identifies the supported Oracle Multimedia DICOM document types with a list of codes.

orddcm_documents

The orddcm_documents view lists details of the documents that are stored in the repository.

orddcm_document_refs

For administrators only, the orddcm_document_refs view lists the documents in the repository that are referenced by other documents in the repository.

3.2 DICOM Developer and Administrator Tasks

The following tasks, which are described in these subsections, present a recommended approach for developing applications using Oracle Multimedia DICOM:

In addition, each of these tasks requires administrators and developers to perform a separate, specific set of steps:

Extracting the DICOM metadata
Validating conformance with DICOM constraints
Protecting confidential patient data

3.2.1 Task 1: Load 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 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 and the editDataModel( ) Procedure for more information.

3.2.2 Task 2: Load the DICOM Content

You can use the SQL*Loader utility to load DICOM content into existing tables in Oracle Database. First, you must create a table with the appropriate columns and initialize the columns (see Creating a Table with an ORDDicom Column). Then, you can call the SQL*Loader utility and load the DICOM content from your data files into the table columns as SecureFiles LOBs (see Loading DICOM Content Using the SQL*Loader Utility). Before performing any operations on the DICOM content, you must call the setDataModel( ) procedure to load the DICOM data model (see the setDataModel( ) Procedure).

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 confidential DICOM content anonymous.

See DICOM Application Development 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.

3.2.3 Task 3: Extract the 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 the setProperties( ) and extractMetadata( ) methods for more information.

The following subsections list the steps for administrators and developers to perform when extracting metadata:

3.2.3.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 DICOM XML Schemas for more information about XML schemas.
Register the metadata XML schema, either as a global or local XML schema, with Oracle XML DB.

Note:

Global registered XML schemas can be seen and used by other database users. To prevent other users from validating against your custom metadata XML schemas that are associated with user-defined mapping documents, register them as local schemas with Oracle XML DB.

See Also:

Oracle XML DB Developer's Guide for more information about global and local XML schemas
Create the mapping document for the metadata XML schema.

See About Creating Mapping Documents and Metadata XML Schemas for more information.
Load the mapping document into the data model repository.

See About Inserting Documents into the Repository for more information.

3.2.3.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 the orddcm_documents view for more information.
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 the extractMetadata( ) method for more information.
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 Also:

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

3.2.4 Task 4: Search and Retrieve 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 ORDDicom Object Type Reference 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. To make searching faster, the attributes in the metadata XML document can also be indexed.

3.2.5 Task 5: Write and Edit DICOM Metadata

Oracle Multimedia DICOM provides support for creating a new ORDDicom object with overwritten or supplemented metadata from an existing ORDDicom object. The writeMetadata( ) method creates a new copy of the ORDDicom object from the original ORDDicom object and an XML document containing any additional and 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 the extractMetadata( ) method for more information.
Add or modify DICOM attributes in the copy of the extracted metadata XML document.

See Overview of DICOM Administration 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 ORDDicom Constructors for reference information.
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 existing attributes and add new attributes in the new ORDDicom object.

See the writeMetadata( ) method for more information.

3.2.6 Task 6: Process, Convert, and Compress DICOM Data

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

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 ORDDicom Methods for reference information about processCopy( ) methods and supported command parameters. See DICOM Processing and Supported Formats for more information about DICOM processing.

3.2.7 Task 7: Create DICOM Content from Secondary Capture Images and Video

Oracle Multimedia DICOM provides the PL/SQL API 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.
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 DICOM PL/SQL API Procedures for reference information about the createDicomImage( ) procedures.

3.2.8 Task 8: Validate 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.

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.

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.

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 view orddcm_constraint_names.

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

Validating the conformance of DICOM content requires a combination of administrator and developer tasks. The following subsections describe these tasks.

Note:

Perform the administrator tasks described in this section first.

The following subsections list the steps for administrators and developers to perform when during conformance validation:

3.2.8.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. Within this document, you can 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.

See About Creating Constraint Documents for more information.
Load the constraint document into the data model repository.

See About Inserting Documents into the Repository for more information.

Example 3-1 Constraint Rule for the Patient Module

 <GLOBAL_RULE name="PatientModule">
   <DESCRIPTION>
     A subset of Patient Module defined in DICOM standard
   </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>

3.2.8.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 the orddcm_constraint_names view for more information.

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 the isConformanceValid( ) method for more information.

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 the orddcm_conformance_vld_msgs view for more information.

If your DICOM content does not conform to the constraint rules defined for your organization, you can write another ORDDicom object with corrected DICOM metadata (see Task 5: Write and Edit DICOM Metadata).

3.2.9 Task 9: Protect Confidential Patient Data

Oracle Multimedia DICOM provides support to protect the privacy of patients by ensuring the confidentiality of patient data. In general, call the isAnonymous( ) method before calling the makeAnonymous( ) method to check if the confidential 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 confidential 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 confidential patient data, as necessary.

The following subsections list the steps for administrators and developers to perform when making confidential data anonymous:

3.2.9.1 Protecting Privacy: Administrator Tasks

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

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

See About Creating Anonymity Documents for more information.
Load the anonymity document into the data model repository.

See About Inserting Documents into the Repository for more information.

3.2.9.2 Protecting Privacy: Developer Tasks

As a developer, perform the following tasks to complete the process of making confidential 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 the orddcm_documents view for more information.
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());
```
See ORDDicom Constructors for more information.
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 the isAnonymous( ) method for more information.

Call the makeAnonymous( ) method to copy the original ORDDicom object, make it anonymous, and then write the new DICOM content into the new, 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 the makeAnonymous( ) method for more information.

3.2.10 Task 10: Improve Storage When Extracting DICOM Attributes

Oracle Multimedia DICOM 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.

See About Creating Stored Tag List Documents for more information about creating stored tag list documents.

See Sample Session 4: Inserting a Stored Tag List Document for sample sessions that show how to insert a stored tag list document into the repository.

See the generateTagListDocument( ) Function for reference information.