Skip Headers
Oracle® interMedia Reference
10g Release 2 (10.2)

Part Number B14297-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

6 SQL/MM Still Image

Oracle interMedia ("interMedia") contains the following information about object types that comply with the first edition of the ISO/IEC 13249-5:2001 SQL MM Part5:StillImage standard (commonly referred to as the SQL/MM Still Image standard):

A public synonym with the corresponding object type name is created for each of these StillImage object types. Therefore, you do not need to specify the ORDSYS schema name when specifying a StillImage object type.

This chapter also includes the following topics:

See Oracle interMedia User's Guide for a list of ORDImage features that are not available for StillImage objects because the SQL/MM Still Image standard does not specify them.


SQL Functions and Procedures

For each Still Image constructor or method, there is an equivalent SQL function or procedure. Each function or procedure is presented with its equivalent constructor or method. Although the description, parameters, usage notes, and exceptions subsections frequently refer to the method, these subsections are also applicable to the equivalent SQL function or procedure.

All SQL functions and procedures are created as standalone functions in the ORDSYS schema with invoker rights. A public synonym with the corresponding function or procedure name is created for all SQL functions and procedures. Therefore, you do not need to specify the schema name when a function or procedure is called. For example:Use ORDSYS.SI_MkAvgClr(averageColor) to make the call without the synonym.Use SI_MkAvgClr(averageColor) to make the call with the synonym.All database users can call these functions and procedures.


Example Media Table and User Definition

The methods described in this reference chapter show examples based on a media table SI_MEDIA. Refer to the SI_MEDIA table definition that follows when reading through the examples. Before using methods, you will need to load some data into the table using one of the examples provided with the reference information for each object type's constructors. You will also need to verify that the user "ron" already exists or create that user if necessary.

SI_MEDIA Table Definition

CREATE TABLE PM.SI_MEDIA(
  PRODUCT_ID NUMBER(6),
  PRODUCT_PHOTO SI_StillImage,
  AVERAGE_COLOR SI_AverageColor,
  COLOR_HISTOGRAM SI_ColorHistogram,
  FEATURE_LIST SI_FeatureList,
  POSITIONAL_COLOR SI_PositionalColor,
  TEXTURE SI_Texture,
  CONSTRAINT id_pk PRIMARY KEY (PRODUCT_ID));
COMMIT;

PM.IMAGETAB Table Definition

Create this table in preparation for Example 2 for the SI_StillImage(content) method, which begins:

CREATE TABLE PM.IMAGETAB (id number, imgblob blob);
COMMIT;

User Ron Definition

For a user "ron" to use the examples, the following statements must be issued before ron executes the examples, where "/mydir" is the directory where ron will find the audio, video, and image data:

GRANT INSERT, UPDATE, SELECT, DELETE on OE.ORDERS to ron;GRANT INSERT, UPDATE, SELECT, DELETE on PM.ONLINE_MEDIA to ron;
GRANT EXECUTE on SYS.DBMS_LOB to ron;
GRANT CREATE SESSION TO ron;
CREATE OR REPLACE DIRECTORY FILE_DIR as '/mydir';
GRANT READ ON DIRECTORY FILE_DIR TO 'user';

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_AverageColor Constructors

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


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:

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:

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

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:

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;
/

SI_Color Object Type

The SI_Color object type represents color values of a digitized image as an RGB color value. It is created in the ORDSYS schema with invoker rights. It is declared as an INSTANTIABLE and NOT FINAL type.

Note:

Use the SI_Color method rather than accessing attributes directly to protect yourself from changes to the internal representation of the SI_Color object.

The SI_Color object is defined as follows:

CREATE OR REPLACE TYPE SI_Color
  AUTHID CURRENT_USER
  AS OBJECT
 (
-------------------
-- TYPE ATTRIBUTES
-------------------
redValue   INTEGER,
greenValue INTEGER,
blueValue  INTEGER,
---------------------
-- METHOD DECLARATION
---------------------
MEMBER PROCEDURE SI_RGBColor
 (redValue   IN INTEGER,
  greenValue IN INTEGER,
 blueValue  IN INTEGER)
) INSTANTIABLE
NOT FINAL;

where:


SI_Color Constructor

Only a system-default constructor is provided for the SI_Color object.


SI_Color Method

This section presents reference information on the SI_Color method used for constructing an SI_Color object using RGB color values:


SI_RGBColor( )

Format

SI_RGBColor(redValue IN INTEGER,

greenValue IN INTEGER,

blueValue IN INTEGER);

Format of Equivalent SQL Function

SI_MkRGBClr(redValue IN INTEGER,

greenValue IN INTEGER,

blueValue IN INTEGER)

RETURN SI_Color;

Description

Constructs an SI_Color object in the RGB color space using the specified red, blue, and green values.

Parameters

redValue

An integer value between 0 and 255.

greenValue

An integer value between 0 and 255.

blueValue

An integer value between 0 and 255.

Usage Notes

Pragmas

None.

Exceptions

None.

Examples

Construct an SI_Color value using the SI_RGBColor( ) method:

DECLARE
   myColor SI_Color;
BEGIN
   myColor := NEW SI_COLOR(null, null, null);
   -- Set myColor to represent the color red:
   myColor.SI_RGBColor(255, 0, 0);
END;
/

Construct an SI_Color value using the SI_MkRGBClr ( ) function:

DECLARE
   myColor SI_Color;
BEGIN
   myColor := NEW SI_COLOR(null, null, null);
   -- Set myColor to represent the color red:
   myColor := SI_MkRGBClr(255, 0, 0);
END;
/

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_ColorHistogram Constructors

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


SI_ColorHistogram(colors, frequencies)

Format

SI_ColorHistogram(SI_ColorsList IN colorsList,

SI_FrequenciesList IN colorFrequenciesList)

RETURN SELF AS RESULT DETERMINISTIC;

Description

Constructs an SI_ColorHistogram object. The following attributes are initialized:

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

Pragmas

None.

Format of Equivalent SQL Function

SI_ArrayClrHstgr(colors IN SI_ColorsList,

frequencies IN colorFrequenciesList),

RETURN SI_ColorHistogram DETERMINISTIC;

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.

Exceptions

None.

Usage Notes

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

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:

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:

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:

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:

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( )

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:

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:

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;
/

SI_FeatureList Object Type

A composite feature that contains up to four different basic features and their associated feature weights. A weight value specifies the importance given to a particular feature during image matching. Each weight value can have a value from 0.0 and 1.0. A feature weight value of 0.0 indicates that the feature is not considered for image matching. This object type is created in the ORDSYS schema with invoker rights. It is declared as an INSTANTIABLE and NOT FINAL type.

Note:

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

The SI_FeatureList object type is defined as follows:

CREATE OR REPLACE TYPE SI_FeatureList
  AUTHID CURRENT_USER
  AS OBJECT
  (
   --attributes
   AvgClrFtr_SI         SI_AverageColor,
   AvgClrFtrWght_SI     DOUBLE PRECISION,
   ClrHstgrFtr_SI       SI_ColorHistogram,
   ClrHstgrFtrWght_SI   DOUBLE PRECISION,
   PstnlClrFtr_SI       SI_PositionalColor,
   PstnlClrFtrWght_SI   DOUBLE PRECISION,
   TextureFtr_SI        SI_Texture,
   TextureFtrWght_SI    DOUBLE PRECISION,
     --
     --
     --Methods
CONSTRUCTOR FUNCTION SI_FeatureList
     (AvgClrFtr_SI             IN  SI_AverageColor,
      AvgClrFtrWght_SI         IN  DOUBLE PRECISION,
      ClrHstgrFtr_SI           IN  SI_ColorHistogram,
      ClrHstgrFtrWght_SI       IN  DOUBLE PRECISION,
      PstnlClrFtr_SI           IN  SI_PositionalColor,
      PstnlClrFtrWght_SI       IN  DOUBLE PRECISION,
      TextureFtr_SI            IN  SI_Texture,
      TextureFtrWght_SI        IN  DOUBLE PRECISION)
     return SELF AS RESULT DETERMINISTIC,
     --
     --
MEMBER PROCEDURE SI_SetFeature
     (averageColorFeature         IN  SI_AverageColor,
     averageColorFeatureWeight    IN  DOUBLE PRECISION),
     --
MEMBER PROCEDURE SI_SetFeature
    (colorHistogramFeature        IN  SI_ColorHistogram,
     colorHistogramFeatureWeight  IN  DOUBLE PRECISION),
    --
MEMBER PROCEDURE SI_SetFeature
    (positionalColorFeature       IN  SI_PositionalColor,
     positionalColorFeatureWeight IN  DOUBLE PRECISION),
    --
MEMBER PROCEDURE SI_SetFeature
    (textureFeature               IN  SI_Texture,
     textureFeatureWeight         IN  DOUBLE PRECISION),
     --
MEMBER FUNCTION SI_Score
     (image IN SI_StillImage)
      RETURN DOUBLE PRECISION DETERMINISTIC,
      --
MEMBER FUNCTION SI_AvgClrFtr( )
     RETURN SI_AverageColor DETERMINISTIC,
     PRAGMA RESTRICT_REFERENCES(SI_AvgClrFtr, WNDS, WNPS, RNDS, RNPS),
     --
MEMBER FUNCTION SI_AvgClrFtrWght( )
     RETURN DOUBLE PRECISION DETERMINISTIC,
     PRAGMA RESTRICT_REFERENCES(SI_AvgClrFtrWght, WNDS, WNPS, RNDS, RNPS),
     --
MEMBER FUNCTION SI_ClrHstgrFtr( )
     RETURN SI_ColorHistogram DETERMINISTIC,
     PRAGMA RESTRICT_REFERENCES(SI_ClrHstgrFtr, WNDS, WNPS, RNDS, RNPS),
     --
MEMBER FUNCTION SI_ClrHstgrFtrWght( )
     RETURN DOUBLE PRECISION DETERMINISTIC,
     PRAGMA RESTRICT_REFERENCES(SI_ClrHstgrFtrWght, WNDS, WNPS, RNDS, RNPS),
     --
MEMBER FUNCTION SI_PstnlClrFtr( )
     RETURN SI_PositionalColor DETERMINISTIC,
     PRAGMA RESTRICT_REFERENCES(SI_PstnlClrFtr, WNDS, WNPS, RNDS, RNPS),
     --
MEMBER FUNCTION SI_PstnlClrFtrWght( )
     RETURN DOUBLE PRECISION DETERMINISTIC,
     PRAGMA RESTRICT_REFERENCES(SI_PstnlClrFtrWght, WNDS, WNPS, RNDS, RNPS),
     --
MEMBER FUNCTION SI_TextureFtr( )
     RETURN SI_Texture DETERMINISTIC,
     PRAGMA RESTRICT_REFERENCES(SI_TextureFtr, WNDS, WNPS, RNDS, RNPS),
     --
MEMBER FUNCTION SI_TextureFtrWght( )
   RETURN DOUBLE PRECISION DETERMINISTIC,
   PRAGMA RESTRICT_REFERENCES(SI_TextureFtrWght, WNDS, WNPS, RNDS, RNPS)
   --  
)
INSTANTIABLE
NOT FINAL;
/

where:


SI_FeatureList Constructor

This section describes the SI_FeatureList constructor.

