 Copyright (c) 2005, Oracle. All Rights Reserved.

   NAME
     README_JPEG2000.txt - ORACLE interMedia JPEG2000 Support Information

                        =======================

Contents
========

     Introduction
     Enabling JPEG2000 Image Processing
     Permission considerations for reading/writing JPEG2000-compressed files 
     Natively compiling JPEG2000 codec to improve performance
     Disabling JPEG2000 Image Processing


Introduction
============

JPEG2000 is an image compression format defined by International
Telecommunication Union (ITU). The image file format JP2, also defined
by ITU, can be used to wrap JPEG2000 compressed image data. 

In Oracle 10g Release 2, interMedia can recognize the JP2 file format,
and retrieve image properties such as height, width and compression
format. interMedia can also read and write metadata formatted using
the Extensible Metadata Platform (XMP) to JP2 files. No action is
required to use this feature.

To enable processing of JPEG2000 compressed images stored in the JP2
format or DICOM format, the user must install an additional Java
package into the Oracle Database. This package can be downloaded from
Sun Microsystems and is part of Java Advanced Imaging Image I/O
Tools. When the package is installed, interMedia will dynamically
detect the presence of the JPEG2000 codec in the database at runtime.
If the codec is present, the interMedia image processing code will use
the codec to compress and decompress the JPEG2000 image data as
required.


Enabling JPEG2000 Image Processing
==================================

Follow these steps to enable interMedia JPEG2000 image processing 
in the database: 

1. Download the "Java Advanced Imaging Image I/O Tools 1.0_01" package 
   from "Java Advanced Imaging (JAI) API" webpage on Sun Microsystems's 
   Java website. After you click the download button and accept the 
   license, you will be directed to the download page. On the download 
   page, there are several install options, like "CLASSPATH Install", 
   "JDK Install", and "JRE Install". Choose the "CLASSPATH install".

2. Extract the JPEG2000 codec jai_imageio.jar and clibwrapper_jiio.jar
   from the downloaded package to:
     <ORACLE_HOME>/ord/jlib (on UNIX)
     <ORACLE_HOME>\ord\jlib (on Windows)

3. Start SQL*Plus and connect as SYSDBA.

4. Invoke the initjp2.sql script to create ORDJP2K schema and install 
   the JPEG2000 codec into the ORDJP2K schema:

-> SQL> @<ORACLE_HOME>/ord/im/admin/initjp2.sql (on UNIX)
        @<ORACLE_HOME>\ord\im\admin\initjp2.sql (on Windows)

   If you would like to install the JPEG2000 codec into another schema,
   you can edit the JP2SCHEMA definition in the initjp2.sql script to 
   suit your needs.


Permission considerations for reading/writing JPEG2000-compressed files 
=======================================================================

The script initjp2.sql grants read/write/delete permissions on
java.io.tmpdir to ORDJP2K and ORDSYS, because Sun Microsystems's
implementation of the JPEG2000 codec calls
java.io.File.createTempFile. 

Extra permissions on the temporary directory are needed if users want to 
write JPEG2000-compressed files. These permissions can be granted in 
one of two ways:

1. Explicitly grant read/write/delete permissions on 
   java.io.tmpdir to every database schema that will call 
   ORDSYS.ORDImage.processCopy to write JPEG2000 images. 

2. Grant definers rights to class J2KImageWriter, which is one of the 
   classes in Sun Microsystems's implementation of JPEG2000 codec:

  a. Start SQL*Plus and connect as SYSDBA.
  b. Run the following SQL commands: 

     SQL> alter session set current_schema = "ORDJP2K";
     SQL> alter java class 
          "com.sun.media.imageioimpl.plugins.jpeg2000.J2KImageWriter" 
          AUTHID DEFINER;


Natively compiling JPEG2000 codec to improve performance
=============================================================

If your platform supports the Oracle Java Accelerator tool NCOMP, then
you can use it to improve the performance of JPEG2000 image
processing. Given a JAR file, the NCOMP tool performs the following:
- Verifies the classes that are loaded in the database.
- Retrieves the Java bytecodes for these classes from the database and
  stores them in a specified project directory.
- Translates the Java bytecodes into platform independent C code. 
- Compiles and links the C source code using a platform-dependent C
  compiler into shared libraries or dynamic-link libraries. 
