{"id":20469396,"url":"https://github.com/frameright/image-display-control-metadata-parser","last_synced_at":"2025-10-26T14:12:20.151Z","repository":{"id":164436781,"uuid":"626947355","full_name":"Frameright/image-display-control-metadata-parser","owner":"Frameright","description":"TypeScript Image Display Control metadata parsing library","archived":false,"fork":false,"pushed_at":"2024-10-14T08:36:35.000Z","size":12399,"stargazers_count":4,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-10-20T04:40:22.173Z","etag":null,"topics":["frameright","image","image-display-control","image-manipulation","iptc-metadata","metadata","metadata-extraction","metadata-parser"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Frameright.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-04-12T13:30:33.000Z","updated_at":"2024-10-14T08:36:32.000Z","dependencies_parsed_at":"2023-10-02T12:54:54.014Z","dependency_job_id":"20492dfc-adff-485b-9553-ecbcd9ff481e","html_url":"https://github.com/Frameright/image-display-control-metadata-parser","commit_stats":{"total_commits":123,"total_committers":3,"mean_commits":41.0,"dds":0.4552845528455285,"last_synced_commit":"80a5d25fd744de35915f90444697f586342cfb0f"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Frameright%2Fimage-display-control-metadata-parser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Frameright%2Fimage-display-control-metadata-parser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Frameright%2Fimage-display-control-metadata-parser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Frameright%2Fimage-display-control-metadata-parser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Frameright","download_url":"https://codeload.github.com/Frameright/image-display-control-metadata-parser/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248699522,"owners_count":21147654,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["frameright","image","image-display-control","image-manipulation","iptc-metadata","metadata","metadata-extraction","metadata-parser"],"created_at":"2024-11-15T14:08:56.515Z","updated_at":"2025-10-26T14:12:20.071Z","avatar_url":"https://github.com/Frameright.png","language":"TypeScript","readme":"[\u003cimg src=\"https://avatars.githubusercontent.com/u/35964478?s=200\u0026v=4\" align=\"right\" width=\"64\" height=\"64\"\u003e](https://frameright.io)\n[![npm version](https://img.shields.io/npm/v/@frameright/image-display-control-metadata-parser)](https://www.npmjs.com/package/@frameright/image-display-control-metadata-parser)\n[![github actions](https://github.com/Frameright/image-display-control-metadata-parser/actions/workflows/main.yml/badge.svg)](https://github.com/Frameright/image-display-control-metadata-parser/actions/workflows/main.yml)\n\n\u0026nbsp;\n\n\u003c!--\nWARNINGS:\n* Bits of information here are duplicated in several places:\n    * https://docs.frameright.io/javascript\n    * https://github.com/Frameright/image-display-control-metadata-parser\n  Make sure to keep them in sync.\n* Make sure all URLs in this document are absolute, and not relative within\n  GitHub, as we are publishing this file to NPM and want URLs to remain valid\n  there.\n--\u003e\n\n# Image Display Control metadata parsing library\n\n\u003e **➡️ See this document rendered at [docs.frameright.io/javascript](https://docs.frameright.io/javascript)**\n\nAn easy way to retrieve [Image Display Control](https://frameright.io) metadata\nout of images. Made with :heart: by [Frameright](https://frameright.io). Power\nto the pictures!\n\n\u0026emsp; :sparkles: [Live demo](https://webc.frameright.io)\n\n\u0026emsp; :bulb: [GitHub Discussions](https://github.com/Frameright/image-display-control-web-component/discussions)\n\n\u003e **NOTE**: this is a wrapper around\n\u003e [mattiasw/ExifReader](https://github.com/mattiasw/ExifReader) and\n\u003e [image-size](https://github.com/image-size/image-size). Many thanks to\n\u003e [mattiasw](https://github.com/mattiasw), [netroy](https://github.com/netroy),\n\u003e and other contributors!\n\n## Table of Contents\n\n\u003c!-- toc --\u003e\n\n- [Overview](#overview)\n- [Usage](#usage)\n  * [In a Node.js back-end](#in-a-nodejs-back-end)\n  * [Directly in a browser](#directly-in-a-browser)\n- [Image Display Control metadata](#image-display-control-metadata)\n\n\u003c!-- tocstop --\u003e\n\n## Overview\n\nThe\n[Image Display Control web component](https://github.com/Frameright/image-display-control-web-component)\nextends the `\u003cimg\u003e` tag with the ability to accept a list of\nimage regions, and to zoom in on the best one for the current element size, thus\nachieving better results than\n[`object-fit: cover;`](https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit)\na.k.a. middle-cropping. Its syntax looks like:\n\n```html\n\u003cimg\n  is=\"image-display-control\"\n  src=\"https://images.pexels.com/photos/3625715/pexels-photo-3625715.jpeg\"\n  width=\"200\"\n  height=\"200\"\n  data-image-regions='[{\n    \"id\": \"oneanimal\",\n    \"names\": [\"One animal\"],\n    \"shape\": \"rectangle\",\n    \"unit\": \"relative\",\n    \"x\": \"0.217\",\n    \"y\": \"0.708\",\n    \"width\": \"0.239\",\n    \"height\": \"0.1467\"\n  }, {\n    \"id\": \"threeanimals\",\n    \"names\": [\"Three animals\"],\n    \"shape\": \"rectangle\",\n    \"unit\": \"relative\",\n    \"x\": \"0.245\",\n    \"y\": \"0.725\",\n    \"width\": \"0.419\",\n    \"height\": \"0.121\"\n  }]'\n/\u003e\n```\n\nTypically this list of image regions come from the metadata of the image file\nitself, is retrieved by the back-end, and is placed in the front-end's\n`\u003cimg data-image-regions=\"` attribute.\n\nThis is where this library comes into play: it allows your Node.js back-end to\neasily retrieve this metadata.\n\n\u003e **NOTES**:\n\u003e\n\u003e * A React component leveraging this library is available\n\u003e   [here](https://github.com/Frameright/react-image-display-control).\n\u003e * A PHP equivalent of this library is available\n\u003e   [here](https://github.com/Frameright/php-image-metadata-parser).\n\n## Usage\n\n### In a Node.js back-end\n\n```jsx\n#!/usr/bin/env node\n// ./myscript.mjs\n\nimport { promises as fs } from 'fs';\n\n// npm install @frameright/image-display-control-metadata-parser\nimport { Parser } from '@frameright/image-display-control-metadata-parser';\n\n// Get it from https://iptc.org/std/photometadata/examples/IPTC-PhotometadataRef-Std2021.1.jpg\nconst buffer = await fs.readFile('IPTC-PhotometadataRef-Std2021.1.jpg');\n\nconst parser = new Parser(buffer);\nconsole.log(parser.getIdcMetadata());\n```\n\nThis has been\n[validated](https://github.com/Frameright/image-display-control-metadata-parser/blob/main/test/index.test.ts)\nwith JPEG, PNG, and WebP images.\n\n\u0026emsp; :memo: [Tutorial](https://www.frameright.io/post/metadata-in-node-js)\n\n\u0026emsp; :scroll: [Reference](https://github.com/Frameright/image-display-control-metadata-parser/blob/main/generated-docs/classes/Parser.md)\n\n\u0026emsp; :wrench: [Contributing](https://docs.frameright.io/javascript/contributing)\n\n\u0026emsp; 📝 [Changelog](https://docs.frameright.io/javascript/contributing)\n\n\u0026emsp; :bulb: [GitHub Discussions](https://github.com/Frameright/image-display-control-web-component/discussions)\n\n### Directly in a browser\n\nFor testing purposes, you can use this library directly in the browser:\n\n```html\n\u003chtml\u003e\n  \u003cbody onload=\"documentLoaded()\"\u003e\n    \u003cscript\n      type=\"module\"\n      src=\"https://cdn.jsdelivr.net/npm/@frameright/image-display-control-metadata-parser@2.0.0/dist/image-display-control-metadata-parser-standalone.min.js\"\n    \u003e\u003c/script\u003e\n\n    \u003cscript type=\"text/javascript\"\u003e\n      async function documentLoaded() {\n        const image = await fetch(\n          'https://iptc.org/std/photometadata/examples/IPTC-PhotometadataRef-Std2021.1.jpg'\n        );\n        const buffer = await image.arrayBuffer();\n        const parser = new ImageDisplayControl.Parser(buffer);\n        const regions = parser.getIdcMetadata();\n        console.log(JSON.stringify(regions, null, 2 /*indent*/));\n      }\n    \u003c/script\u003e\n  \u003c/body\u003e\n\u003c/html\u003e\n```\n\nThe parsed metadata can then directly be fed to the\n[Image Display Control web component](https://github.com/Frameright/image-display-control-web-component).\n\n[This React component](https://github.com/Frameright/react-image-display-control/blob/main/src/index.tsx)\nis an example of doing that.\n\n\u0026emsp; :sparkles: [Live demo](https://webc.frameright.io)\n\n\u0026emsp; 💻 [CodeSandbox](https://codesandbox.io/s/image-display-control-web-component-6hzmq5)\n\n## Image Display Control metadata\n\nNowadays an image file (e.g. JPEG, PNG) can contain this type of image regions\nin their metadata according to\n[the IPTC standard](https://iptc.org/std/photometadata/specification/IPTC-PhotoMetadata#image-region).\nPhotographers, or anyone else, can use the\n[Frameright webapp](https://frameright.app/) to define and store image regions in\nthe metadata of their pictures.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fframeright%2Fimage-display-control-metadata-parser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fframeright%2Fimage-display-control-metadata-parser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fframeright%2Fimage-display-control-metadata-parser/lists"}