ORDImage Object Type

Oracle interMedia describes the ORDImage object type, which supports the storage, management, and manipulation of image data and the ORDImageSignature object type, which supports content-based retrieval (image matching).

This object type is defined as follows:

CREATE OR REPLACE TYPE ORDImage
AS OBJECT
(
  -------------------
  -- TYPE ATTRIBUTES
  -------------------
  source              ORDSource,
  height              INTEGER,
  width               INTEGER,
  contentLength       INTEGER,
  fileFormat          VARCHAR2(4000),
  contentFormat       VARCHAR2(4000),
  compressionFormat   VARCHAR2(4000),
  mimeType            VARCHAR2(4000),

---------------------
-- METHOD DECLARATION
---------------------
-- CONSTRUCTORS
--
STATIC FUNCTION init( ) RETURN ORDImage,
STATIC FUNCTION init(srcType     IN VARCHAR2,
                     srcLocation IN VARCHAR2,
                     srcName     IN VARCHAR2) RETURN ORDImage,

  -- Methods associated with copy operations 
  MEMBER PROCEDURE copy(dest IN OUT ORDImage),
        
  -- Methods associated with image process operations 
  MEMBER PROCEDURE process(command IN VARCHAR2),

  MEMBER PROCEDURE processCopy(command IN     VARCHAR2, 
                               dest    IN OUT ORDImage),

  -- Methods associated with image property set and check operations
  MEMBER PROCEDURE setProperties,

  MEMBER PROCEDURE setProperties(description IN VARCHAR2),

  MEMBER FUNCTION checkProperties RETURN BOOLEAN,

  -- Methods associated with image attributes accessors
  MEMBER FUNCTION getHeight RETURN INTEGER,
  PRAGMA RESTRICT_REFERENCES(getHeight, WNDS, WNPS, RNDS, RNPS), 

  MEMBER FUNCTION getWidth RETURN INTEGER,
  PRAGMA RESTRICT_REFERENCES(getWidth, WNDS, WNPS, RNDS, RNPS), 

  MEMBER FUNCTION getContentLength RETURN INTEGER,
  PRAGMA RESTRICT_REFERENCES(getContentLength, WNDS, WNPS, RNDS, RNPS), 

  MEMBER FUNCTION getFileFormat RETURN VARCHAR2,
  PRAGMA RESTRICT_REFERENCES(getFileFormat, WNDS, WNPS, RNDS, RNPS), 

  MEMBER FUNCTION getContentFormat RETURN VARCHAR2,
  PRAGMA RESTRICT_REFERENCES(getContentFormat, WNDS, WNPS, RNDS, RNPS), 

  MEMBER FUNCTION getCompressionFormat RETURN VARCHAR2,
  PRAGMA RESTRICT_REFERENCES(getCompressionFormat, WNDS, WNPS, RNDS, RNPS), 

  -- Methods associated with the local attribute
  MEMBER PROCEDURE  setLocal,
  MEMBER PROCEDURE  clearLocal,
  MEMBER FUNCTION  isLocal RETURN BOOLEAN,
  PRAGMA RESTRICT_REFERENCES(isLocal, WNDS, WNPS, RNDS, RNPS),
 
  -- Methods associated with the date attribute
  MEMBER FUNCTION  getUpdateTime RETURN DATE,
  PRAGMA RESTRICT_REFERENCES(getUpdateTime, WNDS, WNPS, RNDS, RNPS),
  MEMBER PROCEDURE setUpdateTime(current_time DATE),

  -- Methods associated with the mimeType attribute
  MEMBER FUNCTION  getMimeType RETURN VARCHAR2,
  PRAGMA RESTRICT_REFERENCES(getMimeType, WNDS, WNPS, RNDS, RNPS),
  MEMBER PROCEDURE setMimeType(mime IN VARCHAR2),

  -- Methods associated with the source attribute
MEMBER FUNCTION processSourceCommand(
                                     ctx       IN OUT RAW,
                                     cmd       IN VARCHAR2,
                                     arguments IN VARCHAR2,
                                     result    OUT RAW)
                RETURN RAW,
  MEMBER FUNCTION  getContent RETURN BLOB,
  PRAGMA RESTRICT_REFERENCES(getContent, WNDS, WNPS, RNDS, RNPS),

  MEMBER FUNCTION getBFILE RETURN BFILE,
  PRAGMA RESTRICT_REFERENCES(getBFILE, WNDS, WNPS, RNDS, RNPS),

  MEMBER PROCEDURE deleteContent,

  MEMBER PROCEDURE setSource(source_type     IN VARCHAR2,
                             source_location IN VARCHAR2,
                             source_name     IN VARCHAR2),
  MEMBER FUNCTION  getSource RETURN VARCHAR2,
  PRAGMA RESTRICT_REFERENCES(getSource, WNDS, WNPS, RNDS, RNPS),

  MEMBER FUNCTION  getSourceType RETURN VARCHAR2,
  PRAGMA RESTRICT_REFERENCES(getSourceType, WNDS, WNPS, RNDS, RNPS),

  MEMBER FUNCTION  getSourceLocation RETURN VARCHAR2,
  PRAGMA RESTRICT_REFERENCES(getSourceLocation, WNDS, WNPS, RNDS, RNPS),

  MEMBER FUNCTION  getSourceName RETURN VARCHAR2,
  PRAGMA RESTRICT_REFERENCES(getSourceName, WNDS, WNPS, RNDS, RNPS),

  MEMBER PROCEDURE import(ctx IN OUT RAW),
  MEMBER PROCEDURE importFrom(ctx         IN OUT RAW,
                          source_type     IN VARCHAR2,
                          source_location IN VARCHAR2,
                          source_name     IN VARCHAR2),
  MEMBER PROCEDURE export(ctx             IN OUT RAW,
                          source_type     IN VARCHAR2,
                          source_location IN VARCHAR2,
                          source_name     IN VARCHAR2),

-- Methods associated with file operations on the source
MEMBER FUNCTION openSource(userArg IN RAW, ctx OUT RAW) RETURN INTEGER,
MEMBER FUNCTION closeSource(ctx IN OUT RAW) RETURN INTEGER,
MEMBER FUNCTION trimSource(ctx     IN OUT RAW,
                           newlen  IN INTEGER) RETURN INTEGER,
MEMBER PROCEDURE readFromSource(
                                ctx      IN OUT RAW,
                                startPos IN INTEGER,
                                numBytes IN OUT INTEGER,
                                buffer   OUT RAW), 
MEMBER PROCEDURE writeToSource(
                               ctx      IN OUT RAW,
                               startPos IN INTEGER,
                               numBytes IN OUT INTEGER,
                               buffer   IN RAW), 
);

