IShape

Description

interface Tinman.Terrain.Shapes.IShape

Derived from: IShapeInfo
IShapeOps
ISerializable
Extended by: IShapeGroup
ShapeBase ^abstract

Base interface for geometric two-dimensional shapes that are defined by a distance field.

Shapes can be defined implicitly. In this case, IShapeInfo.VertexCount returns zero and the implementation class is responsible for computing a proper distance field. Explicit shape definitions make use of vertices (see VertexAt), edges (EdgeAt) and triangles (TriangleAt). Edges can also be used to define polygon contours (see EdgeWalk and IShapeInfo.EdgeParity). To built an explicit shape, use Shape.Geometry.

shape type |   vertex |     edge | triangle |   edge
           |    count |    count |    count | parity
-----------+----------+----------+----------+-------
Implicit   |        0 |        0 |        0 |      0
-----------+----------+----------+----------+-------
Points     |      > 0 |        0 |        0 |      0
-----------+----------+----------+----------+-------
Graph      |      > 0 |      > 0 |        0 |      0
-----------+----------+----------+----------+-------
Polygon    |      > 0 |      > 0 |        0 |   != 0
-----------+----------+----------+----------+-------
Mesh       |      > 0 |        0 |      > 0 |      0

All other combinations are invalid, see ShapeType.

A polygon is made up of one or more contours, where each contour is a connected sequence of non-intersecting edges. Polygon contours are defined piecewise by the set of edges (see EdgeAt). A contour can either be an outer ring or a hole, depending on the winding of its vertices.

In order to test whether a point p lies in the inside or outside half-space of a contour edge between two vertices v0 and v1, the Geometric.Winding¹ method can be used:

w       := Winding(v0, v1, p)
inside  := w == Parity
outside := w != Parity
where w != 0

Usually, contours will be closed. Open contours can occur during transformation of shapes from one coordinate system to another (see IShapeOps.TransformCoordinateSystem or IShapeOps.TransformCubemap) for vertex coordinates which are not defined in the target coordinate system.

Public / Methods

Accept

public method Accept → (2)

visitor ⁱⁿ : IShapeVisitor: [not-null]
The shape visitor object.
userData ^opt : object = null: Optional user data.

Accepts the given IShapeVisitor object.

CheckIntersection

[ThreadSafe]
public method CheckIntersection → (2)

box ⁱⁿ : Box2D: The box bounds.
offset ^opt : float64 = 0: Optional distance offset to apply to this shape for the intersection test.
returns → int32: -1 if this shape and box ⁱⁿ are disjoint.
0 if this shape and box ⁱⁿ intersect.
1 if box ⁱⁿ fully contains this shape.
2 if this shape fully contains box ⁱⁿ.

Checks the intersection between this shape and the given bounds.

ContourStart

public method ContourStart → ()

returns → int32 [ ]: The polygon contours. Each element represents the index of an edge that belongs to the contour. For closed contours, the edge with the smallest index is given. For non-closed contours, the first edge is given. Will be empty if this shape is not of type ShapeType.Polygon.

Computes the contours of this polygon shape.

This method will not perform any geometric processing. Instead, it simply uses IShapeInfo.EdgeCount, EdgeAt and EdgeWalk in order to find the polygon contours.

DistanceTo

_2 overloads

[ThreadSafe]
public method DistanceTo¹ → (5)

x ⁱⁿ : float64: X-coordinate of point.
y ⁱⁿ : float64: Y-coordinate of point.
vertices ^out : Vec3I: Shape vertex indices (see VertexAt) that describe the location of the nearest shape feature.
weights ^out : Vec3D: Location of the nearest shape feature, given as relative weights (i.e. the weight sum is 1) of vertices ^out. The weights are sorted in descending order, i.e. Vec3D.X always holds the greatest weight and Vec3D.Z always holds the smallest weight.
maximum ^opt : float64 = Maths.MaxDouble: The maximum relevant distance. This is a hint for the implementing class which can be exploited in order to optimize performance.
returns → float64: Smallest distance to the shape. All results greater than maximum ^opt are considered irrelevant. Implementing methods are free to discard those results.

Computes the smallest distance from the given point to the shape, additionally returning the corresponding nearest feature point on the shape.

If the point lies outside of the shape, the returned distance will be greater than zero. If the point is inside of the shape, the returned distance will be negative. The returned distance will be zero if the point exactly lies on the shape boundary.

[ThreadSafe]
public method DistanceTo² → (3)

x ⁱⁿ : float64: X-coordinate of point.
y ⁱⁿ : float64: Y-coordinate of point.
maximum ^opt : float64 = Maths.MaxDouble: The maximum relevant distance. This is a hint for the implementing class which can be exploited in order to optimize performance.
returns → float64: Smallest distance to the shape.

Computes the smallest distance from the given point to the shape.

EdgeAt

public method EdgeAt → (1)

index ⁱⁿ : int32: [0..IShapeInfo.EdgeCount-1]
The edge index.
returns → Vec2I: The shape edge.

Returns a shape edge.

Each edge connects two vertices (see VertexAt), in the direction from Vec2I.X to Vec2I.Y.

All points that lie on an edge have a shape distance of zero.

See also: IShapeInfo.EdgeCount

EdgeNext

public method EdgeNext → (1)

index ⁱⁿ : int32: [0..IShapeInfo.EdgeCount-1]
The edge index.
returns → int32: Index of next edge (see EdgeAt) or -1 if there is no next edge (i.e. the contour is not closed).

