JasPer Software Reference Manual

(Version: $Id$)

• Introduction
• Obtaining the Software
• Extracting the Software
• Building the Software
• Using the Software
• The jasper Command
• The imgcmp Command
• The imginfo Command
• Reporting Bugs
• Additional JasPer Resources
• Origin of the Name

The JasPer software is a collection of utilities for image coding. Arguably, the most useful utility in the JasPer suite is the transcoder program. This particular program accepts image data in one format and generates image data in another format. The JasPer software can handle image data in a number of popular formats, including JPEG 2000, PNM/PGM/PPM, Windows BMP, and Sun Rasterfile. Since the JPEG-2000 format is supported, the transcoder program can be used as a JPEG-2000 encoder or decoder.

The design of the JasPer JPEG-2000 codec implementation was driven by several key concerns: execution speed, memory usage, robustness, portability, modularity, maintainability, and extensibility. In some cases, however, during the design process, modularity, portability, and understandability of the code were weighed more heavily than execution speed and memory usage. Code understandability and portability were critical considerations since the JasPer software was intended to be used as a reference implementation of JPEG-2000 codec.

The JasPer software is written in the C programming language. This language was chosen mainly due to the availability of C development environments for most of today's computing platforms. The JasPer software consists of about 27k lines of code in total. This code is spread across several programs and libraries.

Return to the Table of Contents.

The latest version of the JasPer software can be downloaded from the following locations:

• JasPer Project Home Page.
• Image Power Home Page.

Return to the Table of Contents.

The JasPer software is distributed in the form of a Zip file. Therefore, in order to extract the contents of this file, a program capable of handling Zip archives is required. Such software is readily available for many different computing platforms:

• UnZip Software. Unzip software for many different platforms (e.g., UNIX, DOS, MacOS, etc.).
• WinZip. Zip/UnZip software for Microsoft Windows.

Return to the Table of Contents.

Obviously, before the software can be built, the contents of the archive file containing the JasPer distribution must be extracted.

The JasPer code should compile and run on any platform with a C language implementation conforming to ISO/IEC 9899:1999 (i.e., the ISO C language standard) and supporting a subset of ISO/IEC 9945-1:1990 (i.e., the POSIX C API). Only limited POSIX support is required (i.e., the open, close, read, write, and lseek functions must be supported).

The specific procedure required to build the JasPer software depends on the type of system involved. Only two different build methods are supported. The first method is based on the well known make utility and should work on most UNIX (or UNIX-like) systems. The second method is specifically tailored to the needs of Microsoft Visual C under Microsoft Windows. In passing, we note that by using free software such as Cygwin, one can also create a UNIX-like environment under Microsoft Windows in which to build JasPer using the first method.

If you are unfortunate enough to have a compiler that is not compliant with ISO/IEC 9899:1999 (i.e., the C language standard), you may need to make some changes to the code. Unfortunately, even some of the most popular C language implementations do not strictly comply with the standard. One such example is Microsoft Visual C 6.0. Due to the popularity of Visual C, however, several workarounds have been added to the JasPer code to ensure that it will compile successfully with Visual C.

The current version of the JasPer software is known to compile in the following environments:

• Red Hat Linux 7.0, GNU C 2.96, GNU Make 3.79.1
• SunOS/SPARC 5.5.1, GNU C 2.7.2.1, SunOS make
• SunOS/SPARC 5.7, GNU C 2.95, SunOS make
• Windows 2000 Professional, Microsoft Visual C 6.0

• Apple Macintosh PPC G3, Rhapsody 5.6, GNU C 2.7.2.1
• Power Macintosh, GNU/Linux 2.2.15pre9, GNU C 2.95.2
• Sun SPARC, Solaris 2.7, GNU C 2.95.2
• Compaq/DEC Alpha, OSF/1 4.0F, GNU C 2.95.2
• IBM PowerPC, AIX 4.2, GNU C 2.95.2
• HP 9000/712, HP-UX 10.20, GNU C 2.95.2
• SGI Origin 200, IRIX 6.5, GNU C 2.95.2

