ShapeBuilder

Description

sealed class Tinman.Terrain.Shapes.ShapeBuilder

Helper class for building geometric shapes.

To build a geometric shape, perform the following steps:

Create a shape builder via Shape.Geometry or call Clear on an existing builder for starting from scratch.
Configure the shape builder flags via Flags.
Configure the geo-reference via Georef.
Configure shape metadata via Metadata.
Configure a coordinate system transformation via Transform.
Configure a vertex transformation via Matrix.
Add geometric primitives:
- Vertices (see Vertex* methods)
- Edges (see Edge* methods)
- Triangles (see Triangle* methods)
- Values (see Value* methods)
Add pre-defined geometric shapes:
- Shapes (see Add¹)
- Arcs (see ArcInner, ArcOuter)
- Arrows (see Arrow)
- Circles (see Circle)
- Curves (see Curve)
- Grids (see Grid)
- Ovals (see Oval)
- Rectangles (see Rectangle¹)
Finish shape building by calling one of the following methods:
- Build
- Graph
- Hull
- Mesh
- Points
- Polygon

See also: Shape.Geometry

Public / Constructors

Build

public method Build → (2)

edgeParity ^opt : int32 = 0: Edge parity to use.
clear ^opt : bool = true: Clear all geometry data with Clear after building the shape?
returns → IShape: The IShape object or null if the shape is empty.

Creates a new instance of IShape from the specified vertices (see Vertex¹), edges (see Edge²) and/or triangles (see Triangle²).

This method only delegates to other methods, in the following order:

Mesh: when one or more triangles have been specified.
Graph: when one or more edges have been specified and edgeParity ^opt is zero.
Polygon: when one or more edges have been specified and edgeParity ^opt is not zero.
Points: otherwise

Graph

public method Graph → (1)

clear ^opt : bool = true: Clear all geometry data with Clear after building the shape?
returns → IShape: The IShape object or null if the shape is empty.

Creates a new instance of IShape from the specified vertices (see Vertex¹) and edges (see Edge²).

Hull

public method Hull → (1)

clear ^opt : bool = true: Clear all geometry data with Clear after building the shape?
returns → IShape: The IShape object or null if the shape is empty.

Creates a new instance of IShape that represents the convex hull of the specified vertices (see Vertex¹).

The returned shape is a convex polygon that contains all specified vertices (the signed distance from the vertex to the shape is less than or equal to zero).

Mesh

public method Mesh → (1)

clear ^opt : bool = true: Clear all geometry data with Clear after building the shape?
returns → IShape: The IShape object or null if the shape is empty.

Creates a new instance of IShape from the specified vertices and triangles.

Points

public method Points → (1)

clear ^opt : bool = true: Clear all geometry data with Clear after building the shape?
returns → IShape: The IShape object or null if the shape is empty.

Creates a new instance of IShape from the specified vertices (see Vertex¹).

Polygon

public method Polygon → (2)

negative ^opt : bool = true: Shall the built polygon have negative parity (IShapeInfo.EdgeParity)? If unsure, just pass true, as negative parity is the default.
clear ^opt : bool = true: Clear all geometry data with Clear after building the shape?
returns → IShape: The IShape object or null if the shape is empty.

Creates a new instance of IShape from the specified vertices (see Vertex¹) and edges (see Edge²).

The signed area of a polygon can be used to determine the parity, if the vertex winding is not intended to be relevant (see Area¹).

Public / Methods

Add

_2 overloads

public method Add¹ → (3)

