ShapeBuilder

Description

sealed class Tinman.Terrain.Shapes.ShapeBuilder

Helper class for building geometric shapes.

To build a geometric shape, perform the following steps:

  1. Create a shape builder via Shape.Geometry or call Clear on an existing builder for starting from scratch.

  2. Configure the shape builder flags via Flags.

  3. Configure the geo-reference via Georef.

  4. Configure a transformation via Transform.

  5. Add geometric primitives:

    • Vertices (see Vertex* methods)

    • Edges (see Edge* methods)

    • Triangles (see Triangle* methods)

  6. Add pre-defined geometric shapes:

  7. Finish shape building by calling one of the following methods:

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 Vertex1), edges (see Edge2) and/or triangles (see Triangle2).

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

  1. Mesh: when one or more triangles have been specified.

  2. Graph: when one or more edges have been specified and edgeParity opt is zero.

  3. Polygon: when one or more edges have been specified and edgeParity opt is not zero.

  4. 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 Vertex1) and edges (see Edge2).

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 Vertex1).

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 Vertex1).

Polygon


public method Polygon → (2)

negative in : 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 Vertex1) and edges (see Edge2).

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 Add1 → (3)

shape in : 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 Add2 → (4)

shape in : IShape

The shape.

flip in : bool

Flip edge resp. triangle vertices?

matrix in : Mat3D

Homogeneous 2D transformation matrix to apply to the vertex coordinates of shape in.

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 in is true, edges (A,B) resp. triangles (A,B,C) are added as (B,A) resp. (C,B,A).

Area

2 overloads


public method Area1 → ()

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.


public method Area2 → (2)

in : int32

Index of first polygon vertex.

in : 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.

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:

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

Clear​Edges


public method ClearEdges → ()

returns → ShapeBuilder

this

Clears geometry data in the shape builder.

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

Clear​Triangles


public method ClearTriangles → ()

returns → ShapeBuilder

this

Clears geometry data in the shape builder.

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

Clear​Values


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

Clear​Vertices


public method ClearVertices → ()

returns → ShapeBuilder

this

Clears geometry data in the shape builder.

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

Curve


public method Curve → (7)

curve in : ICurve

[not-null]
The curve to follow.

range in : RangeD

The control point index range of the shape.

y1b in : float64

Coefficient for Y-coordinate, in curve-space (see remarks).

y2b in : 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 in. 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 in has non-zero length and, y1b in != y2b in or y1m opt != y2m opt:
    A polygon contour with negative parity (y1b in < y2b in) or positive parity ( y1b in > y2b in), see ShapeType.Polygon

  • Otherwise, if range in has zero length and y1b in = y2b in 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 Edge1 → ()

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 Edge2 → (2)

in : int32

Index of first edge vertex.

in : 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 Edge3 → (1)

edge in : Vec2I

Indices of edge vertices.

returns → ShapeBuilder

this

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

Edge​List

6 overloads


