Storing metadata in a PNG image

PNG images can be used to store maps of physical quantities. Some metadata is then needed in order to recover the original data from the image.

This repository contains:

• a sample C++ program showing how to write a PNG file that holds both the image and the relevant metadata
• a Python script that extracts, from this PNG file:
  • the raw image in TIFF format
  • the metadata as a YAML file

Stored metadata

The metadata fields stored in the PNG file are:

• Pixel width: physical dimension corresponding to a pixel in the horizontal direction
• Pixel height: physical dimension corresponding to a pixel in the vertical direction
• Pixel unit: unit for "Pixel width" and "Pixel height"
• Value min: minimal value of the physical quantity, mapped to the pixel value 0
• Value max: maximal value of the physical quantity, mapped to the pixel value 65535
• Value unit: unit for "Value min" and "Value max"
• Creation Time: the creation time, in the RFC-3339-compatible format "YYYY-MM-DD hh:mm:ss±zz:zz"
• Software: software that simulated the image
• Version: version of the software
• Simulation parameters: simulation parameters as a YAML string

Each of these fields is stored a in PNG tEXt chunk. In addition, some information is stored redundantly in two chunks of types:

• sCAL (Physical scale of image subject). This is the resolution referenced to the image's subject, and is distinct from pHYs (Physical pixel dimensions), which is referenced to the displayed (or printed) image.

• pCAL (Calibration of pixel values). This defines the mapping function from the pixel values to the physical quantities they represent.

• tIME (Image last-modification time). This is the same as the creation time, stored in binary, in UTC.

Sample C++ code

The following files are provided:

• write_png.cpp: defines a function write_png_image() that writes a 2D array of floating-point numbers as a 16-bit grayscale PNG file with embedded metadata
• write_png.h: interface of write_png_image()
• main.cpp: example program that uses write_png_image() to create a sample file named image.png
• Makefile: builds the example program as an executable named write_png

Dependencies

• libpng

Python script

• png_extractor.py: converts a 16-bit PNG file to a TIFF file, extracts the metadata and writes it to a YAML file

Example usage:

./png_extractor.py my_file.png

This will create two files: my_file.tif and my_file.yml.

Dependencies

• Python version 3.10 or above
• python modules:
  • png
  • PIL (pillow)
  • numpy
  • os