NAME

pixane - Create and manipulate images from Tcl

SYNOPSIS

pixane option ?arg arg...?

DESCRIPTION

The pixane command is used to create, delete, and query images from Tcl (Tk not required). It is a Tcl wrapper around the Pixane C library. It can take several different forms, depending on the option argument. The legal forms are:

pixane create ?name? ?option value ...?
Creates a new image and returns its name. name specifies the name for the image; if it is omitted then Pixane picks a name of the form pixanex, where x is an integer. There may be any number of option-value pairs, which provide configuration options for the new image. If an image already exists by the given name then an error is returned. Supported options are :

-palette boolean
Specifies if the image should be created with a palette. If false or unspecified, a truecolor image will be created.
-tkphoto tkphoto
Bind pixane handle to an existance TK photo instance. This option is available only if Tk is present into interpreter. Drawing into pixane image will be automatically rendered into Tk photo.

pixane delete ?image image ...?
Deletes each of the named images and returns an empty string.
pixane load image ?options?
Load image content from file or memory buffer. Supported options are :

-file filename
filename gives the name of a file that is to be read to supply data for the image. The file format must be one of those for which there is an image file format handler that can read data.
-channel channelname
channelname gives the name of an opened channel that is to be read to supply data for the image. The file format must be one of those for which there is an image file format handler that can read data.
-data data
Specifies the contents of the image as a binary string. The format of the string must be one of those for which there is an image file format handler that will accept string data. If both the -data and -file options are specified, the -file option takes precedence.
-format format-name
Specifies the name of the file format for the data specified with the -data, -channel or -file option.

pixane save image ?options?
Save image content into file or memory buffer. If no output file or channel is specified, it returns the image content as a binary string. Supported options are :

-file filename
name gives the name of a file when image content will be saved.
-channel channelname
name gives the name of an opened channel when image data will be sent
-data
returns image content as binary string. This is default if no other output option (-file or -channel) is specified.
-format format-name
Specifies the name of the image file format handler to be used to write the data to the file. Specifically, this subcommand searches for the first handler whose name matches an initial substring of format-name and which has the capability to write an image file. If this option is not given, this subcommand uses the first handler that has the capability to write an image file.

pixane width image
Returns a decimal string giving the width of image name in pixels.
pixane height image
Returns a decimal string giving the height of image name in pixels.
pixane resize image width height
Specifies new width and height for the image, in pixels.
pixane text image x y
Draw text in image at the location given by x and y.Supported options are :

-text string
String specifies the characters to be drawn in the image. Newline characters cause line breaks. This option defaults to an empty string.
-font fontName
Specifies the font to use for rendering text. FontName must be a valid handle returned by pixfont.
-size fontsize
Specifies the font size to use. Default to 10.
-angle angle
Specifies the angle (in radians, clockwise) for text. Default to 0.0, which means horizontal.
-stretch factor
Ratio for rendering text. Default to 1.0.
-align how
Specifies horizontal alignment. How must be one of left (default), center or right.
-valign how
Specifies vertical alignment. How must be one of top, middle, baseline (default) and bottom.

pixane color image colorname
Set active foreground color used by drawing primitives. Colorname can be one of #RRGGBBAA, #RRGGBB, a list of 3 or 4 integers in the range [0,255], a single integer in the range [0,255] for a gray level, or one standard color name (e.g. white, black, red, gree, blue, ...)
pixane bgcolor image colorname
Set active foreground color used by drawing primitives. See color option for valid formats of colorname.
pixane compose image rule
Set active compositing rule for image. Rule must be one of replace, over, under, add, subtract, bump and map.
pixane quality image ?quality?
Get (if no argument is specified) or set image quality factor, as an integer in from 0 (lowest quality) to 100 (best quality). This is used only when saving image.
pixane plot image x1 y1 ?x2 y2 ...?
Plot pixels using foreground color.
pixane line image x1 y1 ... xn yn ?options?
Draw segments using foreground color. The arguments x1 through yn give the coordinates for a series of two or more points that describe a series of connected line segments. Supported options are :

-antialiased bool
Enable anti-aliasing when drawing line (default to false)
-arrow value
no effect
-arrowshape value
no effect
-capstyle value
no effect
-joinstyle value
no effect
-smooth value
no effect
-splinesteps value
no effect
-width int
Set line width (default to 1). As of 2008-07-01, implementation is incomplete for thick lines

pixane arc image cx cy rx ?ry? ?dxmin?
Draw an arc centered in (cx,cy).
pixane oval image cx cy rx ?ry? ?dxmin? ?dxmax? ?dymin? ?dymax?
Draw an oval. This is similar to arc option, except oval interior is filled using active background color.
pixane rectangle image x y width height
Draw a rectangular box from (x,y) inclusive to (x+width,y+height) exclusive.
pixane polygon image x1 y1 ... xn yn ?option value option value ...?
pixane polygon image coordList ?option value option value ...?
Not yet implemented (unstable).
pixane fill image
Fill image with current foreground color, using active compositing mode.
pixane blank image
Blank image, that is fill it with transparent pixel.
pixane copy image srcimage ?-from srcx srcy? ?-to destx desty? ?-width width? ?-height height?
Copy content of srcimage into image.
pixane scale image srcimage ?-from srcx srcy? ?-to destx desty? ?-width width? ?-height height? ?-angle angle? ?-quality n?
Copy content of srcimage into image, resizing it to fit into target region. Scaling factor, deduced from source and target geometries, doesn't have to be an integer. Angle specifies rotation (in radians, clockwise) to apply and default to 0.0. Quality is an integer in the range 0 (fastest, lowest quality) to 9 (slowest, best quality). If not specified or negative, library will automatically choose a good (nearly optimal) value according to images properties.
pixane blur image ?radius?
Apply a Gaussian blur to image. Default radius is 1.
pixane median image ?radius?
Apply a median filter to image. Default radius is 1.
pixane wind image dx dy
Apply a wind filter to image, where wind vector is equal to (dx,dy).
pixane gradient image ?x1 y1? ?x2 y2?
Fill image with a gradient from foreground color in (x1,y1) to background color in (x2,y2).
pixane noise image ?level?
Apply a noise filter on image. Level must be a integer ranging from 0 (no noise) to 255 (pure random image). Default level is 15.

Tk extensions

Pixane is a Tcl only extension, and doesn't depend on Tk to handle images. However, if Tk is present in interpreter, pixane exposes some additional features to modify and transform Tk photo handles.

The pixcopy command is used to convert a pixane image into a Tk photo, or a Tk photo into a pixane image.

pixcopy image ?tkphoto?
Convert pixane image image into a Tk photo. If tkphoto is not provided, a non existing Tk image name will be automatically generated.
pixcopy tkphoto ?image?
Convert Tk photo tkphoto into a pixane image. If image is not provided, a non existing pixane name will be automatically generated.

SUPPORTED FORMATS

Pixane include support for reading and writing a large variety of graphic formats.

Format Notes
GIF To avoid entanglement with the Unisys LZW patent, GIF reading support may (and used to) be disabled. Instead of default LZW compression, write support can use a RLE-based algorithm for same reason. Since patent has expired, LZW support can now be safely enabled.
PNG relies on libpng
JPEG relies on libjpeg
TIFF relies on libtiff.
LZW support may be disabled (see patent issue about GIF).
BMP support only uncompressed BMP
EPS (Encapsulated Postscript) write support only
PPM  
RGB (Iris RGB)  
XPM  
PCX  
WBMP  

CREDITS