where:

source: the source of the stored image data.
height: the height of the image in pixels.
width: the width of the image in pixels.
contentLength: the size of the image file on disk, in bytes.
fileFormat: the file type or format in which the image data is stored (TIFF, JIFF, and so forth).
contentFormat: the type of image (monochrome and so forth).
compressionFormat: the compression algorithm used on the image data.
mimeType: the MIME type information.

ORDImage Constructors

This section describes the ORDImage constructor functions, which are the following:

init( ) for ORDImage
init(srcType,srcLocation,srcName) for ORDImage

init( ) for ORDImage

Format

init( ) RETURN ORDImage;

Description

Initializes instances of the ORDImage object type.

Parameters

None.

Pragmas

None.

Exceptions

None.

Usage Notes

This constructor is a static method that initializes all the ORDImage attributes to NULL with the following exceptions:

source.updateTime is set to SYSDATE
source.local is set to 1 (local)
source.localData is set to empty_blob

You should begin using the init( ) method as soon as possible to allow you to more easily initialize the ORDImage object type, especially if the ORDImage type evolves and attributes are added in a future release. INSERT statements left unchanged using the default constructor (which initializes each object attribute), will fail under these circumstances.

Examples

Initialize the ORDImage object attributes:

BEGIN INSERT INTO pm.online_media (product_id, product_photo)  VALUES (3501, ORDSYS.ORDImage.init()); COMMIT;END;/

init(srcType,srcLocation,srcName) for ORDImage

Format

init(srcType IN VARCHAR2,

srcLocation IN VARCHAR2,

srcName IN VARCHAR2)

RETURN ORDImage;

Description

Initializes instances of the ORDImage object type.

Parameters

srcType: The source type of the image data.
srcLocation: The source location of the image data.
srcName: The source name of the image data.

Pragmas

None.

Exceptions

None.

Usage Notes

This constructor is a static method that initializes all the ORDImage attributes to NULL with the following exceptions:

source.updateTime is set to SYSDATE
source.local is set to 0
source.localData is set to empty_blob
source.srcType is set to the input value
source.srcLocation is set to the input value
source.srcName is set to the input value

Examples

Initialize the ORDImage object attributes:

BEGIN
 INSERT INTO pm.online_media (product_id, product_photo) 
   VALUES (3515, ORDSYS.ORDImage.init('FILE', 'FILE_DIR','speaker.jpg'));
 COMMIT;
END;
/

ORDImage Methods

This section presents reference information on the interMedia methods used specifically for image data manipulation.

Chapter 3 presents reference information on the interMedia methods that are common to ORDAudio, ORDDoc, ORDImage, and ORDVideo. Use the methods presented in both chapters to get and set attributes, perform processing operations, and perform metadata extractions.

The following methods are presented in this section:

checkProperties( )
copy( )
getCompressionFormat( )
getContentFormat( )
getContentLength( )
getFileFormat( )
getHeight( )
getWidth( )
import( )
importFrom( )
process( )
processCopy( )
setProperties( )
setProperties( ) for foreign images

checkProperties( )

Format

checkProperties( ) RETURN BOOLEAN;

