Release 9.0.1
Part Number A88786-01
 Home |
 Book List |
 Contents |
 Index |
 Master Index |
 Feedback |
| Oracle interMedia User's Guide and Reference Release 9.0.1 Part Number A88786-01 |
|
Oracle interMedia contains the following information about the ORDImage type and the ORDImageSignature type:
The examples in this chapter assume that the test image table EMP has been created and filled with data. These tables were created using the SQL statements described in Section 8.1.3.
Methods invoked at the ORDSource level that are handed off to the source plug-in for processing have ctx (RAW(4000)) as the first argument. Before calling any of these methods for the first time, the client must allocate the ctx structure, initialize it to NULL, and invoke the source.open( ) method. At this point, the source plug-in can initialize the context for this client. When processing is complete, the client should invoke the source.close( ) method.
Methods invoked from a source plug-in call have the first argument as ctx (RAW(4000)).
|
Note: In the current release, not all source plug-ins will use the ctx argument, but if you code as previously described, your application should work with any current or future source plug-in. |
Oracle interMedia describes the ORDImage object type, which supports the storage, management, and manipulation of image data and the ORDImageSignature object type, which supports content-based retrieval (image matching).
The ORDImage object type supports the storage and management of image data. This object type is defined as follows:
CREATE OR REPLACE TYPE ORDImage AS OBJECT ( ------------------- -- TYPE ATTRIBUTES ------------------- source ORDSource, height INTEGER, width INTEGER, contentLength INTEGER, fileFormat VARCHAR2(4000), contentFormat VARCHAR2(4000), compressionFormat VARCHAR2(4000), mimeType VARCHAR2(4000), --------------------- -- METHOD DECLARATION --------------------- -- CONSTRUCTORS -- STATIC FUNCTION init( ) RETURN ORDImage, STATIC FUNCTION init(srcType IN VARCHAR2, srcLocation IN VARCHAR2, srcName IN VARCHAR2) RETURN ORDImage,-- Methods associated with copy operationsMEMBER PROCEDURE copy(dest IN OUT ORDImage),-- Methods associated with image process operationsMEMBER PROCEDURE process(command IN VARCHAR2), MEMBER PROCEDURE processCopy(command IN VARCHAR2, dest IN OUT ORDImage),-- Methods associated with image property set and check operationsMEMBER PROCEDURE setProperties, MEMBER PROCEDURE setProperties(description IN VARCHAR2), MEMBER FUNCTION checkProperties RETURN BOOLEAN,-- Methods associated with image attributes accessorsMEMBER FUNCTION getHeight RETURN INTEGER, PRAGMA RESTRICT_REFERENCES(getHeight, WNDS, WNPS, RNDS, RNPS), MEMBER FUNCTION getWidth RETURN INTEGER, PRAGMA RESTRICT_REFERENCES(getWidth, WNDS, WNPS, RNDS, RNPS), MEMBER FUNCTION getContentLength RETURN INTEGER, PRAGMA RESTRICT_REFERENCES(getContentLength, WNDS, WNPS, RNDS, RNPS), MEMBER FUNCTION getFileFormat RETURN VARCHAR2, PRAGMA RESTRICT_REFERENCES(getFileFormat, WNDS, WNPS, RNDS, RNPS), MEMBER FUNCTION getContentFormat RETURN VARCHAR2, PRAGMA RESTRICT_REFERENCES(getContentFormat, WNDS, WNPS, RNDS, RNPS), MEMBER FUNCTION getCompressionFormat RETURN VARCHAR2, PRAGMA RESTRICT_REFERENCES(getCompressionFormat, WNDS, WNPS, RNDS, RNPS),-- Methods associated with the local attributeMEMBER PROCEDURE setLocal, MEMBER PROCEDURE clearLocal, MEMBER FUNCTION isLocal RETURN BOOLEAN, PRAGMA RESTRICT_REFERENCES(isLocal, WNDS, WNPS, RNDS, RNPS), -- Methods associated with the date attribute MEMBER FUNCTION getUpdateTime RETURN DATE, PRAGMA RESTRICT_REFERENCES(getUpdateTime, WNDS, WNPS, RNDS, RNPS), MEMBER PROCEDURE setUpdateTime(current_time DATE), -- Methods associated with the mimeType attribute MEMBER FUNCTION getMimeType RETURN VARCHAR2, PRAGMA RESTRICT_REFERENCES(getMimeType, WNDS, WNPS, RNDS, RNPS), MEMBER PROCEDURE setMimeType(mime IN VARCHAR2), -- Methods associated with the source attribute MEMBER FUNCTION getContent RETURN BLOB, PRAGMA RESTRICT_REFERENCES(getContent, WNDS, WNPS, RNDS, RNPS), MEMBER FUNCTION getBFILE RETURN BFILE, PRAGMA RESTRICT_REFERENCES(getBFILE, WNDS, WNPS, RNDS, RNPS), MEMBER PROCEDURE deleteContent, MEMBER PROCEDURE setSource(source_type IN VARCHAR2, source_location IN VARCHAR2, source_name IN VARCHAR2), MEMBER FUNCTION getSource RETURN VARCHAR2, PRAGMA RESTRICT_REFERENCES(getSource, WNDS, WNPS, RNDS, RNPS), MEMBER FUNCTION getSourceType RETURN VARCHAR2, PRAGMA RESTRICT_REFERENCES(getSourceType, WNDS, WNPS, RNDS, RNPS), MEMBER FUNCTION getSourceLocation RETURN VARCHAR2, PRAGMA RESTRICT_REFERENCES(getSourceLocation, WNDS, WNPS, RNDS, RNPS), MEMBER FUNCTION getSourceName RETURN VARCHAR2, PRAGMA RESTRICT_REFERENCES(getSourceName, WNDS, WNPS, RNDS, RNPS), MEMBER PROCEDURE import(ctx IN OUT RAW), MEMBER PROCEDURE importFrom(ctx IN OUT RAW, source_type IN VARCHAR2, source_location IN VARCHAR2, source_name IN VARCHAR2), MEMBER PROCEDURE export(ctx IN OUT RAW, source_type IN VARCHAR2, source_location IN VARCHAR2, source_name IN VARCHAR2), );
where:
This section describes the constructor functions.
The interMedia constructor functions are as follows:
init( ) RETURN ORDImage;
Allows for easy initialization of instances of the ORDImage object type.
None.
None.
None.
This static method initializes all the ORDImage attributes to NULL with the following exceptions:
You should begin using the init( ) method as soon as possible to allow you to more easily initialize the ORDImage object type, especially if the ORDImage type evolves and attributes are added in a future release. INSERT statements left unchanged using the default constructor (which initializes each object attribute), will fail under these circumstances.
Initialize the ORDImage object attributes:
BEGIN INSERT INTO emp VALUES (ORDSYS.ORDImage.init()); END; /
init(srcType IN VARCHAR2,
srcLocation IN VARCHAR2,
srcName IN VARCHAR2)
RETURN ORDImage;
Allows for easy initialization of instances of the ORDImage object type.
The source type of the image data.
The source location of the image data.
The source name of the image data.
None.
None.
This static method initializes all the ORDImage attributes to NULL with the following exceptions:
You should begin using the init( ) method as soon as possible to allow you to more easily initialize the ORDImage object type, especially if the ORDImage type evolves and attributes are added in a future release. INSERT statements left unchanged using the default constructor (which initializes each object attribute), will fail under these circumstances.
Initialize the ORDImage object attributes:
BEGIN INSERT INTO emp VALUES (ORDSYS.ORDImage.init('file','IMGDIR','image1.gif')); END; /
This section presents reference information on the Oracle interMedia methods used for image data manipulation. These methods are described in the following groupings:
The methods described in this chapter show examples based on a test image table EMP. Refer to the EMP table definition that follows when reading through the examples:
CREATE TABLE emp ( ename VARCHAR2(50), salary NUMBER, job VARCHAR2(50), department INTEGER, photo ORDSYS.ORDImage, large_photo ORDSYS.ORDImage); DECLARE Image ORDSYS.ORDImage; BEGIN INSERT INTO emp VALUES ('John Doe', 24000, 'Technical Writer', 123, ORDSYS.ORDImage.init('file','ORDIMGDIR','jdoe.gif')); INSERT INTO emp VALUES ('Jane Doe', 24000, 'Technical Writer', 456, ORDSYS.ORDImage.init('file','ORDIMGDIR','jadoe.gif')); SELECT large_photo INTO Image FROM emp WHERE ename = 'John Doe' FOR UPDATE; Image.setProperties; UPDATE emp SET large_photo = Image WHERE ename = 'John Doe'; COMMIT; SELECT large_photo INTO Image FROM emp WHERE ename = 'Jane Doe' FOR UPDATE; Image.setProperties; UPDATE emp SET large_photo = Image WHERE ename = 'Jane Doe'; COMMIT; END; /
checkProperties RETURN BOOLEAN;
Verifies that the properties stored in attributes of the image object match the properties of the image. This method should not be used for foreign images (those formats not natively supported by interMedia).
None.
Use this method to verify that the image attributes match the actual image.
None.
None.
Check the image attributes:
DECLARE Image ORDSYS.ORDImage; properties_match BOOLEAN; BEGIN SELECT large_photo INTO Image FROM emp WHERE ename = 'John Doe' FOR UPDATE; -- check that properties match the image properties_match := Image.checkProperties(); IF properties_match THEN DBMS_OUTPUT.PUT_LINE('Check Properties succeeded'); END IF; END;
copy(dest IN OUT ORDImage);
Copies an image without changing it.
The destination of the new image.
This method copies the image data, as is, including all source and image attributes, into the supplied local destination image.
If the data is stored locally in the source, then calling this method copies the BLOB to the destination source.localData attribute.
Calling this method copies the external source information to the external source information of the new image whether or not source data is stored locally.
Calling this method implicitly calls the setUpdateTime( ) method on the destination object to update its timestamp information.
None.
NULL_LOCAL_DATA
This exception is raised if you call the copy( ) method and the destination source.localData attribute is not initialized.
This exception is raised if you call the copy( ) method and the source.isLocal attribute value is 1 and the source.localData attribute value is NULL.
Create a copy of the image:
DECLARE Image_1 ORDSYS.ORDImage; Image_2 ORDSYS.ORDImage; BEGIN SELECT photo, large_photo INTO Image_2, Image_1 FROM emp WHERE ename = 'John Doe' FOR UPDATE; -- copy the data from Image_1 to Image_2 Image_1.copy(Image_2); UPDATE emp SET photo = Image_2 WHERE ename = 'John Doe'; END; /
getCompressionFormat RETURN VARCHAR2;
Returns the compression type of an image. This method does not actually read the image, it is a simple access method that returns the value of the compressionFormat attribute.
None.
Use this method rather than accessing the compressionFormat attribute directly to protect yourself from potential changes to the internal representation of the ORDImage object.
PRAGMA RESTRICT_REFERENCES(getCompressionFormat, WNDS,
WNPS, RNDS, RNPS)
None.
Get the compression type of an image:
DECLARE Image ORDSYS.ORDImage; CompressionFormat VARCHAR2(4000); BEGIN SELECT large_photo INTO Image FROM emp WHERE ename = 'John Doe'; -- get the image compression format CompressionFormat := Image.getCompressionFormat(); END;
getContentFormat RETURN VARCHAR2;
Returns the content type of an image (such as monochrome). This method does not actually read the image; it is a simple access method that returns the value of the contentFormat attribute.
None.
Use this method rather than accessing the contentFormat attribute directly to protect yourself from potential changes to the internal representation of the ORDImage object.
PRAGMA RESTRICT_REFERENCES(getContentFormat, WNDS,
WNPS, RNDS, RNPS)
None.
Get the type of an image:
DECLARE Image ORDSYS.ORDImage; ContentFormat VARCHAR2(4000); BEGIN SELECT large_photo INTO Image FROM emp WHERE ename = 'John Doe'; -- get the image content format ContentFormat := Image.getContentFormat(); END;
getContentLength RETURN INTEGER;
Returns the length of the image data content stored in the source. This method does not actually read the image; it is a simple access method that returns the value of the content length attribute.
None.
Use this method rather than accessing the contentLength attribute directly to protect from potential future changes to the internal representation of the ORDImage object.
PRAGMA RESTRICT_REFERENCES(getContentLength, WNDS,
WNPS, RNDS, RNPS)
None.
Get the length of the image data content stored in the source:
DECLARE Image ORDSYS.ORDImage; ContentLength INTEGER; BEGIN SELECT large_photo INTO Image FROM emp WHERE ename = 'John Doe'; -- get the image size ContentLength := Image.getContentLength(); END;
getFileFormat RETURN VARCHAR2;
Returns the file type of an image (such as TIFF or JFIF). This method does not actually read the image; it is a simple access method that returns the value of the fileFormat attribute.
None.
Use this method rather than accessing the fileFormat attribute directly to protect yourself from potential changes to the internal representation of the ORDImage object.
PRAGMA RESTRICT_REFERENCES(getFileFormat, WNDS, WNPS, RNDS, RNPS)
None.
Get the file type of an image:
DECLARE Image ORDSYS.ORDImage; FileFormat VARCHAR2(4000); BEGIN SELECT large_photo INTO Image FROM emp WHERE ename = 'John Doe'; -- get the image file format FileFormat := Image.getFileFormat(); END;
getHeight RETURN INTEGER;
Returns the height of an image in pixels. This method does not actually read the image; it is a simple access method that returns the value of the height attribute.
None.
Use this method rather than accessing the height attribute directly to protect yourself from potential changes to the internal representation of the ORDImage object.
PRAGMA RESTRICT_REFERENCES(getHeight, WNDS, WNPS, RNDS, RNPS)
None.
Get the height of an image:
DECLARE Image ORDSYS.ORDImage; Height INTEGER; BEGIN SELECT large_photo INTO Image FROM emp WHERE ename = 'John Doe'; -- get the image height Height := Image.getHeight(); END; /
getWidth RETURN INTEGER;
Returns the width of an image in pixels. This method does not actually read the image; it is a simple access method that returns the value of the width attribute.
None.
Use this method rather than accessing the width attribute directly to protect yourself from potential changes to the internal representation of the ORDImage object.
PRAGMA RESTRICT_REFERENCES(getWidth, WNDS, WNPS, RNDS, RNPS)
None.
Get the width of an image:
DECLARE Image ORDSYS.ORDImage; Width INTEGER; BEGIN SELECT large_photo INTO Image FROM emp WHERE ename = 'John Doe'; -- get the image width Width := Image.getWidth(); END; /
MEMBER PROCEDURE import(ctx IN OUT RAW);
Transfers image data from an external image data source to a local source (localData) within an Oracle database.
The source plug-in context information. This must be allocated. You must call the source.open( ) method; see the introduction to this chapter for more information.
Use the setSource( ) method to set the external source type, location, and name prior to calling the import( ) method.
You must ensure that the directory exists or is created before you use this method for srcType 'file'.
After importing data from an external image data source to a local source (within an Oracle database), the source information remains unchanged (that is, pointing to the source from where the data was imported).
Invoking this method implicitly calls the setUpdateTime( ) and setLocal methods.
If the file format of the imported image is not previously set to a string beginning with "OTHER", the setProperties( ) method is also called. Set the file format to a string preceded by "OTHER" for foreign image formats; calling the setProperties( ) method for Foreign Images does this for you.
None.
ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION
This exception is raised if you call the import( ) method and the value of srcType is NULL.
ORDSourceExceptions.NULL_SOURCE
This exception is raised if you call the import( ) method and the value of dlob is NULL.
ORDSourceExceptionsMETHOD_NOT_SUPPORTED
This exception is raised if you call the import( ) method and this method is not supported by the source plug-in being used.
See Appendix H for more information about these exceptions.
Import image data from an external image data source into the local source:
DECLARE Image ORDSYS.ORDImage; ctx RAW(4000) :=NULL; BEGIN -- select the image to be imported SELECT large_photo INTO Image FROM emp WHERE ename = 'John Doe' FOR UPDATE; -- import the image into the database Image.import(ctx); -- update the image object UPDATE emp SET large_photo = Image WHERE ename = 'John Doe'; END; /
importFrom(ctx IN OUT RAW,
source_type IN VARCHAR2,
source_location IN VARCHAR2,
source_name IN VARCHAR2);
Transfers image data from the specified external image data source to a local source (localData) within an Oracle database.
The source plug-in context information. This must be allocated. You must call the source.open( ) method; see the introduction to this chapter for more information.
The source type of the image data.
The location from where the image data is to be imported.
The name of the image data.
This method is similar to the import( ) method except the source information is specified as parameters to the method instead of separately.
You must ensure that the directory exists or is created before you use this method for srcType 'file'.
After importing data from an external image data source to a local source (within an Oracle database), the source information (that is, pointing to the source from where the data was imported) is set to the input values.
Invoking this method implicitly calls the setUpdateTime( ) and setLocal methods.
If the file format of the imported image is not previously set to a string beginning with "OTHER", the setProperties( ) method is also called. Set the file format to a string preceded by "OTHER" for foreign image formats; calling the setProperties( ) method for Foreign Images does this for you.
None.
ORDSourceExceptions.NULL_SOURCE
This exception is raised if you call the importFrom( ) method and the value of dlob is NULL.
ORDSourceExceptions.METHOD_NOT_SUPPORTED
This exception is raised if you call the importFrom( ) method and this method is not supported by the source plug-in being used.
ORDSourceExceptions.SOURCE_PLUGIN_EXCEPTION
This exception is raised if you call the importFrom( ) method within a source plug-in when any other exception is raised.
See Appendix H for more information about these exceptions.
Import image data from the specified external data source into the local source:
DECLARE Image ORDSYS.ORDImage; ctx RAW(4000) :=NULL; BEGIN -- select the image to be imported SELECT large_photo INTO Image FROM emp WHERE ename = 'John Doe' FOR UPDATE; -- import the image into the database Image.importFrom(ctx, 'file', 'ORDIMGDIR', 'jdoe.gif'); -- update the image object UPDATE emp SET large_photo = Image WHERE ename = 'John Doe'; END; /
process(command IN VARCHAR2);
Performs one or more image processing operations on a BLOB, writing the image back onto itself.
A list of image processing operations to perform on the image.
You can change one or more of the image attributes shown in Table 8-1. Table 8-2 shows additional changes that can be made only to raw pixel and foreign images.
| Operator Name | Usage | Values |
|---|---|---|
|
compressionFormat |
Compression type/format; coerces output to specified compression format if supported by file format. |
JPEG, SUNRLE, BMPRLE,TARGARLE, LZW, LZWHDIFF, FAX3, FAX4, HUFFMAN3, PACKBITS, GIFLZW, ASCII, RAW, DEFLATE, NONE |
|
compressionQuality |
Compression quality; determines quality of lossy compression; JPEG only. |
MAXCOMPRATIO, MAXINTEGRITY, LOWCOMP, MEDCOMP, HIGHCOMP |
|
contentFormat |
MONOCHROME | nBIT[BIP | BIL | BSQ] {LUT[RGB | GRAY] | {[DRCT]RGB | GREY}}; coerces output to specified content format. |
See Figure 8-1 for use and syntax flow of the following values: MONOCHROME, 1BIT, 2BIT, 4BIT, 8BIT, 12BIT, 16BIT, 24BIT, 32BIT, 48BIT, BIP, BIL, BSQ, LUT, DRCT, RGB, GRAY [SCALE], GREY [SCALE] |
|
cut |
Window to cut or crop (origin.x origin.y width height); first pixel in x or y is 0 (zero); must define a window inside image. |
positive INTEGER INTEGER INTEGER INTEGER |
|
fileFormat |
File format of the image; coerces output to specified file format. |
BMPF, CALS, GIFF, JFIF, PBMF, PGMF, PICT, PNGF, PNMF, PPMF, RASF, RPIX, TGAF, TIFF, WBMP |
|
fixedScale |
Scale to a specific size in pixels (width, height); may not be combined with other scale verbs. |
positive INTEGER INTEGER |
|
maxScale |
Scale to a specific size in pixels, while maintaining the aspect ratio (maxWidth, maxHeight); may not be combined with other scale verbs. |
positive INTEGER INTEGER |
|
scale |
Scale factor (for example, 0.5 or 2.0); uniformly scales image; may not be combined with other scale verbs. |
<FLOAT> positive |
|
xScale |
X-axis scale factor (default is 1); non-uniformly scales image; may be combined only with the yScale operator; may not be combined with any other scale verbs. |
<FLOAT> positive |
|
yScale |
Y-axis scale factor (default is 1); non-uniformly scales image; may only be combined with the xScale operator; may not be combined with any other scale verbs. |
<FLOAT> positive |
| Operator Name | Usage | Values |
|---|---|---|
|
channelOrder |
Indicates the relative position of the red, green, and blue channels (bands) within the image; changes order of output channels. Only for RPIX. |
RGB (default), RBG, GRB, GBR, BRG, BGR |
|
inputChannels |
For multiband images, specify either one (grayscale) or three integers indicating which channels to assign to red (first), green (second), and blue (third). Note that this parameter affects the source image, not the destination; RPIX only. |
INTEGER or |
|
interleave (deprecated in release 9.0.1; functions moved to ContentFormat operator) |
Controls band layout within the image: Coerces output to be BIP, BIL, or BSQ; RPIX only. |
BIP (default), BIL, BSQ |
|
pixelOrder |
If NORMAL, then the leftmost pixel appears first in the image; coerces pixel direction. RPIX only. |
NORMAL (default), REVERSE |
|
scanlineOrder |
If NORMAL, then the top scanline appears first in the image; coerces scanline direction. RPIX and BMPF only. |
NORMAL (default), INVERSE |
|
Dither |
See Section D.4.6 for more information. |
ERRORDIFFUSION, ORDEREDDITHER |
|
Page |
Selects a page from a multipage file; for use with TIFF only; first page is 0 (zero). |
positive INTEGER |
|
Tiled |
No arguments; forces output image to be tiled; for use with TIFF only. |
|
There is no implicit import( ) or importFrom( ) call performed when you call this method; if data is external, you must first call import( ) or importFrom( ) to make the data local before you can process it.
Implicit setProperties( ), setUpdateTime( ), and setMimeType( ) methods are done after the process( ) method is called.
See Appendix D for more information on process( ) method operators.
None.
DATA_NOT_LOCAL
This exception is raised if you call the process( ) method and the data is not local or the source.localData attribute is not initialized.
Example 1: Change the file format of image1 to GIF:
image1.process('fileFormat=GIFF');
Example 2: Change image1 to use lower quality JPEG compression and double the length of the image along the X-axis:
image1.process('compressionFormat=JPEG, compressionQuality=MAXCOMPRATIO, xScale="2.0"');
Note that changing the length on only one axis (for example, xScale=2.0) does not affect the length on the other axis, and would result in image distortion. Also, only the xScale and yScale parameters can be combined in a single operation. Any other combinations of scale operators result in an error.
The maxScale and fixedScale operators are especially useful for creating thumbnail images from various-sized originals. The following line creates at most a 32-by-32 pixel thumbnail image, preserving the original aspect ratio:
image1.process('maxScale=32 32');
Example 3: Convert the image to TIFF:
DECLARE Image ORDSYS.ORDImage; BEGIN SELECT photo INTO Image FROM emp WHERE ename = 'John Doe' FOR UPDATE; Image.process('fileFormat=TIFF'); UPDATE emp SET photo = Image WHERE ename = 'John Doe'; END; /
Example 4: Change the content format to 8BIT, BIP pixel layout, LUT interpretation, and RGB color space:
DECLARE Image ORDSYS.ORDImage; BEGIN SELECT photo INTO Image FROM emp WHERE ename = 'John Doe' FOR UPDATE; Image.process('fileFormat=TIFF','contentFormat=8BITBIPLUTRGB'); UPDATE emp SET photo = Image WHERE ename = 'John Doe'; END; /
processCopy(command IN VARCHAR2,
dest IN OUT ORDImage);
Copies an image stored internally or externally to another image stored internally in a BLOB.
A list of image processing changes to make for the image in the new copy.
The destination of the new image.
See Table 8-1, "Image Processing Operators" and Table 8-2, "Additional Image Processing Operators for Raw Pixel and Foreign Images".
You cannot specify the same BLOB as both the source and destination.
Calling this method processes the image into the destination BLOB from any source (local or external).
Implicit setProperties( ), setUpdateTime( ), and setMimeType( ) methods are done on the destination image after the processCopy( ) method is called.
See Appendix D for more information on processCopy operators.
None.
NULL_DESTINATION
This exception is raised if you call the processCopy( ) method and the value of dest is NULL.
DATA_NOT_LOCAL
This exception is raised if you call the processCopy( ) method and the dest.source.isLocal attribute value is FALSE, (the destination image must be local).
NULL_LOCAL_DATA
This exception is raised if you call the processCopy( ) method and the dest.source.localData attribute value is NULL (destination image must be initialized).
This exception is raised if you call the processCopy( ) method and the source.isLocal attribute value is 1 and the source.localData attribute value is NULL.
Copy an image, changing the file format, compression format, and data format in the destination image:
DECLARE Image_1 ORDSYS.ORDImage; Image_2 ORDSYS.ORDImage; mycommand VARCHAR2(400); BEGIN SELECT photo, large_photo INTO Image_2, Image_1 FROM emp WHERE ename = 'John Doe' FOR UPDATE; mycommand := 'fileFormat=tiff compressionFormat=packbits contentFormat = 8bitlut'; Image_1.processCopy(mycommand, Image_2); UPDATE emp SET photo = Image_2 WHERE ename = 'John Doe'; END; /
setProperties;
Reads the image data to get the values of the object attributes, then stores them into the appropriate attribute fields. The image data can be stored in the database in a BLOB, or externally in a BFILE or URL. If the data is stored externally in anything other than a BFILE, the data is read into a temporary BLOB in order to determine the image characteristics.
This method should not be called for foreign images. Use the setProperties(description) method for foreign images.
None.
After you have copied, stored, or processed a native format image, call this method to set the current characteristics of the new content, except when this method is called implicitly.
This method sets the following information about an image:
Calling this method implicitly calls the setUpdateTime( ) and the setMimeType( ) methods.
None.
NULL_LOCAL_DATA
This exception is raised if you call the setProperties( ) method and the source.isLocal attribute value is 1 and the source.localData attribute value is NULL.
Select the image, and then set the attributes using the setProperties method:
DECLARE Image ORDSYS.ORDImage; BEGIN INSERT INTO emp VALUES ('John Doe', 24000, 'Technical Writer', 123, ORDSYS.ORDImage.init('file','ORDIMGDIR','jdoe.gif'); -- select the newly inserted row for update SELECT large_photo INTO Image FROM emp WHERE ename = 'John Doe' FOR UPDATE; -- set property attributes for the image data Image.setProperties(); DBMS_OUTPUT.PUT_LINE('image width = ' || image.getWidth()); DBMS_OUTPUT.PUT_LINE('image height = ' || image.getHeight()); DBMS_OUTPUT.PUT_LINE('image size = ' || image.getContentLength()); DBMS_OUTPUT.PUT_LINE('image file type = ' || image.getFileFormat()); DBMS_OUTPUT.PUT_LINE('image type = ' || image.getContentFormat()); DBMS_OUTPUT.PUT_LINE('image compression = ' || image.getCompressionFormat()); DBMS_OUTPUT.PUT_LINE('image mime type = ' || image.getMimeType()); UPDATE emp SET large_photo = Image WHERE ename = 'John Doe'; END; /
Example output:
image width = 360 image height = 490 image size = 66318 image file type = JFIF image type = 24BITRGB image compression = JPEG image mime type = image/jpeg
setProperties(description IN VARCHAR2);
Allows you to write the characteristics of a foreign image into the appropriate attribute fields.
Specifies the image characteristics to set for the foreign image.
|
Note: Once you have set the properties for a foreign image, it is up to you to keep the properties consistent. If interMedia detects an unknown file format, it will not implicitly set the properties. |
After you have copied, stored, or processed a foreign image, call this method to set the characteristics of the new image content. Unlike the native image types described in Appendix E, foreign images either do not contain information on how to interpret the bits in the file or, interMedia does not understand the information. In this case, you must set the information explicitly.
You can set the following image characteristics for foreign images, as shown in Table 8-3.
The values supplied to setProperties( ) are written to the existing ORDImage data attributes. The fileFormat is set to "OTHER" and includes the user string, if supplied; for example, 'OTHER: LANDSAT'.
None.
NULL_PROPERTIES_DESCRIPTION
This exception is raised if you call the setProperties( ) method for Foreign Images and the description attribute value is NULL.
Select the foreign image and then set the properties for the image:
DECLARE Image ORDSYS.ORDImage; BEGIN SELECT large_photo INTO Image FROM emp WHERE ename = 'John Doe' FOR UPDATE; -- set property attributes for the image data Image.setProperties('width=123 height=321 compressionFormat=NONE' || ' userString=DJM dataOffset=128' || ' scanlineOrder=INVERSE pixelOrder=REVERSE' || ' interleaving=BIL numberOfBands=1' || ' defaultChannelSelection=1'); UPDATE emp SET large_photo = Image WHERE ename = 'John Doe'; END; /
Oracle interMedia describes the ORDImageSignature object type, which supports content-based retrieval (image matching).
The examples in this section assume that a table called stockphotos has been created and filled with some photographic images. The table was created using the following SQL statement:
CREATE TABLE stockphotos (photo_id NUMBER, photographer VARCHAR2(64), annotation VARCHAR2(255), photo ORDSYS.ORDImage, photo_sig ORDSYS.ORDImageSignature);
When you are storing or copying images, you must first create an empty BLOB in the table. The following method invocation creates an empty ORDImageSignature object:
ORDSYS.ORDImageSignature.init();
The ORDImageSignature object type supports content-based retrieval or image matching. This object type is defined as follows:
CREATE OR REPLACE TYPE ORDImageSignature AS OBJECT ( -- Signature of the image. Contains color, texture -- and shape information of the image. It is stored -- in a BLOB. signature BLOB, ----------------------- -- METHOD DECLARATION -- Makes the callout STATIC FUNCTION init RETURN ORDImageSignature, STATIC FUNCTION evaluateScore(sig1 IN ORDImageSignature, sig2 IN ORDImageSignature, weights IN VARCHAR2) RETURN FLOAT, STATIC FUNCTION isSimilar(sig1 IN ORDImageSignature, sig2 IN ORDImageSignature, weights IN VARCHAR2, threshold IN FLOAT) RETURN INTEGER, MEMBER PROCEDURE generateSignature(image IN ORDImage) );
where:
This section describes the constructor functions.
The interMedia constructor functions are as follows:
init( ) RETURN ORDImageSignature;
Allows for easy initialization of instances of the ORDImageSignature object type.
None.
None.
None.
This static method initializes the ORDImageSignature signature attribute to empty_blob.
You should always use the init( ) method to initialize the ORDImageSignature object type, which will be especially useful if the ORDImageSignature type evolves and attributes are added in a future release.
Initialize the ORDImageSignature object attribute:
BEGIN INSERT INTO stockphotos VALUES ( 5,Al MacFarlane,'red plaid', ORDSYS.ORDImage.init('file','ORDIMGDIR','macfarlane.gif'), ORDSYS.ORDImageSignature.init( )); END; /
This section presents reference information on the Oracle interMedia methods used for image data manipulation. These methods are described in the following groupings:
evaluateScore(
sig1 IN ORDImageSignature,
sig2 IN ORDImageSignature,
weights IN VARCHAR2)
RETURN FLOAT;
A static method of the ORDImageSignature object type that evaluates the distance between two input signatures based on the influence of the specified attributes in the weights parameter.
Signature object.
Signature object.
A string consisting of matching attribute names followed by values. The matching attributes refer to the weights assigned by the user to the different attributes that influences the kind of match. The string can have all or some of the following attributes. Attributes not specified by the user have a default value of 0. At least one of the attributes, color, texture, and shape, must have a value greater than 0.
color: The importance of the feature color. It is a value between 0.0 and 1.0. DEFAULT: 0
texture: The importance of the feature texture. It is a value between 0.0 and 1.0. DEFAULT: 0
shape: The importance of the feature shape. It is a value between 0.0 and 1.0. DEFAULT: 0
location: The importance of the location of the regions in the image. It is a value between 0.0 and 1.0. DEFAULT: 0. Location weight string cannot be specified alone, it must be used with another weight string.
None.
None.
None.
Compare two signatures and evaluate the score between them:
DECLARE t_image ORDSYS.ORDImage; image_sig ORDSYS.ORDImageSignature; compare_sig ORDSYS.ORDImageSignature; BEGIN SELECT photo, photo_sig INTO t_image, image_sig FROM stockphotos WHERE photo_id=1 FOR UPDATE; -- evaluate the signature of two images ORDSYS.ORDImageSignature.evaluateScore(image_sig,compare_sig, 'color=1.0,texture=0,shape=0,location=0'); UPDATE stockphotos SET photo = t_image WHERE photo_id=1; END; /
generateSignature (image IN ORDImage);
Generates a signature for a given input image that is passed back as the signature object.
The image object whose signature is to be generated.
None.
None.
None.
Generate a signature for an image object:
DECLARE t_image ORDSYS.ORDImage; image_sig ORDSYS.ORDImageSignature; BEGIN SELECT photo, photo_sig INTO t_image, image_sig FROM stockphotos WHERE photo_id=1 FOR UPDATE; -- generate a signature image_sig.generateSignature(t_image); UPDATE stockphotos SET photo_sig = image_sig WHERE photo_id =1; END; /
isSimilar(
sig1 IN ORDImageSignature,
sig2 IN ORDImageSignature,
weights IN VARCHAR2,
threshold IN FLOAT)
RETURN INTEGER;
A static method of the ORDImageSignature object type that compares two signatures and computes the distance between them based on the influence of the specified attributes in the weights parameter and the specified threshold value. If the distance is less than the specified threshold, a value of 1 is returned, otherwise a value of 0 is returned.
Signature object.
Signature object.
A string consisting of matching attribute names followed by values. The matching attributes refer to the weights assigned by the user to the different attributes that influences the kind of match. The string can have all or some of the following attributes. Attributes not specified by the user have a default value of 0. At least one of the attributes, color, texture, or shape, must have a value greater than 0.
color: The importance of the feature color. It is a value between 0.0 and 1.0. DEFAULT: 0
texture: The importance of the feature texture. It is a value between 0.0 and 1.0. DEFAULT: 0
shape: The importance of the feature shape. It is a value between 0.0 and 1.0. DEFAULT: 0
location: The importance of the location of the regions in the image. It is a value between 0.0 and 1.0. DEFAULT: 0. This attribute must be specified with one other attribute; it cannot be specified by itself.
The degree of the match that the user desires. For example, if the value is specified as 10, then only those images whose signatures are a distance of 10 or less (score of 10 or less) from the query signature will be returned. The value of the threshold ranges from 0 to 100, which is the range of the distance.
You can use this method to compare two signatures not stored in the database or when you must perform a comparison within a PL/SQL construct.
None.
None.
Compute the distance between two signatures:
DECLARE t_image ORDSYS.ORDImage; image_sig ORDSYS.ORDImageSignature; imagesig2 ORDSYS.ORDImageSignature; BEGIN SELECT photo, photo_sig INTO t_image, image_sig FROM stockphotos WHERE photo_id = 1 FOR UPDATE; -- compute the distance between two signatures ORDSYS.ORDImageSignature.isSimilar(image_sig,imagesig2,'color=1.0,texture=0,shape=0,location=0',10); UPDATE stockphotos SET photo = t_image WHERE photo_id = 1; END; /
The following ORDImageSignature operators are schema level operators and do not reside within a package. These operators use the domain index, if it exists.
...IMGSimilar (ORDSYS.ORDImageSignature,
ORDSYS.ORDImageSignature,
VARCHAR2,
FLOAT
[ ,referencetoScore IN NUMBER] )...;
Determines whether or not two images match. Specifically, the operator compares the signatures of two images, computes a weighted sum of the distance between the two images using user-supplied weight values for the visual attributes, compares the weighted sum with the threshold value, and returns the integer value 1 if the weighted sum is less than or equal to the threshold value. Otherwise, the operator returns 0.
The signature of the image to which you are comparing the query image. Data type is ORDImageSignature. To use the domain index for the comparison, this first parameter must be the signature column on which the domain index has been created. Otherwise, Oracle9i uses the non-indexed implementation of query evaluation.
The signature of the query or test image. Data type is ORDImageSignature.
A list of weights to apply to each visual attribute. Data type is VARCHAR2. The following attributes can be specified, with a value of 0.0 specifying no importance and a value of 1.0 specifying highest importance. You must specify a value greater than zero for at least one of the attributes, not including location.
The threshold value with which the weighted sum of the distances is to be compared. If the weighted sum is less than or equal to the threshold value, the images are considered to match. The range of this parameter is from 0.0 to 100.0.
An optional parameter used when ancillary data (score of similarity) is required elsewhere in the query. Set this parameter to the same value here as used in the IMGScore( ) operator. Data type is NUMBER.
Returns an integer value of 0 (not similar) or 1 (match).
None.
None.
Before the IMGSimilar operator can be used, the image signatures must be created with the generateSignature( ) method. Also, to use the domain index, the index of type ORDImageIndex must have already been created. See Section 2.4 for information on creating and using the index and see Section 2.5 for additional performance tips.
The IMGSimilar( ) operator returns Boolean values to indicate whether two images match (true, if their image matching score is below the threshold). If you want to know the score value itself, you can use the IMGScore( ) operator in conjunction with the IMGSimilar( ) operator to retrieve the score computed in the IMGSimilar( ) operator.
The IMGSimilar( ) operator is useful when the application needs a simple Yes or No for whether or not two images match. The IMGScore( ) operator is useful when an application wants to make finer distinctions about matching or to perform special processing based on the degree of similarity between images.
The weights supplied for the four visual attributes are normalized prior to processing such that they add up to 1.0.
You must specify at least one of the three image attributes color, texture, or shape in the weightstring.
Using the IMG index, find all images similar to the query image using a threshold value of 25 and the following weights for the visual attributes:
This example assumes you already used the generateSignature( ) method to generate a signature for the query image. If an index exists on the signature column, it will be used automatically. See the IMGScore( ) operator for an example that uses the referenceToScore parameter.
DECLARE t_img ORDSYS.ORDImage; i INTEGER; image_sig ORDSYS.ORDImageSignature; query_signature ORDSYS.ORDImageSignature; BEGIN SELECT photo_id, photo, photo_sig INTO i, t_img, image_sig FROM stockphotos WHERE ORDSYS.IMGSimilar(photo_sig, query_signature, 'color="0.2" texture="0.1" shape="0.5" location="0.2"', 25) = 1; END; /
...IMGScore (NUMBER)...;
Compares the signatures of two images and returns a number representing the weighted sum of the distances for the visual attributes. IMGScore( ) is an ancillary operator, used only in conjunction with the primary operator, IMGSimilar( ) to retrieve the score computed in the IMGSimilar( ) operator. Each IMGScore( ) and IMGSimilar( ) operator shares the same reference number.
Identifier to an IMGSimilar( ) operator. This identifier indicates that the image matching score value returned by the IMGScore( ) operator is the same one used in the corresponding IMGSimilar( ) operator. This parameter can also be used to maintain references for multiple invocations of the IMGSimilar( ) operator. Data type is NUMBER.
This function returns a FLOAT value between 0.0 and 100.0, where 0.0 means the images are identical and 100.0 means the images are completely different.
None.
None.
Before the IMGScore( ) operator can be used, the image signatures must be created with the generateSignature( ) method. Also, if you want the comparison to use the domain index, the index of type ORDImageIndex must have already been created. See Section 2.4 for information on creating and using the index, and see Section 2.5 for additional performance tips.
The IMGScore( ) operator can be useful when an application wants to make finer distinctions about matching than the simple Yes or No returned by IMGSimilar( ). For example, using the score returned by IMGScore( ), the application might assign each image being compared to one of several categories, such as Definite Matches, Probable Matches, Possible Matches, and Nonmatches. The IMGScore( ) operator can also be useful if the application needs to perform special processing based on the degree of similarity between images.
Example 1
Find the weighted sum of the distances between a test image and the other images in the stockphotos table, using a threshold of 50 and the following weights for the visual attributes:
This example assumes that the signatures were already created using the generateSignature( ) method and they are stored in the database. Notice that both IMGScore( ) and IMGSimilar( ) are using 123 as the reference number in this example.
DECLARE img_score NUMBER; i INTEGER; query_signature ORDSYS.ORDImageSignature; image_sig ORDSYS.ORDImageSignature; t_img ORDSYS.ORDImage;
BEGIN SELECT photo_id, ORDSYS.IMGScore(123), photo, photo_sig INTO i, img_score, t_img, image_sig FROM stockphotos WHERE ORDSYS.IMGSimilar(image_sig, query_signature, 'color="0.2" texture="0.1" shape="0.5" location="0.2"', 50, 123) = 1 END;
/
The following shows possible results from this example. The first image has the lowest score, and therefore is the best match of the test image. Changing the weights used in the scoring would lead to different results.
ENAME SCORE ---------- ------------ 1 10.5 1 row selected.
Example 2
The following example demonstrates the use of reference numbers to refer to scores evaluated in different IMGSimilar calls. In this example, a query is searching for a stock image in the stockphotos table that is similar in color to query image 1 and similar in shape and location to query image 2.
DECLAREimg_score NUMBER;i INTEGER;query_sig1 ORDSYS.ORDImageSignature;query_sig2 ORDSYS.ORDImageSignature;image1_sig ORDSYS.ORDImageSignature;t_img ORDSYS.ORDImage;BEGINSELECT photo_id, ORDSYS.IMGScore(1), ORDSYS.IMGScore(2), photo,photo_sigINTO i, img_score, t_img, image_sig FROM stockphotosWHEREORDSYS.IMGSimilar(image_sig, query_sig1,'color="1.0"', 50, 1) = 1ANDORDSYS.IMGSimilar(image_sig, query_sig2,'shape="0.5" location="0.2"', 50, 2) = 1END;/
|
 Copyright © 1996-2001, Oracle Corporation. All Rights Reserved. |
|