IShape
Description
- Derived from
- Extended by
-
ShapeBase abstract
Base interface for geometric two-dimensional shapes that are defined by a distance field.
Shapes may be defined implicitly. In this case, the implementation class is responsible for computing the signed distance field (usually applying distance field offsets, for example to generate a circle around a point), using arbitrary arithmetic. Explicit shape definitions on the other hand make use of vertices (see VertexAt), edges (see EdgeAt) and triangles (see TriangleAt) to define the signed distance field with standard arithmetic (i.e. distance to point, distance to line segment, distance to triangle). To built an explicit shape, use Shape.Geometry.
Polygons are defined by one or more contours (see IShape.Contours), where each contour is a connected sequence of edges (see EdgeAt and EdgeWalk). Polygon contours do not intersect (but may share common edges) and will either be an outer ring or an inner ring (i.e. a hole), depending on the winding of its vertices (see IShapeInfo.EdgeParity).
Shapes may aggregate other shapes (see ShapeAt), optionally exposing all or some of the aggregated shape vertices as well (see ShapeVertex). Cubemap shapes contain up to six aggregated shapes (see ShapeFind), one for each cubemap face, having special a geo-reference (see CoordinateOperationMethod.Face).
The following table illustrates the different shape types and their relation to aggregated shapes and contained vertices / edges / triangles:
Shape | Shape | Vertex | Edge | Edge |Triangle Type | Count | Count | Count | Parity | Count ---------+--------+--------+--------+--------+-------- Implicit | >= 0 | >= 0 | = 0 | = 0 | = 0 ---------+--------+--------+--------+--------+-------- Group | >= 0 | >= 0 | = 0 | = 0 | = 0 ---------+--------+--------+--------+--------+-------- Cubemap | 0..6 | = 0 | = 0 | = 0 | = 0 ---------+--------+--------+--------+--------+-------- Points | >= 0 | > 0 | = 0 | = 0 | = 0 ---------+--------+--------+--------+--------+-------- Graph | >= 0 | > 0 | > 0 | = 0 | = 0 ---------+--------+--------+--------+--------+-------- Polygon | >= 0 | > 0 | > 0 | != 0 | = 0 ---------+--------+--------+--------+--------+-------- Mesh | >= 0 | > 0 | = 0 | = 0 | > 0
All other combinations are invalid, see ShapeType.
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.
The signed distance field of a shape is defined in its coordinate system. If a shape is rendered in a geocentric frame (for example by using a IMapShapes object), the inherent distortions of the coordinate system will become apparent in the shape distance field. For example, meridians rendered as thick lines via distance offsets will become thinner towards the poles in a geographic coordinate system. Here are some guidelines for choosing an appropriate coordinate system:
-
If a shape uses plain geometry only (see IsGeometry), the distortion of the distance field is irrelevant. The shape geometry will be subdivided (if necessary, according to the specified accuracy) when a coordinate system transformation is applied.
-
To minimize distortions in the distance field, an appropriate map projection should be used for the region of interest, for example CoordinateOperationMethod.ObliqueStereographic or CoordinateOperationMethod.TransverseMercator.
-
Cubemap shapes may be used to define shape features globally, but the inherent distance field distortions should be taken into account: circles defined via distance offsets may appear as ovals (because of the skewed coordinate axes) and the apparent thickness of lines defined via distance offsets may vary.
Public / Methods
ContourStart
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
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.
- See also
Computes the smallest distance from the given point to the shape, additionally returning the coordinates of the nearest shape feature.
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.
The nearest shape feature will be at a shape vertex (see VertexAt), a point on a shape edge (EdgeAt) or a point in a shape triangle ( TriangleAt, being represented by 1, 2 or 3 vertex indices.
For geometry shapes (see IsGeometry), the nearest shape feature and the given point will always have a distance that is equal to the absolute return value of this method. For other shape types, these values may be different.
- See also
EdgeAt
Returns a shape edge.
All points that lie on an edge have a shape distance of zero.
- See also
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.
ShapeAdd
Adds the given shape in as an aggregated shape to this shape.
Aggregating a shape may involve transformations. Use ShapePrepare method to perform this transformation up-front. This method will never perform any transformation on a prepared shape.
- See also
ShapePrepare
Performs all transformations on the given shape in that would be performed by ShapeAdd.
Preparing a shape that has been returned from ShapePrepare will be as no-op and will never involve any transformations.
- See also
ShapeRemove
2 overloads
Removes the given shape as an aggregated shape from this shape.
- See also
Removes the given shape as an aggregated shape from this shape.
- See also
ShapeVertex
Finds the aggregated shape vertex that corresponds to the given vertex in.
When a shape aggregates other shapes, it may expose vertices of aggregated shapes as its own vertices. In this case, the ShapeVertex method may be used to map such exposed shape vertices to their corresponding aggregated shape and/or vertex. Shapes may expose pseudo-vertices if aggregated shapes do not have any vertices, so it is valid if this method returns a value in the form (n,-1), where n is the index of an aggregated shape.
TriangleAt
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). If the Y-axis points upwards, the vertices are ordered in counter-clockwise winding. If it points downwards, the vertices are ordered in clockwise winding.
Public / Attributes
Bounds
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.
- See also
IsEmpty
Is this shape empty?
An empty shape does not have any own spatial features, i.e. Bounds will return Box2D.Inverse, CheckIntersection will always return -1 and DistanceTo1 will always return the maximum relevant distance. An empty shape may have aggregated shapes that are not empty.
IsGeometry
Is this a geometry shape?
A geometry shape has one the following types:
Geometry shapes can be rebuilt with Shape.Geometry by using the following shape builder methods:
Rebuilding a geometry shape will retain the same data as the IShapeOps.Compile method.
Extensions
Contains
2 overloads
Checks if this shape contains the given geographic coordinates.
Checks if this shape contains the given geographic coordinates.
Contours
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
Computes the vertices on the given polygon contour.
The first and the last vertex will be the same iff the polygon contour is closed.
DistanceTo
2 overloads
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.
- See also
Computes the smallest distance from the given point to the shape, additionally returning the coordinates of the nearest shape feature.
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.
The nearest shape feature will be at a shape vertex (see IShape.VertexAt), a point on a shape edge (IShape.EdgeAt) or a point in a shape triangle ( IShape.TriangleAt, being represented by 1, 2 or 3 vertex indices.
For geometry shapes (see IShape.IsGeometry), the nearest shape feature and the given point will always have a distance that is equal to the absolute return value of this method. For other shape types, these values may be different.
- See also
ImportCSH
Imports this shape into a CSH file (Compressed SHape).
The returned IOperation object will use the WriteCSH method to write the actual file contents.
RenderPrepare
Prepares this shape for geometric rendering (i.e. triangles, and lines).
The method will convert this shape to ShapeType.Graph (for the lines) and to ShapeType.Mesh (for the triangles). The resulting shapes are returned as a compiled shape group.
VisibleBounds
Computes the visible bounds of this shape, which may be used to render the shape.
If the shape is empty (see IShape.IsEmpty), the method returns a box between the points (0|0) and (1|1). If the shape is unbounded (see IShape.Bounds), the vertex bounds are used (see IShape.VertexBounds). If the shape contains only a single point or a horizontal / vertical line segment, the method returns a box with a minimum size of (1|1) that is centered around the point or line segment. point.
WriteCSH
Writes this shape to a CSH file (Compressed SHape).
- IOException
-
If an I/O error has occurred.
- See also