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:

content_SI: an ORDSource object that contains the binary image or BLOB. (SQL/MM specifies the SI_Content attribute as a BLOB.)
contentLength_SI: the content length of the image in bytes.
format_SI: the image format.
height_SI: the number of lines of the image.
width_SI: the number of columns of the image.
mimeType_ora: the MIME type information. (This is an Oracle extension to the SQL/MM Still Image standard.)
contentFormat_ora: the type of image (monochrome and so on). (This is an Oracle extension to the SQL/MM Still Image standard.)
compressionFormat_ora: the compression algorithm used on the image data. (This is an Oracle extension to the SQL/MM Still Image standard.)
retainFeatures_SI: a flag that indicates whether or not image features will be extracted and cached.
averageColorSpec_ora: the cached SI_Color object.
colorsList_ora: the cached array of colors.
frequenciesList_ora: the cached array of color frequencies.
colorPositions_ora: the cached array of color positions.
textureEncoding_ora: the cached array of textures.

SI_StillImage Constructors

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

SI_StillImage(content)
SI_StillImage(content, explicitFormat)
SI_StillImage(content, explicitFormat, height, width)

This is an Oracle extension to the SQL/MM Still Image standard.

Note:

To construct SI_StillImage objects, Oracle Corporation 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:

content_SI.localData is initialized with the specified image.
contentLength_SI is initialized with the length of the image extracted from the specified image.
format_SI is initialized with the format of image extracted from the specified image.
height_SI is initialized with the height of image extracted from the specified image.
width_SI is initialized with the width of image extracted from the specified image.

Parameters

content: The image data.

Pragmas

None.

Exceptions

ORDImageSIExceptions.NULL_CONTENT

This exception is raised if the content parameter is NULL.

See Appendix F for more information about these exceptions.

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.

From the command prompt, run SQL*Loader:
```
sqlldr parfile= blob_load.par
```
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
```
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.

blob_load.par:

userid=ron/ron
control=/homedir/user3/blob_load.ctl
log=/homedir/user3/blob_load.log

blob_load.ctl:

LOAD DATA
INFILE *
INTO TABLE PM.IMAGETAB
REPLACE
FIELDS TERMINATED BY ','
(id ,
 imgblob_fname FILLER CHAR(20),
 imgblob LOBFILE(imgblob_fname) raw terminated by EOF)
BEGINDATA
1,speakers.jpg

insert_object.sql:

DECLARE
   myblob BLOB;
   myid NUMBER;
BEGIN
   SELECT id, imgblob into myid, myblob FROM PM.IMAGETAB WHERE id = 2;
   INSERT INTO PM.SI_MEDIA (product_id, product_photo) 
   VALUES(myid, new ordsys.SI_StillImage(myblob));
   COMMIT;
END;
/

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:

content_SI.localData is initialized with the specified image.
contentLength_SI is initialized with the length of the image extracted from the specified image.
format_SI is initialized with the specified image format.
height_SI is initialized with the height of the image extracted from the specified image. If the constructor function is not able to extract the height value from the specified image, then you can assign a height value to the height_SI attribute -- for example: myImage.height_SI := height.
width_SI is initialized with the width of the image extracted from the specified image. If the constructor function is not able to extract the width value from the specified image, then you can assign a width value to the width_SI attribute -- for example: myImage.width_SI := width.

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.

Usage Notes

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

The explicitFormat parameter value is a supported format, but it is not equivalent to the format extracted from the specified image.
The explicitFormat parameter value is an unsupported format, but the format extracted from the specified image is not a NULL value.

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:

content_SI.localData is initialized with the specified image.
contentLength_SI is initialized with the length of the image extracted from the specified image.
format_SI is initialized with the specified format.
height_SI is initialized with the specified height if the height cannot be extracted from the specified image.
width_SI is initialized with the specified width if the width cannot be extracted from the specified image.

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

This exception is raised if the content parameter is NULL.

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.

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 explicitFormat parameter value is a supported format, but it is not equivalent to the format extracted from the image.
The explicitFormat parameter value is an unsupported format, but the format extracted from the image is not a NULL value.

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( )
SI_InitFeatures( )
SI_ChangeFormat( )
SI_Content( )
SI_ContentLength( )
SI_Format( )
SI_Height( )
SI_RetainFeatures( )
SI_SetContent( )
SI_Thumbnail( )
SI_Thumbnail(height,width)
SI_Width( )

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

The performance impacts associated with image feature caching are:
- Image processing methods such as SI_SetContent and SI_ChangeFormat will be slower.
- Image matching methods such as SI_Score will be faster.

Image feature extraction and caching are not available for unsupported image formats.

Pragmas

None.

Exceptions

ORDImageSIExceptions.UNSUPPORTED_IMAGE_FORMAT

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

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:

content_SI is converted to the value specified with the targetFormat parameter.
contentLength_SI is updated with the new image length extracted from the content_SI attribute.
format_SI is set equal to the targetFormat parameter value.
height_SI is updated with the new height extracted from the content_SI attribute.
width_SI is updated with the new width extracted from the content_SI attribute.

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:

The value of the format_SI attribute is NULL.
The value of the targetFormat parameter is NULL.
The conversion from format_SI to targetFormat is not supported. (Oracle interMedia determines this by looking up the values in the SI_IMAGE_FORMAT_CONVERSIONS view or the SI_FORMAT_CONVRSNS view in SI_INFORMTN_SCHEMA.)

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:

content_SI is updated with the value specified with the specified image.
contentLength_SI is updated with the new content length extracted from the specified image.
height_SI is updated with the new height extracted from the specified image.
width_SI is updated with the new width extracted from the specified image.

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.

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