DICOM PL/SQL API Reference

7 DICOM PL/SQL API Reference

Oracle Multimedia DICOM provides a PL/SQL API, which is defined in the ORD_DICOM PL/SQL package.

The ORD_DICOM PL/SQL package provides functions and procedures to perform common operations such as format conversion, metadata extraction, and conformance validation. This package adds Oracle Multimedia support to medical image data stored in BLOBs and BFILEs.

Application developers who create medical imaging applications without using the Oracle Multimedia ORDDicom object type to store and manage medical image data in relational tables can use the Oracle Multimedia DICOM PL/SQL API to manage their medical image data. In addition, application developers who do not want to migrate their existing medical image applications to use Oracle Multimedia ORDDicom objects can use the DICOM PL/SQL API to manage their medical image data.

The ORD_DICOM package is defined in the ordcpksp.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 functions and procedures in the DICOM PL/SQL API.

This chapter contains these sections:

7.1 Examples for DICOM PL/SQL API Functions and Procedures

The functions and procedures for the DICOM PL/SQL API described in this chapter show examples based on the MEDICAL_IMAGE_REL table. See MEDICAL_IMAGE_REL Table Definition when reading through these examples.

Before using DICOM PL/SQL API functions and procedures, you must load some data into the table. For example, you can use SQL*Loader or the importFrom( ) procedure. Substitute your DICOM files for those in the examples.

7.1.1 Directory Definition and Setup for DICOM PL/SQL API Examples

Before executing the examples, issue the following statements while connected to a user with privileges to create a directory object, where c:\mydir\work is the directory where the user <user> can find the DICOM files:

CREATE OR REPLACE DIRECTORY DICOMDIR as 'c:\mydir\work';
GRANT READ, WRITE ON DIRECTORY DICOMDIR TO <user>;

Note:

At the beginning of each database session, call the setDataModel( ) procedure.

See the setDataModel( ) Procedure for more information.

7.1.2 MEDICAL_IMAGE_REL Table Definition

Before loading data into the table, you must create the table and columns where the data is to be stored. The following PL/SQL code segment creates the MEDICAL_IMAGE_REL table with five columns.

CREATE TABLE MEDICAL_IMAGE_REL
(
 id            integer primary key,
 blob_src      blob,
 bfile_src     bfile,
 image_src     ordsys.ordimage,
 blob_dest     blob
);

where:

blob_src: the source DICOM content in the BLOB.
bfile_src: the source DICOM content in the BFILE.
image_src: the source DICOM content in the ORDImage object.
blob_dest: the destination DICOM content in the BLOB.

7.2 DICOM PL/SQL API Functions

The ORD_DICOM package defines these DICOM PL/SQL API functions:

7.2.1 extractMetadata( ) for BFILEs

Format

extractMetadata(data IN BFILE,
                extractOption IN VARCHAR2 DEFAULT 'ALL',
                docName IN VARCHAR2 DEFAULT 'ordcmmp.xml')
 RETURN SYS.XMLTYPE

Description

Returns the DICOM metadata as an XML document for a specified mapping document. The default mapping document refers to the default metadata namespace http://xmlns.oracle.com/ord/dicom/metadata_1_0.

Parameters

data

The input DICOM content stored in a BFILE.

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 the extractOption parameter is ALL, all attributes in the 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.

Pragmas

None.

Exceptions

None.

Usage Notes

Use the preference parameter XML_SKIP_ATTR to specify size limits for DICOM attributes to be omitted when encoding into XML. See Defining the XML_SKIP_ATTR Preference Parameter 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, either as a global or local XML schema. See Defining the VALIDATE_METADATA Preference Parameter for more information about this preference parameter.

Calling this function when the value of the preference parameter VALIDATE_METADATA is set to true raises an error if the metadata namespace in the mapping document is not available to the current user.

Examples

Extract metadata from the DICOM content stored in a BFILE:

declare
  src bfile;
  metadata xmltype;
begin
  select bfile_src into src from medical_image_rel where id = 1 for update;
  metadata := ord_dicom.extractMetadata(src, 'all', 'ordcmmp.xml');
end;
/

7.2.2 extractMetadata( ) for BLOBs

Format

extractMetadata(data IN BLOB,
                extractOption IN VARCHAR2 DEFAULT 'ALL',
                docName IN VARCHAR2 DEFAULT 'ordcmmp.xml') 
 RETURN SYS.XMLTYPE