Description

Verifies that the properties stored in attributes of the image object match the properties of the image. This method should not be used for foreign images (those formats not natively supported by interMedia).

Parameters

None.

Usage Notes

Use this method to verify that the image attributes match the actual image.

Pragmas

None.

Exceptions

None.

Examples

Check the image attributes:

DECLARE
 image ORDSYS.ORDImage;
 properties_match BOOLEAN;
BEGIN
 SELECT p.product_photo INTO image FROM pm.online_media p
  WHERE p.product_id = 3515;
 -- check that properties match the image
 properties_match := image.checkProperties();
 IF properties_match THEN
  DBMS_OUTPUT.PUT_LINE('Check Properties succeeded');
 ELSE
  DBMS_OUTPUT.PUT_LINE('Check Properties failed');
 END IF;
COMMIT;
END;
/

copy( )

Format

copy(dest IN OUT ORDImage);

Description

Copies an image without changing it.

Parameters

dest: The destination of the new image.

Usage Notes

This method copies the image data, as is, including all source and image attributes, into the supplied local destination image.

If the data is stored locally in the source, then calling this method copies the BLOB to the destination source.localData attribute.

Calling this method copies the external source information to the external source information of the new image, whether or not source data is stored locally.

Calling this method implicitly calls the setUpdateTime( ) method on the destination object to update its timestamp information.

Pragmas

None.

Exceptions

None.

Examples

Create a copy of an image:

DECLARE
 image_1 ORDSYS.ORDImage;
 image_2 ORDSYS.ORDImage;
BEGIN
 -- Initialize a new ORDImage object where the copy will be stored:
  INSERT INTO pm.online_media (product_id, product_photo) 
  VALUES (3091, ORDSYS.ORDImage.init());
 -- Select the source object into image_1:
 SELECT product_photo INTO image_1 FROM pm.online_media 
   WHERE product_id = 3515;
 -- Select the target object into image_2:
 SELECT product_photo INTO image_2 FROM pm.online_media 
   WHERE product_id = 3091 FOR UPDATE;
 -- Copy the data from image_1 to image_2:
 image_1.copy(image_2);
 UPDATE pm.online_media SET product_photo = image_2
  WHERE product_id = 3091;
 COMMIT;
END;
/

getCompressionFormat( )

Format

getCompressionFormat( ) RETURN VARCHAR2;

Description

Returns the value of the compressionFormat attribute of the image object.

Parameters

None.

Usage Notes

Use this method rather than accessing the compressionFormat attribute directly to protect yourself from potential changes to the internal representation of the ORDImage object.

Pragmas

PRAGMA RESTRICT_REFERENCES(getCompressionFormat, WNDS,
WNPS, RNDS, RNPS)

Exceptions

None.

Examples

Get the compression type of an image:

DECLARE
 image ORDSYS.ORDImage;
 compression_format VARCHAR2(4000);
BEGIN
 SELECT p.product_photo INTO image FROM pm.online_media p
  WHERE p.product_id = 3515;
 -- Get the image compression format:
 compression_format := image.getCompressionFormat();
 DBMS_OUTPUT.PUT_LINE('Compression format is ' || compression_format);
 COMMIT;
END;
/

getContentFormat( )

Format

getContentFormat( ) RETURN VARCHAR2;

Description

Returns the value of the contentFormat attribute of the image object.

Parameters

None.

Usage Notes

Use this method rather than accessing the contentFormat attribute directly to protect yourself from potential changes to the internal representation of the ORDImage object.

Pragmas

PRAGMA RESTRICT_REFERENCES(getContentFormat, WNDS,
WNPS, RNDS, RNPS)

Exceptions

None.

Examples

Get the content type of an image:

DECLARE
 image ORDSYS.ORDImage;
 content_format VARCHAR2(4000);
BEGIN
 SELECT p.product_photo INTO image FROM pm.online_media p
  WHERE p.product_id = 3515;
 -- Get the image content format:
 content_format := image.getContentFormat();
 DBMS_OUTPUT.PUT_LINE('Content format is ' || content_format);
 COMMIT;
END;
/

getContentLength( )

Format

getContentLength( ) RETURN INTEGER;

Description

Returns the value of the contentLength attribute of the image object.

Parameters

None.

Usage Notes

Use this method rather than accessing the contentLength attribute directly to protect from potential future changes to the internal representation of the ORDImage object.

Pragmas

PRAGMA RESTRICT_REFERENCES(getContentLength, WNDS,
WNPS, RNDS, RNPS)

Exceptions

None.

Examples

Get the content length of an image:

DECLARE
 image ORDSYS.ORDImage;
 content_length INTEGER;
BEGIN
 SELECT p.product_photo INTO image FROM pm.online_media p
  WHERE p.product_id = 3515;
 -- Get the image size:
 content_length := image.getContentLength();
 DBMS_OUTPUT.PUT_LINE('Content length is ' || content_length);
 COMMIT;
