pix 0.9: Reference Manual

::pix::imgTop, Main, Index

CommandsTop, Main, Index

applyOpacity [::pix::img]Top, Main, Index

Multiplies the alpha channel of the entire image by a given factor.

applyOpacity image opacity
Parameters
imageimg
opacityfactor between 0.0 (transparent) and 1.0 (opaque).
Return value

Nothing.

blur [::pix::img]Top, Main, Index

Applies a Gaussian blur to the image.

blur image radius ?color?
Parameters
imageimg
radiusblur intensity (double)
coloroptional background color for the blur effect Optional, default "".
Return value

Nothing.

ceil [::pix::img]Top, Main, Index

A value of 0 stays 0. Anything else turns into 255.

ceil image
Parameters
imageimg
Description

The pix::img::ceil proc takes an image and replaces all pixels that are not fully transparent (i.e. have an alpha of 0) with a pixel that is fully opaque (i.e. has an alpha of 255). This is useful for creating masks from images.

Return value

Nothing.

copy [::pix::img]Top, Main, Index

This procedure creates a new image by copying the contents of the given image object.

copy image
Parameters
imageimg
Return value

A new handle img object.

destroy [::pix::img]Top, Main, Index

Destroy the img or all images if special word all is specified.

destroy value
Parameters
valueimg object or string
Return value

Nothing.

diff [::pix::img]Top, Main, Index

Compares two images and calculates their difference.

diff masterimage image
Parameters
masterimageThe reference img
imageThe img to compare against the reference
Return value

A Tcl dictionary containing the following keys:

score A value between 0 (identical) and 1 (completely different).
img A new img object visualizing the differences.

draw [::pix::img]Top, Main, Index

Draws a source image onto a destination image using an optional transformation matrix and blend mode.

draw image1 image2 ?matrix3? ?blendMode?
Parameters
image1destination img
image2source img
matrix3A list of 9 values Optional, default identityMatrix.
blendModeEnum value Optional, default NormalBlend.
Return value

Nothing.

drawCopies [::pix::img]Top, Main, Index

Draws a path at many positions: filled, then stroked, like one shape drawn after the other.

drawCopies image path coordinates fillColor strokeColor ?options?
Parameters
imageimg
pathpath the shape, around {0 0}
coordinatesA flat list {x1 y1 x2 y2 ...}
fillColorstring color
strokeColorstring color
optionsA Tcl dict, the options of img::strokePath . Optional, default "".
Description

The options are those of img::strokePath: strokeWidth (in path units, 0 to fill only), transform (the matrix of the whole drawing: the shapes take its linear part, the positions the whole matrix), lineCap, lineJoin, miterLimit, dashes and blendMode (Enum, optional:NormalBlend): how each copy combines with the image, e.g. SubtractMaskBlend erases the image under the copies (their colors are then not used).
The shape is rendered once for each quarter-pixel offset, then copied at every position (the nearest quarter pixel), in the order of the list.

Return value

Nothing.

fill [::pix::img]Top, Main, Index

Fills the entire image with a solid color or a paint pattern.

fill image color
Parameters
imageimg
colorA color string or paint object
Description

If a paint object is provided, it must be created via pix::paint::new.

Return value

Nothing.

fillGradient [::pix::img]Top, Main, Index

Fills with the Paint gradient.

fillGradient image paint
Parameters
imageimg
paintpaint
Return value

Nothing.

fillPath [::pix::img]Top, Main, Index

Fills a path with a color or paint object.

fillPath image pathValue paintValue ?matrix?
Parameters
imageThe destination img object.
pathValueA path object or a SVG path string (e.g., "M 0 0 L 100 0...").
paintValueA color string or a paint object.
matrixAn optional 3x3 transformation matrix . Optional, default identityMatrix.
Return value

Nothing.

fillText [::pix::img]Top, Main, Index

Fills the image with the rendered text.

fillText image object ?args?
Parameters
imageimg
objectfont::typeset or font::readFont object
argsA Tcl dict (options described below)
Description

There are two ways to use this proc:

  1. With an font::typeset object:
  1. With a font object and a text string:

In either case, the img object is the first argument, and the font::typeset or font::readFont object is the second argument.

Return value

Nothing.

flipHorizontal [::pix::img]Top, Main, Index

This method modifies the image in place, flipping it around the Y-axis.

flipHorizontal image
Parameters
imageimg
Description

As a result, the left and right sides of the image are swapped. This operation is useful for creating mirror images or for certain graphical effects.

Return value

Nothing.

flipVertical [::pix::img]Top, Main, Index

This method modifies the image in place, flipping it around the X-axis.

flipVertical image
Parameters
imageimg
Description

As a result, the top and bottom sides of the image are swapped. This operation is useful for creating mirror images or for certain graphical effects.

Return value

Nothing.

get [::pix::img]Top, Main, Index

Gets image size.

get image
Parameters
imageimg
Return value

A Tcl dictionary with keys containing the width and the height of the img.

getColor [::pix::img]Top, Main, Index

Gets a color at {x y} or returns transparent black if outside of bounds.

getColor image coordinates
Parameters
imageimg
coordinatesA list {x y}
Return value

A Tcl dictionary with keys {r g b a} representing the red, green, blue, and alpha (opacity) values of the pixel color in Color object format (red (0-1), green (0-1), blue (0-1), alpha (0-1)).

getPixel [::pix::img]Top, Main, Index

Gets a pixel at {x y} or returns transparent black if outside of bounds.

getPixel image coordinates
Parameters
imageimg
coordinatesA list {x y} (x column of the pixel, y row of the pixel)
Return value

A Tcl dictionary with keys {r g b a} representing the red, green, blue, and alpha (opacity) values of the pixel color in ColorRGBX (premultiplied).

