7 ORDDicom Object Type Reference

Oracle Multimedia provides the ORDDicom object type, which supports the storage, management, and manipulation of DICOM format medical images and other data. The ORDDicom object is intended as an object that is written only once. To generate a new ORDDicom object by image processing or compression, create a new ORDDicom object, ORDImage object, or BLOB.

The ORDDicom object type is defined in the ordcspec.sql file. After installation, this file is available in the Oracle home directory at:

<ORACLE_HOME>/ord/im/admin (on Linux and UNIX)

<ORACLE_HOME>\ord\im\admin (on Windows)

This chapter describes the attributes, constructors, and methods in the ORDDicom object interface. See Table 3-1 for information about other DICOM application programming interfaces (APIs).

7.1 ORDDicom Object Examples

The examples in this chapter use the MEDICAL_IMAGE_OBJ table, which these examples create in the Product Media (PM) sample schema. See Section 7.1.2 when reading through these examples.

Before using ORDDicom methods, you must load some data into the table. For example, you can use the SQL*Loader utility, a Java client, or the import( ) method. Substitute your DICOM files for those in the examples.

Note:

If you manipulate the DICOM content itself (by either directly modifying the BLOB or changing the external source), call the setProperties( ) method to ensure that the object attributes stay synchronized. You must also ensure that the update time is modified. Otherwise, the object attributes will not match the DICOM content.

ORDDicom Object Type

The ORDDicom object type supports the storage, management, and manipulation of DICOM format medical images and other data. The attributes for this object type are defined as follows in the ordcspec.sql file:

STUDY_INSTANCE_UID: the study instance UID of the embedded DICOM content.

SERIES_INSTANCE_UID: the series instance UID of the embedded DICOM content.

source: the original DICOM content stored within the database, under transaction control as a BLOB (recommended), or stored in an operating system-specific file in a local file system with pointer stored in the database.

ORDDicom Constructors

The ORDDicom object can be constructed using these constructors in a SQL statement or PL/SQL program.

The ORDDicom object has embedded BLOB attributes. BLOB locators must be initialized before they can be accessed. Thus, newly constructed ORDDicom objects (unless constructed from a temporary BLOB) must be inserted into a table before you can call object member methods on these ORDDicom objects.

ORDDicom( ) for BLOBs

Format

ORDDicom(SELF IN OUT NOCOPY ORDDicom, data IN BLOB, setproperties IN INTEGER DEFAULT 0) RETURN SELF AS RESULT

Description

Constructs an ORDDicom object from a BLOB. The data stored in the BLOB is copied into the ORDDicom object when the constructed ORDDicom object is inserted or updated into a table. The metadata conforms to the XML schema defined by the default mapping document.

Parameters

data

Embedded DICOM content stored in a BLOB.

setproperties

Indicator flag that determines whether the DICOM attributes are extracted from the embedded DICOM content. If the value is 1, the DICOM attributes are extracted into the metadata attribute of the constructed ORDDicom object, and the attributes of the ORDDicom object are populated. If the value is 0, no DICOM attributes are extracted. The default is 0.

Pragmas

None.

Exceptions

None.

Usage Notes

Use this constructor to create an ORDDicom object when the DICOM content is stored in either a temporary or a persistent BLOB.

ORDDicom( ) for ORDImage

Format

ORDDicom(SELF IN OUT NOCOPY ORDDicom, data IN ORDImage, setproperties IN INTEGER DEFAULT 0) RETURN SELF AS RESULT

Description

Constructs an ORDDicom object from an ORDImage object that has either a local source (BLOB) or a file source (BFILE). If the DICOM content is stored originally in the BLOB of the ORDImage object, the data is copied into the BLOB in the ORDDicom object source attribute when the constructed ORDDicom object is inserted or updated into a table. If the DICOM content is stored originally as a BFILE source of the ORDImage object, the srcType, srcLocation, and srcName parameters from the ORDImage source are copied into the source attribute of the ORDDicom object. The metadata conforms to the XML schema defined by the default mapping document.

Parameters

data

Embedded DICOM content stored in an ORDImage object.

setproperties

Indicator flag that determines whether the DICOM attributes are extracted from the embedded DICOM content. If the value is 1, the DICOM attributes are extracted into the metadata attribute of the constructed ORDDicom object, and the attributes of the ORDDicom object are populated. If the value is 0, no DICOM attributes are extracted. The default is 0.

Pragmas

None.

Exceptions

None.

Usage Notes

Use this constructor to create an ORDDicom object when the DICOM content is stored in an ORDImage object. Or, use this constructor to migrate an ORDImage object to an ORDDicom object.

