[ Table Of Contents ]

img(n) 2.0 doc "Img"

Name

img - Introduction to Img

Table Of Contents

Synopsis

  • package require Img ?2.0?

Description

Img is a Tk extension, adding support for many image formats.

Sources and binaries of Img are available at SourceForge.

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.

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 package require Img, but must be loaded explicitly via package require img::FORMAT.

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 Image Metadata) 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"]

Image Metadata

Some image formats support an individual set of metadata dictionary keys. See the Tk photo 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. Options -xresolution and -yresolution must both be specified. Otherwise no resolution information is written.

  2. Resolution values specified with any of the above options overwrite the corresponding dictionary values.

  3. The resolution values can be specified as double values as documented with function Tk_GetPixels.

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}

Value Mapping

Some image formats support pixel values greater than storable in 8-bit integers.

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 algorithmn and an advanced Automatic Gain Control (AGC) algorithmn 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.

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