ORDImageSignature Object Type

Oracle interMedia describes the ORDImageSignature object type, which supports content-based retrieval (image matching).

Note:

All interMedia features are available with the Standard Edition of Oracle Database except image indexing. The image indexing feature requires bit-mapped indexing, which is available only when you install the Enterprise Edition of Oracle Database.

See the information on using an index to compare signatures in Oracle interMedia User's Guide for details on image indexing.

The examples in this chapter use the ONLINE_MEDIA table in the Product Media sample schema. See Oracle Database Sample Schemas for information on the sample schemas.

Note:

When you are storing or copying ORDImageSignature objects, you must first create an empty ORDImageSignature object in the table by using the ORDImageSignature.init( ) method.

The ORDImageSignature object type supports content-based retrieval, or image matching. This object type is defined as follows:

CREATE OR REPLACE TYPE ORDImageSignature
AS OBJECT
(
  -- Signature of the image.  Contains color, texture
  -- and shape information of the image.  It is stored
  -- in a BLOB.

  signature BLOB,

-----------------------
-- METHOD DECLARATION

-- Makes the callout

STATIC FUNCTION init RETURN ORDImageSignature,

STATIC FUNCTION evaluateScore(sig1    IN ORDImageSignature,
                              sig2    IN ORDImageSignature,
                              weights IN VARCHAR2)
  RETURN FLOAT,

STATIC FUNCTION isSimilar(sig1      IN ORDImageSignature,
                          sig2      IN ORDImageSignature,
                          weights   IN VARCHAR2,
                          threshold IN FLOAT)
  RETURN INTEGER,

MEMBER PROCEDURE generateSignature(image  IN ORDImage)
);

where:

signature: holds the signature of the stored image data.

ORDImageSignature Constructor

This section describes the constructor function.

The interMedia constructor function is as follows:

init( ) for ORDImageSignature

init( ) for ORDImageSignature

Format

init( ) RETURN ORDImageSignature;

Description

Initializes instances of the ORDImageSignature object type.

Parameters

None.

Pragmas

None.

Exceptions

None.

Usage Notes

This constructor is a static method that initializes the ORDImageSignature signature attribute to empty_blob.

You must use the init( ) method to initialize ORDImageSignature objects that are stored in the database.

Examples

Initialize the ORDImageSignature object attribute:

BEGIN
 INSERT INTO pm.online_media (product_id, product_photo, 
  product_photo_signature) 
  VALUES (1910, ORDSYS.ORDImage.init('FILE', 'FILE_DIR','speaker.jpg'),
  ORDSYS.ORDImageSignature.init());
 INSERT INTO pm.online_media (product_id, product_photo, 
  product_photo_signature) 
  VALUES (1940, ORDSYS.ORDImage.init('FILE', 'FILE_DIR','keyboard.jpg'),
  ORDSYS.ORDImageSignature.init());
 INSERT INTO pm.online_media (product_id, product_photo, 
  product_photo_signature) 
  VALUES (2402, ORDSYS.ORDImage.init('FILE', 'FILE_DIR','speaker_02.jpg'),
  ORDSYS.ORDImageSignature.init());
COMMIT;
END;
/

ORDImageSignature Methods

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

The following methods are presented in this section:

evaluateScore( )
generateSignature( )
isSimilar( )

evaluateScore( )

Format

evaluateScore(

sig1 IN ORDImageSignature,

sig2 IN ORDImageSignature,

weights IN VARCHAR2)

RETURN FLOAT;

Description

A static method of the ORDImageSignature object type that evaluates the distance between two input signatures based on the influence of the specified attributes in the weights parameter.

Parameters

sig1

A signature object.

sig2

A signature object.

weights

A string consisting of matching attribute names followed by values between 0.0 and 1.0. The matching attributes refer to the weights assigned by the user to the different attributes that influence the kind of match. Attributes not specified by the user have a default value of 0.0.

The string can have all or some of the attributes. The value associated with an attribute specifies its relative importance in determining the distance between the signatures. An attribute with a value of 0.0 is not considered at all, while an attribute with a value of 1.0 is of the highest importance. The weights supplied are normalized prior to processing such that they add up to 1.0, maintaining the ratios that you supplied. At least one of the attributes must have a value greater than 0.0. The attributes are the following:

color: A value between 0.0 and 1.0 indicating the importance of the feature color.
texture: A value between 0.0 and 1.0 indicating the importance of the feature texture.
shape: A value between 0.0 and 1.0 indicating the importance of the feature shape.
location: A value between 0.0 and 1.0 indicating the importance of the location of the regions in the image. The location weight string cannot be specified alone, it must be used with another weight string.

Return Value

This function returns a FLOAT value between 0.0 and 100.0, where 0.0 means the images are identical and 100.0 means the images are completely different.

Usage Notes

The ORDImageSignature evaluateScore( ) method operates on two image signatures, not on indexes on database tables. Therefore, this method cannot take advantage of the increased performance that is possible using image matching with image signature indexes on the underlying tables. To use signature images, use the IMGSimilar and IMGScore SQL operators.

The ORDImageSignature objects must either be initialized, inserted into a table, and have a signature generated for them, or be created using a temporary LOB and have a signature generated for them, to successfully use the evaluateScore( ) method to compare the signatures.

Pragmas

None.

Exceptions

None.

Examples

Compare two signatures and evaluate the score between them:

DECLARE
 t_image     ORDSYS.ORDImage;
 c_image    ORDSYS.ORDImage;
 image_sig   ORDSYS.ORDImageSignature;
 compare_sig ORDSYS.ORDImageSignature;
 score FLOAT;
BEGIN
 SELECT p.product_photo, p.product_photo_signature INTO t_image, image_sig 
  FROM pm.online_media p
  WHERE p.product_id = 1910 FOR UPDATE;
 -- Generate a signature:
 image_sig.generateSignature(t_image);
 UPDATE pm.online_media p SET p.product_photo_signature = image_sig 
  WHERE product_id =1910;
 SELECT p.product_photo, p.product_photo_signature INTO c_image, compare_sig
  FROM pm.online_media p
  WHERE p.product_id = 1940 FOR UPDATE;
 -- Generate a signature:
 compare_sig.generateSignature(c_image);
 UPDATE pm.online_media p SET p.product_photo_signature = compare_sig
  WHERE product_id = 1940;
SELECT p.product_photo, p.product_photo_signature INTO t_image, image_sig 
 FROM pm.online_media p 
 WHERE p.product_id  = 1910;
SELECT p.product_photo, p.product_photo_signature INTO c_image, compare_sig 
 FROM pm.online_media p
 WHERE p.product_id = 1940;
 -- Compare two images for similarity based on image color:
 score:=ORDSYS.ORDImageSignature.evaluateScore(image_sig, 
  compare_sig,'color=1.0,texture=0,shape=0,location=0');
 DBMS_OUTPUT.PUT_LINE('Score is ' || score);
END;
/

generateSignature( )

Format

generateSignature (image IN ORDImage);

Description

Generates a signature for a given input image that is passed back as the signature object.

Parameters

image: The image object whose signature is to be generated.

Usage Notes

The ORDImageSignature object must either be initialized and inserted into a table or be created using a temporary LOB, to successfully generate a signature for the object.

The minimum image size for which the generateSignature( ) method can be called is 21x21 pixels. The generateSignature( ) method fails and returns the "IMG-00870, Unsupported aspect ratio or image size" error when called for smaller images.

Pragmas

None.

Exceptions

None.

Examples

Generate a signature for an image object stored in the database:

DECLARE
 t_image   ORDSYS.ORDImage;
 image_sig ORDSYS.ORDImageSignature;
BEGIN
 SELECT p.product_photo, p.product_photo_signature INTO t_image, image_sig 
  FROM pm.online_media p
  WHERE p.product_id = 2402 FOR UPDATE;
 -- Generate a signature:
 image_sig.generateSignature(t_image);
 UPDATE pm.online_media p SET p.product_photo_signature = image_sig 
 WHERE    product_id = 2402;
END;
/

isSimilar( )

Format

isSimilar(

sig1 IN ORDImageSignature,

sig2 IN ORDImageSignature,

weights IN VARCHAR2,

threshold IN FLOAT)

RETURN INTEGER;

Description

A static method of the ORDImageSignature object type that compares two signatures, and computes the distance between them based on the influence of the specified attributes in the weights parameter and the specified threshold value. If the distance is less than the specified threshold, a value of 1 is returned, otherwise a value of 0 is returned.

Parameters

sig1

A signature object.

sig2

A signature object.

weights

