SI_PositionalColor Object Type

The SI_PositionalColor object represents the most significant color positions of an image. If an image is divided into n by m rectangles, positional color is a feature that characterizes the image by the n by m most significant colors of the rectangles. This object type is created in the ORDSYS schema with invoker rights. It is declared as an INSTANTIABLE and NOT FINAL type. (See "Internal Helper Types" for the colorPositions attribute syntax.)

The SI_PositionalColor object is defined as follows:

CREATE OR REPLACE TYPE SI_PositionalColor
  AUTHID CURRENT_USER
  AS OBJECT
  (
     --attributes
     SI_ColorPositions  colorPositions,
     --
     --Methods
     CONSTRUCTOR FUNCTION SI_PositionalColor
     (sourceImage IN SI_StillImage)
     RETURN SELF AS RESULT DETERMINISTIC,
     --
     MEMBER FUNCTION SI_Score
      (image IN SI_StillImage),
     RETURN DOUBLE PRECISION DETERMINISTIC
) INSTANTIABLE
  NOT FINAL;
/

where:

• SI_ColorPositions: an array of SI_Color that represents the most significant color positions of an image.

---

SI_PositionalColor Constructor

This section describes the SI_PositionalColor object constructor, which is as follows:

• SI_PositionalColor( )

SI_PositionalColor( )

Format

SI_PositionalColor(sourceImage IN SI_StillImage)

RETURN SELF AS RESULT DETERMINISTIC;

Format of Equivalent SQL Function

SI_FindPstnlClr(sourceImage IN SI_StillImage)

RETURN SI_PositionalColor DETERMINISTIC;

Description

Constructs an SI_PositionalColor object from a specified image. The SI_ColorPositions array attribute is initialized with the most significant color values derived from the specified image.

To derive the SI_PositionalColor object, the image is assumed to be divided into n by m rectangles such that the product of n by m is equal to the value of SI_NumberSections. (Query the SI_VALUES view in SI_INFORMTN_SCHEMA for the value of SI_NumberSections.) The most significant color of each rectangle is determined. The array thus computed is the value of the SI_ColorPositions array attribute.

Parameters

sourceImage

Image whose positional color feature is extracted.

Pragmas

None.

Exceptions

None.

Usage Notes

An error is returned if any of the following conditions is true:

• The value of the sourceImage parameter is NULL.

• The value of sourceImage.SI_Content is NULL.

• The positional color feature is not supported for this image format.

You can determine whether or not the positional color feature is supported for an image format by querying the SI_IMAGE_FORMAT_FEATURES view or the SI_IMAGE_FRMT_FTRS view.

Examples

Create an SI_PositionalColor object from an image using the SI_PositionalColor( ) method:

DECLARE
   myPosColor SI_PositionalColor;
   myimage    SI_StillImage;
BEGIN
   SELECT product_photo INTO myimage FROM PM.SI_MEDIA 
      WHERE product_id=1 FOR UPDATE;
   myPosColor := NEW SI_PositionalColor(myimage);
   UPDATE PM.SI_MEDIA SET positional_color = myPosColor WHERE product_id=1;
   SELECT product_photo INTO myimage FROM PM.SI_MEDIA 
      WHERE product_id=2 FOR UPDATE;
   myPosColor := NEW SI_PositionalColor(myimage);
   UPDATE PM.SI_MEDIA SET positional_color = myPosColor WHERE product_id=2;
   COMMIT;
END;
/

Create an SI_PositionalColor object from an image using the SI_FindPstnlClr( ) function:

DECLARE
   myPosColor SI_PositionalColor;
   myimage    SI_StillImage;
BEGIN
   SELECT product_photo INTO myimage FROM PM.SI_MEDIA 
     WHERE product_id=2 FOR UPDATE;
   UPDATE PM.SI_MEDIA SET positional_color = SI_FindPstnlClr(myimage) 
     WHERE product_id=2;
   COMMIT;
END;
/

---

SI_PositionalColor Method

This section presents reference information on the SI_PositionalColor method used for image matching, which is as follows:

• SI_Score( ) for SI_PositionalColor

SI_Score( ) for SI_PositionalColor

Format

SI_Score(image IN SI_StillImage)

RETURN DOUBLE PRECISION DETERMINISTIC;

Format of Equivalent SQL Function

SI_ScoreByPstnlClr(feature IN SI_PositionalColor,

image IN SI_StillImage),

RETURN DOUBLE PRECISION DETERMINISTIC;

Description

Determines and returns the score of the specified image when compared to the SI_PositionalColor object to which this method is applied. For scoring an image, that image is divided into n by m rectangles such that the product (m * n) is equal to SI_NumberSections. (Query the SI_VALUES view in SI_INFORMTN_SCHEMA for the value of SI_NumberSections.) The lower the returned value, the better the n by m most significant colors of the image are characterized by the most significant colors in SI_PositionalColor to which you apply this method.

This method returns a DOUBLE PRECISION value between 0 and 100, unless any one of the following is true, in which case a NULL value is returned:

• The value of the SI_PositionalColor object to which you apply this method is NULL.

• The value of the image parameter is NULL.

• The value of image.content_SI attribute is NULL.

• The positional color feature is not supported for the specified image.

Parameters

feature

The positional color to be compared with the positional color of the specified image.

image

The image whose positional color feature is extracted and used for comparison.

Usage Notes

None.

Pragmas

None.

Exceptions

None.

Examples

Compare an image to an SI_PositionalColor object and return the score using the SI_Score( ) method:

DECLARE
    score DOUBLE PRECISION;
    myimage SI_StillImage;
    myPosColor SI_PositionalColor;
BEGIN
   SELECT positional_color INTO myPosColor FROM PM.SI_MEDIA 
     WHERE product_id=1;
   SELECT product_photo INTO myimage FROM PM.SI_MEDIA WHERE product_id=2;
   score := myPosColor.SI_Score(myimage);
   DBMS_OUTPUT.PUT_LINE('Score is ' || score);
END;
/

Compare an image to an SI_PositionalColor object and return the score using the SI_ScoreByPstnlClr( ) function:

DECLARE
    score DOUBLE PRECISION;
    myimage SI_StillImage;
    myPosColor SI_PositionalColor;
BEGIN
   SELECT positional_color INTO myPosColor FROM PM.SI_MEDIA 
      WHERE product_id=1;
   SELECT product_photo INTO myimage FROM PM.SI_MEDIA WHERE product_id=2;
   score := SI_ScoreByPstnlClr(myPosColor, myimage);
   DBMS_OUTPUT.PUT_LINE('Score is ' || score);
END;
/