Description

Returns the DICOM metadata as an XML document for a specified mapping document. The default mapping document refers to the default metadata namespace http://xmlns.oracle.com/ord/dicom/metadata_1_0.

Parameters

data

The input DICOM content stored in a BLOB.

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.

docName

The name of the mapping document. The default mapping document ordcmmp.xml is loaded during installation.

Pragmas

None.

Exceptions

None.

Usage Notes

Examples

Extract metadata from the DICOM content stored in a BLOB:

declare
  src blob;
  metadata xmltype;
begin
  select blob_src into src from medical_image_rel where id = 1 for update;
  metadata := ord_dicom.extractMetadata(src, 'all', 'ordcmmp.xml');
end;

7.2.3 extractMetadata( ) for ORDImage

Format

extractMetadata(data IN ORDSYS.ORDImage,
                extractOption IN VARCHAR2 DEFAULT 'ALL',
                docName IN VARCHAR2 DEFAULT 'ordcmmp.xml') 
 RETURN SYS.XMLTYPE

Description

Returns the DICOM metadata as an XML document for a specified mapping document. The default mapping document refers to the default metadata namespace http://xmlns.oracle.com/ord/dicom/metadata_1_0.

Parameters

data

The input DICOM content stored in an ORDImage object.

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.

docName

The name of the mapping document. The default mapping document ordcmmp.xml is loaded during installation.

Pragmas

None.

Exceptions

None.

Usage Notes

Examples

Extract metadata from the DICOM content stored in an ORDImage object:

declare
  src ordimage;
  metadata xmltype;
begin
  select image_src into src from medical_image_rel where id = 1 for update;
  metadata := ord_dicom.extractMetadata(src, 'all', 'ordcmmp.xml');
end;
/

7.2.4 isAnonymous( ) for BFILEs

Format

isAnonymous(src IN BFILE,
            anonymityDocName IN VARCHAR2 DEFAULT 'ordcman.xml')
 RETURN INTEGER

Description

Determines whether the input DICOM content is anonymous, using a specified anonymity document. This function returns a value of 1 if the data is anonymous; otherwise it returns a value of 0.

Parameters

src: The input DICOM content stored in a BFILE.
anonymityDocName: The name of the anonymity document. The default name is ordcman.xml.

Pragmas

None.

Exceptions

None.

Usage Notes

None.

Examples

Check if the DICOM content stored in a BFILE is anonymous:

select ord_dicom.isAnonymous(t.bfile_src, 'ordcman.xml') 
  from medical_image_rel t where id = 1;

7.2.5 isAnonymous( ) for BLOBs

Format

isAnonymous(src IN BLOB,
            anonymityDocName IN VARCHAR2 DEFAULT 'ordcman.xml') 
 RETURN INTEGER

Description

Determines whether the input DICOM content is anonymous, using a specified anonymity document. This function returns a value of 1 if the data is anonymous; otherwise it returns a value of 0.

Parameters

src: The input DICOM content stored in a BLOB.
anonymityDocName: The name of the anonymity document. The default name is ordcman.xml.

Pragmas

None.

Exceptions

None.

Usage Notes

None.

Examples

Check if the DICOM content stored in a BLOB is anonymous:

select ord_dicom.isAnonymous(t.blob_src, 'ordcman.xml') 
  from medical_image_rel t where id = 1;

7.2.6 isAnonymous( ) for ORDImage

Format

isAnonymous(src IN ORDSYS.ORDImage,
            anonymityDocName IN VARCHAR2 DEFAULT 'ordcman.xml')  
 RETURN INTEGER

Description

Determines whether the input DICOM content is anonymous, using a specified anonymity document. This function returns a value of 1 if the data is anonymous; otherwise it returns a value of 0.

Parameters

src: The input DICOM content stored in an ORDImage object.
anonymityDocName: The name of the anonymity document. The default name is ordcman.xml.

Pragmas

None.

Exceptions

None.

Usage Notes

None.

Examples

Check if the DICOM content stored in an ORDImage object is anonymous:

select ord_dicom.isAnonymous(t.image_src, 'ordcman.xml') 
  from medical_image_rel t where id = 1;

7.2.7 isConformanceValid( ) for BFILEs

Format

isConformanceValid(src IN BFILE,
                   constraintName IN VARCHAR2)
 RETURN INTEGER

