JP2OpenJPEG --- JPEG2000 driver based on OpenJPEG library

This driver is an implementation of a JPEG2000 reader/writer based on OpenJPEG library v2.

For GDAL 1.11 or later, use openjpeg 2.X. For GDAL 2.3, use openjpeg >= 2.1

The driver uses the VSI Virtual File API, so it can read JPEG2000 compressed NITF files.

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

The driver supports writing georeferencing information as GeoJP2 and GMLJP2 boxes.

Starting with GDAL 2.0, the driver supports creating files with transparency, arbitrary band count, and adding/reading metadata. Update of georeferencing or metadata of existing file is also supported. Optional intellectual property metdata can be read/written in the xml:IPR box.

Georeferencing

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.

Thread support

By default, if the JPEG2000 file has internal tiling, GDAL will try to decode several tiles in multiple threads if the RasterIO() request it receives intersect several tiles. This behaviour can be controlled with the GDAL_NUM_THREADS configuration option that defaults to ALL_CPUS in that context. In case RAM is limited, it can be needed to set this configuration option to 1 to disable multi-threading

Starting with OpenJPEG 2.2.0, multi-threading decoding can also be enabld at the code-block level. This must be enabled with the OPJ_NUM_THREADS environment variable (note: this is a system environment variable, not a GDAL configuration option), which can be set to a numeric value or NUM_CPUS. Its default value is 1. Starting with GDAL 2.3, this multi-threading at code-block level is automatically enabled by GDAL

Both multi-threading mechanism can be combined together.

Option Options

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

Creation Options

Lossless compression

Lossless compression can be achieved if ALL the following creation options are defined :

GMLJP2v2 definition file

