[ABU] 2-Oct-2013 **EDITING IN PROGRESS** '''pixmix''' - a widget for displaying,zooming,rotating,blending overlapped images. Coming soon .... ''Just a screenshot of an included demo app'' [Image pixmix-screenshoot1] **A new widget, not a Megawidget** '''pixmix''' is entirelly written in Tcl, but it is based on [WinGdi], a custom library providing -at Tcl-level- support for a small part of the Windows Graphic Device Interface. Therefore it works only on Windows platforms. **Download** * pixmix 1.0 [http://irrational-numbers.googlecode.com/files/pixmix-1.0.zip] Demos and full documentation included. Package comprises all the required libs. <> Reference manual '''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** * - * - <> <>Widget