Build Process for UNIX (or UNIX-Like) Systems

The JasPer software is intended to be built using the standard UNIX make utility (in conjunction with a configure script).

If you need a C compiler that is reasonably compliant with the ISO/IEC 9899:1999 standard, you can obtain GNU C from the GNU Project web site. If you need an implementation of Make, you can also obtain GNU Make from the the GNU Project web site. All GNU software is free software.

In what follows, "$TOPDIR" denotes the top level directory of the JasPer software distribution (i.e., the directory containing the file named configure). To build the software, the following steps are required (in order):

1. Set the current working directory to the top level directory of the JasPer software distribution. To set the current working directory as required, type:
   • cd $TOPDIR
   (where $TOPDIR is defined as described earlier in this section).
2. Run the configure program. This allows important information about the system configuration to be determined. In theory, it should not be necessary to manually edit any of the makefile templates (i.e., the Makefile.in files) used by the configure program. To invoke the configure program, type:
   • ./configure
3. Run the make command. The make command is what actually builds the software. In theory, it should not be necessary to manually edit any of the makefiles. To run the make program, type:
   • make

Build Process for Microsoft Visual C Studio under Microsoft Windows

With Microsoft Visual C, the entire build process is driven from workspace and project files. For the sake of convenience, all of the workspace and project files necessary to build the JasPer software are provided.

In what follows, "$TOPDIR" denotes the top level directory of the JasPer software distribution (i.e., the directory containing the file named configure). To build the software, the following steps are required (in order):

1. Run Microsoft Visual C.
2. Open the JasPer workspace file. This file is called jasper.dsw and can be found in the directory $TOPDIR/src/msvc.
3. Build the code. From the "Build Menu", select the "Batch Build" item. Ensure that all projects/configurations are selected. Then, click on the "Build" button.

Return to the Table of Contents.

1. jasper. The JasPer transcoder.
2. imgcmp. An image comparison utility.
3. imginfo. An image information utility.

Return to the Table of Contents.

Synopsis

Description

The jasper command converts image data from one format to another. In other words, this command functions as a general-purpose transcoder. Since the JPEG-2000 format is supported by this software, it can be used as a JPEG-2000 encoder and/or decoder.

Options

The jasper program accepts the following options:

• --help
  Print usage information and exit.
• --version
  Print the version and exit.
• --input file
  -f file
  Read the input image from the file named file. By default, the input image is read from standard input.
• --input-format format
  -t format
  Specify the format of the input image as format. In most circumstances, this option should not be needed, as the format is normally autodetected by examining the image data directly or deduced from the input file name extension if an input file is specified (via the "--input" option).
• --input-option option
  -o option
  Provide the option option to the decoder. The valid values for the argument option are determined by the input image format. See below for more details.
• --output file
  -F file
  Write the encoded image to the file named file. By default, the encoded image is written to standard output.
• --output-format format
  -T format
  Produce the output image in the format indicated by format. The output format must be specified if an output file is not given (via the "--output" option). If an output file is given and no output format is specified, an attempt will be made to deduce the correct format from the output file name extension.
• --output-option option
  -O option
  Provide the option option to the encoder. The valid values for the argument option are determined by the output format. See below for more details.
• --terse
  -q
  Disable verbose mode.

• bmp (Windows BMP)
• jp2 (JPEG-2000 JP2)
• jpc (JPEG-2000 Code Stream)
• pnm (PNM/PGM/PPM)
• mif (My Image Format)
• ras (Sun Rasterfile)

BMP Encoder Options

The BMP encoder does not support any special options.

BMP Decoder Options

The BMP decoder does not support any special options.

JP2 Encoder Options

The JP2 encoder supports all of the same options as the JPC encoder.

JP2 Decoder Options

