JPEG -- JPEG JFIF File Format
Driver short name
JPEG
Build dependencies
(internal libjpeg provided)
The JPEG JFIF format is supported for reading, and batch writing, but not update in place. JPEG files are represented as one band (greyscale) or three band (RGB) datasets with Byte valued bands.
The driver will automatically convert images whose color space is YCbCr,
CMYK or YCbCrK to RGB, unless GDAL_JPEG_TO_RGB is set to NO (YES is the
default). When color space translation to RGB is done, the source color
space is indicated in the SOURCE_COLOR_SPACE metadata of the
IMAGE_STRUCTURE domain.
EXIF metadata can be read from JPEG files (but this will not result in a georeferenced image even if the EXIF_GPSLatitude and EXIF_GPSLongitude tags are set). But if an ESRI world file exists with the .jgw, .jpgw/.jpegw or .wld suffixes, it will be read and used to establish the geotransform for the image. If available a MapInfo .tab file will also be used for georeferencing. Overviews can be built for JPEG files as an external .ovr file.
The driver also supports the "zlib compressed mask appended to the file" approach used by a few data providers to add a bitmask to identify pixels that are not valid data. See RFC 15: Band Masks for further details.
The driver can deal with bitmask where the
bits are ordered with most significant bit first (whereas the usual
convention is least significant bit first). The driver will try to
autodetect that situation, but the heuristics may fail. In that
circumstance, you can set the JPEG_MASK_BIT_ORDER configuration option
to MSB. Bitmask can also be completely ignored by specifying
JPEG_READ_MASK=NO.
The GDAL JPEG Driver is built using the Independent JPEG Group's jpeg library. Also note that the GeoTIFF driver supports tiled TIFF with JPEG compressed tiles. This can be used to apply JPEG compression to datasets that exceed the maximum dimensions of 65,535x65,535 pixels for a single JPEG image.
It is also possible to use the JPEG driver with the libjpeg-turbo, a version of libjpeg, API and ABI compatible with IJG libjpeg-6b, which uses MMX, SSE, and SSE2 SIMD instructions to accelerate baseline JPEG compression/decompression.
Starting with GDAL 3.4, read and write support for JPEG images with 12-bit sample is enabled by default (if JPEG support is also enabled), using GDAL internal libjpeg (based on IJG libjpeg-6b, with additional changes for 12-bit sample support). Support for JPEG with 12-bit sample is independent of whether 8-bit JPEG support is enabled through internal IJG libjpeg-6b or external libjpeg (like libjpeg-turbo)
XMP metadata can be extracted from the file, and will be stored as XML raw content in the xml:XMP metadata domain.
Embedded EXIF thumbnails (with JPEG compression) can be used as overviews, and generated by GDAL.
Driver capabilities
Supports CreateCopy()
This driver supports the GDALDriver::CreateCopy() operation
Supports Georeferencing
This driver supports georeferencing
Supports VirtualIO
This driver supports virtual I/O operations (/vsimem/, etc.)
Color Profile Metadata
GDAL can deal with the following color profile metadata in the COLOR_PROFILE domain:
SOURCE_ICC_PROFILE (Base64 encoded ICC profile embedded in file.)
Note that this metadata property can only be used on the original raw pixel data. If automatic conversion to RGB has been done, the color profile information cannot be used.
This metadata tag can be used as creation options.
Configuration options
Configuration options can be specified in command-line tools using the syntax --config <NAME>=<VALUE> or using functions such as CPLSetConfigOption() (C) or gdal.config_options (Python).
The following configuration options are available :
GDAL_JPEG_TO_RGB=[YES/NO]: Whether CMYK JPEG images should be exposed as RGB.
JPEG_READ_MASK=[YES/NO]: Defaults to
YES. Whether to read the bitmask identifying pixels with valid data.JPEG_MASK_BIT_ORDER=[AUTO/LSB/MSB]: Defaults to
AUTO. Specifies if the mask is written with the least-significant bit (LSB) first, with the most-significant bit (MSB) first, or if GDAL should try and detect the bit order.GDAL_ERROR_ON_LIBJPEG_WARNING=[TRUE/FALSE]: Defaults to
FALSE. While decoding, libjpeg has resiliency towards some errors in the JPEG datastream and will try to recover from them as much of possible. Such errors will be reported as GDAL Warnings, but can optionally be considered as true Errors by setting theGDAL_ERROR_ON_LIBJPEG_WARNINGconfiguration option to TRUE.
Open Options
Open options can be specified in command-line tools using the syntax -oo <NAME>=<VALUE> or by providing the appropriate arguments to GDALOpenEx() (C) or gdal.OpenEx (Python).
The following open options are available:
USE_INTERNAL_OVERVIEWS=[YES/NO]: Defaults to
YES. Whether to use partial DCT decompression to generate overviews.APPLY_ORIENTATION=[YES/NO]: (GDAL >= 3.7) Defaults to
NO. Whether to use EXIF_Orientation metadata item to rotate/flip the image to apply scene orientation. Defaults to NO (that is the image will be returned in sensor orientation).
Creation Options
JPEG files are created using the "JPEG" driver code. Only Byte band types are supported.
Only 1 (greyscale), 3 band (input should be in RGB colorspace.
the driver will convert it automatically to YCbCr colorspace for storage, and
will expose it back as RGB on reading) or 4 band
(input should already by in CMYK colorspace. It will be exposed as RGB on reading
by default, unless the GDAL_JPEG_TO_RGB configuration option
is set to NO) configurations.
JPEG file creation is implemented by the batch (CreateCopy) method. YCbCrK colorspace is not supported in creation. If the source dataset has a nodata mask, it will be appended as a zlib compressed mask to the JPEG file.
Creation options can be specified in command-line tools using the syntax -co <NAME>=<VALUE> or by providing the appropriate arguments to GDALCreate() (C) or Driver.Create (Python).
The following creation options are supported:
WORLDFILE=YES: Force the generation of an associated ESRI world file (with the extension .wld). See World Files section for details.
QUALITY=1-100: Defaults to
75. Set the JPEG quality.Low values result in higher compression ratios, but poorer image quality with strong blocking artifacts. Values above 95 are not meaningfully better quality but can be substantially larger.
LOSSLESS_COPY=[AUTO/YES/NO]: (GDAL >= 3.7) Defaults to
AUTO. Whether conversion should be lossless. In AUTO or YES mode, if LOSSLESS=YES and the source dataset uses JPEG compression, or JPEGXL compression with a JPEG reconstruction box, lossless recoding from it is done. If set to NO, or in AUTO mode and the source is not compatible of lossless transcoding, the regular conversion code path is taken.PROGRESSIVE=ON: Enabled generation of progressive JPEGs. In some cases these will display a reduced resolution image in viewers such as Netscape, and Internet Explorer, before the full file has been downloaded. However, some applications cannot read progressive JPEGs at all. GDAL can read progressive JPEGs, but takes no advantage of their progressive nature.
INTERNAL_MASK=[YES/NO]: By default, if needed, an internal mask in the "zlib compressed mask appended to the file" approach is written to identify pixels that are not valid data. This can be disabled by setting this option to NO.
ARITHMETIC=[YES/NO]: To enable arithmetic coding. Not enabled in all libjpeg builds, because of possible legal restrictions.
BLOCK=1-16: Defaults to
8. (libjpeg >= 8c) DCT block size. All values from 1 to 16 are possible. Default is 8 (baseline format). A value other than 8 will produce files incompatible with versions prior to libjpeg 8c.COLOR_TRANSFORM=[RGB/RGB1]: (libjpeg >= 9). Set to RGB1 for lossless RGB. Note: this will produce files incompatible with versions prior to libjpeg 9.
SOURCE_ICC_PROFILE=value: ICC profile encoded in Base64.
COMMENT=value: String to embed in a comment JPEG marker. When reading, such strings are exposed in the COMMENT metadata item.
EXIF_THUMBNAIL=[YES/NO]: Defaults to
NO. Whether to generate an EXIF thumbnail(overview), itself JPEG compressed. If enabled, the maximum dimension of the thumbnail will be 128, if neither THUMBNAIL_WIDTH nor THUMBNAIL_HEIGHT are specified.THUMBNAIL_WIDTH=value: Width of thumbnail. Only taken into account if
EXIF_THUMBNAIL=YES.THUMBNAIL_HEIGHT=value: Height of thumbnail. Only taken into account if
EXIF_THUMBNAIL=YES.WRITE_EXIF_METADATA=[YES/NO]: Defaults to
YES. Whether to write EXIF_xxxx metadata items in a EXIF segment.
FLIR metadata
Added in version 3.3.
Metadata encoded according to the FLIR convention (infrared images) is available
in the FLIR metadata domain.
Metadata from the following sections is supported:
Header
RawData
CameraInfo
PaletteInfo
GPSInfo
Consult https://exiftool.org/TagNames/FLIR.html for details.
The thermal image data, stored either as raw data or in PNG, is exposed as a
GDAL subdataset whose name is JPEG:"filename.jpg":FLIR_RAW_THERMAL_IMAGE