shape ⁱⁿ : IShape: The shape.
flip ^opt : bool = false: Flip edge resp. triangle vertices? If the current transformation flips handedness (see Matrix, the given value is inverted to compensate.
values ^opt : ShapeValue = ShapeValue.All: The custom per-vertex values to add.
returns → ShapeBuilder: this

Adds all vertices, edges and triangles of the given shape.

When flip ^opt is true, edges (A,B) resp. triangles (A,B,C) are added as (B,A) resp. (C,B,A).

See also: ShapeBuilder.Matrix

public method Add² → (3)

shape ⁱⁿ : IShape: The shape.
parity ⁱⁿ : int32: The desired edge parity (see remarks), usually for the final call to Build or Polygon.
values ^opt : ShapeValue = ShapeValue.All: The custom per-vertex values to add.
returns → ShapeBuilder: this

Adds all vertices, edges and triangles of the given shape.

This method delegates to Add¹, computing the flip parameter as follows:

If parity ⁱⁿ or IShapeInfo.EdgeParity of shape ⁱⁿ is 0, flip is false.
If the sign of parity ⁱⁿ is equal to the edge parity of shape ⁱⁿ, flip is false.
Otherwise, flip is true.

See also: ShapeBuilder.Matrix

ArcInner

public method ArcInner → (5)

center ⁱⁿ : Vec2D: The center of the oval from which to create the arc.
a ⁱⁿ : Vec2D: Vector pointing from center ⁱⁿ to start of arc.
b ⁱⁿ : Vec2D: Vector pointing from center ⁱⁿ to end of arc.
n ⁱⁿ : int32: [>=1]
The number of segments between a ⁱⁿ and b ⁱⁿ.
closed ^opt : bool = true: Create a closed contour starting and ending at center ⁱⁿ"/>, instead of just an arc?
returns → ShapeBuilder: this.

Creates a vertex contour that runs from a ⁱⁿ to b ⁱⁿ over the inner path (i.e. the shorter one).

The edge parity of the contour is the sign of IVec2Ops.Cross² for a ⁱⁿ and b ⁱⁿ.

ArcOuter

public method ArcOuter → (5)

center ⁱⁿ : Vec2D: The center of the oval from which to create the arc.
a ⁱⁿ : Vec2D: Vector pointing from center ⁱⁿ to start of arc.
b ⁱⁿ : Vec2D: Vector pointing from center ⁱⁿ to end of arc.
n ⁱⁿ : int32: [>=1]
The number of segments between a ⁱⁿ and b ⁱⁿ.
closed ^opt : bool = true: Create a closed contour starting and ending at center ⁱⁿ"/>, instead of just an arc?
returns → ShapeBuilder: this.

Creates a vertex contour that runs from a ⁱⁿ to b ⁱⁿ over the outer path (i.e. the longer one).

The edge parity of the contour is the sign of IVec2Ops.Cross² for b ⁱⁿ and a ⁱⁿ.

Area

_2 overloads

public method Area¹ → ()

returns → float64: The signed area.

Computes the signed area of the simple polygon defined by the sequence of vertices that have been added to this builder.

See also: Geometric.AreaPolygon¹

public method Area² → (2)

a ⁱⁿ : int32: Index of first polygon vertex.
b ⁱⁿ : int32: Index of last polygon vertex.
returns → float64: The signed area.

Computes the signed area of the simple polygon defined by the given sequence of vertices.

See also: Geometric.AreaPolygon¹

Arrow

public method Arrow → (6)

from ⁱⁿ : Vec2D: Base point of arrow.
to ⁱⁿ : Vec2D: Tip point of arrow.
width ^opt : float64 = 0.7: Scale factor from length to width.
widthShaft ^opt : float64 = 0.25: Scale factor from width to widthShaft.
lengthShaft ^opt : float64 = 0.5: Scale factor length to lengthShaft.
lengthHead ^opt : float64 = 0.6: Scale factor length to lengthHead.
returns → ShapeBuilder: this.

Creates a vertex contour for an arrow shape (negative edge parity).

The arrow shape vertices a are determined by these dimensions:

       /         /\             \
       |        /  \            |
       |       /    \           |
       |      /      \          | lengthHead
       |     /        \         |
length |    /  _    _  \        |
       |   /.-´ |  | `-.\   \   /
       |        |  |        |
       |        |  |        | lengthShaft
       \        `--´        /

                \__/
             widthShaft

           \____________/
               width

The length is the distance between from ⁱⁿ and to ⁱⁿ. The other dimensions are defined by the ratios given as parameters.

Circle

public method Circle → (3)

center ⁱⁿ : Vec2D: The circle center.
radius ⁱⁿ : float64: [>=0]
The circle radius.
n ⁱⁿ : int32: The number of segments per circle quadrant. Is negative, vertices winding is flipped.
returns → ShapeBuilder: this

Creates a vertex contour for a circle shape by defining an approximating polygon (negative edge parity).

Clear

public method Clear → ()

returns → ShapeBuilder: this

Clears all geometry data in the shape builder.

After calling this method, the following lists will be empty:

Edges
Triangles
Values
Vertices

The default behaviour will clear all geometry data after building a shape with Build, Graph, Hull, Mesh, Points or Polygon.

See also: ShapeBuilder.ClearEdges
ShapeBuilder.ClearTriangles
ShapeBuilder.ClearValues
ShapeBuilder.ClearVertices

ClearEdges

public method ClearEdges → ()

returns → ShapeBuilder: this

Clears geometry data in the shape builder.

After calling this method, the following lists will be empty:

Edges

ClearTriangles

public method ClearTriangles → ()

returns → ShapeBuilder: this

Clears geometry data in the shape builder.

After calling this method, the following lists will be empty:

Triangles

ClearValues

public method ClearValues → (1)

values ^opt : ShapeValue = ShapeValue.All: The custom per-vertex values to clear.
returns → ShapeBuilder: this

Clears geometry data in the shape builder.

After calling this method, the following lists will be empty:

Values, for the given values ^opt

ClearVertices

public method ClearVertices → ()

returns → ShapeBuilder: this

Clears geometry data in the shape builder.

After calling this method, the following lists will be empty:

Edges
Triangles
Vertices

Copy

public method Copy → (2)

shape ⁱⁿ : IShape: The shape.
values ^opt : ShapeValue = ShapeValue.All: The custom per-vertex values to copy.
returns → ShapeBuilder: this

Copies all vertices from the given shape.

Curve

public method Curve → (7)

curve ⁱⁿ : ICurve: [not-null]
The curve to follow.
range ⁱⁿ : RangeD: The control point index range of the shape.
y1b ⁱⁿ : float64: Coefficient for Y-coordinate, in curve-space (see remarks).
y2b ⁱⁿ : float64: Coefficient for Y-coordinate, in curve-space (see remarks).
y1m ^opt : float64 = 0: Coefficient for Y-coordinate, in curve-space (see remarks).
y2m ^opt : float64 = 0: Coefficient for Y-coordinate, in curve-space (see remarks).
accuracy ^opt : float64 = 0: [>=0]
The sub-division accuracy to achieve, given as the maximum allowed error in the shape coordinate system (treating control point position and tangent values as 2D vectors). Set to 0 to disable.
returns → ShapeBuilder: this.

Builds geometry follows the given curve and adds it to this shape builder.

Curve-space is defined as follows:

The coordinate origin coincides with the result of ICurve.Compute2D for the control point index zero.
The X-axis represents the control point indices in the range [0..N], where N is ICurve.Count minus one.
The Y-axis is perpendicular to the curve, where the Y-coordinate zero always lies on the curve. The sign of the Y-axis is chosen so that the points A, B and C form a triangle, according to IShape.TriangleAt:
```
A = (X,0)
B = (X + epsilon,0)
C = (X, epsilon)
```
where X is an X-coordinate value and epsilon is some sufficiently small value. The orientation of the Y-axis depends on the X-coordinate.

The geometry extend along the X-axis is defined with range ⁱⁿ. The extend along the Y-axis is computed from the Vec4D.Z values, which are obtained from ICurve.Compute3D:

y1 = y1m * Z + y1b
y2 = y2m * Z + y2b

Depending on the parameter values, the following geometry is generated:

If range ⁱⁿ has non-zero length and, y1b ⁱⁿ != y2b ⁱⁿ or y1m ^opt != y2m ^opt:
A polygon contour with negative parity (y1b ⁱⁿ < y2b ⁱⁿ) or positive parity ( y1b ⁱⁿ > y2b ⁱⁿ), see ShapeType.Polygon
Otherwise, if range ⁱⁿ has zero length and y1b ⁱⁿ = y2b ⁱⁿ and y1m ^opt = y2m ^opt:
A point, see ShapeType.Points.
Otherwise:
A polyline which is either perpendicular to the curve or parallel to it, see ShapeType.Graph

See also: ShapeBuilder.Matrix

Edge

_3 overloads

public method Edge¹ → ()

returns → ShapeBuilder: this

Specifies an edge when building a graph shape (see Graph).

This method uses the two most recently specified vertices (N-2, N-1), where N is the value of Index when this method is called.

public method Edge² → (2)

a ⁱⁿ : int32: Index of first edge vertex.
b ⁱⁿ : int32: Index of second edge vertex.
returns → ShapeBuilder: this

Specifies an edge when building a graph shape (see Graph) or polygon shape (see Polygon).

public method Edge³ → (1)

edge ⁱⁿ : Vec2I: Indices of edge vertices.
returns → ShapeBuilder: this

Specifies an edge when building a graph shape (see Graph) or polygon shape (see Polygon).

EdgeList

_6 overloads

public method EdgeList¹ → (1)

closed ^opt : bool = true: Connect last vertex to first one?
returns → ShapeBuilder: this

Specifies a sequence of connected edges (polyline) when building a graph shape (see Graph) or polygon shape (see Polygon).

An edge is generated for each pair of recently added vertices, i.e. the vertices in the range from Last (inclusive) to Index (exclusive).

public method EdgeList² → (3)

a ⁱⁿ : int32: Index of first vertex.
b ⁱⁿ : int32: Index of last vertex.
closed ^opt : bool = true: Connect last vertex to first one?
returns → ShapeBuilder: this

Specifies a sequence of connected edges (polyline) when building a graph shape (see Graph) or polygon shape (see Polygon).

The vertex sequence can be reversed by swapping a ⁱⁿ and b ⁱⁿ.

public method EdgeList³ → (2)

edges ⁱⁿ : Vec2I: Index of first (see Vec2I.X) resp. last (see Vec2I.Y) contour vertex.
closed ^opt : bool = true: Connect last vertex to first one?
returns → ShapeBuilder: this

Specifies a sequence of connected edges (polyline) when building a graph shape (see Graph) or polygon shape (see Polygon).

The vertex sequence can be reversed by swapping Vec2I.X and Vec2I.Y of edges ⁱⁿ.

public method EdgeList⁴ → (3)

edges ⁱⁿ : Vec2I [ ]: [not-null]
The list of edges (from Vec2I.X to Vec2I.Y, each).
offset ^opt : int32 = 0: [0..edges.Length]
Offset into edges ⁱⁿ.
count ^opt : int32 = -1: [-1..edges.Length-offset]
Number of edges to read from edges ⁱⁿ. If -1, all remaining edges will be read.
returns → ShapeBuilder: this

Specifies a series of edges.

public method EdgeList⁵ → (1)

edges ⁱⁿ : IArrayVector<Vec2I>: [not-null]
The list of edges (from Vec2I.X to Vec2I.Y, each).
returns → ShapeBuilder: this

Specifies a series of edges.

public method EdgeList⁶ → (1)

edges ⁱⁿ : IVectorConst<Vec2I>: [not-null]
The list of edges (from Vec2I.X to Vec2I.Y, each).
returns → ShapeBuilder: this

Specifies a series of edges.

Flags

public method Flags → (1)

value ⁱⁿ : ShapeBuilderFlags: The current flags.
returns → ShapeBuilder: this

Specifies the shape builder flags.

The default flags are ShapeBuilderFlags.None.

Georef

public method Georef → (1)

georef ⁱⁿ : CoordinateSystem: The coordinate system or null.
returns → ShapeBuilder: this

Specifies the coordinate system of the shape being built.

Grid

public method Grid → (6)

a ⁱⁿ : Vec2D: First grid corner point.
b ⁱⁿ : Vec2D: Second grid corner point.
c ⁱⁿ : Vec2D: Third grid corner point.
d ⁱⁿ : Vec2D: Fourth grid corner point.
x ⁱⁿ : int32: Number of grid points between a ⁱⁿ and b ⁱⁿ (inclusive).
y ⁱⁿ : int32: Number of grid points lines between a ⁱⁿ and d ⁱⁿ (inclusive).
returns → ShapeBuilder: this.

Creates a grid shape.

The grid is specified by the four given control points:

(a)----- + ----- + ----- + -----(b)
 |       |       |       |       |
 + ----- + ----- + ----- + ----- +
 |       |       |       |       |
 + ----- + ----- + ----- + ----- +
 |       |       |       |       |
(d)----- + ----- + ----- + -----(c)

MatrixPop

public method MatrixPop → ()

returns → ShapeBuilder: this

Removes the current transformation from the stack, which restores the transformation that has been in place before the most recent call to MatrixPush.

See also: ShapeBuilder.Matrix

MatrixPush

public method MatrixPush → (1)

matrix ⁱⁿ : Mat3D: The matrix to apply after the current matrix.
returns → ShapeBuilder: this

Appends the given transformation matrix to the current one, until MatrixPop is called.

See also: ShapeBuilder.Matrix

Metadata

public method Metadata → (1)

metadata ⁱⁿ : IJsonValue: The metadata or null.
returns → ShapeBuilder: this

Specifies the metadata of the shape being built.

Oval

public method Oval → (4)

center ⁱⁿ : Vec2D: The center of the oval.
a ⁱⁿ : Vec2D: First vector pointing from center ⁱⁿ to oval edge.
b ⁱⁿ : Vec2D: Second vector pointing from center ⁱⁿ to oval edge.
n ⁱⁿ : int32: [>=1]
The number of segments between a ⁱⁿ and b ⁱⁿ.
returns → ShapeBuilder: this.

Creates a vertex contour for an oval shape defining an approximating polygon.

The edge parity of the contour is the sign of IVec2Ops.Cross² for a ⁱⁿ and b ⁱⁿ.

Rectangle

_3 overloads

public method Rectangle¹ → (2)

box ⁱⁿ : Box2D: The rectangle.
parity ^opt : int32 = -1: The desired edge parity, see Add² for details.
returns → ShapeBuilder: this

Specifies a rectangle.

This method delegates to Rectangle²,

See also: ShapeBuilder.Matrix

public method Rectangle² → (3)

a ⁱⁿ : Vec2D: Coordinate of first rectangle corner.
b ⁱⁿ : Vec2D: Coordinate of second rectangle corner.
flip ^opt : bool = false: Flip vertex order?
returns → ShapeBuilder: this

Specifies a rectangle.

This method delegates to Rectangle³,

See also: ShapeBuilder.Matrix

public method Rectangle³ → (5)

x0 ⁱⁿ : float64: X-coordinate of first rectangle corner.
y0 ⁱⁿ : float64: Y-coordinate of first rectangle corner.
x1 ⁱⁿ : float64: X-coordinate of second rectangle corner.
y1 ⁱⁿ : float64: Y-coordinate of second rectangle corner.
flip ^opt : bool = false: Flip vertex order?
returns → ShapeBuilder: this

Specifies a rectangle.

This method calls Vertex¹ in this order:

(x0 ⁱⁿ, y0 ⁱⁿ)
(x1 ⁱⁿ, y0 ⁱⁿ)
(x1 ⁱⁿ, y1 ⁱⁿ)
(x0 ⁱⁿ, y1 ⁱⁿ)

or if flip ^opt is true:

(x0 ⁱⁿ, y0 ⁱⁿ)
(x0 ⁱⁿ, y1 ⁱⁿ)
(x1 ⁱⁿ, y1 ⁱⁿ)
(x1 ⁱⁿ, y0 ⁱⁿ)

Then, the EdgeList¹ method is called.

See also: ShapeBuilder.Matrix

Transform

public method Transform → (4)

transform ⁱⁿ : CoordinateSystemTransform: [not-null]
The coordinate system transformation to use.
accuracy ^opt : float64 = 0: [>=0]
Optional accuracy to use for subdivision of edges, interpreted according to geocentric ^opt. Set to 0 to disable edge subdivision.
geocentric ^opt : bool = false: Depicts how to interpret the given accuracy ^opt:
false : maximum error in the target coordinate system (see (see CoordinateSystemTransform.Target)
true : maximum error in the geocentric frame (see Geocentric).
verticalType ^opt : VerticalType = VerticalType.Ellipsoid: When geocentric ^opt is true, specifies the vertical coordinate type to use for computing the maximum error in the geocentric frame.
returns → ShapeBuilder: this

Applies the given coordinate transform while building shapes.

When a coordinate transform is given, the specified vertices are expected to be in the source coordinate system (see CoordinateSystemTransform.Source). The built shapes will have the target coordinate system as geo-reference (see IShapeInfo.Georef). So it is not necessary to call Georef when using a transform.

All existing geometry is cleared by this method.

See also: Geocentric

Triangle

_3 overloads

public method Triangle¹ → ()

returns → ShapeBuilder: this

Specifies a triangle when building a mesh shape (see Mesh).

This method uses the three most recently specified vertices (N-3, N-2, N-1), where N is the value of Index when this method is called.

If necessary, the given triangle vertices will be adjusted to meet the requirements of IShape.TriangleAt.

public method Triangle² → (3)

a ⁱⁿ : int32: Index of first triangle vertex.
b ⁱⁿ : int32: Index of second triangle vertex.
c ⁱⁿ : int32: Index of third triangle vertex.
returns → ShapeBuilder: this

Specifies a triangle when building a mesh shape (see Mesh).

If necessary, the given triangle vertices will be adjusted to meet the requirements of IShape.TriangleAt.

public method Triangle³ → (1)

triangle ⁱⁿ : Vec3I: Indices of triangle vertices.
returns → ShapeBuilder: this

Specifies a triangle when building a mesh shape (see Mesh).

If necessary, the given triangle vertices will be adjusted to meet the requirements of IShape.TriangleAt.

TriangleList

_3 overloads

public method TriangleList¹ → (3)

triangles ⁱⁿ : Vec3I [ ]: [not-null]
The list of triangles.
offset ^opt : int32 = 0: [0..triangles.Length]
Offset into triangles ⁱⁿ.
count ^opt : int32 = -1: [-1..triangles.Length-offset]
Number of triangles to read from triangles ⁱⁿ. If -1, all remaining triangles will be read. Defaults to -1.
returns → ShapeBuilder: this

Specifies a series of triangles.

public method TriangleList² → (1)

triangles ⁱⁿ : IArrayVector<Vec3I>: [not-null]
The list of triangles.
returns → ShapeBuilder: this

Specifies a series of triangles.

public method TriangleList³ → (1)

triangles ⁱⁿ : IVectorConst<Vec3I>: [not-null]
The list of triangles.
returns → ShapeBuilder: this

Specifies a series of triangles.

Value

_2 overloads

public method Value¹ → (2)

value ⁱⁿ : float64: The custom value.
type ⁱⁿ : ShapeValue: The type of value ⁱⁿ.
returns → ShapeBuilder: this

Specifies the custom value for the vertex that will be added next (see Index).

Custom values may be specified for vertices that have not yet been added to the shape builder and will be dropped silently if no vertex is specified for them.

See also: ShapeBuilder.Values

public method Value² → (3)

vertex ⁱⁿ : int32: [>=0]
The vertex index.
value ⁱⁿ : float64: The custom value.
type ⁱⁿ : ShapeValue: The type of value ⁱⁿ.
returns → ShapeBuilder: this

Specifies the custom value for the given vertex.

Custom values may be specified for vertices that have not yet been added to the shape builder and will be dropped silently if no vertex is specified for them.

See also: ShapeBuilder.Values

Values

public method Values → (1)

type ⁱⁿ : ShapeValue: The value type.
returns → IArrayVector<float64>: The value list or null iff no custom value of the given type ⁱⁿ has been specified so far.

The custom per-vertex values that have been specified.

See also: ShapeBuilder.Value¹
ShapeBuilder.Value²

Vertex

_2 overloads

public method Vertex¹ → (2)

x ⁱⁿ : float64: X-coordinate of vertex.
y ⁱⁿ : float64: Y-coordinate of vertex.
returns → ShapeBuilder: this

Specifies a new vertex.

public method Vertex² → (1)

vertex ⁱⁿ : Vec2D: The vertex coordinates.
returns → ShapeBuilder: this

Specifies a new vertex.

See also: ShapeBuilder.Matrix

VertexGeographic2D

public method VertexGeographic2D → (1)

vertex ⁱⁿ : LatLon: The vertex coordinates.
returns → ShapeBuilder: this

Specifies a new vertex.

If a coordinate system has been specified, the given vertex ⁱⁿ coordinates will be transformed with ICoordinateTransform.GeographicToMap of CoordinateSystem.CreateCoordinateTransform. Otherwise, the result of LatLon.ToDegrees will be used. The resulting coordinates are then passed to Vertex².

VertexGeographic3D

public method VertexGeographic3D → (1)

vertex ⁱⁿ : LatLonHeight: The vertex coordinates.
returns → ShapeBuilder: this

Specifies a new vertex.

This method delegates to VertexGeographic2D passing LatLonHeight.Coords and then to Value² passing LatLonHeight.Vertical as ShapeValue.Vertical.