color: A value between 0.0 and 1.0 indicating the importance of the feature color.
texture: A value between 0.0 and 1.0 indicating the importance of the feature texture.
shape: A value between 0.0 and 1.0 indicating the importance of the feature shape.
location: A value between 0.0 and 1.0 indicating the importance of the location of the regions in the image. The location weight string cannot be specified alone, it must be used with another weight string.

threshold

The degree of the match that the user desires. For example, if the value is specified as 10, then only those images whose signatures are a distance of 10 or less (score of 10 or less) from the query signature will be returned. The value of the threshold ranges from 0 to 100, which is the range of the distance.

Usage Notes

You can use this method to compare two signatures not stored in the database, or when you must perform a comparison within a PL/SQL construct.

The ORDImageSignature isSimilar( ) method operates on two image signatures, not on indexes on database tables. Therefore, this method cannot take advantage of the increased performance that is possible using image matching with image signature indexes on the underlying tables. To use signature images, use the IMGSimilar and IMGScore SQL operators.

Pragmas

None.

Exceptions

None.

Examples

Compare two images based on color. Images are considered similar if a distance of 10 or less is returned:

DECLARE
 image_sig1 ORDSYS.ORDImageSignature;
 image_sig2 ORDSYS.ORDImageSignature;
 value     INTEGER;
BEGIN
 SELECT product_photo_signature INTO image_sig1 FROM pm.online_media
  WHERE product_id = 1910;
SELECT product_photo_signature INTO image_sig2 FROM pm.online_media
  WHERE product_id = 1940;
 -- Compare the images:
 value := ORDSYS.ORDImageSignature.isSimilar(image_sig1,
 image_sig2,'color=1.0,texture=0,shape=0,location=0',10);
 IF value = 1 THEN
   DBMS_OUTPUT.PUT_LINE('The images are similar');
 ELSIF value = 0 THEN
   DBMS_OUTPUT.PUT_LINE('The images are not similar');
 END IF;
END;
/

ORDImageSignature Operators

The following ORDImageSignature operators are schema level operators and do not reside within a package. These operators use the domain index, if it exists.

IMGSimilar( )
IMGScore( )

IMGSimilar( )

Format

IMGSimilar (sig1 IN ORDSYS.ORDImageSignature,

sig2 IN ORDSYS.ORDImageSignature,

weights IN VARCHAR2,

threshold IN FLOAT

[ ,referencetoScore IN NUMBER] );

Description

Determines whether or not two images match. Specifically, the operator compares the signature of a query image with the signatures of images stored in a table, and determines whether or not the images match, based on the weights and threshold value. This operator returns 1 if the computed distance measure (weighted average) is less than or equal to the threshold value (indicating a match), and returns 0 when the distance between the two images is more than the threshold value.

Parameters

sig1

The signature of the image to which you are comparing the query image. The data type is ORDImageSignature. 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, the database uses the non-indexed implementation of query evaluation.

sig2

The signature of the query or test image. The data type is ORDImageSignature.

weights

color: A value between 0.0 and 1.0 indicating the importance of the feature color.
texture: A value between 0.0 and 1.0 indicating the importance of the feature texture.
shape: A value between 0.0 and 1.0 indicating the importance of the feature shape.
location: A value between 0.0 and 1.0 indicating the importance of the location of the regions in the image. The location weight string cannot be specified alone, it must be used with another weight string.

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.

referencetoScore

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

Return Value

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

Pragmas

None.

Exceptions

None.

Usage Notes

Before the IMGSimilar( ) operator can be used, the image signatures must be created with the generateSignature( ) method. Image signatures that have not been initialized will not be evaluated by the IMGSimilar( ) operator. Also, to use the domain index, the index of type ORDImageIndex must have already been created. See Oracle interMedia User's Guide for information on creating and using the index, and for additional performance tips.

The IMGSimilar( ) operator returns Boolean values to indicate if two images match (true, if their image matching score is below the threshold). If you want to know the score value itself, you can use the IMGScore( ) operator in conjunction with the IMGSimilar( ) operator to retrieve the score computed in the IMGSimilar( ) operator.

The IMGSimilar( ) operator is useful when the application needs a simple Yes or No for whether or not two images match. The IMGScore( ) 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.

Use this operator to take advantage of the increased performance that is possible using image matching with image signature indexes of the underlying tables (as opposed to using the evaluateScore( ) and isSimilar( ) methods).

