1. Reference
  2. Oracle Multimedia ORD_IMAGE PL/SQL Package

5 Oracle Multimedia ORD_IMAGE PL/SQL Package

Oracle Multimedia provides the ORD_IMAGE PL/SQL package. This package provides functions and procedures to perform common operations such as importing and exporting image data to and from operating system files, extracting metadata from and writing metadata to image data, generating thumbnail images, and converting the format of image data.

This package adds Oracle Multimedia support to image data stored in BLOBs and BFILEs.

The ORD_IMAGE package is defined in the ordirpsp.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)

The examples in these topics assume that the TIMG table and the IMAGEDIR directory exist.

See the following topics for details about the functions and procedures in the ORD_IMAGE PL/SQL package:

See Also:

5.1 ORD_IMAGE PL/SQL Package: getMetadata( ) for BFILEs

Format

getMetadata(imageBfile   IN BFILE, 
            metadataType IN VARCHAR2 DEFAULT ‘ALL’) RETURN SYS.XMLSequenceType;

Description

Extracts the specified types of metadata from the image data stored in a BFILE, and returns an array of schema-valid XML documents. If no matching metadata is found, an empty array is returned.

Parameters

imageBfile

The image data represented as a BFILE.

metadataType

A string that identifies the type of embedded metadata to extract. Valid values are: ALL, ORDIMAGE, XMP, EXIF, and IPTC-IIM. The default value is ALL.

Usage Notes

When the value of input parameter metadataType is ALL, and two or more types of supported metadata are present in the image, this function returns several XML documents, one for each type of metadata found. For other values of the input parameter, the function returns zero or one XML document.

Each document is stored as an instance of XMLType, and is based on one of the metadata schemas. Use the XQuery function fn:namespace-uri to determine the type of metadata represented in that document.

See Oracle Multimedia Metadata XML Schemas for information about the supported metadata schemas.

See Also:

Pragmas

None.

Exceptions

ORDImageExceptions.NULL_CONTENT

This exception is raised when the imageBfile parameter is NULL.

Examples

Extract the embedded metadata from an imageBfile, and return an array of schema-valid XML documents:

DECLARE
   imageBfile BFILE := BFILENAME('IMAGEDIR','testimg.jpg');
   metav XMLSequenceType;
   ns varchar2(4000);
BEGIN

   -- get metadata from bfile
   metav := ORDSYS.ORD_IMAGE.getMetadata(imageBfile, 'ALL');

   -- print the namespace of each metadata document
   FOR i IN 1..metav.count LOOP
        SELECT xmlcast(xmlquery('fn:namespace-uri($x/*)'
            PASSING metav(i) AS "x" RETURNING content) AS varchar2(4000))
            INTO ns FROM dual;
        DBMS_OUTPUT.PUT_LINE('namespace: ' || ns);
   END LOOP;

EXCEPTION
   WHEN ORDSYS.ORDImageExceptions.NULL_CONTENT THEN
        DBMS_OUTPUT.PUT_LINE('imageBfile is null');
   WHEN OTHERS THEN
        RAISE;
END;
/

5.2 ORD_IMAGE PL/SQL Package: getMetadata( ) for BLOBs

Format

getMetadata(imageBlob    IN BLOB, 
            metadataType IN VARCHAR2 DEFAULT ‘ALL’) RETURN SYS.XMLSequenceType;

Description

Extracts the specified types of metadata from the image data stored in a BLOB, and returns an array of schema-valid XML documents. If no matching metadata is found, an empty array is returned.

Parameters

imageBlob

The image data represented as a BLOB.

metadataType

A string that identifies the type of embedded metadata to extract. Valid values are: ALL, ORDIMAGE, XMP, EXIF, and IPTC-IIM. The default value is ALL.

Usage Notes

When the value of input parameter metadataType is ALL, and two or more types of supported metadata are present in the image, this function returns several XML documents, one for each type of metadata found. For other values of the input parameter, the function returns zero or one XML document.

Each document is stored as an instance of XMLType, and is based on one of the metadata schemas. Use the XQuery function fn:namespace-uri to determine the type of metadata represented in that document.

See Oracle Multimedia Metadata XML Schemas for information about the supported metadata schemas.

See Also:

Pragmas

None.

Exceptions

ORDImageExceptions.NULL_CONTENT

This exception is raised when the imageBlob parameter is NULL.

Examples

Extract the embedded metadata from an imageBlob, and return an array of schema-valid XML documents:

DECLARE
   imageBlob BLOB;
   metav XMLSequenceType;
   ns varchar2(4000);
BEGIN

   SELECT img INTO imageBlob FROM timg WHERE N=1910;

   -- get metadata from blob
   metav:=ORDSYS.ORD_IMAGE.getMetadata(imageBlob, 'ALL');

   -- print the namespace of each metadata document
   FOR i IN 1..metav.count LOOP
        SELECT xmlcast(xmlquery('fn:namespace-uri($x/*)'
            PASSING metav(i) AS "x" RETURNING content) AS varchar2(4000))
            INTO ns FROM dual;
        DBMS_OUTPUT.PUT_LINE('namespace: ' || ns);
   END LOOP;

EXCEPTION
   WHEN ORDSYS.ORDImageExceptions.NULL_CONTENT THEN
        DBMS_OUTPUT.PUT_LINE('imageBlob is null');
   WHEN OTHERS THEN
        RAISE;
END;
/

5.3 ORD_IMAGE PL/SQL Package: applyWatermark( ) image for BFILEs

Format

applyWatermark(imageBfile           IN OUT NOCOPY BFILE, 
               added_image          IN OUT NOCOPY BFILE, 
               dest                 IN OUT NOCOPY BLOB, 
               logging              OUT VARCHAR2, 
               watermark_properties IN ordsys.ord_str_list default null);

Description

Overlays an image watermark onto a source image stored in a BFILE, and writes it to a destination BLOB.

Parameters

imageBfile

The source image data represented as a BFILE.

added_image

The watermark image stored in a BFILE to be added to the source image.

dest

The destination BLOB for the watermarked image.

logging

A string that contains information about any unexpected behavior that occurred during the watermarking operation. If the operation is successful, an empty string is returned. Otherwise, this procedure returns a string that describes the unexpected behavior.

watermark_properties

A string list of name-value pairs that define attributes of the watermark image, including: width, height, position, position_x, position_y, and transparency.

Usage Notes

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

See Watermarking Operations for more information about watermarking operations and watermark properties.

Pragmas

None.

Exceptions

ORDImageExceptions.NULL_CONTENT

This exception is raised when the source image or added image is NULL.

ORDImageExceptions.NULL_DESTINATION

This exception is raised when the destination image BLOB is NULL.

Examples

Add a watermark image to an image BFILE:

-- add image as watermark for BFILE

DECLARE
   source_image BFILE:=BFILENAME('IMAGEDIR','testimg.jpg');
   added_image BFILE:=BFILENAME('IMAGEDIR','testlogo.png');
   dest_image BLOB;
   prop ordsys.ord_str_list;
   logging VARCHAR2(2000);
BEGIN
   SELECT img INTO dest_image FROM timg WHERE N=2402 FOR UPDATE;

   -- specify properties
   prop:=ordsys.ord_str_list(
        'position=bottomright',
        'transparency=0.2');

   -- add image watermark to source image
   ORDSYS.ORD_IMAGE.applyWatermark(source_image, added_image, dest_image, 
        logging, prop);

   UPDATE timg SET img=dest_image WHERE N=2402;
   COMMIT;

EXCEPTION
   WHEN OTHERS THEN
        RAISE;
END;
/

5.4 ORD_IMAGE PL/SQL Package: applyWatermark( ) image for BLOBs

Format

applyWatermark(imageBlob            IN BLOB, 
               added_image          IN BLOB, 
               dest                 IN OUT NOCOPY BLOB, 
               logging              OUT VARCHAR2, 
               watermark_properties IN ordsys.ord_str_list default null);

Description

Overlays an image watermark onto a source image stored in a BLOB, and writes it to a destination BLOB.

Parameters

imageBlob

The source image data represented as a BLOB.

added_image

The watermark image stored in a BLOB to be added to the source image.

dest

The destination BLOB for the watermarked image.

logging

A string that contains information about any unexpected behavior that occurred during the watermarking operation. If the operation is successful, an empty string is returned. Otherwise, this procedure returns a string that describes the unexpected behavior.

watermark_properties

A string list of name-value pairs that define attributes of the watermark image, including: width, height, position, position_x, position_y, and transparency.

Usage Notes

Because temporary LOBs do not have read consistency, you cannot use the same temporary LOB for both the imageBlob and dest parameters.

Calling this procedure processes the image into the destination BLOB from the source BLOB.