END;
/

getFileFormat( )

Format

getFileFormat( ) RETURN VARCHAR2;

Description

Returns the value of the fileFormat attribute of the image object.

Parameters

None.

Usage Notes

Use this method rather than accessing the fileFormat attribute directly to protect yourself from potential changes to the internal representation of the ORDImage object.

Pragmas

PRAGMA RESTRICT_REFERENCES(getFileFormat, WNDS, WNPS, RNDS, RNPS)

Exceptions

None.

Examples

Get the file type of an image:

DECLARE
 image ORDSYS.ORDImage;
 file_format VARCHAR2(4000);
BEGIN
 SELECT p.product_photo INTO image FROM pm.online_media p
  WHERE p.product_id = 3515;
 -- Get the image file format:
 file_format := Image.getFileFormat();
 DBMS_OUTPUT.PUT_LINE('File format is ' || file_format);
COMMIT;
END;
/

getHeight( )

Format

getHeight( ) RETURN INTEGER;

Description

Returns the value of the height attribute of the image object.

Parameters

None.

Usage Notes

Use this method rather than accessing the height attribute directly to protect yourself from potential changes to the internal representation of the ORDImage object.

Pragmas

PRAGMA RESTRICT_REFERENCES(getHeight, WNDS, WNPS, RNDS, RNPS)

Exceptions

None.

Examples

Get the height of an image:

DECLARE
 image ORDSYS.ORDImage;
 height INTEGER;
BEGIN
 SELECT p.product_photo INTO image FROM pm.online_media p
  WHERE p.product_id = 3515;
 -- Get the image height:
 height := image.getHeight();
 DBMS_OUTPUT.PUT_LINE('Height is ' || height);
 COMMIT;
END;
/

getWidth( )

Format

getWidth( ) RETURN INTEGER;

Description

Returns the value of the width attribute of the image object

Parameters

None.

Usage Notes

Use this method rather than accessing the width attribute directly to protect yourself from potential changes to the internal representation of the ORDImage object.

Pragmas

PRAGMA RESTRICT_REFERENCES(getWidth, WNDS, WNPS, RNDS, RNPS)

Exceptions

None.

Examples

Get the width of an image:

DECLARE
 image ORDSYS.ORDImage;
 width INTEGER;
BEGIN
 SELECT p.product_photo INTO image FROM pm.online_media p
  WHERE p.product_id = 3515;
 -- Get the image width:
 width := image.getWidth();
 DBMS_OUTPUT.PUT_LINE('Width is ' || width);
 COMMIT;
END;
/

import( )

Format

import(ctx IN OUT RAW);

Description

Transfers image data from an external image data source to the localData attribute (of the embedded ORDSource object) within the database.

Parameters

ctx: The source plug-in context information. This should be allocated and initialized to NULL. If you are using a user-defined source plug-in, you should call the openSource( ) method. See the introduction to this chapter for more information.

Usage Notes

Use the setSource( ) method to set the source.srcType, source.srcLocation, and source.srcName attributes (of the embedded ORDSource object) for the external image data source prior to calling the import( ) method.

You must ensure that the directory exists or is created before you use this method for a source.srcType attribute with a value of "file".

After importing data from an external image data source to a local source (within Oracle Database), the source information remains unchanged (that is, pointing to the source from where the data was imported).

Invoking this method implicitly calls the setUpdateTime( ) and setLocal( ) methods.

If the file format of the imported image is not previously set to a string beginning with "OTHER", the setProperties( ) method is also called. Set the file format to a string preceded by "OTHER" for foreign image formats; calling the setProperties( ) method for foreign images does this for you.

This method is invoked at the ORDSource level, which uses the PL/SQL UTL_HTTP package to import media data from an HTTP data source. You can use environment variables to specify the proxy behavior of the UTL_HTTP package. For example, on UNIX, setting the environment variable http_proxy to a URL specifies that the UTL_HTTP package will use that URL as the proxy server for HTTP requests. Setting the no_proxy environment variable to a domain name specifies that the HTTP proxy server will not be used for URLs in the specified domain.

See PL/SQL Packages and Types Reference for more information about the UTL_HTTP PL/SQL package.

Pragmas

None.

Exceptions

ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION

This exception is raised if you call the import( ) method and the value of the source.srcType attribute is NULL.

ORDSourceExceptions.METHOD_NOT_SUPPORTED

This exception is raised if you call the import( ) method and this method is not supported by the source plug-in being used.

See Appendix F for more information about these exceptions.

Examples

Import image data from an external image data source into the local source:

DECLARE
 obj ORDSYS.ORDImage;
 ctx RAW(64) :=NULL;
