.. _raster.jpeg2000:

================================================================================
JPEG2000 -- Implementation of the JPEG-2000 part 1
================================================================================

.. shortname:: JPEG2000

.. build_dependencies:: libjasper

This implementation based on JasPer software (see below).

XMP metadata can be extracted from JPEG2000
files, and will be stored as XML raw content in the xml:XMP metadata
domain.

Driver capabilities
-------------------

.. supports_createcopy::

.. supports_georeferencing::

.. supports_virtualio::

Georeferencing
--------------

Georeferencing information can come from different sources : internal
(GeoJP2 or GMLJP2 boxes), worldfile .j2w/.wld sidecar files, or PAM
(Persistent 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:

-  **1BIT_ALPHA_PROMOTION=YES/NO**: Whether a 1-bit alpha channel should
   be promoted to 8-bit. Defaults to YES.

-  **GEOREF_SOURCES=string**: (GDAL > 2.2) Define which georeferencing
   sources are allowed and their priority order. See
   `Georeferencing <#georeferencing>`__ paragraph.

Creation Options
----------------

-  **WORLDFILE=ON**: Force the generation of an associated ESRI world
   file (.wld).
-  **FORMAT=JP2|JPC**: Specify output file format.
-  **GMLJP2=YES/NO**: (Starting with GDAL 2.0) 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. As implemented currently, the GMLJP2
   box will be written after the codestream. Defaults to YES.
-  **GMLJP2V2_DEF=filename**: (Starting with GDAL 2.0) Indicates whether
   a GML box conforming to the `OGC GML in JPEG2000, version
   2 <http://docs.opengeospatial.org/is/08-085r4/08-085r4.html>`__
   specification should be included in the file. *filename* must point
   to a file with a JSon content that defines how the GMLJP2 v2 box
   should be built. See :ref:`GMLJP2v2 definition file
   section <gmjp2v2def>` 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. As implemented currently, the GMLJP2 box will be written after
   the codestream.
-  **GeoJP2=YES/NO**: (Option starting with GDAL 2.0, but already
   enabled in previous versions. Require a modified Jasper with GeoJP2
   support enabled) Indicates whether a UUID/GeoTIFF box conforming to
   the GeoJP2 (GeoTIFF in JPEG2000) specification should be included in
   the file. Defaults to YES.
-  **NBITS=int_value** : (GDAL >= 2.3) Bits (precision) for sub-byte
   files (1-7), sub-uint16 (9-15).

-  Encoding parameters, directly delivered to the JasPer library
   described in the JasPer documentation. Quoted from the docs:

   \``The following options are supported by the 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:     |                       |
   |                       | ===== ============    |                       |
   |                       | Value Description     |                       |
   |                       | ===== ============    |                       |
   |                       | 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=[, ,. . . , | 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:               |                       |
   |                       | ===== =============== |                       |
   |                       | ===================== |                       |
   |                       | ===================== |                       |
   |                       | ===================== |                       |
   |                       | ====                  |                       |
   |                       | Value Description     |                       |
   |                       | ===== =============== |                       |
   |                       | ===================== |                       |
   |                       | ===================== |                       |
   |                       | ===================== |                       |
   |                       | ====                  |                       |
   |                       | lrcp  layer-resolutio |                       |
   |                       | n-component-position  |                       |
   |                       | (LRCP) progressive (i |                       |
   |                       | .e., rate scalable)   |                       |
   |                       | rlcp  resolution-laye |                       |
   |                       | r-component-position  |                       |
   |                       | (RLCP) progressive (i |                       |
   |                       | .e., resolution scala |                       |
   |                       | ble)                  |                       |
   |                       | rpcl  resolution-posi |                       |
   |                       | tion-component-layer  |                       |
   |                       | (RPCL) progressive    |                       |
   |                       | pcrl  position-compon |                       |
   |                       | ent-resolution-layer  |                       |
   |                       | (PCRL) progressive    |                       |
   |                       | cprl  component-posit |                       |
   |                       | ion-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      |                       |
   |                       | standard 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 6.   |                       |
   +-----------------------+-----------------------+-----------------------+
   | 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.''    |                       |
   +-----------------------+-----------------------+-----------------------+

See Also
--------

-  Implemented as ``gdal/frmts/jpeg2000/jpeg2000dataset.cpp``.
-  You need modified JasPer library to build this driver with GeoJP2
   support enabled. Modified version can be downloaded from
   `http://download.osgeo.org/gdal/jasper-1.900.1.uuid.tar.gz <http://download.osgeo.org/gdal/jasper-1.900.1.uuid.tar.gz>`__
-  `Official JPEG-2000 page <http://www.jpeg.org/JPEG2000.html>`__
-  `The JasPer Project Home
   Page <http://www.ece.uvic.ca/~mdadams/jasper/>`__

Other JPEG2000 GDAL drivers :

-  :ref:`JP2OpenJPEG: based on OpenJPEG library (open
   source) <raster.jp2openjpeg>`

-  :ref:`JP2ECW: based on Erdas ECW library
   (proprietary) <raster.jp2ecw>`

-  :ref:`JP2MRSID: based on LizardTech MrSID library
   (proprietary) <raster.jp2mrsid>`

-  :ref:`JP2KAK: based on Kakadu library (proprietary) <raster.jp2kak>`
