JP2KAK -- JPEG-2000 (based on Kakadu)

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.

The JPEG2000 file format supports lossy and lossless compression of 8bit and 16bit images with 1 or more bands (components). Via the GeoJP2 (tm) 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.

The JPEG2000 driver documented on this page (the JP2KAK driver) is implemented on top of the proprietary Kakadu 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 another JPEG2000 driver based on the free JasPer library.

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.

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.

Configuration Options

The JP2KAK driver supports the following Config Options. These runtime options can be used to alter the behavior of the driver.


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.

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.

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.

Option Options

(GDAL >= 2.0 ) The following open option is available:

Creation Issues

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

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.

Creation Options:

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.

Known Kakadu Issues

Alpha Channel Writing in v7.8

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.
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)

kdu_get_num_processors always returns 0 for some platforms

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.

See Also: