Plane3d Class

Plane3d is the abstract base class for multiple 3d plane representations:

• Plane3dByOriginAndUnitNormal -- plane defined by origin and normal, with no preferred in-plane directions
• Plane3dByOriginAndVectors -- plane defined by origin and 2 vectors in the plane, with normal implied by the vectors' cross product
• Point4d -- homogeneous form of xyzw plane.
• ClipPlane -- implicit plane with additional markup as used by compound clip structures such as ConvexClipPlaneSet and UnionOfConvexClipPlaneSets

As an abstract base class, Plane3d demands that its derived classes implement queries to answer questions about the plane's normal and the altitude of points above or below the plane. (Altitude is measured perpendicular to the plane.) These abstract methods are:

• altitude(Point3d), altitudeXYZ(x,y,z), and altitudeXYZW(Point4d) -- evaluate altitude
• normalX(), normalY(), normalZ() -- return components of the plane's normal vector.
• velocity(Vector3d), velocityXYZ(x,y,z) -- return dot product of the input vector with the plane normal.
• projectPointToPlane (spacePoint: Point3d) -- return projection of spacePoint into the plane.

The Plane3d base class also provides implementations of several queries which it can implement by calling the abstract queries.

• Derived classes may choose to override these default implementations using private knowledge of what they have stored.
• isPointInPlane(spacePoint, tolerance?) -- test if spacePoint is in the plane with tolerance. Default tolerance is small metric distance
• classifyAltitude (spacePoint, tolerance?), classifyAltitudeXYZ (x,y,z,tolerance?) -- return -1,0,1 indicating if spacePoint's altitude is negative, near zero, or positive.

Notes about scaling and signs in methods that compute altitudes, normal components and velocities:

• The term "altitude" indicates a signed distance from the plane.
  • altitude zero is on the plane
  • positive altitudes are on one side
  • negatives are on the other.
• Altitude values and normal components are not strictly required to be true cartesian distance. If the calling code happens to use "distance scaled by 1000X" it understands that it can be OK for its plane implementation to have that scaling.
• By convention, derived classes whose definitions (normals and vectors in plane) are simple cartesian are expected to return true distances. This applies to:
  • Plane3dByOriginAndUnitNormal and ClipPlane
    • These maintain a stored unit normal so the altitude calculations are inherently true cartesian distance.
  • Plane3dByOriginAndVectors -- this is a bit expensive because
    • the normal is the cross product of the defining vectors.
    • that cross product is not typically unit
    • normalization adds to the cost of computing off-plane distances
    • Since a main purpose of using this class is often to navigate a skewed, non-unit grid, occasional off-plane queries are not likely to be important.
• "4 dimensional" (homogeneous coordinate planes) (Point4d and PlaneByOriginAndVectors4d)
  • typically do not force their coefficients to any distance-based normalization
  • are typically used for calculations in spaces with skewing effects do to perspective, and true distances are not required.
• In all classes, the weightedAltitude method is free to be scaled distance.

Extended by

• ClipPlane
• Plane3dByOriginAndUnitNormal
• Plane3dByOriginAndVectors
• Point4d

Implements

• PlaneAltitudeEvaluator

Methods

Name	Description
constructor(): Plane3d
altitude(spacePoint: Point3d): number Abstract	Return the altitude of spacePoint above or below the plane.
altitudeXYZ(x: number, y: number, z: number): number Abstract	Return the altitude of a point given as separate x,y,z components.
classifyAltitude(point: Point3d, tolerance: numberGeometry.smallMetricDistance): "0" | "1" | "-1"	Return a value -1, 0, 1 giving a signed indicator of whether the toleranced altitude of the point is
classifyAltitudeXYZ(x: number, y: number, z: number, tolerance: numberGeometry.smallMetricDistance): "0" | "1" | "-1"	Return a value -1, 0, 1 giving a signed indicator of whether the toleranced altitude of x,y,z is
getAnyPointOnPlane(result?: Point3d): Point3d	Return any point on the plane.
getUnitNormal(result?: Vector3d): undefined | Vector3d	Return the unit normal for the plane.
isPointInPlane(spacePoint: Point3d, tolerance: numberGeometry.smallMetricDistance): boolean	Returns true if spacePoint is within distance tolerance of the plane.
normalX(): number Abstract	Return the x component of the normal used to evaluate altitude.
normalY(): number Abstract	Return the y component of the normal used to evaluate altitude.
normalZ(): number Abstract	Return the z component of the normal used to evaluate altitude.
projectPointToPlane(spacePoint: Point3d, result?: Point3d): Point3d Abstract	Return the projection of spacePoint onto the plane.
velocity(spaceVector: Vector3d): number Abstract	Return the dot product of spaceVector with the plane's unit normal.
velocityXYZ(x: number, y: number, z: number): number Abstract	Return the dot product of spaceVector (x,y,z) with the plane's unit normal.
weightedAltitude(spacePoint: Point4d): number Abstract	Return the altitude of weighted spacePoint above or below the plane.

Defined in

• geometry3d/Plane3d.ts Line 56