The JP2 decoder supports all of the same options are the JPC decoder.

JPC Encoder Options

The following options are provided by the JPC encoder:

• imgareatlx=x
  Set the x-coordinate of the top-left corner of the image area to x.
• imgareatly=y
  Set the y-coordinate of the top-left corner of the image area to y.
• tilegrdtlx=x
  Set the x-coordinate of the top-left corner of the tiling grid to x.
• tilegrdtly=y
  Set the y-coordinate of the top-left corner of the tiling grid to y.
• tilewidth=w
  Set the nominal tile width to w.
• tileheight=h
  Set the nominal tile height to h.
• prcwidth=w
  Set the precinct width to w. The argument w must be an integer power of two. The default value is 32768.
• prcheight=h
  Set the precinct height to h. The argument h must be an integer power of two. The default value is 32768.
• cblkwidth=w
  Set the nominal code block width to w. The argument w must be an integer power of two. The default value is 64.
• cblkheight=h
  Set the nominal code block height to h. The argument h must be an integer power of two. The default value is 64.
• mode=m
  Set the coding mode to m. The argument m must have one of the following values:
  • int ... integer mode
  • real ... real mode
  If lossless coding is desired, the integer mode must be used. By default, the integer mode is employed. The choice of mode also determines which multicomponent and wavelet transforms (if any) are employed.
• rate=r
  Specify the target rate. The argument r is a positive real number. Since a rate of one corresponds to no compression, one should never need to explicitly specify a rate greater than one. By default, the target rate is considered to be infinite.
• ilyrrates=rate_0[,rate_1,...,rate_{N-1}]
  Specify the rates for any intermediate layers. The argument to this option is a comma separated list of N rates. Each rate is a positive real number. The rates must increase monotonically. The last rate in the list should be less than or equal to the overall rate (as specified with the rate option).
• prg=p
  Set the progression order to p. The argument p must have one of the following values:
  • lrcp ... layer-resolution-component-position (LRCP) progressive (i.e., rate scalable)
  • rlcp ... resolution-layer-component-position (RLCP) progressive (i.e., resolution scalable)
  • rpcl ... resolution-position-component-layer (RPCL) progressive
  • pcrl ... position-component-resolution-layer (PCRL) progressive
  • cprl ... component-position-resolution-layer (CPRL) progressive
  By default, LRCP progressive ordering is employed. Note that the RPCL and PCRL progressions are not valid for all possible image geometries. (See ISO/IEC 15444-1 for more details.)
• nomct
  Disallow the use of any multicomponent transform.
• numrlvls=n
  Set the number of resolution levels to n. The argument n must be an integer that is greater than or equal to one. The default value is 5.
• sop
  Generate SOP marker segments.
• eph
  Generate EPH marker segments.
• lazy
  Enable lazy coding mode (a.k.a. arithmetic coding bypass).
• termall
  Terminate all coding passes.
• segsym
  Use segmentation symbols.
• vcausal
  Use vertically stripe causal contexts.
• pterm
  Use predictable termination.
• resetprob
  Reset the probability models after each coding pass.
• numgbits=n
  Set the number of guard bits to n.

JPC Decoder Options

The JPC decoder does not support any special options.

MIF Encoder Options

The MIF encoder does not support any special options.

MIF Decoder Options

The MIF decoder does not support any special options.

PNM Encoder Options

The following options are provided by the PNM encoder:

• text
  Use a non-raw (i.e., non-binary) flavor of PNM format.

PNM Decoder Options

The PNM decoder does not support any special options.

RAS Encoder Options

The RAS encoder does not support any special options.

RAS Decoder Options

The RAS decoder does not support any special options.

Examples

Suppose that we have an image stored in the PNM/PPM format in a file called lena.ppm. To encode this image (losslessly) in the JPEG-2000 JP2 format, and store the result in a file called lena.jp2, type:

• jasper --input lena.ppm --output lena.jp2 --output-format jp2

