# IShape

## Description

`interface` `Tinman.Terrain.Shapes.IShape`

Derived from
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

`[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.

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.

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

`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.