TINMAN 3D / REALTIME TERRAIN
Software Development Kit - User Manual

interface IShape in Tinman.Terrain.Shapes

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

interface IShape extends ISerializable
  IShapeInfo
  base of IShapeGroup
  ShapeBase

Remarks

Shapes can be defined implicitly. In this case, 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 EdgeParity). To built an explicit shape, use 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.

A polygon is made up of one or more contours, where each contour is a connected sequence of edges, usually forming a closed ring. Polygon contours are defined piecewise by the set of edges (see EdgeAt). A contour can either be an outer ring or a hole.

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 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 TransformCoordinateSystem or TransformCubemap) for vertex coordinates which are not defined in the target coordinate system.

Attributes

Bounds

Returns the axis-aligned bounding box of this shape.

property Bounds { get }
type Box2D
value The axis-aligned bounding box.

Remarks:

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

EdgeCount

Returns the number of shape edges.

property EdgeCount { get }
type int32
value [>=0] The number of shape edges.
inherited IShapeInfo.EdgeCount

See also:

EdgeAt

EdgeParity

Defines how the vertex winding of polygon contours is interpreted (outer rings vs. holes).

property EdgeParity { get }
type int32
value The parity value: +/- 1 for polygons, 0 for non-polygon shapes.
inherited IShapeInfo.EdgeParity

Remarks:

A polygon contour is classified as an outer ring or a hole according to the sign of its signed area:

outer := sign(Area(contour)) == Parity
hole  := sign(Area(contour)) != Parity
The default value is -1 (i.e. clockwise orientation in a standard Cartesian coordinate system).

Georef

The coordinate system of the shape.

property Georef { get }
type CoordinateSystem
value [not-null] The coordinate system.
inherited IShapeInfo.Georef

Remarks:

The default coordinate system is a local one (see IsLocal) in metres (see Metre).

IsCubemap

Is this a cubemap shape?

property IsCubemap { get }
type bool
value true if this is a cubemap shape, false if not.
inherited IShapeInfo.IsCubemap

Remarks:

Cubemap shapes have a geographic coordinate system (see IsGeographic) and six separate sub-shapes, one for each cubemap face (see Cubemap)).

See also:

TransformCubemap
Face

IsGeometry

Does this shape consist of plain geometry only?

property IsGeometry { get }
type bool
value true if this shape has plain geometry only, false if not.

Remarks:

Shapes with plain geometry can be rebuilt via Geometry.

SerialType

Returns the serial type of this object.

property SerialType { get }
type ISerialTypeInfo
value [not-null] The serial type.
inherited ISerializable.SerialType

SerialVersion

Returns the serial data version.

property SerialVersion { get }
type int32
value [>=1] The serial data version tag.
inherited ISerializable.SerialVersion

Remarks:

An ISerializable implementation is required to support all versions up to the one returned by SerialVersion.

See also:

ISerializable.Serialize
ISerializable.Deserialize

TriangleCount

Returns the number of shape triangles.

property TriangleCount { get }
type int32
value [>=0] The number of shape triangles.
inherited IShapeInfo.TriangleCount

Type

The shape type.

property Type { get }
type ShapeType
value The shape type.
inherited IShapeInfo.Type

VertexCount

Returns the number of shape vertices.

property VertexCount { get }
type int32
value [>=0] The number of shape vertices.
inherited IShapeInfo.VertexCount

Remarks:

When the vertex count is zero, the shape is defined implicitly. If the vertex count is greater than zero, the shape is explicitly defined by its vertices.

See also:

VertexAt

Methods

Absolute

Returns a shape that returns the absolute distance value (i.e. the outline of this shape).

method Absolute ()
type IShape
returns [not-null] The resulting shape.

Accept

Accepts the given IShapeVisitor object.

method Accept (IShapeVisitor visitor, object userData = null)
params visitor [not-null] The shape visitor object.
  userData Optional user data. Defaults to null.

CheckIntersection

Checks the intersection between this shape and the given bounds.

[ThreadSafe]
method CheckIntersection (Box2D box, float64 offset = 0)
type int32
params box The box bounds.
  offset Optional distance offset to apply to this shape for the intersection test. Defaults to 0.
returns -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.

Compile

Compiles this shape into the most compact form.

method Compile ()
type IShape
returns [not-null] The resulting shape.

Remarks:

Calling this method will not modify the geometry of a shape, only the object model structure.

Deserialize

Initializes the state of this object from the given data stream.

method Deserialize (int32 serialVersion, ISerializer data)
type ISerializable
params serialVersion [>=1] The serial data version.
  data [not-null] The serial data stream.
returns [not-null] The deserialized object. This will typically be this, but in some circumstances, another instance may be returned (e.g. singletons).
inherited ISerializable.Deserialize

Remarks:

The Deserialize method will be called immediately after the object has been instantiated via its default constructor.

The provided serialVersion number is guaranteed to be equal to or less than the SerialVersion returned by this object (i.e. ISerializable object must provide backwards compatibility).

See also:

ISerializable.Serialize
ISerializable.SerialVersion

DistanceTo

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

[ThreadSafe]
method DistanceTo (float64 x, float64 y, float64 maximum = Maths.MaxDouble)
type float64
params x X-coordinate of point.
  y Y-coordinate of point.
  maximum The maximum relevant distance. This is a hint for the implementing class which can be exploited in order to optimize performance.
returns Smallest distance to the shape.

Remarks:

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.


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

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

Remarks:

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

Returns a shape edge.

method EdgeAt (int32 index)
type Vec2I
params index [0..EdgeCount-1] The edge index.
returns The shape edge.

Remarks:

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

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

See also:

IShapeInfo.EdgeCount

EdgeWalk

Returns the neighbouring edges for walking along a polygon contour.

method EdgeWalk (int32 index)
type Vec2I
params index [0..EdgeCount-1] The edge index.
returns Index of neighbouring edge (see IShape):
X points to previous edge, 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.

Face

Returns the shape on the given cubemap face.

method Face (CubemapFace face)
type IShape
params face The cubemap face.
returns The shape or null if there are no shape parts on the given cubemap face.

Remarks:

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

Cubemap shapes are used by IHeightmapShape and IPixelPyramidShape objects.

Invert

Inverts this shape.

method Invert ()
type IShape
returns [not-null] The inverted shape.

Maximum

Returns a composite shape that returns the maximum distance value (i.e. intersection of this shape and the given one).

method Maximum (IShape shape)
type IShape
params shape [not-null] The other shape.
returns [not-null] The resulting shape.

Minimum

Returns a composite shape that returns the minimum distance value (i.e. the union of this shape and the given one).

method Minimum (IShape shape)
type IShape
params shape [not-null] The other shape.
returns [not-null] The resulting shape.

Offset

Applies a distance offset to this shape.

method Offset (float64 offset)
type IShape
params offset The distance offset to apply.
returns [not-null] The resulting shape.

Serialize

Serializes the current state of this object to the given data stream.

method Serialize (ISerializer data)
params data [not-null] The serial data stream.
inherited ISerializable.Serialize

See also:

ISerializable.Deserialize
ISerializable.SerialVersion

ToConfig

Returns the configuration value that describes this object.

method ToConfig ()
type ConfigValue
returns [not-null] The configuration value.
inherited IConfigurable.ToConfig

Remarks:

All configurable objects need to implement this interface. For simple types, it is preferable to delegate to ToValue.

The returned value may be of type Invalid, which means that this object in its current state cannot be described with the configuration API.

Before returning the resulting configuration value, Cache must be called on it, passing this IConfigurable object as parameter.

TransformCoordinates

Transforms this shape using the given 2D homogeneous matrix.

method TransformCoordinates (Mat3D matrix)
type IShape
params matrix The 2D homogeneous matrix.
returns [not-null] The transforming shape.

Remarks:

Shape coordinates of this shape are multiplied with matrix using Mul2 (w = 1) in order to produce shape coordinates of the returned shape.

TransformCoordinateSystem

Transforms this shape to the given coordinate system.

method TransformCoordinateSystem (CoordinateSystem target, float64 accuracy = 0)
type IShape
params target [not-null] The target coordinate system.
  accuracy [>=0] Optional accuracy to use for subdivision of edges. Given as a maximum error in the target coordinate system (see target. HorizontalUnit). Set to 0 to disable edge subdivision. Defaults to 0.
returns [not-null] The transforming shape.

Remarks:

Transformation cannot be performed from resp. to a local coordinate system (see IsLocal). A transformation between two local coordinate system is possible, but only a conversion regarding unit of measure (see LocalUnit) and coordinate system flags (see CoordinateSystemFlags) is done.

Implicit shapes cannot be transformed (see IShape).

TransformCubemap

Transforms this shape to a geographic cubemap coordinate system.

method TransformCubemap (float64 accuracy = 0)
type IShape
params accuracy [>=0] Optional accuracy to use for subdivision of edges. Given as a maximum error in the target coordinate system (see Face). Set to 0 to disable edge subdivision. Defaults to 0.
returns [not-null] The transforming cubemap shape.