Examples

Find all images similar to the query image using a threshold value of 25 and the following weights for the visual attributes:

Color: 0.2
Texture: 0.1
Shape: 0.5
Location: 0.2

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

DECLARE
 id              NUMBER;
 image           ORDSYS.ORDImage;
 query_signature ORDSYS.ORDImageSignature;
 
CURSOR getphotos IS
 SELECT product_id, product_photo FROM pm.online_media WHERE
  ORDSYS.IMGSimilar(product_photo_signature, query_signature, 
  'color="0.2" texture="0.1" shape="0.5" location="0.2"', 25) = 1;
 
BEGIN
 SELECT product_photo_signature INTO query_signature
  FROM pm.online_media
  WHERE product_id =1910;
 OPEN getphotos;
  LOOP
   FETCH getphotos INTO id, image;
   EXIT WHEN getphotos%NOTFOUND;
   DBMS_OUTPUT.PUT_LINE('Image with ID ' || id || ' matches query image.');
  END LOOP;
 CLOSE getphotos;
END; 
/

Compute the distance between a signature in a temporary LOB and signatures that are stored in the database:

DECLARE 
  id NUMBER; 
  image ORDSYS.ORDIMAGE; 
  query_signature ORDSYS.ORDIMAGESIGNATURE;
  query_image ORDSYS.ORDIMAGE; 
 
  CURSOR getphotos IS
   SELECT product_id, product_photo FROM pm.online_media WHERE 
      ordsys.IMGsimilar(product_photo_signature, query_signature, 
      'color="0.2" texture="0.1" shape="0.5" location="0.2"', 25) = 1; 
 
BEGIN 
 SELECT product_photo INTO query_image 
  FROM pm.online_media WHERE product_id = 1910; 
  -- Initialize signature object 
  query_signature := ORDSYS.ORDIMAGESIGNATURE.init(); 
  -- Create temporary storage for the LOB in the signature object 
  DBMS_LOB.CREATETEMPORARY(query_signature.signature, TRUE); 
  query_signature.generateSignature(query_image); 
  OPEN getphotos; 
   LOOP 
     FETCH getphotos INTO id, image; 
     EXIT WHEN getphotos%NOTFOUND; 
     DBMS_OUTPUT.PUT_LINE('Image with ID ' || id || ' matches query image'); 
   END LOOP; 
 CLOSE getphotos; 
 DBMS_LOB.FREETEMPORARY(query_signature.signature); 
END;/

Generate a signature for an image that is not stored in the database, store the signature in a temporary LOB, and compute the distance between this signature and the signatures that are stored in the database:

DECLARE 
 id NUMBER; 
 image ORDSYS.ORDIMAGE; 
 query_signature ORDSYS.ORDIMAGESIGNATURE; 
 query_image ORDSYS.ORDIMAGE; 
 CURSOR getphotos IS
  SELECT product_id, product_photo FROM pm.online_media WHERE
     ORDSYS.IMGsimilar(product_photo_signature, query_signature, 
     'color="0.2" texture="0.1" shape="0.5" location="0.2"', 25) = 1; 
BEGIN
  -- Initialize and set the properties for the image object 
  query_image := ORDSYS.ORDIMAGE.init('FILE','FILE_DIR','red.gif'); 
  query_image.setproperties; 
  -- Initialize the signature object 
  query_signature := ORDSYS.ORDIMAGESIGNATURE.init(); 
  -- Create temporary storage for the BLOB in the signature object 
  DBMS_LOB.CREATETEMPORARY(query_signature.signature, TRUE); 
  -- Generate a signature for the query image
  query_signature.generateSignature(query_image); 
  
  OPEN getphotos; 
    LOOP 
       FETCH getphotos INTO id, image; 
       EXIT WHEN getphotos%NOTFOUND; 
       DBMS_OUTPUT.PUT_LINE('Image with ID ' || id || ' matches query image'); 
    END LOOP; 
  CLOSE getphotos; 
DBMS_LOB.FREETEMPORARY(query_signature.signature); 
END; 
/

IMGScore( )

Format

IMGScore (NUMBER);

Description

Compares the signatures of two images and returns a number representing the weighted sum of the distances for the visual attributes. The IMGScore( ) operator is an ancillary operator, used only in conjunction with the primary operator, IMGSimilar( ), to retrieve the score computed in the IMGSimilar( ) operator. Each IMGScore( ) and IMGSimilar( ) operator shares the same reference number.

