2
OrdVir Class Library

The Oracle8i Visual Information Retrieval Java Client class library contains information about the OrdVir object type:

• Object type -- see Section 2.1

• Methods -- see Section 2.2

The OrdVir object type and class library are based on the OrdImage object type, which are, in turn, based on the OrdMultiMedia object type. OrdMultiMedia contains the OrdSource object type. This guide describes only information unique to the Visual Information Retrieval product. Any inherited methods or other characteristics are discussed in their own documentation.

The Oracle8i interMedia Audio, Image, and Video Java Client User's Guide and Reference describes the OrdImage, OrdMultiMedia, and OrdSource object types.

2.1 OrdVir Object Type

The OrdVir object type supports the storage and management of image data.

This object type is defined by Oracle8i Visual Information Retrieval as follows:

package oracle.ord.media;

import java.sql.*;

import java.io.*;

import oracle.jdbc.driver.*;

import oracle.sql.*;

import oracle.ord.media.*;



public class OrdVir extends OrdImage {



// OrdVir class attribute

byte[] signature;



// OrdVir Default Constructor

public OrdVir() {}

 

public OrdVir(Connection connection)

{  }



int bindInSQLParams(int start, OracleCallableStatement stmt)

throws SQLException

{  }



String defineSQLResults(String var)

{  }



int declareSQLResults(int start, OracleCallableStatement stmt)

throws SQLException

{  }



String setSQLParams(String var)

{  }



int getSQLResults(int start, OracleCallableStatement stmt)

throws SQLException

{  }



String getMediaType()

{  }



String getFormatStr()

{  }



String getUpdStr()

{  }



String getSourceStr()

{  }



String getContentLengthAPI()

{  }



public void refresh(boolean forUpdate) throws SQLException

{  }



public void flush() throws SQLException

  {  }



public void analyze() throws SQLException

{  }



public int similar(byte [] signature2, String attrWeights, float threshold) 

throws SQLException

{  }



public float score(byte [] signature2, String attrWeights) 

throws SQLException

{  }



public int convert(String operations) 

throws SQLException

{  }



// Vir Operators:

public static int similar(byte [] signature1, byte [] signature2,

                          String attrWeights, float threshold,

                          Connection connection)

throws SQLException

{  }



public static float score(byte [] signature1, byte [] signature2,

                          String attrWeights, Connection connection)

throws SQLException

{  }



public static int convert(byte [] signature, String operations,


                            Connection connection)

throws SQLException

{  }

  

// Accessor functions for local OrdVir attributes

public byte[] getSignature() throws SQLException

{  }



public void setSignature(byte[] value) throws SQLException

{  }



}

Where the base image attributes included from OrdImage.java are defined as follows:

• height: contains the height of the image in pixels.

• width: contains the width of the image in pixels.

• contentLength: contains the size of the image data in bytes.

• contentFormat: describes the type of image (for example, monochrome or 8-bit grayscale).

• compressionFormat: describes the type of compression used on the image.

Three additional attributes of special note are defined in the included files, oracle.ord.media.*:

• source: contains the image in the ORDSource object.

• fileFormat: describes the file type or format in which the image data is stored (TIFF, JIFF, and so forth).

• mimeType: describes the MIME type of the image.

See Oracle8i interMedia Audio, Image, and Video Java Client User's Guide and Reference for information about the oracle.ord.media.* files and the OrdMultiMedia abstract class.

2.2 Methods

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

The OrdVir methods are described in the following groupings:

OrdVir Methods for Visual Information Retrieval

• public void analyze( ): generates a signature based on the visual attributes of an image.

• public int convert( ): converts the signature to the format used on the host system.

• public static convert( ): converts the signature to the format used on the host system, without requiring an instance of an OrdVir object.

• public float score( ): compares the signatures of two images, returning a value between 0.0 (perfect match) and 100 (totally opposite).

• public static float score( ): compares the signatures of two images, returning a value between 0.0 and 100, without requiring an instance of an OrdVir object.

