SI_ColorHistogram Object Type

The SI_ColorHistogram object represents the color histogram image feature. It describes the relative frequencies of the colors exhibited by samples of an image. It is created in the ORDSYS schema with invoker rights. It is declared as an INSTANTIABLE and NOT FINAL type. This object type is defined as follows. (See "Internal Helper Types" for the colorsList and colorFrequenciesList attribute syntax.)

Note:

Use the SI_ColorHistogram constructors and methods rather than accessing attributes directly to protect yourself from changes to the internal representation of the SI_ColorHistogram object.

The SI_ColorHistogram object is defined as follows:

CREATE OR REPLACE TYPE SI_ColorHistogram
  AUTHID CURRENT_USER
  AS OBJECT
  (
-------------------
-- TYPE ATTRIBUTES
-------------------
SI_ColorsList       colorsList,
SI_FrequenciesList  colorFrequenciesList,
---------------------
-- METHOD DECLARATION
---------------------
-- CONSTRUCTORS
CONSTRUCTOR FUNCTION SI_ColorHistogram
    (sourceImage IN SI_StillImage)
     RETURN SELF AS RESULT DETERMINISTIC,
CONSTRUCTOR FUNCTION SI_ColorHistogram
    (firstColor IN SI_Color,
     frequency  IN DOUBLE PRECISION)
     RETURN SELF AS RESULT DETERMINISTIC,
CONSTRUCTOR FUNCTION SI_ColorHistogram
    (SI_ColorsList       IN colorsList,
     SI_FrequenciesList  IN colorFrequenciesList)
     RETURN SELF AS RESULT DETERMINISTIC,
MEMBER PROCEDURE SI_Append
    (color     IN SI_Color,
     frequency IN DOUBLE PRECISION),
MEMBER FUNCTION SI_Score
     (image    IN SI_StillImage)
RETURN DOUBLE PRECISION DETERMINISTIC
) INSTANTIABLE
  NOT FINAL;
/

where:

SI_ColorsList: array of the SI_Color object type that represents the color values of the image.
SI_FrequenciesList: array of the colorFrequencies attribute that represents the color frequencies of the image. Its values range from 0 to 100. Each array element represents the frequency of the corresponding color in the SI_ColorsList array.

SI_ColorHistogram Constructors

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

SI_ColorHistogram(colors, frequencies)
SI_ColorHistogram(firstColor, frequency)
SI_ColorHistogram(sourceImage)

SI_ColorHistogram(colors, frequencies)

Format

SI_ColorHistogram(SI_ColorsList IN colorsList,

SI_FrequenciesList IN colorFrequenciesList)

RETURN SELF AS RESULT DETERMINISTIC;

Format of Equivalent SQL Function

SI_ArrayClrHstgr(colors IN SI_ColorsList,

frequencies IN colorFrequenciesList),

RETURN SI_ColorHistogram DETERMINISTIC;

Description

Constructs an SI_ColorHistogram object. The following attributes are initialized:

The SI_ColorsList array attribute is initialized with the value of the specified colors.
The SI_FrequenciesList array attribute is initialized with the value of the specified frequencies.

See "Internal Helper Types" for the SI_ColorsList and colorFrequenciesList attribute syntax.

Parameters

SI_ColorsList colors: An array of colors with a maximum size of SI_MaxHistogramLength. Query the
SI_VALUES view in SI_INFORMTN_SCHEMA for the value of SI_MaxHistogramLength.
SI_FrequenciesList frequencies: An array of color frequencies with a maximum size of SI_MaxHistogramLength.

Pragmas

None.

Exceptions

None.

Usage Notes

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

Any one of the specified values is NULL.
Any one of the specified frequency values is less than 0 or greater than 100.

Examples

Construct an SI_ColorHistogram object using the SI_ColorHistogram(colors, frequencies) constructor:

DECLARE
  myColors ordsys.colorsList;
  myFreqs  ordsys.colorFrequenciesList;
  myColorHist SI_ColorHistogram;
