..Shapes..Geometry

For version 0.7.0.

To top. Up: ..Shapes

..Shapes..Geometry

Core bindings

Summary of extensions

..Shapes..Geometry / circle

ccw_arc circle cw_arc

..Shapes..Geometry / linkpaths

buildchain linkpaths

..Shapes..Geometry / pathmapping

pathmap sidepath sidepath2

The geometric objects in Shapes are coordinates and paths. This namespace is for operations within this class of objects. Once the geometric objects are painted (typically stroked or filled), they become graphical objects and are no longer under the topic of this namespace. Compare ..Shapes..Graphics.

Sections: Syntax equivalents Functions of points Functions of paths Affine transforms Means Extremes Proximity and intersection Path-producing functions Upsamling of paths Numerical tolerance

Syntax equivalents

This section contains one dynamic variable, and a couple of functions which correspond directly to syntactic constructs. While most users should generally not use the functions directly, users interested in graphic design are strongly encouraged to get familiar with the dynamic variable.

@defaultunit
Used by:
Type:	§Length
Default binding:	50 cm
Default unit of unspecified radii of polar coordinates used in path construction. Typically, the unit is set to a special length rather than a fixed distance. See ../syntax.html for details on special lengths. It is not possible to refer to directly to the value of — the dynamic variable can be bound like any other dynamic variable, but will only be used implicitly during path construction.

coords
::§Float ::§Float → §FloatPair
Dynamic references:	none
Implements float-pair.
::§LengthLike ::§LengthLike → §Coords
Dynamic references:	none
Implements coords-2D. One of the arguments is allowed to be the special §Float value zero, which is interpreted as a zero absolute length.

cornercoords
::§LengthLike ::§LengthLike ::§Float → §Coords
Dynamic references:	none
Implements corner-point-2D.

polarhandleFree_r
::§Float → §PolarHandle
Dynamic references:	none
Implements polar-handle-2D in the case when the modulus of the handle is not specified.

polarhandleFree_ra
→ §PolarHandle
Dynamic references:	none
Implements polar-handle-2D in the case when neither modulus nor angle of the handle is not specified.

Functions of points

angle
::§FloatPair → §Float
Dynamic references:	none
Angle to the point from the origin, measured counter-clockwise from the positive x axis.
::§Coords → §Float
Dynamic references:	none
Analogous to the §FloatPair case.

dir
::§Float → §FloatPair
Dynamic references:	none
Unit vector with given angle.

normalized
Scaling to unit length is closely related to computing the norm, compare . While the norm preserves physical units, scaling to unit norm will cancel the unit so that the produced unit vector is always unit-less.
::§FloatPair → §FloatPair
Dynamic references:	none
Scaling to unit length. The argument must not have zero length.
::§Coords → §FloatPair
Dynamic references:	none
Scaling to unit length. The argument must not have zero length.
::§FloatTriple → §FloatTriple
Dynamic references:	none
Scaling to unit length. The argument must not have zero length.
::§Coords3D → §FloatTriple
Dynamic references:	none
Scaling to unit length. The argument must not have zero length.
::§Float → §Float
Dynamic references:	none
Scaling to unit length, resulting in either plus or minus one. The argument must not be zero.
::§Integer → §Integer
Dynamic references:	none
Scaling to unit length, resulting in either plus or minus one. The argument must not be zero.
::§Length → §Float
Dynamic references:	none
Scaling to unit length, resulting in either plus or minus one. The argument must not be the zero length.

orthogonal
::§FloatPair → §FloatPair
Dynamic references:	none
Produces vector which is orthogonal to the given one, by rotating 90° counter-clockwise.

Functions of paths

emptypath
Type:	§Path
An empty 2^d path. Useful in folds, for instance.
See also:	..Shapes..Geometry3D..emptypath