The SI_FeatureList constructor is as follows:


SI_FeatureList( )

Format

SI_FeatureList((AvgClrFtr_SI IN SI_AverageColor,

AvgClrFtrWght_SI IN DOUBLE PRECISION,

ClrHstgrFtr_SI IN SI_ColorHistogram,

ClrHstgrFtrWght_SI IN DOUBLE PRECISION,

PstnlClrFtr_SI IN SI_PositionalColor,

PstnlClrFtrWght_SI IN DOUBLE PRECISION,

TextureFtr_SI IN SI_Texture,

TextureFtrWght_SI IN DOUBLE PRECISION)

Format of Equivalent SQL Function

SI_MkFtrList(averageColorFeature IN SI_AverageColor,

averageColorFeatureWeight IN DOUBLE PRECISION,

colorHistogramFeature IN SI_ColorHistogram,

colorHistogramFeatureWeight IN DOUBLE PRECISION,

positionalColorFeature IN SI_PositionalColor,

positionalColorFeatureWeight IN DOUBLE PRECISION,

textureFeature IN SI_Texture,

textureFeatureWeight IN DOUBLE PRECISION)

RETURN SI_FeatureList;

Description

Constructs an SI_FeatureList object. All the feature and feature weight attributes are set to the corresponding values of the input parameters.

Parameters

AvgClrFtr_SI
averageColorFeature

The average color of SI_FeatureList.

AvgClrFtrWght_SI
averageColorFeatureWeight

The average color weight of SI_FeatureList. The default value is 0.0. The weight value can range from 0.0 to 1.0. A value of 0.0 indicates that the feature should not be considered during image matching.

ClrHstgrFtr_SI
colorHistogramFeature

The color histogram of SI_FeatureList.

ClrHstgrFtrWght_SI
colorHistogramFeatureWeight

The color histogram weight of SI_FeatureList. The default value is 0.0. The weight value can range from 0.0 to 1.0. A value of 0.0 indicates that the feature should not be considered during image matching.

PstnlClrFtr_SI
positionalColorFeature

The positional color of SI_FeatureList.

PstnlClrFtrWght_SI
positionalColorFeatureWeight

The positional color weight of SI_FeatureList. The default value is 0.0. The weight value can range from 0.0 to 1.0. A value of 0.0 indicates that the feature should not be considered during image matching.

TextureFtr_SI
textureFeature

The texture of SI_FeatureList.

TextureFtrWght_SI
textureFeatureWeight

The texture weight of SI_FeatureList. The default value is 0.0. The weight value can range from 0.0 to 1.0. A value of 0.0 indicates that the feature should not be considered during image matching.

Pragmas

None.

Exceptions

None.

Usage Notes

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

Examples

Create an SI_FeatureList object using the SI_FeatureList( ) constructor:

DECLARE
   myimage       SI_StillImage;
   myAvgColor    SI_AverageColor;
   myColorHist   SI_ColorHistogram;
   myPosColor    SI_PositionalColor;
   myTexture     SI_Texture;
   myFeatureList SI_FeatureList;
BEGIN
   SELECT product_photo INTO myimage FROM pm.si_media WHERE product_id=1 FOR
   UPDATE;
   myAvgColor := NEW SI_AverageColor(myimage);
   myColorHist := NEW SI_ColorHistogram(myimage);
   myPosColor := NEW SI_PositionalColor(myimage);
   myTexture := NEW SI_Texture(myimage);
   myFeatureList := new SI_FeatureList(myAvgColor,0.25,myColorHist,0.35,
                                       myPosColor,0.10, myTexture,0.5);
   UPDATE pm.si_media SET feature_list = myFeatureList WHERE product_id=1;
   COMMIT;
END;
/

Create an SI_FeatureList object using the SI_MkFtrList( ) function:

DECLARE
   myimage       SI_StillImage;
   myAvgColor    SI_AverageColor;
   myColorHist   SI_ColorHistogram;
   myPosColor    SI_PositionalColor;
   myTexture     SI_Texture;
   myFeatureList SI_FeatureList;
BEGIN
   SELECT product_photo INTO myimage 
     FROM pm.si_media WHERE product_id=2 FOR
    UPDATE;
   myAvgColor := NEW SI_AverageColor(myimage);
   myColorHist := NEW SI_ColorHistogram(myimage);
   myPosColor := NEW SI_PositionalColor(myimage);
   myTexture := NEW SI_Texture(myimage);
   myFeatureList := SI_MkFtrList(myAvgColor,0.25,myColorHist,0.35,
                    myPosColor,0.10, myTexture,0.5);
   UPDATE pm.si_media SET feature_list = myFeatureList WHERE product_id=2;
  COMMIT;
END;
/

SI_FeatureList Methods

This section presents reference information on the SI_FeatureList methods used for image matching, which are the following:


SI_AvgClrFtr( )

Format

SI_AvgClrFtr( )

RETURN SI_AverageColor DETERMINISTIC;

Format of Equivalent SQL Function

SI_GetAvgClrFtr(featureList IN SI_FeatureList)

RETURN SI_AverageColor DETERMINISTIC;

Description

Returns the value of the AvgClrFtr_SI attribute of the specified SI_FeatureList object.

Parameters

featureList

The SI_FeatureList object for which you want the AvgClrFtr_SI attribute returned.

Usage Notes

None.

Method Pragmas

PRAGMA RESTRICT_REFERENCES(SI_AvgClrFtr, WNDS, WNPS, RNDS, RNPS)

Function Pragmas

PRAGMA RESTRICT_REFERENCES(SI_GetAvgClrFtr, WNDS, WNPS, RNDS, RNPS)

Exceptions

None.

Examples

Get the value of the AvgClrFtr_SI attribute of an SI_FeatureList object using the SI_AvgClrFtr( ) method:

DECLARE
   myFeatureList SI_FeatureList;
   AvgColor    SI_AverageColor;
BEGIN
   SELECT feature_list INTO myFeatureList FROM pm.si_media 
     WHERE product_id=1;
   AvgColor := myFeatureList.SI_AvgClrFtr( );
END;
/

Get the AvgClrFtr_SI attribute of an SI_FeatureList object using the SI_GetAvgClrFtr( ) function:

DECLARE
   myFeatureList SI_FeatureList;
   AvgColor      SI_AverageColor;
BEGIN
   SELECT feature_list INTO myFeatureList FROM pm.si_media WHERE product_id=1;
   AvgColor  := SI_GetAvgClrFtr(myFeatureList);
END;
/

SI_AvgClrFtrWght( )

Format

SI_AvgClrFtrWght( )

RETURN DOUBLE PRECISION DETERMINISTIC;

Format of Equivalent SQL Function

SI_GetAvgClrFtrW(featureList IN SI_FeatureList)

RETURN DOUBLE PRECISION DETERMINISTIC;

Description

Returns the value of the AvgClrFtrWght_SI attribute of the specified SI_FeatureList object.

Parameters

featureList

The SI_FeatureList object for which you want the AvgClrFtrWght_SI attribute returned.

Usage Notes

None.

Method Pragmas

PRAGMA RESTRICT_REFERENCES(SI_AvgClrFtrWght, WNDS, WNPS, RNDS, RNPS)

Function Pragmas

PRAGMA RESTRICT_REFERENCES(SI_GetAvgClrFtrW, WNDS, WNPS, RNDS, RNPS)

Exceptions

None.

Examples

Get the AvgClrFtrWght_SI attribute value of an SI_FeatureList object using the SI_AvgClrFtrWght( ) method:

DECLARE
   myFeatureList SI_FeatureList;
   AvgColorWght  DOUBLE PRECISION;
BEGIN
   SELECT feature_list INTO myFeatureList FROM pm.si_media 
     WHERE product_id=1;
   AvgColorWght := myFeatureList.SI_AvgClrFtrWght( );
   DBMS_OUTPUT.PUT_LINE('Average color feature weight is ' || AvgColorWght);
END;
/

Get the AvgClrFtrWght_SI attribute value of an SI_FeatureList object using the SI_GetAvgClrFtrW( ) function:

DECLARE
   myFeatureList SI_FeatureList;
   AvgColorWght  DOUBLE PRECISION;
BEGIN
   SELECT feature_list INTO myFeatureList FROM pm.si_media 
     WHERE product_id=1;
   AvgColorWght := SI_GetAvgClrFtrW(myFeatureList);
   DBMS_OUTPUT.PUT_LINE('Average color feature weight is ' || AvgColorWght);
END;
/

SI_ClrHstgrFtr( )

Format

SI_ClrHstgrFtr( )

RETURN SI_ColorHistogram DETERMINISTIC;

Format of Equivalent SQL Function

SI_GetClrHstgrFtr(featureList IN SI_FeatureList)

RETURN SI_ColorHistogram DETERMINISTIC;

Description

Returns the value of the ClrHstgrFtr_SI attribute of the specified SI_FeatureList object.

Parameters

featureList

The SI_FeatureList object for which you want the ColorHistogram_SI attribute returned.

Usage Notes

None.

Method Pragmas

PRAGMA RESTRICT_REFERENCES(SI_ClrHstgrFtr, WNDS, WNPS, RNDS, RNPS)

Function Pragmas

PRAGMA RESTRICT_REFERENCES(SI_GetClrHstgrFtr, WNDS, WNPS, RNDS, RNPS)

Exceptions

None.

Examples

Get the value of the ClrHstgrFtr_SI attribute of an SI_FeatureList object using the SI_ClrHstgrFtr( ) method:

DECLARE
   myFeatureList SI_FeatureList;
   ClrHstgrFtr   SI_ColorHistogram;
BEGIN
   SELECT feature_list INTO myFeatureList FROM pm.si_media 
     WHERE product_id=1;
   ClrHstgrFtr := myFeatureList.SI_ClrHstgrFtr( );
END;
/

Get the value of the ClrHstgrFtr_SI attribute of an SI_FeatureList object using the SI_GetClrHstgrFtr( ) function:

DECLARE
   myFeatureList SI_FeatureList;
   ClrHstgrFtr   SI_ColorHistogram;
BEGIN
   SELECT feature_list INTO myFeatureList FROM pm.si_media 
     WHERE product_id=1;
   ClrHstgrFtr := SI_GetClrHstgrFtr(myFeatureList);
END;
/

SI_ClrHstgrFtrWght( )

Format

SI_ClrHstgrFtrWght( )

RETURN DOUBLE PRECISION DETERMINISTIC;

Format of Equivalent SQL Function

SI_GetClrHstgrFtrW(featureList IN SI_FeatureList)

RETURN DOUBLE PRECISION DETERMINISTIC;

Description

Returns the value of the ClrHstgrFtrWght_SI attribute of the specified SI_FeatureList object.

Parameters

featureList

The SI_FeatureList object for which you want the ClrHstgrFtrWght_SI attribute returned.

Usage Notes

None.

Method Pragmas

PRAGMA RESTRICT_REFERENCES(SI_ClrHstgrFtrWght, WNDS, WNPS, RNDS, RNPS)

Function Pragmas

PRAGMA RESTRICT_REFERENCES(SI_GetClrHstgrFtrW, WNDS, WNPS, RNDS, RNPS)

Exceptions

None.

Examples

Get the value of the ClrHstgrFtrWght_SI attribute of an SI_FeatureList object using the SI_ClrHstgrFtrWght( ) method:

DECLARE
   myFeatureList    SI_FeatureList;
   ClrHstgrFtrWght  DOUBLE PRECISION;
BEGIN
  SELECT feature_list INTO myFeatureList FROM pm.si_media 
    WHERE product_id=1;
  ClrHstgrFtrWght := myFeatureList.SI_ClrHstgrFtrWght( );
  DBMS_OUTPUT.PUT_LINE('Color histogram feature weight is ' || ClrHstgrFtrWght);
END;
/

Get the value of the ClrHstgrFtrWght_SI attribute of an SI_FeatureList object using the SI_GetClrHstgrFtrW( ) function:

DECLARE
  myFeatureList    SI_FeatureList;
   ClrHstgrFtrWght  DOUBLE PRECISION;
BEGIN
  SELECT feature_list INTO myFeatureList FROM pm.si_media 
   WHERE product_id=1;
  ClrHstgrFtrWght := SI_GetClrHstgrFtrW(myFeatureList);
  DBMS_OUTPUT.PUT_LINE('Color histogram feature weight is ' || ClrHstgrFtrWght);
END;
/

SI_PstnlClrFtr( )

Format

SI_PstnlClrFtr( )

RETURN SI_PositionalColor DETERMINISTIC;

Format of Equivalent SQL Function

SI_GetPstnlClrFtr(featureList IN SI_FeatureList)

RETURN SI_PositionalColor DETERMINISTIC;

Description

Returns the value of the PstnlClrFtr_SI attribute of the specified SI_FeatureList object.

Parameters

featureList

The SI_FeatureList object for which you want the PstnlClrFtr_SI attribute returned.

Usage Notes

None.

Method Pragmas

PRAGMA RESTRICT_REFERENCES(SI_PstnlClrFtr, WNDS, WNPS, RNDS, RNPS)

Function Pragmas

PRAGMA RESTRICT_REFERENCES(SI_GetPstnlClrFtr, WNDS, WNPS, RNDS, RNPS)

Exceptions

None.

Examples

Get the value of the PstnlClrFtr_SI attribute of an SI_FeatureList object using the SI_PstnlClrFtr( ) method:

DECLARE
   myFeatureList SI_FeatureList;
   PstnlClrFtr   SI_PositionalColor;
BEGIN
   SELECT feature_list INTO myFeatureList FROM pm.si_media 
     WHERE product_id=1;
   PstnlClrFtr := myFeatureList.SI_PstnlClrFtr( );
END;
/

Get the value of the PstnlClrFtr_SI attribute of an SI_FeatureList object using the SI_GetPstnlClrFtr( ) function:

DECLARE
   myFeatureList SI_FeatureList;
   PstnlClrFtr   SI_PositionalColor;
BEGIN
   SELECT feature_list INTO myFeatureList FROM pm.si_media WHERE product_id=1;
   PstnlClrFtr := SI_GetPstnlClrFtr(myFeatureList);
END;
/

SI_PstnlClrFtrWght( )

Format

SI_PstnlClrFtrWght( )

RETURN DOUBLE PRECISION DETERMINISTIC;

Format of Equivalent SQL Function

SI_GetPstnlClrFtrW(featureList IN SI_FeatureList)

RETURN DOUBLE PRECISION DETERMINISTIC;

Description

Returns the value of the PstnlClrFtrWght_SI attribute of the specified SI_FeatureList object.

Parameters

featureList

The SI_FeatureList object for which you want the PstnlClrFtrWght_SI attribute returned.

Usage Notes

None.

Method Pragmas

PRAGMA RESTRICT_REFERENCES(SI_PstnlClrFtrWght, WNDS, WNPS, RNDS, RNPS)

Function Pragmas

PRAGMA RESTRICT_REFERENCES(SI_GetPstnlClrFtrW, WNDS, WNPS, RNDS, RNPS)

Exceptions

None.

Examples

Get the value of the PstnlClrFtrWght_SI attribute of an SI_FeatureList object using the SI_PstnlClrFtrWght( ) method:

DECLARE
   myFeatureList    SI_FeatureList;
   PstnlClrFtrWght  DOUBLE PRECISION;
BEGIN
 SELECT feature_list INTO myFeatureList FROM pm.si_media 
   WHERE product_id=1;
 PstnlClrFtrWght := myFeatureList.SI_PstnlClrFtrWght( );
 DBMS_OUTPUT.PUT_LINE('Positional color feature weight is ' || PstnlClrFtrWght);
END;
/

Get the value of the PstnlClrFtrWght_SI attribute of an SI_FeatureList object using the SI_GetPstnlClrFtrW( ) function:

DECLARE
   myFeatureList    SI_FeatureList;
   PstnlClrFtrWght  DOUBLE PRECISION;
BEGIN
 SELECT feature_list INTO myFeatureList FROM pm.si_media 
   WHERE product_id=1;
 PstnlClrFtrWght := SI_GetPstnlClrFtrW(myFeatureList);
 DBMS_OUTPUT.PUT_LINE('Positional color feature weight is ' || PstnlClrFtrWght);
END;
/

SI_Score( ) for SI_FeatureList

Format

SI_Score(image IN SI_StillImage)

RETURN DOUBLE PRECISION DETERMINISTIC;

Format of Equivalent SQL Function

SI_ScoreByFtrList(featureList IN SI_FeatureList,

image IN SI_StillImage)

RETURN DOUBLE PRECISION DETERMINISTIC;

Description

Determines and returns the score of a specified image to a given SI_FeatureList value. The lower the returned score value, the better the image is characterized by the SI_FeatureList object used for scoring the image. The return score value is computed as follows:

Let n be the number of non-NULL feature attributes of the FeatureList object to which you are applying the method. For i ranging from 1 to n, let fi be the feature attribute and Wi be the value of the corresponding feature weight. The result is the sum of fi.SI_Score(image) * Wi divided by the sum of Wi. The process by which the score value is determined can also be described by the following expression:

Description of si_score_featurelist.gif follows
Description of the illustration si_score_featurelist.gif

A DOUBLE PRECISION value between 0 and 100 is returned. A value of 0 means that the image is identical to the feature list object. A value of 100 means that the image is completely different from the feature list object.

Parameters

featureList

The SI_FeatureList object to which the image will be compared.

image

The image whose features are extracted and compared with the specified SI_FeatureList object to get a score value.

Usage Notes

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

Pragmas

None.

Exceptions

None.

Examples

Compare an image to an SI_FeatureList value and return the score using the SI_Score( ) method:

DECLARE
   myimage       SI_StillImage;
   myFeatureList SI_FeatureList;
   score         DOUBLE PRECISION;
BEGIN
  --Check to see if stored feature list is accurate for the stored image:
  SELECT feature_list INTO myFeatureList FROM pm.si_media 
    WHERE product_id=1;
  SELECT product_photo INTO myimage FROM pm.si_media 
    WHERE product_id=1;
  -- The score will be 0 if the feature list is accurate for the stored image:
  score := myFeatureList.SI_Score(myimage);
  DBMS_OUTPUT.PUT_LINE('Score is ' || score);
END;
/

Compare an image to an SI_FeatureList value and return the score using the SI_ScoreByFtrList( ) function:

DECLARE
    score         DOUBLE PRECISION;
    myimage       SI_StillImage;
    myFeatureList SI_PositionalColor;
BEGIN
  SELECT feature_list INTO myFeatureList FROM pm.si_media 
    WHERE product_id=1;
  SELECT product_photo INTO myimage FROM pm.si_media 
    WHERE product_id=1;
   score := SI_ScoreByFtrList(myFeatureList, myimage);
   DBMS_OUTPUT.PUT_LINE('Score is ' || score);
END;
/

SI_SetFeature(averageColorFeature, averageColorFeatureWeight)

Format

SI_SetFeature(averageColorFeature IN SI_AverageColor,

averageColorFeatureWeight IN DOUBLE PRECISION);

Format of Equivalent SQL Procedure

SI_SetAvgClrFtr (featureList IN OUT NOCOPY SI_FeatureList,

averageColorFeature IN SI_AverageColor,

averageColorFeatureWeight IN DOUBLE PRECISION);

Description

Modifies the SI_AvgClrFtr and SI_AvgClrFtrWght attributes in the specified SI_FeatureList object.

Parameters

averageColorFeature

The new average color value.

averageColorFeatureWeight

The new average color weight.

featureList

The SI_FeatureList object for which you want to update the averageColorFeature and averageColorFeatureWeight values.

Usage Notes

Pragmas

None.

Exceptions

None.

Examples

Modify the SI_AvgClrFtr and SI_AvgClrFtrWght attributes in an SI_FeatureList value using the SI_SetFeature(averageColorFeature, averageColorFeatureWeight) method:

DECLARE
   myColor       SI_Color;
   myAvgColor    SI_AverageColor;   
   myFeatureLIst SI_FeatureList;
BEGIN
   -- Create a new average color:
   myColor := NEW SI_COLOR(null, null, null);
   myColor.SI_RGBColor(30, 120, 200);
   myAvgColor := NEW SI_AverageColor(myColor);
   -- Get an existing feature list:
   SELECT feature_list INTO myFeatureList FROM pm.si_media WHERE product_id=1;
   -- Modify the average color and weight of the SI_FeatureList value:
   myFeatureList.SI_SetFeature(myAvgColor, 0.5);
END;
/

Modify the SI_AvgClrFtr and SI_AvgClrFtrWght attributes in an SI_FeatureList object using the SI_SetAvgClrFtr ( ) procedure:

DECLARE
   myColor       SI_Color;
   myAvgColor    SI_AverageColor;
   myFeatureLIst SI_FeatureList;
BEGIN
   myColor := NEW SI_COLOR(null, null, null);
   myColor.SI_RGBColor(30, 120, 200);
   myAvgColor := NEW SI_AverageColor(myColor);
   SELECT feature_list INTO myFeatureList FROM pm.si_media WHERE product_id=1;
   SI_SetAvgClrFtr(myFeatureList, myAvgColor, 0.5);
END;
/

SI_SetFeature(colorHistogramFeature, colorHistogramFeatureWeight)

Format

SI_SetFeature(colorHistogramFeature IN SI_ColorHistogram,

colorHistogramFeatureWeight IN DOUBLE PRECISION);

Format of Equivalent SQL Procedure

SI_SetClrHstgrFtr (featureList IN OUT NOCOPY SI_FeatureList,

colorHistogramFeature IN SI_ColorHistogram,

colorHistogramFeatureWeight IN DOUBLE PRECISION);

Description

Modifies the ClrHstgrFtr_SI attribute and ClrHstgrFtrWght_SI attribute in the specified SI_FeatureList object.

Parameters

colorHistogramFeature

The new color histogram value.

colorHistogramFeatureWeight

The new color histogram weight value.

featureList

The SI_FeatureList object for which you want to update the colorHistogram and colorHistogramFeatureWeight attribute values.

Usage Notes

Pragmas

None.

Exceptions

None.

Examples

Modify the color histogram feature and feature weight of an SI_FeatureList object using the SI_SetFeature( ) method:

DECLARE
   myColor       SI_Color;
   myClrHist   SI_ColorHistogram;   
   myFeatureList SI_FeatureList;
BEGIN
   myColor := new SI_Color(null, null, null);
   myColor.SI_RGBColor(10, 45, 200);
   myClrHist := new SI_ColorHistogram(myColor, 10.0);
   SELECT feature_list INTO myFeatureList FROM pm.si_media WHERE product_id=1;
   myFeatureList.SI_SetFeature(myClrHist, 10.5);
END;
/

Modify the color histogram feature and feature weight of an SI_FeatureList object using the SI_SetClrHstgrFtr( ) procedure:

DECLARE
   myColor       SI_Color;
   myClrHist   SI_ColorHistogram;   
   myFeatureList SI_FeatureList;
BEGIN
   myColor := new SI_Color(null, null, null);
   myColor.SI_RGBColor(10, 45, 200);
   myClrHist := new SI_ColorHistogram(myColor, 10.0);
   SELECT feature_list INTO myFeatureList FROM pm.si_media 
     WHERE product_id=1;
   SI_SetClrHstgrFtr(myFeatureList, myClrHist, 10.5);
END;
/

SI_SetFeature(positionalColorFeature, positionalColorFeatureWeight)

Format

SI_SetFeature(positionalColorFeature IN SI_PositionalColor,

positionalColorFeatureWeight IN DOUBLE PRECISION);

Format of Equivalent SQL Procedure

SI_SetPstnlClrFtr(featureList IN OUT NOCOPY SI_FeatureList,

positionalColorFeature IN SI_PositionalColor,

positionalColorFeatureWeight IN DOUBLE PRECISION);

Description

Modifies the PstnlClrFtr_SI and the PstnlClrFtrWght_SI attributes in the specified SI_FeatureList object.

Parameters

positionalColorFeature

The new positional color value.

positionalColorFeatureWeight

The new positional color weight value.

featureList

The SI_FeatureList object for which you want to update the positionalColor and positionalColorFeatureWeight attributes.

Usage Notes

Pragmas

None.

Exceptions

None.

Examples

Modify the positional color feature and feature weight of one image by updating it with the positional color feature value from another image using the SI_SetFeature( ) method and specifying a desired feature weight value:

DECLARE
   PosColor2        SI_PositionalColor;
   myFeatureList    SI_FeatureList;
BEGIN
   SELECT positional_color INTO PosColor2  FROM pm.si_media 
     WHERE product_id=2;
   SELECT feature_list INTO myFeatureList FROM pm.si_media 
     WHERE product_id=1;
   myFeatureList.SI_SetFeature(PosColor2, 10.5);
END;
/

Modify the positional color feature and feature weight of one image by updating it with the positional color feature value from another image using the SI_SetPstnlClrFtr( ) procedure and specifying a desired feature weight value:

DECLARE
   PosColor1        SI_PositionalColor;
   myFeatureList2   SI_FeatureList;
   myFeatureListnew SI_FeatureList;
BEGIN
   SELECT positional_color INTO PosColor1  
     FROM pm.si_media WHERE product_id=1;
   SELECT feature_list INTO myFeatureList2 
     FROM pm.si_media WHERE product_id=2;
   SI_SetPstnlClrFtr(myFeatureList2, PosColor1, 10.5);
END;
/

SI_SetFeature(textureFeature, textureFeatureWeight)

Format

SI_SetFeature(textureFeature IN SI_Texture,

textureFeatureWeight IN DOUBLE PRECISION);

Format of Equivalent SQL Procedure

SI_SetTextureFtr(featureList IN OUT NOCOPY SI_FeatureList,

textureFeature IN SI_Texture,

textureFeatureWeight IN DOUBLE PRECISION);

Description

Modifies the TextureFtr_SI attribute and TextureFtrWght_SI attribute in the specified SI_FeatureList object.

Parameters

textureFeature

The new texture value.

textureFeatureWeight

The new texture weight value.

featureList

The SI_FeatureList object for which you want to update the textureFeature and textureFeatureWeight attributes.

Usage Notes

Pragmas

None.

Exceptions

None.

Examples

Modify the texture feature and feature weight of an SI_FeatureList value using the SI_SetFeature( ) method:

DECLARE
   texture1         SI_Texture;
   myFeatureList1   SI_FeatureList;
   myFeatureList2   SI_FeatureList;
BEGIN
   SELECT texture INTO texture1  FROM pm.si_media 
     WHERE product_id=1;
   SELECT feature_list INTO myFeatureList1 FROM pm.si_media 
     WHERE product_id=2;
   myFeatureList2.SI_SetFeature(texture1, 20);
END;/

Modify the texture feature and feature weight of an SI_FeatureList value using the SI_SetTextureFtr( ) procedure:

DECLARE
   texture1         SI_Texture;
   myFeatureList    SI_FeatureList;
BEGIN
   SELECT texture INTO texture1  FROM pm.si_media 
     WHERE product_id=1;
   SELECT feature_list INTO myFeatureList FROM pm.si_media 
     WHERE product_id=2;
   SI_SetTextureFtr(myFeatureList, texture1, 20);
END;/


SI_TextureFtr( )

Format

SI_TextureFtr( )

RETURN SI_Texture DETERMINISTIC;

Format of Equivalent SQL Function

SI_GetTextureFtr (featureList IN SI_FeatureList)

RETURN SI_Texture DETERMINISTIC;

Description

Returns the value of the TextureFtr_SI attribute of the specified SI_FeatureList object.

Parameters

featureList

The SI_FeatureList object for which you want the TextureFtr_SI attribute returned.

Usage Notes

None.

Method Pragmas

PRAGMA RESTRICT_REFERENCES(SI_TextureFtr, WNDS, WNPS, RNDS, RNPS)

Function Pragmas

PRAGMA RESTRICT_REFERENCES(SI_GetTextureFtr, WNDS, WNPS, RNDS, RNPS)

Exceptions

None.

Examples

Get the value of the TextureFtr_SI attribute of an SI_FeatureList object using the SI_TextureFtr( ) method:

DECLARE
   myFeatureList SI_FeatureList;
   mytexture     SI_Texture;
BEGIN
   SELECT feature_list INTO myFeatureList FROM pm.si_media 
     WHERE product_id=1;
   mytexture := myFeatureList.SI_TextureFtr( );
END;
/

Get the value of the TextureFtr_SI attribute of an SI_FeatureList object using the SI_GetTextureFtr ( ) function:

DECLARE
   myFeatureList SI_FeatureList;
   mytexture       SI_Texture;
BEGIN
   SELECT feature_list INTO myFeatureList FROM pm.si_media WHERE product_id=1;
   mytexture := SI_GetTextureFtr(myFeatureList);
END;
/

SI_TextureFtrWght( )

Format

SI_TextureFtrWght( )

RETURN DOUBLE PRECISION DETERMINISTIC;

Format of Equivalent SQL Function

SI_GetTextureFtrW(featureList in SI_FeatureList)

RETURN DOUBLE PRECISION DETERMINISTIC;

Description

Returns the value of the TextureFtrWght_SI attribute of the specified SI_FeatureList object.

Parameters

featureList

The SI_FeatureList object for which you want the TextureFtrWght_SI attribute returned.

Usage Notes

None.

Method Pragmas

PRAGMA RESTRICT_REFERENCES(SI_TextureFtrWght, WNDS, WNPS, RNDS, RNPS)

Function Pragmas

PRAGMA RESTRICT_REFERENCES(SI_GetTextureFtrW, WNDS, WNPS, RNDS, RNPS)

Exceptions

None.

Examples

Get the TextureFtrWght_SI attribute of an SI_FeatureList object using the SI_TextureFtrWght( ) method:

DECLARE
   myFeatureList SI_FeatureList;
   myTextureWght DOUBLE PRECISION;
BEGIN
   SELECT feature_list INTO myFeatureList FROM pm.si_media 
     WHERE product_id=1;
   myTextureWght := myFeatureList.SI_TextureFtrWght( );
   DBMS_OUTPUT.PUT_LINE('Texture feature weight is ' || myTextureWght);
END;
/

Get the value of the TextureFtrWght_SI attribute of an SI_FeatureList object using the SI_GetTextureFtrW( ) function:

DECLARE
   myFeatureList SI_FeatureList;
   myTextureWght DOUBLE PRECISION;
BEGIN
   SELECT feature_list INTO myFeatureList FROM pm.si_media 
     WHERE product_id=1;
   myTextureWght := SI_GetTextureFtrW(myFeatureList);
   DBMS_OUTPUT.PUT_LINE('Texture feature weight is ' || myTextureWght);
END;
/

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.)

