Polygon3D
Canonical path: NemAll_Python_Geometry.Polygon3D
Bases: PolyPoints3D
Representation of a plane polygon in a three dimensional space
To construct a valid 3D polygon from a bunch of points, the following rules must be fulfilled:
- First and last point must coincide. This class does not 'auto-close' polygons! A quadratic shape with '4' edges has to be defined by passing 5 points to a constructor. For such an object, the Count() method will return 5 accordingly.
- The orientation of the points must be monotonous. It can be either clockwise or counter-clockwise.
- All the points must be coplanar.
- The polygon must not self-intersect itself. You can create polygons that self-intersect or have alternating orientation, but in those cases some methods will raise errors or return wrong calculation results.
Each polygon consists of one or more components. A component is a closed loop, representing either a solid or a cut-out, depending on the orientation of the loop (if counter-clockwise is solid element, then clockwise is a cut-out). Each component must be closed (first and last point coincide).
Methods:
-
Clear
–Remove all points from vector.
-
Count
–Get count of points.
-
Empty
–Return true if no points, otherwise false.
-
EqualRef
–Test if reference points are equal.
-
GetEndPoint
–Get the end point in world coordinate system.
-
GetEndRelPoint
–Get the end point
-
GetLastPoint
–Get the last point in world coordinate system.
-
GetLines
–Get edge lines of polygon
-
GetPlane
–Calculate plane
-
GetPoint
–Get point in world coordinate system.
-
GetPointIndex
–Get index of the given point
-
GetPointIndexes
–Get indexes of the given point, in case that several points in the spline
-
GetRefPoint
–Get reference point.
-
GetRelPoint
–Get point in Local coordinate system.
-
GetStartPoint
–Get the start point in world coordinate system.
-
GetStartRelPoint
–Get the start point
-
GetVertices
–Get polygon vertices
-
Insert
–Overloaded function. See individual overloads.
-
InsertPolygon
–Insert a polygon into current one
-
InsertRel
–Insert relative point at specific position. Used local coordinates.
-
IsValid
–Check polygon validity
-
IsValidStatus
–Check polygon validity
-
Normalize
–Normalize a polygon.
-
NormalizeNoThrow
–Normalize Polygon3D.
-
Remove
–Remove point from specific position.
-
RemoveLastPoint
–Remove the last point
-
Reserve
–Reserve container capacity
-
Resize
–Specifies a new size for the points vector.
-
Reverse
–Reverse the point order in polygon, separately for every sub-polygon
-
SetEndPoint
–Set the end point in world coordinates
-
SetPoint
–Set point at given position in world coordinate system.
-
SetRefPoint
–Set reference point in world coordinate system.
-
SetRelPoint
–Set point at given position in relative coordinate system.
-
SetStartPoint
–Set the start point in world coordinates
-
ToLineChain
–Get polyline as a chain of lines composed from 2 points.
-
__eq__
–Equal operator
-
__getitem__
–Get point at position from index. Used world coordinates.
-
__iadd__
–Overloaded function. See individual overloads.
-
__init__
–Overloaded function. See individual overloads.
-
__mul__
–Matrix transformation
-
__ne__
–Not equal operator
-
__repr__
–Convert to string
-
__setitem__
–Set a value at position from index.
Attributes:
-
EndPoint
(Point3D
) –Get the end point in world coordinate system.
-
EndRelPoint
(Point3D
) –Get the end point
-
LastPoint
(Point3D
) –Get the last point in world coordinate system.
-
Lines
(list[Line3D]
) –Get edge lines of polygon
-
Points
(list[Point3D]
) –Get the points
-
RefPoint
(Point3D
) –Get reference point.
-
StartPoint
(Point3D
) –Get the start point in world coordinate system.
-
StartRelPoint
(Point3D
) –Get the start point
-
Vertices
(list[list[Point3D]]
) –Get polygon vertices
EqualRef
EqualRef(polyPoints: PolyPoints3D) -> bool
Test if reference points are equal.
Parameters:
-
polyPoints
(PolyPoints3D
) –the PolyPoints.
Returns:
-
bool
–Reference points are equal: true/false
GetEndPoint
GetEndPoint() -> Point3D
Get the end point in world coordinate system.
Returns:
-
Point3D
–end point in world coordinate system
GetLastPoint
GetLastPoint() -> Point3D
Get the last point in world coordinate system.
Returns:
-
Point3D
–last point in world coordinate system
GetLines
GetLines() -> Line3DList
Get edge lines of polygon
Returns:
-
Line3DList
–Edge lines of polygon
Examples:
square_3d
has a side length of 1.0 and is located in the XY plane. Get the sides like:
GetPlane
GetPlane() -> tuple[eGeometryErrorCode, Plane3D]
Calculate plane
Returns:
-
tuple[eGeometryErrorCode, Plane3D]
–Plane where polygon is
Examples:
square_3d
has a side length of 1.0 and is located in the XY plane. Get the plane like:
GetPoint
GetPoint(index: int) -> Point3D
Get point in world coordinate system.
This method is checked and throwing Geometry::Exception when index is out of range.
Parameters:
-
index
(int
) –point index.
Returns:
-
Point3D
–point point in world coordinate system.
GetPointIndex
GetPointIndexes
GetRefPoint
GetRefPoint() -> Point3D
GetRelPoint
GetRelPoint(index: int) -> Point3D
Get point in Local coordinate system.
This method is checked and throwing Geometry::Exception when index is out of range.
Parameters:
-
index
(int
) –point index.
Returns:
-
Point3D
–point the point at position index.
GetStartPoint
GetStartPoint() -> Point3D
Get the start point in world coordinate system.
Returns:
-
Point3D
–start point in world coordinate system
Insert
overloaded
Insert(polyPoints: PolyPoints3D, position: int = 18446744073709551615) -> bool
Insert vector of points at specific position.
If return false then points weren't inserted.
Parameters:
-
polyPoints
(PolyPoints3D
) –the PolyPoints.
-
position
(int
, default:18446744073709551615
) –position where points will be inserted.
Returns:
-
bool
–bool true if successful.
Insert(point: Point3D, position: int = 18446744073709551615) -> bool
Insert point at specific position. Used world coordinates.
If return false then points weren't Inserted.
Parameters:
-
point
(Point3D
) –the Point.
-
position
(int
, default:18446744073709551615
) –position where points will be inserted.
Returns:
-
bool
–bool true if successful.
InsertPolygon
InsertPolygon(polygon: Polygon3D, position: int = -1) -> bool
Insert a polygon into current one
Parameters:
-
polygon
(Polygon3D
) –Polygon which will be inserted
-
position
(int
, default:-1
) –Position where the polygon will be inserted
Returns:
-
bool
–true if insert was successful
InsertRel
InsertRel(point: Point3D, position: int = 18446744073709551615) -> bool
Insert relative point at specific position. Used local coordinates.
If return false then points weren't Inserted.
Parameters:
-
point
(Point3D
) –the Point.
-
position
(int
, default:18446744073709551615
) –position where points will be inserted.
Returns:
-
bool
–bool true if successful.
IsValidStatus
IsValidStatus() -> tuple[bool, eValidationStatusPolygon3D]
Check polygon validity
Returns:
-
tuple[bool, eValidationStatusPolygon3D]
–tuple(true = valid, false = not valid, If polygon is invalid, here is the reason)
Examples:
Polygon with colinear points
>>> colinear_polygon = Polygon3D([Point3D(0,0,0),
... Point3D(1,0,0),
... Point3D(2,0,0),
... Point3D(0,0,0)])
>>> colinear_polygon.IsValidStatus()
(False, NemAll_Python_Geometry.eValidationStatusPolygon3D.VS_COLINEAR)
Polygon with non-planar points
>>> non_planar_polygon = Polygon3D([Point3D(0,0,0),
... Point3D(1,0,0),
... Point3D(1,1,1),
... Point3D(0,1,0),
... Point3D(0,0,0)])
>>> non_planar_polygon.IsValidStatus()
(False, NemAll_Python_Geometry.eValidationStatusPolygon3D.VS_NOT_COPLANAR)
Valid polygon
Normalize
Normalize(
normalizeType: ePolygonNormalizeType = DEFAULT_NORM_TYPE,
extra_smooth: bool = False,
)
Normalize a polygon.
Normalization involves moving the vertices of a non-planar polygon to make it planar, uniting duplicated points or resolving crossed loops.
Parameters:
-
normalizeType
(ePolygonNormalizeType
, default:DEFAULT_NORM_TYPE
) –Normalization type
-
extra_smooth
(bool
, default:False
) –Increase level of details
Examples:
Normalize non-planar polygon
>>> non_planar_polygon = Polygon3D([Point3D(0,0,0),
... Point3D(1,0,0),
... Point3D(1,1,1),
... Point3D(0,1,0),
... Point3D(0,0,0)])
>>> non_planar_polygon.Normalize()
>>> non_planar_polygon.GetPlane()
(NemAll_Python_Geometry.eGeometryErrorCode.eOK, Plane3D(
Point(0.4, 0.4, 0.2)
Normal(0, 0.70710678118654746, -0.70710678118654746)))
Resolve crossed-loop polygon
NormalizeNoThrow
NormalizeNoThrow(
normalizeType: ePolygonNormalizeType = DEFAULT_NORM_TYPE,
extra_smooth: bool = False,
) -> eGeometryErrorCode
Normalize Polygon3D.
Same as Normalize, but method doesn't throw exception, just return error code
Parameters:
-
normalizeType
(ePolygonNormalizeType
, default:DEFAULT_NORM_TYPE
) –type of Polygon2D normalization
-
extra_smooth
(bool
, default:False
) –Including extra smooth: true/false
Returns:
-
eGeometryErrorCode
–Error code (eOK, eAllocError, eStructuralError, eWrongShape)
Remove
Remove point from specific position.
If return false then points weren't removed.
Parameters:
-
position
(int
) –position of point which will be removed.
Returns:
-
bool
–Point removed: true/false
RemoveLastPoint
Remove the last point
Returns:
-
bool
–Point removed: true/false
Reserve
Reserve container capacity
Parameters:
-
newCount
(int
) –Expected size of container [count of points]
Resize
Specifies a new size for the points vector.
Parameters:
-
newSize
(int
) –The new size of the points vector.
SetEndPoint
SetEndPoint(endpoint: Point3D)
SetPoint
SetPoint(point: Point3D, index: int)
Set point at given position in world coordinate system.
Parameters:
-
point
(Point3D
) –point in the world coordinate system.
-
index
(int
) –index of point which will be set
SetRefPoint
SetRefPoint(refPoint: Point3D)
Set reference point in world coordinate system.
Parameters:
-
refPoint
(Point3D
) –reference point in the world coordinate system.
SetRelPoint
SetRelPoint(point: Point3D, index: int)
Set point at given position in relative coordinate system.
Parameters:
-
point
(Point3D
) –point in the relative coordinate system.
-
index
(int
) –index of point which will be set
SetStartPoint
SetStartPoint(startpoint: Point3D)
ToLineChain
ToLineChain() -> Point3DList
Get polyline as a chain of lines composed from 2 points.
Returns:
-
Point3DList
–vector of lines composed from 2 points (start and end point of a line)
__eq__
__eq__(polygon2: Polygon3D) -> bool
Equal operator
Parameters:
-
polygon2
(Polygon3D
) –Second polygon
Returns:
-
bool
–Polyline3D are equal
__getitem__
__getitem__(index: int) -> Point3D
Get point at position from index. Used world coordinates.
This method is checked and throwing Geometry::Exception when index is out of range.
Parameters:
-
index
(int
) –point index.
Returns:
-
Point3D
–copy of point.
__iadd__
overloaded
Addition assignment operator
Parameters:
-
polygon
(Polygon3D
) –Polygon which will be copied
Returns:
-
Polygon3D
–Reference to polygon
Examples:
Add two triangles
>>> first_triangle = Polygon3D([Point3D(0,0,0),
... Point3D(1,0,0),
... Point3D(1,1,0),
... Point3D(0,0,0)])
>>> second_triangle = Polygon3D([Point3D(0,0,0),
... Point3D(1,1,0),
... Point3D(0,1,0),
... Point3D(0,0,0)])
>>> first_triangle += second_triangle
>>> first_triangle.Normalize()
Result is a square
__mul__
Matrix transformation
Parameters:
-
matrix
(Matrix3D
) –Transformation matrix
Returns:
-
Polygon3D
–Reference to polygon
Examples:
When rotation_2
is a Matrix3D that rotates around X axis by 90°, and square_3d
has a side length of 1 and is located in XY plane, the rotation can be applied to the square like: