4
Visual Information Retrieval Reference

The Visual Information Retrieval library consists of:

Object type -- see Section 4.1.
Methods -- see Section 4.2.
Operators -- see Section 4.3.

The examples in this chapter assume that the stockphotos table, referred to in Chapter 3, has been created and filled with some photographic images. The table was created using the following SQL statement:

CREATE TABLE stockphotos (photo_id NUMBER, photographer VARCHAR2(64),
             annotation VARCHAR2(255), photo ORDSYS.ORDVIR);

When you are storing or copying images, you must first create an empty BLOB in the table. The following shows an empty Visual Information Retrieval object:

ORDSYS.ORDVIR(ORDIMAGE(ORDSOURCE(empty_blob(),NULL, NULL, NULL, SYSDATE, NULL),

                       NULL, NULL, NULL, NULL, NULL, NULL, NULL), 

               NULL);





Note:



If you manipulate the image data itself by either directly modifying the BLOB, or changing the external source, then you must ensure that the object attributes stay synchronized and the update time is modified. Otherwise, the object attributes will not match the image data.

Methods invoked at the ORDSource level that are handed off to the source plug-in for processing have ctx(RAW(4000)) as their first argument. Before calling any of these methods for the first time, the client must perform the following tasks:

Allocate the ctx structure.
Initialize the ctx structure to null.
Invoke the source.open( ) method.

At this point, the source plug-in can initialize the context for this client.
When processing is complete, the client should invoke the source.close( ) method.

See Oracle8i interMedia Audio, Image, and Video User's Guide and Reference for descriptions of source methods.

Methods invoked from a source plug-in have their first argument as ctx(RAW(4000)).

Note:
In the current release, not all source plug-ins will use the ctx argument, but if you code as previously described, your applications should work with any current of future source plug-in.

4.1 Object Type

The Visual Information Retrieval object type ORDVir is composed of the ORDImage type and a signature component. The ORDImage type is composed of the ORDSource type and a number of additional descriptive components.

This section presents reference information on the object types.

For more information on BLOBs and BFILEs, see Oracle8i Application Developer's Guide - Large Objects (LOBs). For more information on the ORDImage and ORDSource types, see Oracle8i interMedia Audio, Image, and Video User's Guide and Reference.

ORDVir Object Type

The ORDVir object type supports storage and retrieval of image data stored in a BLOB, external file, or referenced by a URL. This object type is defined as follows:

CREATE TYPE ORDVIR AS OBJECT
(
-- TYPE ATTRIBUTES
image               ORDImage,
signature           RAW(2000)
-- METHOD DECLARATION
 -- IMAGE COPY METHOD
  MEMBER PROCEDURE copy(dest IN OUT NOCOPY ORDVir), 

 -- IMAGE PROCESSING RELATED METHODS
  MEMBER PROCEDURE process(SELF    IN OUT ORDVir,
                           command IN     VARCHAR2),
  MEMBER PROCEDURE processCopy(command IN     VARCHAR2, 
                               dest    IN OUT NOCOPY ORDVir),

 -- IMAGE PROPERTY SET AND CHECK METHODS
  MEMBER PROCEDURE setProperties(SELF IN OUT ORDVir),
  MEMBER PROCEDURE setProperties(SELF IN OUT ORDVir,
                                 description IN VARCHAR2),
  MEMBER FUNCTION checkProperties RETURN BOOLEAN,

   -- IMAGE ATTRIBUTE ACCESSOR METHODS
  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 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),
 
  MEMBER FUNCTION getSignature RETURN RAW,
  PRAGMA RESTRICT_REFERENCES(getSignature, WNDS, WNPS, RNDS, RNPS),
  -- DATE RELATED METHODS
  MEMBER FUNCTION  getUpdateTime RETURN DATE,
  PRAGMA RESTRICT_REFERENCES(getUpdateTime, WNDS, WNPS, RNDS, RNPS),
  MEMBER PROCEDURE setUpdateTime(current_time DATE),
 
  -- MIMETYPE RELATED METHODS
  MEMBER FUNCTION getMimeType RETURN VARCHAR2,
  PRAGMA RESTRICT_REFERENCES(getMimeType, WNDS, WNPS, RNDS, RNPS),
  MEMBER PROCEDURE setMimeType(mimetype IN VARCHAR),
 
  -- SOURCE/CONTENT RELATED METHODS
  MEMBER FUNCTION  getContentLength RETURN INTEGER,
  PRAGMA RESTRICT_REFERENCES(getContentLength, WNDS, WNPS, RNDS, RNPS),
 
  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(SELF IN OUT ORDVir),
 
  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),
 
  MEMBER PROCEDURE setLocal,
  MEMBER PROCEDURE clearLocal,
  MEMBER FUNCTION isLocal RETURN BOOLEAN,
  PRAGMA RESTRICT_REFERENCES(isLocal, WNDS, WNPS, RNDS, RNPS),
 
  -- MIGRATION RELATED METHODS
  MEMBER PROCEDURE migrateFromORDVirB(
                        SELF IN OUT ORDVIR,
                        old_object IN ORDVirB),
 
  MEMBER PROCEDURE migrateFromORDVirF(
                        SELF IN OUT ORDVIR,
                        old_object IN ORDVirF),
 
  -- VIRAGE RELATED METHODS
  MEMBER PROCEDURE analyze(SELF IN OUT ORDVir) 
);

The ORDImage object type consists of the fields shown in Table 4-1.

Table 4-1 ORDImage Object Type

