Release 8.1.7
Part Number A85335-01
 Library |
 Product |
 Contents |
 Index |
| Oracle Visual Information Retrieval User's Guide and Reference Release 8.1.7 Part Number A85335-01 |
|
Since release 8.1.5, the ORDVirB and ORDVirF object types have been replaced by ORDVir. These object types will be supported in release 8.1.7, but will no longer exist in the next release (after release 8.1.7).
The new ORDVir type is based on the ORDImage type in the Oracle interMedia product. The old interface and object types have been replaced by the interface described in Chapter 4.
This appendix describes the old interface, for those users who still need to access legacy data. Please see the migration functions (migrateFromORDVirB( ) and migrateFromORDVirF( ) methods) in Chapter 4 for information on moving to the new object type.
The old interface will be removed in the next release after release 8.1.7.
The obsolete Visual Information Retrieval library consists of:
The examples in this chapter assume that the stockphotos table 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.ORDVIRB);
When you are storing or copying images, you must first create an empty BLOB in the table. Use the empty_blob( ) function, which has the following format:
ORDSYS.ORDVIRB(empty_blob(),NULL,NULL,NULL,NULL,NULL,NULL,NULL)
The obsolete Visual Information Retrieval object types are as follows:
This section presents reference information on the object types.
For more information on BLOBs and BFILEs, see Oracle8i Application Developers Guide: Large Objects (LOBs).
The ORDVirB object type supports storage and retrieval of image data in a BLOB within an Oracle database. This object type is defined as follows:
CREATE TYPE ORDVIRB ( -- TYPE ATTRIBUTES content BLOB, height INTEGER, width INTEGER, contentLength INTEGER, fileFormat VARCHAR2(64), contentFormat VARCHAR2(64), compressionFormat VARCHAR2(64), signature RAW(2000), -- METHOD DECLARATION MEMBER PROCEDURE copyContent(dest IN OUT NOCOPY BLOB), MEMBER PROCEDURE setProperties(SELF IN OUT ORDVIRB), MEMBER PROCEDURE setProperties(SELF IN OUT ORDVIRB, description IN VARCHAR2), MEMBER PROCEDURE process (SELF IN OUT ORDVIRB, command IN VARCHAR2) MEMBER PROCEDURE processCopy(command IN VARCHAR2, dest IN OUT NOCOPY BLOB), MEMBER FUNCTION getMimeType RETURN VARCHAR2, MEMBER FUNCTION getContent RETURN BLOB, MEMBER FUNCTION getContentLength RETURN INTEGER, MEMBER PROCEDURE deleteContent (SELF IN OUT ORDVirB), MEMBER PROCEDURE Analyze (SELF IN OUT ORDVIRB), MEMBER FUNCTION getHeight RETURN INTEGER, MEMBER FUNCTION getWidth RETURN INTEGER, MEMBER FUNCTION getFileFormat RETURN VARCHAR2, MEMBER FUNCTION getContentFormat RETURN VARCHAR2, MEMBER FUNCTION getCompressionFormat RETURN VARCHAR2, MEMBER FUNCTION getSignature RETURN RAW, MEMBER FUNCTION checkProperties RETURN BOOLEAN );
Where the attributes are:
In PL/SQL, data is moved with the DBMS LOB package. From the client, data is moved using OCI LOB calls. The ORDVirB object type does not supply routines for moving data piece by piece.
The ORDVirF object type supports storage and retrieval of image data in external files (BFILEs, which are not stored in the database). BFILEs are assumed to be read-only, and this is reflected in the member procedures. This object type is defined as follows:
CREATE TYPE ORDVIRF ( -- TYPE ATTRIBUTES content BFILE, height INTEGER, width INTEGER, contentLength INTEGER, fileFormat VARCHAR2(64), contentFormat VARCHAR2(64), compressionFormat VARCHAR2(64), signature RAW(2000), -- METHOD DECLARATION MEMBER PROCEDURE copyContent(dest IN OUT NOCOPY BLOB), MEMBER PROCEDURE setProperties(SELF IN OUT ORDVIRF), MEMBER PROCEDURE setProperties(SELF IN OUT ORDVIRF, description IN VARCHAR2), MEMBER PROCEDURE processCopy(command IN VARCHAR2, dest IN OUT NOCOPY BLOB), MEMBER FUNCTION getMimeType RETURN VARCHAR2, MEMBER FUNCTION getContent RETURN BFILE, MEMBER FUNCTION getContentLength RETURN INTEGER, MEMBER PROCEDURE Analyze (SELF IN OUT ORDVIRF), MEMBER FUNCTION getHeight RETURN INTEGER, MEMBER FUNCTION getWidth RETURN INTEGER, MEMBER FUNCTION getFileFormat RETURN VARCHAR2, MEMBER FUNCTION getContentFormat RETURN VARCHAR2, MEMBER FUNCTION getCompressionFormat RETURN VARCHAR2, MEMBER FUNCTION getSignature RETURN RAW, MEMBER FUNCTION checkProperties RETURN BOOLEAN );
Where the attributes are:
This section presents reference information on the methods used for image manipulation.
Visual Information Retrieval methods are as follows:
For more information on object types and methods, see Oracle8i Concepts.
Analyze( );
Analyzes an image BLOB or BFILE, derives information relating to the visual attributes (including a score for each), and creates the image signature.
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 and then compare the signatures using the Score( ) and Similar( ) operators.
The Analyze( ) method is functionally equivalent to the Analyze( ) operator. You must use the Analyze( ) method when working with foreign images.
Create the signatures for all images in the stockphotos table.
DECLARE temp_image ORDSYS.ORDVirB; 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 RETURN BOOLEAN;
Verifies that the properties stored in attributes of the image object match the properties of the image stored in the BLOB or BFILE. This method should not be used for foreign images.
None.
BOOLEAN
Use this method to verify that the image attributes match the actual image.
Check the image attributes.
virb1 ORDSYS.ORDVirB; properties_match BOOLEAN; ... properties_match := virb1.checkProperties;
copyContent (dest IN OUT NOCOPY BLOB);
Copies an image without changing it.
The destination of the new image.
This method copies the image data into the supplied BLOB.
Create a copy of the image in image1 into myblob.
image1.copyContent(myblob);
deleteContent;
Deletes the contents of the image.
None.
Use this method to delete the contents of the image BLOB. This procedure works only with BLOBs, not BFILEs.
Delete the content of an image.
virb1 ORDSYS.ORDVirB; ... virb1.deleteContent;
getCompressionFormat RETURN VARCHAR2;
Returns the compression type of an image. This method does not actually read the LOB; it is a simple access method that returns the value of the compressionFormat attribute.
None.
VARCHAR2
Use this method rather than accessing the compressionFormat attribute directly to protect yourself from potential changes to the internal representation of the ORDVirB or ORDVirF object.
Get the compression type of an image.
virb1 ORDSYS.ORDVirB; compressionFormat VARCHAR2(64); ... compressionFormat := virb1.getCompressionFormat;
getContent RETURN BLOB;
getContent RETURN BFILE;
Returns the LOB locator of the BLOB or BFILE containing the image. This is a simple access method that returns the value of the content attribute.
None.
BLOB or BFILE, depending on how the image is stored.
Use this method rather than accessing the content attribute directly to protect yourself from potential changes to the internal representation of the ORDVirB or ORDVirF object.
Get the LOB locator for an image.
virb1 ORDSYS.ORDVirB; content BLOB; ... content := virb1.getContent;
getContentFormat RETURN VARCHAR2;
Returns the type of an image (such as monochrome or 8-bit grayscale). This method does not actually read the LOB; it is a simple access method that returns the value of the contentFormat attribute.
None.
VARCHAR2
Use this method rather than accessing the contentFormat attribute directly to protect yourself from potential changes to the internal representation of the ORDVirB or ORDVirF object.
Get the type of an image.
virb1 ORDSYS.ORDVirB; contentFormat VARCHAR2(64); ... contentFormat := virb1.getContentFormat;
getContentLength RETURN INTEGER;
Returns the size of the on-disk image in bytes. This method does not actually read the LOB; it is a simple access method that returns the value of the contentLength attribute.
None.
INTEGER
Use this method rather than accessing the contentLength attribute directly to protect yourself from potential changes to the internal representation of the ORDVirB or ORDVirF object.
Get the content length of an image.
virb1 ORDSYS.ORDVirB; contentLength INTEGER; ... contentLength := virb1.getContentLength;
getFileFormat RETURN VARCHAR2
Returns the file type of an image (such as TIFF or JFIF). This method does not actually read the LOB; it is a simple access method that returns the value of the fileFormat attribute.
None.
VARCHAR2
Use this method rather than accessing the fileFormat attribute directly to protect yourself from potential changes to the internal representation of the ORDVirB or ORDVirF object.
Get the file type of an image.
virb1 ORDSYS.ORDVirB; fileFormat VARCHAR2(64); ... fileFormat := virb1.getFileFormat;
getHeight RETURN INTEGER;
Returns the height of an image in pixels. This method does not actually read the LOB; it is a simple access method that returns the value of the height attribute.
None.
INTEGER
Use this method rather than accessing the height attribute directly to protect yourself from potential changes to the internal representation of the ORDVirB or ORDVirF object.
Get the height of an image.
virb1 ORDSYS.ORDVirB; height INTEGER; ... height := virb1.getHeight;
getMimeType RETURN VARCHAR2;
Returns the Multipurpose Internet Mail Extension (MIME) type of an image (such as image/jpeg or image/tiff). This method returns the MIME type based on the
fileFormat of the image. See Appendix A for the MIME type associated with each supported file format.
None.
VARCHAR2
Use this method to obtain the MIME type of the image. The MIME type is required by Web browsers along with the image content. It tells the Web browser how to interpret the image content.
Get the MIME type of an image.
virb1 ORDSYS.ORDVirB; mimeType VARCHAR2(64); ... mimeType := virb1.getMimeType;
getSignature RETURN RAW;
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.
None.
RAW
Use this method rather than accessing the signature attribute directly to protect yourself from potential changes to the internal representation of the ORDVirB or ORDVirF object.
Get the signature of an image.
virb1 ORDSYS.ORDVirB; signature RAW(2000); ... signature := virb1.getSignature;
getWidth RETURN INTEGER;
Returns the width of an image in pixels. This method does not actually read the LOB; it is a simple access method that returns the value of the width attribute.
None.
INTEGER
Use this method rather than accessing the width attribute directly to protect yourself from potential changes to the internal representation of the ORDVirB or
ORDVirF object.
Get the width of an image.
virb1 ORDSYS.ORDVirB; width INTEGER; ... width := virb1.getWidth;
process (command IN VARCHAR2);
Performs one or more image processing techniques on a BLOB, writing the image back on to itself.
A list of image processing changes to make for the image.
You can change one or more of the image attributes shown in Table E-1. Table E-2 shows additional changes can be made to raw pixel and foreign images. See Appendix A for information on the supported format combinations. See Appendix C for a more complete description of each operator.
Example 1: Change the file format of image1 to GIF.
image1.process('fileFormat=GIFF');
Example 2: Change image1 to use lower quality JPEG compression and double the size of the image, preserving the aspect ratio.
image1.process('compressionFormat=JPEG, compressionQuality=LOWCOMP, scale="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 result in an error.
Example 3: The maxScale and fixedScale parameters are especially useful for creating thumbnail images from various-sized originals. The following line of code creates a 32-by-32 pixel thumbnail image, preserving the original aspect ratio:
image1.process('maxScale=32 32');
processCopy (command IN VARCHAR2,
dest IN OUT NOCOPY BLOB);
Copies an image BLOB or BFILE to another BLOB.
A list of image processing changes to make for the image in the new copy.
The destination of the new image.
When using temporary LOBs, you cannot specify the same temporary LOB as both the source and the destination.
Copy an image, changing the file format, compression format, and data format in the destination image.
create or replace procedure copyit is virB1 ORDSYS.ORDVIRF; virB4 ORDSYS.ORDVIRB; mycommand VARCHAR2(400); begin select col2 into virB1 from ordvirtab where col1 = 1; select col2 into virB4 from ordvirtab where col1 = 4 for update; mycommand:= 'fileFormat=tiff compressionFormat = packbits contentFormat = 8bitlut'; virB1.processcopy(mycommand,virB4.content); virB4.setproperties; update ordvirtab set col2 = virB4 where col1 = 4; end;
setProperties( );
Writes the characteristics of an image (BLOB or BFILE) into the appropriate attribute fields.
None.
After you copied, stored, or processed an image, call this method to set the characteristics of the new image content.
This method sets the following information about an image:
Note that the setProperties( ) method does not create the signature required for content-based retrieval. See the Analyze( ) operator in Section E.3 for details.
Select the image type, and then set the attributes using the setProperties procedure.
virB1 ORDSYS.ORDVIRB; . . . select col2 into virB1 from ordvirtab where col1 = 1 for update; virB1.setProperties; dbms_output.put_line('image width = '|| virB1.width ); dbms_output.put_line('image height = '|| virB1.height ); dbms_output.put_line('image size = '|| virB1.contentLength ); dbms_output.put_line('image file type = '|| virB1.fileFormat ); dbms_output.put_line('image type = '|| virB1.contentFormat ); dbms_output.put_line('image compression = '|| virB1.compressionFormat ); -- Note: signature not meaningful as displayed output.
Example output:
image width = 360 image height = 490 image size = 59650 image file type = JFIF image type = 24BITRGB image compression = JPEG
setProperties(description IN VARCHAR2 );
Allows you to write the characteristics of a foreign image (BLOB or BFILE) into the appropriate attribute fields.
The image characteristics to set for the foreign image.
After you 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 images do not contain information on how to interpret the bits in the file (or contain information that the product cannot understand), and you must set them explicitly.
You can set the following image characteristics for foreign files, as shown in
Table E-3.
The values supplied to setProperties( ) are written to the existing ORDVirB and ORDVirF object attributes. The fileFormat is set to OTHER: and includes the user string, if supplied.
Note that setProperties( ) does not create the signature required for content-based retrieval. See the Analyze( ) operator in Section E.3 for details.
Select the image type, and then set the attributes using the SetProperties method.
virB1 ORDSYS.ORDVIRB; select col2 into virB1 from ordvirtab where col1 = 1 for update; virB1.setProperties('width=380 height=407 dataOffset=128 bandOrder=BIL
userString="LSAT"');
Visual Information Retrieval operators are located in the ORDSYS.VIR package. The operators, which are specific to content-based retrieval, are as follows:
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.Score( ), and so forth. Note that you must have the default CREATE SYNONYM privilege.
This section presents reference information on the operators.
Analyze(image IN BLOB, signature OUT RAW);
or
Analyze(image IN BFILE, signature OUT RAW);
Analyzes an image BLOB or BFILE, derives information relating to the visual attributes, and creates the image signature.
The BLOB or BFILE to be analyzed.
The vector to contain the signature.
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.
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 and then compare the signatures using the Score( ) and Similar( ) operators.
Create the signatures for all images in the stockphotos table.
DECLARE temp_image ORDSYS.ORDVirB; 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.content, temp_image.signature); temp_image.setProperties; UPDATE stockphotos SET photo = temp_image WHERE photo_id = temp_id; END LOOP; CLOSE c1; END;
Convert(signature IN OUT RAW, operation IN VARCHAR2);
Converts the image signature to a format usable by the host machine.
The signature of the image, as created by the Analyze( ) operator or by Viisage software. Data type is raw(2000).
The processing to be done to the image signature. The following operations are available:
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 machine-independent; only the signatures need to be converted.
When the operation is VIISAGE, the signature is converted from the format used by Viisage Technology for facial recognition to the format usable by this product for Score( ) and Similar( ) operators.
Example 1: Convert the signature of the image with photo_id=1 to a signature that is usable by the host system.
DECLARE myimage ORDSYS.ORDVirB; 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;
Example 2: 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 Score( ) and Similar( ) operators.
DECLARE myimage ORDSYS.ORDVirB; 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;
Score(signature1 IN RAW,
signature2 IN RAW,
weightstring IN VARCHAR2);
where weightstring is: 'globalcolor="val" localcolor="val" texture="val" structure="val"'
or: 'facial=1'
Compares the signatures of two images and returns a number representing the weighted sum of the distances for the visual attributes.
The signature of the comparison image (the image with which other images are being compared to test for matches). Data type is RAW(2000).
The signature of the image being compared with the comparison image. Data type is RAW(2000).
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:
A FLOAT value between 0.0 and 100.0, where 0.0 is identical and 100.0 is totally different.
Before the Score( ) operator can be used, the image signatures must be created with the Analyze( ) operator.
The Score( ) operator can be useful when an application wants to make finer distinctions about matching than the simple Yes or No returned by the Similar( ) operator. For example, using the number for weighted sum returned by Score( ), the application might assign each image being compared to one of several categories, such as definite matches, probable matches, possible matches, and non-matches. The Score( ) operator can also be useful if the application needs to perform special processing based on the degree of similarity between images.
The weights supplied for the four visual attributes are normalized before 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. You cannot combine the facial attribute with any of the other attributes.
Example 1: The following example finds the weighted sum of the distances between image 1 and the other images in the stockphotos table, using the following weights for the visual attributes:
Example 2: This example assumes that the signatures were created using the Analyze( ) operator and they are stored in the database.
DECLARE weighted_sum NUMBER; BEGIN SELECT Q.photo_id, ORDSYS.VIR.Score(S.photo.signature, Q.photo.signature, 'globalcolor="0.2"
localcolor="0.2"
texture="0.1"
structure="0.5"') weighted_sum FROM stockphotos Q, stockphotos S WHERE S.photo_id=1 and Q.photo_id !=S.photo_id; END;
The following shows possible output from the previous example. The first image has the lowest score, and therefore is the best match of the test image (photo_id=1). Changing the weights used in the scoring would lead to different results.
PHOTO_ID WEIGHTED_SUM ---------- ------------- 2 3.79988 3 76.0807 4 47.8139 5 80.451 6 91.2473 5 rows selected.
Similar(signature1 IN RAW
signature2 IN RAW,
weightstring IN VARCHAR2
threshold IN FLOAT);
where weightstring is: 'globalcolor="val" localcolor="val" texture="val" structure="val"'
or: 'facial=1'
Determines whether or not two images match. Specifically, compares the signatures of two images, computes a weighted sum of the distance between the two images using 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 Similar( ) operator returns 0.
The signature of the comparison image (the image with which other images are being compared to test for matches).
The signature of the image being compared with the comparison image.
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:
The 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.
An integer value of 0 (not similar) or 1 (match).
Before the Similar( ) operator can be used, the image signatures must be created with the Analyze( ) operator.
The Similar( ) operator is useful when the application needs a simple Yes or No for whether or not two images match. The Score( ) 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 before 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. You cannot combine the facial attribute with any of the other attributes.
This example checks the first image against all the other images in the table and determines if there are any matches, using a threshold value of 75 and the following weights for the visual attributes:
BEGIN SELECT Q.photo_id FROM stockphotos Q, stockphotos S WHERE S.photo_id=1 and Q.photo_id != S.photo_id AND ORDSYS.VIR.Similar(S.photo.signature, Q.photo.signature, 'globalcolor="20"
localcolor="20"
texture="10"
structure="50"', 75)=1; END;
The following shows a possible output from this example. See the Examples section of the Score( ) operator for a different way of viewing the results using the same images and weights.
PHOTO_ID ---------- 2 4 2 rows selected.
|
 Copyright © 1996-2000, Oracle Corporation. All Rights Reserved. |
|