Oracle® interMedia Reference 10g Release 2 (10.2) Part Number B14297-01 |
|
|
View PDF |
Oracle interMedia ("interMedia") contains the following information about the ORDImage object type and the ORDImageSignature object type:
The examples in this chapter use the ONLINE_MEDIA table in the Product Media sample schema. To replicate the examples on your own computer, you should begin with the examples shown in the reference pages for the ORDImage and ORDImageSignature constructors and the import( ) and importFrom( ) methods. Substitute image files you have for the ones shown in the examples. In addition, for a user "ron" to use the examples, the following statements must be issued before ron executes the examples, where "/mydir/work" is the directory where ron will find the image data:
CONNECT /as sysdba CREATE OR REPLACE DIRECTORY FILE_DIR as '/mydir/work'; GRANT READ ON DIRECTORY FILE_DIR TO 'user';
See Oracle Database Sample Schemas for information about the sample schemas.
Note:
If you manipulate the image data itself (by either directly modifying the BLOB or changing the external source), then you must ensure that the object attributes stay synchronized and the update time is modified; otherwise, the object attributes will not match the image data.Methods invoked at the ORDSource level that are handed off to the source plug-in for processing have ctx (RAW) as the first argument. Before calling any of these methods for the first time, the client should allocate the ctx structure, initialize it to NULL, and invoke the openSource( ) method. At this point, the source plug-in can initialize the context for this client. When processing is complete, the client should invoke the closeSource( ) method.
Methods invoked from a source plug-in call have the first argument as ctx (RAW).
Note:
In the current release, none of the plug-ins provided by Oracle and not all source or format plug-ins will use the ctx argument, but if you code as previously described, your application should work with current or future source or format plug-ins.You should use any of the individual set methods to set the attribute value for an object for formats not natively supported; otherwise, for formats natively supported, use the setProperties( ) method to populate the attributes of the object or write a format 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). This object type is defined as follows in the ordispec.sql
file:
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 operations MEMBER PROCEDURE copy(dest IN OUT ORDImage), -- -- Methods associated with image processing operations MEMBER PROCEDURE process(command IN VARCHAR2), -- MEMBER PROCEDURE processCopy(command IN VARCHAR2, dest IN OUT ORDImage), -- -- Methods associated with image property set and check operations MEMBER PROCEDURE setProperties( ), MEMBER PROCEDURE setProperties(description IN VARCHAR2), MEMBER FUNCTION checkProperties RETURN BOOLEAN, -- -- Methods associated with image attributes accessors MEMBER 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 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 metadata attributes MEMBER FUNCTION getMetadata(metadataType IN VARCHAR2 DEFAULT 'ALL') RETURN SYS.XMLSEQUENCETYPE, -- MEMBER PROCEDURE putMetadata(xmlData IN SYS.XMLType, metadataType IN VARCHAR2 DEFAULT 'XMP', encoding IN VARCHAR2 DEFAULT 'UTF-8'), -- -- Methods associated with the local attribute MEMBER 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 getContentLength RETURN INTEGER, PRAGMA RESTRICT_REFERENCES(getContentLength, WNDS, WNPS, RNDS, RNPS), -- 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 FUNCTION getDicomMetadata(optionString IN VARCHAR2) RETURN XMLType, -- 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), -- MEMBER FUNCTION processSourceCommand( ctx IN OUT RAW, cmd IN VARCHAR2, arguments IN VARCHAR2, result OUT RAW) RETURN RAW, -- -- Methods associated with file operations on the source MEMBER FUNCTION openSource(userArg IN RAW, ctx OUT RAW) RETURN INTEGER, -- MEMBER FUNCTION closeSource(ctx IN OUT RAW) RETURN INTEGER, -- MEMBER FUNCTION trimSource(ctx IN OUT RAW, newlen IN INTEGER) RETURN INTEGER, -- MEMBER PROCEDURE readFromSource(ctx IN OUT RAW, startPos IN INTEGER, numBytes IN OUT INTEGER, buffer OUT RAW), -- MEMBER PROCEDURE writeToSource(ctx IN OUT RAW, startPos IN INTEGER, numBytes IN OUT INTEGER, buffer IN RAW), );
where:
source: the source of the stored image data.
height: the height of the image in pixels.
width: the width of the image in pixels.
contentLength: the size of the image file on disk, in bytes.
fileFormat: the file type or format in which the image data is stored (TIFF, JIFF, and so forth).
contentFormat: the type of image (monochrome and so forth).
compressionFormat: the compression algorithm used on the image data.
mimeType: the MIME type information.
This section describes the ORDImage constructor functions, which are the following:
Format
init( ) RETURN ORDImage;
Description
Initializes instances of the ORDImage object type.
Parameters
None.
Pragmas
None.
Exceptions
None.
Usage Notes
This constructor is a static method that initializes all the ORDImage attributes to NULL with the following exceptions:
source.updateTime is set to SYSDATE
source.local is set to 1 (local)
source.localData is set to empty_blob
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.
Examples
Initialize the ORDImage object attributes:
BEGIN INSERT INTO pm.online_media (product_id, product_photo) VALUES (3501, ORDSYS.ORDImage.init()); COMMIT;END;/
Format
init(srcType IN VARCHAR2,
srcLocation IN VARCHAR2,
srcName IN VARCHAR2)
RETURN ORDImage;
Description
Initializes instances of the ORDImage object type.
Parameters
The source type of the image data.
The source location of the image data.
The source name of the image data.
Pragmas
None.
Exceptions
None.
Usage Notes
This constructor is a static method that initializes all the ORDImage attributes to NULL with the following exceptions:
source.updateTime is set to SYSDATE
source.local is set to 0
source.localData is set to empty_blob
source.srcType is set to the input value
source.srcLocation is set to the input value
source.srcName is set to the input value
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.
Examples
Initialize the ORDImage object attributes:
BEGIN INSERT INTO pm.online_media (product_id, product_photo) VALUES (3515, ORDSYS.ORDImage.init('FILE', 'FILE_DIR','speaker.jpg')); COMMIT; END; /
This section presents reference information on the interMedia methods used specifically for image data manipulation.
Chapter 2 presents reference information on the interMedia methods that are common to ORDAudio, ORDDoc, ORDImage, and ORDVideo. Use the methods presented in both chapters to get and set attributes, perform processing operations, and perform metadata extractions.
The following methods are presented in this section:
Format
checkProperties( ) RETURN BOOLEAN;
Description
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).
Parameters
None.
Usage Notes
Use this method to verify that the image attributes match the actual image.
Pragmas
None.
Exceptions
ORDImageExceptions.NULL_SOURCE
This exception is raised when the value of the ORDImage.source attribute is NULL.
See Appendix G for more information about this exception.
Examples
Check the image attributes:
DECLARE image ORDSYS.ORDImage; properties_match BOOLEAN; BEGIN SELECT p.product_photo INTO image FROM pm.online_media p WHERE p.product_id = 3515; -- check that properties match the image properties_match := image.checkProperties(); IF properties_match THEN DBMS_OUTPUT.PUT_LINE('Check Properties succeeded'); ELSE DBMS_OUTPUT.PUT_LINE('Check Properties failed'); END IF; COMMIT; END; /
Format
copy(dest IN OUT ORDImage);
Description
Copies an image without changing it.
Parameters
The destination of the new image.
Usage Notes
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 time stamp information.
Pragmas
None.
Exceptions
ORDImageExceptions.NULL_SOURCE
This exception is raised when the value of the ORDImage.source attribute is NULL.
See Appendix G for more information about this exception.
Examples
Create a copy of an image:
DECLARE image_1 ORDSYS.ORDImage; image_2 ORDSYS.ORDImage; BEGIN -- Initialize a new ORDImage object where the copy will be stored: INSERT INTO pm.online_media (product_id, product_photo) VALUES (3091, ORDSYS.ORDImage.init()); -- Select the source object into image_1: SELECT product_photo INTO image_1 FROM pm.online_media WHERE product_id = 3515; -- Select the target object into image_2: SELECT product_photo INTO image_2 FROM pm.online_media WHERE product_id = 3091 FOR UPDATE; -- Copy the data from image_1 to image_2: image_1.copy(image_2); UPDATE pm.online_media SET product_photo = image_2 WHERE product_id = 3091; COMMIT; END; /
Format
getCompressionFormat( ) RETURN VARCHAR2;
Description
Returns the value of the compressionFormat attribute of the image object.
Parameters
None.
Usage Notes
Use this method rather than accessing the compressionFormat attribute directly to protect yourself from potential changes to the internal representation of the ORDImage object.
Pragmas
PRAGMA RESTRICT_REFERENCES(getCompressionFormat, WNDS, WNPS, RNDS, RNPS)
Exceptions
None.
Examples
Get the compression type of an image:
DECLARE image ORDSYS.ORDImage; compression_format VARCHAR2(4000); BEGIN SELECT p.product_photo INTO image FROM pm.online_media p WHERE p.product_id = 3515; -- Get the image compression format: compression_format := image.getCompressionFormat(); DBMS_OUTPUT.PUT_LINE('Compression format is ' || compression_format); COMMIT; END; /
Format
getContentFormat( ) RETURN VARCHAR2;
Description
Returns the value of the contentFormat attribute of the image object.
Parameters
None.
Usage Notes
Use this method rather than accessing the contentFormat attribute directly to protect yourself from potential changes to the internal representation of the ORDImage object.
Pragmas
PRAGMA RESTRICT_REFERENCES(getContentFormat, WNDS, WNPS, RNDS, RNPS)
Exceptions
None.
Examples
Get the content type of an image:
DECLARE image ORDSYS.ORDImage; content_format VARCHAR2(4000); BEGIN SELECT p.product_photo INTO image FROM pm.online_media p WHERE p.product_id = 3515; -- Get the image content format: content_format := image.getContentFormat(); DBMS_OUTPUT.PUT_LINE('Content format is ' || content_format); COMMIT; END; /
Format
getContentLength( ) RETURN INTEGER;
Description
Returns the value of the contentLength attribute of the image object.
Parameters
None.
Usage Notes
Use this method rather than accessing the contentLength attribute directly to protect from potential future changes to the internal representation of the ORDImage object.
Pragmas
PRAGMA RESTRICT_REFERENCES(getContentLength, WNDS, WNPS, RNDS, RNPS)
Exceptions
None.
Examples
Get the content length of an image:
DECLARE image ORDSYS.ORDImage; content_length INTEGER; BEGIN SELECT p.product_photo INTO image FROM pm.online_media p WHERE p.product_id = 3515; -- Get the image size: content_length := image.getContentLength(); DBMS_OUTPUT.PUT_LINE('Content length is ' || content_length); COMMIT; END; /
Format
getDicomMetadata(optionString IN VARCHAR2) RETURN XMLType ;
Description
Returns an XML representation of the metadata extracted from the DICOM image stored in the ORDImage object. See Appendix F for information about the XML schema for DICOM.
Parameters
A string that specifies the type of DICOM metadata to extract. For this release, the only valid value is imageGeneral
. All other values are ignored.
Usage Notes
The DICOM standard defines many sets of rules for encoding a DICOM object in a binary stream. See Appendix I for information about the DICOM encoding rules supported by interMedia.
See Oracle interMedia User's Guide for more information about the DICOM feature.
Pragmas
None.
Exceptions
ORDImageExceptions.NULL_LOCAL_DATA
This exception is raised when source.localData is NULL.
ORDImageExceptions.NULL_SOURCE
This exception is raised when the value of the ORDImage.source attribute is NULL.
See Appendix G for more information about these exceptions.
Examples
DECLARE local_image ORDSYS.ORDIMAGE; local_id INTEGER; dicom_metadata XMLType := NULL; BEGIN SELECT image INTO local_image FROM medicalImages WHERE id = 1; dicom_metadata := local_image.getDicomMetadata('imageGeneral'); IF (dicom_metadata is NULL) THEN DBMS_OUTPUT.PUT_LINE('dicom metadata is NULL'); END IF; -- print the value of the one of the elements in extracted -- dicom metadata DBMS_OUTPUT.PUT_LINE('namespace: ' || dicom_metadata.getNamespace() ); EXCEPTION WHEN ORDSYS.ORDImageExceptions.NULL_LOCAL_DATA THEN DBMS_OUTPUT.PUT_LINE('source local data is null '); WHEN ORDSYS.ORDImageExceptions.NULL_SOURCE THEN DBMS_OUTPUT.PUT_LINE('source is null '); WHEN OTHERS THEN RAISE; END;/
Format
getFileFormat( ) RETURN VARCHAR2;
Description
Returns the value of the fileFormat attribute of the image object.
Parameters
None.
Usage Notes
Use this method rather than accessing the fileFormat attribute directly to protect yourself from potential changes to the internal representation of the ORDImage object.
Pragmas
PRAGMA RESTRICT_REFERENCES(getFileFormat, WNDS, WNPS, RNDS, RNPS)
Exceptions
None.
Examples
Get the file type of an image:
DECLARE image ORDSYS.ORDImage; file_format VARCHAR2(4000); BEGIN SELECT p.product_photo INTO image FROM pm.online_media p WHERE p.product_id = 3515; -- Get the image file format: file_format := Image.getFileFormat(); DBMS_OUTPUT.PUT_LINE('File format is ' || file_format); COMMIT; END; /
Format
getHeight( ) RETURN INTEGER;
Description
Returns the value of the height attribute of the image object.
Parameters
None.
Usage Notes
Use this method rather than accessing the height attribute directly to protect yourself from potential changes to the internal representation of the ORDImage object.
Pragmas
PRAGMA RESTRICT_REFERENCES(getHeight, WNDS, WNPS, RNDS, RNPS)
Exceptions
None.
Examples
Get the height of an image:
DECLARE image ORDSYS.ORDImage; height INTEGER; BEGIN SELECT p.product_photo INTO image FROM pm.online_media p WHERE p.product_id = 3515; -- Get the image height: height := image.getHeight(); DBMS_OUTPUT.PUT_LINE('Height is ' || height); COMMIT; END; /
Format
getMetadata(metadataType IN VARCHAR2 DEFAULT 'ALL' ) RETURN XMLSequenceType ;
Description
Extracts the specified types of metadata from the image and returns an array of schema valid XML documents. If no matching metadata is found, an empty array is returned.
Parameters
A string that specifies the types of embedded metadata to extract. Valid values are ALL, ORDIMAGE, XMP, EXIF, and IPTC-IIM. The default value is ALL.
Usage Notes
When the value of the input parameter metadataType is ALL, and more than one type of supported metadata is present in the image, this method returns several XML documents, one for each type of metadata found. For other values of the input parameter, the method returns zero or one XML document.
Each document is stored as an instance of XMLType, and is based on one of the metadata schemas. The method XMLType.getNamespace( ) can be used to determine the type of metadata represented in that document.
See Appendix F for a description of the supported metadata schemas.
See Oracle interMedia User's Guide for more information about the Metadata feature.
Pragmas
None.
Exceptions
ORDImageExceptions.NULL_LOCAL_DATA
This exception is raised when source.localData is NULL.
ORDImageExceptions.NULL_SOURCE
This exception is raised when the value of the ORDImage.source attribute is NULL.
See Appendix G for more information about these exceptions.
Examples
DECLARE image ORDSYS.ORDImage; metav XMLSequenceType; BEGIN SELECT product_photo INTO image FROM pm.online_media WHERE product_id = 3106; metav := image.getMetadata('ALL'); -- print the namespace of each metadata document FOR i in 1..metav.count LOOP DBMS_OUTPUT.PUT_LINE('namespace: ' || metav(i).getNamespace() ); END LOOP; EXCEPTION WHEN ORDSYS.ORDImageExceptions.NULL_LOCAL_DATA THEN DBMS_OUTPUT.PUT_LINE('source local data is null'); WHEN ORDSYS.ORDImageExceptions.NULL_SOURCE THEN DBMS_OUTPUT.PUT_LINE('source is null'); WHEN OTHERS THEN RAISE; END; /
Format
getWidth( ) RETURN INTEGER;
Description
Returns the value of the width attribute of the image object
Parameters
None.
Usage Notes
Use this method rather than accessing the width attribute directly to protect yourself from potential changes to the internal representation of the ORDImage object.
Pragmas
PRAGMA RESTRICT_REFERENCES(getWidth, WNDS, WNPS, RNDS, RNPS)
Exceptions
None.
Examples
Get the width of an image:
DECLARE image ORDSYS.ORDImage; width INTEGER; BEGIN SELECT p.product_photo INTO image FROM pm.online_media p WHERE p.product_id = 3515; -- Get the image width: width := image.getWidth(); DBMS_OUTPUT.PUT_LINE('Width is ' || width); COMMIT; END; /
Format
import(ctx IN OUT RAW);
Description
Transfers image data from an external image data source to the localData attribute (of the embedded ORDSource object) within the database.
Parameters
The source plug-in context information. This should be allocated and initialized to NULL. If you are using a user-defined source plug-in, you should call the openSource( ) method. See the introduction to this chapter for more information.
Usage Notes
Use the setSource( ) method to set the source.srcType, source.srcLocation, and source.srcName attributes (of the embedded ORDSource object) for the external image data source prior to calling the import( ) method.
You must ensure that the directory exists or is created before you use this method for a source.srcType attribute with a value of "file".
After importing data from an external image data source to a local source (within 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.
This method is invoked at the ORDSource level, which uses the PL/SQL UTL_HTTP package to import media data from an HTTP data source. You can use environment variables to specify the proxy behavior of the UTL_HTTP package. For example, on UNIX, setting the environment variable http_proxy to a URL specifies that the UTL_HTTP package will use that URL as the proxy server for HTTP requests. Setting the no_proxy environment variable to a domain name specifies that the HTTP proxy server will not be used for URLs in the specified domain.
See Oracle Database PL/SQL Packages and Types Reference for more information about the UTL_HTTP PL/SQL package.
Pragmas
None.
Exceptions
ORDImageExceptions.NULL_SOURCE
This exception is raised when the value of the ORDImage.source attribute is NULL.
ORDSourceExceptions.INCOMPLETE_SOURCE_INFORMATION
This exception is raised if you call the import( ) method and the value of the source.srcType attribute is NULL.
ORDSourceExceptions.METHOD_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 G for more information about these exceptions.
Examples
Import image data from an external image data source into the local source:
DECLARE obj ORDSYS.ORDImage; ctx RAW(64) :=NULL; BEGIN SELECT p.product_photo INTO obj FROM pm.online_media p WHERE p.product_id = 3515 FOR UPDATE; DBMS_OUTPUT.PUT_LINE('getting source'); DBMS_OUTPUT.PUT_LINE('--------------------------'); -- Get source information DBMS_OUTPUT.PUT_LINE(obj.getSource()); -- Import data obj.import(ctx); -- Check size DBMS_OUTPUT.PUT_LINE('Length is ' || obj.getContentLength); UPDATE pm.online_media p SET p.product_photo = obj WHERE p.product_id = 3515; COMMIT; END; /
Format
importFrom(ctx IN OUT RAW,
source_type IN VARCHAR2,
source_location IN VARCHAR2,
source_name IN VARCHAR2);
Description
Transfers image data from the specified external image data source to the source.localData attribute (of the embedded ORDSource object) within the database.
Parameters
The source plug-in context information. This should be allocated and initialized to NULL. If you are using a user-defined source plug-in, you should call the openSource( ) method. See the introduction to this chapter for more information.
The type of the source image data.
The location from which the source image data is to be imported.
The name of the source image data.
Usage Notes
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 with a source_type parameter value of "file".
After importing data from an external image data source to a local source (within 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( ) for foreign images method does this for you.
This method is invoked at the ORDSource level, which uses the PL/SQL UTL_HTTP package to import media data from an HTTP data source. You can use environment variables to specify the proxy behavior of the UTL_HTTP package. For example, on UNIX, setting the environment variable http_proxy to a URL specifies that the UTL_HTTP package will use that URL as the proxy server for HTTP requests. Setting the no_proxy environment variable to a domain name specifies that the HTTP proxy server will not be used for URLs in the specified domain.
See Oracle Database PL/SQL Packages and Types Reference for more information about the UTL_HTTP PL/SQL package.
Pragmas
None.
Exceptions
ORDImageExceptions.NULL_SOURCE
This exception is raised when the value of the ORDImage.source attribute 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.
See Appendix G for more information about these exceptions.
Examples
Import image data from the specified external data source into the local source:
DECLARE obj ORDSYS.ORDImage; ctx RAW(64) :=NULL; BEGIN SELECT p.product_photo INTO obj FROM pm.online_media p WHERE p.product_id = 3501 FOR UPDATE; -- set source to a file -- import data obj.importFrom(ctx,'file','FILE_DIR','speaker.jpg'); -- check size DBMS_OUTPUT.PUT_LINE('Length is ' || obj.getContentLength); DBMS_OUTPUT.PUT_LINE('Source is ' || obj.getSource()); UPDATE pm.online_media p SET p.product_photo = obj WHERE p.product_id = 3501; COMMIT; END; /
Format
process(command IN VARCHAR2);
Description
Performs one or more image processing operations on a BLOB, writing the image back onto itself.
Parameters
A list of image processing operations to perform on the image.
Usage Notes
There is no implicit import( ) or importFrom( ) call performed when you call this method; if data is external, you must first call the import( ) or importFrom( ) method 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 about process( ) method operators.
You can change one or more of the image attributes shown in Table 5-1. Table 5-2 shows additional changes that can be made only to raw pixel and foreign images.
Table 5-1 Image Processing Operators
Operator Name | Usage | Values |
---|---|---|
compressionFormat | Forces output to the specified compression format if it is supported by the output file format. | JPEG, SUNRLE, BMPRLE, TARGARLE, LZW, LZWHDIFF, FAX3, FAX4, HUFFMAN3, PACKBITS, GIFLZW, ASCII, RAW, DEFLATE, NONE |
compressionQuality | Determines the quality of lossy compression; for use with JPEG only. | MAXCOMPRATIO, MAXINTEGRITY, LOWCOMP, MEDCOMP, HIGHCOMP, or an integer value between 0 and 100. |
contentFormat | Determines the format of the image content. | See Section D.2.2 in Appendix D for values. |
contrast | Adjusts image contrast. See Section D.3.1 in Appendix D for more information.Foot 1 | nonnegative FLOATFoot 2 , nonnegative FLOAT FLOAT FLOATFoot 3 , nonnegative FLOAT FLOATFoot 4 , nonnegative FLOAT FLOAT FLOAT FLOAT FLOAT FLOATFoot 5 |
cut | Defines a 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. | nonnegative INTEGER INTEGER INTEGER INTEGER maximum value is 2147483648 |
fileFormat | Forces the output to specified file format. | BMPF, CALS, GIFF, JFIF, PBMF, PGMF, PICT, PNGF, PNMF, PPMF, RASF, RPIX, TGAF, TIFF, WBMP |
fixedScale | Scales an image to a specified size in pixels (width, height); may not be combined with other scale operators. | positive INTEGER INTEGER |
flip | Places the scanlines of an image in inverse order -- swapped top to bottom. | No arguments |
gamma | Adjusts gamma (brightness) of an image. See Section D.3.4 in Appendix D for more information.Foot 6 | positive FLOATFoot 7 positive FLOAT FLOAT FLOATFoot 8 |
maxScale | Scales an image to a specified size in pixels (width, height), while maintaining the aspect ratio; may not be combined with other scale operators. | positive INTEGER INTEGER |
mirror | Places columns of an image in reverse order -- swapped left to right. | No arguments |
page | Selects a page from a multipage file; for use with TIFF only; first page is 0 (zero). | nonnegative INTEGER |
quantize | Specifies how image quantization is to be performed when reducing image bit depth. See Section D.3.7 in Appendix D for more information. | ERRORDIFFUSION (default), ORDEREDDITHER, THRESHOLD, MEDIANCUT |
rotate | Rotates an image within the image plane by the angle specified. See Section D.3.8 in Appendix D for more information.Foot 9 | FLOAT |
scale | Uniformly scales an image by a given factor (for example, 0.5 or 2.0); may not be combined with other scale operators.Foot 10 | positive FLOAT |
tiled | Forces output image to be tiled; for use with TIFF only. | No arguments |
xScale | Scales an image on the X-axis by a given factor (default is 1); image is non-uniformly scaled; may be combined only with the yScale operator; may not be combined with any other scale operators.Foot 11 | positive FLOAT |
yScale | Scales the image on theY-axis scale by a given factor (default is 1); non-uniformly scales image; may only be combined with the xScale operator; may not be combined with any other scale operators.Foot 12 | positive FLOAT |
Note:
To ensure that floating-point values are interpreted according to the NLS_TERRITORY setting for the session, surround the value with double quotation marks (""
). For example, use 'scale="0.7"'
in the AMERICAN territory, and 'scale="0,7"'
in the FRENCH territory.Table 5-2 Additional Image Processing Operators for Raw Pixel and Foreign Images
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, specifies either one (grayscale) or three integers indicating which channels to assign to red (first), green (second), and blue (third). Note that this operator affects the source image, not the destination; RPIX only. | positive INTEGER,Foot 1 positive INTEGER INTEGER INTEGERFoot 2 |
pixelOrder | Forces pixel direction. If NORMAL, then the leftmost pixel appears first in the image. RPIX only. | NORMAL (default), REVERSE |
scanlineOrder | Forces scanline direction. If NORMAL, then the top scanline appears first in the image. RPIX and BMPF only. | NORMAL (default), INVERSE |
Pragmas
None.
Exceptions
ORDImageExceptions.DATA_NOT_LOCAL
This exception is raised if you call the process( ) method and the data is not local (the source.local attribute is 0).
ORDImageExceptions.NULL_SOURCE
This exception is raised when the value of the ORDImage.source attribute is NULL.
See Appendix G for more information about these exceptions.
Examples
Example 1: Change the file format of image1 to GIFF:
DECLARE obj ORDSYS.ORDImage; BEGIN SELECT product_photo INTO obj FROM pm.online_media WHERE product_id = 3515 FOR UPDATE; obj.process('fileFormat=GIFF'); -- Update UPDATE pm.online_media SET product_photo = obj WHERE product_id = 3515; -- Roll back to keep original format of image: ROLLBACK; EXCEPTION WHEN ORDSYS.ORDImageExceptions.DATA_NOT_LOCAL THEN DBMS_OUTPUT.PUT_LINE('Data is not local'); END; /
Example 2: Change image1 to use a compression format of JPEG with MAXCOMPRATIO and double the length of the image along the X-axis:
DECLARE obj ORDSYS.ORDImage; BEGIN SELECT product_photo INTO obj FROM pm.online_media WHERE product_id = 3515 FOR UPDATE; obj.process( 'compressionFormat=JPEG,compressionQuality=MAXCOMPRATIO, xScale="2.0"'); -- Update: UPDATE pm.online_media SET product_photo = obj WHERE product_id = 3515; -- Roll back to keep original format of image: ROLLBACK; EXCEPTION WHEN ORDSYS.ORDImageExceptions.DATA_NOT_LOCAL THEN DBMS_OUTPUT.PUT_LINE('Data is not local'); END; /
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 scale operation. Any other combinations of scale operators result in an error.
Example 3: Create a thumbnail image:
The maxScale and fixedScale operators are especially useful for creating thumbnail images from various-sized originals. The following example creates, at most, a 32-by-32 pixel thumbnail image, preserving the original aspect ratio:
DECLARE obj ORDSYS.ORDImage; BEGIN SELECT product_photo INTO obj FROM pm.online_media WHERE product_id = 3515 FOR UPDATE; obj.process('maxScale=32 32'); UPDATE pm.online_media p SET product_thumbnail = obj WHERE product_id = 3515; COMMIT; EXCEPTION WHEN ORDSYS.ORDImageExceptions.DATA_NOT_LOCAL THEN DBMS_OUTPUT.PUT_LINE('Data is not local'); END; /
Example 4: Change the format to TIFF and the content format to 8BIT, BIP pixel layout, LUT interpretation, and RGB color space:
DECLARE obj ORDSYS.ORDImage; BEGIN SELECT product_photo INTO obj FROM pm.online_media WHERE product_id = 3515 FOR UPDATE; obj.process('fileFormat=TIFF, contentFormat=8BITBIPLUTRGB'); UPDATE pm.online_media SET product_photo = obj WHERE product_id = 3515; -- Roll back to keep original format of image: ROLLBACK; EXCEPTION WHEN ORDSYS.ORDImageExceptions.DATA_NOT_LOCAL THEN DBMS_OUTPUT.PUT_LINE('Data is not local'); END; /
Format
processCopy(command IN VARCHAR2,
dest IN OUT ORDImage);
Description
Copies an image stored internally or externally to another image stored internally in the source.LocalData attribute (of the embedded ORDSource object) and performs one or more image processing operations on the copy.
Parameters
A list of image processing changes to make for the image in the new copy.
The destination of the new image.
Usage Notes
See Table 5-1, "Image Processing Operators" and Table 5-2, "Additional Image Processing Operators for Raw Pixel and Foreign Images".
You cannot specify the same ORDImage 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 applied on the destination image after the processCopy( ) method is called.
See Appendix D for more information about processCopy( ) operators.
Pragmas
None.
Exceptions
ORDImageExceptions.DATA_NOT_LOCAL
This exception is raised if you call the processCopy( ) method and the destination image source.local attribute value is 0 or the destination source.localData attribute is not initialized.
ORDImageExceptions.NULL_DESTINATION
This exception is raised if you call the processCopy( ) method and the destination image is NULL.
ORDImageExceptions.NULL_LOCAL_DATA
This exception is raised if you call the processCopy( ) method and the destination image source.localData attribute value is NULL. This exception is also raised if you call the processCopy( ) method and the source image source.local attribute value is 1 or NULL, and the source.localData attribute value is NULL.
ORDImageExceptions.NULL_SOURCE
This exception is raised when the value of the ORDImage.source attribute is NULL.
See Appendix G for more information about these exceptions.
Examples
Generate a thumbnail image from a source image:
DECLARE obj_1 ORDSYS.ORDImage; obj_2 ORDSYS.ORDImage; BEGIN SELECT product_photo, product_thumbnail INTO obj_1, obj_2 FROM pm.online_media WHERE product_id = 3515 FOR UPDATE; obj_1.processCopy('maxScale=32 32', obj_2); UPDATE pm.online_media SET product_thumbnail = obj_2 WHERE product_id=3515; COMMIT; EXCEPTION WHEN ORDSYS.ORDImageExceptions.NULL_DESTINATION THEN DBMS_OUTPUT.PUT_LINE('The destination is null'); WHEN ORDSYS.ORDImageExceptions.DATA_NOT_LOCAL THEN DBMS_OUTPUT.PUT_LINE('Data is not local'); WHEN ORDSYS.ORDImageExceptions.NULL_LOCAL_DATA THEN DBMS_OUTPUT.PUT_LINE('dest.source.localData attribute is null'); COMMIT; END; /
Format
putMetadata(xmlData IN NOCOPY XMLType, metadataType IN VARCHAR2 DEFAULT 'XMP' encoding IN VARCHAR2 DEFAULT 'UTF-8');
Description
Accepts a schema valid XML document and creates a binary packet suitable for embedding in the target image file format. The packet is encoded according to the value of the encoding parameter. If the value of the metadataType parameter is XMP, a new XMP packet is written to the image, replacing any existing XMP packets.
Parameters
The XMLType that contains a schema valid XML document for the indicated metadataType. If the value of the metadataType parameter is XMP, the root element should contain a well-formed RDF document.
A string that specifies the type of metadata to write. The valid value is XMP; it is also the default.
The character encoding to be used in the image file. Valid values are UTF-8, UTF-16, UTF-16BE, and UTF-16LE. The default is UTF-8.
Usage Notes
The binary metadata packet generated from the same xmlData input may have different sizes for different encodings. Different image file formats support different encodings, and may restrict the binary metadata packet size. The following are the restrictions of the supported image formats:
GIF89a supports UTF-8 encoding only.
JPEG requires a binary packet size of less than 65502 bytes.
TIFF requires a binary packet size of less than 4 gigabytes.
See Oracle interMedia User's Guide for more information about the Metadata feature.
Pragmas
None.
Exceptions
ORDImageExceptions.DATA_NOT_LOCAL
This exception is raised when the data is not local (the source.local attribute is 0.)
ORDImageExceptions.NULL_LOCAL_DATA
This exception is raised when source.localData is NULL.
ORDImageExceptions.NULL_SOURCE
This exception is raised when the value of the ORDImage.source attribute is NULL.
See Appendix G for more information about these exceptions.
Examples
DECLARE image ORDSYS.ORDImage; xmlData XMLType; BEGIN SELECT product_photo INTO image FROM pm.online_media WHERE product_id = 3106 FOR UPDATE; xmlData := xmltype( '<xmpMetadata xmlns="http://xmlns.oracle.com/ord/meta/xmp">' || '<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"' || ' xmlns:dc="http://purl.org/dc/elements/1.1/">' || '<dc:rights>' || ' <rdf:Alt>' || ' <rdf:li xml:lang="en-us">' || ' Oracle Corporation' || ' </rdf:li>' || ' </rdf:Alt>'|| '</dc:rights>' || '</rdf:RDF>' || '</xmpMetadata>', 'http://xmlns.oracle.com/ord/meta/xmp'); image.putMetadata(xmlData, 'xmp', 'utf-8'); UPDATE pm.online_media SET product_photo = image WHERE product_id=3106; COMMIT; EXCEPTION WHEN ORDSYS.ORDImageExceptions.DATA_NOT_LOCAL THEN DBMS_OUTPUT.PUT_LINE('Data is not local'); WHEN ORDSYS.ORDImageExceptions.NULL_LOCAL_DATA THEN DBMS_OUTPUT.PUT_LINE('source.localData attribute is null'); WHEN ORDSYS.ORDImageExceptions.NULL_SOURCE THEN DBMS_OUTPUT.PUT_LINE('source is null'); WHEN OTHERS THEN RAISE; END;/
Format
setProperties( );
Description
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 the source.localData attribute, 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( ) for foreign images method instead.
Parameters
None.
Usage Notes
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:
Height in pixels
Width in pixels
Data size of the image on disk, in bytes
File type (TIFF, JFIF, and so forth)
Image type (monochrome and so forth)
Compression type (JPEG, LZW, and so forth)
MIME type (generated based on file format)
Calling this method implicitly calls the setUpdateTime( ) and the setMimeType( ) methods.
Pragmas
None.
Exceptions
ORDImageExceptions.NULL_LOCAL_DATA
This exception is raised if you call the setProperties( ) method and the source.local attribute value is 1 or NULL and the source.localData attribute value is NULL.
ORDImageExceptions.NULL_SOURCE
This exception is raised when the value of the ORDImage.source attribute is NULL.
See Appendix G for more information about these exceptions.
Examples
Select the image, and then set the attributes using the setProperties( ) method:
DECLARE image ORDSYS.ORDImage; BEGIN SELECT p.product_photo INTO image FROM pm.online_media p WHERE p.product_id = 3515 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 pm.online_media p SET p.product_photo = image WHERE p.product_id = 3515; COMMIT; END; /
Format
setProperties(description IN VARCHAR2);
Description
Lets you write the characteristics of certain foreign images whose format is not natively understood by interMedia into the appropriate attribute fields.
Parameters
The image characteristics to set for the foreign image.
Usage Notes
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.See Appendix E for information about when to use foreign image support. Only some formats that are not natively understood can be described using this setProperties( ) method.
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 B, foreign images either do not contain information about 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 image characteristics for foreign images as described inTable 5-3.
Table 5-3 Image Characteristics for Foreign Files
Field | Data Type | Description |
---|---|---|
CompressionFormat | STRING | Specifies the compression format value. Valid values are: CCITTG3, CCITTG4, or NONE (default). |
DataOffset | INTEGER | Specifies an offset (from the beginning of the file to the start of the image data) that interMedia does not try to interpret. Set the offset to skip any potential header. The value must be a nonnegative integer less than the LOB length. Default is zero. |
DefaultChannelSelection | INTEGER or
INTEGER, INTEGER, INTEGER |
Specifies which bands in a multiband image will be interpreted as color channels when the image is read or processed. If a single integer is specified, the image will be treated as a grayscale image consisting of the data in the specified band only. If three integers are specified, the image will be treated as an RGB image, using the first specified band as the red channel, the second as the green channel, and the third as the blue channel. The first band in the image is numbered 1. The band specifications must be equal to or lower than the number of bands in the image.
For example:
|
Height | INTEGER | Specifies the height of the image in pixels. Value must be a positive integer. There is no default, thus a value must be specified. |
Interleaving | STRING | Specifies the band layout within the image. Valid styles are:
|
NumberOfBands | INTEGER | Specifies the number of color bands in the image with a value that is a positive integer less than 255. Default is 3. |
PixelOrder | STRING | Specifies a string to indicate the pixel order. If the string is NORMAL (default), the leftmost pixel appears first in the file. If the string is REVERSE, the rightmost pixel appears first. |
ScanlineOrder | STRING | Specifies a string to indicate the scanline order. If the string is NORMAL (default), the top scanline appears first in the file. If the string is INVERSE, then the bottom scanline appears first. |
UserString | STRING | Specifies a 4-character descriptive string. If used, the string is stored in the fileFormat attribute, appended to the user string " OTHER:". Default is blank and fileFormat is set to "OTHER". |
Width | INTEGER | Specifies the width of the image in pixels. Value must be a positive integer. There is no default, thus a value must be specified. |
MimeType | STRING | Specifies a MIME type, such as img/gif. |
The values supplied to the setProperties( ) for foreign images method are written to the existing ORDImage data attributes. The fileFormat attribute is set to OTHER and includes the user string, if supplied; for example, OTHER: LANDSAT.
Pragmas
None.
Exceptions
ORDImageExceptions.NULL_PROPERTIES_DESCRIPTION
This exception is raised if you call the setProperties( ) for foreign images method and the description parameter value is NULL.
See Appendix G for more information about this exception.
Examples
Select the foreign image and then set the properties for the image:
DECLARE obj ORDSYS.ORDImage; BEGIN SELECT p.product_photo INTO obj FROM pm.online_media p WHERE p.product_id = 3501 FOR UPDATE; -- Set property attributes for the image data: obj.setProperties('width=123 height=321 compressionFormat=NONE' || ' userString= LANDSTAT dataOffset=128' || ' scanlineOrder=INVERSE pixelOrder=REVERSE' || ' interleaving=BIL numberOfBands=1' || ' defaultChannelSelection=1'); UPDATE pm.online_media SET product_photo = obj WHERE product_id=3501; COMMIT; END; /
Oracle interMedia describes the ORDImageSignature object type, which supports content-based retrieval (image matching).
Note:
All interMedia features are available with the Standard Edition of Oracle Database except image indexing. The image indexing feature requires bit-mapped indexing, which is available only when you install the Enterprise Edition of Oracle Database.See the information about using an index to compare signatures in Oracle interMedia User's Guide for details on image indexing.
The examples in this chapter use the ONLINE_MEDIA table in the Product Media sample schema. See Oracle Database Sample Schemas for information about the sample schemas.
Note:
When you are storing or copying ORDImageSignature objects, you must first create an empty ORDImageSignature object in the table by using the ORDImageSignature.init( ) method.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:
signature: holds the signature of the stored image data.
This section describes the constructor function.
The interMedia constructor function is as follows:
Format
init( ) RETURN ORDImageSignature;
Description
Initializes instances of the ORDImageSignature object type.
Parameters
None.
Pragmas
None.
Exceptions
None.
Usage Notes
This constructor is a static method that initializes the ORDImageSignature signature attribute to empty_blob.
You must use the init( ) method to initialize ORDImageSignature objects that are stored in the database.
Examples
Initialize the ORDImageSignature object attribute:
BEGIN INSERT INTO pm.online_media (product_id, product_photo, product_photo_signature) VALUES (1910, ORDSYS.ORDImage.init('FILE', 'FILE_DIR','speaker.jpg'), ORDSYS.ORDImageSignature.init()); INSERT INTO pm.online_media (product_id, product_photo, product_photo_signature) VALUES (1940, ORDSYS.ORDImage.init('FILE', 'FILE_DIR','keyboard.jpg'), ORDSYS.ORDImageSignature.init()); INSERT INTO pm.online_media (product_id, product_photo, product_photo_signature) VALUES (2402, ORDSYS.ORDImage.init('FILE', 'FILE_DIR','speaker_02.jpg'), ORDSYS.ORDImageSignature.init()); COMMIT; END; /
This section presents reference information on the interMedia methods used for image data manipulation.
The following methods are presented in this section:
Format
evaluateScore(sig1 IN ORDImageSignature,
sig2 IN ORDImageSignature,
weights IN VARCHAR2)
RETURN FLOAT;
Description
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.
Parameters
A signature object.
A signature object.
A string consisting of matching attribute names followed by values between "0.0" and "1.0". The matching attributes refer to the weights assigned by the user to the different attributes that influence the kind of match. Attributes not specified by the user have a default value of "0.0".
The string can have all or some of the attributes. The value associated with an attribute specifies its relative importance in determining the distance between the signatures. An attribute with a value of "0.0" is not considered at all, while an attribute with a value of "1.0" is of the highest importance. The weights supplied are normalized prior to processing such that they add up to "1.0", maintaining the ratios that you supplied. At least one of the attributes must have a value greater than "0.0". The attributes are the following:
color: A value between "0.0" and "1.0" indicating the importance of the feature color.
texture: A value between "0.0" and "1.0" indicating the importance of the feature texture.
shape: A value between "0.0" and "1.0" indicating the importance of the feature shape.
location: A value between "0.0" and "1.0" indicating the importance of the location of the regions in the image. The location weight string cannot be specified alone, it must be used with another weight string.
Note:
To ensure that floating-point values are interpreted according to the NLS_TERRITORY setting for the session, surround the value with double quotation marks (""
). For example, use 'color="0.7"'
in the AMERICAN territory, and 'color="0,7"'
in the FRENCH territory.Return Value
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.
Usage Notes
The ORDImageSignature evaluateScore( ) method operates on two image signatures, not on indexes on database tables. Therefore, this method cannot take advantage of the increased performance that is possible using image matching with image signature indexes on the underlying tables. To use signature images, use the IMGSimilar and IMGScore SQL operators.
The ORDImageSignature objects must either be initialized, inserted into a table, and have a signature generated for them, or be created using a temporary LOB and have a signature generated for them, to successfully use the evaluateScore( ) method to compare the signatures.
Pragmas
None.
Exceptions
None.
Examples
Compare two signatures and evaluate the score between them:
DECLARE t_image ORDSYS.ORDImage; c_image ORDSYS.ORDImage; image_sig ORDSYS.ORDImageSignature; compare_sig ORDSYS.ORDImageSignature; score FLOAT; BEGIN SELECT p.product_photo, p.product_photo_signature INTO t_image, image_sig FROM pm.online_media p WHERE p.product_id = 1910 FOR UPDATE; -- Generate a signature: image_sig.generateSignature(t_image); UPDATE pm.online_media p SET p.product_photo_signature = image_sig WHERE product_id =1910; SELECT p.product_photo, p.product_photo_signature INTO c_image, compare_sig FROM pm.online_media p WHERE p.product_id = 1940 FOR UPDATE; -- Generate a signature: compare_sig.generateSignature(c_image); UPDATE pm.online_media p SET p.product_photo_signature = compare_sig WHERE product_id = 1940; SELECT p.product_photo, p.product_photo_signature INTO t_image, image_sig FROM pm.online_media p WHERE p.product_id = 1910; SELECT p.product_photo, p.product_photo_signature INTO c_image, compare_sig FROM pm.online_media p WHERE p.product_id = 1940; -- Compare two images for similarity based on image color: score:=ORDSYS.ORDImageSignature.evaluateScore(image_sig, compare_sig,'color="1.0",texture=0,shape=0,location=0'); DBMS_OUTPUT.PUT_LINE('Score is ' || score); END; /
Format
generateSignature (image IN ORDImage);
Description
Generates a signature for a given input image that is passed back as the signature object.
Parameters
The image object whose signature is to be generated.
Usage Notes
The ORDImageSignature object must either be initialized and inserted into a table or be created using a temporary LOB, to successfully generate a signature for the object.
The minimum image size for which the generateSignature( ) method can be called is 21x21 pixels. The generateSignature( ) method fails and returns the "IMG-00870, Unsupported aspect ratio or image size" error when called for smaller images.
Before using this method, use the setProperties( ) method to set the the properties of the input image.
Pragmas
None.
Exceptions
None.
Examples
Generate a signature for an image object stored in the database:
DECLARE t_image ORDSYS.ORDImage; image_sig ORDSYS.ORDImageSignature; BEGIN SELECT p.product_photo, p.product_photo_signature INTO t_image, image_sig FROM pm.online_media p WHERE p.product_id = 2402 FOR UPDATE; -- Generate a signature: image_sig.generateSignature(t_image); UPDATE pm.online_media p SET p.product_photo_signature = image_sig WHERE product_id = 2402; END; /
Format
isSimilar(sig1 IN ORDImageSignature,
sig2 IN ORDImageSignature,
weights IN VARCHAR2,
threshold IN FLOAT)
RETURN INTEGER;
Description
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.
Parameters
A signature object.
A signature object.
A string consisting of matching attribute names followed by values between "0.0" and "1.0". The matching attributes refer to the weights assigned by the user to the different attributes that influence the kind of match. Attributes not specified by the user have a default value of "0.0".
The string can have all or some of the attributes. The value associated with an attribute specifies its relative importance in determining the distance between the signatures. An attribute with a value of "0.0" is not considered at all, while an attribute with a value of "1.0" is of the highest importance. The weights supplied are normalized prior to processing such that they add up to "1.0", maintaining the ratios that you supplied. At least one of the attributes must have a value greater than "0.0". The attributes are the following:
color: A value between "0.0" and "1.0" indicating the importance of the feature color.
texture: A value between "0.0" and "1.0" indicating the importance of the feature texture.
shape: A value between "0.0" and "1.0" indicating the importance of the feature shape.
location: A value between "0.0" and "1.0" indicating the importance of the location of the regions in the image. The location weight string cannot be specified alone, it must be used with another weight string.
Note:
To ensure that floating-point values are interpreted according to the NLS_TERRITORY setting for the session, surround the value with double quotation marks (""
). For example, use 'color="0.7"'
in the AMERICAN territory, and 'color="0,7"'
in the FRENCH territory.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.
Usage Notes
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.
The ORDImageSignature isSimilar( ) method operates on two image signatures, not on indexes on database tables. Therefore, this method cannot take advantage of the increased performance that is possible using image matching with image signature indexes on the underlying tables. To use signature images, use the IMGSimilar and IMGScore SQL operators.
The ORDImageSignature objects must either be initialized, inserted into a table, and have a signature generated for them, or be created using a temporary LOB and have a signature generated for them, to successfully use the isSimilar( ) method to compare the signatures.
Pragmas
None.
Exceptions
None.
Examples
Compare two images based on color. Images are considered similar if a distance of 10 or less is returned:
DECLARE image_sig1 ORDSYS.ORDImageSignature; image_sig2 ORDSYS.ORDImageSignature; value INTEGER; BEGIN SELECT product_photo_signature INTO image_sig1 FROM pm.online_media WHERE product_id = 1910; SELECT product_photo_signature INTO image_sig2 FROM pm.online_media WHERE product_id = 1940; -- Compare the images: value := ORDSYS.ORDImageSignature.isSimilar(image_sig1, image_sig2,'color="1.0",texture=0,shape=0,location=0',10); IF value = 1 THEN DBMS_OUTPUT.PUT_LINE('The images are similar'); ELSIF value = 0 THEN DBMS_OUTPUT.PUT_LINE('The images are not similar'); END IF; 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.
Format
IMGSimilar (sig1 IN ORDSYS.ORDImageSignature,
sig2 IN ORDSYS.ORDImageSignature,
weights IN VARCHAR2,
threshold IN FLOAT
[ ,referencetoScore IN NUMBER] );
Description
Determines whether or not two images match. Specifically, the operator compares the signature of a query image with the signatures of images stored in a table, and determines whether or not the images match, based on the weights and threshold value. This operator returns 1 if the computed distance measure (weighted average) is less than or equal to the threshold value (indicating a match), and returns 0 when the distance between the two images is more than the threshold value.
Parameters
The signature of the image to which you are comparing the query image. The 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, the database uses the non-indexed implementation of query evaluation.
The signature of the query or test image. The data type is ORDImageSignature.
A string consisting of matching attribute names followed by values between "0.0" and "1.0". The matching attributes refer to the weights assigned by the user to the different attributes that influence the kind of match. Attributes not specified by the user have a default value of "0.0".
The string can have all or some of the attributes. The value associated with an attribute specifies its relative importance in determining the distance between the signatures. An attribute with a value of "0.0" is not considered at all, while an attribute with a value of "1.0" is of the highest importance. The weights supplied are normalized prior to processing such that they add up to "1.0", maintaining the ratios that you supplied. At least one of the attributes must have a value greater than "0.0". The attributes are the following:
color: A value between "0.0" and "1.0" indicating the importance of the feature color.
texture: A value between "0.0" and "1.0" indicating the importance of the feature texture.
shape: A value between "0.0" and "1.0" indicating the importance of the feature shape.
location: A value between "0.0" and "1.0" indicating the importance of the location of the regions in the image. The location weight string cannot be specified alone, it must be used with another weight string.
Note:
To ensure that floating-point values are interpreted according to the NLS_TERRITORY setting for the session, surround the value with double quotation marks (""
). For example, use 'color="0.7"'
in the AMERICAN territory, and 'color="0,7"'
in the FRENCH territory.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. The data type is NUMBER.
Return Value
Returns an integer value of 0 (not similar) or 1 (match).
Pragmas
None.
Exceptions
None.
Usage Notes
Before the IMGSimilar( ) operator can be used, the image signatures must be created with the generateSignature( ) method. Image signatures that have not been initialized will not be evaluated by the IMGSimilar( ) operator. Also, to use the domain index, the index of type ORDImageIndex must have already been created. See Oracle interMedia User's Guide for information about creating and using the index, and for additional performance tips.
The IMGSimilar( ) operator returns Boolean values to indicate if 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.
Use this operator to take advantage of the increased performance that is possible using image matching with image signature indexes of the underlying tables (as opposed to using the evaluateScore( ) and isSimilar( ) methods).
Examples
Find all images similar to the query image using a threshold value of 25 and the following weights for the visual attributes:
Color: "0.2"
Texture: "0.1"
Shape: "0.5"
Location: "0.2"
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.
DECLARE id NUMBER; image ORDSYS.ORDImage; query_signature ORDSYS.ORDImageSignature; CURSOR getphotos IS SELECT product_id, product_photo FROM pm.online_media WHERE ORDSYS.IMGSimilar(product_photo_signature, query_signature, 'color="0.2" texture="0.1" shape="0.5" location="0.2"', 25) = 1; BEGIN SELECT product_photo_signature INTO query_signature FROM pm.online_media WHERE product_id =1910; OPEN getphotos; LOOP FETCH getphotos INTO id, image; EXIT WHEN getphotos%NOTFOUND; DBMS_OUTPUT.PUT_LINE('Image with ID ' || id || ' matches query image.'); END LOOP; CLOSE getphotos; END; /
Compute the distance between a signature in a temporary LOB and signatures that are stored in the database:
DECLARE id NUMBER; image ORDSYS.ORDIMAGE; query_signature ORDSYS.ORDIMAGESIGNATURE; query_image ORDSYS.ORDIMAGE; CURSOR getphotos IS SELECT product_id, product_photo FROM pm.online_media WHERE ordsys.IMGsimilar(product_photo_signature, query_signature, 'color="0.2" texture="0.1" shape="0.5" location="0.2"', 25) = 1; BEGIN SELECT product_photo INTO query_image FROM pm.online_media WHERE product_id = 1910; -- Initialize signature object query_signature := ORDSYS.ORDIMAGESIGNATURE.init(); -- Create temporary storage for the LOB in the signature object DBMS_LOB.CREATETEMPORARY(query_signature.signature, TRUE); query_signature.generateSignature(query_image); OPEN getphotos; LOOP FETCH getphotos INTO id, image; EXIT WHEN getphotos%NOTFOUND; DBMS_OUTPUT.PUT_LINE('Image with ID ' || id || ' matches query image'); END LOOP; CLOSE getphotos; DBMS_LOB.FREETEMPORARY(query_signature.signature); END;/
Generate a signature for an image that is not stored in the database, store the signature in a temporary LOB, and compute the distance between this signature and the signatures that are stored in the database:
DECLARE id NUMBER; image ORDSYS.ORDIMAGE; query_signature ORDSYS.ORDIMAGESIGNATURE; query_image ORDSYS.ORDIMAGE; CURSOR getphotos IS SELECT product_id, product_photo FROM pm.online_media WHERE ORDSYS.IMGsimilar(product_photo_signature, query_signature, 'color="0.2" texture="0.1" shape="0.5" location="0.2"', 25) = 1; BEGIN -- Initialize and set the properties for the image object query_image := ORDSYS.ORDIMAGE.init('FILE','FILE_DIR','red.gif'); query_image.setproperties; -- Initialize the signature object query_signature := ORDSYS.ORDIMAGESIGNATURE.init(); -- Create temporary storage for the BLOB in the signature object DBMS_LOB.CREATETEMPORARY(query_signature.signature, TRUE); -- Generate a signature for the query image query_signature.generateSignature(query_image); OPEN getphotos; LOOP FETCH getphotos INTO id, image; EXIT WHEN getphotos%NOTFOUND; DBMS_OUTPUT.PUT_LINE('Image with ID ' || id || ' matches query image'); END LOOP; CLOSE getphotos; DBMS_LOB.FREETEMPORARY(query_signature.signature); END; /
Format
IMGScore (NUMBER);
Description
Compares the signatures of two images and returns a number representing the weighted sum of the distances for the visual attributes. The IMGScore( ) operator 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.
Parameters
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. The data type is NUMBER.
Return Value
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.
Pragmas
None.
Exceptions
None.
Usage Notes
Before the IMGScore( ) operator can be used, the image signatures must be created with the generateSignature( ) method. Image signatures that have not been initialized will not be evaluated by the IMGScore( ) operator. Also, if you want the comparison to use the domain index, the index of type ORDImageIndex must have already been created. See Oracle interMedia User's Guide for information about creating and using the index, and 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 the IMGSimilar( ) operator. For example, using the score returned by the IMGScore( ) operator, 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.
Use this operator to take advantage of the increased performance that is possible using image matching with image signature indexes of the underlying tables (as opposed to using the evaluateScore( ) and isSimilar( ) methods).
Examples
Find the weighted sum of the distances between a test image and the other images in the pm.online_media table, using a threshold of 20 and the following weights for the visual attributes:
Color: 0.2
Texture: 0.1
Shape: 0.5
Location: 0.2
This example assumes that the signatures were already created using the generateSignature( ) method. Notice that both IMGScore( ) and IMGSimilar( ) are using 123 as the reference number (referred to as the referenceToScore parameter for the IMGSimilar( ) operator) in this example.
DECLARE id NUMBER; img_score NUMBER; t_img ORDSYS.ORDImage; query_signature ORDSYS.ORDImageSignature; CURSOR getphotos IS SELECT product_id, ORDSYS.IMGScore(123), product_photo FROM pm.online_media WHERE ORDSYS.IMGSimilar(product_photo_signature, query_signature, 'color="0.2" texture="0.1" shape="0.5" location="0.2"', 20, 123) = 1; BEGIN SELECT product_photo_signature INTO query_signature FROM pm.online_media WHERE product_id = 1910; OPEN getphotos; LOOP FETCH getphotos INTO id, img_score, t_img; EXIT WHEN getphotos%NOTFOUND; DBMS_OUTPUT.PUT_LINE('Image with ID '|| id || ' matches query image with score ' || img_score ||'.'); END LOOP; CLOSE getphotos; END; /
The following shows possible results from this example. Image 1910 has a score of 0 because it is the query image; image 1940 is the best match to the query image (besides the query image itself) because it has the lowest score. Changing the weights used in the scoring might lead to different results.
Image with ID 1910 matches query image with score 0. Image with ID 1940 matches query image with score 10.2663. Image with ID 1743 matches query with with score 15.4666.
Demonstrate the use of reference numbers to refer to scores evaluated in different IMGSimilar( ) calls.
In this example, a query is searching for an image in the pm.online_media table that is similar in color to query_sig1, and similar in shape and location to query_sig2.
DECLARE id NUMBER; img_score1 NUMBER; img_score2 NUMBER; t_img ORDSYS.ORDImage; query_sig1 ORDSYS.ORDImageSignature; query_sig2 ORDSYS.ORDImageSignature; CURSOR getphotos IS SELECT product_id, ORDSYS.IMGScore(1), ORDSYS.IMGScore(2), product_photo FROM pm.online_media WHERE ORDSYS.IMGSimilar(product_photo_signature,query_sig1,'color="1.0"', 30, 1) = 1 AND ORDSYS.IMGSimilar(product_photo_signature, query_sig2,'shape="0.5" location="0.2"', 30, 2) = 1; BEGIN SELECT product_photo_signature INTO query_sig1 FROM pm.online_media WHERE product_id = 1910; SELECT product_photo_signature INTO query_sig2 FROM pm.online_media WHERE product_id = 1940; OPEN getphotos; LOOP FETCH getphotos INTO id, img_score1, img_score2, t_img; EXIT WHEN getphotos%NOTFOUND; DBMS_OUTPUT.PUT_LINE('Image with ID '|| id || ' matches the query images.'); END LOOP; CLOSE getphotos; END; /