README.org

[[https://clojars.org/com.github.danielsz/beeld][https://img.shields.io/clojars/v/com.github.danielsz/beeld.svg]]

• Beeld

This library displays the metadata associated with images and does some more. For example,

• Scaling an image in portrait mode or landscape mode based on the orientation EXIF tag.
• Create a naming scheme for a photo library where parts of the name gets extracted from metadata.
• Detect the format of an image so that the correct mime-type can be appended to the headers in a web service.

** Metadata

Image formats embed standardized information about themselves. Multiple information standards may coexist in the same image, for example Exif, IPTC, ICC and XMP. The Exif standard specify a special tag called /Makernote/ that allows camera manufactures to add their proprietary tags.

Over the years, software solutions for retrieving and preserving metadata have coalesced around a handful of flagship projects with Phil Harvey's [[Exiftool][Exiftool]] reigning supreme. For Java, the go-to solution is Drew Noakes's [[https://github.com/drewnoakes/metadata-extractor][metadata extractor]]. This library depends on the latter.

Two namespaces are meant for public consumption, beeld.core and beeld.metadata.

** beeld.metadata

Most users will need only the tags function, which accepts a filename and returns a data structure representing the metadata associated with the image. Since images may have large amounts metadata, the data structure, a map of maps, is organized around standardized directories. Think about them as thematic groupings of information. Examples of such headings are Exif SubIFD, File Type, GPS, etc.

The argument to tags are the same arguments that input-stream accepts: /InputStream/, /File/, /URI/, /URL/, byte array, strings. A string argument gets first resolved as a /URI/, then as a local file name. This means that you can ask about the metadata of images over the wire.

#+begin_src clojure (require '[beeld.metadata :as meta]) (meta/tags "path/to/your/image.jpg") ;;or (meta/tags "https://somewhere.com/your/image.jpg")

;; Returns a map of maps #+end_src

The namespace beeld.metadata offers several convenience functions that retrieve a particular metadata tag, for example mime-type, lens, make, orientation, etc.

** beeld.core

beeld.core defines an interface geared towards low-level image manipulation. The namespace includes functions to convert images to base64, streams or byte arrays, very much in the spirit of Java I/O. The scale function in /beeld.core/ will honor the orientation tag found in the metada and resize the image accordingly. Something that Java's /ImageIO/ doesn't do.

** Contributing

Additional convenience functions in the beeld.metadata namespace are welcome. Anything else requires preliminary discussion and vetting.