Skip Headers

Oracle® interMedia Reference
10g Release 1 (10.1)

Part Number B10829-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Feedback

Go to previous page
Previous
Go to next page
Next
View PDF

Static Methods Unique to the ORDImage Object Type Relational Interface

This section presents reference information on the interMedia static methods unique to the ORDImage relational interface.

The relational interface adds interMedia support to image data stored in BLOBs and BFILEs rather than in the ORDImage object type. The following interface is defined in the ordispec.sql file:

.
.
.
  -- Static Methods for the relational interface
  STATIC PROCEDURE export(ctx             IN OUT RAW,
                          local_data      IN BLOB,
                          source_type     IN VARCHAR2,
                          source_location IN VARCHAR2,
                          source_name     IN VARCHAR2),
  --
  STATIC PROCEDURE importFrom(ctx             IN OUT RAW,
                              local_data      IN OUT NOCOPY BLOB,
                              source_type     IN VARCHAR2,
                              source_location IN VARCHAR2,
                              source_name     IN VARCHAR2),
  --
  STATIC PROCEDURE importFrom(ctx             IN OUT RAW,
                              local_data      IN OUT NOCOPY BLOB,
                              source_type     IN VARCHAR2,
                              source_location IN VARCHAR2,
                              source_name     IN VARCHAR2,
                              format          OUT VARCHAR2,
                              mime_type       OUT VARCHAR2),
  --
  STATIC PROCEDURE getProperties(imageBlob         IN BLOB,
                                 attributes        IN OUT NOCOPY CLOB,
                                 mimeType          OUT VARCHAR2,
                                 width             OUT INTEGER,
                                 height            OUT INTEGER,
                                 fileFormat        OUT VARCHAR2,
                                 contentFormat     OUT VARCHAR2,
                                 compressionFormat OUT VARCHAR2,
                                 contentLength     OUT INTEGER),
  --
  STATIC PROCEDURE getProperties(imageBlob         IN BLOB,
                                 attributes        IN OUT NOCOPY CLOB),
  --
  STATIC PROCEDURE getProperties(imageBfile       IN OUT NOCOPY BFILE,
                                 attributes        IN OUT NOCOPY CLOB,
                                 mimeType          OUT VARCHAR2,
                                 width             OUT INTEGER,
                                 height            OUT INTEGER,
                                 fileFormat        OUT VARCHAR2,
                                 contentFormat     OUT VARCHAR2,
                                 compressionFormat OUT VARCHAR2,
                                 contentLength     OUT INTEGER),
  --
  STATIC PROCEDURE getProperties(imageBfile IN OUT NOCOPY BFILE,
                                 attributes IN OUT NOCOPY CLOB),
  --
  STATIC PROCEDURE process(imageBlob IN OUT NOCOPY BLOB,
                           command   IN VARCHAR2),
  --
  STATIC PROCEDURE processCopy(imageBlob IN OUT NOCOPY BLOB,
                               command   IN VARCHAR2, 
                               dest      IN OUT NOCOPY BLOB),
  --
  STATIC PROCEDURE processCopy(imageBfile IN OUT BFILE,
                               command    IN VARCHAR2, 
                               dest       IN OUT NOCOPY BLOB),
.
.
.

Example Image Table Definition

The methods described in this section show examples based on a test image table TIMG. Refer to the TIMG table definition that follows when reading through the examples:


TIMG Table Definition
CREATE TABLE timg(n NUMBER, 
                  img BLOB,
                  attributes CLOB,
                  mimetype VARCHAR2(4000),
                  width INTEGER,
                  height INTEGER,
                  fileformat VARCHAR2(4000),
                  contentformat VARCHAR2(4000),
                  compressionformat VARCHAR2(4000),
                  contentlength INTEGER)
STORAGE (INITIAL 100K NEXT 100K PCTINCREASE 0);

INSERT INTO timg VALUES(1, EMPTY_BLOB(), EMPTY_CLOB(), NULL, 
                        NULL, NULL, NULL, NULL, NULL, NULL);
INSERT INTO timg VALUES(2, EMPTY_BLOB(), EMPTY_CLOB(), NULL, 
                        NULL, NULL, NULL, NULL, NULL, NULL);
COMMIT;

getProperties( ) for BLOBs

Format

getProperties(imageBlob IN BLOB,

attributes IN OUT NOCOPY CLOB);

Description

Reads the image BLOB data to get the values of the media attributes for supported formats, and then stores them in the input CLOB. This method populates the CLOB with a set of format properties in XML form.

Parameters

imageBlob

The image data represented as a BLOB.

attributes

The CLOB to hold the XML attribute information generated by the getProperties( ) method. This CLOB is populated with a set of format properties of the image BLOB data in XML form.

Usage Notes

None.

Pragmas

None.

Exceptions

ORDImageExceptions.NULL_CONTENT

This exception is raised when the imageBlob parameter is NULL.

Examples

Get the property information for known image attributes:

DECLARE
  img_attrib CLOB;
  img_data BLOB;
BEGIN
   SELECT img, attributes INTO img_data, img_attrib FROM timg WHERE N = 1 FOR UPDATE;
   ORDSYS.ORDImage.getProperties(img_data, img_attrib);

   DBMS_OUTPUT.put_line('Size of XML Annotations ' ||
                   TO_CHAR(DBMS_LOB.GETLENGTH(img_attrib)));
   UPDATE timg SET img=img_data, attributes=img_attrib WHERE N=1;
   COMMIT;
EXCEPTION
   WHEN OTHERS THEN
   RAISE;
END;
/


getProperties( ) (all attributes) for BLOBs

Format

getProperties(imageBlob IN BLOB,

attributes IN OUT NOCOPY CLOB,

mimeType OUT VARCHAR2,

width OUT INTEGER,

height OUT INTEGER,

fileFormat OUT VARCHAR2,

contentFormat OUT VARCHAR2,

compressionFormat OUT VARCHAR2,

contentLength OUT INTEGER);

Description

Reads the image BLOB data to get the values of the media attributes for supported formats, and then stores them in the input CLOB and returns them as explicit parameters. This method gets the properties for the following attributes of the image data: MIME type, width, height, file format, content format, compression format, and content length. It populates the CLOB with a set of format properties in XML form.

Parameters

imageBlob

The image data represented as a BLOB.

attributes

The CLOB to hold the XML attribute information generated by the getProperties( ) method. This CLOB is populated with a set of format properties of the image BLOB data in XML form.

mimeType

The MIME type of the image data.

width

The width of the image in pixels.

height

The height of the image in pixels.

fileFormat

The format of the image data.

contentFormat

The type of image (monochrome, and so forth).

compressionFormat

The compression algorithm used on the image data.

contentLength

The size of the image file on disk, in bytes.

Usage Notes

If a property cannot be extracted from the media source, then the respective parameter is set to NULL.

Pragmas

None.

Exceptions

ORDImageExceptions.NULL_CONTENT

This exception is raised when the imageBlob parameter is NULL.

Examples

Get the property information for known image attributes:

DECLARE
  img_data              BLOB;
  img_attrib        CLOB;
  mimeType          VARCHAR2(4000);
  width             NUMBER;
  height            NUMBER;
  fileFormat        VARCHAR2(32);
  contentFormat     VARCHAR2(4000);
  compressionFormat VARCHAR2(4000);
  contentLength     NUMBER;