Note:

Use the SI_PositionalColor object constructor and method rather than accessing attributes directly to protect yourself from changes to the internal representation of the SI_PositionalColor object.

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_PositionalColor Constructor

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


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:

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

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:

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;
/

SI_StillImage Object Type

The SI_StillImage object type represents digital images with inherent image characteristics such as height, width, format, and so on. It is created in the ORDSYS schema with invoker rights and it is declared as INSTANTIABLE and NOT FINAL.

Note:

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

This object type is defined as follows:

CREATE OR REPLACE TYPE SI_StillImage
AUTHID CURRENT_USER
AS OBJECT
(
-------------------
-- TYPE ATTRIBUTES
-------------------
content_SI           ORDSYS.ORDSOURCE,
contentLength_SI     INTEGER,
format_SI            VARCHAR2(4000),
height_SI            INTEGER,
width_SI             INTEGER,
-- Oracle attribute extensions
mimeType_ora          VARCHAR2(4000),
contentFormat_ora     VARCHAR2(4000),
compressionFormat_ora VARCHAR2(4000),
-- Flag to
retainFeatures_SI     INTEGER,
-- Oracle extension attributes to cache image features
 averageColorSpec_ora SI_Color,
 colorsList_ora       colorsList,
 frequenciesList_ora  colorFrequenciesList,
 colorPositions_ora   colorPositions,
 textureEncoding_ora  textureEncoding,
-- METHOD DECLARATION
---------------------
-- CONSTRUCTORS
--
CONSTRUCTOR FUNCTION
SI_StillImage(content IN BLOB) RETURN SELF as RESULT DETERMINISTIC,
CONSTRUCTOR FUNCTION
SI_StillImage(content IN BLOB, 
              explicitFormat IN VARCHAR2  
              ) RETURN SELF AS RESULT DETERMINISTIC,
CONSTRUCTOR FUNCTION
SI_StillImage(content IN BLOB, 
              explicitFormat IN VARCHAR2, 
              height IN INTEGER, 
              width IN INTEGER)  RETURN SELF as RESULT DETERMINISTIC,
              
-- Accessor methods for StillImage attributes 
MEMBER FUNCTION SI_Height RETURN INTEGER DETERMINISTIC,
PRAGMA RESTRICT_REFERENCES(SI_Height, WNDS, WNPS, RNDS, RNPS),

MEMBER FUNCTION SI_Width RETURN INTEGER DETERMINISTIC,
PRAGMA RESTRICT_REFERENCES(SI_Width, WNDS, WNPS, RNDS, RNPS),

MEMBER FUNCTION SI_Format RETURN VARCHAR2 DETERMINISTIC,
PRAGMA RESTRICT_REFERENCES(SI_Format, WNDS, WNPS, RNDS, RNPS),

MEMBER FUNCTION SI_Content RETURN BLOB DETERMINISTIC,
PRAGMA RESTRICT_REFERENCES(SI_Content, WNDS, WNPS, RNDS, RNPS),

MEMBER FUNCTION SI_ContentLength RETURN INTEGER DETERMINISTIC,
PRAGMA RESTRICT_REFERENCES(SI_ContentLength, WNDS, WNPS, RNDS, RNPS),

--Accessor method for retainFeatures_SI attribute
MEMBER FUNCTION SI_retainFeatures return BOOLEAN DETERMINISTIC,
PRAGMA RESTRICT_REFERENCES(SI_retainFeatures, WNDS, WNPS, RNDS, RNPS),
-- Methods associated with image processing
MEMBER PROCEDURE SI_SetContent(content IN BLOB),
MEMBER PROCEDURE SI_ChangeFormat(targetFormat IN VARCHAR2),
MEMBER FUNCTION SI_Thumbnail( )
                     return SI_StillImage DETERMINISTIC,
MEMBER FUNCTION SI_Thumbnail(height IN INTEGER, 
                              width IN INTEGER)
                     return SI_StillImage DETERMINISTIC,
-- Methods associated with the Oracle extension for image feature caching
MEMBER PROCEDURE   SI_InitFeatures,
MEMBER PROCEDURE   SI_ClearFeatures
) INSTANTIABLE
NOT FINAL;
/

