INSTALLATION INSTRUCTIONS
Note to Windows users: use  Wordpad or Word (or other not-so-dumb text
reader)  to read  this file.   Notepad does  not understand  UNIX line
returns and will show all the file in 1 line.

===============================================================================
                                 JJ2000

             An Implementation of the JPEG 2000 Standard in Java(TM)

                               Version 5.1
===============================================================================


Outline:
=======

1.  General notes
2.  JJ2000 Implementation status
3.  Obtaining the code, documentation, etc.
4.  Installing the JJ2000 byte code
5.  Obtaining a Java(TM) Virtual Machine
6.  Running the JJ2000 bytecode (i.e. compiled code)
7.  Running the JJ2000 encoder and decoder
8.  Installing and using the JJ2000 source code
9.  Installing the pre-compiled JJ2000 documentation
10. JJ2000 embedded image viewer
11. Running JJ2000 decoder as an applet
12. Enabling multiprocessor features on SMP machines
13. Troubleshooting
14. Change history

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


1. General notes
================

This document  describes the  installation and the  use of  the JJ2000
decoder  and encoder  under  several operating  systems (Linux,  Unix,
Windows, ...).  The implementation  is purely written in Java(TM) 1.1,
so  it can  run on  any  platform with  a Java  Virtual Machine  (JVM)
version  1.1 or  later.   The  provided encoder  and  the decoder  are
compatible  with the  International standard  IS 15444-1  (core coding
system).

If  you   find  some   bugs  or  if   you  have  problems   using  the
encoder/decoder, please send an e-mail to jj2000-bugs@ltssg3.epfl.ch

2. JJ2000 implementation status
===============================

Version 5.1 contains a complete JPEG 2000 part 1 decoder as well as an
encoder.  The  supported functionalities  are compliant with  the JPEG
2000 part 1 algorithm as it is described in the International Standard
IS 15444-1.  The major improvement of  this last version  comes from a
complete support of the JP2 file format at the decoding side.