Constructs an ORDDicom object from a specific source. By default, the value of the source_type parameter is set to LOCAL, which means that the source of the data is stored locally in the database in a BLOB. With the default values, an empty object with a local source is constructed. If the value of the source_type parameter is set to FILE, an ORDDicom object is constructed with the source stored as an external FILE. The metadata conforms to the XML schema defined by the default XML mapping document.

Parameters

source_type

The type of the source. Valid values are: FILE or LOCAL. The default is LOCAL.

source_location

The directory location of the source (used for source_type=FILE).

source_name

The file name of the source (used for source_type=FILE).

setproperties

Indicator flag that determines whether the DICOM attributes are extracted from the embedded DICOM content. If the value is 1, the DICOM attributes are extracted into the metadata attribute of the constructed ORDDicom object, and the attributes of the ORDDicom object are populated. If the value is 0, no DICOM attributes are extracted. The default is 0.

Pragmas

None.

Exceptions

None.

Usage Notes

Use this constructor to create an ORDDicom object when the DICOM content is stored in the file system. Use the empty constructor when uploading DICOM content from a client, such as a Web browser or a Java application. Or, use the empty constructor as a destination object for methods such as processCopy( ), makeAnonymous( ), and writeMetadata( ).

Examples

Example 1:

Create an ORDDicom object from a file without populating the object attributes:

In this section, <unique-UID> represents a 64-byte, dot-concatenated, numeric string that represents a globally unique identifier for DICOM content worldwide. The UID is commonly constructed with a root that uniquely identifies the organization producing the DICOM content, and a suffix that uniquely identifies the DICOM content within that organization. For some examples in this section, you must replace <unique-UID> with the appropriate UID.

export( )

Format

export(SELF IN ORDDicom, dest_type IN VARCHAR2, dest_location IN VARCHAR2, dest_name IN VARCHAR2)

Description

Exports embedded DICOM content to a specified destination. The data remains in the source BLOB when it is copied to the destination.

Parameters

dest_type

The type of the destination (only FILE is supported).

dest_location

The location of the destination (must be a valid Oracle directory object).

dest_name

The name of the destination file.

Pragmas

None.

Exceptions

None.

Usage Notes

Use this method to export the embedded DICOM content to the local file system.

The export( ) method writes only to a database directory object that the user has privilege to access. That is, you can access a directory object that you have created using the SQL statement CREATE DIRECTORY, or one to which you have been granted READ and WRITE access.

For example, the following SQL*Plus commands create a directory object and grant the user pm permission to read and write any file within the directory c:\mydir\work:

extractMetadata( )

Returns the DICOM metadata as XML code for a specified mapping document. The default mapping document refers to the default metadata namespace http://xmlns.oracle.com/ord/dicom/metadata_1_0. The metadata attribute of the ORDDicom object is not affected.

Parameters

extractOption

A string that specifies the types of metadata to extract from the DICOM content. Valid values are: ALL, MAPPED, and STANDARD. The default is ALL.

When the value of this parameter is ALL, all the attributes in the embedded DICOM content are extracted. When the value is set to MAPPED, only mapped attributes are extracted. And, when the value is set to STANDARD, only attributes that conform to the DICOM standard and mapped attributes are extracted.

docName

The name of the mapping document. The default mapping document ordcmmp.xml is loaded during installation. This document refers to the default metadata namespace http://xmlns.oracle.com/ord/dicom/metadata_1_0.

Pragmas

None.

Exceptions

None.

Usage Notes

Use this method to retrieve metadata from the embedded DICOM content as XML code, and then store it in a database table for searching or viewing.

Use the preference parameter XML_SKIP_ATTR to specify size limits for DICOM attributes to be omitted when encoding into XML. See Section 10.2.6.8 for more information about this preference parameter.

Use the preference parameter VALIDATE_METADATA to specify whether the XML documents are validated against a specific XML schema that is registered with Oracle XML DB. See Section 10.2.6.7 for more information about this preference parameter.

getAttributeByName( )

Returns the value of a DICOM attribute, as a VARCHAR2 string, for DICOM attributes other than SQ type attributes. For SQ type attributes, this method returns a segment of XML code, as a VARCHAR2 string. Use this method to get a single attribute from the embedded DICOM content.

Parameters

attributeName

The name of a specified attribute.

definerName

The name of the attribute definer. The default name is DICOM.

Pragmas

None.

Exceptions

None.

Usage Notes

See Section 3.2.4 for more information about the best methods to use for searching and retrieving DICOM attributes.

getAttributeByTag( )