- Deploys the libraries into the Oracle Database. The deployed
  libraries can be found under <ORACLE_HOME>/javavm/admin directory.
At runtime, the Java virtual machine will route function invocations
to natively compiled libraries if they are available.

For more information on using the Accelerator to produce natively compiled
libraries, see Chapter "Oracle Database Java Application Performance" 
in the Oracle Database Java Developer's Guide. 

interMedia includes a Perl script, ncompjp2.pl, that will help you to
produce natively compiled libraries for the JPEG200 image codec.

To run ncompjp2.pl script:

1. Change directory to:

  <ORACLE_HOME>/ord/im/admin (on UNIX)
  <ORACLE_HOME>\ord\im\admin (on Windows)

2. Invoke ncompjp2.pl as:

  PROMPT> perl ncompjp2.pl -u <JP2SCHEMA name> -d <projectDir> -h

  Arguments:
    
   -u        : JPEG2000 schema name. JP2SCHEMA is ORDJP2K by default 
               unless it is overridden in initjp2.sql. This argument 
               is required.
   -d        : Specifies the full path for the NCOMP project directory. 
               This directory must exist. The tool will not create this 
               directory for you. This argument is required.
   -h        : help message. This argument is optional.


Make sure the following requirements are met before running the 
script:

1. Database is up and environment variable ORACLE_HOME is set 

2. SQL*Plus can be run from command prompt

3. PATH environment variable includes the directory where PERL 
   executable resides

4. NCOMP project directory exists 

5. Satisfy the following requirements for running the NCOMP
   utility. Please see "Oracle Database Java Developer's Guide" 
   for more details.

  a. Install a C compiler for the intended platform on the
     computer where you are running NCOMP.
  b. Verify that the correct compiler and linker commands are 
     referenced within the Settings_os.properties file located
     in the <ORACLE_HOME>/javavm/jahome directory. If the
     settings are not correct, it's possible to override them
     by creating a file called Settings_os_PRODUCT.properties
     in the NCOMP project directory. Any settings in this file
     override the global settings. For example, on Windows, the
     Settings_os.properties, by default, sets:
       visual.c.home = c:/devstudio/vc
     If your VISUAL C is installed under:
       C:\Program Files\Microsoft Visual Studio .NET 2003\Vc7
     you can create Settings_os_PRODUCT.properties with one
     line as:
  visual.c.home = "C:\Program Files\Microsoft Visual Studio .NET 2003\Vc7"
     NCOMP will then pick up the compiler and linker under the
     correct directory.

     Note: on Windows, if there are spaces in the
     "visual.c.home" path string, put double quotes (") around
     the string as in the above example.


This script prompts user to enter the SYSDBA password. 

This script prints out "JPEG2000 library NCOMP succeeds!"
if NCOMP succeeds, otherwise "JPEG2000 library NCOMP problems
detected!". When NCOMP fails, the content of the JP2SCHEMA's 
jaccelerator$dlls and jaccelerator$dll_errors tables are
printed out. These two tables are populated by NCOMP to
record the deployment results and errors. 
Each row in the jaccelerator$dlls table represents a shared
library. If the STATUS column is "installed", then the
library is ncomped successfully.

Under the NCOMP project directory, besides the ncomp.log
generated by the NCOMP utility, this script also saves the 
NCOMP's standard error to a log file named ncompjp2.log.
When NCOMP fails, check these two log files for detailed error
information.

Note: if "JPEG2000 library NCOMP problems detected!" shows up,
you should check ncomp.log first to find out whether the 
C compiler reference is right. If the C compiler or linker
cannot be found, ncomp.log will contain errors like "got 
java.io.IOException: CreateProcess".


Disabling JPEG2000 Image Processing
===================================

Follow these steps to disable interMedia JPEG2000 image processing
in the database:

1. Start SQL*Plus and connect as SYSDBA.
 
2. Invoke the imdrpjp2.sql script to drop ORDJP2K schema and revoke the
   permissions granted to ORDJP2K.

-> SQL> @<ORACLE_HOME>/ord/im/admin/imdrpjp2.sql (on UNIX)
        @<ORACLE_HOME>\ord\im\admin\imdrpjp2.sql (on Windows)