BEGIN
    --Create the varray objects colors and frequencies:
    myColors := ordsys.colorsList();
    myFreqs :=  ordsys.colorFrequenciesList();
    --Create 100 empty elements in the varray:
    myColors.extend(100);
    myFreqs.extend(100);
    --Add three colors to the varray:
    myColors :=  ordsys.colorslist(SI_mkRGBClr(10, 20, 255),
                            SI_mkRGBClr(200,200,255),
                            SI_mkRGBClr(35,100,100));
    --Add three frequencies to the varray:
    myFreqs := ordsys.colorFrequenciesList(10, 1, 90);
    --Construct the histogram using the colors and frequency varrays:
    myColorHist := NEW SI_ColorHistogram(myColors, myFreqs);
END;
/

Construct an SI_ColorHistogram object using the SI_ArrayClrHstgr( ) function:

DECLARE
  myColors ordsys.colorsList;
  myFreqs  ordsys.colorFrequenciesList;
  myColorHist SI_ColorHistogram;
BEGIN
    --Create the varray objects colors and frequencies:
    myColors := ordsys.colorsList();
    myFreqs :=  ordsys.colorFrequenciesList();
    --Create 100 empty elements in the varray:
    myColors.extend(100);
    myFreqs.extend(100);
    --Add three colors to the varray:
    myColors :=  ordsys.colorslist(SI_mkRGBClr(10, 20, 255),
                            SI_mkRGBClr(200,200,255),
                            SI_mkRGBClr(35,100,100));
    --Add three frequencies to the varray:
    myFreqs := ordsys.colorFrequenciesList(10, 1, 90);
    --Construct the histogram using the colors and frequency varrays:
    myColorHist := SI_ArrayClrHstgr(myColors, myFreqs);
END;
/

SI_ColorHistogram(firstColor, frequency)

Format

SI_ColorHistogram(firstColor IN SI_Color,

frequency IN DOUBLE PRECISION)

RETURN SELF AS RESULT DETERMINISTIC;

Format of the Equivalent SQL Function

SI_MkClrHstgr(firstColor IN SI_Color, frequency IN DOUBLE PRECISION)

RETURN SI_ColorHistogram DETERMINISTIC;

Description

Creates a single color/frequency pair in an SI_ColorHistogram object. The following attributes are initialized:

The SI_ColorsList array attribute is initialized with the value of the specified firstColor.
The SI_FrequenciesList array attribute is initialized with the value of the specified frequency.

Parameters

firstColor: A color value of SI_ColorHistogram.
frequency: The frequency value of SI_ColorHistogram for the firstColor parameter.

Pragmas

None.

Exceptions

None.

Usage Notes

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

Any one of the specified values is NULL.
The frequency specified is less than 0 or greater than 100.

Examples

Create a single color/frequency pair for an SI_ColorHistogram object using the SI_ColorHistogram(firstColor, frequency) constructor:

DECLARE
   myColor  SI_Color;
   myClrHist SI_ColorHistogram;
BEGIN
   -- Initialize myColor:
   myColor := new SI_Color(null, null, null);
   myColor.SI_RGBColor(10, 45, 200);
   -- Construct the histogram using myColor and a frequency of 10.0:
   myClrHist := new SI_ColorHistogram(myColor, 10.0);
END;
/

Construct a single color/frequency pair for an SI_ColorHistogram object using the SI_MkClrHstgr( ) function:

DECLARE
   myColor  SI_Color;
   myClrHist SI_ColorHistogram;
BEGIN
   -- Initialize myColor:
   myColor := new SI_Color(null, null, null);
   myColor.SI_RGBColor(10, 45, 200);
   -- Construct the histogram using myColor and a frequency of 10.0:
   myClrHist := SI_MkClrHstgr(myColor, 10.0);
END;
/

SI_ColorHistogram(sourceImage)

Format