where:


SI_StillImage Constructors

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

Note:

To construct SI_StillImage objects, Oracle strongly recommends that you use one of the constructors in the previous list, not the default SI_StillImage object constructor.

SI_StillImage(content)

Format

SI_StillImage(content IN BLOB)

RETURN SELF as RESULT DETERMINISTIC;

Format of Equivalent SQL Function

SI_MkStillImage1(content in BLOB)

RETURN SI_StillImage DETERMINISTIC;

Description

Returns a new SI_StillImage object. This constructor initializes the SI_StillImage attributes as follows:

Parameters

content

The image data.

Pragmas

None.

Exceptions

ORDImageSIExceptions.NULL_CONTENT

This exception is raised if the content parameter is NULL.

See Appendix G for more information about this exception.

Usage Notes

None.

Examples

The following examples demonstrate how to insert a StillImage object into a database table. The first two examples use the SI_StillImage(content) constructor; the third example uses the SI_MkStillImage1( ) function. In addition, the first and third examples use the PL/SQL package DBMS_LOB.LOADFROM FILE and the second example uses SQL*Loader. Typically, you would use the PL/SQL package if you were inserting objects one-by-one, and you would use SQL*Loader to insert objects in a batch job.

Example 1: Insert a BLOB into a StillImage object column using DBMS_LOB.LOADFROMFILE.