duration
::§Path → §Integer
Dynamic references:	none
Index of the final pathpoint along the path (indexing starting from zero at the beginning of the path). On a closed path, this is the same as the total number of pathpoints. On an open path, it is one less.
::§Path3D → §Integer
Dynamic references:	none
Analogous to the the 2^d case.

reverse
::§Path → §Path
Dynamic references:	none
Construct path where the order of pathpoints in the representation is reversed. The constructed path looks identical to the original.
::§Path3D → §Path3D
Dynamic references:	none
Analogous to the the 2^d case.

winding

path::§Path origin::§Coords → §Integer

Dynamic references:

none

Counts the number of counter-clockwise turns that path makes about origin. It is required that path be closed.

The winding number is used to define filling and clipping.

Winding numbers

Winding numbers computed by winding.

Source: show/hide — visit
##needs winding-rule-paths.shext ##lookin ..Shapes ##lookin ..Shapes..Geometry cmd: \ pth → { bb: [Layout..bbox Traits..@width:4mm \| [Graphics..stroke pth]] step: 3mm x1: [Layout..xmin bb] x2: [Layout..xmax bb] y1: [Layout..ymin bb] y2: [Layout..ymax bb] Text..@size:0.7*step \| [[Data..range x1 x2 step].foldl \ p x → [[Data..range y1 y2 step].foldl \ p y → p & [[shift (x,y)] Layout..center [] (Text..newText << [String..sprintf `%d´ [Geometry..winding pth (x,y)]])] p] Graphics..null] } Traits..@nonstroking: [Traits..gray 0.4] \| { IO..•page << ( [cmd starPath] & starPathStroke ) << ( [cmd sameCircle] & sameCircleStroke ) >> [shift (3cm,0cm)] << ( [cmd alternatingCircle] & alternatingCircleStroke ) >> [shift (6cm,0cm)] }

Argument variation integrals

Using winding to compute the argument variation integral for open paths.

Source: show/hide — visit
/ This examples shows how to compute the integral of argument variation for an open path, based on the kernel function that computes winding numbers for closed paths. / ##lookin ..Shapes ##lookin ..Shapes..Geometry / This function implements the integral of argument variation. It constructs a closed path by adding a counter-clockwise segment, gets its winding number, and compensates for the closing segment. The closing segment is computed as four straight line segments, at the biggest of the radii of the original path's endpoints. */ argumentVariation: \ pth origin → [if pth.closed? 360° [Geometry..winding pth origin] { pth0: [[shift ~origin] pth] dStart: pth0.end.p dEnd: pth0.begin.p aStart: [angle dStart] aEnd: { tmp: [angle dEnd] [if tmp ≥ aStart tmp tmp+360°] } aStep: (aEnd - aStart) / 4 d: [Numeric..Math..max [Numeric..Math..abs dStart] [Numeric..Math..abs dEnd]] * [normalized dStart] 360° * [Geometry..winding [[Data..range '1 '3].foldl \ p e → (p--[[rotate eaStep] d]) pth0]--cycle (0m,0m)] - ( aEnd - aStart ) }] /* Just for illustration, the path used to compute the winding number is extracted from the function body above. */ closedPath: \ pth origin → { dStart: pth.end.p - origin dEnd: pth.begin.p - origin aStart: [angle dStart] aEnd: { tmp: [angle dEnd] [if tmp ≥ aStart tmp tmp+360°] } aStep: (aEnd - aStart) / 4 d: [Numeric..Math..max [Numeric..Math..abs dStart] [Numeric..Math..abs dEnd]] [normalized dStart] [[shift origin] [[Data..range '1 '3].foldl \ p e → (p--[[rotate eaStep] d]) [[shift ~origin] pth]]--cycle] } /* This helper function makes an illustration for a single path. It marks the origin, strokes the path, strokes the closed path for which the winding number is computed, and prints the argument variation near the origin. / helper: \ pth → ( Graphics..newGroup << Traits..@stroking:Traits..RGB..RED \| [Graphics..stroke [Geometry..circle 1mm]] << Traits..@dash:[Traits..dashpattern 2bp 2bp] \| [Graphics..stroke [closedPath pth (0m,0m)]] << [Graphics..stroke pth head:[Graphics..ShapesArrow width:10 ...]] << [[shift (0cm,~1cm)] (Text..newText << [String..sprintf `%.1f°´ [argumentVariation pth (0m,0m)]/1°])]) / All examples will be constructed as simple variations of this path. / pth: (~1cm,~1cm)>(1%C^100°)--(1%C^)<(2cm,2cm)>(1%C^)--(1%C^)<(1cm,1cm)>(1%C^)--(1%C^)<(3cm,3cm)>(1%C^)--(1%C^45°)<(2cm,~2cm) / Finally, apply the helper on some paths. / IO..•page << [helper pth] << [helper [Geometry..reverse pth]] >> [shift (7cm,0cm)] << [helper [[shift (~1.5cm,~1cm)] pth]] >> [shift (0cm,~7cm)] << [helper [Geometry..reverse [[shift (~1.5cm,~1cm)] pth]]] >> [shift (7cm,~7cm)]