Attribute	Data Type	Description
source	ORDSource	Points to the source of the stored image data
height	INTEGER	Height of the image in pixels
width	INTEGER	Width of the image in pixels
contentLength	INTEGER	Size of the on-disk image file in bytes
fileFormat	VARCHAR2(4000)	File type of image (such as, TIFF or JFIF)
contentFormat	VARCHAR2(4000)	Type of image (such as, monochrome or 8-bit grayscale
compressionFormat	VARCHAR2(4000)	Compression type of the image
mimeType	VARCHAR2(4000)	MIME type of the image

The ORDSource object type consists of the fields shown in Table 4-2.

Table 4-2 ORDSource Object Type

Attribute	Data Type	Description
localData	BLOB	Locally stored image data.
srcType	VARCHAR2(4000)	Identifies the source type as one of the following: NULL 'FILE' -- source is an external file 'HTTP' -- HTTP server name '<name>' -- name of another source
srcLocation	VARCHAR2(4000)	Identifies where the data can be found based on the srcType. See Table 4-3.
srcName	VARCHAR2(4000)	Identifies the data object name based on the source type. See Table 4-4.
updateTime	DATE	The time at which the data was last updated.
local	NUMBER	Flag to determine if the data is local (1) or not (0).

Table 4-3 describes the valid srcLocation values.

Table 4-3 srcLocation Values

srcType	srcLocation
NULL	NULL or not accessed
FILE	<DIR> or name of the directory object
HTTP	<SourceBase> or URL needed to find the base directory
<name>	<iden> or identifier string required to access another server

Table 4-4 describes the valid srcName values.

Table 4-4 Valid srcName Values

srcType	srcName
NULL	NULL or not accessed
FILE	<FILE> or name of the file
HTTP	<Source> or name of the object
<name>	<object name> or name of the object

In PL/SQL, data is moved with the DBMS LOB package. From the client, data is moved using OCI LOB calls. The ORDVir object type does not supply routines for moving data piece by piece.

4.2 Methods for Image Manipulation

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

The Visual Information Retrieval methods are as follows:

analyze( ): creates the signature of an image based on the image characteristics.
checkProperties( ): verifies that the characteristics stored within an image object match the object attributes.
clearLocal( ): resets the flag to indicate that data is stored externally.
copy( ): copies an ORDVir image to another ORDVir object.
deleteContent( ): deletes the contents of an image stored in a BLOB.
export( ): transfers data from the local source to the specified external data source. Note that sources not natively supported by Visual Information Retrieval are not writable, and therefore do not support the export( ) method.
getBFILE( ): returns the external image as a BFILE.
getCompressionFormat( ): returns the compression type used on an image.
getContent( ): returns the content of the local data.
getContentFormat( ): returns the type of the image.
getContentLength( ): returns the size of the image in bytes.
getFileFormat( ): returns the file type of an image.
getHeight( ): returns the height of the image in pixels.
getMimeType( ): returns the MIME type of an image.
getSignature( ): returns the signature of an image.
getSource( ): returns a string containing complete information about the external data source, formatted as a URL.
getSourceLocation( ): returns the external source location of the image data.
getSourceName( ): returns the external source name of the image data.
getSourceType( ): returns the external source type of the image data.
getUpdateTime( ): returns the time when the image object was last updated.
getWidth( ): returns the width of an image in pixels.
import( ): transfers data from an external data source to the local source.
importFrom( ): transfers data from the specified external data source to the local source.
isLocal( ): returns TRUE if the data is stored locally in a BLOB, or FALSE if the data is external.
migrateFromORDVirB( ): copies an old ORDVirB image to an ORDVir object.
migrateFromORDVirF( ): copies an old ORDVirF image to an ORDVir object.
process( ): processes an image in place (for example, modifies it or converts it to another format); available for BLOBs only.
processCopy( ): copies an image and processes the copy (for example, modifies it or converts it to another format); available for any source, but the destination must be a BLOB.
setMimeType( ): sets the MIME type of the image. This method is called implicitly by any method that modifies native images.
setProperties( ): obtains and stores the attributes of an image for native image formats. A second version of this method does the same for foreign images.
setSource( ): sets the source information to where the external image data is located.
setUpdateTime( ): sets the updateTime attribute for the image object, indicating when the image was last changed.

For more information on object types and methods, see Oracle8i Concepts.

Note that some of the following methods have pragma, or compiler directives, associated with them. The pragma tells the PL/SQL compiler what sort of access the method needs to the database. The compiler can then deny the method read/write access to database tables, packaged variables, or both. Methods with defined pragma (such as the getXXX methods) can be called from SQL expressions.

Pragmas use the following syntax:

PRAGMA RESTRICT REFERENCES (function_name, WNDS, [,WNPS] [,RNDS] [RNPS]);

where:

WNDS means "writes no database state"
WNPS means "writes no package state"
RNDS means "reads no database state"
RNPS means "reads no package state"

analyze( ) Method

Format

analyze( );

Description

Analyzes an image, derives information relating to the visual attributes (including a score for each), and creates the image signature.

Parameter

None.

Usage

The analyze( ) method creates the image attribute signature, which is necessary for any content-based retrieval. Whenever you are working with a new or changed image, you should also use the SetProperties( ) method to set the other image characteristics.

Signatures for facial images can be created using an optional third-party software package from Viisage Technology, Inc. After creating a facial signature, Visual Information Retrieval can convert the signature to a standard format using the
Convert( ) operator and then compare the signatures using the VIRScore( ) and VIRSimilar( ) operators.

The analyze( ) method is functionally equivalent to the Analyze( ) operator. You must use the analyze( ) method, and not the operator, when working with foreign images (images not natively supported).

Pragmas

None.

Exceptions

None.

Example

Create the signatures for all images in the stockphotos table.

DECLARE
   temp_image   ORDSYS.ORDVir;
   temp_id      INTEGER;
   cursor c1 is select id, image from stockphotos for update;
BEGIN
   OPEN c1;
   LOOP
      fetch c1 into temp_id, temp_image;
      EXIT WHEN c1%NOTFOUND;
  
 -- Generate signature and set the properties for the image.
      temp_image.analyze; 
      temp_image.setProperties;
      UPDATE stockphotos SET photo = temp_image WHERE photo_id = temp_id;
   END LOOP;
   CLOSE c1;
END;

checkProperties( ) Method

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.

Parameter

None.

Usage

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

Pragma

None.

Exception

None.

Example

Check the image attributes:

image            ORDSYS.ORDVir;
properties_match BOOLEAN;
BEGIN
  SELECT large_photo INTO image FROM emp
    WHERE ename='John Doe' FOR UPDATE;
  properties_match := image.checkProperties;
  IF properties_match THEN DBMS_OUTPUT.PUT_LINE('Check Properties Succeeded');
  END IF;
END;

clearLocal( ) Method

Format

clearLocal;

Description

Resets the local flag value from local (1) to nonlocal (0) for the source of the data.

Parameter

None.

Usage

When the local flag is clear (0), this means that the data is stored externally. In that case, Visual Information Retrieval methods look for image data in the srcType, srcName, and srcLocation attributes.

Pragma

None.

Exception

None.

Example

DECLARE
    Image ORDSYS.ORDVir;
BEGIN
    SELECT large_photo INTO Image FROM emp WHERE ename = 'John Doe' FOR UPDATE;
 
    -- clear local so we look for image externally
    Image.clearLocal;
  
    UPDATE emp SET large_photo = Image WHERE ename = 'John Doe';
END;
/

copy( ) Method

Format

copy(dest IN OUT NOCOPY ORDVir);

Description

Copies an image without changing it.

Parameter

dest

The destination of the new image.

Usage

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

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

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

Pragma

None.

Exception

NULL_LOCAL_DATA -- raised if the destination source.localData is not initialized, or if the source.isLocal value is 1 and source.localData is NULL.

Example

Create a copy of the image:


DECLARE
    Image_1 ORDSYS.ORDVir;
    Image_2 ORDSYS.ORDVir;
BEGIN
    SELECT photo, large_photo
       INTO Image_2, Image_1
       FROM emp
       WHERE ename = 'John Doe' FOR UPDATE;
    -- copy the data from Image_1 to Image_2
    Image_1.copy(Image_2);
    UPDATE emp SET photo = Image_2
        WHERE ename = 'John Doe';
END;

deleteContent( ) Method

Format

deleteContent;

Description

Deletes the local data from the current local source (localData).

Parameter

None.

Usage

This method can be called after you export the data from the local source to an external image data source and you no longer need this data in the local source.

Pragma

None.

Exception

None.

Example

Delete the local data from the current local source:

DECLARE
    Image ORDSYS.ORDVir;
BEGIN
    SELECT large_photo INTO Image FROM emp
      WHERE ename = 'John Doe' FOR UPDATE;
     -- delete the local content of the image
    Image.deleteContent;
    UPDATE emp SET large_photo = Image WHERE ename = 'John Doe';
END;
/

export( ) Method

Format

export(ctx IN OUT RAW,

source_type IN VARCHAR2,

source_location IN VARCHAR2,

source_name IN VARCHAR2);

Description

Transfers image data from a local source (localData) within an Oracle database to an external image data source.

Parameters

ctx

The source plug-in context information.

source_type

The source type of the location where the image data is to be exported.

source_location

The location where the image data is to be exported.

source_name

The name of the image object where the image is to be exported.

Usage

After exporting image data, all image attributes remain unchanged, except the source attribute and the value of the local attribute, which is set to zero, meaning nonlocal. After calling the export method, call the deleteContent method to delete the content of the local data if you want to delete the contents of localData.

There is no server-side native support for the export method. This method is available for user-defined sources that can support the export method.

Whenever you import or export images with signature data between platforms, you should use the convert( ) method to ensure that the signature is in the correct format.

Pragma

None.

Exception

None.

Example

None.

getBFILE Method

Format

getBFILE RETURN BFILE;

Description

Returns the LOB locator of the BFILE containing the image.

Parameter

None.

Usage

This method constructs a BFILE using the stored srcLocation and srcName. srcLocation must contain a defined directory object, and srcName must contain a valid file name.

Pragma

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

Exceptions

INCOMPLETE_SOURCE_INFORMATION -- raised if the srcType is NULL.

INVALID_SOURCE_TYPE -- raised if srcType is not FILE.

Example

Get the BFILE for the image:

DECLARE
    Image ORDSYS.ORDVir;
    imagebfile BFILE;
BEGIN
    SELECT large_photo INTO Image FROM emp
      WHERE ename = 'John Doe';
 
    -- get the image BFILE
    imagebfile := Image.getBFILE;
END;

getCompressionFormat Method

Format

getCompressionFormat RETURN VARCHAR2;

Description

Returns the compression type of an image. This method does not actually read the image, it is a simple access method that returns the value of the compressionFormat attribute.

Parameter

None.

Usage

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

Pragma

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

Exception

None.

Example

Get the compression type of an image:

imgb1             ORDSYS.ORDVir;
compressionFormat VARCHAR2(4000);

...
compressionFormat := imgb1.getCompressionFormat;

getContent Method

Format

getContent RETURN BLOB;

Description

Returns the LOB locator of the BLOB containing the image. This is a simple access method that returns the value of the localData attribute.

Parameter

None.

Usage

This method can be used in conjunction with the getMimeType method. For example, a client trying to access image data to put it on a Web-based viewer can call getMimeType and publish the header and then call getContent to access the image data and send it over the wire.

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

Pragma

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

Exception

None.

Example

A client accesses image data:

DECLARE
    Image ORDSYS.ORDVir;
    localData BLOB;
BEGIN
    SELECT large_photo INTO Image FROM emp
      WHERE ename = 'John Doe';
    -- get the image BLOB
    localData := Image.getContent;
END;

getContentFormat Method

Format

getContentFormat RETURN VARCHAR2;

Description

Returns the format of an image (such as monochrome or 8-bit grayscale). This method does not actually read the image; it is a simple access method that returns the value of the contentFormat attribute.

Parameter

None.

Usage

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

Pragma

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

Exception

None.

Example

Get the type of an image:

imgb1         ORDSYS.ORDVir;
contentFormat VARCHAR2(4000);

...
contentFormat := imgb1.getContentFormat;

getContentLength( ) Method

Description

Returns the length of the image data content stored in the source. This method does not actually read the image; it is a simple access method that returns the value of the contentLength attribute.

Format

getContentLength RETURN INTEGER;

Parameter

None.

Usage

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

Pragma

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

Exception

None.

Example

Get the length of the image data content stored in the source:

imgb1         ORDSYS.ORDVir;
contentLength INTEGER;

...
contentLength := imgb1.getContentLength;

getFileFormat( ) Method

Format

getFileFormat RETURN VARCHAR2;

Description

Returns the file type of an image (such as TIFF or JFIF). This method does not actually read the image; it is a simple access method that returns the value of the fileFormat attribute.

Parameter

None.

Usage

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

Pragma

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

Exception

None.

Example

Get the file type of an image:

imgb1      ORDSYS.ORDVir;
fileFormat VARCHAR2(4000);

...
fileFormat := imgb1.getFileFormat;

getHeight( ) Method

Format

getHeight RETURN INTEGER;

Description

Returns the height of an image in pixels. This method does not actually read the image; it is a simple accessor method that returns the value of the height attribute.

Parameter

None.

Usage

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

Pragma

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

Exception

None.

Example

Get the height of an image:

imgb1  ORDSYS.ORDVir;
height INTEGER;

...
height := imgb1.getHeight;

getMimeType( ) Method

Format

getMimeType RETURN VARCHAR2;

Description

Returns the MIME (Multipurpose Internet Mail Exchange) type of an image (such as image/jpeg or image/gif). This method does not actually read the image, it is a simple access method that returns the value of the mimeType attribute.

Parameter

None.

Usage

Use this method to obtain the MIME type of the image. The MIME type is required by Web browsers along with image content. It tells the web browser how to interpret the image.

For unrecognizable formats, you must call the setMimeType( ) method and specify the appropriate MIME type.

See Appendix A for the MIME type associated with each supported file type.

Pragma

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

Exception

None.

Example

Return the MIME media type:

imgb1      ORDSYS.ORDVir;
mimeType   VARCHAR2(4000);

...
mimeType := imgb1.getMimeType;

getSignature( ) Method

Format

getSignature RETURN RAW;

Description

Returns the signature of an image. This method does not actually create the image signature, it is a simple access method that returns the contents of the signature attribute.

Parameter

None.

Usage

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

Pragma

None.

Exception

None.

Example

Get the signature of an image:

virb1     ORDSYS.ORDVir;
 signature RAW(2000);

...
signature := virb1.getSignature;

getSource( ) Method

Format

getSource RETURN VARCHAR2;

Description

Returns information about the external location of the image data in URL format.

Parameter

None.

Usage

The possible return values for this method are:

file://<DIR OBJECT NAME>/<FILE NAME>
HTTP://<URL>
<user-defined_type>://<user_defined_location>/<user_defined_name>

Pragma

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

Exception

None.

Example

Get the source of the image data:

DECLARE
    Image ORDSYS.ORDVir;
    SourceInfo VARCHAR2(4000);
BEGIN
    SELECT large_photo INTO Image FROM emp
      WHERE ename = 'John Doe';
    -- get the image source information
    SourceInfo := Image.getSource;
END;

getSourceLocation( ) Method

Format

getSourceLocation RETURN VARCHAR2;

Description

Returns a formatted string containing the external image data source location.

Parameter

None.

Usage

This method returns a VARCHAR2 string formatted as <location> for the current value of the srcLocation attribute.

Pragma

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

Exception

INCOMPLETE_SOURCE_LOCATION -- raised if the location is not set in the image object.

Example

Get the source information about an image data source location:

DECLARE
    Image ORDSYS.ORDVir;
    SourceLocation VARCHAR2(4000);
BEGIN
    SELECT large_photo INTO Image FROM emp
      WHERE ename = 'John Doe';
 
    -- get the image source location
    SourceLocation := Image.getSourceLocation;
END;

getSourceName( ) Method

Format

getSourceName RETURN VARCHAR2;

Description

Returns a string containing the name of the external image data source.

Parameter

None.

Usage

This method returns a VARCHAR2 string containing the name of the external data source, for example, 'testimg.dat' .

Pragma

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

Exception

INCOMPLETE_SOURCE_NAME -- raised if the srcName is not set in the image object.

Example

Get the source name information about an image data source:

DECLARE
    Image ORDSYS.ORDVir;
    SourceName VARCHAR2(4000);
BEGIN
    SELECT large_photo INTO Image FROM emp
      WHERE ename = 'John Doe';
 
    -- get the image source name
    SourceName := Image.getSourceName;
END;
/

getSourceType( ) Method

Format

getSourceType RETURN VARCHAR2;

Description

Returns a string containing the type of the external data source.

Parameter

None.

Usage

This method returns a VARCHAR2 string containing the type of the external image data source, for example, 'FILE'.

Pragma

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

Exception

None.

Example

Get the source type information about an image data source:

DECLARE
    Image ORDSYS.ORDVir;
    SourceType VARCHAR2(4000);
BEGIN
    SELECT large_photo INTO Image FROM emp
      WHERE ename = 'John Doe';
 
    -- get the image source type
    SourceType := Image.getSourceType;
END;
/

getUpdateTime( ) Method

Format

getUpdateTime RETURN DATE;

Description

Returns the time when the image was last updated.

Parameter

None.

Usage

None.

Pragma

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

Exception

None.

Example

Get the updated time of some image data:

DECLARE
   Image       ORDSYS.ORDVir;
   UpdateTime  DATE;
BEGIN
   SELECT large_photo INTO Image FROM emp
     WHERE ename = 'John Doe';
 -- get the image update time
   UpdateTime := Image.getUpdateTime;
END;
/

getWidth( ) Method

Format

getWidth RETURN INTEGER;

Description

Returns the width of an image in pixels. This method does not actually read the image; it is a simple access method that returns the value of the width attribute.

Parameter

None.

Usage

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

Pragma

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

Exception

None.

Example

Get the width of an image:

imgb1  ORDSYS.ORDVir;
width  INTEGER;

...
width := imgb1.getWidth;

import( ) Method

Format

import(ctx IN OUT RAW);

Description

Transfers image data from an external image data source to a local source (localData) within an Oracle database.

Parameter

ctx

Specifies the source plug-in context information. The ctx structure must be allocated, and you must call the source.open( ) method. See the beginning of this chapter for more information.

Usage

Use the setSource( ) method to set the external source type, location, and name, prior to calling the import( ) method.

After importing data from an external image data source to a local source (within an Oracle database), the source information remains unchanged (that is, it points 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 native, the setProperties( ) method is also called.

Whenever you import or export images with signature data between platforms, you should use the convert( ) method to ensure that the signature is in the correct format.

Pragma

None.

Exceptions

INCOMPLETE_SOURCE_INFORMATION --raised if the value of srcType is 'NULL'.
NULL_SOURCE -- raised if the value of BLOB is 'NULL'.
METHOD_NOT_SUPPORTED -- raised if the import( ) method is not supported by the source plug-in being used.

Example

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

DECLARE
    Image ORDSYS.ORDVir;
     ctx  RAW(4000) := NULL;
BEGIN
    -- select the image to be imported
    SELECT large_photo INTO Image FROM emp
           WHERE ename = 'John Doe' FOR UPDATE;
    
    -- import the image into the database
    Image.import(ctx);
END;
/

importFrom( ) Method

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 a local source (localData) within an Oracle database.

Parameters

ctx

Specifies the source plug-in context information. The ctx structure must be allocated, and you must call the source.open( ) method. See the beginning of this chapter for more information.

source_type

Specifies the source type of the image data.

source_location

Specifies the location from which the image data is to be imported.

source_name

Specifies the name of the image data.

Usage

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

Invoking this method implicitly calls the setUpdateTime( ) and setLocal methods. If the file format of the imported image is natively supported, the setProperties( ) method is also called.

Whenever you import or export images with signature data between platforms, you should use the convert( ) method to ensure that the signature is in the correct format.

Pragma

None.

Exception

None.

Example

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

DECLARE
    Image ORDSYS.ORDVir;
    ctx   RAW(4000):=NULL;
BEGIN
    -- select the image to be imported
    SELECT large_photo INTO Image FROM emp
           WHERE ename = 'John Doe' FOR UPDATE;
    
    -- import the image into the database
    Image.importFrom(ctx,
                     'file',
                     'ORDIMGDIR',
                     'jdoe.gif');
 
    UPDATE emp SET large_photo = Image WHERE ename = 'John Doe';
END;
/

isLocal( ) Method

Format

isLocal RETURN BOOLEAN;

Description

Returns the current value of the local flag, indicating whether or not the data is stored locally.

Parameter

None.

Usage

A value of TRUE means the data is local to the database. A value of FALSE means the data is external to the database.

Pragma

Pragma RESTRICT_REFERENCES(isLocal, WNDS, WNPS,RNDS,RNPS)

Exception

None.

Example

Determine whether or not data is local:

DECLARE
    Image ORDSYS.ORDVir;
BEGIN
    SELECT large_photo INTO Image FROM emp WHERE ename = 'John Doe'; 
    -- check to see if image is stored locally
    IF Image.isLocal THEN
        DBMS_OUTPUT.PUT_LINE('Image is stored locally');
    ELSE
        DBMS_OUTPUT.PUT_LINE('Image is stored externally');
    END IF;
END;

migrateFromORDVirB( ) Method

Format

migrateFromORDVirB(old_object ORDVirB);

Description

Allows you to migrate old ORDVirB images to the new ORDVir object type.

Parameter

old_object

The old ORDVirB image.

Usage

This method copies images from the source BLOB to the destination BLOB, copies all image attributes from the old object to the new object, and sets the update time and local attribute.

Pragma

None.

Exceptions

NULL_SOURCE -- raised if src(old_object) is NULL.
NULL_DESTINATION -- raised if destination ORDVir is NULL.
NULL_CONTENT -- raised if old object content attribute is NULL.
NULL_LOCAL_DATA -- raised if destination ORDVir source.localData is NULL.

Example

Migrate an old ORDVirB image to a new ORDVir image:

DECLARE
    Image ORDSYS.ORDVir;
    old_image ORDSYS.ORDVirB;
BEGIN
    -- Select the old image
    SELECT imageb INTO old_image FROM old_images WHERE id = 1;
 
    -- Select the new image
    SELECT large_photo INTO Image FROM emp WHERE ename = 'John Doe' FOR UPDATE;
 
    -- Migrate from the old to the new
    Image.migrateFromORDVirB(old_image);
 
    UPDATE emp SET large_photo = Image WHERE ename = 'John Doe';
END;
/

migrateFromORDVirF( ) Method

Format

migrateFromORDVirF(old_object ORDVirF);

Description

Allows you to migrate old ORDVirF images to the new ORDVir object type.

Parameter

old_object

The old ORDVirF image.

Usage

Extracts the directory name and file name from the source image and copies them to the srcLocation and SrcName attributes of the destination image. This method copies all image attributes from the old object to the new object, sets the update time, and clears the local attribute.

Pragma

None.

Exception

None.

Example

Migrate an old ORDVirF image to a new ORDVir image:


DECLARE
    Image ORDSYS.ORDVir;
    old_image ORDSYS.ORDVirF;
BEGIN
    -- Select the old image
    SELECT imagef INTO old_image FROM old_images WHERE id = 1;
 
    -- Select the new image
    SELECT large_photo INTO Image FROM emp WHERE ename = 'John Doe' FOR UPDATE;
 
    -- Migrate from the old to the new
    Image.migrateFromORDVirF(old_image);
 
    UPDATE emp SET large_photo = Image WHERE ename = 'John Doe';
END;
/

process( ) Method

Format

process(command IN VARCHAR2);

Description

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

Parameter

command

A list of image processing changes to make for the image.

Usage

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

Table 4-5 Image Processing Operators

Operator Name	Usage	Values
compressionFormat	Compression type/format	JPEG, SUNRLE, BMPRLE, TARGARLE, LZW, LZWHDIFF, FAX3, FAX4, HUFFMAN3, Packbits, GIFLZW
compressionQuality	Compression quality	MAXCOMPRATIO, MAXINTEGRITY, LOWCOMP, MEDCOMP, HIGHCOMP
contentFormat	Imagetype/pixel/data format	MONOCHROME, 8BITGRAYSCALE, 8BITGREYSCALE, 8BITLUT, 24BITRGB
cut	Window to cut or crop (origin.x origin.y width height)	(Integer Integer Integer Integer) maximum value is 65535
fileFormat	File format of the image	BMPF, CALS, GIFF, JFIF, PICT, RASF, RPIX, TGAF, TIFF
fixedScale	Scale to a specific size in pixels (Width, Height)	(INTEGER INTEGER)
maxScale	Scale to a specific size in pixels, while maintaining the aspect ratio (maxWidth, maxHeight)	(INTEGER INTEGER)
scale	Scale factor (for example, 0.5 or 2.0)	<FLOAT> positive
xScale	X-axis scale factor (default is 1)	<FLOAT> positive
yScale	Y-axis scale factor (default is 1)	<FLOAT> positive

Table 4-6 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.	RGB (default), RBG, GRB, GBR, BRG, BGR
InputChannels	For multiband images, specify either one (grayscale) or three integers indicating which channels to assign to red (first), green (second), and blue (third). Note that this parameter affects the source image, not the destination.	INTEGER or INTEGER INTEGER INTEGER
Interleave	Controls band layout within the image: Band Interleaved by Pixel Band Interleaved by Line Band Sequential	BIP (default), BIL, BSQ
PixelOrder	If NORMAL, then the leftmost pixel appears first in the image.	NORMAL (default), REVERSE
ScanlineOrder	If NORMAL, then the top scanline appears first in the image.	NORMAL (default), INVERSE

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

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

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

Note that because you are changing the object, you must have the appropriate write access to the table. Also, you must select the object for update.

See Appendix C for complete descriptions of the process( ) operators.

Pragma

None.

Exception

DATA_NOT_LOCAL -- raised if data is not local or source.localData is NULL.

Example

Change the file format of image1 to GIF:

SELECT photo INTO image1 FROM ordimgtab FOR UPDATE
image1.process('fileFormat=GIFF');

Change image1 to use lower quality JPEG compression and double the length of the image along the X-axis:

image1.process('compressionFormat=JPEG, compressionQuality=LOWCOMP, 
xScale="2.0"');

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

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

image1.process(maxScale="32 32");

processCopy( ) Method

Format

processCopy(command IN VARCHAR2,

dest IN OUT NOCOPY ORDVir);

Description

Copies an image stored internally or externally to another image stored internally as a BLOB.

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

See Table 4-5, "Image Processing Operators" and Table 4-6, "Additional Image Processing Operators for Raw Pixel and Foreign Images". See Appendix C for complete descriptions of the processCopy( ) operators.
You cannot specify the same BLOB as both the source and destination.
Calling this method processes the image into the destination BLOB from any source (local or external).
The destination source must be initialized prior to calling this method.
The destination image must be local.
Implicit setProperties( ), setUpdateTime( ), and setMimeType( ) methods are done after the processCopy( ) method is called.

Pragma

None.

Exceptions

NULL_DESTINATION -- raised if the value of dest is NULL.

NULL_LOCAL_DATA -- raised if source.localData is NULL and source.isLocal is 1. Also raised if dest.source.lcoalData is NULL.

DATA_NOT_LOCAL -- raised if the destination image is not local.

Example

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

create or replace procedure copyit is 
  imgB1     ORDSYS.ORDVir; 
  imgB4     ORDSYS.ORDVir; 
  mycommand   VARCHAR2(400); 
begin 
  select col2 into imgB1 from ordimgtab  where col1 = 1; 
  select col2 into imgB4 from ordimgtab  where col1 = 4 for update; 
  command:= 'fileFormat=tiff compressionFormat = packbits 
  contentFormat = 8bitlut'; 
  imgB1.processcopy(mycommand,imgB4); 
  update ordimgtab set col2 = imgB4 where col1 = 4;
end;

setLocal Method

Format

setLocal;

Description

Sets the local attribute to indicate that the data is stored internally in a BLOB. When local is set, image methods look for image data in the source.localData attribute.

Parameter

None.

Usage

This method sets the local attribute to "1," meaning the data is stored locally in localData.

Pragma

None.

Exception

NULL_LOCAL_DATA -- raised if source.localData is NULL.

Example

Indicate that the image is stored locally:

DECLARE
    Image ORDSYS.ORDVir;
BEGIN
    SELECT large_photo INTO Image FROM emp WHERE ename = 'John Doe' FOR UPDATE;
 
    -- set local so we look for the image in the database
    Image.setLocal;
  
    UPDATE emp SET large_photo = Image WHERE ename = 'John Doe';
END;
/

setMimeType( ) Method

Format

setMimeType(mime IN VARCHAR2);

Description

Allows you to set the MIME media type of the stored image data.

Parameter

mime

The MIME media type.

Usage

You can override the automatic setting of MIME information by calling this method with a specified MIME value.

Visual Information Retrieval cannot automatically set the MIME type of foreign images. You must use this method to set the MIME type for foreign images.

Pragma

None.

Exception

None.

Example

Set the MIME media type for some stored image data:

DECLARE
    Image ORDSYS.ORDVir;
BEGIN
    SELECT large_photo INTO Image FROM emp FOR UPDATE
      WHERE ename = 'John Doe';
     -- set the image mime type
    Image.setMimeType('image/bmp');
END;

setProperties( ) Method

Format

setProperties;

Description

Reads the image data to get the values of the object attributes, then stores them in the appropriate attribute fields. The image data can be stored in the database in a BLOB, 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 image characteristics.

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

Parameter

None.

Usage

After you have copied, stored, or processed a native format image, call this method to set the current characteristics of the new content. Note that some methods already call setProperties( ) implicitly.

This procedure sets the following information about an image:

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

This method implicitly sets the update time and MIME type.

Pragma

None.

Exception

NULL_LOCAL_DATA -- raised if the source.localData attribute is NULL and the source.local attribute indicates the data is local.

Example

Select the image, and then set the attributes using the setProperties method.

imgB1 ORDSYS.ORDVir;
.
.
.
select col2 into imgB1 from ordimgtab where col1 = 1 for update;
imgB1.setProperties;
dbms_output.put_line('image width = '|| imgB1.getWidth );
dbms_output.put_line('image height = '|| imgB1.getHeight );
dbms_output.put_line('image size = '|| imgB1.getContentLength );
dbms_output.put_line('image file type = '|| imgB1.getFileFormat );
dbms_output.put_line('image type = '|| imgB1.getContentFormat );
dbms_output.put_line('image compression = '|| imgB1.getCompressionFormat )
dbms_output.put_line('image MIME type = '|| imgB1.getMimeType );

Example output:

image width = 360
image height = 490
image size = 59650
image file type = JFIF
image type = 24BITRGB
image compression = JPEG
image MIME type = image/jpeg

setProperties( ) Method for Foreign Images

Format

setProperties(description IN VARCHAR2);

Description

Allows you to write the characteristics of a foreign image (one not natively supported) into the appropriate attribute fields.

This method does not set the MIME type attribute. You must explicitly call the setMimeType( ) method to set the MIME type for foreign images.

Parameter

description

The image characteristics to set for the foreign image.

Usage

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

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 A, foreign (or headerless) images either do not contain information on how to interpret the bits in the file or Visual Information Retrieval does not understand the information. In this case, you must set the information explicitly.

You can set the following image characteristics for foreign images, as shown in Table 4-7.

Table 4-7 Image Characteristics for Headerless Files

Field	Data Type	Description
CompressionFormat	STRING	Value must be CCITG3, CCITG4, or NONE (default).
DataOffset	INTEGER	The offset allows the image to have a header that Visual Information Retrieval does not try to interpret. Set the offset to avoid any potential header. The value must be a positive integer less than the LOB length. Default is zero.
DefaultChannelSelection	INTEGER	For multiband images, specify either one (grayscale) or three integers indicating which channels to assign to red (first), green (second), and blue (third)
Height	INTEGER	Height of the image in pixels. Value must be a positive integer. There is no default, and a value must be specified.
Interleaving	STRING	Band layout within the image. Valid styles are: BIP (default): Band Interleaved by Pixel BIL: Band Interleaved by Line BSQ: Band Sequential
NumberOfBands	INTEGER	Value must be a positive integer less than 255 describing the number of color bands in the image. Default is 3.
PixelOrder	STRING	If NORMAL (default), the leftmost pixel appears first in the file. If REVERSE, the rightmost pixel appears first.
ScanlineOrder	STRING	If NORMAL (default), the top scanline appears first in the file. If INVERSE, then the bottom scanline appears first.
UserString	STRING	A 4-character descriptive string. If used, the string is stored in the fileFormat field, appended to the file format ("OTHER:"). Default is blank and fileFormat is set to "OTHER".
Width	INTEGER	Width of the image in pixels. Value must be a positive integer. There is no default, and a value must be specified.

Note that this method does not set the MIME type attribute. You must set the MIME type explicitly using the setMimeType( ) method.

The values supplied to setProperties( ) are written to the existing ORDVir data attributes. The fileFormat is set to 'OTHER' and includes the user string, if supplied, for example, 'OTHER: DICOM'.

Pragma

None.

Exception

NULL_PROPERTIES_DESCRIPTION -- raised if the description is NULL.

Example

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

DECLARE
    Image ORDSYS.ORDVIR;
BEGIN
    SELECT large_photo INTO Image FROM emp
           WHERE ename = 'John Doe' FOR UPDATE;
    -- set property attributes for the image data
    Image.setProperties('width=123 height=321 compressionFormat=NONE' ||
                        ' userString=DJM dataOffset=128' ||
                        ' scanlineOrder=INVERSE pixelOrder=REVERSE' ||
                        ' interleaving=BIL numberOfBands=1' ||
                        ' defaultChannelSelection=1');
    UPDATE emp SET large_photo = Image WHERE ename = 'John Doe';
END;
/

setSource( ) Method

Format

setSource(source_type IN VARCHAR2,

source_location IN VARCHAR2,

source_name IN VARCHAR2);

Description

Sets or alters information about the external source of the image data.

Parameters

source_type

Sets or alters the srcType attribute of the image data source.

source_location

Sets or alters the srcLocation attribute of the image data source.

source_name

Sets or alters the srcName attribute of the image data source.

Usage

Users can use this method to set the image data source to a new external file or URL.

Calling this method implicitly calls the setUpdateTime( ) method.

Pragma

None.

Exception

None.

Example

Set the source of the image data:

DECLARE
   Image ORDSYS.ORDVir;
   BEGIN
      SELECT large_photo INTO Image FROM emp FOR UPDATE
         WHERE ename = 'John Doe';
   -- set source information for the image
      Image.setSource('file', 'ORDVIRDIR', 'jdoe.gif');
      UPDATE emp SET large_photo = Image WHERE ename = 'John Doe';
   END;
/

setUpdateTime( ) Method

Format

setUpdateTime(current_time DATE);

Description

Sets the time when the image data was last updated.

Parameter

current_time

The updated time. Default is SYSDATE.

Usage

Use this method whenever you modify the image data. The process( ), processCopy( ), and setProperties( ) methods all call this method and setMimeType( ) implicitly.

Pragma

None.

Exception

None.

Example

Set the updated time of some image data:

DECLARE
   Image ORDSYS.ORDVir;
   BEGIN
      SELECT large_photo INTO Image FROM emp FOR UPDATE
         WHERE ename = 'John Doe';
   -- set image update time
      Image.setUpdateTime(SYSDATE);
      UPDATE emp SET large_photo = Image WHERE ename = 'John Doe';
   END;
/

4.3 Operators for Visual Information Retrieval

The Visual Information Retrieval operators are located in the ORDSYS schema.

Two operators are located in the ORDSYS.VIR package:

Analyze( ): Produces the signature of an image.
Convert( ): Converts the signature to either big or little endian byte order based on the architecture of the host machine. This operator can also convert a Viisage facial signature to a signature usable by the VIRScore( ) and VIRSimliar( ) operators.

For ease of use, you can create a local synonym for the ORDSYS.VIR package. Connect to your schema and issue the following command:

SVRMGR> CREATE SYNONYM VIR FOR ORDSYS.VIR;

After creating the synonym, you can use it in calls to the operators: VIR.Analyze( ), VIR.Convert( ), and so forth. Note that you must have the default CREATE SYNONYM privilege.

Two additional operators are schema level operators and do not reside within the package. These operators use the domain index, if it exists.

ORDSYS.VIRSimilar( ): Compares two signatures and determines whether or not the images match, based on the weights and threshold. Returns 1 if the computed distance measure (weighted average) is less than or equal to the threshold value, and otherwise returns 0.
ORDSYS.VIRScore( ): Returns the score value computed by the primary operator, VIRSimilar( ). VIRScore( ) is an ancillary operator to VIRSimilar( ).

Analyze( ) Operator

Format

Analyze(image IN OUT ORDVir);

Description

Analyzes an image, derives information relating to the visual attributes, and creates the image signature.

Parameter

image

The ORDVir object to be analyzed.

Usage

The Analyze( ) operator creates the image signature (or feature vector), which is necessary for any content-based retrieval. Whenever you are working with a new or changed image, you should call Analyze( ) to generate a signature and then use the setProperties( ) method to set the other image characteristics.

During analysis, images are temporarily scaled to a common size such that the signatures are based on a common reference.

Example

Create the signatures for all images in the stockphotos table:

DECLARE
   temp_image   ORDSYS.ORDVir;
   temp_id      INTEGER;
   cursor c1 is select id, image from stockphotos for update;
BEGIN
   OPEN c1;
   LOOP
      fetch c1 into temp_id, temp_image;
      EXIT WHEN c1%NOTFOUND;
  
 -- Generate signature and set the properties for the image.
      ORDSYS.VIR.Analyze(temp_image); 
      temp_image.setProperties;
      UPDATE stockphotos SET photo = temp_image WHERE photo_id = temp_id;
   END LOOP;
   CLOSE c1;
END;

Convert( ) Operator

Format

Convert(signature IN OUT RAW, operation IN VARCHAR2);

Description

Converts the image signature to a format usable by the host machine.

Parameters

signature

The signature of the image, as created by the Analyze( ) operator or by Viisage software. Data type is RAW(2000).

operation

The kind of processing done to the image signature. The following operations are available:

Operation Keyword Description

BYTEORDER

Converts the signature to the natural byte order of the host machine.

VIISAGE

Converts the signature from the format used for Viisage facial images to a signature usable by the VIRScore( ) and
VIRSimilar( ) operators.

Operation Keyword	Description
BYTEORDER	Converts the signature to the natural byte order of the host machine.
VIISAGE	Converts the signature from the format used for Viisage facial images to a signature usable by the VIRScore( ) and VIRSimilar( ) operators.

Usage

When the operation is BYTEORDER, the signature is converted to the format of the host machine regardless of its initial state.

This procedure is useful if the database is stored on a remote system, but you want to do your processing locally. If your host machine is from Sun Microsystems, Inc., the Convert( ) operator sets the signature to the big endian byte order. On an Intel Corporation machine, the operator converts the signature to the little endian byte order. Note that the images themselves are platform-independent; only the signatures need to be converted.

When the operator is VIISAGE, the signature is converted from the format used by Viisage Technology for facial image recognition to the format usable by this product for VIRScore and VIRSimilar operations. Note that you cannot use a domain index with facial signatures.

Example

Convert the signature of the image with photo_id=1 to the platform of the host system:

DECLARE
   myimage ORDSYS.ORDVir;
   myid      INTEGER;
BEGIN
   SELECT photo INTO myimage FROM stockphotos WHERE photo_id=1 FOR UPDATE;
   ORDSYS.VIR.Convert(myimage.signature,'BYTEORDER');
   UPDATE stockphotos SET photo=myimage WHERE photo_id=1;
END;

Convert the signatures of the image with photo_id=1 from the format used for Viisage facial image recognition software to a signature usable by the VIRScore( ) and
VIRSimilar( ) operators:

DECLARE
   myimage ORDSYS.ORDVir;
   myid    INTEGER;
BEGIN
   SELECT photo INTO myimage FROM stockphotos WHERE photo_id=1 FOR UPDATE;
   ORDSYS.VIR.Convert(myimage.signature,'VIISAGE');
   UPDATE stockphotos SET photo=myimage WHERE photo_id=1;
END;

VIRScore( ) Operator

Format

VIRScore(referencetoSimilar IN NUMBER);

Description

Compares the signatures of two images and returns a number representing the weighted sum of the distances for the visual attributes. VIRScore( ) is an ancillary operator, used only in conjunction with the primary operator, VIRSimilar( ).

Parameter

referencetoSimilar

The corresponding invocation of VIRSimilar. If there are multiple invocations of VIRSimilar in the same query, this parameter is used to maintain reference. Data type is NUMBER.

Returns

This function returns a FLOAT value between 0.0 and 100.0, where 0.0 is identical and 100.0 is totally different.

Usage

Before the VIRScore( ) operator can be used, the image signatures must be created with the VIR.Analyze( ) operator. Also, if you want the comparison to use the domain index, the index of type ORDVIRIDX must have already been created. See Section 2.4 for information on creating and using the index, and Section 3.7 for additional performance tips.

The VIRScore( ) operator can be useful when an application wants to make finer distinctions about matching than the simple "Yes" or "No" returned by
VIRSimilar( ). For example, using the number for weighted sum returned by VIRScore( ), the application might assign each image being compared to one of several categories, such as Definite Matches, Probable Matches, Possible Matches, and Nonmatches. The VIRScore( ) operator can also be useful if the application needs to perform special processing based on the degree of similarity between images.

The VIRScore( ) operator also works with old signatures stored using the deprecated ORDVirB and ORDVirF object types. However, Oracle recommends that you migrate to the new object type using the migrateFromORDVirF( ) and
migrateFromORDVirB( ) methods.

Example

Find the weighted sum of the distances between a test image and the other images in the stockphotos table, using a threshold of 50 and the following weights for the visual attributes:

Global color: 0.2
Local color: 0.2
Texture: 0.1
Structure: 0.5

This example assumes that the signatures have already been created using the Analyze( ) operator and they are stored in the database. Notice that both VIRScore and VIRSimilar are using 123 as the reference number in this example.

DECLARE
   img_score       NUMBER;
   i               INTEGER;
   query_signature RAW(2000);

BEGIN
   SELECT photo_id, ORDSYS.VIRScore(123) INTO i, img_score FROM T WHERE
     ORDSYS.VIRSimilar(img.signature, query_signature, 
               'globalcolor="0.2" localcolor="0.2" 

                 texture="0.1" structure="0.5"', 50, 123) = 1   
END;

The following shows possible results from this example. The first image has the lowest score, and therefore is the best match of the test image. Changing the weights used in the scoring would lead to different results.

PHOTO_ID   SCORE 
---------- ------------
         2    3.79988   
         4    47.8139   
  2 rows selected.

VIRSimilar( ) Operator

Format

VIRSimilar(signature IN RAW,

querysignature IN RAW,

weightstring IN VARCHAR2,

threshold IN FLOAT

[ ,referencetoScore IN NUMBER] );

where weightstring is: 'globalcolor="val" localcolor="val" texture="val" structure="val"'

or: 'facial=1'

Description

Determines whether or not two images match. Specifically, the operator compares the signatures of two images, computes a weighted sum of the distance between the two images using user-supplied weight values for the visual attributes, compares the weighted sum with the threshold value, and returns the integer value 1 if the weighted sum is less than or equal to the threshold value. Otherwise, the operator returns 0.

Parameters

signature

The signature of the image to which you are comparing the test image. Data type is RAW(2000). To use the domain index for the comparison, this first parameter must be the signature column on which the domain index has been created. Otherwise, Oracle8i uses the non-indexed implementation of query evaluation.

querysignature

The signature of the query or test image. Data type is RAW(2000).

weightstring

A list of weights to apply to each visual attribute. Data type is VARCHAR2. The following attributes can be specified, with a value of 0.0 specifying no importance and a value of 1.0 specifying highest importance. You must specify a value greater than zero for at least one of the attributes. The facial attribute is not compatible with any of the other attributes.

Attribute Description

globalcolor

The weight value (0.0 to 1.0) assigned to the global color visual attribute. Data type is number. Default is 0.0.

localcolor

The weight value (0.0 to 1.0) assigned to the local color visual attribute. Data type is number. Default is 0.0.

texture

The weight value (0.0 to 1.0) assigned to the texture visual attribute. Data type is number. Default is 0.0.

structure

The weight value (0.0 to 1.0) assigned to the structure visual attribute. Data type is number. Default is 0.0.

facial

A value of 1 indicates that this is a facial signature.
Data type is number. Default is 0.0

Attribute	Description
globalcolor	The weight value (0.0 to 1.0) assigned to the global color visual attribute. Data type is number. Default is 0.0.
localcolor	The weight value (0.0 to 1.0) assigned to the local color visual attribute. Data type is number. Default is 0.0.
texture	The weight value (0.0 to 1.0) assigned to the texture visual attribute. Data type is number. Default is 0.0.
structure	The weight value (0.0 to 1.0) assigned to the structure visual attribute. Data type is number. Default is 0.0.
facial	A value of 1 indicates that this is a facial signature. Data type is number. Default is 0.0

Note:
When specifying parameter values that include floating-point numbers, you should use double quotation marks (" ") around the value. If you do not, this may result in incorrect values being passed and you will get incorrect results.

threshold

The threshold value with which the weighted sum of the distances is to be compared. If the weighted sum is less than or equal to the threshold value, the images are considered to match. This range of this parameter is from 0.0 to 100.0.

referencetoScore

An optional parameter used when ancillary data (score of similarity) is required elsewhere in the query. Set this parameter to the same value here as used in the VIRScore operator. Data type is NUMBER.

Returns

Returns an integer value of 0 (not similar) or 1 (match).

Usage

Before the VIRSimilar( ) operator can be used, the image signatures must be created with the Analyze( ) operator. Also, to use the domain index, the index of type ORDVIRIDX must have already been created. See Section 2.4 for information on creating and using the index and Section 3.7 for additional performance tips.

The VIRSimilar( ) operator is useful when the application needs a simple "Yes" or "No" for whether or not two images match. The VIRScore( ) operator is useful when an application wants to make finer distinctions about matching or to perform special processing based on the degree of similarity between images.

The weights supplied for the four visual attributes are normalized prior to processing such that they add up to 100 percent. To avoid confusion and meaningless results, you should develop a habit of always using the same scale, whether 0 to 100 or 0.0 to 1.0.

You must specify at least one of the four image attributes or the facial attribute in the weightstring. Note that facial signatures cannot be indexed.

The VIRSimilar( ) operator also works with old signatures stored using the deprecated ORDVirB and ORDVirF object types. However, Oracle recommends that you migrate to the new object type using the migrateFromORDVirF( ) and
migrateFromORDVirB( ) methods.

Example

Using the VIR index, find all images similar to the query image using a threshold value of 25 and the following weights for the visual attributes:

Global color: 20
Local color: 20
Texture: 10
Structure: 50

This example assumes you have already used the Analyze( ) operator to generate a signature for the query image. If an index exists on the signature column, it will be used automatically.

DECLARE
   t_img ORDSYS.ORDVIR;
   i     INTEGER;
   query_signature RAW(2000);
BEGIN
   SELECT id, img INTO i, t_img FROM T WHERE 
        ORDSYS.VIRSimilar(t_img.signature, query_signature, 
                 'globalcolor="20"  localcolor="20" 

                    texture="10" structure="50"', 25) = 1;
END;

4 Visual Information Retrieval Reference

4.1 Object Type

ORDVir Object Type

Table 4-1 ORDImage Object Type

Table 4-2 ORDSource Object Type

Table 4-3 srcLocation Values

Table 4-4 Valid srcName Values

4.2 Methods for Image Manipulation

analyze( ) Method

Format

Description

Parameter

Usage

Pragmas

Exceptions

Example

checkProperties( ) Method

Format

Description

Parameter

Usage

Pragma

Exception

Example

clearLocal( ) Method

Format

Description

Parameter

Usage

Pragma

Exception

Example

copy( ) Method

Format

Description

Parameter

Usage

Pragma

Exception

Example

deleteContent( ) Method

Format

Description

Parameter

Usage

Pragma

Exception

Example

export( ) Method

Format

Description

Parameters

Usage

Pragma

Exception

Example

getBFILE Method

Format

Description

Parameter

Usage

Pragma

Exceptions

Example

getCompressionFormat Method

Format

Description

Parameter

Usage

Pragma

Exception

Example

getContent Method

Format

Description

Parameter

Usage

Pragma

Exception

Example

4
Visual Information Retrieval Reference