• public int similar( ): compares the current image to a provided comparison signature and determines if they are alike within a specified threshold.

• public static int similar( ): compares the signatures of two images and determines if they are alike within a specified threshold, without requiring an instance of an OrdVir object.

• public getSignature( ): reads the signature of the OrdVir object stored on the client side.

• public setSignature( ): sets the signature field of the OrdVir object.

OrdVir Methods for Communication Between the Client and Server

• public void flush( ): sends information from the client-side OrdVir object to the server-side OrdVir object.

• public void refresh( ): sends information from the server-side OrdVir object to the client-side OrdVir object with or without locking the database row.

2.2.1 Inherited Methods

The following methods are inherited through the OrdMultiMedia package. See Oracle8i interMedia Audio, Image, and Video Java Client User's Guide and Reference for further information on these methods.

OrdVir Methods Associated with Image Attributes

• public int getHeight( ): gets the image height from the client cache.

• public int getWidth( ): gets the image width from the client cache.

• public int getContentLength( ): gets the length of the content from the client cache.

• public String getContentFormat( ): gets the content format from the client cache.

• public String getCompressionFormat( ): gets the compression format from the client cache.

• public String getAllAttributesAsString( ): gets all the image attributes and returns them as a string.

OrdVir Methods Associated with the Source Attribute

• public BLOB getContent( ): gets the content BLOB that holds the image data.

• public BFILE getBFILE( ): gets the content BFILE that holds the image data.

• public void deleteContent( ): deletes the image data from the LOB on the server-side OrdVir object.

• public String getSource( ): returns information about the data source of the OrdVir object.

OrdVir Methods Associated with Properties Set and Check Operations

• public void setProperties( ): sets the database object attributes according to the values stored in the content data header.

• public void setProperties(String): sets the database object attributes according to the values provided in the parameter.

• public boolean checkProperties( ): checks that the values of the database OrdVir object are consistent with the values stored in the content header.

OrdVir Methods Associated with Copy Operations

• public void copy( ): copies the image data from the client-side OrdVir object source to a server-side OrdVir object.

OrdVir Methods Associated with Processing Image Data

• public void process( ): executes a given command on the server side OrdVir object and updates that object.

• public void processCopy( ): copies image data to a destination OrdVir object and modifies the copy according to the specified command.

OrdVir Methods Associated with the Media Type

• protected String getMediaType( ): returns the media type information.

OrdVir Methods Associated with Locking

• protected void setLock( ): sets the lock on the OrdVir object.

OrdVir Methods Associated with the SQL Type

• protected int bindInSQLParams( ): binds the local values of the OrdVir object attributes to the parameters of the given statement.

• protected String defineSQLResults( ): constructs a SQL statement to transfer data from a fetched object to the local object attributes.

• protected int declareSQLResults( ): binds the output parameters in a statement produced by the defineSQLResults( ) method to the attributes of the OrdVir object.

• protected String setSQLParams( ): constructs a SQL statement to set the attributes of a database OrdVir object to the values specified by the binding parameters.

• protected int getSQLResults( ): updates the attributes of the client-side OrdVir object with values from the database object fetched by the executing statement.

OrdVir Methods Associated with Generating SQL Queries

• protected String getFormatStr( ): returns the format string.

• protected String getUpdStr( ): returns the SQL string that is used to update an OrdVir instance.

• protected String getSourceStr( ): returns the source string.

• protected String getContentLengthAPI( ): returns the server-side contentLength API for this class.

2.2.2 OrdVir Methods for Visual Information Retrieval

This section presents reference information on the OrdVir methods associated directly with visual information retrieval.

The methods described in this chapter show examples based on the instantiation of an OrdVir object. For the examples in this section, please consult the following Java code:

import oracle.ord.media.mediaClass;



public class clientProgram {

     public static void main(String[] args){

          The code in the examples should be placed here.

     }

}

In each example, the parameter connection is a connection to an Oracle8i database.

---

analyze Method

Format

public void analyze( ) 

throws SQLException

Scope

public

Description