This example demonstrates how to insert an image into a StillImage object column using the PL/SQL package DBMS_LOB.LOADFROMFILE.

Connect as SYSDBA, create a BFILE to indicate where the image you want to load is located, and grant the READ privilege to the user who will be loading the image:

DECLARE
   lobd blob;
   fils BFILE := BFILENAME('FILE_DIR','speaker.jpg');
BEGIN
   DBMS_LOB.CREATETEMPORARY(lobd, TRUE);
   DBMS_LOB.fileopen(fils, DBMS_LOB.file_readonly);
   DBMS_LOB.LOADFROMFILE(lobd, fils, DBMS_LOB.GETLENGTH(fils));
   DBMS_LOB.FILECLOSE(fils);
   INSERT INTO PM.SI_MEDIA (product_id, product_photo) 
       VALUES(1, new ORDSYS.SI_StillImage(lobd));
   DBMS_LOB.FREETEMPORARY(lobd);
   COMMIT;
END;
/

Example 2: Insert a BLOB into a StillImage object column using SQL*Loader.

This example demonstrates how to insert a StillImage object into a database table using SQL*Loader. This example assumes that the image file, speaker.jpg, is in the same directory as the parameter file and the control file.

  1. From the command prompt, run SQL*Loader:

    sqlldr parfile= blob_load.par
    
    
  2. When the phrase 'commit point reached' is returned, connect to the database as user ron and issue a SQL COMMIT statement. (This example assumes that user ron has been created and granted privileges as shown in Example 1.)

    sqlplus
    CONNECT ron/ron
    
    
  3. Run the SQL script to insert the SI_StillImage object in the SI_MEDIA table:

    @insert_object.sql
    
    

This example assumes that the blob_load.par, blob_load.ctl, and insert_object.sql files have been defined as follow and that the PM.IMAGETAB table has been created as shown in Example Media Table and User Definition.

Example 3: Create a new SI_StillImage object using the SI_MkStillImage1( ) function and the PL/SQL package DBMS_LOB.LOADFROM FILE:

DECLARE
   lobd blob;
   fils BFILE := BFILENAME('FILE_DIR','modem.jpg');
BEGIN
   DBMS_LOB.CREATETEMPORARY(lobd, TRUE);
   DBMS_LOB.FILEOPEN(fils, dbms_lob.file_readonly);
   DBMS_LOB.LOADFROMFILE(lobd, fils, dbms_lob.getlength(fils));
   DBMS_LOB.FILECLOSE(fils);
   INSERT INTO PM.SI_MEDIA (product_id, product_photo) 
     VALUES (66, SI_MkStillImage1(lobd));
   DBMS_LOB.FREETEMPORARY(lobd);
   COMMIT;
END;
/

SI_StillImage(content, explicitFormat)

Format

SI_StillImage(content IN BLOB,

explicitFormat IN VARCHAR2)

RETURN SELF as RESULT DETERMINISTIC;

Format of Equivalent SQL Function

SI_MkStillImage2(content in BLOB, explicitFormat in VARCHAR2)

RETURN SI_StillImage DETERMINISTIC;

Description

Constructs an SI_StillImage object from a specified image and a format. This constructor lets you specify the image format when the specified image is in an unsupported image format. Query the SI_IMAGE_FORMATS view in SI_INFORMTN_SCHEMA for a list of the supported image formats.

This constructor initializes the SI_StillImage attributes as follows:

Parameters

content

The image data.

explicitFormat

The format that you want interMedia to use if the specified image is in an unsupported image format.

Pragmas

None.

Exceptions

ORDImageSIExceptions.NULL_CONTENT

This exception is raised if the content parameter is NULL.

See Appendix G for more information about this exception.

Usage Notes

An error is returned if the explicitFormat parameter is a NULL value, or if either of the following statements is true:

The following table presents values for the explicitFormat parameter and the actual image format, and whether or not that combination of values will result in an error. A image format of NULL indicates that the format cannot be extracted from the image.

explicitFormat Image Format Error Returned?
GIF (a supported format) GIF No
GIF (a supported format) JPEG Yes
xyz (an unsupported format) GIF Yes
xyz (an unsupported format) Null No

Examples

Create an SI_StillImage object from a specified image and format using the SI_StillImage(content, explicitFormat) constructor:

DECLARE
   lobd BLOB;
   fils BFILE := BFILENAME('FILE_DIR','window.psp');
   newimage SI_StillImage;
   height NUMBER;
   width NUMBER;
   myimage SI_StillImage;
BEGIN
   -- Put the blob in a temporary LOB:
   DBMS_LOB.CREATETEMPORARY(lobd, TRUE);
   DBMS_LOB.FILEOPEN(fils, DBMS_LOB.FILE_READONLY);
   DBMS_LOB.LOADFROMFILE(lobd, fils, DBMS_LOB.GETLENGTH(fils));
   DBMS_LOB.FILECLOSE(fils);
   -- Create a new SI_StillImage object for this image (which has an
   -- unsupported format):
   newimage := NEW SI_StillImage(lobd, 'psp');
   -- If the stored height and width values are NULL, the following will set
   -- them appropriately. Alternatively, you could use the 
   -- SI_StillImage(content, explicitFormat, height,width) constructor:
   height := 570;
   width := 1168;
   IF (newimage.SI_Height is NULL) THEN
      newimage.height_SI := height;
   END IF;
   IF (newimage.SI_Width is NULL) THEN
      newimage.width_SI := width;
   END IF;
   -- Insert the image into the si_media table, then free the temporary LOB:
   INSERT INTO PM.SI_MEDIA (product_id, product_photo) VALUES (3, newimage);
   DBMS_LOB.FREETEMPORARY(lobd);
   -- Make sure that the height and width were stored as expected:
   SELECT product_photo INTO myimage FROM PM.SI_MEDIA WHERE product_id=3;
   height := myimage.SI_height;
   width := myimage.SI_width;
   DBMS_OUTPUT.PUT_LINE('Height is ' || height || ' pixels.');
   DBMS_OUTPUT.PUT_LINE('Width is ' || width ||  ' pixels.');
   COMMIT;
END;
/

Create a new SI_StillImage object from a specified image and format using the SI_MkStillImage2( ) function:

DECLARE
   lobd BLOB;
   fils BFILE := BFILENAME('FILE_DIR','window.psp');
   newimage SI_StillImage;
   height NUMBER;
   width NUMBER;
   myimage SI_StillImage;
BEGIN
   -- Put the blob in a temporary LOB:
   DBMS_LOB.CREATETEMPORARY(lobd, TRUE);
   DBMS_LOB.FILEOPEN(fils, DBMS_LOB.FILE_READONLY);
   DBMS_LOB.LOADFROMFILE(lobd, fils, DBMS_LOB.GETLENGTH(fils));
   DBMS_LOB.FILECLOSE(fils);
   -- Create a new SI_StillImage object for this image (which has an
   -- unsupported format):
   newimage := SI_MkStillImage2(lobd, 'psp');
   -- If the stored height and width values are NULL, the following will set
   -- them appropriately:
   height := 570;
   width := 1168;
   IF (SI_GetHeight(newimage) is NULL) THEN
      newimage.height_SI := height;
   END IF;
   IF (SI_GetWidth(newimage) is NULL) THEN
      newimage.width_SI := width;
   END IF;
   -- Insert the image into the si_media table, then free the temporary LOB:
   INSERT INTO PM.SI_MEDIA (product_id, product_photo) VALUES (77, newimage);
   DBMS_LOB.FREETEMPORARY(lobd);
   -- Make sure that the height and width were stored as expected:
   SELECT product_photo INTO myimage FROM PM.SI_MEDIA WHERE product_id=77;
   height := myimage.SI_height;
   width := myimage.SI_width;
   DBMS_OUTPUT.PUT_LINE('Height is ' || height || ' pixels.');
   DBMS_OUTPUT.PUT_LINE('Width is ' || width ||  ' pixels.');
   COMMIT;
END;
/

SI_StillImage(content, explicitFormat, height, width)

Format

SI_StillImage(content IN BLOB,

explicitFormat IN VARCHAR2,

height IN INTEGER,

width IN INTEGER)

RETURN SI_STILLIMAGE as RESULT DETERMINISTIC;

Format of Equivalent SQL Function

ora_SI_MkStillImage(content IN BLOB)

explicitFormat IN VARCHAR2,

height IN INTEGER,

width IN INTEGER)

RETURN SI_StillImage DETERMINISTIC;

Description

Constructs an SI_StillImage value from a specified image. This constructor lets you specify the image format, height, and width when the specified image is an unsupported image format. Query the SI_IMAGE_FORMATS view in SI_INFORMTN_SCHEMA for a list of the supported image formats.