Returns the next edge for walking along the polygon contour.

See also: IShape.EdgePrev

EdgePrev

public method EdgePrev → (1)

index ⁱⁿ : int32: [0..IShapeInfo.EdgeCount-1]
The edge index.
returns → int32: Index of previous edge (see EdgeAt) or -1 if there is no previous edge (i.e. the contour is not closed).

Returns the previous edge for walking along the polygon contour.

See also: IShape.EdgeNext

EdgeWalk

public method EdgeWalk → (1)

index ⁱⁿ : int32: [0..IShapeInfo.EdgeCount-1]
The edge index.
returns → Vec2I: Index of neighbouring edge (see EdgeAt):
Vec2I.X points to previous edge, Vec2I.Y points to next edge. The component will be -1 if there is no neighbouring edge (i.e. the contour is not closed). Both components will be -1 for non-polygon shapes.

Returns the neighbouring edges for walking along the polygon contour.

See also: IShape.EdgePrev
IShape.EdgeNext

Face

public method Face → (1)

face ⁱⁿ : CubemapFace: The cubemap face.
returns → IShape: The shape or null if there are no shape parts on the given cubemap face.

Returns the shape on the given cubemap face.

Passing CubemapFace.NegZ to an ordinary shape will return this. Cubemap shapes (see IShapeOps.TransformCubemap) will return an aggregated shape for each cubemap face, or null.

Cubemap shapes are used by IHeightmapShape and IPixelPyramidShape objects.

TriangleAt

public method TriangleAt → (1)

index ⁱⁿ : int32: [0..IShapeInfo.TriangleCount-1]
The triangle index.
returns → Vec3I: The shape triangle.

Returns a shape triangle.

Each triangle connects three vertices (see VertexAt), in the order Vec3I.X, Vec3I.Y, Vec3I.Z, where Vec3I.X <Vec3I.Y and Vec3I.X < Vec3I.Z. The vertex winding is chosen so that the signed triangle area is positive (see Geometric.AreaTriangle¹).

VertexAt

public method VertexAt → (1)

index ⁱⁿ : int32: [0..IShapeInfo.VertexCount-1]
The vertex index.
returns → Vec2D: The shape vertex.

Returns a shape vertex.

All vertices have a shape distance of zero.

See also: IShapeInfo.VertexCount

Public / Attributes

Bounds

public attribute Bounds → (get)

value : Box2D: The axis-aligned bounding box.

Returns the axis-aligned bounding box of this shape.

The bounding box is defined as the smallest possible rectangle that contains all points which have a shape distance of zero or less.

IsGeometry

public attribute IsGeometry → (get)

value : bool: true if this shape has plain geometry only, false if not.

Does this shape consist of plain geometry only?

Shapes with plain geometry can be rebuilt via Shape.Geometry.

Extensions

Contains

_2 overloads

public static method Contains¹ → (2)

latitude ⁱⁿ : float64: The geographic latitude angle, in radians.
longitude ⁱⁿ : float64: The geographic longitude angle, in radians.
returns → bool: true if the given coordinates are inside of this shape,
false if they are outside of it.

Checks if this shape contains the given geographic coordinates.

public static method Contains² → (1)

latLon ⁱⁿ : LatLon: The geographic coordinates.
returns → bool: true if the given coordinates are inside of this shape,
false if they are outside of it.

Checks if this shape contains the given geographic coordinates.

ContourClosed

public static method ContourClosed → (1)

contour ⁱⁿ : int32: The contour index, as returned by IShape.ContourStart.
returns → bool: true if the polygon shape contour is closed, false if not.

Checks if the given polygon shape contour is closed.

Contours

public static method Contours → ()

returns → int32 [ ] [ ]: The vertices of each contour. Will be empty if this shape is not of type ShapeType.Polygon.

Computes the vertices of each contour of this polygon shape.

The returned array may be accessed as follows:

contours[N][M] := vertex index

where N is the contour index and M is the vertex index in the contour.

ContourVertices

public static method ContourVertices → (1)

contour ⁱⁿ : int32: The contour index, as returned by IShape.ContourStart.
returns → int32 [ ]: The vertices on the polygon contour. Will be empty if this shape is not of type ShapeType.Polygon.

Computes the vertices on the given polygon contour.

The first and the last vertex will be the same iff the polygon contour is closed.

ConvexHull

public static method ConvexHull → ()

returns → IShape: The convex hull or null if this shape does not have any vertices.

Computes the convex hull of vertices of this shape.

See also: ShapeBuilder.Hull

DistanceTo

public static method DistanceTo → (2)

point ⁱⁿ : Vec2D: The point coordinates.
maximum ^opt : float64 = Maths.MaxDouble: The maximum relevant distance. This is a hint for the implementing class which can be exploited in order to optimize performance.
returns → float64: Shortest distance to the shape.

Computes the shortest distance from the given point to the shape.

ImportCSH

[OwnerReturn]
public static method ImportCSH → (1)

output ⁱⁿ : Path: [not-null]
Path to output CSH file.
returns → IOperation: The IOperation object that will write the shape file.

Imports this shape into a CSH file (Compressed SHape).

The returned IOperation object will use the WriteCSH method to write the actual file contents.

WriteCSH

public static method WriteCSH → (1)

stream ⁱⁿ : IDataStream: [not-null]
The output data stream.

Writes this shape to a CSH file (Compressed SHape).

IOException: If an I/O error has occurred.

See also: IShape.ImportCSH