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.Winding1 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 in : 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 in : 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 in are disjoint.
0 if this shape and box in intersect.
1 if box in fully contains this shape.
2 if this shape fully contains box in.

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 DistanceTo1 → (5)

in : float64

X-coordinate of point.

in : 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 DistanceTo2 → (3)

in : float64

X-coordinate of point.

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

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.

EdgeAt


public method EdgeAt → (1)

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

EdgeNext


public method EdgeNext → (1)

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

Face


public method Face → (1)

face in : 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 in : 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.AreaTriangle1).

VertexAt


public method VertexAt → (1)

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

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

latitude in : float64

The geographic latitude angle, in radians.

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

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

DistanceTo


public static method DistanceTo → (2)

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

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.

ImportCSH


[OwnerReturn]
public static method ImportCSH → (1)

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