ZPB-EXIF - access to digital image Exif data for Common Lisp

Abstract

Exif is a standard for embedding information in an image file created by a digital camera. ZPB-EXIF is a library that makes Exif data accessible to Common Lisp programs. It is available under a BSD-like license. For more info about Exif, see Exif.org. The latest version is 1.2.4, released on June 3rd, 2020.

Download shortcut: http://www.xach.com/lisp/zpb-exif.tgz

Contents

  1. Overview
  2. Example
  3. Terms
  4. The ZPB-EXIF Dictionary
    1. make-exif
    2. exif-value
    3. parsed-exif-value
    4. exif-alist
    5. ifd-alist
    6. ifd-entry
    7. entry-value
    8. parsed-entry-value
    9. image-ifd
    10. exif-ifd
    11. gps-ifd
    12. interoperability-ifd
    13. thumbnail-ifd
    14. exif-data
    15. thumbnail-image
    16. invalid-stream
    17. invalid-jpeg-stream
    18. invalid-exif-stream
  5. Parsed Values
    1. Image IFD
    2. Exif IFD
  6. Feedback

Overview

Exif data is structured like so:

ZPB-EXIF provides access to key/value lookup through an object created from an Exif file or stream. It provides quick access to image, Exif, and GPS IFD values, and indirect access to other IFDs and their key/value entries.

Example