This constructor and its equivalent SQL function are Oracle extensions to the SQL/MM Still Image standard.

This constructor initializes the SI_StillImage attributes as follows:

Parameters

content

The image data.

explicitFormat

The format that you want interMedia to use if the image is in an unsupported format.

height

The value for the height_SI attribute that you want interMedia to use if the image is in an unsupported format.

width

The value for the width_SI attribute that you want interMedia to use if the image is in an unsupported format.

Pragmas

None.

Exceptions

ORDImageSIExceptions.ILLEGAL_HEIGHT_WIDTH_SPEC

This exception is raised if the value of the height or width parameter is NULL or is a negative value.

ORDImageSIExceptions.NULL_CONTENT

This exception is raised if the content parameter is NULL.

See Appendix G for more information about these exceptions.

Usage Notes

An error message is returned if the explicitFormat parameter value is a NULL value, or if either of the following statements is true:

The following table presents values for the explicitFormat parameter and the actual image format, and whether or not that combination of values will result in an error. An image format of NULL indicates that the format cannot be extracted from the image.

explicitFormat Image Format Error Returned?
GIF (a supported format) GIF No
GIF (a supported format) JPEG Yes
xyz (an unsupported format) GIF Yes
xyz (an unsupported format) Null No

Examples

Construct an SI_StillImage value from an image using the SI_StillImage(content, explicitFormat, height, width) constructor:

DECLARE
   lobd BLOB;
   fils BFILE := BFILENAME('FILE_DIR','window.psp');
   newimage SI_StillImage;
   height NUMBER;
   width NUMBER;
   myimage SI_StillImage;
BEGIN
   -- Put the blob in a temporary LOB:
   DBMS_LOB.CREATETEMPORARY(lobd, TRUE);
   DBMS_LOB.FILEOPEN(fils, DBMS_LOB.FILE_READONLY);
   DBMS_LOB.LOADFROMFILE(lobd, fils, DBMS_LOB.GETLENGTH(fils));
   DBMS_LOB.FILECLOSE(fils);
   -- Create a new SI_StillImage object for this image (which has an
   -- unsupported format):
   newimage := NEW SI_StillImage(lobd, 'psp', 570, 1168);
   -- Insert the image into the si_media table, then free the temporary LOB:
   INSERT INTO PM.SI_MEDIA (product_id, product_photo) VALUES (4, newimage);
   DBMS_LOB.FREETEMPORARY(lobd);
   -- Make sure that the height and width were stored as expected:
   SELECT product_photo INTO myimage FROM PM.SI_MEDIA WHERE product_id=4;
   height := myimage.SI_height;
   width := myimage.SI_width;
   DBMS_OUTPUT.PUT_LINE('Height is ' || height || ' pixels.');
   DBMS_OUTPUT.PUT_LINE('Width is ' || width ||  ' pixels.');
   COMMIT;
END;
/

Construct an SI_StillImage value from an image using the ora_SI_StillImage(content, explicitFormat, height, width) function:

DECLARE
   lobd BLOB;
   fils BFILE := BFILENAME('FILE_DIR','window.psp');
   newimage SI_StillImage;
   height NUMBER;
   width NUMBER;
   myimage SI_StillImage;
BEGIN
   -- Put the blob in a temporary LOB:
   DBMS_LOB.CREATETEMPORARY(lobd, TRUE);
   DBMS_LOB.FILEOPEN(fils, DBMS_LOB.FILE_READONLY);
   DBMS_LOB.LOADFROMFILE(lobd, fils, DBMS_LOB.GETLENGTH(fils));
   DBMS_LOB.FILECLOSE(fils);
   -- Create a new SI_StillImage object for this image (which has an
   -- unsupported format):
   newimage := ora_SI_StillImage(lobd, 'psp', 570, 1168);
   -- Insert the image into the si_media table, then free the temporary LOB:
   INSERT INTO PM.SI_MEDIA (product_id, product_photo) VALUES (6, newimage);
   DBMS_LOB.FREETEMPORARY(lobd);
   -- Make sure that the height and width were stored as expected:
   SELECT product_photo INTO myimage FROM PM.SI_MEDIA WHERE product_id=6;
   height := myimage.SI_height;
   width := myimage.SI_width;
   DBMS_OUTPUT.PUT_LINE('Height is ' || height || ' pixels.');
   DBMS_OUTPUT.PUT_LINE('Width is ' || width ||  ' pixels.');
   COMMIT;
END;
/

SI_StillImage Methods

This section presents reference information on the SI_StillImage methods used for image data manipulation, which are the following:


SI_ClearFeatures( )

Format

SI_ClearFeatures( );

Description

Disables image feature caching and sets the value of all internal image feature attributes to NULL. You can call this method to remove the processing overhead associated with feature synchronization if you are not performing image matching. This method does nothing for unsupported image formats.

This method is not in the first edition of the SQL/MM Still Image standard, but has been accepted for inclusion in the next version.

Parameters

None.

Usage Notes

None.

Pragmas

None

Exceptions

None.

Examples

Disable image feature caching and set the value of all internal image feature attributes for a specified image to NULL:

DECLARE 
  myimage SI_StillImage; 
BEGIN 
  SELECT product_photo INTO myimage FROM PM.SI_MEDIA WHERE product_id = 1; 
  UPDATE PM.SI_MEDIA
   SET product_photo = myimage where product_id=1;
  myimage.SI_ClearFeatures; 
  DBMS_OUTPUT.PUT_LINE('Image feature caching diasbled'); 
  COMMIT;
END; 
/

SI_InitFeatures( )

Format

SI_InitFeatures( );

Description

Extracts the image features and caches them in the SI_StillImage object. This method needs to be called once, after which SI_StillImage will manage the image features such that every time the image is processed, new image features will automatically be extracted. This method is recommended for image-matching users.

This method is not in the first edition of the SQL/MM Still Image standard, but has been accepted for inclusion in the next version.

Parameters

None.

Usage Notes

Pragmas

None.

Exceptions

ORDImageSIExceptions.UNSUPPORTED_IMAGE_FORMAT

This exception is raised if this method is invoked on an unsupported image format.

See Appendix G for more information about this exception.

Examples

Extract the image features and cache them in an SI_StillImage object:

DECLARE
  myimage SI_StillImage; 
BEGIN 
  SELECT product_photo INTO myimage FROM PM.SI_MEDIA 
     WHERE product_id = 1 FOR UPDATE; 
  myimage.SI_InitFeatures; 
  UPDATE PM.SI_MEDIA
   SET product_photo = myimage where product_id=1;
  DBMS_OUTPUT.PUT_LINE('Image feature caching enabled'); 
  COMMIT;
END; 
/ 

SI_ChangeFormat( )

Format

SI_ChangeFormat(targetFormat IN VARCHAR2);

Format of Equivalent SQL Procedure

SI_ConvertFormat(image IN OUT NOCOPY SI_StillImage,

targetFormat IN VARCHAR2);

Description

Converts the format of an SI_StillImage object and adjusts the affected attributes as follows:

Parameters

image

The image whose content you want to convert.

targetFormat

The format to which you want the image to be converted.

Usage Notes

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

Pragmas

None.

Exceptions

None.

Examples

Convert the format of an SI_StillImage object to WBMP using the SI_ChangeFormat( ) method:

DECLARE 
   origformat VARCHAR2 (10);
   newformat VARCHAR2 (10); 
   myimage SI_StillImage; 
   currentformat VARCHAR2 (10);
BEGIN 
  SELECT product_photo INTO myimage FROM PM.SI_MEDIA 
    WHERE product_id = 1 FOR UPDATE; 
  origformat := myimage.SI_Format; 
  DBMS_OUTPUT.PUT_LINE('Original format is ' || origformat); 
  newformat := 'WBMP';
  myimage.SI_ChangeFormat(newformat);
  INSERT INTO PM.SI_MEDIA (product_id, product_photo) VALUES (44, myimage);
  SELECT product_photo INTO myimage FROM PM.SI_MEDIA 
    WHERE product_id = 44; 
  currentformat := myimage.SI_Format;
  DBMS_OUTPUT.PUT_LINE('New format is ' || currentformat); 
  COMMIT;
END; 
/ 

Convert the format of an SI_StillImage object to GIFF using the SI_ConvertFormat( ) procedure:

DECLARE 
   origformat VARCHAR2 (10);
   newformat VARCHAR2 (10); 
   myimage SI_StillImage; 
   currentformat VARCHAR2 (10);
BEGIN 
  SELECT product_photo INTO myimage FROM PM.SI_MEDIA 
    WHERE product_id = 1 FOR UPDATE; 
  origformat := myimage.SI_Format; 
  DBMS_OUTPUT.PUT_LINE('Original format is ' || origformat); 
  newformat := 'GIFF';
  SI_ConvertFormat(myimage, newformat);
  INSERT INTO PM.SI_MEDIA (product_id, product_photo) VALUES (5, myimage);
  SELECT product_photo INTO myimage FROM PM.SI_MEDIA 
    WHERE product_id = 3 FOR UPDATE; 
  currentformat := myimage.SI_Format;
  DBMS_OUTPUT.PUT_LINE('New format is ' || currentformat); 
  COMMIT;
END; 
/ 

SI_Content( )

Format

SI_Content ( )

RETURN BLOB DETERMINISTIC;

Format of Equivalent SQL Function

SI_GetContent(image IN SI_StillImage)

RETURN BLOB DETERMINISTIC;

Description

Returns the BLOB stored in the content_SI attribute of the SI_StillImage object to which this method is applied.

Parameters

None.

Usage Notes

None.

Method Pragmas

PRAGMA RESTRICT_REFERENCES(SI_Content, WNDS, WNPS, RNDS, RNPS)

Function Pragmas

PRAGMA RESTRICT_REFERENCES(SI_GetContent, WNDS, WNPS, RNDS, RNPS)

Exceptions

None.

Examples

Get the BLOB data stored in the content_SI attribute of an SI_StillImage object using the SI_Content( ) method:

DECLARE
   myimage SI_StillImage; 
   photo   BLOB;
BEGIN 
  SELECT product_photo INTO myimage FROM PM.SI_MEDIA 
    WHERE product_id = 1; 
  photo := myimage.SI_Content;
END; 
/

Get the BLOB data stored in the content_SI attribute of an SI_StillImage object using the SI_GetContent( ) function:

DECLARE 
   myimage SI_StillImage; 
   photo   BLOB;
BEGIN 
  SELECT product_photo INTO myimage FROM PM.SI_MEDIA 
    WHERE product_id = 1; 
  photo := SI_GetContent(myimage);
END; 
/ 

SI_ContentLength( )

Format

SI_ContentLength ( )

RETURN INTEGER DETERMINISTIC;

Format of Equivalent SQL Function

SI_GetContentLngth(image IN SI_StillImage)

RETURN INTEGER DETERMINISTIC;

Description

Returns the value (in bytes) of the contentLength_SI attribute of the specified SI_StillImage object.

Parameters

image

The image for which the content length is returned.

Usage Notes

None.

Method Pragmas

PRAGMA RESTRICT_REFERENCES(SI_ContentLength, WNDS, WNPS, RNDS, RNPS)

Function Pragmas