Parameters

NUMBER (referencetoSimilar): Identifier to an IMGSimilar( ) operator. This identifier indicates that the image-matching score value returned by the IMGScore( ) operator is the same one used in the corresponding IMGSimilar( ) operator. This parameter can also be used to maintain references for multiple invocations of the IMGSimilar( ) operator. The data type is NUMBER.

Return Value

This function returns a FLOAT value between 0.0 and 100.0, where 0.0 means the images are identical and 100.0 means the images are completely different.

Pragmas

None.

Exceptions

None.

Usage Notes

Before the IMGScore( ) operator can be used, the image signatures must be created with the generateSignature( ) method. Image signatures that have not been initialized will not be evaluated by the IMGScore( ) operator. Also, if you want the comparison to use the domain index, the index of type ORDImageIndex must have already been created. See Oracle interMedia User's Guide for information on creating and using the index, and for additional performance tips.

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

Examples

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

Color: 0.2
Texture: 0.1
Shape: 0.5
Location: 0.2

This example assumes that the signatures were already created using the generateSignature( ) method. Notice that both IMGScore( ) and IMGSimilar( ) are using 123 as the reference number (referred to as the referenceToScore parameter for the IMGSimilar( ) operator) in this example.

DECLARE
 id              NUMBER;
 img_score       NUMBER;
 t_img           ORDSYS.ORDImage;
 query_signature ORDSYS.ORDImageSignature;
 
 CURSOR getphotos IS
 SELECT product_id, ORDSYS.IMGScore(123), product_photo 
  FROM pm.online_media WHERE
  ORDSYS.IMGSimilar(product_photo_signature, query_signature, 
  'color="0.2" texture="0.1" shape="0.5" location="0.2"', 20, 123) = 1;
 
BEGIN
 SELECT product_photo_signature INTO query_signature 
   FROM pm.online_media
   WHERE product_id = 1910;
 OPEN getphotos;
  LOOP
   FETCH getphotos INTO id, img_score, t_img;
   EXIT WHEN getphotos%NOTFOUND;
   DBMS_OUTPUT.PUT_LINE('Image with ID '|| id || 
                        ' matches query image with score ' || 
                          img_score ||'.');
  END LOOP;
 CLOSE getphotos;
END;
/

The following shows possible results from this example. Image 1910 has a score of 0 because it is the query image; image 1940 is the best match to the query image (besides the query image itself) because it has the lowest score. Changing the weights used in the scoring might lead to different results.

Image with ID 1910 matches query image with score 0.
Image with ID 1940 matches query image with score  10.2663.
Image with ID 1743 matches query with with score  15.4666.

Demonstrate the use of reference numbers to refer to scores evaluated in different IMGSimilar( ) calls.

In this example, a query is searching for an image in the pm.online_media table that is similar in color to query_sig1, and similar in shape and location to query_sig2.

DECLARE
 id              NUMBER;
 img_score1      NUMBER;
 img_score2      NUMBER;
 t_img           ORDSYS.ORDImage;
 query_sig1      ORDSYS.ORDImageSignature;
 query_sig2      ORDSYS.ORDImageSignature;
 
CURSOR getphotos IS
 SELECT product_id, ORDSYS.IMGScore(1), ORDSYS.IMGScore(2), product_photo
  FROM pm.online_media WHERE
  ORDSYS.IMGSimilar(product_photo_signature,query_sig1,'color="1.0"', 30, 1) = 1 
  AND
  ORDSYS.IMGSimilar(product_photo_signature, query_sig2,'shape="0.5" 
                    location="0.2"', 30, 2) = 1;
 
BEGIN
 SELECT product_photo_signature INTO query_sig1 
   FROM pm.online_media
   WHERE product_id = 1910;
 SELECT product_photo_signature INTO query_sig2
   FROM pm.online_media
   WHERE product_id = 1940;
 OPEN getphotos;
  LOOP
   FETCH getphotos INTO id, img_score1, img_score2, t_img;
   EXIT WHEN getphotos%NOTFOUND;
   DBMS_OUTPUT.PUT_LINE('Image with ID '|| id || ' matches the query images.');
  END LOOP;
 CLOSE getphotos;
END;
/