Release 8.1.5
A67293-01
 Library |
 Product |
 Contents |
 Index |
| Oracle8i Visual Information Retrieval User's Guide and Reference Release 8.1.5 A67293-01 |
|
The Visual Information Retrieval library consists of:
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);
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:
At this point, the source plug-in can initialize the context for this client.
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. |
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.
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.
The ORDSource object type consists of the fields shown in Table 4-2.
| Attribute | Data Type | Description |
|---|---|---|
|
localData |
BLOB |
Locally stored image data. |
|
srcType |
VARCHAR2(4000) |
Identifies the source type as one of the |
|
srcLocation |
VARCHAR2(4000) |
Identifies where the data can be found based on the srcType. |
|
srcName |
VARCHAR2(4000) |
Identifies the data object name based on the source type. |
|
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-4 describes the 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.
This section presents reference information on the methods used for image manipulation.
The Visual Information Retrieval methods are as follows:
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:
analyze( );
Analyzes an image, derives information relating to the visual attributes (including a score for each), and creates the image signature.
None.
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).
None.
None.
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 RETURN BOOLEAN;
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.
None.
Use this method to verify that the image attributes match the actual image.
None.
None.
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;
Resets the local flag value from local (1) to nonlocal (0) for the source of the data.
None.
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.
None.
None.
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(dest IN OUT NOCOPY ORDVir);
Copies an image without changing it.
The destination of the new image.
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.
None.
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.
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;
Deletes the local data from the current local source (localData).
None.
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.
None.
None.
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(ctx IN OUT RAW,
source_type IN VARCHAR2,
source_location IN VARCHAR2,
source_name IN VARCHAR2);
Transfers image data from a local source (localData) within an Oracle database to an external image data source.
The source plug-in context information.
The source type of the location where the image data is to be exported.
The location where the image data is to be exported.
The name of the image object where the image is to be exported.
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.
None.
None.
None.
getBFILE RETURN BFILE;
Returns the LOB locator of the BFILE containing the image.
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 RESTRICT_REFERENCES(getBFILE, WNDS, WNPS, RNDS, RNPS)
INCOMPLETE_SOURCE_INFORMATION -- raised if the srcType is NULL.
INVALID_SOURCE_TYPE -- raised if srcType is not FILE.
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 RETURN VARCHAR2;
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.
None.
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 RESTRICT_REFERENCES(getCompressionFormat, WNDS, WNPS, RNDS, RNPS)
None.
Get the compression type of an image:
imgb1 ORDSYS.ORDVir; compressionFormat VARCHAR2(4000); ... compressionFormat := imgb1.getCompressionFormat;
getContent RETURN BLOB;
Returns the LOB locator of the BLOB containing the image. This is a simple access method that returns the value of the localData attribute.
None.
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 RESTRICT_REFERENCES(getContent, WNDS, WNPS, RNDS, RNPS)
None.
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 RETURN VARCHAR2;
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.
None.
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 RESTRICT_REFERENCES(getContentFormat, WNDS, WNPS, RNDS, RNPS)
None.
Get the type of an image:
imgb1 ORDSYS.ORDVir; contentFormat VARCHAR2(4000); ... contentFormat := imgb1.getContentFormat;
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.
getContentLength RETURN INTEGER;
None.
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 RESTRICT_REFERENCES(getContentLength, WNDS, WNPS, RNDS, RNPS)
None.
Get the length of the image data content stored in the source:
imgb1 ORDSYS.ORDVir; contentLength INTEGER; ... contentLength := imgb1.getContentLength;
getFileFormat RETURN VARCHAR2;
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.
None.
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 RESTRICT_REFERENCES(getFileFormat, WNDS, WNPS, RNDS, RNPS)
None.
Get the file type of an image:
imgb1 ORDSYS.ORDVir; fileFormat VARCHAR2(4000); ... fileFormat := imgb1.getFileFormat;
getHeight RETURN INTEGER;
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.
None.
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 RESTRICT_REFERENCES(getHeight, WNDS, WNPS, RNDS, RNPS)
None.
Get the height of an image:
imgb1 ORDSYS.ORDVir; height INTEGER; ... height := imgb1.getHeight;
getMimeType RETURN VARCHAR2;
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.
None.
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 RESTRICT_REFERENCES(getMimeType, WNDS, WNPS, RNDS, RNPS)
None.
Return the MIME media type:
imgb1 ORDSYS.ORDVir; mimeType VARCHAR2(4000); ... mimeType := imgb1.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.
Use this method rather than accessing the signature attribute directly to protect yourself from potential changes to the internal representation of the ORDVir object.
None.
None.
Get the signature of an image:
virb1 ORDSYS.ORDVir; signature RAW(2000); ... signature := virb1.getSignature;
getSource RETURN VARCHAR2;
Returns information about the external location of the image data in URL format.
None.
The possible return values for this method are:
PRAGMA RESTRICT_REFERENCES(getSource, WNDS, WNPS, RNDS, RNPS)
None.
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 RETURN VARCHAR2;
Returns a formatted string containing the external image data source location.
None.
This method returns a VARCHAR2 string formatted as <location> for the current value of the srcLocation attribute.
PRAGMA RESTRICT_REFERENCES(getSourceLocation, WNDS, WNPS, RNDS, RNPS)
INCOMPLETE_SOURCE_LOCATION -- raised if the location is not set in the image object.
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 RETURN VARCHAR2;
Returns a string containing the name of the external image data source.
None.
This method returns a VARCHAR2 string containing the name of the external data source, for example, 'testimg.dat' .
PRAGMA RESTRICT_REFERENCES(getSourceName, WNDS, WNPS, RNDS, RNPS)
INCOMPLETE_SOURCE_NAME -- raised if the srcName is not set in the image object.
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 RETURN VARCHAR2;
Returns a string containing the type of the external data source.
None.
This method returns a VARCHAR2 string containing the type of the external image data source, for example, 'FILE'.
PRAGMA RESTRICT_REFERENCES(getSourceType, WNDS, WNPS, RNDS, RNPS)
None.
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 RETURN DATE;
Returns the time when the image was last updated.
None.
None.
PRAGMA RESTRICT_REFERENCES(getUpdateTime, WNDS, WNPS, RNDS, RNPS)
None.
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 RETURN INTEGER;
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.
None.
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 RESTRICT_REFERENCES(getWidth, WNDS, WNPS, RNDS, RNPS)
None.
Get the width of an image:
imgb1 ORDSYS.ORDVir; width INTEGER; ... width := imgb1.getWidth;
import(ctx IN OUT RAW);
Transfers image data from an external image data source to a local source (localData) within an Oracle database.
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.
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.
None.
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(ctx IN OUT RAW,
source_type IN VARCHAR2,
source_location IN VARCHAR2,
source_name IN VARCHAR2);
Transfers image data from the specified external image data source to a local source (localData) within an Oracle database.
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.
Specifies the source type of the image data.
Specifies the location from which the image data is to be imported.
Specifies the name of the image data.
This method is similar to the import( ) method except the source information is specified within the method instead of separately.
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 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.
None.
None.
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 RETURN BOOLEAN;
Returns the current value of the local flag, indicating whether or not the data is stored locally.
None.
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 RESTRICT_REFERENCES(isLocal, WNDS, WNPS,RNDS,RNPS)
None.
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(old_object ORDVirB);
Allows you to migrate old ORDVirB images to the new ORDVir object type.
The old ORDVirB image.
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.
None.
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(old_object ORDVirF);
Allows you to migrate old ORDVirF images to the new ORDVir object type.
The old ORDVirF image.
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.
None.
None.
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(command IN VARCHAR2);
Performs one or more image processing techniques on a BLOB, writing the image back onto 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 4-5. Table 4-6 shows additional changes that can be made only to raw pixel and foreign images.
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.
None.
DATA_NOT_LOCAL -- raised if data is not local or source.localData is NULL.
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(command IN VARCHAR2,
dest IN OUT NOCOPY ORDVir);
Copies an image stored internally or externally to another image stored internally as a BLOB.
A list of image processing changes to make for the image in the new copy.
The destination of the new image.
None.
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.
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;
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.
None.
This method sets the local attribute to "1," meaning the data is stored locally in localData.
None.
NULL_LOCAL_DATA -- raised if source.localData is NULL.
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(mime IN VARCHAR2);
Allows you to set the MIME media type of the stored image data.
The MIME media type.
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.
None.
None.
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;
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.
None.
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:
This method implicitly sets the update time and MIME type.
None.
NULL_LOCAL_DATA -- raised if the source.localData attribute is NULL and the source.local attribute indicates the data is local.
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(description IN VARCHAR2);
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.
The image characteristics to set for the foreign image.
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.
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'.
None.
NULL_PROPERTIES_DESCRIPTION -- raised if the description is NULL.
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(source_type IN VARCHAR2,
source_location IN VARCHAR2,
source_name IN VARCHAR2);
Sets or alters information about the external source of the image data.
Sets or alters the srcType attribute of the image data source.
Sets or alters the srcLocation attribute of the image data source.
Sets or alters the srcName attribute of the image data source.
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.
None.
None.
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(current_time DATE);
Sets the time when the image data was last updated.
The updated time. Default is SYSDATE.
Use this method whenever you modify the image data. The process( ), processCopy( ), and setProperties( ) methods all call this method and setMimeType( ) implicitly.
None.
None.
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; /
The Visual Information Retrieval operators are located in the ORDSYS schema.
Two operators are located in the ORDSYS.VIR package:
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.
Analyze(image IN OUT ORDVir);
Analyzes an image, derives information relating to the visual attributes, and creates the image signature.
The ORDVir object to be analyzed.
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 using the
Convert( ) operator and then compare the signatures using the VIRScore( ) and VIRSimilar( ) operators.
During analysis, images are temporarily scaled to a common size such that the signatures are based on a common reference.
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(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 kind of processing 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 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.
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(referencetoSimilar IN NUMBER);
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( ).
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.
This function returns a FLOAT value between 0.0 and 100.0, where 0.0 is identical and 100.0 is totally different.
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.
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:
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(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'
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.
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.
The signature of the query or test 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. 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.
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.
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 an integer value of 0 (not similar) or 1 (match).
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.
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:
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;