Affine transforms

affinetransform
::§FloatPair ::§FloatPair ::§Coords → §Transform
Dynamic references:	none
Construct transform from multiplier for x and y coordinates, followed by a shift.

shift
::§Coords → §Transform
Dynamic references:	none
Construct transform.

rotate
angle::§Float → §Transform
Dynamic references:	none
Construct transform.

scale
r:1::§Float x:1::§Float y:1::§Float → §Transform
Dynamic references:	none
Construct transform that scales x by rx, and y by ry.

inverse
::§Transform → §Transform
Dynamic references:	none
Constructs the inverse of a transform. This is only possible if the linear part of the transform is non-singular.

Means

mean
::§Path → §Coords
Dynamic references:	none
Mean point of the path. Note that this is not the same as the mean of the area that would be painted when filling the path.
::§Path3D → §Coords3D
Dynamic references:	none
Analogous to the the 2^d case.

pathpoint_mean
::§Path → §Coords
Dynamic references:	none
Mean of the path points of the path.
::§Path3D → §Coords3D
Dynamic references:	none
Analogous to the the 2^d case.

Extremes

maximizer
::§Path ::§FloatPair → §PathSlider
Dynamic references:	none
Finds the first point on the path where the global maximum in the given direction is attained.
::§Path3D ::§FloatTriple → §PathSlider3D
Dynamic references:	none
Analogous to the the 2^d case.

pathpoint_maximizer
::§Path ::§FloatPair → §PathSlider
Dynamic references:	none
Finds the first path point on the path where the global maximum in the given direction is attained.
::§Path3D ::§FloatTriple → §PathSlider3D
Dynamic references:	none
Analogous to the the 2^d case.

controlling_maximizer
::§Path ::§FloatPair → §Coords
Dynamic references:	none
Finds the a point among the control points of the path, where the global maximum in the given direction is attained.
::§Path3D ::§FloatTriple → §Coords3D
Dynamic references:	none
Analogous to the the 2^d case.

Proximity and intersection

intersection

::§Path ::§Path → §PathSlider

Dynamic references:

none

Finds the first point on the first path where it intersects with the second path.

If no intersection is found, the error handler @handler_NoIntersection is called with the two paths as argumets.

Additional information from the computation is stored in the info field of the returned §PathSlider. This structure, in turn, has fields accordning to the following table.

The info §Structure returned by intersection
Field	Type	Description

other	§PathSlider	The “time” of the intersection according to the second path.

@handler_NoIntersection
Used by:
Type:	§Function
To be called when the intersection between two paths cannot be found. Shall take the two §Path objects as arguments.

approximator

::§Path ::§Coords → §PathSlider

Dynamic references:

none

Finds the first point on the path where the global minimum in distance to the given point is attained.

The algorithm and related tolerances are described in ../algo-tol.html.