Sets the value for both the server- and client-side signature attributes based on the image data.

Parameter

None.

Returns

None.

Exception

java.sql.SQLException

Usage

try{

     OrdVir  imageObj = new OrdVir (connection);

     .

     .

     .

     imageObj.analyze();

   }

catch(SQLException e){

     .

     .

     .

 }

---

convert Method

Format

public int convert(string operations) 

throws SQLException

Scope

public

Description

Converts the server-side signature data to a format usable on the database server (host) machine.

Parameter

operations

The type 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 image recognition to a signature usable by the score( ) and similar( ) operators.

Returns

None.

Exception

java.sql.SQLException

Usage

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

This method is useful if your signature data was created on a system with a different byte order than the system to which you are currently bound (the system where you intend to perform similar( ) and score( ) operations). 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 system-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 score and similar operations.

try{

     OrdVir  imageObj = new OrdVir (connection);

     .

     .

     .

     ImageObj.convert("BYTEORDER");

   }

catch(SQLException e){

     .

     .

     .

     }

---

convert Method (static)

Format

public static int convert(byte []    signature,

                          string     operations,

                          connection connection ) 

throws SQLException

Scope

public

Description

Converts the client-side signature data to a format usable on the host machine. This is a static function not within the context of a particular image object.

Unlike the non-static version of this function, the static function can directly operate on signature data without any instance of an OrdVir object.

Parameters

signature

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

operation

The type 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 image recognition to a signature usable by the score( ) and similar( ) operators.

connection

An object representing a connection to the server.

Returns

None.

Exception

java.sql.SQLException

Usage

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

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 system-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 score( ) and similar( ) operations.

try{

     byte[] imgSignature = new byte[2000];

     .

     .

     .

     OrdVir.convert(imgSignature,"BYTEORDER",connection);

   }

catch(SQLException e){

     .

     .

     .

     }

---

score Method

Format

public float score(byte [] cmpSignature,

                   string  attrWeights) 

throws SQLException

Scope

public

Description

Compares the client-side image signature of the current OrdVir object to the cmpSignature signature using the weights provided in attrWeights.

Parameters

cmpSignature

The signature of the comparison image.

attrWeights

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

Returns

A floating-point number between 0.0 and 100.0, representing the weighted sum of the distances between the visual attributes.

Exception

java.sql.SQLException

Usage

The connection string of the two image objects must be the same.

try{

     byte signature2 = new byte[2000];

     .

     .

     .

     float score= OrdVir.score(signature2, "localcolor=1.0",connection);

   }

catch(SQLException e){

     .

     .

     .   }

---

score Method (static)

Format

public static float score(byte []    signature1,

                          byte []    signature2,

                          string     attrWeights

                          connection connection) 

throws SQLException

Scope

public

Description

Compares two client-side image signatures using the weights provided in
attrWeights.

Unlike the non-static version of this function, the static function can directly operate on signature data without an instance of an OrdVir object.

Parameters

signature1, signature2

The signatures of the two images.

attrWeights

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

connection

An object representing a connection to the server.

Returns

A floating-point number between 0.0 and 100.0, representing the weighted sum of the distances between the visual attributes.

Exception

java.sql.SQLException

Usage

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.

The connection string of the two image objects must be the same.

try{

     byte signature1 = new byte[2000];

     byte signature2 = new byte[2000];

     .

     .

     .

     float score= OrdVir.score(signature1,signature2,


         "localcolor=1.0",connection);

   }



catch(SQLException e){

     .

     .

     .

     }

---

similar Method

Format

public int similar( byte [] cmpSignature, 

                    string  attrWeights, 

                    float   threshold) 

throws SQLException

Scope

public

Description

Compares the current client-side image to a signature provided in cmpSignature, using the weights provided in attrWeights.

Parameters

cmpSsignature

The signature of the image stored in cmpImg.

attrWeights

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

connection

An object representing a connection to the server.

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. The range of this parameter is from 0.0 to 100.0.

Returns

