================================= RELEASE NOTES FOR THE EXCALIBUR IMAGE DATABLADE MODULE 1.10.UC3 DATE: 05/27/98 ================================= TABLE OF CONTENTS I. OVERVIEW OF RELEASE NOTES II. INFORMIX DYNAMIC SERVER WITH UNIVERSAL DATA OPTION COMPATIBILITY III. CONFIGURATION IV. INSTALLATION V. REGISTRATION VI. UNREGISTERING A DATABLADE MODULE VII. FUNCTIONAL BEHAVIOR CHANGES VIII. EXAMPLE IMAGES IX. EXAMPLE FILES X. PERFORMANCE ENHANCEMENT NOTES XI. PERFORMANCE ENHANCEMENT TIPS FOR INDEXING XII. USAGE XIII. PRODUCT LIMITATIONS XIV. KNOWN PROBLEMS XV. FIXED PROBLEMS +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ I. OVERVIEW OF RELEASE NOTES ============================= The Excalibur Image DataBlade module comprises three individually installed components: Image Foundation (IFD), Features (FRS), and Image Processing (IPD). These release notes are for all three components. The purpose of these release notes is to make you aware of any special actions required to configure and use the Excalibur Image DataBlade module on your computer. This file also describes new functional behavior changes from earlier versions of this product and related Informix products, and how these changes affect current products. In addition, this file contains information about known bugs and their workarounds. This release notes document is not intended to be all-inclusive; it should be used as an addendum to the "Excalibur Image DataBlade Module User's Guide," which provides thorough information about product features and product behavior. These release notes are written for the following audience: o System administrators who install INFORMIX Dynamic Server with Universal Data Option o Database administrators who control access to INFORMIX Dynamic Server with Universal Data Option databases o Developers who write applications using the Excalibur Image DataBlade module II. INFORMIX DYNAMIC SERVER WITH UNIVERSAL DATA OPTION COMPATIBILITY ======================================================= Version 1.10.UC3 of the of the Excalibur Image DataBlade module has been verified on INFORMIX Dynamic Server with Universal Data Option Version 9.14.UC2. III. CONFIGURATION =================== To use the Image Processing and Features components of the Excalibur Image DataBlade module, you must use the onspaces utility to create an sbspace. If you use only the Image Foundation component to process or convert images stored in external files, configuring an sbspace is not necessary. An sbspace stores smart large object data. A default sbspace must be defined in the ONCONFIG configuration file. Any sbspace can be used for the default. To create an index, you must have a default sbspace, and you must store the index in an sbspace, preferably a different one from the default. See the server "Administrator's Guide" for information on creating an sbspace. IV. INSTALLATION ================= To use the Excalibur Image DataBlade module, you must install the Image Processing, Features, and Image Foundation components of the DataBlade module. See the "Read Me First" sheet packaged with your software for detailed installation instructions. Be sure to run the tar command on each of the Excalibur Image DataBlade module distribution file components. The tar command creates "datablade" directories for each component (IFD, IPD, FRS), into which it copies the product files. After you have run the tar command, move to the DataBlade module component directory and run the install script: cd ./install Once you have successfully installed each of the Excalibur Image DataBlade module components, you must register the Excalibur Image DataBlade module. V. REGISTRATION ================= To use the Excalibur Image DataBlade module, each DataBlade module component and the LOB Locator DataBlade module must be registered in the database in which they will be used. The Excalibur Image DataBlade module components and the LOB Locator DataBlade module (IPD, FRS, IFD, LLD) are registered using BladeManager's registration command. To successfully register each Excalibur Image DataBlade module component and the LOB Locator DataBlade module, you must register the Image Processing (IPD) component first as follows: >blademgr uds> register IPD.1.10.UC3 dbtest // where dbtest is your database BladeManager will prompt you to register each of the remaining products that depend on the Image Processing component. See the "BladeManager User's Guide" for complete instructions on how to register DataBlade modules. VI. UNREGISTERING A DATABLADE MODULE ====================================== You can unregister a DataBlade module that was previously installed only if there is no data in your database that uses the definitions defined by the DataBlade module. Unregistration is only available for modules installed with the BladeManager utility. Refer to the "BladeManager User's Guide" for information on the unregister command. VII. FUNCTIONAL BEHAVIOR CHANGES ================================= In the previous version, the ScaleImgBy, ScaleImgTo, ConvertImgFormat, and ConvertImgType UDRs update the source images files of the IFX_FILE type, which will destroy the original source. These UDRs now return new images as smart large objects, regardless of the source image data type (either IFX_FILE or IFX_BLOB). Also, rather than raise errors, the behavior for ImgWidth, ImgHeight, ImgFormat, ImgType UDRs has been changed to return NULL attribute values on invalid input IfdImgDesc image descriptors. VIII. EXAMPLE IMAGES ==================== This product includes the following example images in the $INFORMIXDIR/extend/%%%IFDVERSION%%%/examples directory: informix.tif lenncp.tif october.jpg You can use them to run the sql examples listed in the "Excalibur Image DataBlade Module User's Guide." To run the examples, you need to copy these sample images to the /tmp directory. IX. EXAMPLE FILES ================== This product also includes the following example files in the $INFORMIXDIR/extend/%%%IFDVERSION%%%/examples directory: o ifdexamples.sql -- examples of executing Image Foundation user- defined routines (UDRs) within SQL o ifdudr.c -- examples of executing the ReadToMem, WriteFromMem, WriteLocFromMem, and FreeImagePtr UDRs within a UDR An example image is provided with this release for use with the example files. X. PERFORMANCE ENHANCEMENT NOTES ===================================== When you create a feature vector on images of the IfdImgDesc row type, theIpdColorImageFE, IpdGestaltImageFE, and IpdTextureImageFE feature extractor functions perform image scaling and type conversion preprocessing that can affect performance. Details of this preprocessing as well as procedures for performance enhancement are described below. A. IMAGE SCALING PREPROCESSING ------------------------------- During feature extraction, the database server invokes the feature extractor functions and the parameters that you specify when you create an frnet index using the SQL CREATE INDEX statement. The feature extractor functions perform the following image processing prior to passing the feature vector to the frnet index: o If the pixel dimensions are not equal to those specified in the RETINA_HEIGHT and RETINA_WIDTH parameters, the image is scaled to the pixel dimensions specified in the RETINA_HEIGHT and RETINA_WIDTH parameters. o If the RETINA_HEIGHT and RETINA_WIDTH parameters are not specified, the image is scaled to the default RETINA_HEIGHT and RETINA_WIDTH parameters. See Chapter 3 of the "Excalibur Image DataBlade Module User's Guide," for more information about feature extractor functions and default parameter settings. B. TYPE CONVERSION PREPROCESSING --------------------------------- In addition to image preprocessing, the IpdGestaltImageFE feature extractor function performs the following image processing prior to passing the feature vector to the frnet index: o If an image type is specified in the RETINA_IMAGETYPE parameter (that is, GRAY or RGB), the image is converted to the specified image type. o If the RETINA_IMAGETYPE parameter is not specified, the image type is converted to the default image type (that is, GRAY). XI. PERFORMANCE ENHANCEMENT TIPS FOR INDEXING ============================================== This section contains tips for improving the performance of the Excalibur Image DataBlade module. A. USING SMALLER SIZE FOR FEATURE EXTRACTION ---------------------------------------------- Performing feature extraction from large images is slower than from smaller images. To improve performance on feature extraction, Informix recommends you use smaller RETINA_HEIGHT and RETINA_WIDTH parameters than the default settings. However, this can result in less accurate feature vectors. B. AVOIDING IMAGE SCALING AND TYPE CONVERSION DURING INDEXING -------------------------------------------------------------- To avoid scaling and converting your images during indexing, you may store store the image in the same size and type you specified in the RETINA_HEIGHT, RETINA_WIDTH, and RETINA IMAGETYPE parameters used in feature extractor functions. C. DISTRIBUTING SBSPACE I/O ----------------------------- During image indexing, the Excalibur Image DataBlade module temporarily stores feature vectors in the default sbspace. The frnet index function then reads the feature vectors from the default sbspace and inserts them into the frnet index table. To distribute sbspace I/O, Informix recommends that you: o store the smart large object table data in a sbspace on a separate disk. o reserve the default sbspace for the feature extractor function's temporary storage on a separate disk. o create the frnet index on a separate sbspace on a separate disk. D. CREATING INDEXES AFTER STORING IMAGES ------------------------------------------ To improve performance during indexing, Informix recommends that you insert your bulk image data first into an IfdImgDesc column and then create your frnet index. If you need to insert a large amount of data after you have created your frnet index, Informix recommends that you drop the frnet index, insert the new data, and then recreate the frnet index. XII. USAGE ========== This section describes issues you should be aware of as you use the Excalibur Image DataBlade Module. A. STORING IMAGES IN SMART LARGE OBJECTS ---------------------------------------- To ensure recoverability, you should store your images in smartblobs rather than leaving them on the file system. Here is an example of how to insert an image into an IfdImgDesc column using ifx_blob lo_protocol: CREATE TABLE imgtable (id serial, image_col ifdimgdesc); INSERT INTO imgtable VALUES 0, ROW(ROW(ROW('ifx_blob',FileToBlob('/images/example.gif', 'server'), NULL::lvarchar)::lld_locator, NULL::lvarchar)::ifdlocator, NULL::lvarchar, NULL::lvarchar, NULL::integer, NULL::integer, NULL::lvarchar)::ifdimgdesc); B. CALCULATING FEATURE VECTOR (Fv) SIZE --------------------------------------- To calculate the feature vector size of the gestalt, color and texture images, use the following formulas: o Gestalt: Fv size = 4*((w*h*k+31)/32) bytes where w = RETINA_WIDTH (in pixels) h = RETINA HEIGHT (in pixels) k = #bytes/pixel that is, the number of bytes in the feature vector is equal to the bytes of pixel data in input image (w*h*k in 32-bit alignment). o Color: Fv size = 4*((1404+31)/32) bytes = 180 bytes o Texture: Fv size = 4*((512+31)/32) = 68 bytes C. DETERMINING THE SIZE OF THE SBSPACE FOR STORING INDEXES ------------------------------------------------------------ To find the estimated sbspace size = size of (largest Fv of indexed set) * (# of objects in indexed set) + sum(aux. data & file storage overhead). You can check the actual usage of the sbspace with the onstat -d command. You see the difference between the estimated size and the actual usage, that is the sum(aux. data & file storage overhead). The reason is as follows. All Fv index objects are stored in one or more "block files" that occupy the most sbspace. Two additional entities are also stored in the sbspace: a control file and a series of association files. The control file is the central switch station of the index. It contains a version identifier, a corruption flag, the number of objects and features contained in the index, and so on. The association files map object IDs to index IDs and provide maps for the opposite direction (index IDs to object IDs) as well. D. ESTIMATING THE SIZE OF LOG SPACE FOR INDEX CREATION ------------------------------------------------------- To estimate the amount of log space needed for index creation: 1. Create an index on an empty table. 2. Use the onstat command to record the logging info into an output file (res.out): onstat -l > res.out 3. Insert rows into the table 4. Record the updated logging information again into the same output file: onstat -l >> res.out 5. Obtain the total log space used by comparing the before and after information recorded in the output file. To interpret the information from the onstat -l command, see server "Administrator's Guide" for detail. XIII. PRODUCT LIMITATIONS ========================== A. LOGGING SBSPACES -------------------- By default, sbspaces are not logged. You must log the sbspace where your indexes reside to avoid unrecoverable corruption. B. OBTAINING CORRECT VALUES OF IFDIMGDESC ATTRIBUTE COLUMNS --------------------------------------------------------- If you want to get safe (correct) values of the attribute columns (pixelwidth, pixelheight, imgtype, imgformat) from the IfdImgDesc row after insert/modify images in the table, you will need to call the server functions (ImgWidth, ImgHeight, ImgFormat, ImgType) explicitly to init or update those attribute columns. In other words, you should not trust the attribute values in IfdImgDesc rows unless the attributes were set or updated by explicitly calling those functions. C. CLUSTERING AND ALTERING FRAGMENT INDEXES ------------------------------------------- The current version does not allow you to create cluster indexes or alter existing fragment indexes. D. DBEXPORT/DBIMPORT --------------------- Due to a bug in the database server, you cannot export/import a database with DBEXPORT/DBIMPORT utilities that include an index based on the secondary access method frnet. You should not use the preceding utilities with databases that use the Excalibur Image DataBlade module. For more information on these database utilities, refer to the server "Administrator's Guide." XIV. KNOWN PROBLEMS ==================== PTS 71040: ANSI mode is not supported at this time by BladeManager. PTS 80466: Unable to create an index using the DataBlade-defined access method in a concurrent transaction. XV. FIXED PROBLEMS =================== The following problems have been fixed since Version 1.10.UC1: PTS 84705: ScaleImgTo() function does not preserve the aspect ratio when the same_aspect flag is set to TRUE. PTS 86829: ConvertImgFormat() function returns an empty string for lo_user field. PTS 89798: Under certain conditions if the name of the frnet indexes are very similar, attempts to drop an frnet index failed. PTS 90082: Altering a fragment index raises error saying "no access method predicate function." Informix does not allow altering fragment indexes at all. PTS 91790: Creating a clustered index returns "index created," but actually the clustered index is not created.