===============================================================================
JJ2000
An Implementation of the JPEG 2000 Standard in Java(TM)
Version 4.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 utilization of the
JJ2000 decoder and encoder under several operating systems (Linux,
Unix, Windows, ...). The implementation is purely in Java(TM), so it
can run on any platform with a Java Virtual Machine for Java 1.1 and
later. The encoder and the decoder are compatible with FDIS text.
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 4.1 contains a complete JPEG 2000 decoder as well as an
encoder. The functionalities supported by this codec are compliant
with the JPEG 2000 part 1 algorithm as it is described in the Final
Draft International Standard.
As for the previous versions, this software has been extensively
tested and multiple codestreams exchanges have been done with the
Verification Model software (VM8.6) and some other known
implementations of JPEG~2000 part 1.
In addition to JPEG 2000 features, 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.
2a. JJ2000 backward compatibility.
----------------------------------
JJ2000 encourages all its users to download and use the version 4.1
that is the only JJ2000 version compatible with current description of
the standard (FDIS). See below to have a list of incompatibilities
with older versions.
* with version 4.0:
-------------------
Because of some modifications in the writing of packet headers, the
latest version is not compatible with version 4.0 when using the
arithmetic selective bypass mode ('-Cbypass' option) or when
terminating the arithmetic coding at the end of each coding pass
('-Creg_term' option).
* with version 3.2.2 and previous:
----------------------------------
Due to some revisions in the First Draft International Standard (FDIS)
and some corrections in JJ2000 source code, version 4.1 is not
compatible with releases 3.2.2 and previous concerning the following
points:
- Filtering with 9x7 filter pair. The FDIS imposes now another
convention for high pass coefficients signs.
- Reversible Component Transform: the 2 last components have been
swapped to conform the description given in FDIS.
2b. Known issues.
-----------------
JJ2000 version 4.1 do not write any packet whenever the formula
computing the number of precincts in each component and resolution
levels gives zero. However, this may contradict the following
statement of Annex B.6 in the Final Draft International Standard
(FDIS) of JPEG 2000 part 1:
'It can happen that a precinct is empty, meaning that no subband
coefficients from the relevant resolution level actually contribute to
the precinct. This can occur, for example, at the lower right of a
tile-component due to sampling with respect to the reference
grid. When this happens every packet corresponding to that precinct
must still appear in the codestream (see Annex B.9).'
This issue will be fixed as soon as a clarification, about whether or
not this situation is applicable to the case where no precinct exists,
is obtained.
3. Obtaining the code, documentation, etc.
==========================================
The compiled Java(TM) byte code, the source code and the documentation
can be downloaded by all WG1 members from the JJ2000 web site at:
http://jj2000.epfl.ch
or
http://jpeg2000.epfl.ch
The download of the software is protected by a password that can
obtained by filling a form at http://jj2000.epfl.ch/jj_download.
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_4.1.zip or
jj2000_4.1.tar.gz) 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-4.1' directory with the necessary files in it.
* on Unix, Linux:
unzip jj2000_4.1.zip
or
gunzip -c jj2000_4.1.tar.gz | tar xvf -
* with Windows: use WinZip with jj2000_4.1.zip
Note: If you use the tar.gz 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-4.1'
directory:
* jj2000-4.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), 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-4.1.jar;%CLASSPATH%
- UNIX with Bourne Shell (i.e. sh):
CLASSPATH=<jjdir>/jj2000-4.1.jar:$CLASSPATH
export CLASSPATH
- UNIX with C-shell (i.e. csh or tcsh):
setenv CLASSPATH <jjdir>/jj2000-4.1.jar:$CLASSPATH
(or setenv CLASSPATH <jjdir>/jj2000-4.1.jar
if CLASSPATH has not been already defined)
where <jjdir> is the full path of the directory where the
'jj2000-4.1.jar' file is found. For instance, under Windows, if
<jjdir> is 'C:\JJ2000\JJ2000-4.1\':
set CLASSPATH=C:\JJ2000\JJ2000-4.1\jj2000-4.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-4.1.jar JJ2KEncoder <args>
jre -cp <jjdir>\jj2000-4.1.jar JJ2KDecoder <args>
- UNIX:
jre -cp <jjdir>/jj2000-4.1.jar JJ2KEncoder <args>
jre -cp <jjdir>/jj2000-4.1.jar JJ2KDecoder <args>
where, as above, <jjdir> is the full path of the directory where the
file jj2000-4.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-4.1.jar JJ2KEncoder <args>
jview /cp:p <jjdir>\jj2000-4.1.jar JJ2KDecoder <args>
where, as above, <jjdir> is the full path of the directory where the
file jj2000-4.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_4.1-src.zip or
jj2000_4.1-src.tar.gz) 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-4.1' directory with the necessary files in it.
* on Unix, Linux:
unzip jj2000_4.1.zip
or
gunzip -c jj2000_4.1.tar.gz | tar xvf -
* with Windows: use WinZip with jj2000_4.1.zip
Note: If you use the tar.gz 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-4.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 JJ2KDecoder.java
To compile the decoder type, in the 'src' directory:
javac -depend JJ2KDecoder.java
The "-depend" option forces the compilation of all necessary files.
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_4.1-doc.zip or
jj2000_4.1-doc.tar.gz) 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-4.1' directory with the necessary files in it.
* on Unix, Linux:
unzip jj2000_4.1-doc.zip
or
gunzip -c jj2000_4.1-doc.tar.gz | tar xvf -
* with Windows: use WinZip with jj2000_4.1-doc.zip
- After this you should find the following files and directories in
the 'jj2000-4.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_4.1-src.zip -> jj2000_4.1-src.jar
- uncompress the archive: jar xvf jj2000_4.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
===================
14a. 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
14b. 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
14c. 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
14d. Changes in 3.2.1, from version 3.2
----------------------------------------
- Changed the license and copyright statement
14e. 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.
14f. Changes in 3.1, from version 3.0
--------------------------------------
- Packet partition support at encoder side
- Fixed all other known bugs
14g. 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
14h. 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
14i. Changes in 2.1.1, from version 2.1
---------------------------------------
- Bug fixes on SSO-DWT.
14j. Changes in 2.1, from version 2.0
-------------------------------------
- Fully functional implementation of the SSO-DWT with the canvas.
14k. 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.
14l. 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.
14m. 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
|