Returns the value of a DICOM attribute, as a VARCHAR2 string, for DICOM attributes other than SQ type attributes. For SQ type attributes, this method returns a segment of XML code, as a VARCHAR2 string. Use this method to get a single attribute of the embedded DICOM content.

Parameters

tag

The code value used to specify a DICOM attribute or item tag, as a hexadecimal string.

definerName

The name of the attribute definer. The default name is DICOM.

Pragmas

None.

Exceptions

None.

Usage Notes

See Section 3.2.4 for more information about the best methods to use for searching and retrieving DICOM attributes.

getSeriesInstanceUID( )

Returns the value of the SERIES_INSTANCE_UID attribute of the ORDDicom object.

Parameters

None.

Pragmas

None.

Exceptions

None.

Usage Notes

None.

Examples

Return the value of the SERIES_INSTANCE_UID attribute for the ORDDicom object:

select t.dicom_src.getSeriesInstanceUID() from medical_image_obj t;

getSOPClassUID( )

Format

getSOPClassUID( ) RETURN VARCHAR2 DETERMINISTIC PARALLEL_ENABLE,

Description

Returns the value of the SOP_CLASS_UID attribute of the ORDDicom object.

Parameters

None.

Pragmas

None.

Exceptions

None.

Usage Notes

None.

Examples

Return the value of the SOP_CLASS_UID attribute for the ORDDicom object:

select t.dicom_src.getSOPClassUID() from medical_image_obj t;

getSOPInstanceUID( )

Format

getSOPInstanceUID( ) RETURN VARCHAR2 DETERMINISTIC PARALLEL_ENABLE

Description

Returns the value of the SOP_INSTANCE_UID attribute of the ORDDicom object.

Parameters

None.

Pragmas

None.

Exceptions

None.

Usage Notes

None.

Examples

Return the value of the SOP_INSTANCE_UID attribute for the ORDDicom object:

select t.dicom_src.getSOPInstanceUID() from medical_image_obj t;

getSourceInformation( )

Format

getSourceInformation( ) RETURN VARCHAR2 DETERMINISTIC PARALLEL_ENABLE

Description

Returns the source information from the source attribute of the ORDDicom object as a URL in the form "source_type://source_location/source_name".

Parameters

None.

Pragmas

None.

Exceptions

None.

Usage Notes

None.

Examples

Return the source information for the ORDDicom object:

select t.dicom_src.getSourceInformation() from medical_image_obj t;

getSourceLocation( )

Format

getSourceLocation( ) RETURN VARCHAR2 DETERMINISTIC PARALLEL_ENABLE

Description

Returns the source location from the source attribute of the ORDDicom object.

Parameters

None.

Pragmas

None.

Exceptions

None.

Usage Notes

None.

Examples

Return the source location for the ORDDicom object:

select t.dicom_src.getSourceLocation() from medical_image_obj t;

getSourceName( )

Format

getSourceName( ) RETURN VARCHAR2 DETERMINISTIC PARALLEL_ENABLE

Description

Returns the source name from the source attribute of the ORDDicom object.

Parameters

None.

Pragmas

None.

Exceptions

None.

Usage Notes

None.

Examples

Return the source name for the ORDDicom object:

select t.dicom_src.getSourceName() from medical_image_obj t;

getSourceType( )

Format

getSourceType( ) RETURN VARCHAR2 DETERMINISTIC PARALLEL_ENABLE

Description

Returns the source type from the source attribute of the ORDDicom object.

Parameters

None.

Pragmas

None.

Exceptions

None.

Usage Notes

None.

Examples

Return the source type for the ORDDicom object:

select t.dicom_src.getSourceType() from medical_image_obj t;

getStudyInstanceUID( )

Format

getStudyInstanceUID( ) RETURN VARCHAR2 DETERMINISTIC PARALLEL_ENABLE,

Description

Returns the value of the STUDY_INSTANCE_UID attribute of the ORDDicom object.

Parameters

None.

Pragmas

None.

Exceptions

None.

Usage Notes

None.

Examples

Return the value of the STUDY_INSTANCE_UID attribute for the ORDDicom object:

select t.dicom_src.getStudyInstanceUID() from medical_image_obj t;

import( )

Format

import(SELF IN OUT NOCOPY ORDDicom, setproperties IN INTEGER DEFAULT 1)

Description

Imports DICOM content from the current source. This method assumes that the source attributes have been set in the ORDDicom object by passing the source_type, source_location, and source_name parameters to the constructor.

Parameters

setproperties