SI_ColorHistogram(sourceImage IN SI_StillImage)

RETURN SELF AS RESULT DETERMINISTIC;

Format of Equivalent SQL Function

SI_FindClrHstgr (sourceImage IN SI_StillImage)

RETURN SI_ColorHistogram DETERMINISTIC;

Description

Extracts a color histogram from the specified image. The following attributes are initialized:

The SI_ColorsList attribute is initialized with the color values derived from the specified image.
The SI_FrequenciesList attribute is initialized with the frequencies derived from the specified image.

Parameters

sourceImage: The image from which the color histogram is extracted.

Pragmas

None.

Exceptions

None.

Usage Notes

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

The value of the specified image is NULL.
The value of sourceImage.SI_Content is NULL.
The color histogram feature is not supported for this image format.

To determine whether or not the color histogram feature is supported for a given image format, query the SI_IMAGE_FORMAT_FEATURES view or SI_IMAGE_FRMT_FTRS view.

Examples

Extract an SI_ColorHistogram object from an image using the
SI_ColorHistogram(sourceImage) constructor:

DECLARE
   myColorHist SI_ColorHistogram;
   myimage    SI_StillImage;
BEGIN
 -- Select a product_photo from the si_media table:
 SELECT product_photo INTO myimage FROM PM.SI_MEDIA WHERE product_id=2 FOR
 UPDATE;
 -- Extract the color histogram from the source image:
  myColorHist := NEW SI_ColorHistogram(myimage);
 -- Update the color_histogram column with the extracted value:
 UPDATE PM.SI_MEDIA SET color_histogram = myColorHist WHERE product_id=2;
 COMMIT;
END;
/

Extract an SI_ColorHistogram object from an image using the SI_FindClrHstgr( ) function:

DECLARE
   myColorHist SI_ColorHistogram;
   myimage    SI_StillImage;
BEGIN
 SELECT product_photo INTO myimage FROM PM.SI_MEDIA WHERE product_id=2 FOR
 UPDATE;
   myColorHist := SI_FindClrHstgr(myimage);
   UPDATE PM.SI_MEDIA SET color_histogram = myColorHist WHERE product_id=2;
 COMMIT;
END;
/

SI_ColorHistogram Methods

This section presents reference information on the SI_ColorHistogram methods used for color histogram construction and image matching, which are the following:

SI_Append( )
SI_Score( ) for SI_ColorHistogram

SI_Append( )

Format

SI_Append(color IN SI_Color,

frequency IN DOUBLE PRECISION);

Format of Equivalent SQL Procedure

SI_AppendClrHstgr(feature IN OUT NOCOPY SI_ColorHistogram,

color IN SI_Color,

frequency IN DOUBLE PRECISION);

Description

Extends a specified SI_ColorHistogram value by a color/frequency pair.

Parameters

color: The color value to be added to the histogram.
frequency: The corresponding frequency value of the specified color that is to be added to the histogram.
feature: The color histogram to which the color and frequency values are appended.

Usage Notes

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

Any of the specified values is NULL.
The frequency is less than 0 or greater than 100.
The attribute SI_ColorsList already has SI_MaxHistogramLength elements.

Pragmas

None.

Exceptions

None.

Examples

Extend an SI_ColorHistogram value by a color/frequency pair using the
SI_Append( ) method:

DECLARE
   myColor  SI_Color;
   myClrHist SI_ColorHistogram;
BEGIN
   -- Initialize myColor:
   myColor := new SI_Color(null, null, null);
   myColor.SI_RGBColor(10, 45, 200);
   -- Construct a histogram using a single color/frequency pair
   -- consisting of myColor and a frequency of 10.0:
   myClrHist := new SI_ColorHistogram(myColor, 10.0);
   -- Append myClrHist with another color/frequency pair:
   myColor.SI_RGBColor(60, 55, 100);
   myClrHist.SI_Append(myColor, 20.0);
END;
/

