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 the GDAL_ERROR_ON_LIBJPEG_WARNING configuration 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.

EXIF and GPS tags

The below tables list the EXIF and GPS tags that can be written.

  • The "Metadata item name" column presents the name of the metadata item to attach to the source dataset.

  • The "Hex code" column is the value of the corresponding TIFF EXIF/GPS tag (for reference only)

  • The "Type" column is the TIFF type associated.
    • ASCII is for text values that are NUL-terminated (for a fixed length tag, the length includes this NUL-terminating characters). e.g EXIF_Make=the_make

    • BYTE/UNDEFINED is for values that can be made of any byte value. The value of the corresponding GDAL metadata item must be a string of hexadecimal formatted values, e.g EXIF_GPSVersionID=0x02 0x00 0x00 0x00. GDAL also accepts an ASCII string: e.g. EXIF_ExifVersion=0231

    • SHORT is for unsigned integer values in the range [0,65535]. Some tags may accept multiple values, in which case they must be separated by space.

    • LONG is for unsigned integer values in the range [0,4294967295]. Some tags may accept multiple values, in which case they must be separated by space.

    • RATIONAL is for positive floating-point values. Some tags may accept multiple values, in which case they must be separated by space. e.g EXIF_GPSLatitude=49 2 3.5

    • SRATIONAL is for positive or negative floating-point values. Some tags may accept multiple values, in which case they must be separated by space.

    When an item accepts a fixed number of values and that more are provided, they will be truncated with a warning. In the case they are less values provided than needed, they will be padded with appropriate spaces / zeroes

  • The "Number of values" column is the number of values for the item. Might be "variable" if there is no restriction, or a fixed value. For Type=ASCII, the fixed value includes the NUL-terminating byte, so the number of actual printable characters is number of values - 1.

  • The "Optionality" column indicates whether the item should be present ("Mandatory"), is "Recommended" or "Optional". GDAL does not enforce this.

Many items have more restrictions on the valid content that are not expressed in the below tables. Consult the EXIF specification for more information.

Metadata item name

Hex code

Type

Number of values

Optionality

EXIF_Document_Name

0x010D

ASCII

variable

Optional

EXIF_ImageDescription

0x010E

ASCII

variable

Recommended

EXIF_Make

0x010F

ASCII

variable

Recommended

EXIF_Model

0x0110

ASCII

variable

Recommended

EXIF_Orientation

0x0112

SHORT

1

Recommended

EXIF_XResolution

0x011A

RATIONAL

1

Mandatory

EXIF_YResolution

0x011B

RATIONAL

1

Mandatory

EXIF_ResolutionUnit

0x0128

SHORT

1

Mandatory

EXIF_TransferFunction

0x012D

SHORT

768

Optional

EXIF_Software

0x0131

ASCII

variable

Optional

EXIF_DateTime

0x0132

ASCII

20

Recommended

EXIF_Artist

0x013B

ASCII

variable

Optional

EXIF_WhitePoint

0x013E

RATIONAL

2

Optional

EXIF_PrimaryChromaticities

0x013F

RATIONAL

6

Optional

EXIF_YCbCrCoefficients

0x0211

RATIONAL

3

Optional

EXIF_YCbCrPositioning

0x0213

SHORT

1

Mandatory

EXIF_ReferenceBlackWhite

0x0214

RATIONAL

6

Optional

EXIF_Copyright

0x8298

ASCII

variable

Optional

EXIF_ExposureTime

0x829A

RATIONAL

1

Recommended

EXIF_FNumber

0x829D

RATIONAL

1

Optional

EXIF_ExposureProgram

0x8822

SHORT

1

Optional

EXIF_SpectralSensitivity

0x8824

ASCII

variable

Optional

EXIF_ISOSpeedRatings

0x8827

SHORT

variable

Optional

EXIF_OECF

0x8828

UNDEFINED

variable

Optional

EXIF_SensitivityType

0x8830

SHORT

1

Optional

EXIF_StandardOutputSensitivity

0x8831

LONG

1

Optional

EXIF_RecommendedExposureIndex

0x8832

LONG

1

Optional

EXIF_ISOSpeed

0x8833

LONG

1

Optional

EXIF_ISOSpeedLatitudeyyy

0x8834

LONG

1

Optional

EXIF_ISOSpeedLatitudezzz

0x8835

LONG

1

Optional

EXIF_ExifVersion

0x9000

UNDEFINED

4

Mandatory

EXIF_DateTimeOriginal

0x9003

ASCII

20

Optional

EXIF_DateTimeDigitized

0x9004

ASCII

20

Optional

EXIF_OffsetTime

0x9010

ASCII

7

Optional

EXIF_OffsetTimeOriginal

0x9011

ASCII

7

Optional

EXIF_OffsetTimeDigitized

0x9012

ASCII

7

Optional

EXIF_ComponentsConfiguration

0x9101

UNDEFINED

4

Mandatory

EXIF_CompressedBitsPerPixel

0x9102

RATIONAL

1

Optional

EXIF_ShutterSpeedValue

0x9201

SRATIONAL

1

Optional

EXIF_ApertureValue

0x9202

RATIONAL

1

Optional

EXIF_BrightnessValue

0x9203

SRATIONAL

1

Optional

EXIF_ExposureBiasValue

0x9204

SRATIONAL

1

Optional

EXIF_MaxApertureValue

0x9205

RATIONAL

1

Optional

EXIF_SubjectDistance

0x9206

RATIONAL

1

Optional

EXIF_MeteringMode

0x9207

SHORT

1

Optional

EXIF_LightSource

0x9208

SHORT

1

Optional

EXIF_Flash

0x9209

SHORT

1

Recommended

EXIF_FocalLength

0x920A

RATIONAL

1

Optional

EXIF_SubjectArea

0x9214

SHORT

variable

Optional

EXIF_MakerNote

0x927C

UNDEFINED

variable

Optional

EXIF_UserComment

0x9286

UNDEFINED

variable

Optional

EXIF_SubSecTime

0x9290

ASCII

variable

Optional

EXIF_SubSecTime_Original

0x9291

ASCII

variable

Optional

EXIF_SubSecTime_Digitized

0x9292

ASCII

variable

Optional

EXIF_FlashpixVersion

0xA000

UNDEFINED

4

Mandatory

EXIF_ColorSpace

0xA001

SHORT

1

Mandatory

EXIF_PixelXDimension

0xA002

LONG

1

Mandatory

EXIF_PixelYDimension

0xA003

LONG

1

Mandatory

EXIF_RelatedSoundFile

0xA004

ASCII

13

Optional

EXIF_FlashEnergy

0xA20B

RATIONAL

1

Optional

EXIF_SpatialFrequencyResponse

0xA20C

UNDEFINED

variable

Optional

EXIF_FocalPlaneXResolution

0xA20E

RATIONAL

1

Optional

EXIF_FocalPlaneYResolution

0xA20F

RATIONAL

1

Optional

EXIF_FocalPlaneResolutionUnit

0xA210

SHORT

1

Optional

EXIF_SubjectLocation

0xA214

SHORT

2

Optional

EXIF_ExposureIndex

0xA215

RATIONAL

1

Optional

EXIF_SensingMethod

0xA217

SHORT

1

Optional

EXIF_FileSource

0xA300

UNDEFINED

1

Optional

EXIF_SceneType

0xA301

UNDEFINED

1

Optional

EXIF_CFAPattern

0xA302

UNDEFINED

variable

Optional

EXIF_CustomRendered

0xA401

SHORT

1

Optional

EXIF_ExposureMode

0xA402

SHORT

1

Recommended

EXIF_WhiteBalance

0xA403

SHORT

1

Recommended