Indicator flag that determines whether the DICOM attributes are extracted into the metadata attribute of the ORDDicom object. If the value is 1, the DICOM attributes are extracted into the metadata attribute of the ORDDicom object, and the attributes of the ORDDicom object are populated. If the value is 0, no DICOM attributes are extracted. The default is 1.

Pragmas

None.

Exceptions

None.

Usage Notes

Use this method when the ORDDicom object is constructed from a source other than a BLOB, and must be imported into a BLOB.

The import( ) method reads only from a database directory object that the user has privilege to access. That is, you can access a directory object that you have created using the SQL statement CREATE DIRECTORY, or one to which you have been granted READ access.

For example, the following SQL*Plus commands create a directory object and grant the user pm permission to read any file within the directory c:\mydir\work:

isAnonymous( )

Determines whether the embedded DICOM content is anonymous using a specified anonymity document, which is stored in the data model repository. This method returns a value of 1 if the data is anonymous; otherwise it returns a value of 0.

Parameters

anonymityDocName

The name of the anonymity document. The default name is ordcman.xml.

Pragmas

None.

Exceptions

None.

Usage Notes

Use this method before calling the makeAnonymous( ) method to find out whether patient identifying information has been removed from the embedded DICOM content (see also the makeAnonymous( ) method).

isConformanceValid( )

Format

isConformanceValid( constraintName IN VARCHAR2 ) RETURN INTEGER

Description

Performs a conformance validation check to determine whether the embedded DICOM content conforms to a specific set of constraints identified by the constraintName parameter. This method returns a value of 1 if conformance is valid; otherwise it returns a value of 0.

The name of the constraint to be used for conformance validation checking.

Pragmas

None.

Exceptions

None.

Usage Notes

If this method is called from a SQL query, ensure that the constraint rule definition does not contain any <ACTION> elements.

Use the preference parameter EXP_IF_NULL_ATTR_IN_CONSTRAINT to indicate whether to throw exceptions when encountering missing attributes or null attribute values during conformance validation. See Section 10.2.6.2 for more information about this preference parameter.

Examples

Check if the ORDDicom objects are conformance valid. Then, show any conformance validation messages that are generated.

isLocal( )

Format

isLocal( ) RETURN INTEGER DETERMINISTIC PARALLEL_ENABLE

Description

Returns the local status of the source. If the DICOM content is stored in the source BLOB, the object is defined as local. If the DICOM content is stored externally in an operating system-specific file, the object is defined as not local. This method returns a value of 1 if the object is local; otherwise it returns a value of 0.

makeAnonymous( )

Format

makeAnonymous(SELF IN ORDDicom, dest_SOP_INSTANCE_UID IN VARCHAR2, dest IN OUT NOCOPY ORDDicom, anonymityDocName IN VARCHAR2 DEFAULT 'ordcman.xml')

Description

Removes patient identifying information from the ORDDicom object after copying it into another ORDDicom object, based on a specified anonymity document. Both the embedded DICOM content and the metadata attribute in the destination ORDDicom object are made anonymous.

Parameters

dest_SOP_INSTANCE_UID

The SOP instance UID of the destination ORDDicom object. It must ensure that the destination DICOM content is globally unique.

dest

An empty ORDDicom object in which to store the anonymous ORDDicom object.

anonymityDocName

The name of the anonymity document. The default name is ordcman.xml.

Pragmas

None.

Exceptions

None.

Usage Notes

Use this method to remove patient identifying information from the embedded DICOM content for use in data sharing and research.

processCopy( ) to BLOBs

Format

processCopy(SELF IN ORDDicom, command IN VARCHAR2, dest IN OUT NOCOPY BLOB)

Description

Copies the ORDDicom object that is input into the destination BLOB, and then performs the specified processing operations on the destination BLOB. The original ORDDicom object that was input remains unchanged.

The destination BLOB that contains the output of the process command on the ORDDicom object.

Pragmas

None.

Exceptions

None.

Usage Notes

Use this method to process an ORDDicom object into a BLOB after copying it from the ORDDicom object. In this case, the output in the BLOB is image or video content.

See Appendix C for information about the encoding rules that support DICOM content processing. See Appendix D for more information about DICOM processing.

Use the preference parameter VALIDATE_METADATA to specify whether the XML documents are validated against the Oracle default DICOM metadata schema. See Section 10.2.6.7 for more information about this preference parameter.

processCopy( ) to ORDDicom

Format

processCopy(SELF IN ORDDicom, command IN VARCHAR2, dest_SOP_INSTANCE_UID IN VARCHAR2, dest IN OUT NOCOPY ORDDicom, metadata IN SYS.XMLTYPE DEFAULT NULL)

Description

