Difference between revisions of "Transformation tool specification"

From GIMP GUI Redesign
Jump to: navigation, search
(transformation constraints)
(transformation constraints)
Line 144: Line 144:
 
;centre/corner rotate
 
;centre/corner rotate
 
:works on rotation axis, toggled by <ctrl>
 
:works on rotation axis, toggled by <ctrl>
 +
 +
the scale constraints—keep aspect and from centre—have been aligned with the selection tools and the rest of the world.

Revision as of 19:31, 6 March 2009

intro

This is the specification for the unified transformation tool.

This tool has been designed to achieve some very specific goals:

  1. it is a tool for users who know what they are doing, at a pace of around two actions per second; this tool stays out of their way and does not make them think;
  2. it is a tool to work on pixels creatively, more by feeling than by numbers; this gives us the confidence to ban working with numbers for transformations where this can be useful—scale, move, rotate—to other tools or menu commands;
  3. combining bot points above, we try to enable a positive feedback loop where the result of the last transformation input inspires the next few steps;
  4. it is a tool to supersede the move, scale and shear tools, in a drive to slim down the toolbox; this means that simple things need to remain simple;
  5. it is a tool that provides a more freewheeling alternative to the rotate and perspective tools; as a follow-up to this design the rotate and perspective need a serious refresh—to for instance support getting horizons really horizontal and verticals really vertical for photographers.

on units, sizes and visible

All sizes in this spec are in on-screen pixels. This means that the zoom level has an influence on everything. A 30x20 in-image rectangle can be displayed on screen as 300x200, and vice versa.

Also the panning of the image has an influence on everything. Only the visible part of the transform frame goes into the size calculations.

decision time

The right moment to recalculate the transform frame shall be after—through zooming, panning or actual transformation change—the on-screen pixel size of the transform frame has changed. It is explicitly not desirable to do this during zooming, panning or actual transformation changes.

doing the work

In the interest of both GIMP and users, the transformation tool shall be very lazy about doing real calculations on image pixels. This actual calculation shall only be performed when users go and do something else: e.g. select another tool, switch layer, invoke a plugin, save the file, etc. This is also a contract with users that maximum fidelity is assured by conceptually taking the pixels as they were when the transformation tool was selected and transforming only once with an aggregate transformation—which shall combine every single step thet users did after entering the tool.

undo

Before the final pixel recalculation is done, very single step thet users did after entering the tool shall be able to be undone. After the final pixel recalculation is done only the aggregate transformation shall be able to be undone.

pixels, selections, paths and guides

The first thing we have to do is to untangle the mess of the different modes—layer, selection, paths—as used in the 2.6 transform tools. We do that with the following strategy:

  • selections are transformed in any selection tool;
  • paths are transformed in the path tool;
  • pixels are transformed in the transform tool;
  • guides are moved with the transform tool.

intermezzo: tool icon

the tool icon for the transform tool shall be the ‘mouse arrow‘—example: Transform tool icon.png. This enables the tool to be instantly recognised for moving and scaling pixels, and for moving guides.

transforming selections

In any selection tool, in ‘marching -ants state’ (nothing hairy happening), either the pending selection or else (each, in a multi-selection future) committed selection shall have a transform icon—Transform icon.png, 32 pix diameter, 25% opacity—associated with it on-canvas. Clicking it shall invoke the transform mode:

  • the transform icon shall change into a similarly styled icon representing the current selection tool; clicking it shall commit the transformation (if any) and return to the state the selection tool was in just before invoking the transform mode;
  • only the marching-ants outline of this (pending) selection shall remain and the smallest initial transform frame that can contain this outline shall be overlaid;
  • the selection tool shall remain the official active tool in the toolbox, but the tool options shall be swapped out for the ones of the transform tool;
  • the transform tool shall operate on the marching ants outline.

Invoking and ending the transform mode needs a cool key short-cut, similar to the spacebar trick. <alt> is a possibility, I am open to suggestions.

transforming paths

This shall work fully analogue to transforming selections. When not in building-paths mode, each path shall have the same transform icon associated with it on-canvas. Clicking it shall invoke the transform mode:

  • the transform icon shall change into a similarly styled icon representing the path tool; clicking it shall commit the transformation (if any) and return to the state the path tool was in just before invoking the transform mode;
  • the smallest initial transform frame that can contain this path shall be overlaid;
  • the path tool shall remain the official active tool in the toolbox, but the tool options shall be swapped out for the ones of the transform tool;
  • the transform tool shall operate on the path.

Same deal here with the key short-cut. I am open to suggestions.

moving guides

Moving existing guides shall ‘just work’: hover the mouse sprite close enough to a guide; the guide highlights; grab it, move it, drop it. If the current way for this does not work well enough, then this needs improving, not the introduction of settings or modes.

on-canvas interaction

The action is on-canvas. A frame of handles is used to perform all transform actions: move, rotate, scale, shear and perspective.

Here is the frame in its initial—rectangular—form:

Transform frame.png