BEGIN
   SELECT img, attributes, mimetype, width, height, fileformat, contentformat,
     compressionformat, contentlength INTO img_data, img_attrib, mimeType, width,
     height, fileFormat, contentFormat, compressionFormat, contentLength 
     FROM timg WHERE N = 1 FOR UPDATE;

  ORDSYS.ORDImage.getProperties(img_data, img_attrib, 
         mimeType, width, height, fileFormat,
         contentFormat, compressionFormat, contentLength);

   DBMS_OUTPUT.put_line('Size of XML Annotations ' ||
                   TO_CHAR(DBMS_LOB.GETLENGTH(img_attrib)));
   DBMS_OUTPUT.put_line('mimeType: ' || mimeType );
   DBMS_OUTPUT.put_line('width: ' || width );
   DBMS_OUTPUT.put_line('height: ' || height );
   DBMS_OUTPUT.put_line('fileFormat: ' || fileFormat );
   DBMS_OUTPUT.put_line('contentFormat: ' || contentFormat );
   DBMS_OUTPUT.put_line('compressionFormat: ' || compressionFormat );
   DBMS_OUTPUT.put_line('contentLength: ' || contentLength );
   UPDATE timg SET 
       img=img_data, 
       attributes=img_attrib, 
       mimetype=mimeType, 
       width=width, 
       height=height, 
       fileformat=fileFormat, 
       contentformat=contentFormat, 
       compressionformat=compressionFormat, 
       contentlength=contentLength 
    WHERE N=1;
   COMMIT;
EXCEPTION
   WHEN OTHERS THEN
   RAISE;
END;
/


getProperties( ) for BFILEs

Format

getProperties(imageBfile IN OUT NOCOPY BFILE,

attributes IN OUT NOCOPY CLOB);

Description

Reads the image BFILE data to get the values of the media attributes for supported formats, and then stores them in the input CLOB. This method populates the CLOB with a set of format properties in XML form.

Parameters

imageBfile

The image data represented as a BFILE.

attributes

The CLOB to hold the XML attribute information generated by the getProperties( ) method. This CLOB is populated with a set of format properties of the image BFILE data in XML form.

Usage Notes

None.

Pragmas

None.

Exceptions

ORDImageExceptions.NULL_CONTENT

This exception is raised when the imageBfile parameter is NULL.

Examples

Get the property information for known image attributes:

DECLARE
  img_attrib CLOB;
  data BFILE := BFILENAME('IMAGEDIR','testimg.dat');
BEGIN
   DBMS_LOB.CREATETEMPORARY(img_attrib, FALSE, DBMS_LOB.CALL);
   ORDSYS.ORDImage.getProperties(data, img_attrib);

   DBMS_OUTPUT.put_line('Size of XML Annotations ' ||
                   TO_CHAR(DBMS_LOB.GETLENGTH(img_attrib)));
EXCEPTION
   WHEN OTHERS THEN
   RAISE;
END;
/


getProperties( ) (all attributes) for BFILEs

Format

getProperties(imageBfile IN OUT NOCOPY BFILE,

attributes IN OUT NOCOPY CLOB,

mimeType OUT VARCHAR2,

width OUT INTEGER,

height OUT INTEGER,

fileFormat OUT VARCHAR2,

contentFormat OUT VARCHAR2,

compressionFormat OUT VARCHAR2,

contentLength OUT INTEGER);

Description

Reads the image BFILE data to get the values of the media attributes for supported formats, and then stores them in the input CLOB and returns them as explicit parameters. This method gets the properties for the following attributes of the image data: MIME type, width, height, file format, content format, compression format, and content length. It populates the CLOB with a set of format properties in XML form.

Parameters

imageBfile

The image data represented as a BFILE.

attributes

The CLOB to hold the XML attribute information generated by the getProperties( ) method. This CLOB is populated with a set of format properties of the image BFILE data in XML form.

mimeType

The MIME type of the image data.

width

The width of the image in pixels.

height

The height of the image in pixels.

fileFormat

The format of the image data.

contentFormat

The type of image (monochrome, and so forth).

compressionFormat

The compression algorithm used on the image data.

contentLength

The size of the image file on disk, in bytes.

Usage Notes

If a property cannot be extracted from the media source, then the respective parameter is set to NULL.

Pragmas

None.

Exceptions

ORDImageExceptions.NULL_CONTENT