PRAGMA RESTRICT_REFERENCES(SI_GetContentLngth, WNDS, WNPS, RNDS, RNPS)

Exceptions

None.

Examples

Get the value of the contentLength_SI attribute of an SI_StillImage object using the SI_ContentLength( ) method:

DECLARE 
   length number; 
   myimage SI_StillImage;
BEGIN 
  SELECT product_photo INTO myimage FROM PM.SI_MEDIA WHERE product_id = 1; 
  length := myimage.SI_ContentLength; 
  DBMS_OUTPUT.PUT_LINE('Length is ' || length); 
END; 
/ 

Get the value of the contentLength_SI attribute of an SI_StillImage object using the SI_GetContentLngth( ) function:

DECLARE 
  length number; 
   myimage SI_StillImage;
BEGIN 
  SELECT product_photo INTO myimage FROM PM.SI_MEDIA WHERE product_id = 1; 
  length := SI_GetContentLngth(myimage); 
  DBMS_OUTPUT.PUT_LINE('length is ' || length); 
END; 
/ 

SI_Format( )

Format

SI_Format ( )

RETURN VARCHAR2 DETERMINISTIC;

Format of Equivalent SQL Function

SI_GetFormat(image IN SI_StillImage)

RETURN VARCHAR2 DETERMINISTIC;

Description

Returns the value of the format_SI attribute (such as TIFF or JFIF) of the SI_StillImage object to which this method is applied.

Parameters

None.

Usage Notes

None.

Method Pragmas

PRAGMA RESTRICT_REFERENCES(SI_Format, WNDS, WNPS, RNDS, RNPS)

Function Pragmas

PRAGMA RESTRICT_REFERENCES(SI_GetFormat, WNDS, WNPS, RNDS, RNPS)

Exceptions

None.

Examples

Get the value of the format_SI attribute of an SI_StillImage object using the SI_Format( ) method:

DECLARE 
   format VARCHAR2 (10); 
   myimage SI_StillImage; 
BEGIN 
  SELECT product_photo INTO myimage FROM PM.SI_MEDIA WHERE product_id = 1; 
  format := myimage.SI_Format; 
  DBMS_OUTPUT.PUT_LINE('Format is ' || format); 
END; 
/ 

Get the value of the format_SI attribute of an SI_StillImage object using the SI_GetFormat( ) function:

DECLARE 
   format VARCHAR2 (10); 
   myimage SI_StillImage; 
BEGIN 
  SELECT product_photo INTO myimage FROM PM.SI_MEDIA WHERE product_id = 1; 
  format := SI_GetFormat(myimage); 
  DBMS_OUTPUT.PUT_LINE('Format is ' || format); 
END; 
/ 

SI_Height( )

Format

SI_Height ( )

RETURN INTEGER DETERMINISTIC;

Format of Equivalent SQL Function

SI_GetHeight(image IN SI_StillImage)

RETURN INTEGER DETERMINISTIC;

Description

Returns the value of the height_SI attribute (in pixels) of the SI_StillImage object to which this method is applied.

Parameters

image

The image for which the height is returned.

Usage Notes

None.

Method Pragmas

PRAGMA RESTRICT_REFERENCES(SI_Height, WNDS, WNPS, RNDS, RNPS)

Function Pragmas

PRAGMA RESTRICT_REFERENCES(SI_GetHeight, WNDS, WNPS, RNDS, RNPS)

Exceptions

None.

Examples

Get the value of the height_SI attribute of an SI_StillImage object using the SI_Height( ) method:

DECLARE 
   ht NUMBER; 
   myimage SI_StillImage; 
BEGIN 
  SELECT product_photo INTO myimage FROM PM.SI_MEDIA WHERE product_id = 1; 
  ht := myimage.SI_Height; 
  DBMS_OUTPUT.PUT_LINE('height ' || ht); 
END; 
/ 

Get the value of the height_SI attribute of an SI_StillImage object using the SI_GetHeight( ) function:

DECLARE  
  ht NUMBER; 
   myimage SI_StillImage; 
BEGIN 
  SELECT product_photo INTO myimage FROM PM.SI_MEDIA WHERE product_id = 1; 
  ht := SI_GetHeight(myimage); 
  DBMS_OUTPUT.PUT_LINE('height ' || ht); 
END; 
/  

SI_RetainFeatures( )

Format

SI_RetainFeatures( );

RETURN BOOLEAN DETERMINISTIC;

Description

Returns a Boolean value (TRUE or FALSE) to indicate whether or not image features will be extracted and cached.

This method is not in the first edition of the SQL/MM Still Image standard, but has been accepted for inclusion in the next version.

Parameters

None.

Usage Notes

None.

Method Pragma

PRAGMA RESTRICT_REFERENCES(WNDS, WNPS, RNDS, RNPS)

Exceptions

None.

Examples

Determine whether or not the image features will be extracted and cached for a given SI_StillImage object:

DECLARE
  myimage     SI_StillImage; 
BEGIN 
  SELECT product_photo INTO myimage FROM PM.SI_MEDIA 
     WHERE product_id = 1; 
  IF (myimage.SI_RetainFeatures = TRUE) THEN
  DBMS_OUTPUT.PUT_LINE('Images features will be extracted and cached'); 
 ELSE
  DBMS_OUTPUT.PUT_LINE('Images features will not be extracted and cached');
 END IF;
END; 
/ 

SI_SetContent( )

Format

SI_SetContent(content IN BLOB);

Format of Equivalent SQL Procedure

SI_ChgContent(image IN OUT NOCOPY SI_StillImage,

content IN BLOB);

Description

Updates the content of an SI_StillImage object. It sets the values of the following attributes:

Parameters

content

The image data. The format of this image data must be the same as the format of the current image.

image

The image whose content you want to update.

Usage Notes

None.

Pragmas

None.

Exceptions

ORDImageSIExceptions.NULL_CONTENT

This exception is raised if the content parameter is NULL.

See Appendix G for more information about this exception.

Examples

Update the content of an SI_StillImage object using the SI_SetContent( ) method:

DECLARE 
   newcontent BLOB; 
   fils BFILE := BFILENAME('FILE_DIR','keyboard.jpg');
   myimage SI_StillImage; 
BEGIN 
   -- Put the blob in a temporary LOB:
   DBMS_LOB.CREATETEMPORARY(newcontent, TRUE);
   DBMS_LOB.FILEOPEN(fils, DBMS_LOB.FILE_READONLY);
   DBMS_LOB.LOADFROMFILE(newcontent, fils, DBMS_LOB.GETLENGTH(fils));
   DBMS_LOB.FILECLOSE(fils);
   -- Select a row to be updated: 
  SELECT product_photo INTO myimage FROM PM.SI_MEDIA WHERE product_id = 1 
     FOR UPDATE; 
  myimage.SI_SetContent(newcontent); 
  -- Update the content of product_photo:
  UPDATE PM.SI_MEDIA
   SET product_photo = myimage where product_id=1;
 -- Free the temporary LOB:
 DBMS_LOB.FREETEMPORARY(newcontent);
 COMMIT;
END; 
/ 

Update the content of an SI_StillImage object using the SI_ChgContent( ) procedure:

DECLARE 
   newcontent BLOB; 
   fils BFILE := BFILENAME('FILE_DIR','keyboard.jpg');
   myimage SI_StillImage; 
   
BEGIN 
   -- Put the blob in a temporary LOB:
   DBMS_LOB.CREATETEMPORARY(newcontent, TRUE);
   DBMS_LOB.FILEOPEN(fils, DBMS_LOB.FILE_READONLY);
   DBMS_LOB.LOADFROMFILE(newcontent, fils, DBMS_LOB.GETLENGTH(fils));
   DBMS_LOB.FILECLOSE(fils);
   -- Select a row to be updated:
   SELECT product_photo INTO myimage FROM PM.SI_MEDIA WHERE product_id = 1 
     FOR UPDATE; 
   SI_ChgContent(myimage, newcontent);
   -- Update the content of product_photo:
   UPDATE PM.SI_MEDIA
   SET product_photo = myimage where product_id=1;
   -- Free the temporary LOB:
   DBMS_LOB.FREETEMPORARY(newcontent);
   COMMIT;
END; 
/ 

SI_Thumbnail( )

Format

SI_Thumbnail ( )

RETURN SI_StillImage;

Format of Equivalent SQL Function

SI_GetThmbnl (image IN SI_StillImage)

RETURN SI_StillImage;

Description

Derives a thumbnail image from the specified SI_StillImage object. The default thumbnail size is 80 by 80 pixels. Because this method preserves the image aspect ratio, the resulting thumbnail size will be as close to 80 by 80 pixels as possible.

Parameters

image

The image for which you want to generate a thumbnail image.

Usage Notes

None.

Pragmas

None.

Exceptions

None.

Examples

Create a new thumbnail image from an SI_StillImage object using the SI_Thumbnail( ) method:

DECLARE
   myimage SI_StillImage;
   myThumbnail SI_StillImage;
   height number;
   width number;
BEGIN 
  SELECT product_photo INTO myimage FROM PM.SI_MEDIA WHERE product_id = 1; 
  width := myimage.SI_width; 
  height := myimage.SI_height;
  DBMS_OUTPUT.PUT_LINE('Height is ' || height || ' pixels.');
  DBMS_OUTPUT.PUT_LINE('Width is ' || width ||  ' pixels.');
  myThumbnail := myimage.SI_Thumbnail;
  width := myThumbnail.SI_width; 
  height := myThumbnail.SI_height;
  DBMS_OUTPUT.PUT_LINE('Height is ' || height || ' pixels.');
  DBMS_OUTPUT.PUT_LINE('Width is ' || width ||  ' pixels.');
END; 
/

Create a new thumbnail image from an SI_StillImage object using the SI_GetThmbnl( ) function:

DECLARE
   myimage SI_StillImage;
   myThumbnail SI_StillImage;
   height number;
   width number;
BEGIN 
  SELECT product_photo INTO myimage FROM PM.SI_MEDIA WHERE product_id = 1; 
  width := myimage.SI_width; 
  height := myimage.SI_height;
  DBMS_OUTPUT.PUT_LINE('Height is ' || height || ' pixels.');
  DBMS_OUTPUT.PUT_LINE('Width is ' || width ||  ' pixels.');
  myThumbnail := SI_GetThmbnl(myimage);
  width := myThumbnail.SI_width; 
  height := myThumbnail.SI_height;
  DBMS_OUTPUT.PUT_LINE('Height is ' || height || ' pixels.');
  DBMS_OUTPUT.PUT_LINE('Width is ' || width ||  ' pixels.');
END; 
/

SI_Thumbnail(height,width)

Format

SI_Thumbnail(height IN INTEGER, width IN INTEGER)

RETURN SI_StillImage DETERMINISTIC;

Format of Equivalent SQL Function

SI_GetSizedThmbnl(image IN SI_StillImage,

height IN INTEGER,

width IN INTEGER)

RETURN SI_StillImage DETERMINISTIC;

Description

Derives a new thumbnail image from the specified SI_StillImage object using the height and width that you specify. This method does not preserve the aspect ratio.

Parameters

height

The height that you want interMedia to use for the thumbnail image.

image

The image for which you want to generate a thumbnail image.

width

The width that you want interMedia to use for the thumbnail image.

