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:
- Make it available after image load on script level
- Make it setable within the image
- Write it in the image file.
- Prepare eventual automations on automatic scaling on screen resolution
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
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|
||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.
The current C interface for drivers and other programs is not sufficient to support the metadata dict.
A new extensible interface is envisaged with:
- a pair of functions to get or set all options of the image.
- a new driver interface to basically only pass the command.
- and a compatibility layer to the current driver interface
There are currently functions to access the raster data (
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:
Tcl_Obj * Tk_PhotoGetOption(Tk_PhotoHandle handle, const char *OptionName)
This retrieves the current value of an option.
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.
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.