Extend an SI_ColorHistogram value by a color/frequency pair using the
SI_AppendClrHstgr( ) procedure:

DECLARE
   myColor  SI_Color;
   myClrHist SI_ColorHistogram;
BEGIN
   -- Initialize myColor:
   myColor := new SI_Color(null, null, null);
   myColor.SI_RGBColor(10, 45, 200);
   -- Construct a histogram using a single color/frequency pair
   -- consisting of myColor and a frequency of 10.0:
   myClrHist := new SI_ColorHistogram(myColor, 10.0);
   -- Append myClrHist with another color/frequency pair:
   myColor.SI_RGBColor(60, 55, 100);
   SI_AppendClrHstgr(myClrHist, myColor, 20.0);
END;
/

SI_Score( ) for SI_ColorHistogram

Format

SI_Score(image IN SI_StillImage)

RETURN DOUBLE PRECISION DETERMINISTIC;

Format of Equivalent SQL Function

SI_ScoreByClrHstgr(feature IN SI_ColorHistogram,

image IN SI_StillImage) RETURN DOUBLE PRECISION DETERMINISTIC;

Description

Determines and returns the score of the color histogram of the specified image as compared to the SI_ColorHistogram object instance to which you apply this method. This method returns a DOUBLE PRECISION value between 0 and 100. A value of 0 means that the color histogram of the specified image and the SI_ColorHistogram object instance are identical. A value of 100 indicates that the color histogram of the specified image and the SI_ColorHistogram object instance are completely different. A NULL value is returned if any one of the following is true:

The value of the SI_ColorHistogram object instance is NULL.
The value of the specified image is NULL.
The value of image.SI_Content is NULL.
The value of the color histogram feature is not supported for the format of the specified image.

Parameters

image: The image whose color histogram feature is extracted and used for comparison.
feature: The histogram to be compared with the color histogram of the specified image.

Usage Notes

None.

Pragmas

None.

Exceptions

None.

Examples

Compare a color histogram of an image to an SI_ColorHistogram value and return the score using the SI_Score method:

DECLARE
   myClrHistConstructed SI_ColorHistogram;
   myImage              SI_StillImage;
   myColor              SI_Color;
   score DOUBLE PRECISION; 
BEGIN
   -- Get a stored image:
   SELECT product_photo INTO myimage FROM PM.SI_MEDIA WHERE product_id=2; 
   -- Initialize myColor
   myColor := new SI_Color(null, null, null);
   myColor.SI_RGBColor(10, 45, 200);
   -- Construct a histogram using a single color/frequency pair
   -- consisting of myColor and a frequency of 10.0:
   myClrHistConstructed := new SI_ColorHistogram(myColor, 10.0);
   -- Compare the color histogram of the stored image to myClrHistConstructed:
   score := myClrHistConstructed.SI_Score(myImage);
   DBMS_OUTPUT.PUT_LINE('Score is ' || score);
END;
/

Compare the color histogram of an image to an SI_ColorHistogram value and return the score using the SI_ScoreByClrHstgr( ) function:

DECLARE
   myClrHistConstructed SI_ColorHistogram;
   myImage              SI_StillImage;
   myColor              SI_Color;
   score DOUBLE PRECISION; 
BEGIN
   -- Get a stored image
   SELECT product_photo INTO myimage FROM PM.SI_MEDIA WHERE product_id=2;
   -- Initialize myColor:
   myColor := new SI_Color(null, null, null);
   myColor.SI_RGBColor(10, 45, 200);
   -- Construct a histogram using a single color/frequency pair
   -- consisting of myColor and a frequency of 10.0:
   myClrHistConstructed := new SI_ColorHistogram(myColor, 10.0);
   -- Compare the color histogram of the stored image to myClrHistConstructed:
   score  := SI_ScoreByClrHstgr(myClrHistConstructed, myImage);
   DBMS_OUTPUT.PUT_LINE('Score is ' || score);
END;
/