imgtools

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
COMMANDS
BUGS
SEE ALSO
KEYWORDS

NAME

imgtools - tools to modify Tk photo images.

SYNOPSIS

package require Tk 8.6

package require imgtools ?0.3?

::imgtools::gradient fromColor toColor ?option ?value?? ?...? destImage

::imgtools::rotate sourceImage angle ?option ?value?? ?...? destImage

::imgtools::scale sourceImage sizeSpec ?option ?value?? ?...? destImage

::imgtools::transparency subcommand sourceImage arg ... ?option ?value?? ?...? destImage

DESCRIPTION

imgtools is an extension to Tk that provides tools to modify photo images. It can scale and rotate images, modify transparency and create rectangular color gradients.

OPTIONS

The commands of the package support the following options.
-alpha value

Transparency to use for empty regions in the destination image - e.g. near the corners when rotating an image. value must be between 0 (transparent) and 1 (opaque). value may also be specified in percent. Defaults to 0.

-background color

Specifies the color to use for empty regions in the destination image - e.g. near the corners when rotating an image. color may have any of the forms accepted by Tk_GetColor. The default is black (#000000).

-clipping mode

Used to specify the size of the destination image for transformations where the resulting image can have empty areas. May be one of none (the whole source image is visible), keepsize (destination image will have the same size as the original) or noblanks (destination image will have no empty areas). Defaults to none.

-compositingrule rule

Specifies how transparent pixels in the source image are combined with the destination image. When a compositing rule of overlay is set, the old contents of the destination image are visible, as if the source image were printed on a piece of transparent film and placed over the top of the destination. When a compositing rule of set is set, the old contents of the destination image are discarded and the source image is used as-is. The default compositing rule is overlay.

-from x1 ?y1? ?x2? ?y2?

Specify a rectangular region in the source image to use as input. (x1,y1) and (x2,y2) specify diagonally opposite corners of the rectangle (in any order). The pixels affected include the left and top edges of the region, but not the bottom and right edges. The region must lie within the bounds of the source image. x2 and y2 may be omitted, in this case the region ends at the bottom right corner of the image. If a x coordinate is specified, but no correspondign y coordinate, y takes the same value as x. This is true even if y takes an invalid value. If no -from option is given, the whole source image is taken as input.

-interpolation method

Chose the interpolation method. Supported methods are: nearest neighbor (nearest), linear interpolation (linear), cubic interpolation with a Catmull-Rom filter (catrom) and sinc interpolation (lanczos2 and lanczos3). Defaults to catrom.

-orient orientation

Specify which orientation should be used, e.g. for gradients. Must be either horizontal or vertical.

-shrink

If passed, the size of the destination image will be reduced to the size of the modified image. This option will not affect the width or height of the image if the user has specified a non-zero value for the -width or -height configuration option, respectively.

-to x1 y1 x2 y2

Specify a rectangular region of the destination image to be affected. (x1,y1) and (x2,y2) specify diagonally opposite corners of the rectangle. The pixels affected include the left and top edges of the region, but not the bottom and right edges. The coordinates must be non-negative integers. They can be larger as the size of the destination image, however. See destImage below for the rules for size changes of destination image. If a x coordinate is specified, but no correspondign y coordinate, y takes the same value as x. If x2 and y2 are not specified, the default value is (x1,y1) plus the size of the processed source image. If no -to option is given, the region starts at (0,0) and is sized to contain the processed source image exactly. If the region is smaller than the data available, the exceeding portions are discarded. If the region is larger than the processed source image, it will be filled by replicating the image in a tiled fashion.

destImage

The image to use for output, must be an existing Tk photo image. The contents of destImgage will be (partially) overwritten, depending on the -compositingrule option. The size of destImage may change as well: its size is increased if the resulting image is larger than destImage. If the resulting image is smaller, destImage is shrinked only if the -shrink option is passed. If a user-size was set on destImage with the -with and/or -height options (see photo.n), the size of the image will not change. It is possible to use the same image as input and output image.

sourceImage

The image to use as input, must be an existing photo image. The image will not be modified, unless it is used as destImage as well.

COMMANDS

::imgtools::gradient fromColor toColor ?-compositingrule rule? ?-orient orientation? ?-to x1 y1 x2 y2? ?-shrink? destImage

Create a rectangular gradient from fromColor (top or left) to toColor (bottom or right) and write it to destImage. The colors may have any of the forms accepted by Tk_GetColor. The direction of the gradient can be specified with the -orient option, the default is vertical. The size and position of the area of the gradient can be specified with the -to option. Returns destImage.

::imgtools::rotate sourceImage angle ?-alpha value? ?-background color? ?-clipping mode? ?-compositingrule rule? ?-from x1 y1 x2 y2? ?-interepolation method? ?-shrink? ?-to x1 y1 x2 y2? destImage

Rotate the source image clockwise by angle degrees. angle may have any floating-point value, optionally followed by a ’°’ character. The degrees symbol is ignored - it is merely syntactic sugar. Negative angles cause conter-clockwise rotation. Returns destImage.

::imgtools::scale sourceImage sizeSpec ?-compositingrule rule? ?-from x1 y1 x2 y2? ?-interepolation method? ?-shrink? ?-to x1 y1 x2 y2? destImage

Scale the source Image to the given size. sizespec must have the form widthxheight. width and height may be either absolute or relative values. Absolute sizes are specified in pixels and must be integers. Relative sizes are given in percent, as a number followed by a percent sign (%). Relative values may have any of the valid forms for a double in Tcl. One of width or height may be omitted, in this case the aspect ratio of the image is preserved. If width is a relative number, the percent sign may be omitted for height. Negative sizes cause the image to be flipped about the respective axis. Returns destImage.

::imgtools::transparency subcommand sourceImage arg ... ?option ?value?? ?...? destImage

Modify or get the alpha channel of an image. The following subcommands are available:

::imgtools::transparency decrease sourceImage alphaValue ?-compositingrule rule ?-from x1 y1 x2 y2? ?-shrink? ?-to x1 y1 x2 y2? destImage

Make a copy of sourceImage and decrease its transparency. Transparency is decreased relative to the current alpha value of each pixel. This means that the whole image is made less transparent keeping the relative difference in transparency between pixels. alphaValue may be given as a real number between 0 and 1, or as a percentual value between 0% and 100%. An alpha value of 1 makes everything fully opaque, 0 keeps the current alpha of each pixel. It must be noted that making opaque fully tranparent pixels can yeld unexpected results, as fully transparent pixels may have any color (usually they are black, though).

::imgtools::transparency get sourceImage x y

Returns the transparency value of the pixel at x,y, as a floating point value between 0 (fully transparent) and 1 (fully opaque).

::imgtools::transparency increase sourceImage alphaValue ?-compositingrule rule? ?-from x1 y1 x2 y2? ?-shrink? ?-to x1 y1 x2 y2? destImage

Make a copy of sourceImage and increase the transparency of the image. Transparency is increased relative to the current alpha value of each pixel. This means that the image is made more transparent keeping the difference in transparency between different areas of the image. alphaValue may be given as a real number between 0 and 1, or as a percentual value between 0% and 100%. An alpha value of 1 keeps the current alpha of each pixel, 0 makes everything fully transparent.

::imgtools::transparency mask sourceImage maskImage ?-compositingrule rule? ?-from x1 y1 x2 y2? ?-shrink? ?-to x1 y1 x2 y2? destImage

Make a copy of sourceImage and replace its alpha channel with the one of maskImage. maskImage must be an existing photo image. The mask is applyed starting at the top left corner of the source image or of the region specified with the -from option. If it is smaller than the source region, it is applyed in a tiled fashion. If the mask is larger than the source image, the extra mask data is ignored.

::imgtools::transparency set sourceImage alphaValue ?-compositingrule rule? ?-from x1 y1 x2 y2? ?-shrink? ?-to x1 y1 x2 y2? destImage

Make a copy of sourceImage and set the transparency of the image to alphaValue. Any transparency information of the source image will be replaced with the specified value. alphaValue may be given as a number between 0 and 1 or in percent, in the range 0%...100%. An alpha of 0 is fully transparent, 1 (or 100%) is fully opaque. It must be noted that making opaque fully tranparent pixels can yeld unexpected results, as fully transparent pixels may have any color (usually they are black, though).

BUGS

This is a development release, so there are certainly many bugs and problems. Please report!

Please post bug reports, whishes, suggestions to the bugtracker on the imgtools project page: tkimgtools.sourceforge.net.

SEE ALSO

image(n) photo(n) Tk_GetColor(3)

KEYWORDS

image scale rotate photo gradient transparency