getSize [::pix::img]Top, Main, Index

See img::get procedure.

getSize

inside [::pix::img]Top, Main, Index

Returns true if {x y} is inside the image, false otherwise.

inside image coordinates
Parameters
imageimg
coordinatesA list {x y}
Return value

Returns true if {x y} is inside the image, false otherwise.

invert [::pix::img]Top, Main, Index

Inverts all of the colors and alpha.

invert image
Parameters
imageimg
Description

This will flip the image by changing the color and alpha of every pixel. The result will be a new image where every pixel is the exact opposite of the corresponding pixel in the original image.

For example, if the original image is entirely white, the resulting image will be entirely black. If the original image is entirely black, the resulting image will be entirely white. This is useful for things like getting the negative of an image, or creating a reverse version of an image.

Return value

Nothing.

isOneColor [::pix::img]Top, Main, Index

Checks if the entire image is the same color.

isOneColor image
Parameters
imageimg
Return value

A Tcl boolean value.

isOpaque [::pix::img]Top, Main, Index

Checks if the entire image is opaque (alpha values are all 255).

isOpaque image
Parameters
imageimg
Return value

A Tcl boolean value.

isTransparent [::pix::img]Top, Main, Index

Checks if this image is fully transparent or not.

isTransparent image
Parameters
imageimg
Return value

Returns true, false otherwise.

magnifyBy2 [::pix::img]Top, Main, Index

Scales image up by 2 ^ power.

magnifyBy2 image ?power?
Parameters
imageimg
powerInteger value Optional, default 1.
Description

If only one argument is given (i.e. the image object), just magnify by 2. This is a convenience for the user.

Return value

A new handle img object.

minifyBy2 [::pix::img]Top, Main, Index

Scales the image down by an integer scale.

minifyBy2 image ?power?
Parameters
imageimg
powerInteger value Optional, default 1.
Description

We were given an integer power as an argument, so we call img.minifyBy2() with that power. This will scale the image down by 2^power.

Return value

A new handle img object.

new [::pix::img]Top, Main, Index

Creates and returns a new image object.

new size
Parameters
sizeA list {width height}
Return value

A new handle img object.

opaqueBounds [::pix::img]Top, Main, Index

Checks the bounds of opaque pixels.

opaqueBounds image
Parameters
imageimg
Description

Some images have transparency around them, use this to find just the visible part of the image and then use subImage to cut it out. Returns zero rect if whole image is transparent, or just the size of the image if no edge is transparent.

Return value

Returns A Tcl dictionary with keys {x y w h}.

readImage [::pix::img]Top, Main, Index

Reads an image file from the disk and creates a new image object.

readImage filePath
Parameters
filePathfull path to the image file (.png, .jpg, *.svg, etc.)
Return value

A handle to the new img object.

resize [::pix::img]Top, Main, Index

Resize an image to a given height and width.

resize image size
Parameters
imageimg
sizeA list {width height}
Return value

A new img handle.

rotate90 [::pix::img]Top, Main, Index

Rotates the image 90 degrees clockwise.

rotate90 image
Parameters
imageimg
Return value

Nothing.

setColor [::pix::img]Top, Main, Index

See img::setPixel procedure.

setColor

setPixel [::pix::img]Top, Main, Index

Sets a pixel at {x y} or does nothing if outside of bounds.

setPixel image coordinates color
Parameters
imageimg
coordinatesA list {x y}
colorstring color
Return value

Nothing.

shadow [::pix::img]Top, Main, Index

Create a shadow of the image with the offset, spread and blur.

shadow image options
Parameters
imageimg
optionsdict (offset, spread, blur, color)
Return value

Nothing.

strokePath [::pix::img]Top, Main, Index

Strokes a path with a color or a paint object and optional stroke and line join options.

strokePath image value color options
Parameters
imageThe img object to draw on.
valueA string path or a path object created with the pix::path::new Tcl proc.
colorA string color or a paint object created with the pix::paint::new Tcl proc.
optionsA Tcl dict, see attributes below.
Description
Return value

Nothing.

strokeText [::pix::img]Top, Main, Index

This procedure is responsible for rendering text onto an image with various styling options.

strokeText image object text options
Parameters
imageimg.
objectThis can either be a 'arrangement' or a font object.
textIf the object is a font object, this parameter is the text string that needs to be rendered on the image.
optionsCheck out the description below.
Description
Return value

Nothing.

subImage [::pix::img]Top, Main, Index

Gets a sub image from this image.

subImage image coordinates size
Parameters
imageimg
coordinatesA list {x y}
sizeA list {width height}
Description

The subImage function extracts a portion of the original image starting at {x y} and spanning the width and height specified.

Return value

A new handle img object.

superImage [::pix::img]Top, Main, Index

Either cuts a sub image or returns a super image with padded transparency.

superImage image coordinates size
Parameters
imageimg
coordinatesA list {x y}
sizeA list {width height}
Description

If the coordinates and size of the superImage are within the bounds of the original image, a sub image is cut from the original image.

If the coordinates and size of the superImage are outside the bounds of the original image, a super image is created with the original image centered and padded with transparency. The resulting super image is always the size specified in the arguments.

If the resulting super image is different from the original image, a new image is created. If the resulting super image is the same as the original image, the original image is returned.

Return value

A new handle img object.

toGrayScale [::pix::img]Top, Main, Index

Converts an image to grayscale.

toGrayScale img ?handleAlpha?
Parameters
img object
handleAlphaBoolean value that indicates whether to handle the alpha channel . Optional, default true.
Return value

nothing.

writeFile [::pix::img]Top, Main, Index

Save image file.

writeFile image filePath
Parameters
imageimg
filePathstring (*.png|*.bmp|*.qoi|*.ppm)
Return value

Nothing.