README
¶
This is about READING image metadata
Writing is not supported, and never will.
I welcome PRs with fixes, but please raise an issue first if you want to add new features.
Performance
Extracting EXIF performs well, ref. the benhcmark below. Note that you can get a significant boost if you only need a subset of the fields (e.g. only the Orientation). The last line is with the library that Hugo used before it was replaced with this.
BenchmarkDecodeCompareWithGoexif/bep/imagemeta/exif/jpeg/alltags-10 62474 19054 ns/op 4218 B/op 188 allocs/op
BenchmarkDecodeCompareWithGoexif/bep/imagemeta/exif/jpeg/orientation-10 309145 3723 ns/op 352 B/op 8 allocs/op
BenchmarkDecodeCompareWithGoexif/rwcarlsen/goexif/exif/jpg/alltags-10 21987 50195 ns/op 175548 B/op 812 allocs/op
Looking at some more extensive tests, testing different image formats and tag sources, we see that the current XMP implementation leaves a lot to be desired (you can provide your own XMP handler if you want).
BenchmarkDecode/png/exif-10 39164 30783 ns/op 4231 B/op 189 allocs/op
BenchmarkDecode/png/all-10 5617 206111 ns/op 48611 B/op 310 allocs/op
BenchmarkDecode/webp/all-10 3069 379637 ns/op 144181 B/op 2450 allocs/op
BenchmarkDecode/webp/xmp-10 3291 359133 ns/op 139991 B/op 2265 allocs/op
BenchmarkDecode/webp/exif-10 47028 25788 ns/op 4255 B/op 191 allocs/op
BenchmarkDecode/jpg/exif-10 58701 20216 ns/op 4223 B/op 188 allocs/op
BenchmarkDecode/jpg/iptc-10 135777 8725 ns/op 1562 B/op 80 allocs/op
BenchmarkDecode/jpg/iptc/category-10 215674 5393 ns/op 456 B/op 15 allocs/op
BenchmarkDecode/jpg/iptc/city-10 192067 6201 ns/op 553 B/op 17 allocs/op
BenchmarkDecode/jpg/xmp-10 3244 359436 ns/op 139861 B/op 2263 allocs/op
BenchmarkDecode/jpg/all-10 2874 389489 ns/op 145700 B/op 2523 allocs/op
BenchmarkDecode/tiff/exif-10 2065 566786 ns/op 214089 B/op 282 allocs/op
BenchmarkDecode/tiff/iptc-10 16761 71003 ns/op 2603 B/op 133 allocs/op
BenchmarkDecode/tiff/all-10 1267 933321 ns/op 356878 B/op 2668 allocs/op
When in doubt, Exiftool is right
The output of this library is tested against exiftool -n -json. This means, for example, that:
- We use f-numbers and not APEX for aperture values.
- We use seconds and not APEX for shutter speed values.
- EXIF field definitions are fetched from this table: https://exiftool.org/TagNames/EXIF.html
- IPTC field definitions are fetched from this table: https://exiftool.org/TagNames/IPTC.html
- The XMP handling is currently very simple, you can supply your own XMP handler (see the
HandleXMPoption) if you need more.
There are some subtle differences in output:
- Exiftool prints rationale number arrays as space formatted strings with a format/precision that seems unnecessary hard to replicate, so we use
strconv.FormatFloat(f, 'f', -1, 64)for these.
Development
Many of the tests depends on generated golden files. To update these, run:
go generate ./gen
Note that you need a working exiftool and identify(ImageMagick) in your PATH for this to work. This was tested OK with:
exiftool -ver
12.76
Debugging tips:
exiftool testdata/goexif_samples/has-lens-info.jpg -htmldump > dump.html
Documentation
¶
Index ¶
- Constants
- Variables
- func IsInvalidFormat(err error) bool
- type DecodeResult
- type HandleTagFunc
- type ImageConfig
- type ImageFormat
- type InvalidFormatError
- type Options
- type Rat
- type Source
- type TagInfo
- type Tags
- func (t *Tags) Add(tag TagInfo)
- func (t Tags) All() map[string]TagInfo
- func (t *Tags) EXIF() map[string]TagInfo
- func (t Tags) GetDateTime() (time.Time, error)
- func (t Tags) GetLatLong() (lat float64, long float64, err error)
- func (t *Tags) Has(tag TagInfo) bool
- func (t *Tags) IPTC() map[string]TagInfo
- func (t *Tags) XMP() map[string]TagInfo
Constants ¶
const UnknownPrefix = "UnknownTag_"
UnknownPrefix is used as prefix for unknown tags.
Variables ¶
var ( // ErrStopWalking is a sentinel error to signal that the walk should stop. ErrStopWalking = fmt.Errorf("stop walking") )
Functions ¶
func IsInvalidFormat ¶
IsInvalidFormat reports whether the error was an InvalidFormatError.
Types ¶
type DecodeResult ¶ added in v0.13.0
type DecodeResult struct {
// ImageConfig contains basic image configuration.
// Note that this will be zero if the CONFIG source was not requested.
ImageConfig ImageConfig
}
DecodeResult contains the result of a Decode operation.
func Decode ¶
func Decode(opts Options) (result DecodeResult, err error)
Decode reads EXIF and IPTC metadata from r and returns a Meta struct.
type HandleTagFunc ¶
HandleTagFunc is the function that is called for each tag.
type ImageConfig ¶ added in v0.13.0
ImageConfig contains basic image configuration.
type ImageFormat ¶
type ImageFormat int
ImageFormat is the image format.
const ( // ImageFormatAuto signals that the image format should be detected automatically (not implemented yet). ImageFormatAuto ImageFormat = iota // JPEG is the JPEG image format. JPEG // TIFF is the TIFF image format. TIFF // PNG is the PNG image format. PNG // WebP is the WebP image format. WebP )
func (ImageFormat) String ¶
func (i ImageFormat) String() string
type InvalidFormatError ¶
type InvalidFormatError struct {
Err error
}
InvalidFormatError is used when the format is invalid.
func (*InvalidFormatError) Error ¶
func (e *InvalidFormatError) Error() string
func (*InvalidFormatError) Is ¶ added in v0.6.0
func (e *InvalidFormatError) Is(target error) bool
Is reports whether the target error is an InvalidFormatError.
type Options ¶
type Options struct {
// The Reader (typically a *os.File) to read image metadata from.
R io.ReadSeeker
// The image format in R.
ImageFormat ImageFormat
// If set, the decoder skip tags in which this function returns false.
// If not set, a default function is used that skips all EXIF tags except those in IFD0.
ShouldHandleTag func(tag TagInfo) bool
// The function to call for each tag.
HandleTag HandleTagFunc
// The default XMP handler is currently very simple:
// It decodes the RDF.Description.Attrs using Go's xml package and passes each tag to HandleTag.
// If HandleXMP is set, the decoder will call this function for each XMP packet instead.
// Note that r must be read completely.
HandleXMP func(r io.Reader) error
// If set, the decoder will only read the given tag sources.
// Note that this is a bitmask and you may send multiple sources at once.
Sources Source
// Warnf will be called for each warning.
Warnf func(string, ...any)
// Timeout is the maximum time the decoder will spend on reading metadata.
// Mostly useful for testing.
// If set to 0, the decoder will not time out.
Timeout time.Duration
// LimitNumTags is the maximum number of tags to read.
// Default value is 5000.
LimitNumTags uint32
// LimitTagSize is the maximum size in bytes of a tag value to read.
// Tag values larger than this will be skipped without notice.
// Note that this limit is not relevant for the XMP source.
// Default value is 10000.
LimitTagSize uint32
}
Options contains the options for the Decode function.
type Rat ¶
type Rat[T int32 | uint32] interface { Num() T Den() T Float64() float64 // String returns the string representation of the rational number. // If the denominator is 1, the string will be the numerator only. String() string }
Rat is a rational number.
type Source ¶ added in v0.5.0
type Source uint32
Source is a bitmask and you may send multiple sources at once.
const ( // EXIF is the EXIF tag source. EXIF Source = 1 << iota // IPTC is the IPTC tag source. IPTC // XMP is the XMP tag source. XMP // CONFIG source, which currently the image dimensions encoded in the image. // Note that this must not be confused with the dimensions stored in EXIF tags. CONFIG )
type TagInfo ¶
type TagInfo struct {
// The tag source.
Source Source
// The tag name.
Tag string
// The tag namespace.
// For EXIF, this is the path to the IFD, e.g. "IFD0/GPSInfoIFD"
// For XMP, this is the namespace, e.g. "http://ns.adobe.com/camera-raw-settings/1.0/"
// For IPTC, this is the record tag name as defined https://exiftool.org/TagNames/IPTC.html
Namespace string
// The tag value.
Value any
}
TagInfo contains information about a tag.
type Tags ¶
type Tags struct {
// contains filtered or unexported fields
}
Tags is a collection of tags grouped per source.
func (Tags) GetDateTime ¶
GetDateTime tries to find a date/time value from available metadata sources. It checks EXIF first (DateTimeOriginal, DateTime), then XMP (DateTimeOriginal, CreateDate, DateCreated), and finally IPTC (DateCreated + TimeCreated).
func (Tags) GetLatLong ¶
GetLatLong returns the latitude and longitude from available metadata sources. It checks EXIF first, then falls back to XMP.
Source Files
Directories