In addition, the JJ2000 codec  contains an embedded viewer for decoded
images (See 10,  "JJ2000 Embedded image viewer"), a  simple applet for
the JJ2000 decoder (See 11, "Running JJ2000 decoder as an applet") and
special  features that can  speed-up the  execution by  exploiting the
multiple   CPUs  of   multiprocessor  machines   (See   12,  "Enabling
multiprocessor features on SMP machines").

Finally, JJ2000 would like to acknowledge JJ2000 users for their valid
feed-back that allowed improving the code and fixing bugs.

3. Obtaining the code, documentation, etc.
==========================================

The  latest official  version corresponding  to the  compiled Java(TM)
byte code, the source code  and the documentation can be downloaded by
from the JJ2000 web site at:

        http://jj2000.epfl.ch
  or
        http://jpeg2000.epfl.ch

This  web site contains  also information,  tutorial and  useful links
related to JPEG 2000.

First the  explanations on how to  download, install and  run the byte
code are given. Instructions on how  to obtain and use the source code
are given towards the end of this document.

4. Installing the JJ2000 byte code (i.e. compiled code)
======================================================

- Download   the   latest   compressed  archive   (jj2000_5.1.zip   or
jj2000_5.1.tar.bz2) from the JJ2000 web site (http://jj2000.epfl.ch)

- Create the directory where you want to install the JJ2000 Codec.

- Decompress  the  archive  in  this  directory. This  will  create  a
'jj2000-5.1' directory with the necessary files in it.

        * on Unix, Linux:
                unzip jj2000_5.1.zip
        or
                bunzip2 -c jj2000_5.1.tar.bz2 | tar xvf -

        * with Windows: use WinZip with jj2000_5.1.zip

Note: If  you use the  tar.bz2 archive with  WinZip make sure  that the
automatic CR-LF  conversion is  turned off, since  this will  ruin the
files in the archive.

- After this you should find the following files in the 'jj2000-5.1'
directory:

        * jj2000-5.1.jar - This file contains all the Java compiled code
        * README         - The file you are reading
        * COPYRIGHT      - Copyright statement of the JJ2000 software

Note:

- Do not "unjar"  the jar file containing the  byte code. The Java(TM)
virtual  machine can  execute  byte  code contained  in  this kind  of
archive (JAR stands for Java ARchive).

- Since that Java(TM) byte-code can be used on any machine, you do not
need to recompile the software.

- The byte code  archive does not contain the  optional shared library
necessary  to  access  some  special JJ2000  funcionality  under  some
operating systems.  This library  is not necessary  to run  the JJ2000
software, unless  those very special  features are wanted.  The source
code  for the  library is  contained in  the source  distribution. See
section 10  for details on these  special features and  how to compile
the shared library.

5. Obtaining a Java(TM) Virtual Machine (if you don't have one)
===============================================================

In order to execute Java(TM) software a Java(TM) Virtual Machine (JVM)
is needed. If you already have one installed you can skip this point.

Many  Windows machines  come equipped  with a  Microsoft  JVM already,
which is version 1.1.x or later. Try, in an MS-DOS window, the command
'jview'.   If  a help  message  is displayed  then  a  JVM is  already
installed on your machine, you don't need to install a new one and you
can skip  the rest of  this point, unless  you want to try  with other
JVMs. For other architectures ask your system administrator.

If you don't have a JVM version 1.1.x or later installed, you can
download one from JavaSoft (for Solaris and Windows:
http://www.javasoft.com), Apple (for MacOS:
http://www.apple.com/java), or Microsoft (for Windows95/98/NT:
http://www.microsoft.com/java), Blackdown (for Linux:
http://www.blackdown.org), IBM
(http://www-105.ibm.com/developerworks/tools.nsf/dw/java-devkits-byname?OpenDocument&Count=100),
among other sites.  For other platforms a list of available ports is
available at JavaSoft's web site
(http://java.sun.com/cgi-bin/java-ports.cgi).

6. Running the JJ2000 bytecode (i.e. compiled code)
====================================================

How to execute  the byte code depends on  the Java(TM) Virtual Machine
(JVM) you use.  The only necessary thing is to set  what is called the
CLASSPATH, that indicates where to find the byte code.

Below is explained how to set the CLASSPATH for the most popular JVMs,
for other JVMs please refer to your JVMs documentation.

6a. Sun's Java Development Kit (JDK)
------------------------------------

If you are  using Sun's JDK (the command is  'java'), or an equivalent
JVM  you  have  to  set  the environment  variable  CLASSPATH  in  the
following way:

- Windows 95/98/NT (in an MS-DOS window):

        set CLASSPATH=<jjdir>/jj2000-5.1.jar;%CLASSPATH%

- UNIX with Bourne Shell (i.e. sh):

        CLASSPATH=<jjdir>/jj2000-5.1.jar:$CLASSPATH
        export CLASSPATH

- UNIX with C-shell (i.e. csh or tcsh):

        setenv CLASSPATH <jjdir>/jj2000-5.1.jar:$CLASSPATH
	(or setenv CLASSPATH <jjdir>/jj2000-5.1.jar 
	if CLASSPATH has not been already defined)

where  <jjdir>   is  the  full   path  of  the  directory   where  the
'jj2000-5.1.jar'  file  is  found.  For instance,  under  Windows,  if
<jjdir> is 'C:\JJ2000\JJ2000-5.1\':

        set CLASSPATH=C:\JJ2000\JJ2000-5.1\jj2000-5.1.jar;%CLASSPATH%

In order to make this setting  permanent you can add the line above at
the end of your C:\AUTOEXEC.BAT file in Windows, or your ~/.profile or
~/.cshrc file in UNIX with the sh or csh shells, respectively.

If you  are using Windows NT,  it is preferable to  make the following
environment variable changes  in the Control Panel, instead  of in the
C:\AUTOEXEC.BAT file.   Start the  Control Panel, select  System, then
edit the environment variable CLASSPATH.

The in order to run the encoder or decoder you can type, respectively:

        java JJ2KEncoder <arguments>

        java JJ2KDecoder <arguments>

More instructions on  how to use the encoder and  decoder can be found
below.

6b. Sun's Java Runtime Environment (JRE)
----------------------------------------

If you  are using Sun's JRE  (the command is 'jre'),  or an equivalent
JVM,  you  have  to  use  the  following  command-lines  (setting  the
CLASSPATH variable seems to have no effect):

- Windows 95/98/NT:

        jre -cp <jjdir>\jj2000-5.1.jar JJ2KEncoder <args>

        jre -cp <jjdir>\jj2000-5.1.jar JJ2KDecoder <args>

- UNIX:

        jre -cp <jjdir>/jj2000-5.1.jar JJ2KEncoder <args>

        jre -cp <jjdir>/jj2000-5.1.jar JJ2KDecoder <args>

where, as above, <jjdir> is the full path of the directory where the
file jj2000-5.1.jar is found.

More instructions on  how to use the encoder and  decoder can be found
below.

6c. Microsoft's JVM
-------------------

If you  are using  Microsoft's JVM, you  can either set  the CLASSPATH
environment  variable as  explained for  Sun's JDK  above, or  use the
following command-lines:

- Windows 95/98/NT:

        jview /cp:p <jjdir>\jj2000-5.1.jar JJ2KEncoder <args>

        jview /cp:p <jjdir>\jj2000-5.1.jar JJ2KDecoder <args>

where, as above, <jjdir> is the full path of the directory where the
file jj2000-5.1.jar is found.

More instructions on  how to use the encoder and  decoder can be found
below.

7. Running the JJ2000 encoder and decoder
=========================================

The JJ2000 encoder and decoder are very easy to run, and they follow a
syntax which is similar to the one from the JPEG 2000 VM.

The exact command line to type depends on the JVM you are running, for
the different  possibilities please refer to "Running  the JJ2000 byte
code" above. Here we provide examples  for Sun's JDK, but it should be
straightforward to derive the command-line for the other JVMs.

The speed of  the encoder or decoder will strongly  depend in the type
of JVM you  are using. JVMs which have  Just-In-Time compilation (JIT)
are much  faster than simple  interpreters. Most popular  JVMs include
JIT, so don't disable it.

To run the encoder you have to type:

        java JJ2KEncoder <args>

and for the decoder:

        java JJ2KDecoder <args>

where <args>  is the  arguments given to  the encoder or  decoder. The
'-u' argument  prints a  detailed usage message  to the  terminal. The
name and syntax  of the arguments are similar to those  of the VM. The
minor differences are due  to the implementation architecture which is
quite different.

The '-i' option denotes the  input file, while the '-o' option denotes
the output file. The '-v'  message prints the version and copyright of
JJ2000.

For instance, to code the well-known lena image to 2.0 bpp with the
other default options, type:

        java JJ2KEncoder -i lena.pgm -o lena.j2k -rate 2

Then to decode it at 1 bpp, type:

        java JJ2KDecoder -i lena.j2k -o lena-jj.pgm -rate 1

Supported image  file formats are:  PGM(raw), PGX and  PPM(raw). Color
image can be used either by using a PPM(raw) file or by using the Red,
Green and Blue components PGM or PGX files.

If you receive an "OutOfMemoryError" from the JVM you need to increase
the maximum memory limit of  the JVM. See "Troubleshooting" at the end
of this document to do that.

A  decent general purpose  image viewer  for Windows  can be  found at
"http://www.irfanview.com". Among other  image viewers that understand
the     PPM     and    PGM     format     there    is     PaintShopPro
(http://www.paintshoppro.com/).

For UNIX/X11, the  most popular image viewers understand  PGM and PPM,
as 'xv',  'ImageMagic', etc. Ask  your system administrator if  you do
not know if one of those is installed.

8. Installing and using the JJ2000 source code
==============================================

8a. Installing the source code
------------------------------

- Download    the    compressed    archive   (jj2000_5.1-src.zip    or
jj2000_5.1-src.tar.bz2)      from     the      JJ2000      web     site
(http://jj2000.epfl.ch)

- Create the directory where you want to install the JJ2000 Codec.

- Decompress  the  archive  in  this  directory. This  will  create  a
'jj2000-5.1' directory with the necessary files in it.

        * on Unix, Linux:
                unzip jj2000_5.1.zip
        or
                bunzip2 -c jj2000_5.1.tar.bz2 | tar xvf -

        * with Windows: use WinZip with jj2000_5.1.zip

Note: If  you use the  tar.bz2 archive with  WinZip make sure  that the
automatic CR-LF  conversion is  turned off, since  this will  ruin the
files in the archive.

- After this  you should find  the following files and  directories in
the 'jj2000-5.1' directory:

        * src/         - This directory contains all the Java source code
	* JNI-src/     - C source of methods using the Java Native Interface.
	                 This is optional.
        * README       - The file you are reading
        * COPYRIGHT    - The copyright statement of the JJ2000 software

Note that this source code  package does not contain the compiled byte
code or  the compiled  documentation, but that  both can  be generated
from the source code, or downloaded separately.

8b. Setting the CLASSPATH
-------------------------

In order to compile and run the compiled source code you need first to
set the CLASSPATH. With Sun's Java Development Kit (JDK) and most java
compilers  this   is  done   by  setting  the   CLASSPATH  environment
variable. Consult your compiler's documentation in case of trouble. In
the  case  of a  Java  Integrated  Development  Environment (IDE)  the
procedure can be significantly different.

- Windows 95/98/NT (in an MS-DOS window):

        set CLASSPATH=<jjdir>/src;%CLASSPATH%

- UNIX with Bourne Shell (i.e. sh):

        CLASSPATH=<jjdir>/src:$CLASSPATH
        export CLASSPATH

- UNIX with C-shell (i.e. csh or tcsh):

        setenv CLASSPATH <jjdir>/src:$CLASSPATH
	(or setenv CLASSPATH <jjdir>/src
	  if CLASSPATH has not been already defined)

where <jjdir>  is the full  path of the  directory in which  the 'src'
directory is found.

8c. Compiling the source code
-----------------------------

There are basically 2 ways  to compile the Java(TM) source code: using
the make or using the java compiler on the main class file.

Note  that the compilation  of the  optional C  source using  the Java
Native Interface requires  additional step. See section 10d  on how to
do that. The  C source files are optional and are  not required to run
JJ2000. They are only required to access some special operating system
features. See section 10 for more details.

- Using the make file

The  makefiles included  with JJ2000  use  GNU make.  Therefore it  is
necessary  to have  GNU make  installed in  order to  run  them. These
makefiles reconfigure automatically, so if  new files are added to the
project no  modifications are necessary  to the makefiles (not  so for
directory  additions). These  makefiles probably  won't run  under any
other make program. Under many  systems the GNU make program is called
'gmake'.

The makefile  uses the 'javac' command  line to call  the compiler. If
this is  different in your  system edit the 'GNUmakefile.var'  file in
the 'src' directory to match your compiler's command line.

In order  to use the  makefiles move to  the 'src' directory  and type
"make help" to see the list of available targets to compile.

In order to compile all the source code tree, type:

        make all

This will  compile all the files  in each Java  package, regardless if
they have been changed or not.

To compile just out of date files, type:

        make

For the other targets see "make help".

- Using the compiler with the main class file

If you  don't have  GNU make  installed, you can  always use  the java
compiler to compile all the source code in one call to it.

To compile the encoder type, in the 'src' directory:

        javac -depend JJ2KEncoder.java

To compile the decoder type, in the 'src' directory:

        javac -depend JJ2KDecoder.java

To compile the appler type, in the 'src' directory:

	javac -depend jj2000\j2k\decoder\SimpleAppletDecoder.java
 or
	javac -depend jj2000/j2k/decoder/SimpleAppletDecoder.java

 depending on your platform

Note:  the "-depend" option  forces the  compilation of  all necessary
files. This  option may have a  different name depending  on your java
compiler. Check your compiler's documentation in case of trouble.

8d. Running the compiled code
-----------------------------

To run  the compiled code  follow the instructions under  "Running the
JJ2000   byte   code"  above   by   replacing  <jjdir>/jj2000.jar   by
<jjdir>/src, and under "Running the JJ2000 encoder and decoder" above.

8e. Compiling the documentation
-------------------------------

The already  compiled documentation can be downloaded  from the JJ2000
web site  (see below). However it  can also be  compiled directly from
the code source.

To compile the documentation type, in the 'src' directory:

        make doc

This will generate the HTML  documentation of all the source code. The
documentation is placed in  the '<jjdir>/doc' directory, where <jjdir>
is the directory where the 'src' directory is found.

Unfortunately, due  to a  bug in the  Java 1.1  documentation compiler
(javadoc), the index  that is generated is empty.  Java 1.2 solves the
problem. The  documentation that can  be downloaded from the  web site
has been generated with Java 1.2.

9. Installing the pre-compiled JJ2000 documentation
===================================================

A  pre-compiled version of  the HTML  documentation can  be downloaded
from  the JJ2000  web site.  This  documentation can  also be  browsed
on-line from the same web site (http://jj2000.epfl.ch).

Below are the instructions on how to download the documentation.

- Download    the    compressed    archive   (jj2000_5.1-doc.zip    or
jj2000_5.1-doc.tar.bz2)      from     the      JJ2000      web     site
(http://jj2000.epfl.ch)

- Create the directory where you want to install the JJ2000 Codec.

- Decompress  the  archive  in  this  directory. This  will  create  a
'jj2000-5.1' directory with the necessary files in it.

        * on Unix, Linux:
                unzip jj2000_5.1-doc.zip
        or
                bunzip2 -c jj2000_5.1-doc.tar.bz2 | tar xvf -

        * with Windows: use WinZip with jj2000_5.1-doc.zip

- After this  you should find  the following files and  directories in
the 'jj2000-5.1' directory:

        * doc/            - This file contains all the HTML documentation
        * doc/index.html  - Main page of the documentation
        * README          - The file you are reading
        * COPYRIGHT       - The copyright statement of the JJ2000 software

- This documentation has been automatically generated by the "javadoc"
tool from Sun's JDK1.2.

10. JJ2000 embedded image viewer.
=================================

JJ2000 decoder  contains an embedded  viewer that allow  displaying of
decoded images.   Currently supported image types are  images with 1,3
and 4 components with same sizes and bit-depth less or equal to 8.  If
there is one component, it is  assumed to be gray-level data. If there
are 3, it is assumed to be  RGB data, in that order. Finally, if there
are  4 components,  it is  assumed  to be  RGBA data  (RGB plus  alpha
plane), in that order.

The viewer  is enable if not  output file is specified  in the command
line.  Hence, a typical command-line is the following:

	java JJ2KDecoder -i lena.j2k

(displays the compressed image 'lena')

11. Running JJ2000 decoder as an applet
=======================================

Since  version  4.0,  JJ2000  contains  a simple  applet  that  allows
decoding a specified  image in an HTML page. In  the source code, this
corresponds  the SimpleAppletDecoder  class in  the jj2000.j2k.decoder
package.   This  applet  accepts  all  the parameters  of  the  JJ2000
decoder, except  output files.  In  practice, the compressed  image is
downloaded, decoded and shown in the applet area. Finally, scroll bars
appear if the image is larger than the applet area.

An example use could be the following mark-up in an HTML page:

<applet code="jj2000.j2k.decoder.SimpleAppletDecoder.class"
 archive="jj2000-aplt.jar"
 width="512" height="512">
   <param name="i" value="tools.jp2">
   <param name="res" value="3">
</applet>


12. Enabling multiprocessor features
====================================

As from version 3.2 some portions of JJ2000 have been parallelized and
are  able to  exploit multiple  CPUs in  parallel, reducing  the total
execution time. Parallellism is implemented by using multiple threads.

12a. Currently parallelized portions of JJ2000
----------------------------------------------

Currently  only  the  entropy  encoder  has  been  parallelized.   The
parallelization occurs at the  code-block level, meaning that multiple
code-blocks will be encoded  in parallel.  The parallel implementation
is selectable at run-time.  By default the non-parallel implementation
is used.

12b. Necessary requirements to exploit parallel features
--------------------------------------------------------

In  order to  exploit the  parallel  features of  JJ2000 the  Java(TM)
Virtual Machine (JVM)  must use native threads and  must allow them to
map to multiple CPUs. Using a "green" threads JVM will not profit from
multiple CPUs, although JJ2000 will function correctly if the parallel
features are enabled in such JVMs.

Of  course, running  on a  multiprocessor  machine is  also needed  to
exploit the parallel features.

The following JVMs and Operating Systems, at least, should work:

	- IBM 1.1.x JVMs under Linux 2.2.x
	- IBM 1.2.x and 1.1.x JVMs under Windows NT / 2000
	- Sun/Blackdown's 1.1.x and 1.2.x JVMs under Linux 2.2.x
	- Sun's 1.3.x, 1.2.x and 1.1.x JVMs under Windows NT / 2000
	- Microsoft 1.1.x JVMs under Windows NT / 2000
	- Sun/SGI's 1.2.x and 1.1.x JVMs on IRIX/IRIX64 (see below)
	- Sun 1.2.x and 1.1.x JVMs on Solaris (see below)

Most UNIX  operating systems (not Linux)  do not allow  access to more
than 1 CPU to the JVM without special steps. In order to allow the JVM
to access multiple  CPUs it is necessary to  set the concurrency level
of the POSIX threads system. See "Concurrency level and POSIX threads"
below on how to do that.

12c. Turning parallel features on
---------------------------------

The parallel  features in  JJ2000 are enabled  by using a  Java system
property.

For the entropy encoder the  number of extra threads used is specified
by the following Java system property:

   jj2000.j2k.entropy.encoder.StdEntropyCoder.nthreads

If set  to 0  (the default) the  non-parallel (i.e.   single threaded)
version of the entropy coder will be  used. If set to N (1 or larger),
N threads will be used  to encode code-blocks in parallel. In general,
N should be set to the number of processors in the machine for optimal
performance. If N  is set to 1 no code-blocks  are encoded in parallel
but the logic for parallel encoding is  used. If N is set to less than
the number  of processors  in the machine  the full  machine potential
will  not be  exploited. If  in is  set to  something larger  than the
number of processors in the  machine then the overall performance will
be most likely reduced, although not by any significant amount (unless
N is excessively large).

The Java  system property can  be set on  the JVM command line  and in
some cases in  some configuration file. To set it  in the command line
use the  '-D' option to the  JVM.  For example,  the following command
line will use 2 extra threads for parallel encoding of code-blocks.

  java -Djj2000.j2k.entropy.encoder.StdEntropyCoder.nthreads=2 JJ2KEncoder ...

12d. Concurrency level and POSIX threads
----------------------------------------

The  POSIX threads  on most  UNIX  operating systems  (not Linux)  use
process  scope scheduling  (PTHREAD_SCOPE_PROCESS) with  a concurrency
level of 0 by default. This  means that the system will map threads to
system  processes (and  thus  different CPUs,  if any)  automatically.
Unfortunately the  method by which the system  automatically finds the
number   of  system   processes  to   use  depends   on   the  threads
blocking. Since  JJ2000 uses  CPU bound threads  that do not  block no
extra system processes are created and only 1 CPU is ever used.

In order to set the concurrency  level manually it is necessary to use
native methods  since the Java system  does not provide  access to it.
JJ2000 does  have the necessary native  methods implemented.  However,
the  shared  library containing  these  is  not  distributed with  the
bytecode (i.e.  compiled) archive since  it is system dependent but it
can be easely compiled from the source distribution.

To compile  the shared  library go to  the 'JNI-src' directory  in the
JJ2000  distribution.  The  makefile  in this  directory requires  GNU
make.   Under many  systems the  GNU  make command  is called  'gmake'
instead of 'make'. The makefile is called 'GNUmakefile'.

The 'GNUmakefile'  has default definitions for many  systems and finds
most  values  automatically.  However,  in  your  system  it might  be
necessary to modify  some of the defaults. See  the 'GNUmakefile' file
on how to do that.

Then type 'make' (or 'gmake') in that directory. This will compile the
library 'libjj2000.so'. Place this library in some directory where the
system  can find  it. Typically  these directories  are listed  in the
LD_LIBRARY_PATH,  LD_LIBRARYN32_PATH or  similar  variables. For  IRIX
systems  the library  is compiled  using  the "n32"  ABI interface  so
LD_LIBRARYN32_PATH applies.

To set the concurrency level  for JJ2000, set the Java system property
"jj2000.j2k.util.ThreadPool.concurrency"   to   the   desired   value.
Typically this  would be the number  of processors in  the machine, or
some slightly higher  value (1 or 2 more).  For example, the following
command line will set the concurrency level to 4 and use 4 threads for
the parallel entropy encoder.

  java -Djj2000.j2k.util.ThreadPool.concurrency=4 \
    -Djj2000.j2k.entropy.encoder.StdEntropyCoder.nthreads=4 JJ2KEncoder ...

A message will be printed notifying the change in concurrency.

Note that setting  the concurrency level only works  for POSIX threads
based JVMs. Attepmting to set the concurrency level on other JVMs will
probabaly crash them due  to unsatisfied references. POSIX threads are
often referred to as "native" threads in UNIX JVMs.

Also note  that under  IRIX it is  necessary to  use the JVM  with the
"n32" ABI interface,  which is the default. In  some cases, the '-n32'
option might need to be given in the JVM command line. For example the
following command line selects the "native" threads and "n32" ABI:

  java -n32 -native ...

12e. What kind or performance increase can be expected ?
--------------------------------------------------------

The  performance  increase that  can  be  expected  from the  parallel
entropy  coder depends  on the  proportion  of time  spent on  entropy
coding and the number of processors.

As an example, when running the JJ2000 encoder in lossless mode on the
gray-level "bike" image  on a lightly loaded dual  Pentium III 550 MHz
PC with  the IBM 1.1.8  JDK under Linux  2.2.12, the encoding  time is
reduced from  15 secs (for  the single-threaded implementation)  to 10
secs (setting  N to  2).  The  time spent on  entropy coding  alone is
reduced  by a  factor of  1.9,  which means  an efficiency  of 96%  in
exploting the entropy coder parallelism.

The speed-up  factor will vary  depending on the image,  the transform
used, the  quantization step size  (i.e. the number of  bitplanes) and
some other minor factors. However,  the speed-up of the entropy coding
for N = 2 will be close to 1.9 in most cases.

13. Troubleshooting
==================

- If you  have problems  when unpacking the  archive, you can  use the
zipped java tool jar (Java ARchive):

        - Rename the archive: jj2000_5.1-src.zip -> jj2000_5.1-src.jar
        - uncompress the archive: jar xvf jj2000_5.1-src.jar

- If you can not run the decoder and the encoder:

        Make sure that the CLASSPATH is correctly set. Follow the
        instructions under "Running the JJ2000 bytecode".

- If you receive an out-of-memory error from the Java Virtual Machine (JVM):

        You will need to increase the memory limit of the JVM. How to
        do this depends on the particular JVM you are using. With
        Sun's JDK or JRE the option "-mx20m" increases the memory limit
        to 20 megabytes, you can replace 20 by any other number.

- If you have problems compiling with optimizations:

        Compilers derived from Sun's JDK 1.1.x have a bug that prevents
        compilation of JJ2000 when the '-O' flag is given. If you experience
        compilation errors about final variables when doing 'make release'
        or 'make distrib', upgrade to JDK 1.2.x or turn off optimizations
        by changing the 'JAVACRELEASEFLAGS' variable in the
        'src/GNUmakefile.var' file.

14.  Change history
===================

* Changes in 5.1, from version 5.0
----------------------------------

- Complete support of JP2 file format (at decoding side)

* Changes in 5.0, from version 4.2
----------------------------------

- Support for constrained reconstruction (i.e. reconstruction with
  limited number of layers, code-blocks, ...).
- Several bug-fixes

* Changes in 4.2, from version 4.1
----------------------------------

- Several bug-fixes

* Changes in 4.1, from version 4.0
----------------------------------

- Update of the optional JPEG 2000 part 1 file format (JP2)
- Implementation of  a tool  indicating the length  of the ROI  in the
codestream (at the encoder side)
- Add COM marker segment at the encoder side
- Some bug fixes

* Changes in 4.0, from version 3.2.2
------------------------------------

- Updated to be compliant with FDIS of JPEG 2000 Part-1 (IS 15444-1) 
- ROI with arbitrary shape
- 2nd and 3rd components swapped in Reversible Component Transform
- Optimized JJ2000 encoding default options
- Packed Packet Header at the encoder side
- New wavelet filters conventions
- New code stream parser for the decoder
- Some reorganization in the source code (distinct encoder and decoder 
  packages)
- Applet for the decoder

*  Changes in 3.2.2, from version 3.2.1
----------------------------------------

- Optimized the entropy encoding/decoding engines. The new engine packs
  coefficient states and has unrolled loops. Runs faster and uses less memory.
- Implemented error detection based on predictable termination at the decoder.
  Error detection is now selectable (i.e. can be turned on/off).
- Fixed known bugs

*  Changes in 3.2.1, from version 3.2
------------------------------------- 

- Changed the license and copyright statement

*  Changes in 3.2, from version 3.1
----------------------------------- 

- User selectable parallel implementation of entropy encoding on
  multiprocessor machines (with appropriate Java(TM) Virtual Machine).
- Packed Packet Headers (PPM,PPT) for the decoder.
- Tile specific, component specific and tile-component specific options 
- Tile parts.
- File format. 
- Progression order changes.
- SOP and EPH marker segments.
- New code stream parser.
- Many classes, methods and variables renamed, source-code somewhat 
  reorganized to reflect the FCD terminology.
- Part 2 functionalities and features removed.  

*  Changes in 3.1, from version 3.0
-----------------------------------

- Packet partition support at encoder side
- Fixed all other known bugs


*  Changes in 3.0, from version 2.9
-----------------------------------

- Tile-component specific encoding/decoding options for almost all modules
  (quantizer, kernels, Region of interest, entropy coder modes, code-blocks
  length)
- Packet partition support at decoder side
- Display of JPEG2000 decoded images embedded in the decoder
- RGN markers are written in tile headers
- Header writers and readers almost entirely rewritten
- Added an option (-Rstart_level) to allow the encoder to include a number
  of entire resolution levels in the ROI mask
- Fixed all other known bugs
 

*  Changes in 2.9, from version 2.1.1
-------------------------------------

- Update of code-stream syntax (as from CD 1.0 specification)
- Improved decoder's main header parser.
- Packets, Tile and headers are byte aligned.
- Bit stuffing (selective arithmetic coding bypass mode and in packet header)
- Improvements and fixes on rate allocator
- Updated near optimal length computation for MQ coded lengths
- Fix a bug on cell's partition origin projection into the canvas
- Fix some bugs on ROI (ROI and maxshift, RGN marker segment)
- Fixed all other known bugs


* Changes in 2.1.1, from version 2.1
------------------------------------

- Bug fixes on SSO-DWT.


* Changes in 2.1, from version 2.0
----------------------------------

- Fully functional implementation of the SSO-DWT with the canvas.


* Changes in 2.0, from version 1.1
----------------------------------

- Implemented the new entropy coder adopted in Vancouver, with all
  options.
- Implemented ROI, including rectangular and circular ROIs, maxshift
  method and fast rectangular mask generation.
- Implemented the canvas system, as scheduled for VM5.3 (except for SSO-DWT).
- Implemented the Single Sample Overlap DWT (SSO-DWT).
- Implemented segmentation markers and corresponding error detection
  and concealment.
- Updated to WD3.0PRB syntax.
- Greatly improved execution time.
- Reduced memory consumption.
- Improved the internal architecture and modularity.
- Removed support for old VM3.xA syntax.
- Fixed all known bugs.
- Added decoding to bitrate by parsing, in addition to truncation.


* Changes in 1.1, from 1.0
--------------------------

- Standard syntax (from VM4.2 text) can now be generated by the
  encoder.
- Known bugs have been fixed:
    - Color images (with standard syntax) decoding.
    - Spacl and Packet decomposition decoding.


* Version 1.0
-------------

This was the first release to WG1, and was based on VM4 text.

It supported the following:

- Adjustable number of wavelet decomposition levels
- All bitstream profiles
- Reversible coding
- Wavelet kernels: floating-point 9x7, integer 5x3 and CRF13x7
- Mallat, Spacl and Packet wavelet decompositions
- Implicit quantization
- Tiling
- Target bitrate using post compression rate allocation
- Adjustable base quantization step size
- Selectable wavelet kernels for different resolution levels and
  different components
- Adjustable number of guard bits
- Adjustable codeblock size
- Adjustable subblock size
- Configurable layer distribution
- Reduced resolution decoding
- Decoding some image components only
- Truncation at specified decoding rate