SI_AverageColor Object Type

The SI_AverageColor object type describes the average color feature of an image. It is created in the ORDSYS schema with invoker rights. It is declared as an INSTANTIABLE and NOT FINAL type.

Note:

Use the SI_AverageColor object type constructors and method rather than accessing attributes directly to protect yourself from changes to the internal representation of the SI_AverageColor object.

The AverageColor object type is defined as follows:

CREATE OR REPLACE TYPE SI_AverageColor
  AUTHID CURRENT_USER
  AS OBJECT
 (
-------------------
-- TYPE ATTRIBUTES
-------------------
SI_AverageColorSpec SI_Color,
---------------------
-- METHOD DECLARATION
---------------------
-- CONSTRUCTORS
--
CONSTRUCTOR FUNCTION SI_AverageColor
(sourceImage IN SI_StillImage)
RETURN SELF AS RESULT DETERMINISTIC,

CONSTRUCTOR FUNCTION SI_AverageColor
(SI_AverageColorSpec IN SI_Color)
     return SELF AS RESULT DETERMINISTIC,

-- Methods associated with the source attribute
MEMBER FUNCTION SI_Score
(image in SI_StillImage)
 RETURN DOUBLE PRECISION DETERMINISTIC
) INSTANTIABLE
  NOT FINAL;
/

where:

SI_AverageColorSpec: the average color of the object.

SI_AverageColor Constructors

This section describes the SI_AverageColor object constructors, which are the following:

SI_AverageColor(averageColorSpec)
SI_AverageColor(sourceImage)

SI_AverageColor(averageColorSpec)

Format

SI_AverageColor(averageColorSpec IN SI_Color)

RETURN SELF AS RESULT DETERMINISTIC;

Format of Equivalent SQL Function

SI_MkAvgClr(avgClr IN SI_Color) RETURN SI_AverageColor DETERMINISTIC;

Description

Constructs an SI_AverageColor object. The SI_AverageColorSpec attribute is initialized with the value of the specified color.

Parameters

averageColorSpec avgClr: The color used to construct an SI_AverageColor object.

Pragmas

None.

Exceptions

None.

Usage Notes

An error message is returned if one or more of the following conditions are true:

The value of the specified averageColorSpec is NULL.
The value of the specified averageColorSpec is not a valid SI_Color value.

Examples

Construct an SI_AverageColor object from a specified color using the
SI_AverageColor(averageColorSpec) constructor:

DECLARE
   myColor SI_Color;
   myAvgColor SI_AverageColor;
BEGIN
 myColor := NEW SI_COLOR(null, null, null);
 myColor.SI_RGBColor(10, 100, 200);
 myAvgColor := NEW SI_AverageColor(myColor);
 INSERT INTO PM.SI_MEDIA (product_id, average_color) VALUES (75, myAvgColor);
 COMMIT;
END;
/

Construct an SI_AverageColor object from a specified color using the
SI_MkAvgClr( ) function:

DECLARE
   myColor SI_Color;
   myAvgColor SI_AverageColor;
BEGIN
   myColor := NEW SI_COLOR(null, null, null);
   myColor.SI_RGBColor(10, 100, 200);
   myAvgColor := SI_MkAvgClr(myColor);
   INSERT INTO PM.SI_MEDIA (product_id, average_color) 
     VALUES (89, myAvgColor);
   COMMIT;
END;
/

SI_AverageColor(sourceImage)

Format

SI_AverageColor(sourceImage IN SI_StillImage)

RETURN SELF AS RESULT DETERMINISTIC;

Format of Equivalent SQL Function

SI_FindAvgClr(sourceImage IN SI_StillImage) RETURN SI_AverageColor DETERMINISTIC;

Description

Derives an SI_AverageColor value from the specified image. The image is divided into n samples. Then, each component (red, green, blue) of all the samples is added separately and divided by the number of samples. This gives the values of the components of the specified image. The process by which SI_AverageColor is determined can also be described by the following expression, where n is the number of samples:

Description of si_averagecolor.gif follows
Description of the illustration si_averagecolor.gif

Parameters

sourceImage: The image from which the average color feature is extracted.

Pragmas

None.

Exceptions

None.

Usage Notes

An error is returned if one or more of the following conditions are true:

The value of the specified image is NULL.
The value of sourceImage.SI_Content is NULL.
The average color feature is not supported for the format of the specified image. This is determined by looking up the SI_IMAGE_FORMAT_FEATURES view or SI_IMAGE_FRMT_FTRS view.

Examples

Derive an SI_AverageColor value using the SI_AverageColor(sourceImage) constructor:

DECLARE
   myimage SI_StillImage;
   myAvgColor SI_AverageColor;
BEGIN
   SELECT product_photo INTO myimage FROM PM.SI_MEDIA WHERE product_id=1;
   myAvgColor := NEW SI_AverageColor(myimage);
END;
/

Derive an SI_AverageColor object from an image using the SI_FindAvgClr( ) function:

DECLARE
   myimage SI_StillImage;
   myAvgColor SI_AverageColor;
BEGIN
   SELECT product_photo INTO myimage FROM PM.SI_MEDIA WHERE product_id=1;
   myAvgColor := SI_FindAvgClr(myimage);
END;
/

SI_AverageColor Method

This section presents reference information on the SI_AverageColor method used for image matching:

SI_Score( ) for SI_AverageColor

SI_Score( ) for SI_AverageColor

Formats

SI_Score(image in SI_StillImage)

RETURN DOUBLE PRECISION DETERMINISTIC;

Format of Equivalent SQL Function

SI_ScoreByAvgClr(feature IN SI_AverageColor, image IN SI_StillImage)

RETURN DOUBLE PRECISION DETERMINISTIC;

Description

Determines and returns the score of the specified image as compared to the SI_AverageColor object instance to which you apply the method. This method returns a DOUBLE PRECISION value between 0 and 100. A value of 0 indicates that the average color of the specified image and the SI_AverageColor object instance are identical. A value of 100 indicates that average color of the specified image and the SI_AverageColor object instance are completely different.

Parameters

image: The image whose average color feature is compared with the SI_AverageColor object instance to which you apply this method.
feature: An SI_AverageColor value.

Usage Notes

This method returns a NULL value if any of the following is true:

The value of the SI_AverageColor to which the method is applied is NULL.
The value of the specified image is NULL.
The value of image.content_SI is NULL.
The SI_AverageColor feature is not supported for the specified image format.

Pragmas

None.

Exceptions

None.

Examples

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

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

Compare an image to an SI_AverageColor object and return the score using the SI_ScoreByAvgClr( ) function:

DECLARE
    score DOUBLE PRECISION;
    myimage SI_StillImage;
    myotherimage SI_StillImage;
    myAvgColor SI_AverageColor;
BEGIN
   SELECT product_photo INTO myimage FROM PM.SI_MEDIA WHERE product_id=1;
   myAvgColor := NEW SI_AverageColor(myimage);
   SELECT product_photo INTO myotherimage FROM PM.SI_MEDIA WHERE product_id=2;
   score := SI_ScoreByAvgClr(myAvgColor, myotherimage);
   DBMS_OUTPUT.PUT_LINE('Score is ' || score);
END;
/