This exception is raised when the imageBfile parameter is NULL.

Examples

Get the property information for known image attributes:

DECLARE
  img_data          BFILE := BFILENAME('IMAGEDIR','testimg.dat');
  img_attrib        CLOB;
  mimeType          VARCHAR2(80);
  width             NUMBER;
  height            NUMBER;
  fileFormat        VARCHAR2(32);
  contentFormat     VARCHAR2(4000);
  compressionFormat VARCHAR2(4000);
  contentLength     NUMBER;
BEGIN
   DBMS_LOB.CREATETEMPORARY(img_attrib, FALSE, DBMS_LOB.CALL);

  ORDSYS.ORDImage.getProperties(img_data, img_attrib, 
         mimeType, width, height, fileFormat, 
         contentFormat, compressionFormat, contentLength);

   DBMS_OUTPUT.put_line('Size of XML Annotations ' ||
                   TO_CHAR(DBMS_LOB.GETLENGTH(img_attrib)));
   DBMS_OUTPUT.put_line('mimeType: ' || mimeType );
   DBMS_OUTPUT.put_line('width: ' || width );
   DBMS_OUTPUT.put_line('height: ' || height );
   DBMS_OUTPUT.put_line('fileFormat: ' || fileFormat );
   DBMS_OUTPUT.put_line('contentFormat: ' || contentFormat );
   DBMS_OUTPUT.put_line('compressionFormat: ' || compressionFormat );
   DBMS_OUTPUT.put_line('contentLength: ' || contentLength );
EXCEPTION
   WHEN OTHERS THEN
   RAISE;
END;
/


process( )

Format

process(imageBlob IN OUT NOCOPY BLOB,

command IN VARCHAR2);

Description

Performs one or more image processing operations on a BLOB, writing the image back onto itself.

Parameters

imageBlob

The image data represented as a BLOB.

command

A list of image processing operations to perform on the image.

Usage Notes

You can change one or more of the image attributes shown in Table 6-1. Table 6-2 shows additional changes that can be made only to raw pixel and foreign images.

See Appendix D for more information on process( ) operators.

The process( ) method changes image attributes, therefore if you are storing image attributes, you should call the getProperties( ) method after calling the process( ) method.

Pragmas

None.

Exceptions

ORDImageExceptions.DATA_NOT_LOCAL

This exception is raised if you call the process( ) method and the imageBlob parameter is not initialized.

Examples

Example 1: Change the image in the image_data BLOB to use higher quality JPEG compression and double the length of the image along the X-axis:

ORDSYS.ORDImage.process(
image_data,'compressionFormat=JPEG,compressionQuality=MAXCOMPRATIO, xScale="2.0"');

Note that changing the length on only one axis (for example, xScale=2.0) does not affect the length on the other axis, and would result in image distortion. Also, only the xScale and yScale parameters can be combined in a single scale operation. Any other combinations of scale operators result in an error.

Example 2: Create at most a 32-by-32 pixel thumbnail image, preserving the original aspect ratio. The maxScale and fixedScale operators are especially useful for creating thumbnail images from various-sized originals:

ORDSYS.ORDImage.process(image_data, 'maxScale=32 32');

Example 3: Convert the image to TIFF:

DECLARE
img_attrib CLOB;  
image_data BLOB;
BEGIN
   SELECT img, attributes INTO image_data, img_attrib FROM timg 
     WHERE N = 1 FOR UPDATE;
   ORDSYS.ORDImage.process(image_data, 'fileFormat=TIFF');
   ORDSYS.ORDImage.getProperties(image_data, img_attrib);
   UPDATE timg SET img = image_data, attributes=img_attrib WHERE N = 1;
   COMMIT;
EXCEPTION
   WHEN OTHERS THEN
   RAISE;
END;
/


processCopy( ) for BLOBs

Format

processCopy(imageBlob IN BLOB,

command IN VARCHAR2,

dest IN OUT NOCOPY BLOB);

Description