Description

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

This function also logs error messages from the constraint documents, which can be viewed by querying the public view orddcm_conformance_vld_msgs. The public view orddcm_constraint_names contains the list of constraint names.

Parameters

src: The input DICOM content stored in a BFILE.
constraintName: The name of the constraint to be used for conformance validation checking.

Pragmas

None.

Exceptions

None.

Usage Notes

If this function 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 Defining the EXP_IF_NULL_ATTR_IN_CONSTRAINT Preference Parameter for more information about this preference parameter.

Examples

Delete any existing conformance validation messages. Check if the DICOM content stored in a BFILE is conformance valid. Then, show any new conformance validation messages that are generated.

 -- clear the previous conformance validation messages
delete from orddcm_conformance_vld_msgs;

-- conformance validate the DICOM content
    declare
      src bfile;
    begin
      select bfile_src into src from medical_image_rel where id = 1;
      dbms_output.put_line('isConformanceValid(PatientModule) ' ||
        ord_dicom.isConformanceValid(src, 'PatientModule'));
    end;
    /

-- get the logged conformance validation messages
select message, msg_time time from orddcm_conformance_vld_msgs
  where rule_name='PatientModule';

7.2.8 isConformanceValid( ) for BLOBs

Format

isConformanceValid(src IN BLOB,
                   constraintName IN VARCHAR2) 
 RETURN INTEGER

Description

Parameters

src: The input DICOM content stored in a BLOB.
constraintName: The name of the constraint to be used for conformance validation checking.

Pragmas

None.

Exceptions

None.

Usage Notes

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

Examples

Delete any existing conformance validation messages. Check if the DICOM content stored in a BLOB is conformance valid. Then, show any new conformance validation messages that are generated.

-- clear the previous conformance validation messages
delete from orddcm_conformance_vld_msgs;

-- conformance validate the DICOM content
    declare
      src blob;
    begin
      select blob_src into src from medical_image_rel where id = 1;
      dbms_output.put_line('isConformanceValid(PatientModule) ' ||
       ord_dicom.isConformanceValid(src, 'PatientModule'));
    end;
    /

-- get the logged conformance validation messages
select message, msg_time time from orddcm_conformance_vld_msgs
  where rule_name='PatientModule';

7.2.9 isConformanceValid( ) for ORDImage

Format

isConformanceValid(src IN ORDSYS.ORDImage,
                   constraintName IN VARCHAR2) 
 RETURN INTEGER

Description

Parameters

src: The input DICOM content stored in an ORDImage object.
constraintName: The name of the constraint to be used for conformance validation checking.

Pragmas

None.

Exceptions

None.

Usage Notes

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

Examples

Delete any existing conformance validation messages. Check if the DICOM content stored in an ORDImage object is conformance valid. Then, show any new conformance validation messages that are generated.

-- clear the previous conformance validation messages
delete from orddcm_conformance_vld_msgs;

-- conformance validate the DICOM content
    declare
      src ordimage;
    begin
      select image_src into src from medical_image_rel where id = 1;
      dbms_output.put_line('isConformanceValid(PatientModule) ' ||
       ord_dicom.isConformanceValid(src, 'PatientModule'));
    end;
    / 

-- get the logged conformance validation messages
select message, msg_time time from orddcm_conformance_vld_msgs
  where rule_name='PatientModule';

7.3 DICOM PL/SQL API Procedures

The ORD_DICOM package defines these DICOM PL/SQL API procedures:

Note:

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.

7.3.1 createDicomImage( ) for BFILEs

Format

createDicomImage(src IN BFILE,
                 metadata IN SYS.XMLTYPE,
                 dest IN OUT NOCOPY BLOB)

Description

Creates a DICOM image from a source image and DICOM metadata. If the source content that is input to this procedure is DICOM content, the resulting destination DICOM content contains only the metadata that was input to this procedure in the metadata parameter. Thus, in the destination DICOM content, the metadata in the source DICOM content is removed and replaced by the metadata that was input.

Parameters

src: The source raster image stored in a BFILE.
metadata: DICOM metadata stored in data type XMLType. The metadata must include all standard and private attributes. It must include a new SOP instance UID for the destination DICOM image, ensuring that the destination DICOM content is globally unique.
dest: An empty BLOB in which to store the DICOM image created from the source image and metadata.

