s = image_name.getExif(tag_name ‖ hashmap_nameʃ, values_for_displayʅ);
The
Image.getExif function queries the
EXIF data stored by an image held by the
Image object. EXIF data used by some image formats, primarily JPEG images, can include information about the device that took the photo, when the photo was taken, and the location—in GPS coordinates—where the photo was captured.
EXIF data is stored as a mapping of tags to values, each stored in an Image File Directory (IFD) set. Values can be stored as strings or numbers, and when querying EXIF data, the raw value, potentially converted to a string, is returned. More information about EXIF data is available in the technical guide "
Exchangeable Image File format for Digital Still Cameras."
The
Image.getExif function can be used to query a single value by providing a string expression,
tag_name. Each IFD is searched for a tag with the
given name, and the first non-blank value is returned. If the EXIF data does not contain a value for a valid tag, a blank string is returned. If the tag name is invalid, an error message is displayed and a blank string is returned. See the
EXIF Tags page for a list of valid tag names.
The
Image.getExif function can also be used to query all EXIF data by providing one-dimensional string
HashMap. The HashMap's keys will contain the tag name for each EXIF data, with the key's value corresponding to the EXIF value.
If the optional conditional expression
values_for_display evaluates to
true, a value suitable for displaying to a user is returned. The text used for display values is available by viewing code, including
exif-entry.c, that is part of
libexif, the library that CSPro uses to parse EXIF data.
Some useful EXIF data is stored in a format that can be challenging to parse. CSPro provides several custom tag names, starting with CSPro:, to simplify querying this data:
| Tag Name | Calculated Value | Source Tags |
|---|
| CSPro:TimestampOriginal | The UNIX time when the picture was recorded. This value is only defined when the EXIF data contains time zone information. | DateTimeOriginal
OffsetTimeOriginal
SubSecTimeOriginal (optional) |
| CSPro:GPSLatitude | The latitude, represented as a decimal value, as captured by the device's GPS receiver or location services. | GPSLatitudeRef
GPSLatitude |
| CSPro:GPSLongitude | The longitude, represented as a decimal value, as captured by the device's GPS receiver or location services. | GPSLongitudeRef
GPSLongitude |
These calculated values are not included in the tags when using this function with a HashMap.
The tag names for some EXIF data are used by multiple IFD sets. In the rare chance that this occurs in images that you are trying to process, you can use the name of an IDF set, followed by a colon, to specify which IFD should be searched.
| IFD Prefix | Image File Directory | Example Use |
|---|
| 0: | Primary Image | 0:Make |
| 1: | Thumbnail Image | 1:JPEGInterchangeFormat |
| EXIF: | Extended Information | EXIF:ISOSpeed |
| GPS: | Geolocation Data | GPS:GPSAltitude |
| Interoperability: | Interoperability Information | Interoperability:InteroperabilityIndex |
The function returns a string containing the value associated with the provided tag, or a blank string when used with a HashMap. If the Image object does not contain an image or if the tag name is invalid, a blank string is returned.
Image concert_image; // ...
concert_image.getExif("Make"); // "NIKON"
concert_image.getExif("Model"); // "COOLPIX S8100" Image enumerator_image; // ...
HashMap string exif_values;
enumerator_image.getExif(exif_values);
exif_values("BrightnessValue"); // "7.97 EV (859.07 cd/m^2)"
exif_values("ShutterSpeedValue"); // "10.60 EV (1/1552 sec.)" This shows examples of the CSPro-prefixed tags as well as the raw values that are used in the calculation:
Image hawk_image; // ...
tonumber(hawk_image.getExif("CSPro:TimestampOriginal")); // 1746544676.195
hawk_image.getExif("DateTimeOriginal"); // "2025:05:06 11:17:56"
hawk_image.getExif("OffsetTimeOriginal"); // "-04:00"
hawk_image.getExif("SubSecTimeOriginal"); // "195"
tonumber(hawk_image.getExif("CSPro:GPSLatitude")); // 38.847222
hawk_image.getExif("GPSLatitudeRef"); // "N"
hawk_image.getExif("GPSLatitude"); // "38, 50, 50.57"
tonumber(hawk_image.getExif("CSPro:GPSLongitude")); // -76.93
hawk_image.getExif("GPSLongitudeRef"); // "W"
hawk_image.getExif("GPSLongitude"); // "76, 55, 48.41" Image roof_image; // ...
roof_image.getExif("Flash"); // "16"
roof_image.getExif("Flash", false); // "16"
roof_image.getExif("Flash", true); // "Flash did not fire, compulsory flash mode"