BEGIN
 SELECT p.product_photo INTO obj FROM pm.online_media p 
  WHERE p.product_id  = 3515 FOR UPDATE;
 DBMS_OUTPUT.PUT_LINE('getting source');
 DBMS_OUTPUT.PUT_LINE('--------------------------');
 -- Get source information
 DBMS_OUTPUT.PUT_LINE(obj.getSource());
 -- Import data
 obj.import(ctx);
 -- Check size
 DBMS_OUTPUT.PUT_LINE('Length is ' || obj.getContentLength);
 UPDATE pm.online_media p SET p.product_photo = obj WHERE p.product_id = 3515;
 COMMIT;
END;
/

importFrom( )

Format

importFrom(ctx IN OUT RAW,

source_type IN VARCHAR2,

source_location IN VARCHAR2,

source_name IN VARCHAR2);

Description

Transfers image data from the specified external image data source to the source.localData attribute (of the embedded ORDSource object) within the database.

Parameters

ctx: The source plug-in context information. This should be allocated and initialized to NULL. If you are using a user-defined source plug-in, you should call the openSource( ) method. See the introduction to this chapter for more information.
source_type: The type of the source image data.
source_location: The location from which the source image data is to be imported.
source_name: The name of the source image data.

Usage Notes

This method is similar to the import( ) method except the source information is specified as parameters to the method instead of separately.

You must ensure that the directory exists or is created before you use this method with a source_type parameter value of "file".

After importing data from an external image data source to a local source (within Oracle Database), the source information (that is, pointing to the source from where the data was imported) is set to the input values.

Invoking this method implicitly calls the setUpdateTime( ) and setLocal( ) methods.

See PL/SQL Packages and Types Reference for more information about the UTL_HTTP PL/SQL package.

Pragmas

None.

Exceptions

ORDSourceExceptions.METHOD_NOT_SUPPORTED

This exception is raised if you call the importFrom( ) method and this method is not supported by the source plug-in being used.

ORDSourceExceptions.SOURCE_PLUGIN_EXCEPTION

This exception is raised if you call the importFrom( ) method and the source plug-in raises an exception.

See Appendix F for more information about these exceptions.

Examples

Import image data from the specified external data source into the local source:

DECLARE
 obj ORDSYS.ORDImage;
 ctx RAW(64) :=NULL;
BEGIN
 SELECT p.product_photo INTO obj FROM pm.online_media p 
  WHERE p.product_id  = 3501 FOR UPDATE;
 -- set source to a file
 -- import data
 obj.importFrom(ctx,'file','FILE_DIR','speaker.jpg');
 -- check size
 DBMS_OUTPUT.PUT_LINE('Length is ' || obj.getContentLength);
 DBMS_OUTPUT.PUT_LINE('Source is ' || obj.getSource());
 UPDATE pm.online_media p SET p.product_photo = obj WHERE p.product_id = 3501;
 COMMIT;
END;
/

process( )

Format

process(command IN VARCHAR2);

Description

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

Parameters

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

Usage Notes

There is no implicit import( ) or importFrom( ) call performed when you call this method; if data is external, you must first call the import( ) or importFrom( ) method to make the data local before you can process it.

Implicit setProperties( ), setUpdateTime( ), and setMimeType( ) methods are done after the process( ) method is called.

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

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.

Table 6-1 Image Processing Operators

Operator Name	Usage	Values
compressionFormat	Forces output to the specified compression format if it is supported by the output file format.	JPEG, SUNRLE, BMPRLE, TARGARLE, LZW, LZWHDIFF, FAX3, FAX4, HUFFMAN3, PACKBITS, GIFLZW, ASCII, RAW, DEFLATE, NONE
compressionQuality	Determines the quality of lossy compression; for use with JPEG only.	MAXCOMPRATIO, MAXINTEGRITY, LOWCOMP, MEDCOMP, HIGHCOMP, or an integer value between 0 and 100.
contentFormat	Determines the format of the image content.	See Section D.2.2 for values.
contrast	Adjusts image contrast. See Section D.3.1 for more information.	nonnegative FLOAT^Foot 1, nonnegative FLOAT FLOAT FLOAT^Foot 2, nonnegative FLOAT FLOAT^Foot 3, nonnegative FLOAT FLOAT FLOAT FLOAT FLOAT FLOAT^Foot 4
cut	Defines a window to cut or crop (origin.x origin.y width height); first pixel in x or y is 0 (zero); must define a window inside image.	nonnegative INTEGER INTEGER INTEGER INTEGER maximum value is 2147483648
fileFormat	Forces the output to specified file format.	BMPF, CALS, GIFF, JFIF, PBMF, PGMF, PICT, PNGF, PNMF, PPMF, RASF, RPIX, TGAF, TIFF, WBMP
fixedScale	Scales an image to a specified size in pixels (width, height); may not be combined with other scale operators.	positive INTEGER INTEGER
flip	Places the scanlines of an image in inverse order -- swapped top to bottom.	No arguments
gamma	Adjusts gamma (brightness) of an image. See Section D.3.4 for more information.	positive FLOAT^Foot 5 positive FLOAT FLOAT FLOAT^Foot 6
maxScale	Scales an image to a specified size in pixels (width, height), while maintaining the aspect ratio; may not be combined with other scale operators.	positive INTEGER INTEGER
mirror	Places columns of an image in reverse order -- swapped left to right.	No arguments
page	Selects a page from a multipage file; for use with TIFF only; first page is 0 (zero).	nonnegative INTEGER
quantize	Specifies how image quantization is to be performed when reducing image bit depth. See Section D.3.7 for more information.	ERRORDIFFUSION (default), ORDEREDDITHER, THRESHOLD, MEDIANCUT
rotate	Rotates an image within the image plane by the angle specified. See Section D.3.8 for more information.	FLOAT
scale	Uniformly scales an image by a given factor (for example, 0.5 or 2.0); may not be combined with other scale operators.	positive FLOAT
tiled	Forces output image to be tiled; for use with TIFF only.	No arguments
xScale	Scales an image on the X-axis by a given factor (default is 1); image is non-uniformly scaled; may be combined only with the yScale operator; may not be combined with any other scale operators.	positive FLOAT
yScale	Scales the image on theY-axis scale by a given factor (default is 1); non-uniformly scales image; may only be combined with the xScale operator; may not be combined with any other scale operators.	positive FLOAT

