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 a transformation via Transform.
Add geometric primitives:
- Vertices (see Vertex* methods)
- Edges (see Edge* methods)
- Triangles (see Triangle* methods)
Add pre-defined geometric shapes:
- Splines (see Curve)
- Boxes (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 ⁱⁿ : bool: Shall the built polygon have a 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 Geometric.AreaPolygon¹).

Public / Methods

Add

_2 overloads

public method Add¹ → (3)

shape ⁱⁿ : IShape: The shape.
flip ^opt : bool = false: Flip edge resp. triangle vertices?
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).

public method Add² → (4)

shape ⁱⁿ : IShape: The shape.
flip ⁱⁿ : bool: Flip edge resp. triangle vertices?
matrix ⁱⁿ : Mat3D: Homogeneous 2D transformation matrix to apply to the vertex coordinates of shape ⁱⁿ.
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 ⁱⁿ is true, edges (A,B) resp. triangles (A,B,C) are added as (B,A) resp. (C,B,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¹

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

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

Edge

_3 overloads

public method Edge¹ → ()

returns → ShapeBuilder: this

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

This method uses the three 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 consecutive vertices. When this method is called multiple times, edges are generated only for newly specified vertices.

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.

Metadata

public method Metadata → (1)

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

Specifies the metadata of the shape being built.

Rectangle

_3 overloads

public method Rectangle¹ → (1)

box ⁱⁿ : Box2D: The rectangle.
returns → ShapeBuilder: this

Specifies a rectangle.

This method delegates to Rectangle³,

public method Rectangle² → (2)

a ⁱⁿ : Vec2D: Coordinate of first rectangle corner.
b ⁱⁿ : Vec2D: Coordinate of second rectangle corner.
returns → ShapeBuilder: this

Specifies a rectangle.

This method delegates to Rectangle³,

public method Rectangle³ → (4)

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.
returns → ShapeBuilder: this

Specifies a rectangle.

This method calls Vertex¹ in this order:

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

Then, the EdgeList¹ method is called.

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.

VertexList

_3 overloads

public method VertexList¹ → (3)

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

Specifies a series of vertices.

public method VertexList² → (1)

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

Specifies a series of vertices.

public method VertexList³ → (1)

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

Specifies a series of vertices.

Public / Attributes

Edges

public attribute Edges → (get)

value : IArrayVector<Vec2I>: [not-null]
The edge list.

The list of edges that have been specified.

Geocentric

public attribute Geocentric → (get)

value : Geocentric: The geocentric helper object or null iff not in geocentric mode.

In geocentric mode (see Transform), returns the helper object that is used for geocentric computations.

Index

public attribute Index → (get)

value : int32: [>=0]
The next vertex index.

Returns the next vertex index.

See also: ShapeBuilder.Vertex¹

IndicesOriginal

public attribute IndicesOriginal → (get)

value : int32 [ ]: The vertex index mapping of the most recently built shape or null.

Mapping from built shape vertex indices to original input vertex indices.

Triangles

public attribute Triangles → (get)

value : IArrayVector<Vec3I>: [not-null]
The vertex list.

The list of triangles that have been specified.

Vertices

public attribute Vertices → (get)

value : IArrayVector<Vec2D>: [not-null]
The vertex list.

The list of vertices that have been specified.

ShapeBuilder

Description

Public / Constructors

Build

Graph

Hull

Mesh

Points

Polygon

Public / Methods

Add

Area

Clear

Clear​Edges

Clear​Triangles

Clear​Values

Clear​Vertices

Curve

Edge

Edge​List

Flags

Georef

Metadata

Rectangle

Transform

Triangle

Triangle​List

Value

Values

Vertex

Vertex​List

Public / Attributes

Edges

Geocentric

Index

Indices​Original

Triangles

Vertices

ClearEdges

ClearTriangles

ClearValues

ClearVertices

EdgeList

TriangleList

VertexList

IndicesOriginal