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

EndPoint property writable

EndPoint: Point3D

Get the end point in world coordinate system.

EndRelPoint property

EndRelPoint: Point3D

Get the end point

LastPoint property

LastPoint: Point3D

Get the last point in world coordinate system.

Lines property

Lines: list[Line3D]

Get edge lines of polygon

Points property writable

Points: list[Point3D]

Get the points

RefPoint property writable

RefPoint: Point3D

Get reference point.

StartPoint property writable

StartPoint: Point3D

Get the start point in world coordinate system.

StartRelPoint property

StartRelPoint: Point3D

Get the start point

Vertices property

Vertices: list[list[Point3D]]

Get polygon vertices

Clear

Clear()

Remove all points from vector.

Count

Count() -> int

Get count of points.

Returns:

• int –

  bool.

Empty

Empty() -> bool

Return true if no points, otherwise false.

Returns:

• bool –

  bool.

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

GetEndRelPoint

GetEndRelPoint() -> Point3D

Get the end point

Returns:

• Point3D –

  end point

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:

>>> square_3d.GetLines()
Line3D(0, 0, 0, 1, 0, 0)
Line3D(1, 0, 0, 1, 1, 0)
Line3D(1, 1, 0, 0, 1, 0)
Line3D(0, 1, 0, 0, 0, 0)

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:

>>> result, plane = square_3d.GetPlane()
>>> result
NemAll_Python_Geometry.eGeometryErrorCode.eOK
>>> plane.Point
Point3D(0.4, 0.4, 0)
>>> plane.Vector
Vector3D(0, 0, -1)

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

GetPointIndex(point: Point3D) -> tuple[bool, int]

Get index of the given point

Parameters:

• point (Point3D) –

  Searched point

Returns:

• tuple[bool, int] –

  tuple(True if a point was found, Found index)

GetPointIndexes

GetPointIndexes(point: Point3D) -> tuple[bool, list[int]]

Get indexes of the given point, in case that several points in the spline will have the same coordinates

Parameters:

• point (Point3D) –

  Searched point

Returns:

• tuple[bool, list[int]] –

  tuple(True if at least one point was found, Found indexes)

GetRefPoint

GetRefPoint() -> Point3D

Get reference point.

Returns:

• Point3D –

  the reference point in the world coordinate system.

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

GetStartRelPoint

GetStartRelPoint() -> Point3D

Get the start point

Returns:

• Point3D –

  start point

GetVertices

GetVertices() -> object

Get polygon vertices

Returns:

• object –

  polygon vertices

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.

IsValid

IsValid() -> bool

Check polygon validity

Returns:

• bool –

  true = valid, false = not valid

IsValidStatus

IsValidStatus() -> tuple[bool, eValidationStatus]

Check polygon validity

Returns:

• tuple[bool, eValidationStatus] –

  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

>>> valid_polygon = Polygon3D([Point3D(0,0,0),
...                            Point3D(1,0,0),
...                            Point3D(1,1,0),
...                            Point3D(0,1,0),
...                            Point3D(0,0,0)])
>>> valid_polygon.IsValidStatus()
(True, NemAll_Python_Geometry.eValidationStatusPolygon3D.VS_NOT_COPLANAR)

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()
>>> _, plane = non_planar_polygon.GetPlane()
>>> plane.Point
Point3D(0.4, 0.4, 0.2)
>>> plane.Vector
Vector3D(0, 0.707, -0.707)

Resolve crossed-loop polygon

>>> crossed_loop_polygon = Polygon3D([Point3D(0,0,0),
...                                   Point3D(1,0,0),
...                                   Point3D(0,1,0),
...                                   Point3D(1,1,0),
...                                   Point3D(0,0,0)])
>>> crossed_loop_polygon.Normalize()
>>> crossed_loop_polygon
Polygon3D(
   Count(4)
   Points(
      (0.5, 0.5, 0)
      (0, 1, 0)
      (1, 1, 0)
      (0.5, 0.5, 0)))

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(position: int) -> bool

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

RemoveLastPoint() -> bool

Remove the last point

Returns:

• bool –

  Point removed: true/false

Reserve

Reserve(newCount: int)

Reserve container capacity

Parameters:

• newCount (int) –

  Expected size of container [count of points]

Resize

Resize(newSize: int)

Specifies a new size for the points vector.

Parameters:

• newSize (int) –

  The new size of the points vector.

Reverse

Reverse()

Reverse the point order in polygon, separately for every sub-polygon

SetEndPoint

SetEndPoint(endpoint: Point3D)

Set the end point in world coordinates

Parameters:

• endpoint (Point3D) –

  new end point

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)

Set the start point in world coordinates

Parameters:

• startpoint (Point3D) –

  new start point

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

__iadd__(polygon: Polygon3D) -> Polygon3D

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

>>> first_triangle
Polygon3D(
   Count(5)
   Points(
      (0, 0, 0)
      (1, 0, 0)
      (1, 1, 0)
      (0, 1, 0)
      (0, 0, 0)))

__iadd__(point: Point3D) -> Polygon3D

Addition assignment operator

Parameters:

• point (Point3D) –

  New Point3D which will be added to the polygon

Returns:

• Polygon3D –

  Reference to polygon

Examples:

Initialize an empty polygon

>>> square = Polygon3D()
>>> square.IsValid()
False

Add points with in-place addition operator to get a valid polygon representing a square

>>> square += Point3D(0,0,0)
>>> square += Point3D(1,0,0)
>>> square += Point3D(1,1,0)
>>> square += Point3D(0,1,0)
>>> square += Point3D(0,0,0)
>>> square.IsValid()
True

__init__ overloaded

__init__()

Initialize

__init__(pntList: list[Point3D])

Constructor with an initializer list

Parameters:

• pntList (list[Point3D]) –

  Point list

__init__(polygon: Polygon3D)

Copy constructor.

Parameters:

• polygon (Polygon3D) –

  Polygon which will be copied

__mul__

__mul__(matrix: Matrix3D) -> Polygon3D

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:

>>> square_3d * rotation_2
Polygon3D(
   Count(5)
   Points(
      (0, 0, 0)
      (1, 0, 0)
      (1, 0, 1)
      (0, 0, 1)
      (0, 0, 0)))

__ne__

__ne__(polygon2: Polygon3D) -> bool

Not equal operator

Parameters:

• polygon2 (Polygon3D) –

  Second polygon

Returns:

• bool –

  Polyline3D are equal

__repr__

__repr__() -> str

Convert to string

__setitem__

__setitem__(index: int | slice, value: Point3D | list[Point3D])

Set a value at position from index.

Parameters:

• index (int | slice) –

  index of the value.

• value (Point3D | list[Point3D]) –

  value to insert.

Placeholder