See also:

CoordinateSystem.ToCubemapFace

TransformGeometry

Transforms this shape to the given coordinate system.

method TransformGeometry (CoordinateSystemTransform transform, float64 accuracy = 0)
type IShape
params transform [not-null] The coordinate system transformation to apply.
  accuracy [>=0] Optional accuracy to use for subdivision of edges. Given as a maximum error in the target coordinate system (see transform. Target. HorizontalUnit). Set to 0 to disable edge subdivision. Defaults to 0.
returns The transformed shape or null if the transformed shape is empty or if the transformation is not possible (see remarks).

Remarks:

Transformation cannot be performed from resp. to a local coordinate system (see IsLocal). A transformation between two local coordinate system is possible, but only a conversion regarding unit of measure (see LocalUnit) and coordinate system flags (see CoordinateSystemFlags) is done.

Implicit shapes cannot be transformed (see IShape).

TriangleAt

Returns a shape triangle.

method TriangleAt (int32 index)
type Vec3I
params index [0..TriangleCount-1] The triangle index.
returns The shape triangle.

Remarks:

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

VertexAt

Returns a shape vertex.

method VertexAt (int32 index)
type Vec2D
params index [0..VertexCount-1] The vertex index.
returns The shape vertex.

Remarks:

All vertices have a shape distance of zero.

See also:

IShapeInfo.VertexCount

Extensions

Contains

method Contains (LatLon latLon)
type bool
params latLon

method Contains (float64 latitude, float64 longitude)
type bool
params latitude
  longitude

ConvexHull

Computes the convex hull of vertices of this shape.

method ConvexHull ()
type IShape
returns The convex hull or null if this shape does not have any vertices.

DistanceTo

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

method DistanceTo (Vec2D point, float64 maximum = Maths.MaxDouble)
type float64
params point The point coordinates.
  maximum The maximum relevant distance. This is a hint for the implementing class which can be exploited in order to optimize performance.
returns Shortest distance to the shape.

Remarks:

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

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

[OwnerReturn]
method ImportCSH (Path output)
type IOperation
params output [not-null] Path to output CSH file.

Outline

Returns a shape that covers the outline of this shape.

method Outline (float64 width = 0)
type IShape
params width [>=0] Width of outline shape. Defaults to 0.
returns [not-null] The resulting shape.

Rasterizer

Returns a ShapeRasterizer object that rasterizes distance values into the given sample buffer.

method Rasterizer (IColorRamp colorRamp)
type IShapeRasterizer<ColorBuffer>
params colorRamp [not-null] The color ramp to use.
returns [not-null] The shape rasterizer.

Remarks:

Distance values are converted into color values by performing a color ramp lookup.

See also:

IColorRamp
ColorBuffer

Returns a ShapeRasterizer object that rasterizes distance values into the given sample buffer.

method Rasterizer (HeightmapSamples samples, float64 falloff)
type IShapeRasterizer<HeightmapRegion>
params samples [not-null] Heightmap sample values per shape vertex.
  falloff [>=0] Distance falloff at shape boundary.
returns [not-null] The shape rasterizer.

Remarks:

The shape interior is rasterized by interpolating the shape vertices: Each vertex (see VertexAt) has a corresponding heightmap value in samples.

See also:

HeightmapRegion

Returns a ShapeRasterizer object that rasterizes distance values into the given sample buffer.

method Rasterizer (HeightmapSample sample, float64 falloff)
type IShapeRasterizer<HeightmapRegion>
params sample The uniform heightmap sample of the shape.
  falloff [>=0] Distance falloff at shape boundary.
returns [not-null] The shape rasterizer.

Remarks:

The shape interior is rasterized using the given uniform heightmap sample value.

See also:

HeightmapRegion

TransformCoordinates

Transforms this shape using the center of its bounds as the origin.

method TransformCoordinates (Transform transform)
type IShape
params transform The transform to apply.
returns [not-null] The resulting shape.

See also:

Transforms.TransformPointD

Transforms this shape using the given homogeneous matrix.

method TransformCoordinates (Mat2D matrix)
type IShape
params matrix The homogeneous transformation matrix.
returns [not-null] The resulting shape.

Transforms this shape.

method TransformCoordinates (Transform transform, Vec2D center)
type IShape
params transform The transform to apply.
  center The transformation center.
returns [not-null] The resulting shape.

See also:

Transforms.TransformPointD

WriteCSH

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

method WriteCSH (IDataStream stream)
params stream [not-null] The output data stream.