TIP 529: Add metadata dict property to tk photo image

Bounty program for improvements to Tcl and certain Tcl packages.
Author:         Harald Oehlmann <[email protected]>
State:          Draft
Type:           Project
Vote:           Pending
Created:        07-Dec-2018
Keywords:       Tk, image
Tcl-Version:    8.7
Tk-Branch:     tip-529-image-metadata


An additional property is proposed for photo images to hold image metadata:

myimage cget -metadata
myimage configure -metadata [dict create dpi 300.0]


Image files may contain a lot of metadata like resolution, comments, GPS location etc. This metadata should be accessable and setable for the following aims:

This TIP specially targets the resolution (DPI) value of the image.

The image resolution included in an image file is crucial for its usage, as many applications (word & co.) use this field to calculate a default size. One may enjoy, that image files used in pdf4tcl are automatically scaled at the right resolution (e.g. the resolution saved in the image file).

This information is included in png files (supported by tk core) and many other image formats included in the Img patch.

I authored an extension to the Img patch to specify the dpi field of a bmp file on file writing. The syntax was accorded with Jeff Hobbs:

myimage write file.bmp -format [list bmp -resolution 300 i]

This may be expressed (when all packages are adopted) by:

myimage configure -metadata [dict create dpi 300.0]
myimage write file.bmp


Metadata Dict

The propery "-metadata" is added to each image. It contains a dictionary, where the keys of the dictionary are specific to each photo image format.

The following default keys are used by Tk's built in photo image formats, if the corresponding data is present:

Key Description Example image formats
dpi Image resolution png
comment Text comment gif
xmp xmp image data png

If a particular image does not specify any keys (whether during creation or otherwise) then the dictionary will be empty.


The following commands are directly concerned:

image create photo myimage -metadata $metadict
myimage cget -metadata
myimage configure -metadata $metadict

It is also OK to store application data related to the image within the property dict. A widget may store special properties; Tk will store and return values it does not recognise, but otherwise will ignore them.

Any load and save command may use the content of the metadata dict. This may be an ongoing process, specially within the Img patch.

The commands are:

image create photo myimage -file myfile.bmp
myimage configure -file myfile.bmp
myimage write file.bmp

The image create and file loading functions recreate the metadata dict. Any current contents is lost.

The write method uses any dict keys it knows. Any unknown dict keys are ignored.

C Interface

The current C interface for drivers and other programs is not sufficient to support the metadata dict.

A new extensible interface is envisaged with:

There are currently functions to access the raster data (Tk_PhotoGetImage, Tk_PhotoPutBlock). The other properties (-file, -data, -format, -gamma) are not exposed.

A new interface may also be used for other image formats like SVG where the image data consists of the rastered image, the image data and metadata. In this case, an image save operation might even not use the raster data but only metadata and image data.

Image Property get and set Functions

Two new stub table functions are added:

  1. Tcl_Obj * Tk_PhotoGetOption(Tk_PhotoHandle handle, const char *OptionName)

    This retrieves the current value of an option.

  2. void Tk_PhotoSetOption(Tk_PhotoHandle handle, const char *OptionName, Tcl_Obj *optionValue)

    This updates or creates the value of an option.

Revised Image Driver Commands

The new command interface only passes the image handle. Any required data may be accquired by the get/set functions. Also, access to the raster data is done by the raster access functions.

The current registration function is




The current implementation is only a sketch in my brain. I hope, that an image handler can set the options after reading and a binary extension of the image handlers is not necessary. Nevertheless, I don't know jet.

Any help and comments are appreciated. I am realy a novice here.

Implementation may start soon with the tag tip-529-image-metadata.

Rejected Alternatives

C interface: only use metadata dict get and set functions

Two new stub table functions are added:

Tcl_Obj * Tk_PhotoGetMetadata(Tk_PhotoHandle handle)

void Tk_PhotoSetMetadata(Tk_PhotoHandle handle, Tcl_Obj *metadata)

This works well for image read. The function "Tk_PhotoSetMetadata" is called within the image read function.

But it is not suitable for image write, as the required photo handle is not passed into the write functions:

static int CommonWriteGIF(Tcl_Interp *interp,
        const char *fileName,
        WriteBytesFunc *writeProc,
        Tcl_Obj *format,
        Tk_PhotoImageBlock *blockPtr);

In consequence, the write function should be extended by the metadata object pointer.


This document has been placed in the public domain.