Pragmas

None.

Exceptions

None.

Usage Notes

See DICOM Encoding Rules for information about the encoding rules that support image content processing.

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

Examples

Create a DICOM image from a source BFILE and DICOM metadata:

declare
  src bfile;
  dest blob;
  metadata xmltype;
begin
  metadata := xmltype(bfilename('DICOMDIR', 'wm_meta.xml'), 
                      nls_charset_id('AL32UTF8'), 
                      'http://xmlns.oracle.com/ord/dicom/metadata_1_0');
 
  select bfile_src, blob_dest into src, dest from medical_image_rel 
    where id = 1 for update;
 
  ord_dicom.createDicomImage(src, metadata, dest);
end;
/

7.3.2 createDicomImage( ) for BLOBs

Format

createDicomImage(src IN BLOB,
                 metadata IN SYS.XMLTYPE,
                 dest IN OUT NOCOPY BLOB)

Description

Parameters

src: The source raster image stored in a BLOB.
metadata: DICOM metadata stored in data type XMLType. The metadata must include all standard and private attributes. It must include a new SOP instance UID for the destination DICOM image, ensuring that the destination DICOM content is globally unique.
dest: An empty BLOB in which to store the DICOM image created from the source image and metadata.

Pragmas

None.

Exceptions

None.

Usage Notes

See DICOM Encoding Rules for information about the encoding rules that support image content processing.

Examples

Create a DICOM image from a source BLOB and DICOM metadata:

declare
  src blob;
  dest blob;
  metadata xmltype;
begin
  metadata := xmltype(bfilename('DICOMDIR', 'wm_meta.xml'), 
                      nls_charset_id('AL32UTF8'), 
                      'http://xmlns.oracle.com/ord/dicom/metadata_1_0');
 
  select blob_src, blob_dest into src, dest from medical_image_rel 
    where id = 1 for update;
 
  ord_dicom.createDicomImage(src, metadata, dest);
end;
/

7.3.3 createDicomImage( ) for ORDImage

Format

createDicomImage(src IN ORDSYS.ORDImage,
                 metadata IN SYS.XMLTYPE,
                 dest IN OUT NOCOPY BLOB)

Description

Parameters

src: The source raster image stored in an ORDImage object.
metadata: DICOM metadata stored in data type XMLType. The metadata must include all standard and private attributes. It must include a new SOP instance UID for the destination DICOM image, ensuring that the destination DICOM content is globally unique.
dest: An empty BLOB in which to store the DICOM image created from the source image and metadata.

Pragmas

None.

Exceptions

None.

Usage Notes

See DICOM Encoding Rules for information about the encoding rules that support image content processing.

Examples

Create a DICOM image from a source ORDImage object and DICOM metadata:

declare
  src ordimage;
  dest blob;
  metadata xmltype;
begin
  metadata := xmltype(bfilename('DICOMDIR', 'wm_meta.xml'), 
                      nls_charset_id('AL32UTF8'), 
                      'http://xmlns.oracle.com/ord/dicom/metadata_1_0');
 
  select image_src, blob_dest into src, dest from medical_image_rel 
    where id = 1 for update;
 
  ord_dicom.createDicomImage(src, metadata, dest);
end;
/

7.3.4 export( )

Format

export(src IN BLOB,
       dest_type IN VARCHAR2,
       dest_location IN VARCHAR2,
       dest_name IN VARCHAR2)

Description

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

Parameters

src: The source location of the DICOM content.
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

The export( ) procedure 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 <user> permission to read and write to any file within the directory c:\mydir\work. Before executing these commands, you must be connected as a user with privileges to create a directory object.

CREATE OR REPLACE DIRECTORY DICOMDIR AS 'c:\mydir\work';
GRANT READ,WRITE ON DIRECTORY DICOMDIR TO <user>;

See Examples for DICOM PL/SQL API Functions and Procedures for more information about directory and table definitions.

Examples

Export DICOM content from a BLOB to a specified file:

declare
  src blob;
begin
  select blob_src into src from medical_image_rel where id = 1;
  ord_dicom.export(src, 'FILE', 'DICOMDIR', 'exported.dcm');
end;
/

7.3.5 importFrom( )

Format

importFrom(dest IN OUT NOCOPY BLOB,
           source_type IN VARCHAR2,
           source_location IN VARCHAR2,
           source_name IN VARCHAR2)