public method EdgeList1 → (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 EdgeList2 → (3)

in : int32

Index of first vertex.

in : 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 in and in.


public method EdgeList3 → (2)

edges in : 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 in.


public method EdgeList4 → (3)

edges in : Vec2I [ ]

[not-null]
The list of edges (from Vec2I.X to Vec2I.Y, each).

offset opt : int32 = 0

[0..edges.Length]
Offset into edges in.

count opt : int32 = -1

[-1..edges.Length-offset]
Number of edges to read from edges in. If -1, all remaining edges will be read.

returns → ShapeBuilder

this

Specifies a series of edges.


public method EdgeList5 → (1)

edges in : 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 EdgeList6 → (1)

edges in : 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 in : ShapeBuilderFlags

The current flags.

returns → ShapeBuilder

this

Specifies the shape builder flags.

The default flags are ShapeBuilderFlags.None.

Georef


public method Georef → (1)

georef in : CoordinateSystem

The coordinate system or null.

returns → ShapeBuilder

this

Specifies the coordinate system of the shape being built.

Metadata


public method Metadata → (1)

metadata in : IJsonValue

The metadata or null.

returns → ShapeBuilder

this

Specifies the metadata of the shape being built.

Rectangle

3 overloads


public method Rectangle1 → (1)

box in : Box2D

The rectangle.

returns → ShapeBuilder

this

Specifies a rectangle.

This method delegates to Rectangle3,


public method Rectangle2 → (2)

in : Vec2D

Coordinate of first rectangle corner.

in : Vec2D

Coordinate of second rectangle corner.

returns → ShapeBuilder

this

Specifies a rectangle.

This method delegates to Rectangle3,


public method Rectangle3 → (4)

x0 in : float64

X-coordinate of first rectangle corner.

y0 in : float64

Y-coordinate of first rectangle corner.

x1 in : float64

X-coordinate of second rectangle corner.

y1 in : float64

Y-coordinate of second rectangle corner.

returns → ShapeBuilder

this

Specifies a rectangle.

This method calls Vertex1 in this order:

  • (x0 in, y0 in)

  • (x1 in, y0 in)

  • (x1 in, y1 in)

  • (x0 in, y1 in)

Then, the EdgeList1 method is called.

Transform


public method Transform → (4)

transform in : 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 Triangle1 → ()

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 Triangle2 → (3)

in : int32

Index of first triangle vertex.

in : int32

Index of second triangle vertex.

in : 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 Triangle3 → (1)

triangle in : 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.

Triangle​List

3 overloads


public method TriangleList1 → (3)

triangles in : Vec3I [ ]

[not-null]
The list of triangles.

offset opt : int32 = 0

[0..triangles.Length]
Offset into triangles in.

count opt : int32 = -1

[-1..triangles.Length-offset]
Number of triangles to read from triangles in. If -1, all remaining triangles will be read. Defaults to -1.

returns → ShapeBuilder

this

Specifies a series of triangles.


public method TriangleList2 → (1)

triangles in : IArrayVector<Vec3I>

[not-null]
The list of triangles.

returns → ShapeBuilder

this

Specifies a series of triangles.


public method TriangleList3 → (1)

triangles in : IVectorConst<Vec3I>

[not-null]
The list of triangles.

returns → ShapeBuilder

this

Specifies a series of triangles.

Value

2 overloads


public method Value1 → (2)

value in : float64

The custom value.

type in : ShapeValue

The type of value in.

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.


public method Value2 → (3)

vertex in : int32

[>=0]
The vertex index.

value in : float64

The custom value.

type in : ShapeValue

The type of value in.

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.

Values


public method Values → (1)

type in : ShapeValue

The value type.

returns → IArrayVector<float64>

The value list or null iff no custom value of the given type in has been specified so far.

The custom per-vertex values that have been specified.

Vertex

2 overloads


public method Vertex1 → (2)

in : float64

X-coordinate of vertex.

in : float64

Y-coordinate of vertex.

returns → ShapeBuilder

this

Specifies a new vertex.


public method Vertex2 → (1)

vertex in : Vec2D

The vertex coordinates.

returns → ShapeBuilder

this

Specifies a new vertex.

Vertex​List

3 overloads


public method VertexList1 → (3)

vertices in : Vec2D [ ]

[not-null]
The list of vertices.

offset opt : int32 = 0

[0..vertices.Length]
Offset into vertices in.

count opt : int32 = -1

[-1..vertices.Length-offset]
Number of vertices to read from vertices in. If -1, all remaining vertices will be read.

returns → ShapeBuilder

this

Specifies a series of vertices.


public method VertexList2 → (1)

vertices in : IArrayVector<Vec2D>

[not-null]
The list of vertices.

returns → ShapeBuilder

this

Specifies a series of vertices.


public method VertexList3 → (1)

vertices in : 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.

Indices​Original


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.