EVOLUTION-MANAGER

Edit File: frmt_jp2kak.html

<html>
<head>
<title>JP2KAK -- JPEG-2000 (based on Kakadu)</title>
</head>

<h1>JP2KAK -- JPEG-2000 (based on Kakadu)</h1>

Most forms of JPEG2000 JP2 and JPC compressed images (ISO/IEC 15444-1) can be
read with GDAL using a driver based on the Kakadu library.  As well, new images
can be written.  Existing images cannot be updated in place.<p>

The JPEG2000 file format supports lossy and lossless compression of
8bit and 16bit images with 1 or more bands (components).  Via the
<a href="https://web.archive.org/web/20151028081930/http://www.lizardtech.com/download/geo/geotiff_box.txt">GeoJP2 (tm)</a> mechanism,
GeoTIFF style coordinate system and georeferencing information can be embedded
within the JP2 file.  JPEG2000 files use a substantially different format and
compression mechanism than the traditional JPEG compression and JPEG JFIF
format.  They are distinct compression mechanisms produced by the same
group.  JPEG2000 is based on wavelet compression.<p>

The JPEG2000 driver documented on this page (the JP2KAK driver) is implemented
on top of the proprietary <a href="http://www.kakadusoftware.com/">Kakadu</a>
library.  This is a high quality and high performance JPEG2000 library in wide
used in the geospatial and general imaging community.  However, it is not free,
and so normally builds of GDAL from source will not include support for this
driver unless the builder purchases a license for the library and configures
accordingly.  GDAL includes <a href="frmt_jpeg2000.html">another JPEG2000 driver</a>
based on the free JasPer library.<p>

When reading images this driver will represent the bands as being
Byte (8bit unsigned), 16 bit signed or 16 bit unsigned.  Georeferencing
and coordinate system information will be available if the file is a
GeoJP2 (tm) file.  Files color encoded in YCbCr color space will be
automatically translated to RGB.  Paletted images are also supported.<P>

Starting with GDAL 1.9.0, XMP metadata can be extracted from JPEG2000 files, and will be
stored as XML raw content in the xml:XMP metadata domain.<p>

<h2>Configuration Options</h2>

The JP2KAK driver supports the following
<a href="http://trac.osgeo.org/gdal/wiki/ConfigOptions">Config Options</a>.
These runtime options can be used to alter the behavior of the driver.

<ul>
<li> <b>JP2KAK_THREADS</b>=n: By default an effort is made to take advantage of
multi-threading on multi-core computers using default rules from the Kakadu
library.  This option may be set to a value of zero to avoid using additional
threads or to a specific count to create the requested number of worker threads.<p>

<li> <b>JP2KAK_FUSSY</b>=YES/NO: This can be set to YES to turn on fussy reporting
of problems with the JPEG2000 data stream.  Defaults to NO.<p>

<li> <b>JP2KAK_RESILIENT</b>=YES/NO: This can be set to YES to force Kakadu to
maximize resilience with incorrectly created JPEG2000 data files, likely at
some cost in performance.  This is likely to be necessary if, among other reasons,
you get an error message about "Expected to find EPH marker following packet header"
or error reports indicating the need to run with the resilient and sequential flags
on.  Defaults to NO.<p>

</ul>

<h2><a name="georeferencing">Georeferencing</a></h2>

<p>
Georeferencing information can come from different sources : internal (GeoJP2
or GMLJP2 boxes), worldfile .j2w/.wld sidecar files, or PAM (Persitant Auxiliary metadata)
.aux.xml sidecar files.
By default, information is fetched in following order (first listed is the most
prioritary): PAM, GeoJP2, GMLJP2, WORLDFILE.
</p>
<p>Starting with GDAL 2.2, the allowed sources
and their priority order can be changed with the GDAL_GEOREF_SOURCES
configuration option (or GEOREF_SOURCES open option) whose value is a
comma-separated list of the following keywords :
PAM, GEOJP2, GMLJP2, INTERNAL (shortcut for GEOJP2,GMLJP2), WORLDFILE, NONE.
First mentioned sources are the most prioritary over the next ones. A non mentioned
source will be ignored.
</p>
<p>
For example setting it to "WORLDFILE,PAM,INTERNAL" will make a geotransformation
matrix from a potential worldfile prioritary over PAM or internal JP2 boxes.
Setting it to "PAM,WORLDFILE,GEOJP2" will use the mentioned sources and
ignore GMLJP2 boxes.
</p>

<h2>Option Options</h2>

(GDAL &gt;= 2.0 )

The following open option is available:
<ul>
<li><p><b>1BIT_ALPHA_PROMOTION=YES/NO</b>: Whether a 1-bit alpha channel should be promoted to 8-bit.
Defaults to YES.</li>
<li><p><b>GEOREF_SOURCES=string</b>: (GDAL &gt; 2.2) Define which georeferencing sources are
allowed and their priority order. See <a href="#georeferencing"><i>Georeferencing</i></a> paragraph.</li>
</ul>

<h2>Creation Issues</h2>

JPEG2000 files can only be created using the CreateCopy mechanism to
copy from an existing dataset.<p>

JPEG2000 overviews are maintained as part of the mathematical description of
the image.  Overviews cannot be built as a separate process, but on read the
image will generally be represented as having overview levels at various
power of two factors.<p>