Usage Notes

To preserve the aspect ratio, supply the appropriate height and width values. To obtain the appropriate height and width values, multiply the image height and width values by the required scaling factor. For example, if an image size is 100 by 100 pixels and the resulting thumbnail image needs to be one fourth of the original image, then the height argument should be 100 divided by 2 and the width argument should be 100 divided by 2. The resulting thumbnail image would be 50 by 50 pixels, and the aspect ratio would be preserved.

Pragmas

None.

Exceptions

None.

Examples

Create a new thumbnail image from an SI_StillImage object with the specified height and width using the SI_Thumbnail(height, width) method:

DECLARE
   myimage SI_StillImage;
   myThumbnail SI_StillImage;
   height number;
   width number;
BEGIN 
  SELECT product_photo INTO myimage FROM PM.SI_MEDIA WHERE product_id = 1; 
  width := myimage.SI_width; 
  height := myimage.SI_height;
  DBMS_OUTPUT.PUT_LINE('Height is ' || height || ' pixels.');
  DBMS_OUTPUT.PUT_LINE('Width is ' || width ||  ' pixels.');
  myThumbnail := myimage.SI_Thumbnail(129,121);
  width := myThumbnail.SI_width; 
  height := myThumbnail.SI_height;
  DBMS_OUTPUT.PUT_LINE('Height is ' || height || ' pixels.');
  DBMS_OUTPUT.PUT_LINE('Width is ' || width ||  ' pixels.');
END; 
/ 

Create a thumbnail image from an SI_StillImage object with the specified height and width using the SI_GetSizedThmbnl function:

DECLARE 
   myimage SI_StillImage;
   myThumbnail SI_StillImage;
   height number;
   width number;
BEGIN 
  SELECT product_photo INTO myimage FROM PM.SI_MEDIA WHERE product_id = 1; 
  width := myimage.SI_width; 
  height := myimage.SI_height;
  DBMS_OUTPUT.PUT_LINE('Height is ' || height || ' pixels.');
  DBMS_OUTPUT.PUT_LINE('Width is ' || width ||  ' pixels.');
  myThumbnail := SI_GetSizedThmbnl(myimage,129,121);
  width := myThumbnail.SI_width; 
  height := myThumbnail.SI_height;
  DBMS_OUTPUT.PUT_LINE('Height is ' || height || ' pixels.');
  DBMS_OUTPUT.PUT_LINE('Width is ' || width ||  ' pixels.');
END; 
/

SI_Width( )

Format

SI_Width ( )

RETURN INTEGER DETERMINISTIC;

Format of Equivalent SQL Function

SI_GetWidth(image IN SI_StillImage)

RETURN INTEGER DETERMINISTIC;

Description

Returns the value of the width_SI attribute (in pixels) of the SI_StillImage object to which this method is applied.

Parameters

image

The image for which the width is returned.

Usage Notes

None.

Method Pragmas

PRAGMA RESTRICT_REFERENCES(SI_Width, WNDS, WNPS, RNDS, RNPS)

Function Pragmas

PRAGMA RESTRICT_REFERENCES(SI_GetWidth, WNDS, WNPS, RNDS, RNPS)

Exceptions

None.

Examples

Get the value of the width_SI attribute of an SI_StillImage object using the SI_Width( ) method:

DECLARE 
   width NUMBER; 
   myimage SI_StillImage; 
BEGIN 
  SELECT product_photo INTO myimage FROM PM.SI_MEDIA WHERE product_id = 1; 
  width := myimage.SI_Width; 
  DBMS_OUTPUT.PUT_LINE('Width is ' || width); 
END; 
/ 

Get the value of the width_SI attribute of an SI_StillImage object using the SI_GetWidth( ) function:

DECLARE 
   width NUMBER; 
   myimage SI_StillImage; 
BEGIN 
  SELECT product_photo INTO myimage FROM PM.SI_MEDIA WHERE product_id = 1; 
  width := SI_GetWidth(myimage); 
  DBMS_OUTPUT.PUT_LINE('Width is ' || width); 
END; 
/ 

SI_Texture Object Type

Describes the image texture characteristics by the size of repeating items (coarseness), brightness variations (contrast), and predominant direction (directionality). 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 textureEncoding attribute syntax.)

Note:

Use the SI_Texture constructor and method rather than accessing attributes directly to protect yourself from changes to the internal representation of the SI_Texture object.

The SI_Texture object is described as follows:

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

where:


SI_Texture Constructor

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


SI_Texture( )

Format

SI_Texture(sourceImage IN SI_StillImage)

RETURN SELF AS RESULT DETERMINISTIC;

Format of Equivalent SQL Function

SI_FindTexture(sourceImage IN SI_StillImage)

RETURN SI_Texture DETERMINISTIC;

Description

Constructs an SI_Texture object from the specified image.

Parameters

sourceImage

The image whose texture feature is being extracted.

Pragmas

None.

Exceptions

None.

Usage Notes

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

Examples

Create an SI_Texture object using the SI_Texture( ) constructor:

DECLARE
   myTexture  SI_Texture;
   myimage    SI_StillImage;
BEGIN
  SELECT product_photo INTO myimage FROM pm.si_media 
   WHERE product_id=1 FOR UPDATE;
  myTexture := NEW SI_Texture(myimage);
  UPDATE pm.si_media SET texture = myTexture WHERE product_id=1;
  COMMIT;
END;
/

Create an SI_Texture object using the SI_FindTexture( ) function:

DECLARE
   myTexture  SI_Texture;
   myimage    SI_StillImage;
BEGIN
   SELECT product_photo INTO myimage FROM pm.si_media 
     WHERE product_id=2 FOR UPDATE;
   myTexture := SI_FindTexture(myimage);
   UPDATE pm.si_media SET texture = myTexture WHERE product_id=2;
   COMMIT;
END;
/

SI_Texture Method

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


SI_Score( ) for SI_Texture

Format

SI_Score(image IN SI_StillImage)RETURN DOUBLE PRECISION DETERMINISTIC;

Format of Equivalent SQL Function

SI_ScoreByTexture(feature IN SI_Texture,

image IN SI_StillImage),

RETURN DOUBLE PRECISION DETERMINISTIC;

Description

Determines and returns the score of the specified image as compared to the SI_Texture object to which you are applying the method. The lower the returned value, the better the texture of the image is characterized by the SI_Texture value used for scoring the image. 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:

Parameters

feature

The feature value to be compared with the texture of the specified image.

image

The image whose texture feature is extracted and used for score comparison.

Usage Notes

None.

Pragmas

None.

Exceptions

None.

Examples

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

DECLARE
    score DOUBLE PRECISION;
    myimage SI_StillImage;
    myTexture SI_Texture;
BEGIN
   SELECT texture INTO myTexture FROM pm.si_media 
      WHERE product_id=1;
   SELECT product_photo INTO myimage FROM pm.si_media 
      WHERE product_id=2;
   score := myTexture.SI_Score(myimage);
   DBMS_OUTPUT.PUT_LINE('Score is ' || score);
END;
/

Compare the texture of an image to an SI_Texture object using the SI_ScoreByTexture( ) function and return the score:

DECLARE
    score DOUBLE PRECISION;
    myimage SI_StillImage;
    myTexture SI_Texture;
BEGIN
   SELECT texture INTO myTexture FROM pm.si_media 
      WHERE product_id=1;
   SELECT product_photo INTO myimage FROM pm.si_media 
      WHERE product_id=2;
   score := SI_ScoreByTexture(myTexture, myimage);
   DBMS_OUTPUT.PUT_LINE('Score is ' || score);
END;
/

Views

The schema, SI_INFORMTN_SCHEMA, contains several views that identify the supported image formats and implementation-defined values. The privilege set on these views is PUBLIC WITH GRANT OPTION. The views are:

The column names, data types, and a description is provided for each of these views in the tables that follow.

Table 6-1 describes the SI_IMAGE_FORMATS view. This view identifies the supported image formats.

Table 6-1 SI_IMAGE_FORMATS View

Column Name Data Type Description
SI_FORMAT VARCHAR2(SI_MaxFormatLength) A list of the supported image formats.

Table 6-2 describes the SI_IMAGE_FORMAT_CONVERSIONS view. This view identifies the source and target image formats for which an image format conversion is supported. The short name for this view is SI_IMAGE_FORMAT_CONVRSNS.

Table 6-2 SI_IMAGE_FORMAT_CONVERSIONS View

Column Name Data Type Description
SI_SOURCE_FORMAT VARCHAR2(SI_MaxFormatLength) The format of the source image.
SI_TARGET_FORMAT VARCHAR2(SI_MaxFormatLength) The format of the target image.

Table 6-3 describes the SI_IMAGE_FORMAT_FEATURES view. This view identifies the image formats for which a basic feature is supported. The short name for this view is SI_IMAGE_FRMT_FTRS.

Table 6-3 SI_IMAGE_FORMAT_FEATURES View

Column Name Data Type Description
SI_FORMAT VARCHAR2(SI_MaxFormatLength) The format name.
SI_FEATURE_NAME VARCHAR2(100) The basic feature name that is supported by the named format. Value can be any of the following:
  • SI_AverageColor

  • SI_Texture

  • SI_PositionalColor

  • SI_ColorHistogram


Table 6-4 describes the SI_THUMBNAIL_FORMATS view. This view identifies the image formats from which thumbnail images can be derived. The short name for this view is SI_THUMBNAIL_FRMTS.

Table 6-4 SI_THUMBNAIL_FORMATS View

Column Name Data Type Description
SI_FORMAT VARCHAR2(SI_MaxFormatLength) The formats from which a thumbnail image can be derived.

Table 6-5 describes the SI_VALUES view. This view identifies the implementation-defined values.

Table 6-5 SI_VALUES View

Column Name Data Type Description
SI_VALUE VARCHAR2( SI_MaxFormatLength) The implementation-defined meta-variables. The SI_VALUES view has 8 rows where each row has one of the following SI_VALUE column values:
  • SI_MaxContentLength is the maximum length for the binary representation of the SI_StillImage attribute.

  • SI_MaxFeatureNameLength is the maximum length for the character representation of a basic image feature name.

  • SI_MaxFormatLength is the maximum length for the character representation of an image format indication.

  • SI_MaxHistogramLength is the maximum number of color/frequency pairs that are admissible in an SI_ColorHistogram feature value.

  • SI_MaxRGBColor is the maximum value for each component of a color value that is represented by the RGB color space.

  • SI_MaxTextureLength is the number of bytes needed for the encoded representation of an SI_Texture object.

  • SI_MaxValueLength is the maximum length for the character representation (name) of the meta-variables in the SI_VALUES view.

  • SI_NumberSections is the number of most significant color values that are represented by the SI_PositionalColor value.

SI_SUPPORTED_VALUE NUMBER(38) A column with the following values:
  • 0

    If the implementation places no limit on the meta-variable defined by SI_VALUE column or cannot determine the limit.

  • NULL

    If the implementation does not support any features for which the meta-variable is applicable.

  • Any non-NULL, nonzero value

    The maximum size supported by the implementation for this meta-variable.



Internal Helper Types

An attribute that consists of an array is specified as an internal helper type. Internal helper types are created in the ORDSYS schema and do not have public synonyms.

The internal helper types are the following: