.. _raster.jpeg2000:

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

.. shortname:: JPEG2000

.. build_dependencies:: libjasper

.. deprecated_driver:: version_targeted_for_removal: 3.5
   env_variable: GDAL_ENABLE_DEPRECATED_DRIVER_JPEG2000
   message: You should consider using another driver, in particular the JP2OpenJPEG driver that is a better free and open source alternative.

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

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**: 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**: 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**: 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>`