^Footnote 1Specifies the percent contrast enhancement to be applied to all bands (GRAY or RGB)
^Footnote 2Specifies the percent contrast enhancement to be applied to each band (RGB only)
^Footnote 3Specifies the bounds for contrast enhancement to be applied to all bands (GRAY or RGB)
^Footnote 4Specifies the bounds for contrast enhancement to be applied to each band (RGB only)
^Footnote 5Specifies a gamma value to be applied to all bands (GRAY or RGB)
^Footnote 6Specifies separate gamma values to be applied to each band (RGB only)

Note:

When specifying values that include floating-point numbers, you must use double quotation marks (" ") around the value. If you do not, the wrong values may be passed and you will get incorrect results.

Table 6-2 Additional Image Processing Operators for Raw Pixel and Foreign Images

Operator Name	Usage	Values
channelOrder	Indicates the relative position of the red, green, and blue channels (bands) within the image; changes order of output channels. Only for RPIX.	RGB (default), RBG, GRB, GBR, BRG, BGR
inputChannels	For multiband images, specifies either one (grayscale) or three integers indicating which channels to assign to red (first), green (second), and blue (third). Note that this operator affects the source image, not the destination; RPIX only.	positive INTEGER,^Foot 1 positive INTEGER INTEGER INTEGER^Foot 2
pixelOrder	Forces pixel direction. If NORMAL, then the leftmost pixel appears first in the image. RPIX only.	NORMAL (default), REVERSE
scanlineOrder	Forces scanline direction. If NORMAL, then the top scanline appears first in the image. RPIX and BMPF only.	NORMAL (default), INVERSE

^Footnote 1Specifies that a single band is to be selected from the input image and that band will be used to create a grayscale output image
^Footnote 2Specifies that three bands are to be selected from the input image and those bands will specify the red, green, and blue bands of an RGB output image

Pragmas

None.

Exceptions

ORDImageExceptions.DATA_NOT_LOCAL

This exception is raised if you call the process( ) method and the data is not local (the source.local attribute is 0).

Examples

Example 1: Change the file format of image1 to GIFF:

DECLARE
 obj ORDSYS.ORDImage;
BEGIN
 SELECT product_photo INTO obj FROM pm.online_media
  WHERE product_id = 3515 FOR UPDATE;
 obj.process('fileFormat=GIFF');
 -- Update 
 UPDATE pm.online_media SET product_photo = obj WHERE product_id = 3515;
 -- Roll back to keep original format of image:
 ROLLBACK;
 EXCEPTION
  WHEN ORDSYS.ORDImageExceptions.DATA_NOT_LOCAL THEN
   DBMS_OUTPUT.PUT_LINE('Data is not local');
END;
/

Example 2: Change image1 to use a compression format of JPEG with MAXCOMPRATIO and double the length of the image along the X-axis:

DECLARE
 obj ORDSYS.ORDImage;
BEGIN
 SELECT product_photo INTO obj FROM pm.online_media
  WHERE product_id = 3515 FOR UPDATE;
  obj.process(
       'compressionFormat=JPEG,compressionQuality=MAXCOMPRATIO, xScale="2.0"'); 
 -- Update: 
 UPDATE pm.online_media SET product_photo = obj WHERE product_id = 3515;
 -- Roll back to keep original format of image:
 ROLLBACK;
 EXCEPTION
  WHEN ORDSYS.ORDImageExceptions.DATA_NOT_LOCAL THEN
   DBMS_OUTPUT.PUT_LINE('Data is not local');
END;
/

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 3: Create a thumbnail image:

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

DECLARE
 obj ORDSYS.ORDImage;
BEGIN
 SELECT product_photo INTO obj FROM pm.online_media
  WHERE product_id = 3515 FOR UPDATE;
 obj.process('maxScale=32 32');
 UPDATE pm.online_media p SET product_thumbnail = obj 
  WHERE product_id = 3515;
 COMMIT;
 EXCEPTION
  WHEN ORDSYS.ORDImageExceptions.DATA_NOT_LOCAL THEN
   DBMS_OUTPUT.PUT_LINE('Data is not local');
END;
/

Example 4: Change the format to TIFF and the content format to 8BIT, BIP pixel layout, LUT interpretation, and RGB color space:

DECLARE
 obj ORDSYS.ORDImage;
BEGIN
 SELECT product_photo INTO obj FROM pm.online_media
  WHERE product_id = 3515 FOR UPDATE;
 obj.process('fileFormat=TIFF, contentFormat=8BITBIPLUTRGB');
 UPDATE pm.online_media SET product_photo = obj WHERE product_id = 3515;
 -- Roll back to keep original format of image:
 ROLLBACK;
 EXCEPTION
  WHEN ORDSYS.ORDImageExceptions.DATA_NOT_LOCAL THEN
   DBMS_OUTPUT.PUT_LINE('Data is not local');
END;
/

processCopy( )

Format

processCopy(command IN VARCHAR2,

dest IN OUT ORDImage);

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

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 ORDImage as both the source and destination.

Calling this method processes the image into the destination BLOB from any source (local or external).

Implicit setProperties( ), setUpdateTime( ), and setMimeType( ) methods are applied on the destination image after the processCopy( ) method is called.

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.DATA_NOT_LOCAL

This exception is raised if you call the processCopy( ) method and the destination image source.local attribute value is 0 or the destination source.localData attribute is not initialized.

ORDImageExceptions.NULL_LOCAL_DATA

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

This exception is raised if you call the processCopy( ) method and the source image source.local attribute value is 1 or NULL and the source.localData attribute value is NULL.

Examples

Generate a thumbnail image from a source image:

DECLARE
 obj_1 ORDSYS.ORDImage;
 obj_2 ORDSYS.ORDImage;
 
BEGIN
 SELECT product_photo, product_thumbnail INTO obj_1, obj_2 
  FROM pm.online_media
  WHERE product_id = 3515 FOR UPDATE;
  obj_1.processCopy('maxScale=32 32', obj_2);
 UPDATE pm.online_media SET product_thumbnail = obj_2 
  WHERE product_id=3515;
 COMMIT;
EXCEPTION
  WHEN ORDSYS.ORDImageExceptions.NULL_DESTINATION THEN
   DBMS_OUTPUT.PUT_LINE('The destination is null');
  WHEN ORDSYS.ORDImageExceptions.DATA_NOT_LOCAL THEN
   DBMS_OUTPUT.PUT_LINE('Data is not local');
  WHEN ORDSYS.ORDImageExceptions.NULL_LOCAL_DATA THEN
   DBMS_OUTPUT.PUT_LINE('dest.source.localData attribute is null');
COMMIT;
END;
/

setProperties( )

Format

setProperties( );

Description

Reads the image data to get the values of the object attributes, then stores them into the appropriate attribute fields. The image data can be stored in the database the source.localData attribute, or externally in a BFILE or URL. If the data is stored externally in anything other than a BFILE, the data is read into a temporary BLOB in order to determine the image characteristics.

This method should not be called for foreign images. Use the setProperties( ) for foreign images method instead.

Parameters

None.

Usage Notes

After you have copied, stored, or processed a native format image, call this method to set the current characteristics of the new content, except when this method is called implicitly.

This method sets the following information about an image:

Height in pixels
Width in pixels
Data size of the image on disk, in bytes
File type (TIFF, JFIF, and so forth)
Image type (monochrome and so forth)
Compression type (JPEG, LZW, and so forth)
MIME type (generated based on file format)

Calling this method implicitly calls the setUpdateTime( ) and the setMimeType( ) methods.

Pragmas

None.

Exceptions

ORDImageExceptions.NULL_LOCAL_DATA

This exception is raised if you call the setProperties( ) method and the source.local attribute value is 1 or NULL and the source.localData attribute value is NULL.

Examples

Select the image, and then set the attributes using the setProperties( ) method:

DECLARE
 image ORDSYS.ORDImage;
BEGIN
 SELECT p.product_photo INTO image FROM pm.online_media p
  WHERE p.product_id = 3515 FOR UPDATE;
 -- set property attributes for the image data
 image.setProperties();
 DBMS_OUTPUT.PUT_LINE('image width = ' || image.getWidth());
 DBMS_OUTPUT.PUT_LINE('image height = ' || image.getHeight());
 DBMS_OUTPUT.PUT_LINE('image size = ' || image.getContentLength());
 DBMS_OUTPUT.PUT_LINE('image file type = ' || image.getFileFormat());
 DBMS_OUTPUT.PUT_LINE('image type = ' || image.getContentFormat());
 DBMS_OUTPUT.PUT_LINE('image compression = ' || image.getCompressionFormat());
 DBMS_OUTPUT.PUT_LINE('image mime type = ' || image.getMimeType());
 UPDATE pm.online_media p SET p.product_photo = image 
   WHERE p.product_id = 3515;
 COMMIT;
END;
/

setProperties( ) for foreign images

Format

setProperties(description IN VARCHAR2);

Description

Lets you write the characteristics of certain foreign images whose format is not natively understood by interMedia into the appropriate attribute fields.

Parameters

description: The image characteristics to set for the foreign image.

Usage Notes

Note:

Once you have set the properties for a foreign image, it is up to you to keep the properties consistent. If interMedia detects an unknown file format, it will not implicitly set the properties.

See Appendix E for information on when to use foreign image support. Only some formats that are not natively understood can be described using this setProperties( ) method.

After you have copied, stored, or processed a foreign image, call this method to set the characteristics of the new image content. Unlike the native image types described in Appendix B, foreign images either do not contain information on how to interpret the bits in the file or, interMedia does not understand the information. In this case, you must set the information explicitly.

You can set the image characteristics for foreign images as described in Table 6-3.

Table 6-3 Image Characteristics for Foreign Files

Field	Data Type	Description
CompressionFormat	STRING	Specifies the compression format value. Valid values are: CCITTG3, CCITTG4, or NONE (default).
DataOffset	INTEGER	Specifies an offset (from the beginning of the file to the start of the image data) that interMedia does not try to interpret. Set the offset to skip any potential header. The value must be a nonnegative integer less than the LOB length. Default is zero.
DefaultChannelSelection	INTEGER or INTEGER, INTEGER, INTEGER	Specifies which bands in a multiband image will be interpreted as color channels when the image is read or processed. If a single integer is specified, the image will be treated as a grayscale image consisting of the data in the specified band only. If three integers are specified, the image will be treated as an RGB image, using the first specified band as the red channel, the second as the green channel, and the third as the blue channel. The first band in the image is numbered 1. The band specifications must be equal to or lower than the number of bands in the image. For example: Specify "DefaultChannelSelection = 1" to cause the first band of the image to be interpreted as a grayscale image. Specify "DefaultChannelSelection = 4" to cause the fourth band of the image to be interpreted as a grayscale image. Specify "DefaultChannelSelection = 1, 2, 3" to cause the image to be interpreted as RGB using the first three bands of the image as red, green and blue channels. Specify "DefaultChannelSelection = 3, 1, 4" to cause the image to be interpreted as RGB using the third, first, and fourth bands of the image as the red, green and blue channels.
Height	INTEGER	Specifies the height of the image in pixels. Value must be a positive integer. There is no default, thus a value must be specified.
Interleaving	STRING	Specifies the band layout within the image. Valid styles are: BIP (default) Band Interleaved by Pixel BIL Band Interleaved by Line BSQ Band Sequential
NumberOfBands	INTEGER	Specifies the number of color bands in the image with a value that is a positive integer less than 255. Default is 3.
PixelOrder	STRING	Specifies a string to indicate the pixel order. If the string is NORMAL (default), the leftmost pixel appears first in the file. If the string is REVERSE, the rightmost pixel appears first.
ScanlineOrder	STRING	Specifies a string to indicate the scanline order. If the string is NORMAL (default), the top scanline appears first in the file. If the string is INVERSE, then the bottom scanline appears first.
UserString	STRING	Specifies a 4-character descriptive string. If used, the string is stored in the fileFormat attribute, appended to the user string " OTHER:". Default is blank and fileFormat is set to "OTHER".
Width	INTEGER	Specifies the width of the image in pixels. Value must be a positive integer. There is no default, thus a value must be specified.
MimeType	STRING	Specifies a MIME type, such as img/gif.

The values supplied to the setProperties( ) for foreign images method are written to the existing ORDImage data attributes. The fileFormat attribute is set to OTHER and includes the user string, if supplied; for example, OTHER: LANDSAT.

Pragmas

None.

Exceptions

ORDImageExceptions.NULL_PROPERTIES_DESCRIPTION

This exception is raised if you call the setProperties( ) for foreign images method and the description parameter value is NULL.

Examples

Select the foreign image and then set the properties for the image:

DECLARE
    obj ORDSYS.ORDImage;
BEGIN
 SELECT p.product_photo INTO obj FROM pm.online_media p
  WHERE p.product_id = 3501 FOR UPDATE;
 -- Set property attributes for the image data:
 obj.setProperties('width=123 height=321 compressionFormat=NONE' ||
                     ' userString= LANDSTAT dataOffset=128' || 
                     ' scanlineOrder=INVERSE pixelOrder=REVERSE' ||
                     ' interleaving=BIL numberOfBands=1' ||
                     ' defaultChannelSelection=1');
 UPDATE pm.online_media SET product_photo = obj 
   WHERE product_id=3501;
 COMMIT;
END;
/