See Watermarking Operations for more information about watermarking operations and watermark properties.

Pragmas

None.

Exceptions

ORDImageExceptions.NULL_CONTENT

This exception is raised when the source image or added image is NULL.

ORDImageExceptions.NULL_DESTINATION

This exception is raised when the destination image BLOB is NULL.

Examples

Add a watermark image to an image BLOB:

-- add image as watermark for BLOB

DECLARE
   source_image BLOB;
   added_image BLOB;
   dest_image BLOB;
   prop ordsys.ord_str_list;
   logging VARCHAR2(2000);
BEGIN
   SELECT img INTO source_image FROM timg WHERE N=1910;
   SELECT img INTO added_image FROM timg WHERE N=1940;
   SELECT img INTO dest_image FROM timg WHERE N=2402 FOR UPDATE;

   -- specify properties
   prop:=ordsys.ord_str_list(
        'position=bottomright',
        'transparency=0.2');

   -- add image watermark to source image
   ORDSYS.ORD_IMAGE.applyWatermark(source_image, added_image, dest_image,
       logging, prop);

   UPDATE timg SET img=dest_image WHERE N=2402;
   COMMIT;

EXCEPTION
   WHEN OTHERS THEN
        RAISE;
END;
/

5.5 ORD_IMAGE PL/SQL Package: applyWatermark( ) text for BFILEs

Format

applyWatermark(imageBfile           IN OUT NOCOPY BFILE, 
               added_text           IN VARCHAR2, 
               dest                 IN OUT NOCOPY BLOB, 
               logging              OUT VARCHAR2, 
               watermark_properties IN ordsys.ord_str_list default null);

Description

Overlays a text watermark onto a source image stored in a BFILE, and writes it to a destination BLOB.

Parameters

imageBfile

The source image data represented as a BFILE.

added_text

The watermark text stored in a string to be added to the source image.

dest

The destination BLOB for the watermarked image.

logging

A string that contains information about any unexpected behavior that occurred during the watermarking operation. If the operation is successful, an empty string is returned. Otherwise, this procedure returns a string that describes the unexpected behavior. For example, if the watermark text is so long that it is truncated, this string is returned: WARNING: text is too long and truncated.

watermark_properties

A string list of name-value pairs that define attributes of the watermark text, including: font_name, font_style, font_size, text_color, position_x, position_y, and transparency.

Usage Notes

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

See Watermarking Operations for more information about watermarking operations and watermark properties.

Pragmas

None.

Exceptions

ORDImageExceptions.NULL_CONTENT

This exception is raised when the source image is NULL.

ORDImageExceptions.NULL_DESTINATION

This exception is raised when the destination image BLOB is NULL.

Examples

Add watermark text to an image BFILE:

-- add text as watermark for BFILE

DECLARE
   source_image BFILE:=BFILENAME('IMAGEDIR','testimg.jpg');
   added_text varchar2(200);
   dest_image BLOB;
   prop ordsys.ord_str_list;
   logging VARCHAR2(2000);
BEGIN
   SELECT img INTO dest_image FROM timg WHERE N=2402 FOR UPDATE;

   added_text:='Oracle Multimedia @ 2016';

   -- specify properties
   prop:=ordsys.ord_str_list(
        'font_name=Times New Roman',
        'font_style=bold',
        'font_size=50',
        'text_color=red',
        'position_x=100',
        'position_y=100',
        'transparency=0.6');

   -- add text watermark to source image
   ORDSYS.ORD_IMAGE.applyWatermark(source_image, added_text, dest_image,
        logging, prop);

   UPDATE timg SET img=dest_image WHERE N=2402;
   COMMIT;

EXCEPTION
   WHEN OTHERS THEN
        RAISE;
END;
/

5.6 ORD_IMAGE PL/SQL Package: applyWatermark( ) text for BLOBs

Format

applyWatermark(imageBlob            IN BLOB, 
               added_text           IN VARCHAR2, 
               dest                 IN OUT NOCOPY BLOB, 
               logging              OUT VARCHAR2, 
               watermark_properties IN ordsys.ord_str_list default null);

Description

Overlays a text watermark onto a source image stored in a BLOB, and writes it to a destination BLOB.

Parameters

imageBlob

The source image data represented as a BLOB.

added_image

The watermark text stored in a string to be added to the source image.

dest

The destination BLOB for the watermarked image.

logging

A string that contains information about any unexpected behavior that occurred during the watermarking operation. If the operation is successful, an empty string is returned. Otherwise, this procedure returns a string that describes the unexpected behavior. For example, if the watermark text is so long that it is truncated, this string is returned: WARNING: text is too long and truncated.

watermark_properties

A string list of name-value pairs that define attributes of the watermark text, including: font_name, font_style, font_size, text_color, position_x, position_y, and transparency.

Usage Notes

Because temporary LOBs do not have read consistency, you cannot use the same temporary LOB for both the imageBlob and dest parameters.

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

See Watermarking Operations for more information about watermarking operations and watermark properties.

Pragmas

None.

Exceptions

ORDImageExceptions.NULL_CONTENT

This exception is raised when the source image is NULL.

ORDImageExceptions.NULL_DESTINATION

This exception is raised when the destination image BLOB is NULL.

Examples

Add watermark text to an image BLOB:

-- add text as watermark for BLOB

DECLARE
   source_image BLOB;
   added_text varchar2(200);
   dest_image BLOB;
   prop ordsys.ord_str_list;
   logging VARCHAR2(2000);
BEGIN
   SELECT img INTO source_image FROM timg WHERE N=1910;
   SELECT img INTO dest_image FROM timg WHERE N=2402 FOR UPDATE;

   added_text:='Oracle Multimedia @ 2016';

   -- specify properties
   prop := ordsys.ord_str_list(
        'font_name=Times New Roman',
        'font_style=bold',
        'font_size=50',
        'text_color=red',
        'position_x=100',
        'position_y=100',
        'transparency=0.6');

   -- add text watermark to source image
   ORDSYS.ORD_IMAGE.applyWatermark(source_image, added_text, dest_image,
        logging, prop);

   UPDATE timg SET img=dest_image WHERE N=2402;
   COMMIT;

EXCEPTION
   WHEN OTHERS THEN
        RAISE;
END;
/

5.7 ORD_IMAGE PL/SQL Package: convert( ) for BFILEs

Format

convert(imageBfile IN OUT NOCOPY BFILE, 
        fileFormat IN VARCHAR2, 
        dest       IN OUT NOCOPY BLOB);

Description

Creates a derivative image from a source image stored in a BFILE by converting the source image into an image of the specified file format and writing the resulting image into the destination BLOB. The original source image is not modified.

Parameters

imageBfile

The source image data represented as a BFILE.

fileFormat

The file format of the resulting image.

dest

The destination of the new image.

Usage Notes

None.

Pragmas

None.

Exceptions

ORDImageExceptions.NULL_DESTINATION

This exception is raised when the destination image BLOB is NULL.

ORDImageExceptions.NULL_LOCAL_DATA

This exception is raised when the imageBfile parameter is NULL.

Examples

Convert an image to another format:

DECLARE
   source_image BFILE:=BFILENAME('IMAGEDIR','testimg.jpg');
   dest_image BLOB;
BEGIN
   SELECT img INTO dest_image FROM timg WHERE N=2402 FOR UPDATE;
   
   -- convert source image to PNG
   ORDSYS.ORD_IMAGE.convert(source_image, 'PNG', dest_image);

   UPDATE timg SET img=dest_image WHERE N=2402;

EXCEPTION
   WHEN OTHERS THEN
        RAISE;
END;
/

5.8 ORD_IMAGE PL/SQL Package: convert( ) for BLOBs

Format

convert(imageBlob  IN BLOB, 
        fileFormat IN VARCHAR2, 
        dest       IN OUT NOCOPY BLOB);

Description

Creates a derivative image from a source image stored in a BLOB by converting the source image into an image of the specified file format and writing the resulting image into the destination BLOB. The original source image is not modified.

Parameters

imageBlob

The image data represented as a BLOB.

fileFormat

The file format of the resulting image.

dest

The destination of the new image.

Usage Notes

Because temporary LOBs do not have read consistency, you cannot use the same temporary LOB for both the imageBlob and dest parameters.

Pragmas

None.

Exceptions

ORDImageExceptions.DATA_NOT_LOCAL

This exception is raised when the imageBlob parameter is NULL.

Examples

Convert an image to another format:

DECLARE
   source_image BLOB;
   dest_image BLOB;
BEGIN
   SELECT img INTO source_image FROM timg WHERE N=1910;
   SELECT img INTO dest_image FROM timg WHERE N=2402 FOR UPDATE;
   
   -- convert source image to PNG
   ORDSYS.ORD_IMAGE.convert(source_image, 'PNG', dest_image);

   UPDATE timg SET img=dest_image WHERE N=2402;
   COMMIT;

