Copyright (c) Oracle Corporation 1997,1998, 1999, 2000. All Rights Reserved. NAME README.txt - ORACLE VISUAL INFORMATION RETRIEVAL RELEASE INFORMATION VERSION=8.1.7.0.0 README FILE ======================= Contents ======================= IMPORTANT - Changes Coming in the Next Version Important - Listener Must be Running Oracle Visual Information Retrieval Release 8.1.7 For More Information Oracle Technology Network Oracle Visual Information Retrieval Documentation Warnings Upgrade Notes Installing Oracle Visual Information Retrieval Running the Demos Downgrade Notes Deinstall Notes Dropping Visual Information Retrieval Types Using the Visual Information Retrieval Java Classes Important Information for Ensuring Future Compatibility Problems Fixed in This Release Features Added in This Release Known Problems in This Release Deprecated Features: 3rd Party Facial Recognition no Longer Supported ORDImgB and ORDImgF Object Types Will Be Dropped IMPORTANT - Changes Coming in the Next Version ============================================== Oracle plans to change the implementation of Visual Information Retrieval in the next version of Oracle. It is our intention that this image content based retrieval functionality will be layered on the new interMedia image functionality. In the next version, we plan to include a Visual Information Retrieval compatible API for the ORDVir object. This should require no application changes for applications that use the ORDVir object, methods and operators. However, it is expected that image signatures will have to be regenerated, and the image signature index will have to be recreated. As has always been the case in the past, it is possible that image comparison results may vary due to changes and improvements in the image comparison algorithms. Variations in image matching results are to be expected as image content based retrieval technology improves over time. IMPORTANT - Listener Must be Running ==================================== The listener must be running in order to use this option. See section 3.3 below. Oracle Visual Information Retrieval Release 8.1.7 ================================================= Provides for the storage, retrieval, processing, and content-based searching of two dimensional, static bit-mapped images. Provides support for building an index for content-based searching. Images are stored efficiently using popular compression schemes in industry standard desktop publishing image interchange formats. For More Information ======================================================================== VIR technology is licensed from Virage, Inc. For more information about Virage, see their websight at http://www.virage.com. Oracle Technology Network ========================= For the most recent information about Oracle8i interMedia and related products, and for free downloads of interMedia utilities and plugins, please go to the interMedia section of Oracle Technology Network: http://technet.oracle.com Follow the links to Products > Internet Servers > interMedia. Oracle Visual Information Retrieval Documentation =================================================== Complete online documentation is available with Oracle8i. Warnings: ======================= Visual Information Retrieval is installed under the database user ORDSYS. This user is created during installation and is subject to change in future beta or production releases. THE FUNCTIONS, PACKAGES AND TYPES SUPPLIED BY THIS PACKAGE AND ITS EXTERNAL INTERFACE ARE RESERVED BY ORACLE AND ARE SUBJECT TO CHANGE IN FUTURE RELEASES. THIS PACKAGE MUST NOT BE MODIFIED BY THE CUSTOMER. DOING SO COULD CAUSE INTERNAL ERRORS AND SECURITY VIOLATIONS IN THE DBMS. Upgrade Notes: ======================= This is Visual Information Retrieval release 8.1.7. There are upgrade scripts to help you upgrade from 8.0.x and 8.1.x to 8.1.7. Before following these instructions however, you have to upgrade to interMedia 8.1.7. For information on upgrading to interMedia 8.1.7 see /ord/im/admin/README.txt on UNIX, \ord\im\admin\README.TXT on Windows NT. When you are ready to upgrade to Visual Information Retrieval 8.1.7: 1) invoke virdbma to decide whether or not you need to upgrade. Start server manager (svrmgrl on UNIX and Windows NT) -> % svrmgrl Connect as SYSDBA -> SVRMGRL> connect / as SYSDBA -> SVRMGRL> @/ord/vir/admin/virdbma.sql (on UNIX) @\ord\vir\admin\virdbma.sql (on Windows NT) (where is the Oracle home directory) This script will output one of the following strings: NOT_INSTALLED - if no prior Visual Information Retrieval release was installed on your system. You can do an install rather than an upgrade. INSTALLED - if Visual Information Retrieval 8.1.7 is already installed u080xxx0.sql - the script for upgrade. xxx is the version of Visual Information Retrieval that you have currently installed. For example, u0800050.sql will upgrade from Visual Information Retrieval version 8.0.5.0.0. Note, virdbma cannot distinguish between 8.0 versions of Visual Information Retrieval. If you have an 8.0 version installed, the 8.0.5 script will always be chosen. 2) if an upgrade is required, perform the upgrade: Start server manager -> % svrmgrl Connect as ORDSYS -> SVRMGRL> @/ord/vir/admin/u080xxx0.sql (on UNIX) @\ord\vir\admin\u080xxx0.sql (on Windows NT) where u080xxx0.sql is the upgrade script output by step 1 if an upgrade is necessary. Installing Oracle Visual Information Retrieval ================================================ Prior to installing Oracle Visual Information Retrieval, you must first install Oracle8i Enterprise Edition and Oracle interMedia. If you installed Oracle Visual Information Retrieval during the same installation as Oracle8i Enterprise Edition, you do not have to perform the procedures in this section; Oracle Visual Information Retrieval was automatically configured for you. Oracle Visual Information Retrieval is an option of Oracle8i Enterprise Edition that provides image storage, retrieval, format conversion, and content based searching capabilities through an object data type (ODT). 1 Installation Decisions 2 Pre-Installation Steps 3 Installation Steps 1 Installation Decisions ------------------------ During the installation process you will create the ORDSYS user. This user ID is the standard Oracle database account with special privileges for options. Decision: Decide on a password for the ORDSYS user. The default password for the ORDSYS user during default installation is 'ORDSYS'. 2 Pre-Installation Steps ------------------------ Perform the following pre-installation tasks prior to installing Oracle Visual Information Retrieval. For instructions, please see the Installation Guide for your operating system: 2.1 Install the Oracle8i Enterprise Edition, including the PL/SQL option and the objects option. 2.2 Create the database. 2.3 Start up the database. 2.4 Install Oracle interMedia, Version 8.1.7.0.0 or later. 3 Installation Steps ------------------------ Perform the following mandatory installation steps. Remember, you only need to do this if you are manually installing Visual Information Retrieval. You do NOT need to do this if you use the Database Configuration Assistant. 3.1 Install the non-database components for the Visual Information Retrieval, using the Oracle Universal Installer. 3.2 Create Visual Information Retrieval. Start server manager (svrmgrl on UNIX and Windows NT) -> % svrmgrl Connect as SYSDBA -> SVRMGRL> connect / as SYSDBA Invoke virinst.sql -> SVRMGRL> @/ord/vir/admin/virinst.sql (on UNIX) @\ord\vir\admin\virinst.sql (on Windows NT) where is the ORACLE_HOME directory. 3.3 Start the Listener The listener must be configured to use external procedure calls. Check your tnsnames.ora file for an entry called extproc_connection_data and in the listener.ora file for an entry called extproc. See your network documentation for details. If this is not done properly, Visual Information Retrieval will NOT work. Once this has been completed, Oracle Visual Information Retrieval is usable. ======================= Running the Demos ================= Once you have installed Oracle Visual Information Retrieval, you may choose to run the Oracle Visual Information Retrieval demos. For information on running the OCI demo, see the following: /ord/vir/demo/README.txt (on UNIX), and \ord\vir\demo\README.txt (on Windows NT), where is the ORACLE_HOME directory. See the following for information on running the Java demo: /ord/vir/demo/java/README.txt (on UNIX), and \ord\vir\demo\java\README.txt (on Windows NT), where is the ORACLE_HOME directory. Downgrade Notes =============== In order to prepare for the downgrade of Oracle Visual Information Retrieval, perform the following steps: 1) start server manager (svrmgrl on UNIX and Windows NT) 2) Invoke the appropriate script. on UNIX: -> SVRMGRL> @/ord/vir/admin/d080xxx0.sql on Windows NT: SVRMGRL> @\ord\vir\admin\d080xxx0.sql where xxx is the version of Visual Information Retrieval you wish to downgrade to. For example, d0800050.sql will prepare for a downgrade to Oracle Visual Information Retrieval 8.0.5. Note - this script will prompt for passwords for ORDSYS. Deinstall Notes =============== The following steps will render Oracle Visual Information Retrieval inactive: 1) start server manager (svrmgrl on UNIX and Windows NT) 2) Invoke the script virdins.sql on UNIX: -> SVRMGRL> @/ord/vir/admin/virdins.sql on Windows NT: SVRMGRL> @\ord\vir\admin\virdins.sql Note - this script will prompt for passwords for ORDSYS. Dropping Visual Information Retrieval Types =========================================== After you have deinstalled Visual Information Retrieval and dropped all tables and types which depend on Visual Information Retrieval objects, you can drop the Visual Information Retrieval types by invoking the following script from server manager: on UNIX: -> SVRMGRL> @/ord/vir/admin/virdtyp.sql on Windows NT: SVRMGRL> @\ord\vir\admin\virdtyp.sql Using the Visual Information Retrieval Java Classes =================================================== In 8.1.7 we introduce new Visual Information Retrieval Java Classes. See "Features Added in This Release" for more information on these new classes. To use the 8.1.7 Visual Information Retrieval Java Classes, your Java environment must be correct and set up to compile and run Java programs. In addition, the following setup is required. The environment variable CLASSPATH must contain the jdk classes, the interMedia Java library, the Visual Information Retrieval Java library, and the JDBC and SQLJ runtime libraries. The libraries are located as follows (note, the location of the jdk classes is version and installation dependent and not mentioned here): Unix: /jdbc/lib/classes111.zip or classes12.zip /ord/jlib/ordim817.zip /ord/jlib/ordvir817.zip /sqlj/lib/runtime.zip Windows NT: \jdbc\lib\classes111.zip or classes12.zip \ord\jlib\ordim817.zip \ord\jlib\ordvir817.zip \sqlj\lib/runtime.zip The location of the JDBC OCI shared library must be specified in LD_LIBRARY_PATH (for UNIX) or PATH (for Windows NT). Note that this library may already be specified since the same shared library location must be specified to use other client applications such as SQL*Plus. Unix: /lib (for libocijdbc8.so) Windows NT: \bin (for ocijdbc8.dll) The 8.1.5 Visual Information Retrieval Java library is still shipped. If you do not wish to use the new Visual Information Retrieval Java Classes, the 8.1.5 Java Classes can still be used. To use the 8.1.5 Visual Information Retrieval Java Classes, ensure the setup described above with the exception of ordim817.zip and ordvir817.zip in CLASSPATH. Instead, confirm that CLASSPATH includes ordim.zip (the interMedia 8.1.5 library) and ordvir.zip (the Visual Information Retrieval 8.1.5 library). Important Information for Ensuring Future Compatibility ========================================================= IMPORTANT - We may evolve the Visual Information Retrieval object type (ORDVir) by adding new object attributes in a future release of Visual Information Retrieval. Client-side applications that wish to maintain compatibility to the "8.1.7" version of the ORDVir object type even after a server upgrade which evolves the object types are advised to do the following: - Make a call to the compatibility initialization function at the beginning of the application if necessary (see below). - Do not use default constructors since insert statements using the default constructor may fail if the ORDVir object type has evolved to add new attributes. Instead, the application can use the new static constructor function provided in 8.1.7. See the "Features Added in This Release" section below for details. When and How to Call the Compatibility Initialization Function -------------------------------------------------------------- NOTE : - Only client-side applications that statically understand the structure of the ORDVir object type need to make a call to the compatibility initialization function. Server-side stored procedures will automatically use the newly installed (and potentially evolved) ORDVir object type after an upgrade so do not need to call the compatibility initialization function. Client-side applications that do not statically (at compile time) understand the structure of the ORDVir object type do not need to call the compatibility initialization function. OCI applications that determine the structure of the ORDVir object type at runtime via the OCIDescribeAny call do not need to call the compatibility initialization function. Client-side applications written in OCI that have been compiled with the C structure of the ORDVir object type (generated by OTT) should make a call to the server-side PL/SQL function, ORDSYS.VIR.compatibilityInit, at the beginning of the application. FUNCTION compatibilityInit(release IN VARCHAR2, errmsg OUT VARCHAR2) return NUMBER; This PL/SQL function takes a string input parameter representing the version of Oracle Visual Information Retrieval being used by your application. This string should be set to '8.1.7' to allow your 8.1.7 application to work (without upgrading) with a potential future version of Oracle with an evolved ORDVir object type. The second parameter is a string output parameter. If the function returns a status other than 0, this errmsg string will contain the reason for the failure. Client-side applications written in Java using the Visual Information Retrieval Java Classes for 8.1.7 should call the OrdMediaUtil.virCompatibilityInit function after connecting to Oracle. public static void virCompatibilityInit(OracleConnection con) throws Exception This Java function takes an OracleConnection as argument. The included Visual Information Retrieval 8.1.7 Java Classes will ensure that your 8.1.7 application will work (without upgrading) with a potential future version of Visual Information Retrieval with an evolved object type. There is not yet a way for client-side PL/SQL applications to maintain compatibility to the 8.1.7 version of the ORDVir object if the object is evolved to add new attributes in a future release. Please see the "Oracle8i Visual Information Retrieval User's Guide and Reference Release 8.1.7" and the "Oracle8i Visual Information Retrieval Java Client User's Guide and Reference, Release 8.1.7" for further information along with detailed descriptions and examples. Both will be available on the Oracle Technology Network. Problems Fixed in This Release ============================== 1) The export() method now works for srcType 'FILE'. The semantics for export() are as such: o export() is similar to a file copy operation. That is, the original data stored in the BLOB is not touched other than for reading purposes. o export() is not an exact mirror operation to import() in that clearLocal() is not called automatically by export() whereas import() calls setLocal(). o if your intent is to no longer manage the multimedia data within the database after the export() method is used but you do intend to continue to reference the multimedia data (e.g. as a BFILE) then you should call deleteContent() to free up the BLOB storage. The ability to write a file on the database server is a powerful one. This ability could potentially be used in malicious ways. One might attempt to overwrite critical database files or simply write large or numerous files in order to fill the server's disks. Because of these possibilities certain privileges must be in place before export() will work for a user. o First export() will only write to a directory object the user has privilege to access. That is, a directory the user has either created themselves with the SQL "CREATE DIRECTORY" command or one that they have been granted READ on. In order to execute the CREATE DIRECTORY command one must have the CREATE ANY DIRECTORY privilege. o Second, to further restrict which files can be written to the DBMS_JAVA.GRANT_PERMISSION must be used to specify which files are allowed to be written to. E.g. CALL DBMS_JAVA.GRANT_PERMISSION( 'MEDIAUSER', 'java.io.FilePermission', '/actual/server/directory/path/filename.dat', 'write'); See the Oracle8i Java Developer's Guide, Security and Performance for more information on DBMS_JAVA.GRANT_PERMISSION. 2) An additional ORDSource.import method has been defined: MEMBER PROCEDURE import( SELF IN OUT NOCOPY ORDSource, ctx IN OUT RAW, mimetype OUT VARCHAR2, format OUT VARCHAR2) This import method is nearly identical to the existing import method except that the destination BLOB is not passed in as a separate (redundant) parameter. It is likely that the import method with the redundant destination BLOB parameter will be deprecated in a future release. 3) The deleteContent() method was unintentionally setting most of ORDVir's metadata attributes to NULL. deleteConent() no longer touches the metadata attributes. Features Added in This Release ============================== 1) Static Methods for easy Initialization Static methods have been added which allow for easy initialization of instances of the ORDVir type. The method is called "init" and can be used in one of two variations. The first init takes no parameters and initializes all the media type's attributes to NULL with the following exceptions: image.source.updateTime is set to SYSDATE image.source.local is set to 1 image.source.localData is set to empty_blob() The second variation on "init" takes three string parameters which are directly mapped to source.srcType, source.srcLocation, and source.srcName. All of the other attributes are set to NULL with the following exceptions: image.source.updateTime is set to SYSDATE image.source.local is set to 0 image.source.localData is set to empty_blob() **IMPORTANT** We strongly recommend that you begin using the init method as soon as possible. We may evolve the ORDVir type in the future. If we add attributes to the ORDVir type in a future version, insert statements using the default constructor (which initializes each object attribute) will fail. Example Uses: SQL: INSERT INTO VIRTABLE_A VALUES ( ORDSYS.ORDVIR.init(), ... ); INSERT INTO VIRTABLE_B VALUES ( ORDSYS.ORDVIR.init('FILE','IMGDIR','product3154.jpg'), ... ); PL/SQL: DECLARE myImgA ORDSYS.ORDVIR; myImgB ORDSYS.ORDVIR; BEGIN myImgA := ORDSYS.ORDVir.init; myImgB := ORDSYS.ORDVir.init('FILE','IMGDIR','product3154.jpg'); ... INSERT INTO MEDIATABLE VALUES ( myImgA, myImgB, .... ); END; 2) New Visual Information Retrieval Java Classes for Image Content Oracle Visual Information Retrieval Java Classes enable Java applications on any tier (client, application server or database server) to manipulate and modify image data stored in Oracle8i. Applications connect to the database, select the media object, copy that object from the database, perform various operations and store the new media object in Oracle8i. Visual Information Retrieval Java Classes support JDBC access to image content. This support enables applications to select and operate on a result set that contains sets of ORDVir columns plus other relational data. These classes also enable access to object attributes and invocation of object methods. The new Visual Information Retrieval Java Classes will work with Oracle8i Server (8.1.5 or higher) and Oracle8i Client (8.1.6 or higher). To support JDBC, changes have been made to the Visual Information Retrieval Java Classes' syntax and semantics. It is no longer necessary to explicitly bind an application's copy of the object to a database object. It is also no longer necessary to refresh and flush the application's copy of the object to synchronize it with the corresponding database object. Instead, users retrieve ORDVir objects in their Java programs using the standard JDBC executeQuery() function call. Rather than flushing the application's copy of the object to the database, an explicit update is performed by executing a standard SQL update statement using the JDBC API. Another fundamental change is that all methods, with the exception of those that load data from an external data source into the BLOB, change the state of the application's copy of the object. The user must perform an explicit update as mentioned above in order to propagate changes to the database object. In addition, some APIs have been dropped from the new Java classes and some have been changed in minor ways. Please visit the Oracle Technology Network for detailed documentation on the new Java Classes. 3) The digital camera format known as "Exif" is now recognized by Visual Information Retrieval. The Exif format is essentially a variation on the JFIF format and as such the ORDVir.setProperties method sets the fileFormat attribute to JFIF. Known Problems in This Release ============================== Importing Visual Information Retrieval signature data across hardware platforms with different endian characteristics could silently corrupt the data. Users are advised to invoke the Convert() function to rectify the signatures after import. ======== Using the "process" method with progressively encode JPEG files will fail. ======== There is a performance bug in this release which causes the new operators, VIRSimilar and VIRScore, to be suboptimal in their performance when a domain index HAS NOT been created for Visual Information Retrieval. Hence, if for some reason a domain index has not been created we recommend that you use the older operators, vir.similar and vir.score (for usage please refer to Appendix E in the Visual Information Retrieval documentation). Wherever possible, create an index and use the operators VIRSimilar and VIRScore for best possible performance. If an index cannot be created, use the older operators instead of the new operators. ======== The operators VIRSimilar and VIRScore cannot be used in PL/SQL constructs (for example in an IF statement). They can be used in all SQL constructs (WHERE clause, SELECT clause, ORDER BY clause are few examples). Note that all the SQL constructs with the operators VIRSimilar and VIRScore can be used in a PL/SQL procedure. ======== Using the "process" method with progressively encode JPEG files will fail. Deprecated Features =================== 3rd Party Facial Recognition no Longer Supported ------------------------------------------------ In prior releases, Visual Information Retrieval supported facial signature conversion and image comparison from 3rd party facial recognition technology. Effective in 8.1.7, this support is no longer available. ORDImgB and ORDImgF Object Types Will Be Dropped ------------------------------------------------ The deprecated object types, ORDVirB and ORDVirF will not be shipped in versions after 8.1.7. ======================= END OF README.txt