Description

Imports DICOM content from a specified source into a BLOB.

Parameters

dest: The storage destination of the imported DICOM file.
source_type: The type of the source (only FILE is supported).
source_location: The location of the source (must be a valid Oracle directory object).
source_name: The name of the source file.

Pragmas

None.

Exceptions

None.

Usage Notes

The importFrom( ) procedure 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 <user> permission to read any file within the directory c:\mydir\work. Before executing these commands, you must be connected as a user with privileges to create a directory object.

CREATE OR REPLACE DIRECTORY DICOMDIR AS 'c:\mydir\work';
GRANT READ ON DIRECTORY DICOMDIR TO <user>;

See Examples for DICOM PL/SQL API Functions and Procedures for more information about directory and table definitions.

Examples

Import the DICOM content into a BLOB:

declare
  dest blob;
begin
  select blob_dest into dest from medical_image_rel where id = 1 for update;
  ord_dicom.importFrom(dest, 'file', 'DICOMDIR', 'example.dcm');
end;
/

7.3.6 makeAnonymous( ) for BFILEs

Format

makeAnonymous(src IN BFILE,
              dest_sop_instance_uid IN VARCHAR2,
              dest IN OUT NOCOPY BLOB,
              anonymityDocName IN VARCHAR2 DEFAULT 'ordcman.xml')

Description

Removes patient identifying information from the source DICOM content after copying it into another DICOM content BLOB, based on a specified anonymity document.

Parameters

src: The input DICOM content stored in a BFILE.
dest_sop_instance_uid: The SOP instance UID of the destination DICOM content. It must ensure that the destination DICOM content is globally unique.
dest: An empty BLOB in which to store the anonymous DICOM content.
anonymityDocName: The name of the anonymity document. The default name is ordcman.xml.

Pragmas

None.

Exceptions

None.

Usage Notes

None.

Examples

Remove patient identifying information from the embedded DICOM content stored in a BFILE:

Note:

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

declare
  src bfile;
  dest blob;
  dest_sop_instance_uid varchar2(128) := '<unique-UID>';
begin
  select bfile_src, blob_dest into src, dest from medical_image_rel
    where id = 1 for update;
  ord_dicom.makeAnonymous(src, dest_sop_instance_uid, dest, 'ordcman.xml');
end;
/

7.3.7 makeAnonymous( ) for BLOBs

Format

makeAnonymous(src IN BLOB,
              dest_sop_instance_uid IN VARCHAR2,
              dest IN OUT NOCOPY BLOB,
              anonymityDocName IN VARCHAR2 DEFAULT 'ordcman.xml')

Description

Removes patient identifying information from the source DICOM content after copying it into another DICOM content BLOB, based on a specified anonymity document.

Parameters

src: The input DICOM content stored in a BLOB.
dest_sop_instance_uid: The SOP instance UID of the destination DICOM content. It must ensure that the destination DICOM content is globally unique.
dest: An empty BLOB in which to store the anonymous DICOM content.
anonymityDocName: The name of the anonymity document. The default name is ordcman.xml.

Pragmas

None.

Exceptions

None.

Usage Notes

None.

Examples

Remove patient identifying information from the embedded DICOM content stored in a BLOB:

Note:

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

declare
  src blob;
  dest blob;
  dest_sop_instance_uid varchar2(128) := '<unique-UID>';
begin
  select blob_src, blob_dest into src, dest from medical_image_rel
    where id = 1 for update;
  ord_dicom.makeAnonymous(src, dest_sop_instance_uid, dest, 'ordcman.xml');
end;
/

7.3.8 makeAnonymous( ) for ORDImage

Format

makeAnonymous(src IN ORDSYS.ORDImage,
              dest_sop_instance_uid IN VARCHAR2,
              dest IN OUT NOCOPY BLOB,
              anonymityDocName IN VARCHAR2 DEFAULT 'ordcman.xml')

Description

Removes patient identifying information from the source DICOM content after copying it into another DICOM content BLOB, based on a specified anonymity document.

Parameters

src: The input DICOM content stored in an ORDImage object.
dest_sop_instance_uid: The SOP instance UID of the destination DICOM content. It must ensure that the destination DICOM content is globally unique.
dest: An empty BLOB in which to store the anonymous DICOM content.
anonymityDocName: The name of the anonymity document. The default name is ordcman.xml.

Pragmas

None.

Exceptions

None.

Usage Notes

None.

Examples

Remove patient identifying information from the embedded DICOM content stored in an ORDImage object:

Note:

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

declare
  src ordimage;
  dest blob;
  dest_sop_instance_uid varchar2(128) := '<unique-UID>';
begin
  select image_src, blob_dest into src, dest from medical_image_rel
    where id = 1 for update;
  ord_dicom.makeAnonymous(src, dest_sop_instance_uid, dest, 'ordcman.xml');
end;
/

7.3.9 processCopy( ) for BFILEs

Format

processCopy(src IN BFILE,
            command IN VARCHAR2,
            dest IN OUT NOCOPY BLOB)

Description

Reads the DICOM content that is input from the source BFILE, performs the specified processing operations on the image, and then stores the resulting image in the destination BLOB. The original DICOM content in the source BFILE remains unchanged.

Parameters

src: The input DICOM content stored in the source BFILE.
command: A command string that accepts a processing operator as input. Valid values include: fileFormat, frame, contentFormat, compressionFormat, cut, scale, and rotate. See DICOM Processing and Supported Formats for information about processing operators.
dest: An empty BLOB in which to store the destination content.

Pragmas

None.

Exceptions

None.

Usage Notes

See DICOM Encoding Rules for information about the encoding rules that support DICOM content processing. See DICOM Processing and Supported Formats for more information about DICOM processing.

Examples

Generate a new JPEG thumbnail image from a DICOM source:

declare
  src bfile;
  dest blob;
begin
  select bfile_src, blob_dest into src, dest from medical_image_rel
    where id = 1 for update;
  ord_dicom.processCopy(src, 'fileFormat=jpeg maxScale=100 100', dest);
end;
/

7.3.10 processCopy( ) for BFILEs with SOP Instance UID

Format

processCopy(src IN BFILE,
            command IN VARCHAR2,
            dest_sop_instance_uid IN VARCHAR2,
            dest IN OUT NOCOPY BLOB,
            metadata IN SYS.XMLTYPE DEFAULT NULL)

Description

Reads the DICOM content that is input from the source BFILE, performs the specified processing operations on the image, updates it with the new metadata, and then stores the resulting image in the destination BLOB. The original DICOM content in the source BFILE remains unchanged.

Parameters

src: The input DICOM content stored in the source BFILE.
command: A command string that accepts a processing operator as input. Valid values include: frame, contentFormat, compressionFormat, cut, scale, and rotate. See DICOM Processing and Supported Formats for information about processing operators.
dest_sop_instance_uid: The SOP instance UID of the destination DICOM content. It must ensure that the destination DICOM content is globally unique.
dest: An empty BLOB in which to store the destination content.
metadata: The new metadata to be written into the new DICOM content.

Pragmas

None.

Exceptions

None.

Usage Notes

See DICOM Encoding Rules for information about the encoding rules that support DICOM content processing. See DICOM Processing and Supported Formats for more information about DICOM processing.

Examples

Generate a new compressed DICOM image:

Note:

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

  src bfile;
  dest blob;
  dest_sop_instance_uid varchar2(128) := '<unique-UID>';
begin
  select bfile_src, blob_dest into src, dest from medical_image_rel
    where id = 1 for update;
  ord_dicom.processCopy(
    src, 'CompressionFormat=jpeg', dest_sop_instance_uid, dest);
end;
/

7.3.11 processCopy( ) for BLOBs

Format

processCopy(src IN BLOB,
            command IN VARCHAR2,
            dest IN OUT NOCOPY BLOB)

Description

Reads the DICOM content that is input from the source BLOB, performs the specified processing operations on the image, and then stores the resulting image in the destination BLOB. The original DICOM content in the source BLOB remains unchanged.

Parameters

src: The input DICOM content stored in the source BLOB.
command: A command string that accepts a processing operator as input. Valid values include: fileFormat, frame, contentFormat, compressionFormat, cut, scale, and rotate. See DICOM Processing and Supported Formats for information about processing operators.
dest: An empty BLOB in which to store the destination content.

Pragmas

None.

Exceptions

None.

Usage Notes

See DICOM Encoding Rules for information about the encoding rules that support DICOM content processing. See DICOM Processing and Supported Formats for more information about DICOM processing.

Examples