EXCEPTION
   WHEN OTHERS THEN
        RAISE;
END;
/

5.9 ORD_IMAGE PL/SQL Package: convert( ) in place

Format

convert(imageBlob  IN OUT NOCOPY BLOB, 
        fileFormat IN VARCHAR2);

Description

Converts an image into the specified file format, writing the image back onto itself.

Parameters

imageBlob

The image data represented as a BLOB.

fileFormat

The file format of the resulting image.

Usage Notes

None.

Pragmas

None.

Exceptions

ORDImageExceptions.DATA_NOT_LOCAL

This exception is raised when the imageBlob parameter is NULL.

Examples

Convert an image to another format:

DECLARE
   image BLOB;
BEGIN
   SELECT img INTO image FROM timg WHERE N=2402 FOR UPDATE;
   
   -- convert image to JFIF and update in place
   ORDSYS.ORD_IMAGE.convert(image, 'JFIF');

   UPDATE timg SET img=image WHERE N=2402;
   COMMIT;

EXCEPTION
   WHEN OTHERS THEN
        RAISE;
END;
/

5.10 ORD_IMAGE PL/SQL Package: crop( ) for BFILEs

Format

crop(imageBfile IN OUT NOCOPY BFILE, 
     originX    IN INTEGER, 
     originY    IN INTEGER, 
     width      IN INTEGER, 
     height     IN INTEGER, 
     dest       IN OUT NOCOPY BLOB);

Description

Creates a derivative image from a source image stored in a BFILE by cropping the source image and writing the resulting image into the destination BLOB. The original source image is not modified.

Parameters

imageBfile

The image data represented as a BFILE.

originX

Origin X coordinate pixel value. First pixel value is 0 (zero).

originY

Origin Y coordinate pixel value. First pixel value is 0 (zero).

width

The width of the cut image in pixels.

height

The height of the cut image in pixels.

dest

The destination of the new image.

Usage Notes

None.

Pragmas

None.

Exceptions

ORDImageExceptions.NULL_DESTINATION

This exception is raised when the destination image BLOB is NULL.

ORDImageExceptions.NULL_LOCAL_DATA

This exception is raised when the imageBfile parameter is NULL.

Examples

Create a new image from a source image, and crop it:

DECLARE
   source_image BFILE := BFILENAME('IMAGEDIR','testimg.jpg');
   dest_image BLOB;
BEGIN
   SELECT img INTO dest_image FROM timg WHERE N=2402 FOR UPDATE;

   -- crop image from x1=0,y1=0 with width=20,heigth=20
   ORDSYS.ORD_IMAGE.crop(source_image, 0,0,20,20, dest_image);

   UPDATE timg SET img=dest_image WHERE N=2402;
   COMMIT;

EXCEPTION
   WHEN OTHERS THEN
        RAISE;
END;
/

5.11 ORD_IMAGE PL/SQL Package: crop( ) for BLOBs

Format

crop(imageBlob IN BLOB, 
     originX   IN INTEGER, 
     originY   IN INTEGER, 
     width     IN INTEGER, 
     height    IN INTEGER, 
     dest      IN OUT NOCOPY BLOB);

Description

Creates a derivative image from a source image stored in a BLOB by cropping the source image and writing the resulting image into the destination BLOB. The original source image is not modified.

Parameters

imageBlob

The image data represented as a BLOB.

originX

Origin X coordinate pixel value. First pixel value is 0 (zero).

originY

Origin Y coordinate pixel value. First pixel value is 0 (zero).

width

The width of the cut image in pixels.

height

The height of the cut image in pixels.

dest

The destination of the new image.

Usage Notes

Because temporary LOBs do not have read consistency, you cannot use the same temporary LOB for both the imageBlob and dest parameters.

Pragmas

None.

Exceptions

ORDImageExceptions.DATA_NOT_LOCAL

This exception is raised when the imageBlob parameter is NULL.

Examples

Create a new image from a source image, and crop it:

DECLARE
   source_image BLOB;
   dest_image BLOB;
BEGIN
   SELECT img INTO source_image FROM timg WHERE N=1910;
   SELECT img INTO dest_image FROM timg WHERE N=2402 FOR UPDATE;

   -- crop image from x1=0,y1=0 with width=20,height=20
   ORDSYS.ORD_IMAGE.crop(source_image, 0,0,20,20, dest_image);

   UPDATE timg SET img=dest_image WHERE N=2402;
   COMMIT;

EXCEPTION
   WHEN OTHERS THEN
        RAISE;
END;
/

5.12 ORD_IMAGE PL/SQL Package: crop( ) in place

Format

crop(imageBlob IN OUT NOCOPY BLOB, 
     originX   IN INTEGER, 
     originY   IN INTEGER, 
     width     IN INTEGER, 
     height    IN INTEGER);

Description

Defines a window to crop from the image in imageBlob, writing the cropped image back onto itself.

Parameters

imageBlob

The image data represented as a BLOB.

originX

Origin X coordinate pixel value. First pixel value is 0 (zero).

originY

Origin Y coordinate pixel value. First pixel value is 0 (zero).

width

The width of the cut image in pixels.

height

The height of the cut image in pixels.

Usage Notes

None.

Pragmas

None.

Exceptions

ORDImageExceptions.DATA_NOT_LOCAL

This exception is raised when the imageBlob parameter is NULL.

Examples

Create a new image and crop it:

DECLARE
   image BLOB;
BEGIN
   SELECT img INTO image FROM timg WHERE N=2402 FOR UPDATE;
   
   -- crop image from x1=0,y1=0 with width=20,height=20
   ORDSYS.ORD_IMAGE.crop(image, 0,0,20,20);

   UPDATE timg SET img=image WHERE N=2402;
   COMMIT;

EXCEPTION
   WHEN OTHERS THEN
        RAISE;
END;
/

5.13 ORD_IMAGE PL/SQL Package: flip( ) for BFILEs

Format

flip(imageBfile IN OUT NOCOPY BFILE, 
     dest       IN OUT NOCOPY BLOB);

Description

Places the scanlines of a source image in inverse order, swapped top to bottom, and writes the resulting image into the destination BLOB.

Parameters

imageBfile

The source image data represented as a BFILE.

dest

The destination of the new image.

Usage Notes

None.

Pragmas

None.

Exceptions

ORDImageExceptions.NULL_DESTINATION

This exception is raised when the destination image is NULL.

ORDImageExceptions.NULL_LOCAL_DATA

This exception is raised when the imageBfile parameter is NULL.

Examples

Flip an image from top to bottom:

DECLARE
   source_image BFILE:=BFILENAME('IMAGEDIR','testimg.jpg');
   dest_image BLOB;
BEGIN
   SELECT img INTO dest_image FROM timg WHERE N=2402 FOR UPDATE;
   
   -- flip image
   ORDSYS.ORD_IMAGE.flip(source_image, dest_image);

   UPDATE timg SET img=dest_image WHERE N=2402;
   COMMIT;

EXCEPTION
   WHEN OTHERS THEN
        RAISE;
END;
/

5.14 ORD_IMAGE PL/SQL Package: flip( ) for BLOBs

Format

flip(imageBlob IN BLOB, 
     dest      IN OUT NOCOPY BLOB);

Description

Places the scanlines of an image in inverse order, swapped top to bottom, and writes the resulting image into the destination BLOB.

Parameters

imageBlob

The source image data represented as a BLOB.

dest

The destination of the new image.

Usage Notes

Because temporary LOBs do not have read consistency, you cannot use the same temporary LOB for both the imageBlob and dest parameters.

Pragmas

None.

Exceptions

ORDImageExceptions.DATA_NOT_LOCAL

This exception is raised when the imageBlob parameter is NULL.

Examples

Flip an image from top to bottom:

DECLARE
   source_image BLOB;
   dest_image BLOB;
BEGIN
   SELECT img INTO source_image FROM timg WHERE N=1910;
   SELECT img INTO dest_image FROM timg WHERE N=2402 FOR UPDATE;
   
   -- flip image
   ORDSYS.ORD_IMAGE.flip(source_image, dest_image);

   UPDATE timg SET img=dest_image WHERE N=2402;
   COMMIT;

EXCEPTION
   WHEN OTHERS THEN
        RAISE;
END;
/

5.15 ORD_IMAGE PL/SQL Package: flip( ) in place

Format

flip(imageBlob IN OUT NOCOPY BLOB);

Description

Places the scanlines of an image in inverse order, swapped top to bottom, writing the image back onto itself.

Parameters

imageBlob