::§Path ::§Path → §PathSlider

Dynamic references:

none

Finds a point on the first path where the global minimum in distance to the second path is attained. If there are intersections, the earliest of these is returned

The algorithm and related tolerances are described in ../algo-tol.html.

Additional information from the computation is stored in the info field of the returned §PathSlider. This structure, in turn, has fields accordning to the following table.

The info §Structure returned by approximator
Field	Type	Description

dist	§Length	Distance between paths at optimum.
other	§PathSlider	The “time” along the second path at optimum.

::§Path3D ::§Coords3D → §PathSlider3D

Dynamic references:

none

Analogous to the the 2^d case.

::§Path3D ::§Path3D → §PathSlider

Dynamic references:

none

Analogous to the the 2^d case. However, note that the meaning of intersection is not quite clear in the 3^d case, and hence we shall not be precise regarding among which times the earliest is taken if there are several “intersections”.

pathpoint_approximator
::§Path ::§Coords → §PathSlider
Dynamic references:	none
Finds the first path point on the path where the global minimum in distance to the given point is attained.
::§Path3D ::§Coords3D → §PathSlider3D
Dynamic references:	none
Analogous to the the 2^d case.

Path-producing functions

rectangle
::§Coords ::§Coords → §Path
Dynamic references:	none
Constructs a rectangular path with the given points as opposite corners. The path starts at the first of the given points, and if the points are given as bottom-left and upper-right (in that order), the path is oriented counter-clockwise.

meetpaths

::§Path ::§Path → §Path

Dynamic references:

none

Merge the two paths by merging the end point of the first path with the begin point of the second path. It is not required for the two paths to intersect; the merge operation is defined anyway by replacing the two merged points with one at the mean, taking one interpolation point form each path. Use this to avoid vanishing spline segments when joining two consecutive paths.

Hopefully, the example below expresses the idea more clearly.

Merging paths

Application of meetpaths. Note that the interesting stuff is found in ..Shapes..Geometry / linkpaths.

Source: show/hide — visit
##needs ..Shapes..Geometry / linkpaths ##needs ..Shapes..Data / seq-support ##lookin ..Shapes ##lookin ..Shapes..Geometry / The mergepaths function turned out difficult to implement since the subpath function does not return the control point at the free end of the cut (this is often a desirable behavior). Instead the function meetpaths was added to the kernel. / \|pathpoint: \ p t → \| (+[reversespeed p t][reversedirection p t])< \|* [point p t] \|** >(+[speed p t][direction p t]) \|* \|mergepaths: \ p1 p2 → \| [if [Geometry..duration p1]>1 \|** { t:([Geometry..duration p1]-1) [subpath p1 0 t]>(+[speed p1 t][direction p1 t]) } \|* [pathpoint p1 0]] \| -- \| (+[reversespeed p1 ∞][reversedirection p1 ∞])< \|* ( 0.5 * ( [point p1 ∞] + [point p2 0] ) ) \|** >(+[speed p2 0][direction p2 0]) \|* -- \| [if [Geometry..duration p2]>1 \| (+[reversespeed p 1][reversedirection p 1])<[subpath p2 1 ∞] \|* [pathpoint p2 ∞]] Geometry..@defaultunit: 1%c \| { pth1: (~1cm,0cm)--(^)<(0cm,0cm)>(1cm,1cm)--(2cm,3cm)<(4cm,4cm)>(^) pth2: (^)<(5cm,4cm)>(5cm,5cm)--(1cm^180°)<(7cm,3cm)>(^)--(7cm,2cm) Traits..@stroking:[Traits..gray 0.7] \| { IO..•page << [Graphics..stroke pth1] IO..•page << [Graphics..stroke pth2] } IO..•page << [Graphics..stroke [Geometry..meetpaths pth1 pth2]] } Geometry..@defaultunit: 1%c \| { pth1: (0cm,~3cm)>(2cm^70°)--(5cm,5cm) pth2: (3cm,~2cm)>(2cm^140°)--(0cm,4cm) Traits..@stroking:[Traits..gray 0.7] \| { IO..•page << [Graphics..stroke pth1] << [Graphics..stroke pth2] } IO..•page << [Graphics..stroke [Geometry..linkpaths pth1 pth2]] } { subpath: \ pth t1 t2 → [pth t1]--[pth t2] seg: \ a → [shift (5cm,0)][rotate a][shift (0,~1.2cm)] [] [Geometry..reverse [subpath [Geometry..circle 1cm] 0 1.5]] c1: [seg 0°] c2: [seg 90°] c3: [seg 180°] c4: [seg 270°] IO..•page << [Graphics..stroke c1] pths: [Data..list c1 c2 c3 c4] IO..•page << [pths.foldl \ p e → p & [Graphics..stroke e] Graphics..null] scaleAroundCenter: \ factor pth → { c: [Geometry..mean pth] [shift c][scale factor][shift ~c] [] pth } IO..•page << Traits..@stroking: Traits..RGB..RED \| [Graphics..stroke [scaleAroundCenter 1.3 ...][] [Geometry..buildchain pths]--cycle] }