• jasper -f lena.ppm -F lena.jp2 -T jp2

Suppose that we have a RGB color image stored in the JPEG-2000 JP2 format in a file called lena.jp2. To encode this image in the PNM/PPM format, and store the result in a file called lena.ppm, type:

• jasper --input lena.jp2 --output lena.ppm --output-format pnm

• jasper -f lena.jp2 -F lena.ppm -T pnm

Suppose that we have an image stored in the BMP format in a file called lena.bmp. To encode this image in a lossy manner at 100:1 compression in the JPEG-2000 (code stream) format, and store the result in a file called lena_lossy.jpc, type:

• jasper -f lena.bmp -F lena_lossy.jpc -T jpc -O rate=0.01

Suppose that we have an image stored in a file called sachie.pnm in the PNM/PPM format, and we want to encode the image in the JPEG-2000 (code stream) format and store the result in a file named sachie_new.jpc. Further, suppose that we want the JPEG-2000 format to employ the following parameters:

• code blocks are 64 samples in width and 32 samples in height
• no multicomponent transform is to be employed
• 4 resolution levels should be employed for each component
• the compression is lossy at 64:1

• jasper -f sachie.pnm -F sachie_new.jpc -T jpc -O cblkwidth=64 -O cblkheight=32 -O nomct -O numrlvls=4 -O rate=0.015625

Return to the Table of Contents.

Synopsis

Description

Options

The following options are supported:

• -f file
  Read the primary (i.e., reference) image (for comparison purposes) from the file named file.
• -F file
  Read the secondary image (for comparison purposes) from the file named file.
• -m metric
  Use the difference metric specified by metric. The metric argument may assume one of the following values:
  • psnr .... peak signal to noise ratio
  • mse ..... mean squared error
  • rmse .... root mean squared error
  • pae ..... peak absolute error
  • mae ..... mean absolute error
  • equal ... equality (boolean)

The "-f" and "-F" options must always be specified. There is currently no way to explicitly specify the format of the images. If the format of either image cannot be autodetected, the command will exit with an error.

Examples

Suppose that we have two slightly different versions of an image stored in files original.pgm and reconstructed.pgm. In order to calculate the difference between these images using the PSNR metric, type:

• imgcmp -f original.pgm -F reconstructed.pgm -m psnr

Return to the Table of Contents.

Synopsis

Description

The imginfo command displays information about an image. This command is really only intended to be used from shell scripts for testing purposes.

Return to the Table of Contents.

If you are unfortunate enough to encounter any problems with JasPer, please submit a bug report. In order to ensure that we are able to properly process your bug report, always ensure that it includes the following information:

• The version of JasPer in which the problem was found.
• The details of the run-time system (i.e., operating system)
• The compiler that you are using (i.e., vendor, version number).
• The command line options used when the problem was observed.
• Indicate whether or not the problem is reproducible. If the problem is reproducible, indicate the exact steps required to reproduce the problem.
• A description of the problem that you are experiencing.

Return to the Table of Contents.

For more information about the JasPer software, please visit the following web pages:

• JasPer Project Home Page.
• Image Power Home Page.
• JasPer Project Mailing List Home Page. By joining this group, one can easily obtain new information about the JasPer Project in a timely fashion. The associated mailing list is used to announce new releases of the software and disseminate other important information about JasPer.

Return to the Table of Contents.

The JasPer software is named, in part, after Jasper National Park, the largest national park in the Canadian Rockies with 10,878 square kilometres of mountain wilderness. As it happens, jasper is also the name of an opaque cryptocrystalline variety of quartz used for ornamentation or as a gemstone. Hence, the implication that the software is robust (i.e., solid as a rock) and precious (i.e., like a gemstone). Lastly, the name "jasper" was also chosen because it contains a letter "J" followed subsequently by a letter "P", not unlike the abbreviation "JP" that is currently associated with the emerging JPEG-2000 standard.

Return to the Table of Contents.