Copies an image stored internally or externally to another image stored internally in the source.localData attribute (of the embedded ORDSource object) and performs one or more image processing operations on the copy.

Parameters

imageBlob

The source image data represented as a BLOB.

command

A list of image processing changes to make for the image in the new copy.

dest

The destination of the new image.

Usage Notes

See Table 6-1, "Image Processing Operators" and Table 6-2, "Additional Image Processing Operators for Raw Pixel and Foreign Images".

You cannot specify the same BLOB as both the source and destination.

Calling this method processes the image into the destination BLOB from any source BLOB.

The processCopy( ) method changes image attributes, therefore, if you are storing image attributes, you should call the getProperties( ) method on the destination image after calling the processCopy( ) method.

See Appendix D for more information on processCopy( ) operators.

Pragmas

None.

Exceptions

ORDImageExceptions.DATA_NOT_LOCAL

This exception is raised if you call the processCopy( ) method and the imageBlob parameter is not initialized.

Examples

Copy an image, changing the file format, compression format, and content format in the destination image:

DECLARE
  dest_attrib      CLOB;
  image_data       BLOB;
  destination_data BLOB;
  the_Command      VARCHAR2(4000);
BEGIN
   SELECT img INTO image_data FROM timg WHERE N = 1;
   SELECT img, attributes INTO destination_data, dest_attrib FROM timg 
      WHERE N = 2 FOR UPDATE;

   the_Command := 'fileFormat=tiff, compressionFormat=packbits, contentFormat=8bitlut';
   ORDSYS.ORDImage.processCopy(image_data, the_Command, destination_data);
   ORDSYS.ORDImage.getProperties(destination_data, dest_attrib);
   UPDATE timg SET img = destination_data, attributes=dest_attrib WHERE N = 2;
   COMMIT;
EXCEPTION
   WHEN OTHERS THEN
   RAISE;
END;
/


processCopy( ) for BFILEs

Format

processCopy(imageBfile IN OUT NOCOPY BFILE,

command IN VARCHAR2,

dest IN OUT NOCOPY BLOB);

Description

Copies an image stored internally or externally to another image stored internally in the source.localData attribute (of the embedded ORDSource object) and performs one or more image processing operations on the copy.

Parameters

imageBfile

The image data represented as a BFILE.

command

A list of image processing changes to make for the image in the new copy.

dest

The destination of the new image.

Usage Notes

See Table 6-1, "Image Processing Operators" and Table 6-2, "Additional Image Processing Operators for Raw Pixel and Foreign Images".

Calling this method processes the image into the destination BLOB from any source BFILE.

The processCopy( ) method changes image attributes, therefore, if you are storing image attributes, you should call the getProperties( ) method on the destination image after calling the processCopy( ) method.

See Appendix D for more information on processCopy( ) operators.

Pragmas

None.

Exceptions

ORDImageExceptions.NULL_DESTINATION

This exception is raised if you call the processCopy( ) method and the destination image is NULL.

ORDImageExceptions.NULL_LOCAL_DATA

This exception is raised when the imageBfile parameter is NULL.

Examples

Copy an image, generating a thumbnail image of, at most, 32 x 32 pixels in the destination image:

DECLARE
  dest_attrib      CLOB;
  image_data       BFILE := BFILENAME('IMAGEDIR','testimg.dat');
  destination_data BLOB;
  the_Command      VARCHAR2(4000);
BEGIN
   SELECT img, attributes INTO destination_data, dest_attrib FROM timg 
       WHERE N = 2 FOR UPDATE;

   the_Command := 'maxScale=32 32';
   ORDSYS.ORDImage.processCopy(image_data, the_Command, destination_data);
   ORDSYS.ORDImage.getProperties(destination_data, dest_attrib);
   UPDATE timg SET img = destination_data, attributes=dest_attrib WHERE N = 2;
   COMMIT;
EXCEPTION
   WHEN OTHERS THEN
   RAISE;
END;
/