EXIF_DigitalZoomRatio

0xA404

RATIONAL

1

Optional

EXIF_FocalLengthIn35mmFilm

0xA405

SHORT

1

Optional

EXIF_SceneCaptureType

0xA406

SHORT

1

Recommended

EXIF_GainControl

0xA407

RATIONAL

1

Optional

EXIF_Contrast

0xA408

SHORT

1

Optional

EXIF_Saturation

0xA409

SHORT

1

Optional

EXIF_Sharpness

0xA40A

SHORT

1

Optional

EXIF_DeviceSettingDescription

0xA40B

UNDEFINED

variable

Optional

EXIF_SubjectDistanceRange

0xA40C

SHORT

1

Optional

EXIF_ImageUniqueID

0xA420

ASCII

33

Optional

EXIF_CameraOwnerName

0xA430

ASCII

variable

Optional

EXIF_BodySerialNumber

0xA431

ASCII

variable

Optional

EXIF_LensSpecification

0xA432

RATIONAL

4

Optional

EXIF_LensMake

0xA433

ASCII

variable

Optional

EXIF_LensModel

0xA434

ASCII

variable

Optional

EXIF_LensSerialNumber

0xA435

ASCII

variable

Optional

GPS tags:

Metadata item name

Hex code

Type

Number of values

Optionality

EXIF_GPSVersionID

0x0000

BYTE

4

Optional

EXIF_GPSLatitudeRef

0x0001

ASCII

2

Optional

EXIF_GPSLatitude

0x0002

RATIONAL

3

Optional

EXIF_GPSLongitudeRef

0x0003

ASCII

2

Optional

EXIF_GPSLongitude

0x0004

RATIONAL

3

Optional

EXIF_GPSAltitudeRef

0x0005

BYTE

1

Optional

EXIF_GPSAltitude

0x0006

RATIONAL

1

Optional

EXIF_GPSTimeStamp

0x0007

RATIONAL

3

Optional

EXIF_GPSSatellites

0x0008

ASCII

variable

Optional

EXIF_GPSStatus

0x0009

ASCII

2

Optional

EXIF_GPSMeasureMode

0x000A

ASCII

2

Optional

EXIF_GPSDOP

0x000B

RATIONAL

1

Optional

EXIF_GPSSpeedRef

0x000C

ASCII

2

Optional

EXIF_GPSSpeed

0x000D

RATIONAL

1

Optional

EXIF_GPSTrackRef

0x000E

ASCII

2

Optional

EXIF_GPSTrack

0x000F

RATIONAL

1

Optional

EXIF_GPSImgDirectionRef

0x0010

ASCII

2

Optional

EXIF_GPSImgDirection

0x0011

RATIONAL

1

Optional

EXIF_GPSMapDatum

0x0012

ASCII

variable

Optional

EXIF_GPSDestLatitudeRef

0x0013

ASCII

2

Optional

EXIF_GPSDestLatitude

0x0014

RATIONAL

3

Optional

EXIF_GPSDestLongitudeRef

0x0015

ASCII

2

Optional

EXIF_GPSDestLongitude

0x0016

RATIONAL

3

Optional

EXIF_GPSDestBearingRef

0x0017

ASCII

2

Optional

EXIF_GPSDestBearing

0x0018

RATIONAL

1

Optional

EXIF_GPSDestDistanceRef

0x0019

ASCII

2

Optional

EXIF_GPSDestDistance

0x001A

RATIONAL

1

Optional

EXIF_GPSProcessingMethod

0x001B

UNDEFINED

variable

Optional

EXIF_GPSAreaInformation

0x001C

UNDEFINED

variable

Optional

EXIF_GPSDateStamp

0x001D

ASCII

11

Optional

EXIF_GPSDifferential

0x001E

SHORT

1

Optional

EXIF_GPSHPositioningError

0x001F

RATIONAL

1

Optional

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

See Also