The result of the comparison. If the result is less than or equal to the threshold, this method returns 1. Otherwise, this method returns 0.

Exception

java.sql.SQLException

Usage

try{

     OrdVir  imageObj = new OrdVir (connection);

     byte    signature2 = new byte[2000];

     .

     .

     .

     int result = imageObj.similar(signature2, "localcolor=1.0",connection, 10);

   }

catch(SQLException e){

     .

     .

     .

     }

---

similar Method (static)

Format

public static int similar( byte []    signature1,

                           byte []    signature2, 

                           string     attrWeights, 

                           float      threshold

                           connection connection) 

throws SQLException

Scope

public

Description

Compares the two client-side image signatures using the weights provided in attrWeights.

Unlike the non-static version of this function, the static function can directly operate on signature data without an instance of an OrdVir object.

Parameters

signature1, signature2

The signatures of the images to be compared.

attrWeights

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

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. The range of this parameter is from 0.0 to 100.0.

connection

An object representing a connection to the server.

Returns

The result of the comparison. If the result is less than or equal to the threshold, this method returns 1. Otherwise, this method returns 0.

Exception

java.sql.SQLException

Usage

try{

     OrdVir  imageObj = new OrdVir (connection);

     byte    signature1 = new byte[2000];

     byte    signature2 = new byte[2000];

     .

     .

     .

     int result = imageObj.similar(signature1, signature2, 


          "localcolor=1.0",connection, 10);

   }

catch(SQLException e){

     .

     .

     .

     }

---

getSignature Method

Format

public byte [] getSignature( ) 

throws SQLException

Scope

public

Description

Reads the signature of the OrdVir object stored on the client side.

Parameter

None.

Returns

Returns the signature of the OrdVir object stored on the client side .

Exception

java.sql.SQLException

Usage

try{

     OrdVir  imageObj = new OrdVir (connection);  

     .

     .

     .

     byte[] imgSignature = imageObj.getSignature();

   }

catch(SQLException e){

     .

     .

     .

     }

---

setSignature Method

Format

public void setSignature(byte [] value) 

throws SQLException

Scope

public

Description

Sets the signature field of the client OrdVir object. The signature value must be generated by either the analyze( ) method or Viisage software.

Parameter

None.

Returns

None.

Exception

java.sql.SQLException

Usage

try{

     OrdVir  imageObj = new OrdVir (connection);

     byte[]  imgSignature = new byte[2000];

     .

     .

     .

     imageObj.setSignature(imgSignature);

   }

catch(SQLException e){

     .

     .

     .

     }

2.2.3 OrdVir Methods for Communication Between the Client and Server

This section presents reference information on the OrdVir methods associated with the communication between the client and server.

The methods described in this section show examples based on the instantiation of an OrdVir object. For the examples in this section, please consult the following Java code:

import oracle.ord.media.mediaClass;



public class clientProgram {

     public static void main(String[] args){

          The code in the examples should be placed here.

     }

}

In each example, the parameter connection is a connection to an Oracle8i database.

---

flush( ) Method

Format

public void flush()

throws SQLException

Scope

public

Description

Sends information from the client-side OrdVir object to the server-side OrdVir object.

Parameter

None.

Returns

None.

Exception

java.sql.SQLException

Usage

try{

     OrdVir imageObj = new OrdVir(connection);

     .

     .

     .

     imageObj.flush();

}

catch(SQLException e){

     .

     .

     .

}

---

refresh( ) Method

Format

public void refresh(boolean forUpdate)

throws SQLException

Scope

public

Description

Sends information from the server-side OrdVir object to the client-side OrdVir object with or without locking the database row.

Parameter

forUpdate

Indicates whether or not the option is selected to be updated. It is set to true if it is selected to be updated; false otherwise.

Returns

None.

Exception

java.sql.SQLException

Usage

try{

     OrdVir imageObj = new OrdVir(connection);

     .

     .

     .

     imageObj.refresh(false);

}

catch(SQLException e){

     .

     .

     .

}

where:

• false indicates the option was not refreshed for the update.

---