> (defparameter *exif* (make-exif #p"gg_gps.jpg"))
=> *EXIF*

> (exif-value "FNumber" *exif*)
=> 9/2

> (parsed-exif-value "MeteringMode" *exif*)
=> :PATTERN

> (exif-value :DateTimeOriginal *exif*)
=> "2003:11:23 18:07:37"

> (exif-value #x0112 *exif*)   ; #x0112 => orientation tag in the image IFD
=> 6

> (parsed-exif-value #x0112 *exif*)
=> :ROTATED-270

> (exif-value :ISOSpeedRating *exif*)   ; Field not present in this particular image
=> NIL

> (list (exif-value "GPSLatitude" *exif*)
        (exif-value "GPSLatitudeRef" *exif*)
        (exif-value "GPSLongitude" *exif*)
        (exif-value "GPSLongitudeRef" *exif*))
=> (#(39 54 56) "N" #(116 23 27) "E")



Terms

tag
an integer that refers to a unique field in a specific IFD. For example, the integer #x0001 represents the InteroperabilityIndex field in the interoperability IFD and the GPSVersionID field in the GPS IFD
tag designator
an object representing a tag and that is one of: a string (denoting a tag named by the string for a given IFD), a symbol (denoting a tag named by the string that is its name), or a tag (denoting itself)

The ZPB-EXIF Dictionary

[Function]
make-exif exif-stream-designator => exif

Returns an exif object. exif-stream-designator may be a stream (designating itself), a pathname (designating the stream created by opening the file), or a string (treated the same as a pathname). If exif-stream-designator does not refer to a JPEG, signals an invalid-jpeg-stream error. If exif-stream-designator refers to a JPEG, but the JPEG does not contain any Exif data, signals an invalid-exif-stream error.

[Function]
exif-value tag-designator exif => value

Returns the value of the field identified by tag-designator from the image IFD, Exif IFD, or GPS IFD.

[Function]
parsed-exif-value tag-designator exif => parsed-value

Returns an the value of the field identified by tag-designator from the image IFD, Exif IFD, or GPS IFD in parsed form.

[Function]
exif-alist exif &key parsedp => alist

Returns an association list that has tag names for keys and IFD entry values for values for all entries in the image, Exif, and GPS IFDs in exif. If parsedp is true, the IFD entry values are in parsed form.

[Function]
ifd-alist exif &key parsedp => alist

Returns an association list that has tag names for keys and IFD entry values for values for the entries ifd. If parsedp is true, the IFD entry values are in parsed form.

[Function]
ifd-entry tag-designator ifd => ifd-entry

Returns the IFD entry identified by tag-designator in ifd, or NIL if no IFD entry could be found.

[Function]
entry-value ifd-entry => value

Returns the value of ifd-entry.

[Function]
parsed-entry-value ifd-entry => value

Returns the value of ifd-entry in parsed form.

[Function]
image-ifd exif => ifd

Returns the image IFD for exif. The following tags may be available in the image IFD:

TagNameData Type
Tags Relating to Image Data Structure
#x0100ImageWidthshort or long
#x0101ImageHeightshort or long
#x0102BitsPerSampleshort
#x0103Compressionshort
#x0106PhotometricInterpretationshort
#x0112Orientationshort
#x0115SamplesPerPixelshort
#x011CPlanarConfigurationshort
#x0212YCbCrSubSamplingshort
#x0213YCbCrPositioningshort
#x011AXResolutionrational
#x011BYResolutionrational
#x0128ResolutionUnitshort
Tags Relating to Recording Offsets
#x0111StripOffsetsshort or long
#x0116RowsPerStripshort or long
#x0117StripByteCountsshort or long
#x0201JPEGInterchangeFormatlong
#x0202JPEGInterchangeFormatLengthlong
Tags Relating to Image Data Characteristics
#x012DTransferFunctionshort
#x013EWhitePointrational
#x013FPrimaryChromaticitiesrational
#x0211YCbCrCoefficientsrational; parsed value available
#x0214ReferenceBlackWhiterational
Other Tags
#x0132DateTimeascii; parsed value available
#x010EImageDescriptionascii
#x010FMakeascii
#x0110Modelascii
#x0131Softwareascii
#x013BArtistascii
#x8298Copyrightascii

[Function]
exif-ifd exif => ifd

Returns the Exif IFD for exif. The following tags may be available in the exif IFD:
TagNameData Type
Tags Relating to Version
#x9000ExifVersionundefined; parsed value available
#xA000FlashpixVersionundefined
Tags Relating to Image Data Characteristics
#xA001ColorSpaceshort; parsed value available
#xA001Gammarational; parsed value available
#x9101ComponentsConfigurationundefined
#x9102CompressedBitsPerPixelrational
#xA002PixelXDimensionshort or long
#xA003PixelYDimensionshort or long
Tags Relating to User Information
#x927CMakerNoteundefined
#x9286UserCommentundefined; parsed value available
#xA004RelatedSoundFileascii
Tags Relating to Date and Time
#x9003DateTimeOriginalascii; parsed value available
#x9004DateTimeDigitizedascii; parsed value available
#x9290SubSecTimeascii
#x9291SubSecTimeOriginalascii
#x9292SubSecTimeDigitizedascii
Tags Relating to Picture Taking Conditions
#x829AExposureTimerational; parsed value available
#x829DFNumberrational; parsed value available
#x8822ExposureProgramrational; parsed value available
#x8824SpectralSensitivityascii
#x8827ISOSpeedRatingsshort
#x8828OECFundefined
#x9201ShutterSpeedValuesrational; parsed value available
#x9202ApertureValuerational; parsed value available
#x9203BrightnessValuesrational
#x9204ExposureBiasValuesrational
#x9205MaxApertureValuerational; parsed value available
#x9206SubjectDistancerational; parsed value available
#x9207MeteringModeshort; parsed value available
#x9208LightSourceshort; parsed value available
#x9209Flashshort; parsed value available
#x920AFocalLengthrational; parsed value available
#x9214SubjectAreashort
#xA20BFlashEngergyrational
#xA20CSpatialFrquencyResponseundefined
#xA20EFocalPlaneXResolutionrational; parsed value available
#xA20FFocalPlaneYResolutionrational; parsed value available
#xA210FocalPlaneResolutionUnitshort
#xA214SubjectLocationshort
#xA215ExposureIndexrational
#xA217SensingMethodshort; parsed value available
#xA300FileSourceundefined
#xA301SceneTypeundefined
#xA302CFAPatternundefined
#xA401CustomRenderedshort
#xA402ExposureModeshort; parsed value available
#xA403WhiteBalanceshort; parsed value available
#xA404DigitalZoomRatiorational
#xA405FocalLengthIn35mmFilmshort
#xA406SceneCaptureTypeshort; parsed value available
#xA407GainControlrational; parsed value available
#xA408Contrastshort; parsed value available
#xA409Saturationshort; parsed value available
#xA40ASharpnessshort; parsed value available
#xA40BDeviceSettingDescriptionundefined
#xA40CSubjectDistanceRangeshort
#xA420ImageUniqueIDascii

[Function]
gps-ifd exif => ifd

Returns the GPS IFD for exif.

The following tags are available in the GPS IFD:
TagNameData Type
#x0000GPSVersionIDbyte
#x0001GPSLatitudeRefascii
#x0002GPSLatituderational
#x0003GPSLongitudeRefascii
#x0004GPSLongitudeascii
#x0005GPSAltitudeRefbyte
#x0006GPSAltituderational
#x0007GPSTimeStamprational
#x0008GPSSatellitesascii
#x0009GPSStatusascii
#x000AGPSMeasureModeascii
#x000BGPSDOPrational
#x000CGPSSpeedRefascii
#x000DGPSSpeedrational
#x000EGPSTrackRefascii
#x000FGPSTrackrational
#x0010GPSImgDirectionRefascii
#x0011GPSImgDirectionrational
#x0012GPSMapDatumascii
#x0013GPSDestLatitudeRefascii
#x0014GPSDestLatituderational
#x0015GPSDestLongitudeRefascii
#x0016GPSDestLongituderational
#x0017GPSDestBearingRefascii
#x0018GPSDestBearingrational
#x0019GPSDestDistanceRefascii
#x001AGPSDestDistancerational

[Function]
interoperability-ifd exif => ifd

Returns the interoperability IFD for exif.

[Function]
thumbnail-ifd exif => ifd

Returns the thumbnail IFD for exif. The tags available are the same as for the image IFD.

[Function]
exif-data exif => value

Returns a vector of (unsigned-byte 8) data representing all the data in the Exif section of the stream from which exif was created.

[Function]
thumbnail-image exif => value

Returns a vector of (unsigned-byte 8) data representing the embedded Exif thumbnail of exif, or NIL if no Exif thumbnail is present.

[Condition]
invalid-stream

This error condition is a supertype of Exif stream conditions.

[Condition]
invalid-jpeg-stream

This condition is signalled when a stream being processed is not a JPEG stream. It is a subtype of invalid-stream.

[Condition]
invalid-exif-stream

This condition is signalled when a stream being processed is not an Exif stream. It is a subtype of invalid-stream.

Parsed Values

When using parsed-exif-value, the following IFD/tag combinations are converted from the "raw" Exif value into a more processing-friendly format. All others return the same value that would be returned by exif-value

Image IFD

Exif IFD

Feedback

This library was created by Zachary Beane. For questions, comments, bug reports, and patches, please email him.


$Header: /home/cvs/zpb-exif/zpb-exif.html,v 1.5 2009/09/08 17:16:34 xach Exp $