The image data represented as a BLOB.

Usage Notes

None.

Pragmas

None.

Exceptions

ORDImageExceptions.DATA_NOT_LOCAL

This exception is raised when the imageBlob parameter is NULL.

Examples

Flip an image from top to bottom:

DECLARE
   image BLOB;
BEGIN
   SELECT img INTO image FROM timg WHERE N=2402 FOR UPDATE;
   
   -- flip image
   ORDSYS.ORD_IMAGE.flip(image);

   UPDATE timg SET img = image WHERE N=2402;
   COMMIT;

EXCEPTION
   WHEN OTHERS THEN
        RAISE;
END;
/

5.16 ORD_IMAGE PL/SQL Package: getProperties( ) for BFILEs

Format

getProperties(imageBfile IN OUT NOCOPY BFILE, 
              attributes IN OUT NOCOPY CLOB);

Description

Reads the image data stored in a BFILE to get the values of the media attributes for supported formats, and then stores them in the input CLOB. This procedure 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 extracted by the getProperties( ) procedure. 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);

   -- get properties from bfile
   ORDSYS.ORD_IMAGE.getProperties(data, img_attrib);

   -- print length of extracted properties
   DBMS_OUTPUT.PUT_LINE('Size of XML Annotations ' || 
        TO_CHAR(DBMS_LOB.GETLENGTH(img_attrib)));

EXCEPTION
   WHEN OTHERS THEN
        RAISE;
END;
/

5.17 ORD_IMAGE PL/SQL Package: getProperties( ) (all attributes) for BFILEs

Format

