pixmix 1.0 Pictures Mixer

a widget for displaying,zooming,rotating,blending overlapped images.

SYNOPSIS

package require Tk 8.5

package require Img

package require pixmix ?1.0?

• pixmix pathName ?option value...?
• pathName cget option
• pathName configure ?option? ?value option value ...?
• pathName create layer name ?option value...?
• pathName layercget name option
• pathName layerconfigure name ?option? ?value option value ...?
• pathName loadFile name filename
• pathName loadPhoto name photo
• pathName imagesize name
• pathName rename name newName
• pathName delete name
• pathName layers
• pathName lower name ?belowThis?
• pathName raise name ?aboveThis?
• pathName savePhoto
• pathName saveFile filename ?photoOptions...?
• pathName move name dx dy
• pathName moveto name dx dy
• pathName scale name df ?Cx Cy?
• pathName scaleto name df ?Cx Cy?
• pathName rotate name angle ?Cx Cy?
• pathName rotateto name angle ?Cx Cy?
• pathName fit name ?what?
• pixmix::matrix identity
• pixmix::matrix translate dx dy
• pixmix::matrix rotate sx ?sy? ?CX CY?
• pixmix::matrix rotate angle ?CX CY?
• pixmix::matrix skewx angle
• pixmix::matrix skewy angle
• pixmix::matrix multiply mtx1 mtx2

DESCRIPTION

INTRODUCTION

pixmix is a widget for displaying,zooming,rotating,blending overlapped images. pixmix resembles the classic canvas widget but with some differences:

• it has been designed for working with (large) images.
• Images can be stacked in 'layers' and then zoomed, rotated and alpha-blended.
• it's fast - and for Windows platform only !

pixmix is just a widget, not a full app, but you can browse some of the small included demos to discover how to build full apps.

LAYERS

pixmix can display any number of images organized in layers. Each layer can hold one image, and layers are ordered for purposes of display, with the first layer in the layer-list being displayed first, followed by the next layer in the list, and so on. Layers later in the layer-list obscure those that are earlier in the layer-list and are sometimes referred to as being “on top” of previous. When a new layer is created it is placed at the end of the layer-list, on top of everything else. Widget commands may be used to re-arrange the order of the layer-list.

COORDINATES and GEOMETRIC TRANSFORMATIONS

Each image loaded in a layer is placed at coord (0,0), with no scaling and no rotation. In order to move,scale,rotate the image, you must manipulate the layer's matrix parameter. Geometric (affine) transformations are performed with a 3x3 homogeneous matrix.

  |m11  m12  0|
  |m21  m22  0|
  |dx   dx   1|

Since the 3rd column MUST always be (0 0 1), you only need to specify the other six coefficients (m11 m12 m21 m22 dx dy). As alternative to direct matrix manipulation, some auxiliary methods like move, rotate and many others are provided. See also the section Working with Matrices

WIDGET COMMANDS

The pixmix command creates the pathName widget and returns a new Tcl command whose name is pathName.

pixmix pathName ?option value...?

WIDGET OPTIONS

-background color

Specifies the background color used for filling the widget area.

-cursor cursor

Specifies the mouse cursor to be used for the widget. The value may have any of the forms acceptable to Tk_GetCursor. In addition, if an empty string is specified, it indicates that the widget should defer to its parent for cursor specification.

WIDGET SUBCOMMANDS

The following subCommands are possible for pixmix widgets:

pathName cget option

Returns the current value of the configuration option given by option. Option may have any of the values accepted by the pixmix command.

pathName configure ?option? ?value option value ...?

Queries or modifies the configuration options of the widget. If no option is specified, returns a list describing all of the available options for pathName (see Tk_ConfigureInfo for information on the format of this list). If option is specified with no value, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more option-value pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. Option may have any of the values accepted by the pixmix command.

pathName create layer name ?option value...?

Creates a new layer named name ( name must be unique ). New layer is placed on top of other layers. Each layer can be configured with the following options:

-alpha number

Specifies the layer's alpha (opacity) coefficient; number may vary from 0.0 (transparentn) to 1.0 (opaque)

-visible boolean

Specifies if layer should be visible or not.

-clip RegiorOrEmptyString

Region is a list of four integers {x1 y1 x2 y2} specifying a rectangular sub-region of the image to be dispayed. In order to reset the clip-region and then display the whole image, you should specify the empty string or {}. Note that the the origin of the clipped region is translated to (0,0). It's not an error if coordinates of the clip-region are larger than the image's real size.

-matrix matrixOrEmptyString

matrix is a list of six numbers used for setting geometric transformations such as scale, rotation, translation. If matrix is the empty string or {}, then transformation is reset, i.e. the Identity-matrix is used. See the above section COORDINATES and GEOMETRIC TRANSFORMATIONS. Note that some auxiliary methods may alter the -matrix value, in a more comfortable way. NOTE: A new layer is invisible if no image is loaded (seed loadFile and loadPhoto)

 # create a layer named abc
