img(3tk)

📦
version 2.1.1 · 4 versions
, in ubuntu resolute, ubuntu stonking

💖 NAME 💖

img — Introduction to Img 🫶

✨ SYNOPSIS ✨

package require Img ?2.1?

🌸 DESCRIPTION 🌸

okay so bestie, sit down, hydrate, because Img is a whole collection of format handlers for the Tk photo image type — yes, that Tk photo, the one at https://www.tcl.tk/man/tcl9.0/TkCmd/photo.html. it's giving "every image format you could ever want, all in one package" and honestly? iconic. 👑

Sources and binaries of Img are out here living their best life on SourceForge: https://sourceforge.net/projects/tkimg/. 🦋

every single format has its own whole page with all the deets, so go read those. here's the roster, no cap:

  • 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. based on libjpeg 9f. see img-jpeg.
  • pcx — Paintbrush format. see img-pcx.
  • pixmap — Pixmap image type. plot twist: while all the other formats are handlers for the Tk photo image type, this one is an entirely new image type for Tk. main character energy fr. see img-pixmap.
  • png — Portable Network Graphics format. based on libpng 1.6.47. see img-png.
  • ppm — Portable pixmap format. see img-ppm.
  • ps* — Postscript and PDF format. needs an external application — ghostview — to actually do its thing. 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. based on libtiff 4.7.0. 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 you're on an older Tcl/Tk version, use the latest Img 1.4 version instead. no exceptions bestie. 💀
  2. Formats marked with * are not loaded when you do a package require Img — you have to load them explicitly via package require img::FORMAT.

🦋 MULTI-PAGE IMAGES 🦋

Some image formats support storage of multiple pages in a file. slay.

Supported by formats img-gif, img-ico, img-ps, img-tiff.

You can extract a specific page 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 the 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, because 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 their own individual set of metadata dictionary keys. peep the Tk photo image command at https://www.tcl.tk/man/tcl9.0/TkCmd/photo.html for more info about 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 a 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 a 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 that support image resolution (DPI and aspect) have the following format options for writing these values without you having to explicitly set the metadata dictionary:

-resolution -xresolution -yresolution

  1. Option -resolution lets you specify both horizontal and vertical resolution values.
  2. If you're not using option -resolution, then options -xresolution and -yresolution must both be specified. Otherwise no resolution information is written at all. 😭
  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 a 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 what's storable in 8-bit integers. big values, big vibes.

  • The following formats support 16-bit integer pixel values: img-dted, img-ppm img-raw.
  • The following formats support floating point pixel values: img-flir, img-raw.

To map these values to 8-bit integer values (which is what a Tk photo needs), two different algorithms are implemented in Img:

a simple MinMax algorithm, and an advanced Automatic Gain Control (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.

🌈 MATCHING ORDER 🌈

When reading images without specifying the format (i.e. without using option -format), the match functions of the available formats are tried in reversed order as registered. So the handlers of the Img package get 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 the manual page of function Tk_CreatePhotoImageFormat (https://www.tcl.tk/man/tcl9.0/TkLib/CrtPhImgFmt.html) for a detailed description of the handler structure and matching functions.

The resulting matching order is best explained by an example:

package require Tk
package require Img
package require img::raw     (Format2 Img handler)

Note that the package require Img command actually calls the following statements:

package require img::window  (Format2 Img handler)
package require img::tga     (Format2 Img handler)
package require img::ico     (Format3 Img handler)
package require img::pcx     (Format3 Img handler)
package require img::sgi     (Format2 Img handler)
package require img::sun     (Format2 Img handler)
package require img::xbm     (Format2 Img handler)
package require img::xpm     (Format2 Img handler)
package require img::jpeg    (Format3 Img handler)
package require img::png     (Format3 Img handler)
package require img::tiff    (Format3 Img handler)
package require img::bmp     (Format3 Img handler)
package require img::ppm     (Format2 Img handler)

The order of calling the match functions is therefore as follows:

Match format raw       (Format2 Img handler)
Match format ppm       (Format2 Img handler)
Match format xpm       (Format2 Img handler)
Match format xbm       (Format2 Img handler)
Match format sun       (Format2 Img handler)
Match format sgi       (Format2 Img handler)
Match format tga       (Format2 Img handler)
Match format window    (Format2 Img handler)
Match format svg       (Format2 Tk handler)
Match format ppm       (Format2 Tk handler)
Match format default   (Format2 Tk handler)
Match format bmp       (Format3 Img handler)
Match format tiff      (Format3 Img handler)
Match format png       (Format3 Img handler)
Match format jpeg      (Format3 Img handler)
Match format pcx       (Format3 Img handler)
Match format ico       (Format3 Img handler)
Match format png       (Format3 Tk handler)
Match format gif       (Format3 Tk handler)

⭐ 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

Copyright (c) 1995-2025 Jan Nijtmans <nijtmans@users.sourceforge.net>
Copyright (c) 2002-2025 Andreas Kupries <andreas_kupries@users.sourceforge.net>
Copyright (c) 2003-2025 Paul Obermeier <obermeier@users.sourceforge.net>

and that's the whole page bestie!! 🎀 this was img(3tk), straight outta Img version 2.1, and yes it's still sitting pretty in section 3tk of the manual. go read the format pages, you're gonna eat. 💅💖✨

📦 where this page comes from