getProperties(imageBfile        IN OUT NOCOPY BFILE, 
              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 data stored in a BFILE to get the values of the media attributes for supported formats, and then returns them as explicit parameters. This procedure extracts the properties for these attributes of the image data: MIME type, width, height, file format, content format, compression format, and content length.

Parameters

imageBfile

The image data represented as a BFILE.

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

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

ORDSourceExceptions.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');
   mimeType VARCHAR2(80);
   width NUMBER;
   height NUMBER;
   fileFormat VARCHAR2(32):=NULL;
   contentFormat VARCHAR2(4000);
   compressionFormat VARCHAR2(4000);
   contentLength NUMBER;
BEGIN
 
   -- get properties from bfile
   ORDSYS.ORD_IMAGE.getProperties(img_data,
         mimeType, width, height, fileFormat,
         contentFormat, compressionFormat, contentLength);

   -- print properties
   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;
/

5.18 ORD_IMAGE PL/SQL Package: getProperties( ) for BLOBs

Format

getProperties(imageBlob  IN BLOB, 
              attributes IN OUT NOCOPY CLOB);

Description

Reads the image data stored in a BLOB to get the values of the media attributes for supported formats, and then stores them in the input CLOB. This procedure 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 extracted by the getProperties( ) procedure. 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;

   -- get properties from blob
   ORDSYS.ORD_IMAGE.getProperties(img_data, img_attrib);

   -- print length of extracted properties
   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;
/

5.19 ORD_IMAGE PL/SQL Package: getProperties( ) (all attributes) for BLOBs

Format

getProperties(imageBlob         IN BLOB, 
              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 data stored in a BLOB to get the values of the media attributes for supported formats, and then returns them as explicit parameters. This procedure extracts the properties for these attributes of the image data: MIME type, width, height, file format, content format, compression format, and content length.

Parameters

imageBlob

The image data represented as a BLOB.

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

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;
   mimeType VARCHAR2(4000);
   width NUMBER;
   height NUMBER;
   fileFormat VARCHAR2(32):=NULL;
   contentFormat VARCHAR2(4000);
   compressionFormat VARCHAR2(4000);
   contentLength NUMBER;
BEGIN
   SELECT img, mimetype, width, height, fileformat, contentformat,
            compressionformat, contentlength 
       INTO img_data, mimeType, width, height, fileFormat,
            contentFormat, compressionFormat, contentLength
       FROM timg WHERE N=1 FOR UPDATE;
  
   -- get properties from blob
   ORDSYS.ORD_IMAGE.getProperties(img_data,
       mimeType, width, height, fileFormat,
       contentFormat, compressionFormat, contentLength);

   -- print properties
   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, mimetype=mimeType, width=width,
         height=height, fileformat=fileFormat, contentformat=contentFormat,
         compressionformat=compressionFormat, contentlength=contentLength
       WHERE N=1;
   COMMIT;

EXCEPTION
   WHEN OTHERS THEN
        RAISE;
END;
/

5.20 ORD_IMAGE PL/SQL Package: grayscale( ) for BFILEs

Format

grayscale(imageBfile IN OUT NOCOPY BFILE, 
          dest       IN OUT NOCOPY BLOB);

Description

Converts an image to an 8-bit grayscale image, and writes the resulting image into the destination BLOB.

Parameters

imageBfile

The source image data represented as a BFILE.

dest

The destination of the new image.

Usage Notes

None.

Pragmas

None.

Exceptions

ORDImageExceptions.NULL_DESTINATION

This exception is raised when the destination image is NULL.

ORDImageExceptions.NULL_LOCAL_DATA

This exception is raised when the imageBfile parameter is NULL.

Examples

Convert a source image into a grayscale image:

DECLARE
   source_image BFILE:=BFILENAME('IMAGEDIR','testimg.jpg');
   dest_image BLOB;
BEGIN
   SELECT img INTO dest_image FROM timg WHERE N = 2402 FOR UPDATE;
   
   -- convert source image into a grayscale image
   ORDSYS.ORD_IMAGE.grayscale(source_image, dest_image);

   UPDATE timg SET img=dest_image WHERE N=2402;
   COMMIT;

EXCEPTION
   WHEN OTHERS THEN
        RAISE;
END;
/

5.21 ORD_IMAGE PL/SQL Package: grayscale( ) for BLOBs

Format

grayscale(imageBlob IN BLOB, 
          dest      IN OUT NOCOPY BLOB);

Description

Converts an image to an 8-bit grayscale image, and writes the resulting image into the destination BLOB.

Parameters

imageBlob

The source image data represented as a BLOB.

dest

The destination of the new image.

Usage Notes

Because temporary LOBs do not have read consistency, you cannot use the same temporary LOB for both the imageBlob and dest parameters.

Pragmas

None.

Exceptions

ORDImageExceptions.DATA_NOT_LOCAL

This exception is raised when the imageBlob parameter is NULL.

Examples

Convert a source image into a grayscale image:

DECLARE
   source_image BLOB;
   dest_image BLOB;
BEGIN
   SELECT img INTO source_image FROM timg WHERE N=1910;
   SELECT img INTO dest_image FROM timg WHERE N=2402 FOR UPDATE;
   
   -- convert source image into a grayscale image
   ORDSYS.ORD_IMAGE.grayscale(source_image, dest_image);

   UPDATE timg SET img=dest_image WHERE N=2402;
   COMMIT;

EXCEPTION
   WHEN OTHERS THEN
        RAISE;
END;
/

5.22 ORD_IMAGE PL/SQL Package: grayscale( ) in place

Format

grayscale(imageBlob IN OUT NOCOPY BLOB);

Description

Converts an image to an 8-bit grayscale image, writing the image back onto itself.

Parameters

imageBlob

The image data represented as a BLOB.

Usage Notes

None.

Pragmas

None.

Exceptions

ORDImageExceptions.DATA_NOT_LOCAL

This exception is raised when the imageBlob parameter is NULL.

Examples

Convert an image into a grayscale image:

DECLARE
   image BLOB;
BEGIN
   SELECT img INTO image FROM timg WHERE N=2402 FOR UPDATE;
   
   -- convert into a grayscale image
   ORDSYS.ORD_IMAGE.grayscale(image);

   UPDATE timg SET img=image WHERE N=2402;
   COMMIT;

EXCEPTION
   WHEN OTHERS THEN
        RAISE;
END;
/

5.23 ORD_IMAGE PL/SQL Package: mirror( ) for BFILEs

Format

mirror(imageBfile IN OUT NOCOPY BFILE, 
       dest       IN OUT NOCOPY BLOB);

Description

Places the columns of an image in reverse order, swapped left to right, and writes the resulting image into the destination BLOB. The original source image is not modified.

Parameters

imageBfile

The source image data represented as a BFILE.

dest

The destination of the new image.

Usage Notes

None.

Pragmas

None.

Exceptions

ORDImageExceptions.NULL_DESTINATION

This exception is raised when the destination image is NULL.

ORDImageExceptions.NULL_LOCAL_DATA

This exception is raised when the imageBfile parameter is NULL.

Examples

Create a mirrored image from left to right:

DECLARE
    source_image BFILE := BFILENAME('IMAGEDIR','testimg.jpg');
    dest_image BLOB;
BEGIN
    SELECT img INTO dest_image FROM timg WHERE N=2402 FOR UPDATE;
   
    -- mirror image
    ORDSYS.ORD_IMAGE.mirror(source_image, dest_image);

    UPDATE timg SET img=dest_image WHERE N=2402;
    COMMIT;

EXCEPTION
    WHEN OTHERS THEN
        RAISE;
END;
/

5.24 ORD_IMAGE PL/SQL Package: mirror( ) for BLOBs

Format

mirror(imageBlob IN BLOB, 
       dest      IN OUT NOCOPY BLOB);

Description

Places the columns of an image in reverse order, swapped left to right, and writes the resulting image into the destination BLOB. The original source image is not modified.

Parameters

imageBlob

The source image data represented as a BLOB.

dest

The destination of the new image.

Usage Notes

Because temporary LOBs do not have read consistency, you cannot use the same temporary LOB for both the imageBlob and dest parameters.

Pragmas

None.

Exceptions

ORDImageExceptions.DATA_NOT_LOCAL

This exception is raised when the imageBlob parameter is NULL.

Examples

Create a mirrored image from left to right:

DECLARE
    source_image BLOB;
    dest_image BLOB;
BEGIN
    SELECT img INTO source_image FROM timg WHERE N=1910;
    SELECT img INTO dest_image FROM timg WHERE N=2402 FOR UPDATE;
   
    -- mirror image
    ORDSYS.ORD_IMAGE.mirror(source_image, dest_image);

    UPDATE timg SET img=dest_image WHERE N=2402;
    COMMIT;

EXCEPTION
    WHEN OTHERS THEN
        RAISE;
END;
/

5.25 ORD_IMAGE PL/SQL Package: mirror( ) in place

Format

mirror(imageBlob IN OUT NOCOPY BLOB);

Description

Places the columns of an image in reverse order, swapped left to right, writing the image back onto itself.

Parameters

imageBlob

The image data represented as a BLOB.

Usage Notes

None.

Pragmas

None.

Exceptions

ORDImageExceptions.DATA_NOT_LOCAL

This exception is raised when the imageBlob parameter is NULL.

Examples

Create a mirrored image from left to right:

DECLARE
    image BLOB;
BEGIN
    SELECT img INTO image FROM timg WHERE N=2402 FOR UPDATE;
   
    -- mirror image
    ORDSYS.ORD_IMAGE.mirror(image);

    UPDATE timg SET img=image WHERE N=2402;
    COMMIT;

EXCEPTION
    WHEN OTHERS THEN
        RAISE;
END;
/

5.26 ORD_IMAGE PL/SQL Package: page( ) for BFILEs

Format

page(imageBfile IN OUT NOCOPY BFILE, 
     pageNumber IN INTEGER, 
     dest       IN OUT NOCOPY BLOB);

Description

Selects a page from a multipage file, and writes the resulting image into the destination BLOB. The original source image is not modified. This procedure is for use with TIFF images only. Page 0 is the first page.

Parameters

imageBfile

The source image data represented as a BFILE.

pageNumber

A nonnegative integer representing the page number to be selected. 0 (zero) represents the first page.

dest

The destination of the new image.

Usage Notes

None.

Pragmas

None.

Exceptions

ORDImageExceptions.NULL_DESTINATION

This exception is raised when the destination image is NULL.

ORDImageExceptions.NULL_LOCAL_DATA

This exception is raised when the imageBfile parameter is NULL.

Examples

Select a page from a multipage TIFF file and write the selected page as output:

DECLARE
    source_image BFILE := BFILENAME('IMAGEDIR','testimg.tif');
    dest_image BLOB;
BEGIN
    SELECT img INTO dest_image FROM timg WHERE N=1910 FOR UPDATE;

    -- page selection from a multipage TIFF input image
    ORDSYS.ORD_IMAGE.page(source_image, 0, dest_image);

    UPDATE timg SET img=dest_image WHERE N=1910;
    COMMIT;

EXCEPTION
    WHEN OTHERS THEN
        RAISE;
END;
/

5.27 ORD_IMAGE PL/SQL Package: page( ) for BLOBs

Format

page(imageBlob  IN BLOB, 
     pageNumber IN INTEGER, 
     dest       IN OUT NOCOPY BLOB);

Description

Selects a page from a multipage file, and writes the resulting image into the destination BLOB. The original source image is not modified. This procedure is for use with TIFF images only. Page 0 is the first page.

Parameters

imageBlob

The source image data represented as a BLOB.

pageNumber

A nonnegative integer representing the page number to be selected. 0 (zero) represents the first page.

dest

The destination of the new image.

Usage Notes

Because temporary LOBs do not have read consistency, you cannot use the same temporary LOB for both the imageBlob and dest parameters.

Pragmas

None.

Exceptions

ORDImageExceptions.DATA_NOT_LOCAL

This exception is raised when the imageBlob parameter is NULL.

Examples

Select a page from a multipage TIFF file and write the selected page as output:

DECLARE
    source_image BLOB;
    dest_image BLOB;
BEGIN
    --select the source image and select for update the destination image
    SELECT img INTO source_image FROM timg WHERE N=1910;
    SELECT img INTO dest_image FROM timg WHERE N=2402 FOR UPDATE;
       
    -- page selection from a multipage TIFF input image
    ORDSYS.ORD_IMAGE.page(source_image, 0, dest_image);

    UPDATE timg SET img=dest_image WHERE N=2402;
    COMMIT;

EXCEPTION
    WHEN OTHERS THEN
        RAISE;
END;
/

5.28 ORD_IMAGE PL/SQL Package: page( ) in place

Format

page(imageBlob  IN OUT NOCOPY BLOB, 
     pageNumber IN INTEGER);

Description

Selects a page from a multipage file, writing the image back onto itself. This procedure is for use with TIFF images only. Page 0 is the first page.

Parameters

imageBlob

The image data represented as a BLOB.

pageNumber

A nonnegative integer representing the page number to be selected. 0 (zero) represents the first page.

Usage Notes

None.

Pragmas

None.

Exceptions

ORDImageExceptions.DATA_NOT_LOCAL

This exception is raised when the imageBlob parameter is NULL.

Examples

Select a page from a multipage TIFF file and write the selected page as output:

DECLARE
    image BLOB;
BEGIN
    -- select the source image for update
    SELECT img INTO image FROM timg WHERE N=1910 FOR UPDATE;
   
    -- page selection from a multipage TIFF input image
    ORDSYS.ORD_IMAGE.page(image, 0);

    UPDATE timg SET img=image WHERE N=1910;
    COMMIT;

EXCEPTION
    WHEN OTHERS THEN
        RAISE;
END;
/

5.29 ORD_IMAGE PL/SQL Package: 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 image attributes.

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

See process( ) for lists and descriptions of all the image processing operators.

See Oracle Multimedia Image Processing for more information about process( ) operators.

Pragmas

None.

Exceptions

ORDImageExceptions.DATA_NOT_LOCAL

This exception is raised when the imageBlob parameter is NULL.

Examples

Convert the source image to a compressed JFIF image, with a maximum size of 32 x 32 pixels:

DECLARE
    img_attrib CLOB;
    image_data BLOB;
BEGIN
    SELECT img, attributes INTO image_data, img_attrib FROM timg 
        WHERE N=1 FOR UPDATE;

    -- Process the image by converting it to a maximum 32x32 image 
    -- of format JFIF with maximum compression   
    ORDSYS.ORD_IMAGE.process(image_data, 'fileFormat=JFIF, 
        compressionQuality=MAXCOMPRATIO,maxScale=32 32');
   
    -- get properties of processed image
    ORDSYS.ORD_IMAGE.getProperties(image_data, img_attrib);

    UPDATE timg SET img=image_data, attributes=img_attrib WHERE N=1;
    COMMIT;

EXCEPTION
    WHEN OTHERS THEN
        RAISE;
END;
/

5.30 ORD_IMAGE PL/SQL Package: processCopy( ) for BFILEs

Format

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

Description

Creates a derivative image from a source image stored in a BFILE by performing one or more image processing operations on the source image and writing the resulting image into the destination BLOB. The original source image is not modified.

Parameters

imageBfile

The source image data represented as a BFILE.

command

A list of image processing operations to perform on the image in order to create a new derivative image to be stored in the dest BLOB.

dest

The destination of the new image.

Usage Notes

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

Calling this procedure changes one or more image attributes. Therefore, if you are storing image attributes, call the ORD_IMAGE getProperties( ) procedure on the destination image after calling the ORD_IMAGE processCopy( ) procedure.

See process( ) for lists and descriptions of all the image processing operators.

See Oracle Multimedia Image Processing for more information about processCopy( ) operators.

Pragmas

None.

Exceptions

ORDImageExceptions.NULL_DESTINATION

This exception is raised when the destination image is NULL.

ORDImageExceptions.NULL_LOCAL_DATA

This exception is raised when the imageBfile parameter is NULL.

Examples

Convert the source image to a compressed JFIF image, with a maximum size of 32 x 32 pixels:

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

    -- Process the image by converting it to a maximum 32x32 image 
    -- of format JFIF with maximum compression 
    Command := 'fileFormat=JFIF, compressionQuality=MAXCOMPRATIO,maxScale=32 32';

    -- process with a pre-defined command
    ORDSYS.ORD_IMAGE.processCopy(image_data, Command, destination_data);

    -- get properties of processed image
    ORDSYS.ORD_IMAGE.getProperties(destination_data, dest_attrib);

    UPDATE timg SET img=destination_data, attributes=dest_attrib WHERE N=2;
    COMMIT;

EXCEPTION
    WHEN OTHERS THEN
        RAISE;
END;
/

5.31 ORD_IMAGE PL/SQL Package: processCopy( ) for BLOBs

Format

processCopy(imageBlob IN BLOB, 
            command   IN VARCHAR2, 
            dest      IN OUT NOCOPY BLOB);

Description

Creates a derivative image from a source image stored in a BLOB by performing one or more image processing operations on the source image and writing the resulting image into the destination BLOB. The original source image is not modified.

Parameters

imageBlob

The source image data represented as a BLOB.

command

A list of image processing operations to perform on the image in order to create a new derivative image to be stored in the dest BLOB.

dest

The destination of the new image.

Usage Notes

Because temporary LOBs do not have read consistency, you cannot use the same temporary LOB for both the imageBlob and dest parameters.

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

Calling this procedure changes one or more image attributes. Therefore, if you are storing image attributes, call the ORD_IMAGE getProperties( ) procedure on the destination image after calling the ORD_IMAGE processCopy( ) procedure.

See process( ) for lists and descriptions of all the image processing operators.

See Oracle Multimedia Image Processing for more information about processCopy( ) operators.

Pragmas

None.

Exceptions

ORDImageExceptions.DATA_NOT_LOCAL

This exception is raised when the imageBlob parameter is NULL.

Examples

Convert the source image to a compressed JFIF image, with a maximum size of 32 x 32 pixels:

DECLARE
    dest_attrib CLOB;
    image_data BLOB;
    destination_data BLOB;
    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;

    -- Process the image by converting it to a maximum 32x32 image 
    -- of format JFIF with maximum compression       
    Command := 'fileFormat=JFIF, compressionQuality=MAXCOMPRATIO,maxScale=32 32';

    -- process with pre-defined command
    ORDSYS.ORD_IMAGE.processCopy(image_data, Command, destination_data);

    -- get properties of processed image
    ORDSYS.ORD_IMAGE.getProperties(destination_data, dest_attrib);
   
    UPDATE timg SET img=destination_data, attributes=dest_attrib WHERE N=2;
    COMMIT;

EXCEPTION
   WHEN OTHERS THEN
        RAISE;
END;
/

5.32 ORD_IMAGE PL/SQL Package: putMetadata( ) for BFILEs

Format

putMetadata(imageBfile   IN BFILE, 
            dest         IN OUT NOCOPY BLOB, 
            xmlData      IN SYS.XMLType, 
            metadataType IN VARCHAR2 DEFAULT ‘XMP’, 
            encoding     IN VARCHAR2 DEFAULT ‘UTF-8’);

Description

Accepts a BFILE containing an image and a schema-valid XML document, and creates a binary packet suitable for embedding in the target image file format. The packet is encoded according to the value of the encoding parameter. If the value of the metadataType parameter is XMP, this procedure writes a new XMP packet to the image, replacing any existing XMP packets. The new image file with embedded metadata is returned in the dest parameter. The original image is not changed.

Parameters

imageBfile

The source image data represented as a BFILE.

dest

The BLOB to receive the image containing the embedded metadata.

xmlData

The XMLtype that contains a schema-valid XML document for the indicated metadataType. If the value of the metadataType parameter is XMP, the root element should contain a well-formed RDF document.

metadataType

A string that specifies the type of metadata to write. The valid value is XMP; it is also the default.

encoding

The character encoding to be used in the image file. Valid values are: UTF-8, UTF-16, UTF-16BE, and UTF-16LE. The default is UTF-8.

Usage Notes

The binary metadata packet generated from the same xmlData input may have different sizes for different encodings. Different image file formats support different encodings, and may restrict the binary metadata packet size. The restrictions of the supported image formats are as follows:

  • GIF89a supports UTF-8 encoding only.

  • JPEG requires a binary packet size of less than 65502 bytes.

  • TIFF requires a binary packet size of less than 4 gigabytes.

See Also:

Oracle Multimedia User's Guide for more information about the metadata feature

Pragmas

None.

Exceptions

ORDImageExceptions.NULL_CONTENT

This exception is raised when the imageBfile parameter is NULL.

ORDImageExceptions.NULL_DESTINATION

This exception is raised when the destination image BLOB is NULL.

Examples

Insert a new image into the table timg. The new image is a copy of the image testimg.dat from the IMAGEDIR directory object, with updated XMP metadata: 

DECLARE
    dest_attrib CLOB;
    destination_data BLOB;
    image_data BFILE:=BFILENAME('IMAGEDIR','testimg.dat');
    xmlData XMLType;
BEGIN
    SELECT img INTO destination_data FROM timg WHERE N=2402 FOR UPDATE;
 
    xmlData:=xmltype(
         '<xmpMetadata xmlns="http://xmlns.oracle.com/ord/meta/xmp">' ||
         '<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"' ||
         ' xmlns:dc="http://purl.org/dc/elements/1.1/">' ||
         '<rdf:Description>' ||
         ' <dc:rights>' ||
         ' <rdf:Alt>' ||
         ' <rdf:li xml:lang="en-us">' ||
         ' Oracle Corporation' ||
         ' </rdf:li>' ||
         ' </rdf:Alt>'||
         '</dc:rights>' ||
         '</rdf:Description>' ||
         '</rdf:RDF>' ||
         '</xmpMetadata>', 'http://xmlns.oracle.com/ord/meta/xmp'); 
 
    -- add metadata to the destination image
    ORDSYS.ORD_IMAGE.putMetadata(image_data, destination_data, 
                                 xmlData, 'xmp', 'utf-8');

    -- get properties of the updated image
    ORDSYS.ORD_IMAGE.getProperties(destination_data, dest_attrib);

    UPDATE timg SET img=destination_data, attributes=dest_attrib 
        WHERE N=2402;
    COMMIT;

EXCEPTION
    WHEN OTHERS THEN
        RAISE;
END;
/

5.33 ORD_IMAGE PL/SQL Package: putMetadata( ) for BLOBs

Format

putMetadata(imageBlob    IN BLOB, 
            dest         IN OUT NOCOPY BLOB, 
            xmlData      IN SYS.XMLType, 
            metadataType IN VARCHAR2 DEFAULT ‘XMP’, 
            encoding     IN VARCHAR2 DEFAULT ‘UTF-8’);

Description

Accepts a BLOB containing an image and a schema-valid XML document, and creates a binary packet suitable for embedding in the target image file format. The packet is encoded according to the value of the encoding parameter. If the value of the metadataType parameter is XMP, this procedure writes a new XMP packet to the image, replacing any existing XMP packets. The new image file with embedded metadata is returned in the dest parameter. The original image is not changed.

Parameters

imageBlob

The source image data represented as a BLOB.

dest

The BLOB to receive the image containing the embedded metadata.

xmlData

The XMLtype that contains a schema-valid XML document for the indicated metadataType. If the value of the metadataType parameter is XMP, the root element should contain a well-formed RDF document.

metadataType

A string that specifies the type of metadata to write. The valid value is XMP; it is also the default.

encoding

The character encoding to be used in the image file. Valid values are: UTF-8, UTF-16, UTF-16BE, and UTF-16LE. The default is UTF-8.

Usage Notes

Because temporary LOBs do not have read consistency, you cannot use one temporary LOB for both the imageBlob and dest parameters.

The binary metadata packet generated from the same xmlData input may have different sizes for different encodings. Different image file formats support different encodings, and may restrict the binary metadata packet size. The restrictions of the supported image formats are as follows:

  • GIF89a supports UTF-8 encoding only.

  • JPEG requires a binary packet size of less than 65502 bytes.

  • TIFF requires a binary packet size of less than 4 gigabytes.

See Also:

Oracle Multimedia User's Guide for more information about the metadata feature

Pragmas

None.

Exceptions

ORDImageExceptions.NULL_CONTENT

This exception is raised when the imageBlob parameter is NULL.

ORDImageExceptions.NULL_DESTINATION

This exception is raised when the destination image is NULL.

Examples

Insert a new image in the table timg with updated XMP metadata: 

DECLARE
    dest_attrib CLOB;
    source_image BLOB;
    dest_image BLOB;
    xmlData XMLType;
BEGIN
    SELECT img INTO source_image FROM timg WHERE N=1910;
    SELECT img INTO dest_image FROM timg WHERE N=2402 FOR UPDATE;

    xmlData:=xmltype(
         '<xmpMetadata xmlns="http://xmlns.oracle.com/ord/meta/xmp">' ||
         '<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"' ||
         ' xmlns:dc="http://purl.org/dc/elements/1.1/">' ||
         '<rdf:Description>' ||
         ' <dc:rights>' ||
         ' <rdf:Alt>' ||
         ' <rdf:li xml:lang="en-us">' ||
         ' Oracle Corporation' ||
         ' </rdf:li>' ||
         ' </rdf:Alt>'||
         '</dc:rights>' ||
         '</rdf:Description>' ||
         '</rdf:RDF>' ||
         '</xmpMetadata>', 'http://xmlns.oracle.com/ord/meta/xmp'); 
 
    -- add metadata to the destination image 
    ORDSYS.ORD_IMAGE.putMetadata(source_image, dest_image, 
                                 xmlData, 'xmp', 'utf-8');

    -- get properties of updated image
    ORDSYS.ORD_IMAGE.getProperties(dest_image, dest_attrib);

    UPDATE timg SET img=dest_image, attributes=dest_attrib WHERE N=2402;
    COMMIT;

EXCEPTION
    WHEN OTHERS THEN
        RAISE;
END;
/

5.34 ORD_IMAGE PL/SQL Package: rotate( ) for BFILEs

Format

rotate(imageBfile IN OUT NOCOPY BFILE, 
       angle      IN FLOAT, 
       dest       IN OUT NOCOPY BLOB);

Description

Rotates an image within the image plane by the angle specified, and writes the resulting image into the destination BLOB.

Parameters

imageBfile

The source image data represented as a BFILE.

angle

The angle within the image plane by which to rotate the image. A positive value specifies a clockwise rotation. A negative value specifies a counter-clockwise rotation.

dest

The destination of the new image.

Usage Notes

None.

Pragmas

None.

Exceptions

ORDImageExceptions.NULL_DESTINATION

This exception is raised when the destination image is NULL.

ORDImageExceptions.NULL_LOCAL_DATA

This exception is raised when the imageBfile parameter is NULL.

Examples

Rotate an image by 45 degrees:

DECLARE
    source_image BFILE:=BFILENAME('IMAGEDIR','testimg.jpg');
    dest_image BLOB;
BEGIN
    SELECT img INTO dest_image FROM timg WHERE N=2402 FOR UPDATE;
   
    -- rotate image
    ORDSYS.ORD_IMAGE.rotate(source_image, 45, dest_image);

    UPDATE timg SET img=dest_image WHERE N=2402;
    COMMIT;

EXCEPTION
    WHEN OTHERS THEN
        RAISE;
END;
/

5.35 ORD_IMAGE PL/SQL Package: rotate( ) for BLOBs

Format

rotate(imageBlob IN OUT NOCOPY BFILE, 
       angle     IN FLOAT, 
       dest      IN OUT NOCOPY BLOB);

Description

Rotates an image within the image plane by the angle specified, and writes the resulting image into the destination BLOB.

Parameters

imageBlob

The source image data represented as a BLOB.

angle

The angle within the image plane by which to rotate the image. A positive value specifies a clockwise rotation. A negative value specifies a counter-clockwise rotation.

dest

The destination of the new image.

Usage Notes

Because temporary LOBs do not have read consistency, you cannot use the same temporary LOB for both the imageBlob and dest parameters.

Pragmas

None.

Exceptions

ORDImageExceptions.DATA_NOT_LOCAL

This exception is raised when the imageBlob parameter is NULL.

Examples

Rotate an image by 45 degrees:

DECLARE
    source_image BLOB;
    dest_image BLOB;
BEGIN
    SELECT img INTO source_image FROM timg WHERE N=1910;
    SELECT img INTO dest_image FROM timg WHERE N=2402 FOR UPDATE;
   
    -- rotate image
    ORDSYS.ORD_IMAGE.rotate(source_image, 45, dest_image);

    UPDATE timg SET img=dest_image WHERE N=2402;
    COMMIT;

EXCEPTION
    WHEN OTHERS THEN
        RAISE;
END;
/

5.36 ORD_IMAGE PL/SQL Package: rotate( ) in place

Format

rotate(imageBlob IN OUT NOCOPY BLOB, 
       angle     IN FLOAT);

Description

Rotates an image within the image plane by the angle specified, writing the image back onto itself.

Parameters

imageBlob

The image data represented as a BLOB.

angle

The angle within the image plane by which to rotate the image. A positive value specifies a clockwise rotation. A negative value specifies a counter-clockwise rotation.

Usage Notes

None.

Pragmas

None.

Exceptions

ORDImageExceptions.DATA_NOT_LOCAL

This exception is raised when the imageBlob parameter is NULL.

Examples

Rotate an image by 45 degrees:

DECLARE
    image BLOB;
BEGIN
    SELECT img INTO image FROM timg WHERE N=2402 FOR UPDATE;
   
    -- rotate image
    ORDSYS.ORD_IMAGE.rotate(image,45);

    UPDATE timg SET img=image WHERE N=2402;
    COMMIT;

EXCEPTION
    WHEN OTHERS THEN
        RAISE;
END;
/

5.37 ORD_IMAGE PL/SQL Package: scale( ) for BFILEs

Format

scale(imageBfile IN OUT NOCOPY BFILE, 
      width      IN INTEGER, 
      height     IN INTEGER, 
      dest       IN OUT NOCOPY BLOB);

Description

Scales the image in imageBfile to a specified size in pixels (width, height), while maintaining the aspect ratio, and writes the resulting image into the destination BLOB. The original source image is not modified.

Parameters

imageBfile

The source image data represented as a BFILE.

width

The maximum width of the resulting image in pixels.

height

The maximum height of the resulting image in pixels.

dest

The destination of the new image.

Usage Notes

None.

Pragmas

None.

Exceptions

ORDImageExceptions.NULL_DESTINATION

This exception is raised when the destination image is NULL.

ORDImageExceptions.NULL_LOCAL_DATA

This exception is raised when the imageBfile parameter is NULL.

Examples

Scale an image by specific dimensions:

DECLARE
    source_image BFILE := BFILENAME('IMAGEDIR','testimg.jpg');
    dest_image BLOB;
BEGIN
    SELECT img INTO dest_image FROM timg WHERE N=2402 FOR UPDATE;
   
    -- scale image with specific width and height values
    ORDSYS.ORD_IMAGE.scale(source_image, 20, 20, dest_image);

    UPDATE timg SET img=dest_image WHERE N=2402;
    COMMIT;

EXCEPTION
    WHEN OTHERS THEN
        RAISE;
END;
/

5.38 ORD_IMAGE PL/SQL Package: scale( ) for BLOBs

Format

scale(imageBlob IN BLOB, 
      width     IN INTEGER, 
      height    IN INTEGER, 
      dest      IN OUT NOCOPY BLOB);

Description

Scales the image in imageBlob to a specified size in pixels (width, height), while maintaining the aspect ratio, and writes the resulting image into the destination BLOB. The original source image is not modified.

Parameters

imageBlob

The source image data represented as a BLOB.

width

The maximum width of the resulting image in pixels.

height

The maximum height of the resulting image in pixels.

dest

The destination of the new image.

Usage Notes

Because temporary LOBs do not have read consistency, you cannot use the same temporary LOB for both the imageBlob and dest parameters.

Pragmas

None.

Exceptions

ORDImageExceptions.DATA_NOT_LOCAL

This exception is raised when the imageBlob parameter is NULL.

Examples

Scale an image by specific dimensions:

DECLARE
    source_image BLOB;
    dest_image BLOB;
BEGIN
    SELECT img INTO source_image FROM timg WHERE N=1910;
    SELECT img INTO dest_image FROM timg WHERE N=2402 FOR UPDATE;
   
    -- scale image with specific width and height values
    ORDSYS.ORD_IMAGE.scale(source_image, 20, 20, dest_image);

    UPDATE timg SET img=dest_image WHERE N=2402;
    COMMIT;

EXCEPTION
    WHEN OTHERS THEN
        RAISE;
END;
/

5.39 ORD_IMAGE PL/SQL Package: scale( ) in place

Format

scale(imageBlob IN OUT NOCOPY BLOB, 
      width     IN INTEGER, 
      height    IN INTEGER);

Description

Scales the image in imageBlob to a specified size in pixels (width, height), while maintaining the aspect ratio, and writes the image back onto itself.

Parameters

imageBlob

The image data represented as a BLOB.

width

The maximum width of the resulting image in pixels.

height

The maximum height of the resulting image in pixels.

Usage Notes

None.

Pragmas

None.

Exceptions

ORDImageExceptions.DATA_NOT_LOCAL

This exception is raised when the imageBlob parameter is NULL.

Examples

Scale an image by specific dimensions:

DECLARE
    image BLOB;
BEGIN
    SELECT img INTO image FROM timg WHERE N=2402 FOR UPDATE;
   
    -- scale image with specific width and height values
    ORDSYS.ORD_IMAGE.scale(image, 20, 20);

    UPDATE timg SET img=image WHERE N=2402;
    COMMIT;

EXCEPTION
    WHEN OTHERS THEN
        RAISE;
END;
/

5.40 ORD_IMAGE PL/SQL Package: scale( ) by Factor for BFILEs

Format

scale(imageBfile  IN OUT NOCOPY BFILE, 
      scaleFactor IN FLOAT, 
      dest        IN OUT NOCOPY BLOB);

Description

Scales the image in imageBfile by the given scale factor, and writes the resulting image into the destination BLOB while maintaining the aspect ratio. The original source image is not modified.

Parameters

imageBfile

The source image data represented as a BFILE.

scaleFactor

The factor by which to scale the image. A positive FLOAT value.

dest

The destination of the new image.

Usage Notes

None.

Pragmas

None.

Exceptions

ORDImageExceptions.NULL_DESTINATION

This exception is raised when the destination image is NULL.

ORDImageExceptions.NULL_LOCAL_DATA

This exception is raised when the imageBfile parameter is NULL.

Examples

Scale an image by a factor of 1.5:

DECLARE
    source_image BFILE := BFILENAME('IMAGEDIR','testimg.jpg');
    dest_image BLOB;
BEGIN
    SELECT img INTO dest_image FROM timg WHERE N=2402 FOR UPDATE;
   
    -- scale image with a specific factor
    ORDSYS.ORD_IMAGE.scale(source_image, 1.5, dest_image);

    UPDATE timg SET img=dest_image WHERE N=2402;
    COMMIT;

EXCEPTION
    WHEN OTHERS THEN
        RAISE;
END;
/

5.41 ORD_IMAGE PL/SQL Package: scale( ) by Factor for BLOBs

Format

scale(imageBlob   IN BLOB, 
      scaleFactor IN FLOAT, 
      dest        IN OUT NOCOPY BLOB);

Description

Scales the image in imageBlob by the given scale factor, and writes the resulting image into the destination BLOB while maintaining the aspect ratio. The original source image is not modified.

Parameters

imageBlob

The source image data represented as a BLOB.

scaleFactor

The factor by which to scale the image. A positive FLOAT value.

dest

The destination of the new image.

Usage Notes

Because temporary LOBs do not have read consistency, you cannot use the same temporary LOB for both the imageBlob and dest parameters.

Pragmas

None.

Exceptions

ORDImageExceptions.DATA_NOT_LOCAL

This exception is raised when the imageBlob parameter is NULL.

Examples

Scale an image by a factor of 1.5:

DECLARE
    source_image BLOB;
    dest_image BLOB;
BEGIN
    SELECT img INTO source_image FROM timg WHERE N=1910;
    SELECT img INTO dest_image FROM timg WHERE N=2402 FOR UPDATE;
   
    -- scale image with a specific factor
    ORDSYS.ORD_IMAGE.scale(source_image, 1.5, dest_image);

    UPDATE timg SET img=dest_image WHERE N=2402;
    COMMIT;

EXCEPTION
    WHEN OTHERS THEN
        RAISE;
END;
/

5.42 ORD_IMAGE PL/SQL Package: scale( ) by Factor in place

Format

scale(imageBlob   IN OUT NOCOPY BLOB, 
      scaleFactor IN FLOAT);

Description

Scales the image in imageBlob by the given scale factor, writing the image back onto itself while maintaining the aspect ratio.

Parameters

imageBlob

The image data represented as a BLOB.

scaleFactor

The factor by which to scale the image. A positive FLOAT value.

Usage Notes

None.

Pragmas

None.

Exceptions

ORDImageExceptions.DATA_NOT_LOCAL

This exception is raised when the imageBlob parameter is NULL.

Examples

Scale an image by a factor of 1.5:

DECLARE
    image BLOB;
BEGIN
    SELECT img INTO image FROM timg WHERE N=2402 FOR UPDATE;
   
    -- scale image with a specific factor
    ORDSYS.ORD_IMAGE.scale(image, 1.5);

    UPDATE timg SET img=image WHERE N=2402;
    COMMIT;

EXCEPTION
    WHEN OTHERS THEN
        RAISE;
END;
/

5.43 ORD_IMAGE PL/SQL Package: thumbnail( ) for BFILEs

Format

thumbnail(imageBfile IN OUT NOCOPY BFILE, 
          dest       IN OUT NOCOPY BLOB);

Description

Creates a derivative image from a source image stored in a BFILE by creating an 80 x 80 pixel thumbnail image and writing the resulting image into the destination BLOB while maintaining the aspect ratio. The original source image is not modified.

Parameters

imageBfile

The source image data represented as a BFILE.

dest

The destination of the new image.

Usage Notes

None.

Pragmas

None.

Exceptions

ORDImageExceptions.NULL_DESTINATION

This exception is raised when the destination image is NULL.

ORDImageExceptions.NULL_LOCAL_DATA

This exception is raised when the imageBfile parameter is NULL.

Examples

Create an image thumbnail from a source image:

DECLARE
    source_image BFILE:=BFILENAME('IMAGEDIR','testimg.jpg');
    dest_image BLOB;
BEGIN
    SELECT img INTO dest_image FROM timg WHERE N=2402 FOR UPDATE;
   
    -- generate thumbnail image
    ORDSYS.ORD_IMAGE.thumbnail(source_image, dest_image);

    UPDATE timg SET img=dest_image WHERE N=2402;
    COMMIT;

EXCEPTION
    WHEN OTHERS THEN
        RAISE;
END;
/

5.44 ORD_IMAGE PL/SQL Package: thumbnail( ) for BLOBs

Format

thumbnail(imageBlob IN BLOB, 
          dest      IN OUT NOCOPY BLOB);

Description

Creates a derivative image from a source image stored in a BLOB by creating an 80x80 pixel thumbnail image and writing the resulting image into the destination BLOB while maintaining the aspect ratio.

Parameters

imageBlob

The source image data represented as a BLOB.

dest

The destination of the new image.

Usage Notes

Because temporary LOBs do not have read consistency, you cannot use the same temporary LOB for both the imageBlob and dest parameters.

Pragmas

None.

Exceptions

ORDImageExceptions.DATA_NOT_LOCAL

This exception is raised when the imageBlob parameter is NULL.

Examples

Create an image thumbnail from a source image:

DECLARE
    source_image BLOB;
    dest_image BLOB;
BEGIN
    SELECT img INTO source_image FROM timg WHERE N=1910;
    SELECT img INTO dest_image FROM timg WHERE N=2402 FOR UPDATE;
   
    -- generate thumbnail image
    ORDSYS.ORD_IMAGE.thumbnail(source_image, dest_image);

    UPDATE timg SET img=dest_image WHERE N=2402;
    COMMIT;

EXCEPTION
    WHEN OTHERS THEN
        RAISE;
END;
/

5.45 ORD_IMAGE PL/SQL Package: thumbnail( ) in place

Format

thumbnail(imageBlob IN OUT NOCOPY BLOB);

Description

Creates an 80 x 80 pixel thumbnail image from the image in imageBlob, writing the image back onto itself while maintaining the aspect ratio.

Parameters

imageBlob

The image data represented as a BLOB.

Usage Notes

None.

Pragmas

None.

Exceptions

ORDImageExceptions.DATA_NOT_LOCAL

This exception is raised when the imageBlob parameter is NULL.

Examples

Create an image thumbnail from a source image:

DECLARE
    image BLOB;
BEGIN
    SELECT img INTO image FROM timg WHERE N=2402 FOR UPDATE;
   
    -- generate thumbnail image
    ORDSYS.ORD_IMAGE.thumbnail(image);

    UPDATE timg SET img=image WHERE N=2402;
    COMMIT;

EXCEPTION
    WHEN OTHERS THEN
        RAISE;
END;
/