.c create layer abc
 # create a layer with some options set ...
.c create layer layer#A -visible false
.c layerconfigure layer#A -alpha 0.8

pathName layercget name option

Returns the current value of the configuration option option for the layer name. This command is similar to the cget widget command except that it applies to a particular layer rather than the widget as a whole. Option may have any of the values accepted by the create layer command.

pathName layerconfigure name ?option? ?value option value ...?

This command is similar to the configure widget command except that it modifies layer-specific options instead of modifying options for the overall pixmix widget. If no option is specified, returns a list describing all of the available options and their actual values for the layer given by name. If option is specified with no value, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more option-value pairs are specified, then the command modifies the given layer option(s); in this case the command returns an empty string. The options and values are the same as those permissible in the create layer. See the create layer command for details on the legal options and values.

pathName loadFile name filename

Loads content of filename (Jpeg, png, ...) in layer name. Note that it's your responsability to load a package for supporting extra image formats. ( e.g. package Img )

pathName loadPhoto name photo

Loads content of photo in layer name

pathName imagesize name

Returns a list of two integers: width and height (in pixels) of the image loaded in layer name. If no image has been loaded, return {0 0}

pathName rename name newName

Renames layer name to newName

pathName delete name

Deletes layer name

pathName layers

Lists all layers ; first layer is the bottom one, last layer is displayed on top.

pathName lower name ?belowThis?

If belowThis is not specified, this command moves layer name at bottom, otherwise it moves layer name just below belowThis.

pathName raise name ?aboveThis?

If aboveThis is not specified, this command moves layer name at top, otherwise it moves layer name just over aboveThis.

pathName savePhoto

Saves the overall resulting image in a new photo (see photo standard command). Returns the name of the photo

pathName saveFile filename ?photoOptions...?

Saves the overall resulting image in filename. It is recommended to explicitely use all the photoOptions as described for the standard image write command.

.c saveFile c:/tmp/shot.jpg -format jpeg

Auxiliary subcommands

The following subcommand are programmer's helper . All these subcommands modify the layer's -matrix option.

pathName move name dx dy

Applies a (dx,dy) translation to layer name.

pathName moveto name dx dy

Sets a (dx,dy) translation to layer name; scale and rotation don't change.

pathName scale name df ?Cx Cy?

Applies a further df scale-factor to current transformation. Optional (Cx,Cy) is the zoom-center (default is (0,0).

pathName scaleto name df ?Cx Cy?

Sets the df scale-factor. Translation and rotation don't change. Optional (Cx,Cy) is the zoom-center (default is (0,0).

pathName rotate name angle ?Cx Cy?

Apply a rotation of angle radians to layer name. Optional (Cx,Cy) is the center of the rotation (default is (0,0). Note that the rotation 'seems' inverse just because the Y axis is inverted !

pathName rotateto name angle ?Cx Cy?

Sets a rotation of angle radians to layer name. Optional (Cx,Cy) is the center of the rotation (default is (0,0). Note that the rotation 'seems' inverse just because the Y axis is inverted !

pathName fit name ?what?

Displays the image loaded in layer name at its 'best fit', i.e centered and fully visbile in the current window. Option what specifies which dimension should be used for computing the best-fit ; valid values are x (best-width), y (best-height)and xy(best-fit). Default is xy.

Working with Matrices

We recall that geometric transformations on layers should be made by setting the -matrix option. A matrix is a list of six numbers (m11 m12 m21 m22 dx dy). Working with these matrices can be simplified by using the pixmix::matrix command.

pixmix::matrix identity

Returns the identity matrix {1 0 0 1 0 0}

pixmix::matrix translate dx dy

Returns the matrix for (dx,dy) translation

pixmix::matrix rotate sx ?sy? ?CX CY?

- Returns the matrix for scaling by factor sx in x-dimension and sy in y-dimension. If sy is not specificied it is assumed to be equal to sx. CX,CY is the center of transformation

pixmix::matrix rotate angle ?CX CY?

Returns the matrix for an angle rotation (in radians). CX,CY is the center of transformation

pixmix::matrix skewx angle

Returns the matrix for a skew-distorsion on x-dimension. angle is expressed in radians.

pixmix::matrix skewy angle

Same as matrix skewx, just for the y-dimension

pixmix::matrix multiply mtx1 mtx2

Returns a new matrix as the product (composition) of matrix mtx1 and mtx2.

BINDINGS

pixmix does not provide any default behavior. Bindings may be set to respond to some event (typically mouse-related events), like in the mini-apps included in the demos directory.

EVENTS

pixmix does not generate any virtual-event.

Examples

See the mini-apps within the demos directory.

BUGS, IDEAS, FEEDBACK

• -
• -