Copies the ORDDicom object that is input into a destination ORDDicom object, then performs the specified processing operations on the destination ORDDicom object and updates it with the new metadata. The original ORDDicom object that was input remains unchanged.

The SOP instance UID of the destination ORDDicom object. It must ensure that the destination DICOM content is globally unique.

dest

An empty ORDDicom object in which to store the new DICOM content with the new metadata.

metadata

The new metadata to be written into the new DICOM content.

Pragmas

None.

Exceptions

None.

Usage Notes

Use this method to process DICOM content into a destination ORDDicom object after copying it from the source ORDDicom object. In this case, the output is image or video content.

See Appendix C for information about the encoding rules that support DICOM content processing. See Appendix D for more information about DICOM processing.

Use the preference parameter VALIDATE_METADATA to specify whether the XML documents are validated against the Oracle default DICOM metadata schema. See Section 10.2.6.7 for more information about this preference parameter.

Examples

Copy the DICOM content into an ORDDicom object and then process it:

Note:

Replace <unique-UID> with the UID that identifies the organization producing the DICOM content and the DICOM content within that organization.

processCopy( ) to ORDImage

Format

processCopy(SELF IN ORDDicom, command IN VARCHAR2, dest IN OUT NOCOPY ORDImage)

Description

Copies the ORDDicom object that is input into the destination ORDImage object, and then performs the specified processing operations on the destination ORDImage object. The original ORDDicom object that was input remains unchanged.

An empty ORDImage object in which to store the new, processed ORDImage object without the DICOM metadata.

Pragmas

None.

Exceptions

None.

Usage Notes

Use this method to get a non-DICOM image that is suitable for presentation on the Web from the embedded DICOM content.

See Appendix C for information about the encoding rules that support image content processing. See Appendix D for more information about DICOM processing.

Use the preference parameter VALIDATE_METADATA to specify whether the XML documents are validated against the Oracle default DICOM metadata schema. See Section 10.2.6.7 for more information about this preference parameter.

setProperties( )

Format

setProperties(SELF IN OUT NOCOPY ORDDicom)

Description

Sets the attributes of the ORDDicom object. The attributes of the ORDDicom object are populated and the embedded DICOM content attributes are extracted into the metadata attribute of the ORDDicom object. The XML metadata conforms to the default metadata schema namespace http://xmlns.oracle.com/ord/dicom/metadata_1_0.

If the repository contains a stored tag list document, the XML metadata contains only the DICOM attributes specified by the stored tag list. Otherwise, the XML metadata contains all the attributes from the embedded DICOM content.

Parameters

None.

Pragmas

None.

Exceptions

None.

Usage Notes

Use this method to populate ORDDicom object attributes and to get the metadata from the embedded DICOM content.

Use the preference parameter XML_SKIP_ATTR to specify size limits for DICOM attributes to be omitted when encoding into XML. See Section 10.2.6.8 for more information about this preference parameter.

Use the preference parameter VALIDATE_METADATA to specify whether the XML documents are validated against a specific XML schema that is registered with Oracle XML DB. See Section 10.2.6.7 for more information about this preference parameter.

writeMetadata( )

Format

writeMetadata(SELF IN ORDDicom, metadata IN SYS.XMLTYPE, dest IN OUT NOCOPY ORDDicom)

Description

Modifies the current ORDDicom object with the metadata provided by making a copy of the existing ORDDicom object in the destination ORDDicom object, and then modifying the metadata. The original ORDDicom object remains unchanged. The attributes in the embedded DICOM content of the destination ORDDicom object are copied from the metadata that was input.

Parameters

metadata

The input metadata stored in data type XMLType. In the destination ORDDicom object, the input metadata is used to update the values for attributes that are identical to attributes in the source ORDDicom object, or to add any new attributes. The metadata must conform to the default metadata schema with the namespace http://xmlns.oracle.com/ord/dicom/metadata_1_0. The SOP instance UID in the metadata must ensure that the destination DICOM content is globally unique.

dest

An empty ORDDicom object in which to store the new embedded DICOM content with the new metadata.

Pragmas

None.

Exceptions

None.

Usage Notes

Use this method to update attributes in the embedded DICOM content.

In addition, you can use this method to add private attributes to the embedded DICOM content.

See Appendix C for information about the encoding rules that support metadata extraction.

Use the preference parameter VALIDATE_METADATA to specify whether the XML documents are validated against the Oracle default DICOM metadata schema. See Section 10.2.6.7 for more information about this preference parameter.

Use the preference parameter SQ_WRITE_LEN to specify how the DICOM sequence (SQ) types are encoded. See Section 10.2.6.6 for more information about this preference parameter.