for clarity the frame is shown here at full opacity and against a 50% grey background

  • transparent centre area is the move handle
  • the four white-background corners are the scale handles
  • the four white-background area between the scale handles are the side handles, also used for scaling
  • the top black-background circle is the rotation handle
  • the centre black-background circle is the rotation axis
  • the four slanted-striped areas on the side handles are the shear handles
  • the four lack-background corners are the perspective handles

Al these handles/areas shall be drawn using pure black or pure white colours. All shall be shown on the canvas at 25% opacity, except for the move handles which shall be transparent, and the scale handles which shall have 50% opacity. That this works in any situation we can see here against the 3 acid-test backgrounds, and something colourful:

Transform opacity test.png

note that some handle sizing is not 100% according to spec in these images

As can be seen here, only where necessary the areas shall be delineated by a 1 pixel border in contrasting colour.

shaping up

Although its default shape when invoking the transform tool—or mode—shall be rectangular at zero degrees angle with the canvas, in practice the transform frame will not remain this orderly for long. In general four corner points will be connected to each other by four sides and this spans up the transform frame.

Because of rotation, the notion of width and height becomes rather arbitrary for the transform frame:

  • the minimum and maximum width of the transform frame shall be defined as the minimum and maximum distance between the two sides that started off as vertical in the initial frame.
  • the minimum and maximum height of the transform frame shall be defined as the minimum and maximum distance between the two sides that started off as horizontal in the initial frame.
  • the centre of the transform frame shall be defined as the point where the two diagonals through the corner points cross.

While calculating the sizes of the frame, we will assume that the transform will be performed at a magnification where users can actually see what they are doing. This means there is not requirement to implement a narrow situation.

Conceptually, the transform frame is set up as follows:

  1. connect the four corner points by the four sides;
  2. set up the inner lines that built the side handles and scale handles together with the sides:
    • the inner lines shall run parallel to the sides;
    • the distance between the inner lines and the sides for both ‘horizontal sides’ shall be the same; it shall be the minimum height / 4, CLAMPed by 50 at the top end;
    • the distance between the inner lines and the sides for both ‘vertical sides’ shall be the same; it shall be the minimum width / 4, CLAMPed by 50 at the top end;
    • these distances between the inner lines and the sides shall be called the side handle widths; we can see that all the side handles and all the corner areas are parallelograms.
  3. set up the perspective handles inside the corner areas:
    • the area of each perspective handle shall be 1/3rd of that of its corner area (in other words, half the area of the scale handle in the same corner area);
    • the line that completes the triangle of the perspective handle (together with the two sides) shall run parallel to the diagonal of the corner area; hint: this is done by intersecting this line at a distance of sqrt(2/3) of the length of the outside lines of the corner area.
  4. set up the shear handles:
    • the shear handles shall be placed on the side handles, close to—and on the counter-clockwise side—of the corner areas;
    • their shape shall be a parallelogram with a height of the full width of the side handle it is placed upon, slanted towards the corner area by (side handle width) / 3, always rounded up;
    • the shear handles shall be drawn with 2-pixel wide alternating lines, and shall start from the centre of the side handle with a black one; the total number of black lines shall be ( ((side handle length) / 2) - (slant) ) / 4, always rounded down;
    • the first line, drawn furthest away from the corner area shall start at the centre of the inner line and shall finish at the centre of the side line minus the slant; this relative placement ensures that the handle will always be slanted relatively to the (very) probable slanting of the corner area itself;
    • example: place a shear handle on a (slanted) 50 pix wide 90 pix long side handle; height of the shear handle is 50, slant is 50 / 3 17, number of black lines is ((90 / 2) - 17) / 4 = 7, start drawing 45 pixels from the corner area, draw to 45 - 17 = 28:
      Transform shear example.png
  5. place rotation handle:
    • the radius of the circle shall be MIN(of both side handle widths) / 3, always rounded down; this results in an area of close to a third of that of a corner area;
    • the shall be placed on a side handle, close to—and on the clockwise side—of a corner area; it shall be placed centred on the side handle width, at a distance of half its radius from the corner area;
    • the default position of the rotation handle shall be next to the corner area that starts out at the top-left of the initial transform frame; however, the rotation handle shall always be in view, if it is not for the default position, then is shall be positioned next to the first corner area in clockwise direction which will make it visible in the current viewport.
  6. place the rotation axis:
    • the radius of the shall be that of the rotation handle;
    • the centre this circle shall be placed at the rotation axis;
    • the default position of the ration axis shall be the centre of the transform frame.

transformation constraints

Because the handles on the transform frame work 100% in parallel, transformation constraints can be overloaded, and the modifier keys to toggle them can be overloaded as well. There shall be the following transformation constraints:

constrain
works on move, rotate and perspective. toggled by <ctrl>
keep aspect
works on scale. toggled by <shift>
from centre
works on scale and shear, toggled by <ctrl>
free shear
works on shear, toggled by <shift>
centre/corner rotate
works on rotation axis, toggled by <ctrl>

the scale constraints—keep aspect and from centre—have been aligned with the selection tools and the rest of the world.