Creation Options:<p>

<ul>

<li> <b>CODEC=JP2/J2K</b> Codec to use. If not specified, guess based on
file extension. If unknown, default to JP2</li> <p>

<li> <b>QUALITY=n</b>: Set the compressed size ratio as a percentage
of the size of the uncompressed image.  The default is 20 indicating that
the resulting image should be 20% of the size of the uncompressed image.
Actual final image size may not exactly match that requested depending on
various factors. A value of 100 will result in use of the lossless compression
algorithm . On typical image data, if you specify a value greater than 65, it
might be worth trying with QUALITY=100 instead as lossless compression might
produce better compression than lossy compression. <P>

<li> <b>BLOCKXSIZE=n</b>: Set the tile width to use.  Defaults to 20000.
<p>

<li> <b>BLOCKYSIZE=n</b>: Set the tile height to use.  Defaults to image height.
<p>

<li> <b>FLUSH=TRUE/FALSE</b>: Enable/Disable incremental flushing when writing files.  Required to be FALSE for RLPC and LRPC Corder.  May use a lot of memory when FALSE while writing large images.  Defaults to TRUE.
<p>

<li> <b>GMLJP2=YES/NO</b>: Indicates whether a GML box
conforming to the OGC GML in JPEG2000 specification should be included in the
file. Unless GMLJP2V2_DEF is used, the version of the GMLJP2 box will be
version 1. Defaults to YES.<p>

<li> <b>GMLJP2V2_DEF=filename</b>: (Starting with GDAL 2.0) Indicates whether a GML box
conforming to the <a href="http://docs.opengeospatial.org/is/08-085r4/08-085r4.html">
OGC GML in JPEG2000, version 2</a> specification should be included in the
file. <i>filename</i> must point to a file with a JSon content that defines how
the GMLJP2 v2 box should be built. See <a href="frmt_jp2openjpeg.html#GMLJP2v2Def">
GMLJP2v2 definition file section</a> in documentation of the JP2OpenJPEG driver
for the syntax of the JSon configuration file.
It is also possible to directly pass the JSon content inlined as a string.
If filename is just set to YES, a minimal instance will be built.<p>

<li> <b>GeoJP2=YES/NO</b>: Indicates whether a UUID/GeoTIFF box conforming to the GeoJP2 (GeoTIFF in JPEG2000) specification should be included in the file.  Defaults to YES.<p>

<li> <b>LAYERS=n</b>: Control the number of layers produced.  These are
sort of like resolution layers, but not exactly.  The default value is
12 and this works well in most situations.<p>

<li> <b>ROI=xoff,yoff,xsize,ysize</b>: Selects a region to be a region of
interest to process with higher data quality.  The various "R" flags below may
be used to control the amount better.  For example the settings
"ROI=0,0,100,100", "Rweight=7" would encode the top left 100x100 area of
the image with considerable higher quality compared to the rest of the image.
<p>

</ul>

The following creation options are tightly tied to the Kakadu library, and
are considered to be for advanced use only.  Consult Kakadu documentation
to better understand their meaning.<p>

<ul>
<li> <b>Corder</b>: Defaults to "PRCL".
<li> <b>Cprecincts</b>: Defaults to "{512,512},{256,512},{128,512},{64,512},{32,512},{16,512},{8,512},{4,512},{2,512}".
<li> <b>ORGgen_plt</b>: Defaults to "yes".
<li> <b>Cmodes</b>: Kakadu library default used.
<li> <b>Clevels</b>: Kakadu library default used.
<li> <b>Rshift</b>: Kakadu library default used.
<li> <b>Rlevels</b>: Kakadu library default used.
<li> <b>Rweight</b>: Kakadu library default used.
</ul>

<h2>Known Kakadu Issues</h2>

<h3>Alpha Channel Writing in v7.8</h3>

Kakadu v7.8 has a bug in jp2_channels::set_opacity_mapping that can
cause an error when writing images with an alpha channel.  Please
upgrade to version 7.9.

<pre>
Error: GdalIO: Error in Kakadu File Format Support: Attempting to
create a Component Mapping (cmap) box, one of whose channels refers to
a non-existent image component or palette lookup table. (code = 1)
</pre>

<h3>kdu_get_num_processors always returns 0 for some platforms</h3>

On non-windows / non-mac installs (e.g. Linux), Kakadu might not
include unistd.h in kdu_arch.cpp.  This means that
_SC_NPROCESSORS_ONLN and _SC_NPROCESSORS_CONF are not defined and
kdu_get_num_processors will always return 0.  Therefore the jp2kak
driver might not default to creating worker threads.

<ul>

<li> Implemented as <tt>gdal/frmts/jp2kak/jp2kakdataset.cpp</tt>. </li>

<li> If you're using a Kakadu release before v7.5, configure &amp; compile GDAL with eg. <code>CXXFLAGS="-DKDU_MAJOR_VERSION=7 -DKDU_MINOR_VERSION=3 -DKDU_PATCH_VERSION=2"</code> for Kakadu version 7.3.2.</li>

<li> Alternate <a href="frmt_jpeg2000.html">JPEG2000 driver</a>.</li>

</ul>

</body>
</html>