A GMLJP2v2 box typically contains a GMLJP2RectifiedGridCoverage with the SRS information and geotransformation matrix. It is also possible to add metadata, vector features (GML feature collections), annotations (KML), styles (typically SLD, or other XML format) or any XML content as an extension. The value of the GMLJP2V2_DEF creation option should be a file that conforms with the below syntax (elements starting with "#" are documentation, and can be omitted): 
{
    "#doc" : "Unless otherwise specified, all elements are optional",

    "#root_instance_doc": "Describe content of the GMLJP2CoverageCollection",
    "root_instance": {
        "#gml_id_doc": "Specify GMLJP2CoverageCollection gml:id. Default is ID_GMLJP2_0",
        "gml_id": "some_gml_id",

        "#grid_coverage_file_doc": [
            "External XML file, whose root might be a GMLJP2GridCoverage, ",
            "GMLJP2RectifiedGridCoverage or a GMLJP2ReferenceableGridCoverage.",
            "If not specified, GDAL will auto-generate a GMLJP2RectifiedGridCoverage" ],
        "grid_coverage_file": "gmljp2gridcoverage.xml",

        "#grid_coverage_range_type_field_predefined_name_doc": [
            "New in GDAL 2.2",
            "One of Color, Elevation_meter or Panchromatic ",
            "to fill gmlcov:rangeType/swe:DataRecord/swe:field",
            "Only used if grid_coverage_file is not defined.",
            "Exclusive with grid_coverage_range_type_file" ],
        "grid_coverage_range_type_field_predefined_name": "Color",

        "#grid_coverage_range_type_file_doc": [
            "New in GDAL 2.2",
            "File that is XML content to put under gml:RectifiedGrid/gmlcov:rangeType",
            "Only used if grid_coverage_file is not defined.",
            "Exclusive with grid_coverage_range_type_field_predefined_name" ],
        "grid_coverage_range_type_file": "grid_coverage_range_type.xml",

        "#crs_url_doc": [
            "true for http://www.opengis.net/def/crs/EPSG/0/XXXX CRS URL.",
            "If false, use CRS URN. Default value is true",
            "Only taken into account for a auto-generated GMLJP2RectifiedGridCoverage"],
        "crs_url": true,

        "#metadata_doc": [ "An array of metadata items. Can be either strings, with ",
                           "a filename or directly inline XML content, or either ",
                           "a more complete description." ],
        "metadata": [

            "dcmetadata.xml",

            {
                "#file_doc": "Can use relative or absolute paths. Exclusive of content, gdal_metadata and generated_metadata.",
                "file": "dcmetadata.xml",

                "#gdal_metadata_doc": "Whether to serialize GDAL metadata as GDALMultiDomainMetadata",
                "gdal_metadata": false,

                "#dynamic_metadata_doc":
                    [ "The metadata file will be generated from a template and a source file.",
                      "The template is a valid GMLJP2 metadata XML tree with placeholders like",
                      "{{{XPATH(some_xpath_expression)}}}",
                      "that are evaluated from the source XML file. Typical use case",
                      "is to generate a gmljp2:eopMetadata from the XML metadata",
                      "provided by the image provider in their own particular format." ],
                "dynamic_metadata" :
                {
                    "template": "my_template.xml",
                    "source": "my_source.xml"
                },

                "#content": "Exclusive of file. Inline XML metadata content",
                "content": "<gmljp2:metadata>Some simple textual metadata</gmljp2:metadata>",

                "#parent_node": ["Where to put the metadata.",
                                 "Under CoverageCollection (default) or GridCoverage" ],
                "parent_node": "CoverageCollection"
            }
        ],

        "#annotations_doc": [ "An array of filenames, either directly KML files",
                              "or other vector files recognized by GDAL that ",
                              "will be translated on-the-fly as KML" ],
        "annotations": [
            "my.kml"
        ],

        "#gml_filelist_doc" :[
            "An array of GML files or vector files that will be on-the-fly converted",
            "to GML 3.2. Can be either GML filenames (or other OGR datasource names), ",
            "or a more complete description" ],
        "gml_filelist": [

            "my.gml",

            "my.shp",

            {
                "#file_doc": "OGR datasource. Can use relative or absolute paths. Exclusive of remote_resource",
                "file": "converted/test_0.gml",

                "#remote_resource_doc": "URL of a feature collection that must be referenced through a xlink:href",
                "remote_resource": "http://svn.osgeo.org/gdal/trunk/autotest/ogr/data/expected_gml_gml32.gml",

                "#namespace_doc": ["The namespace in schemaLocation for which to substitute",
                                  "its original schemaLocation with the one provided below.",
                                  "Ignored for a remote_resource"],
                "namespace": "http://example.com",

                "#schema_location_doc": ["Value of the substituted schemaLocation. ",
                                         "Typically a schema box label (link)",
                                         "Ignored for a remote_resource"],
                "schema_location": "gmljp2://xml/schema_0.xsd",

                "#inline_doc": [
                    "Whether to inline the content, or put it in a separate xml box. Default is true",
                    "Ignored for a remote_resource." ],
                "inline": true,

                "#parent_node": ["Where to put the FeatureCollection.",
                                 "Under CoverageCollection (default) or GridCoverage" ],
                "parent_node": "CoverageCollection"
            }
        ],


        "#styles_doc": [ "An array of styles. For example SLD files" ],
        "styles" : [
            {
                "#file_doc": "Can use relative or absolute paths.",
                "file": "my.sld",

                "#parent_node": ["Where to put the FeatureCollection.",
                                 "Under CoverageCollection (default) or GridCoverage" ],
                "parent_node": "CoverageCollection"
            }
        ],

        "#extensions_doc": [ "An array of extensions." ],
        "extensions" : [
            {
                "#file_doc": "Can use relative or absolute paths.",
                "file": "my.xml",

                "#parent_node": ["Where to put the FeatureCollection.",
                                 "Under CoverageCollection (default) or GridCoverage" ],
                "parent_node": "CoverageCollection"
            }
        ]
    },

    "#boxes_doc": "An array to describe the content of XML asoc boxes",
    "boxes": [
        {
            "#file_doc": "can use relative or absolute paths. Required",
            "file": "converted/test_0.xsd",

            "#label_doc": ["the label of the XML box. If not specified, will be the ",
                          "filename without the directory part." ],
            "label": "schema_0.xsd"
        }
    ]
}

Metadata can be dynamically generated from a template file (in that context, with a XML structure) and a XML source file. The template file is processed by searching for patterns like {{{XPATH(xpath_expr)}}} and replacing them by their evaluation against the content of the source file. xpath_expr must be a XPath 1.0 compatible expression, with the addition of the following functions :

A template file to process XML metadata of Pleiades imagery can be found here, and a template file to process XML metadata of GeoEye/WorldView imagery can be found here.

Vector information

Starting with GDAL 2.0, a JPEG2000 file containing a GMLJP2 v2 box with GML feature collections and/or KML annotations embedded can be opened as a vector file with the OGR API. For example: 
ogrinfo -ro my.jp2

INFO: Open of my.jp2'
      using driver `JP2OpenJPEG' successful.
1: FC_GridCoverage_1_rivers (LineString)
2: FC_GridCoverage_1_borders (LineString)
3: Annotation_1_poly

Feature collections can be linked from the GMLJP2 v2 box to a remote location. By default, the link is not followed. It will be followed if the open option OPEN_REMOTE_GML is set to YES.

See Also:

Other JPEG2000 GDAL drivers :