Create a new JPEG thumbnail image:

  src blob;
  dest blob;
begin
  select blob_src, blob_dest into src, dest from medical_image_rel
    where id = 1 for update;
  ord_dicom.processCopy(src, 'fileFormat=jpeg maxScale=100 100' dest);
end;
/

7.3.12 processCopy( ) for BLOBs with SOP Instance UID

Format

processCopy(src IN BLOB,
            command IN VARCHAR2,
            dest_sop_instance_uid IN VARCHAR2,
            dest IN OUT NOCOPY BLOB,
            metadata IN SYS.XMLTYPE DEFAULT NULL)

Description

Reads the DICOM content that is input from the source BLOB, performs the specified processing operations on the image, updates it with the new metadata, and then stores the resulting image in the destination BLOB. The original DICOM content in the source BLOB remains unchanged.

Parameters

src: The input DICOM content stored in the source BLOB.
command: A command string that accepts a processing operator as input. Valid values include: frame, contentFormat, compressionFormat, cut, scale, and rotate. See DICOM Processing and Supported Formats for information about processing operators.
dest_sop_instance_uid: The SOP instance UID of the destination DICOM content. It must ensure that the destination DICOM content is globally unique.
dest: An empty BLOB in which to store the destination content.
metadata: The new metadata to be written into the new DICOM content.

Pragmas

None.

Exceptions

None.

Usage Notes

See DICOM Encoding Rules for information about the encoding rules that support DICOM content processing. See DICOM Processing and Supported Formats for more information about DICOM processing.

Examples

Create a new compressed DICOM image:

Note:

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

declare
  src blob;
  dest blob;
  dest_sop_instance_uid varchar2(128) := '<unique-UID>';
begin
  select blob_src, blob_dest into src, dest from medical_image_rel
    where id = 1 for update;
  ord_dicom.processCopy(
    src, 'CompressionFormat=jpeg', dest_sop_instance_uid, dest);
end;
/

7.3.13 processCopy( ) for ORDImage

Format

processCopy(src IN ORDSYS.ORDImage,
            command IN VARCHAR2,
            dest IN OUT NOCOPY BLOB)

Description

Reads the DICOM content that is input from the source ORDImage object, performs the specified processing operations on the image, and then stores the resulting image in the destination BLOB. The original DICOM content in the source ORDImage object remains unchanged.

Parameters

src: The input DICOM content stored in the source ORDImage object.
command: A command string that accepts an image processing operator as input. Valid values include: fileFormat, frame, contentFormat, compressionFormat, cut, scale, and rotate. See DICOM Processing and Supported Formats for information about image processing operators.
dest: An empty BLOB in which to store the destination content.

Pragmas

None.

Exceptions

None.

Usage Notes

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

See DICOM Encoding Rules for information about the encoding rules that support image content processing. See DICOM Processing and Supported Formats for more information about DICOM processing.

Examples

Create a new JPEG thumbnail image:

declare
  src ordimage;
  dest blob;
begin
  select image_src, blob_dest into src, dest from medical_image_rel
    where id = 1 for update;
  ord_dicom.processCopy(src, 'fileFormat=jpeg maxScale=100 100' dest);
end;
/

7.3.14 processCopy( ) for ORDImage with SOP Instance UID

Format

processCopy(src IN ORDSYS.ORDImage,
            command IN VARCHAR2,
            dest_sop_instance_uid IN VARCHAR2,
            dest IN OUT NOCOPY BLOB,
            metadata IN SYS.XMLTYPE DEFAULT NULL)

Description

Reads the DICOM content that is input from the source ORDImage object, performs the specified processing operations on the image, updates it with the new metadata, and then stores the resulting image in the destination BLOB. The original DICOM content in the source ORDImage object remains unchanged.

Parameters

src: The input DICOM content stored in the source ORDImage object.
command: A command string that accepts an image processing operator as input. Valid values include: frame, contentFormat, compressionFormat, cut, scale, and rotate. See DICOM Processing and Supported Formats for information about image processing operators.
dest_sop_instance_uid: The SOP instance UID of the destination DICOM image. It must ensure that the destination DICOM content is globally unique.
dest: An empty BLOB in which to store the destination content.
metadata: The new metadata to be written into the new DICOM content.

Pragmas

None.

Exceptions

None.

Usage Notes

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

See DICOM Encoding Rules for information about the encoding rules that support image content processing. See DICOM Processing and Supported Formats for more information about DICOM processing.

Examples

Create a new compressed DICOM image:

Note:

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

declare
  src ordimage;
  dest blob;
  dest_sop_instance_uid varchar2(128) := '<unique-UID>';
begin
  select image_src, blob_dest into src, dest from medical_image_rel
    where id = 1 for update;
  ord_dicom.processCopy(
    src, 'CompressionFormat=jpeg', dest_sop_instance_uid, dest);
end;
/

7.3.15 writeMetadata( ) for BFILEs

Format

writeMetadata(src IN BFILE,
              metadata IN SYS.XMLTYPE,
              dest IN OUT NOCOPY BLOB),

Description

Writes or modifies the current DICOM content with the metadata provided by making a copy of the existing DICOM content in the destination BLOB, and then modifying the metadata. The original DICOM content remains unchanged. The attributes in the destination DICOM content are copied from the metadata that was input.

Parameters

src: The input DICOM content stored in a BFILE.
metadata: The input metadata stored in data type XMLType. In the destination DICOM content, the input metadata is used to update the values for attributes that are identical to attributes in the source DICOM content, 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 BLOB in which to store the new DICOM content with the new metadata.

Pragmas

None.

Exceptions

None.

Usage Notes

See DICOM Encoding Rules for information about the encoding rules that support metadata extraction.

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

Examples

Write the new metadata to the copy of the DICOM content in the destination BLOB:

declare
  src bfile;
  dest blob;
  metadata xmltype;
begin
  metadata := xmltype(bfilename('DICOMDIR', 'wm_meta.xml'), 
                      nls_charset_id('AL32UTF8'), 
                      'http://xmlns.oracle.com/ord/dicom/metadata_1_0');
 
  select bfile_src, blob_dest into src, dest from medical_image_rel
    where id = 1 for update;
 
  ord_dicom.writeMetadata(src, metadata, dest);
 
end;
/

7.3.16 writeMetadata( ) for BLOBs

Format

writeMetadata(src IN BLOB,
              metadata IN SYS.XMLTYPE,
              dest IN OUT NOCOPY BLOB),

Description

Parameters

src: The input DICOM content stored in a BLOB.
metadata: The input metadata stored in data type XMLType. In the destination DICOM content, the input metadata is used to update the values for attributes that are identical to attributes in the source DICOM content, 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 BLOB in which to store the new DICOM content with the new metadata.

Pragmas

None.

Exceptions

None.

Usage Notes

See DICOM Encoding Rules for information about the encoding rules that support metadata extraction.

Examples

Write the new metadata to the copy of the DICOM content in the destination BLOB:

declare
  src blob;
  dest blob;
  metadata xmltype;
begin
  metadata := xmltype(bfilename('DICOMDIR', 'wm_meta.xml'), 
                      nls_charset_id('AL32UTF8'), 
                      'http://xmlns.oracle.com/ord/dicom/metadata_1_0');
 
  select blob_src, blob_dest into src, dest from medical_image_rel
    where id = 1 for update;
 
  ord_dicom.writeMetadata(src, metadata, dest);
 
end;
/

7.3.17 writeMetadata( ) for ORDImage

Format

writeMetadata(src IN ORDSYS.ORDImage,
              metadata IN SYS.XMLTYPE,
              dest IN OUT NOCOPY BLOB),

Description

Parameters

src: The input DICOM content stored in an ORDImage object.
metadata: The input metadata stored in data type XMLType. In the destination DICOM content, the input metadata is used to update the values for attributes that are identical to attributes in the source DICOM content, 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 BLOB in which to store the new DICOM content with the new metadata.

Pragmas

None.

Exceptions

None.

Usage Notes

See DICOM Encoding Rules for information about the encoding rules that support metadata extraction.

Examples

Write the new metadata to the copy of the DICOM content in the destination BLOB:

declare
  src ordimage;
  dest blob;
  metadata xmltype;
begin
  metadata := xmltype(bfilename('DICOMDIR', 'wm_meta.xml'), 
                      nls_charset_id('AL32UTF8'), 
                      'http://xmlns.oracle.com/ord/dicom/metadata_1_0');
 
  select image_src, blob_dest into src, dest from medical_image_rel
    where id = 1 for update;
 
  ord_dicom.writeMetadata(src, metadata, dest);
 
end;
/