Install Now
img - Introduction to Img
Contents
Copyright
Copyright (c) 1995-2024 Jan Nijtmans <nijtmans@users.sourceforge.net>
Copyright (c) 2002-2024 Andreas Kupries <andreas_kupries@users.sourceforge.net>
Copyright (c) 2003-2024 Paul Obermeier <obermeier@users.sourceforge.net>
img 2.0 img(3tk)
Description
Img is a collection of format handlers for the Tkphoto [https://www.tcl.tk/man/tcl9.0/TkCmd/photo.html]
image type.
Sources and binaries of Img are available at SourceForge [https://sourceforge.net/projects/tkimg/].
The individual formats are described in more detail on their own pages.
bmp Windows bitmap format. See img-bmp.
dted* Digital Terrain Elevation Data format. See img-dted.
flir* FLIR FPF Public Image format. See img-flir.
gif* Graphics Interchange Format. See img-gif.
ico Windows icon format. See img-ico.
jpeg Joint Picture Experts Group format. See img-jpeg.
pcx Paintbrush format. See img-pcx.
pixmap Pixmap image type. While the other formats are handlers for the Tk photo image type, this is a
new image type for Tk. See img-pixmap.
png Portable Network Graphics format. See img-png.
ppm Portable pixmap format. See img-ppm.
ps* Postscript and PDF format. Requires an external application, ghostview for its operation. See
img-ps.
raw* Raw data format. See img-raw.
sgi Silicon Graphics format. See img-sgi.
sun Sun raster format. See img-sun.
tga Truevision Targa format. See img-tga.
tiff Tagged Image File Format. See img-tiff.
window Tk window as photo image. See img-window.
xbm X Windows Bitmap format. See img-xbm.
xpm X Windows Pixmap format. See img-xpm.
Image Metadata
Some image formats support an individual set of metadata dictionary keys. See the Tkphoto
[https://www.tcl.tk/man/tcl9.0/TkCmd/photo.html] image command for more information regarding image
metadata.
This support is enabled, if Img is linked against Tk 8.7 or newer.
The following keys are supported:
DPI Horizontal image resolution in dots per inch as double value.
Supported by formats img-bmp, img-jpeg, img-pcx, img-png, img-tiff.
aspect Aspect ratio defined as horizontal size divided by vertical size as double value.
Supported by formats img-bmp, img-jpeg, img-pcx, img-png, img-tiff.
numpages
The number of pages in an image file.
Supported by formats img-ico, img-tiff.
All formats supporting image resolution (DPI and aspect) have the following format options for writing
these values without explicitly setting the metadata dictionary:
-resolution-xresolution-yresolution.
[1] Option -resolution allows specifying both horizontal and vertical resolution values.
[2] If not using option -resolution, options -xresolution and -yresolution must both be specified.
Otherwise no resolution information is written.
[3] Resolution values specified with any of the above options overwrite the corresponding metadata
dictionary values.
[4] The resolution values can be specified as double values as documented with function Tk_GetPixels
[https://www.tcl.tk/man/tcl9.0/TkLib/GetPixels.html].
Example resolution specifications:
1.0: 1 inch
1i : 1 inch
1c : 1 centimeter
1m : 1 millimeter
1p : 1 point
Example writing PNG image with horizontal resolution of 300 inches and vertical resolution of 200
centimeters:
img write out.png -format {png -resolution 300i 200c}
Matching Order
When reading images without specifying the format (using option -format), the match functions of the
available formats are tried in reversed order as registered. So, the handlers of the Img package are
called before the handlers of the Tk core. The Tk core registers the following handlers: GIF, PNG, PPM,
SVG, DEFAULT.
In Tk 8.7 a new format handler structure (Tk_PhotoImageFormatVersion3) was introduced to handle the new
metadata information. All old handlers (Tk_PhotoImageFormat) are called before calling the new Format3
handlers.
See manual page of function Tk_CreatePhotoImageFormat
[https://www.tcl.tk/man/tcl9.0/TkLib/CrtPhImgFmt.html] for a detailed description of the handler struture
and matching functions.
The resulting matching order is best explained by an example:
package require Tk
package require Img
package require img::raw (Format2Imghandler)
Note, that the packagerequireImg command actually calls the following statements:
package require img::window (Format2Imghandler)
package require img::tga (Format2Imghandler)
package require img::ico (Format3Imghandler)
package require img::pcx (Format3Imghandler)
package require img::sgi (Format2Imghandler)
package require img::sun (Format2Imghandler)
package require img::xbm (Format2Imghandler)
package require img::xpm (Format2Imghandler)
package require img::jpeg (Format3Imghandler)
package require img::png (Format3Imghandler)
package require img::tiff (Format3Imghandler)
package require img::bmp (Format3Imghandler)
package require img::ppm (Format2Imghandler)
The order of calling the match functions is therefore as follows:
Match format raw (Format2Imghandler)
Match format ppm (Format2Imghandler)
Match format xpm (Format2Imghandler)
Match format xbm (Format2Imghandler)
Match format sun (Format2Imghandler)
Match format sgi (Format2Imghandler)
Match format tga (Format2Imghandler)
Match format window (Format2Imghandler)
Match format svg (Format2Tkhandler)
Match format ppm (Format2Tkhandler)
Match format default (Format2Tkhandler)
Match format bmp (Format3Imghandler)
Match format tiff (Format3Imghandler)
Match format png (Format3Imghandler)
Match format jpeg (Format3Imghandler)
Match format pcx (Format3Imghandler)
Match format ico (Format3Imghandler)
Match format png (Format3Tkhandler)
Match format gif (Format3Tkhandler)Multi-Page Images
Some image formats support storage of multiple pages in a file.
Supported by formats img-gif, img-ico, img-ps, img-tiff.
A specific page can be extracted using the -index option. Index 0 specifies the first page.
There is currently no support for writing multi-page images.
The number of pages of an image file can either be retrieved using metadata key numpages (see chapter
ImageMetadata) or by checking different -index values.
For example, GIF images can have multiple pages in one file. The metadata dictionary key numpages is not
supported for GIF images, as this property cannot be extracted fast.
If you need to know the number of pages, use code like in the following example:
proc CheckIndex { fileName fmt ind } {
set retVal [catch {image create photo -file $fileName -format "$fmt -index $ind"} phImg]
if { $retVal == 0 } {
image delete $phImg
return true
}
return false
}
proc GetNumPages { fileName fmt } {
if { [CheckIndex $fileName $fmt 1] } {
set ind 5
while { [CheckIndex $fileName $fmt $ind] } {
incr ind 5
}
incr ind -1
while { ! [CheckIndex $fileName $fmt $ind] } {
incr ind -1
}
return [expr { $ind + 1 }]
}
return 1
}
# Determine the number of pages of an animated GIF.
set numPages [GetNumPages $imgFile "gif"]
Name
img - Introduction to Img
Notes
[1] Img version 2 only works with Tcl/Tk 8.6 or newer. If using an older Tcl/Tk version, use the
lastest Img 1.4 version.
[2] Formats marked with * are not loaded when doing a packagerequireImg, but must be loaded
explicitly via packagerequireimg::FORMAT.
See Also
img, img-bmp, img-dted, img-flir, img-gif, img-ico, img-jpeg, img-pcx, img-pixmap, img-png, img-ppm, img-
ps, img-raw, img-sgi, img-sun, img-tga, img-tiff, img-window, img-xbm, img-xpm
Synopsis
package require Img?2.0?
________________________________________________________________________________________________________________
Value Mapping
Some image formats support pixel values greater than storable in 8-bit integers.
• The following formats support 16-bit integer pixel values: img-dted, img-ppm.
• The following formats support floating point pixel values: img-flir, img-raw.
To map these values to 8-bit integer values as needed for a Tk photo, two different algorithms are
implemented in Img:
A simple MinMax algorithm and an advanced AutomaticGainControl(AGC) algorithm using histogram
equalization.
The default for all supported formats is to use the MinMax algorithm, which determines the minimum and
maximum values of the image automatically.
PNG Icons
Emojis