Visio has a number of ShapeSheet transform functions that allow you to transform a point expressed in one shape's coordinate space to the coordinate space of another one.
- LOCTOLOC
- LOCTOPAR
- LOC
- PAR
- ANGLETOLOC
- ANGLETOPAR
Local and Parent Coordinates
When you open the ShapeSheet in Visio you're presented with coordinates expressed in two ways - Local and Parent coordinates.
Most cells use Local coordinates (see green shading above) and these are values that are local to the shape's bottom left origin (x:0, y:0).
The others, PinX/Y and Angle (shown in blue), describe the position and orientation of the shape in the coordinate space of its Parent container. This container may be the page, for a top level shape, or a group shape if it's a sub-shape.
Pin and LocPin
While a shape's Pin represents its position within a container (ie its Parent position), the LocPin (or Local Pin) can be seen as an offset for the shape's drawing origin.
For example, in the following image the blue rectangle's Pin is set at x:40, y:40 in Parent coordinates, which in this case is the page. The shape's Local Pin is set to the default middle of the the shape at x:30, y:20 (see red cross-hair). Note, normally Visio uses relative formulas - I'm just using absolute values here to make it easier to see what's happening.
The rectangle is also a group shape and contains a single orange circle sub-shape. The Pin position of the sub-shape is set to x:40, y:30 and this is described in Parent coordinates, which is the rectangle.
If you then shift the rectangle's LocPin to x:20, y:10 then you can see that the entire local coordinate space of the of the rectangle has moved. Note though, that the shape's Pin position, relative to the page, remains the same, as do the local coordinates of the (orange) sub-shape.
So now we're clear on Local and Parent coordinates, let's move on to looking at the transform functions.
ShapeSheet Transform Functions
Visio has six main functions to help with changing from one coordinate system to another. Two for dealing with angles, which I'll come onto in minute, and four for general transformation.
LOCTOLOC and LOCTOPAR allow you to specify both the source and destination coordinate spaces via cell references, neither of which have to be in the shape you're defining your formula in. You can think of LOC and PAR, on the other hand, as shortcuts that allow you to assume the destination coordinate space is the one in that you're defining the formula in.
LOC
Docs description: Takes a point defined in one shape's local coordinates and returns the equivalent point expressed in the local coordinates of the shape associated with the formula.
Example usage: If you look in the "Blocks with Perspective" stencil you'll find that each shape references a vanishing point defined on the page. The shape contains a control that uses the LOC function to convert the page level point to one that's described in the Local coordinates of the respective shape.
PAR
Docs description: Returns the x,y coordinates of a point in the coordinate system of the shape's parent.
My description: Takes a point in the Local coordinates of a shape and converts it to the Parent coordinate space of the shape where this function is used.
Example usage: Any time you use point to point glue with a connector (ie statically gluing a 1D endpoint to a connection point, rather than dynamic whole shape glue) Visio injects formulas into the connector endpoint cells and uses the PAR function to convert the Local coordinates of the connection points to the Parent coordinates it needs to locate the connector on the page.
LOCTOLOC
Docs description: Returns a transformed point in local coordinates in the destination coordinate system.
My description: Takes a point in the Local coordinates of a shape and converts it to the Local coordinate space of another shape.
Example usage: I couldn't spot an example of LOCTOLOC in the built in stencil content, so here's a slightly contrived example - consider the following image where you've got a rectangle (Sheet.3) with an (orange) sub-shape. You want to locate the sub-shape over the connection point in the other rectangle (Sheet.1), so in the ShapeSheet of the sub-shape (Sheet.4) you use the LOCTOLOC function to transform the Local coordinates of the connection point to Local coordinates within the group shape - Sheet.3. The result is that sub-shape will remain positioned over the connection point irrespective of where its group parent is placed on the page. One benefit of this arrangement is that, although the orange sub-shape appears to be a child of the the upper rectangle (Sheet.1), it will be deleted when its parent (Sheet.3) is removed from the page allowing for an interesting visual attribute type relationship.
LOCTOPAR
Docs description: Returns a transformed point in parent coordinates in the destination coordinate system.
Example usage: If you use static (point to point) glue to connect two shapes together, Visio injects a formula into the PinX/Y cells and makes use of the LOCTOPAR function. In the image below you can see the PinX cell for the (green) Decision shape and that the point being transformed is the Local Connection point in the (blue) Process.4 shape. It's using Process.4 as the source coordinate space via a reference to the Process.4!EventXFMod cell, and this shape (Decision) as the destination coordinate space via another reference to the [Decision.]EventXFMod cell. (The outer PNTX function just pulls the x component out of the point and there's also the addition of 12.5 mm, which is half the shape's width.)
ANGLETOPAR
Docs description: Returns a transformed angle in the destination shape's parent coordinate system. Converts an angle from local coordinates in a source shape to the parent coordinates in a destination shape.
Example usage: When you add a connection point to a shape in Visio via the UI, the point is given a direction. The direction is set via a vector, which, by default, is perpendicular to the vertex that the connection is applied to. You can see this in the following image where the lower ShapeSheet shows the cells for the green circle.
I've added a second geometry section (see diagonal green line) and set the end of the line to the DirX/Y cells of the first connection row so that you can visualize that vector. The image shows the blue rectangle mid-drag, and you can see that the rectangle rotates to the angle determined by the vector. Visio then takes this angle and uses the ANGLETOPAR function to transform the degree value from the Local value in the coordinate space of the green circle, to Parent coordinate space of the rectangle.
ANGLETOLOC
Docs description: Returns a transformed angle in the destination shape's local coordinate system. Converts an angle from local coordinates in a source shape to the local coordinates in a destination shape.
ANGLETOLOC is broadly the same as ANGLETOPAR just that it returns coordinates from a Local space rather than the Parent.
Wrap up
So I hope this helps in understanding how this set of functions work. The key thing to think about when using them is where is your calculation going to be consumed? Is it a cell that uses Local or Parent coordinates? Note that the consuming cell is not necessarily where the function is defined.