::§Path3D ::§Path3D → §Path3D

Dynamic references:

none

Analogous to the the 2^d case.

svg_path
d::§String xunit:1 bp::§Lenth yunit:1 bp::§Lenth multi::§Boolean singletons:true::§Boolean → §Path
Dynamic references:	none
Interpret the string d as an svg description of a path. Generally, converting coordinates from the svg model to Shapes is cumbersome, as it basically requires a drawing area in the Shapes world to be defined and related to svg coordinates. However, by disregarding the shift part of the true coordinate transform, only scaling remains to be determined, and for this there is xunit and yunit. The argument multi is optional. If provided, true means that a §MultiPath will be returned (generally containing several sub paths of type §Path), and false means that there must be exactly one sub path, which will be returned as a §Path. If singletons is false, paths with zero duration are ignored. Use this function when you'd rather use a graphical tool to define paths than writing the Shapes code by hand. For instance, paths can be created with Gimp, and exported in svg format. Note that svg graphics is typically located below the origin, while Shapes (and pdf) programs typically locate graphics above the origin. When determining how to shift the returned path, and this is done using svg information, it must be remembered that the svg y coordinate is increasing downwards.

Upsamling of paths

While most operations on paths only depend on the geometry of the path, there are some operations that operate on the spline representation. Generally, such operations give a more precise result for smaller spline segments, and fortunately, a spline can be divided into smaller segments without changing its geometry. This is referred to as upsampling of the path, and Shapes provides some variants on how this can be done.

upsample_balance
::§Path → §Path
Dynamic references:	none
Divide each spline segment in two such that the velocity is continuous at the new path point. This will make the distance to the two interpolation points at the new path point equal, hence the name. It turns out that this happens at spline time 0.5, so the implementation is very cheap.
::§Path3D → §Path3D
Dynamic references:	none
Analogous to the the 2^d case.

upsample_inflections
::§Path → §Path
Dynamic references:	none
Add samples at inflection points.

upsample_bends
angle::§Float path::§Path → §Path
Dynamic references:	none
Add samples at inflection points, and so that each segment bends at most angle. Segments that need upsampling (after inflections have been removed) are sampled evenly with respect to direction.

upsample_every
period::§Length path::§Path → §Path
Dynamic references:	none
Add sample points such that each segment is at most period long. Segments that need upsampling are sampled evenly with respect to arc length.
period::§Length path::§Path3D → §Path3D
Dynamic references:	none
Analogous to the the 2^d case.

Numerical tolerance

Generally, programs should not directly refer to the low level tolerance parameters described in ../. Therefore, most of these parameters are not even exposed with a binding. This section gives the exceptions.

arcdelta
Type:	§Length
The value controlled by arcdelta.