Image Display Control metadata parsing library

➡️ See this document rendered at docs.frameright.io/javascript

An easy way to retrieve Image Display Control metadata out of images. Made with ❤️ by Frameright. Power to the pictures!

✨ Live demo

💡 GitHub Discussions

NOTE: this is a wrapper around mattiasw/ExifReader and image-size. Many thanks to mattiasw, netroy, and other contributors!

Overview

The Image Display Control web component extends the <img> tag with the ability to accept a list of image regions, and to zoom in on the best one for the current element size, thus achieving better results than object-fit: cover; a.k.a. middle-cropping. Its syntax looks like:

<img
  is="image-display-control"
  src="https://images.pexels.com/photos/3625715/pexels-photo-3625715.jpeg"
  width="200"
  height="200"
  data-image-regions='[{
    "id": "oneanimal",
    "names": ["One animal"],
    "shape": "rectangle",
    "unit": "relative",
    "x": "0.217",
    "y": "0.708",
    "width": "0.239",
    "height": "0.1467"
  }, {
    "id": "threeanimals",
    "names": ["Three animals"],
    "shape": "rectangle",
    "unit": "relative",
    "x": "0.245",
    "y": "0.725",
    "width": "0.419",
    "height": "0.121"
  }]'
/>

Typically this list of image regions come from the metadata of the image file itself, is retrieved by the back-end, and is placed in the front-end's <img data-image-regions=" attribute.

This is where this library comes into play: it allows your Node.js back-end to easily retrieve this metadata.

NOTES:

A React component leveraging this library is available here.

A PHP equivalent of this library is available here.

Usage

In a Node.js back-end

#!/usr/bin/env node
// ./myscript.mjs

import { promises as fs } from 'fs';

// npm install @frameright/image-display-control-metadata-parser
import { Parser } from '@frameright/image-display-control-metadata-parser';

// Get it from https://iptc.org/std/photometadata/examples/IPTC-PhotometadataRef-Std2021.1.jpg
const buffer = await fs.readFile('IPTC-PhotometadataRef-Std2021.1.jpg');

const parser = new Parser(buffer);
console.log(parser.getIdcMetadata());

This has been validated with JPEG, PNG, and WebP images.

📝 Tutorial

📜 Reference

🔧 Contributing

📝 Changelog

💡 GitHub Discussions

Directly in a browser

For testing purposes, you can use this library directly in the browser:

<html>
  <body onload="documentLoaded()">
    <script
      type="module"
      src="https://cdn.jsdelivr.net/npm/@frameright/image-display-control-metadata-parser@2.0.0/dist/image-display-control-metadata-parser-standalone.min.js"
    ></script>

    <script type="text/javascript">
      async function documentLoaded() {
        const image = await fetch(
          'https://iptc.org/std/photometadata/examples/IPTC-PhotometadataRef-Std2021.1.jpg'
        );
        const buffer = await image.arrayBuffer();
        const parser = new ImageDisplayControl.Parser(buffer);
        const regions = parser.getIdcMetadata();
        console.log(JSON.stringify(regions, null, 2 /*indent*/));
      }
    </script>
  </body>
</html>

The parsed metadata can then directly be fed to the Image Display Control web component.

This React component is an example of doing that.

✨ Live demo

💻 CodeSandbox