+# coding=utf-8
+"""Module for boolean operations on 2D polygons (union, intersection, difference, xor).
+
+The functions here are derived from the pypolybool python library available at
+https://github.com/KaivnD/pypolybool
+
+The pypolybool library is, itself, a pure Python port of the polybooljs JavaScript
+library maintained by Sean Mconnelly available at https://github.com/velipso/polybooljs
+
+Full documentation of the method is available at
+https://sean.cm/a/polygon-clipping-pt2
+
+Based somewhat on the F. Martinez (2013) algorithm.
+
+Francisco Martínez, Carlos Ogayar, Juan R. Jiménez, Antonio J. Rueda (2013),
+"A simple algorithm for Boolean operations on polygons",
+Advances in Engineering Software, Volume 64, Pages 11-19, ISSN 0965-9978,
+https://doi.org/10.1016/j.advengsoft.2013.04.004.
+"""
+from__future__importdivision
+
+
+"""____________OBJECTS FOR INPUT/OUTPUT FROM BOOLEAN OPERATIONS____________"""
+
+
+
+[docs]
+classBooleanPoint:
+"""2D Point class used in polygon boolean operations.
+
+ Args:
+ x: Float for X coordinate.
+ y: Float for Y coordinate
+ """
+
+ def__init__(self,x,y):
+ self.x=x
+ self.y=y
+
+
+[docs]
+ defis_equivalent(self,other_pt,tol):
+"""Check if this point is equivalent ot another within tolerance."""
+ ifnotisinstance(other_pt,BooleanPoint):
+ returnFalse
+ returnabs(self.x-other_pt.x)<tolandabs(self.y-other_pt.y)<tol
+
+
+
+[docs]
+ @staticmethod
+ defcollinear(pt1,pt2,pt3,tolerance):
+"""Get a boolean for whether 3 points are colinear."""
+ dx1=pt1.x-pt2.x
+ dy1=pt1.y-pt2.y
+ dx2=pt2.x-pt3.x
+ dy2=pt2.y-pt3.y
+ returnabs(dx1*dy2-dx2*dy1)<tolerance
+
+
+
+[docs]
+ @staticmethod
+ defcompare(pt1,pt2,tolerance):
+"""Get an integer for the relationship between two points.
+
+ Zero indicates equal. Positive 1 is to the right. Negative 1 is to the left.
+ """
+ ifabs(pt1.x-pt2.x)<tolerance:
+ return0ifabs(pt1.y-pt2.y)<toleranceelse-1ifpt1.y<pt2.yelse1
+ return-1ifpt1.x<pt2.xelse1
+
+
+
+[docs]
+ @staticmethod
+ defpoint_above_or_on_line(point,left,right,tolerance):
+"""Get a boolean for whether a point is above or on a line.
+
+ Args:
+ point: BooleanPoint to be evaluated.
+ left: BooleanPoint for the left of the line segment.
+ right: BooleanPoint for the right of the line segment
+ """
+ return(right.x-left.x)*(point.y-left.y)-(right.y-left.y)*(
+ point.x-left.x
+ )>=-tolerance
+
+
+
+[docs]
+ @staticmethod
+ defbetween(point,left,right,tolerance):
+"""Get a boolean for whether a point is between two points.
+
+ Args:
+ point: BooleanPoint to be evaluated.
+ left: BooleanPoint for the left.
+ right: BooleanPoint for the right.
+ """
+ dPyLy=point.y-left.y
+ dRxLx=right.x-left.x
+ dPxLx=point.x-left.x
+ dRyLy=right.y-left.y
+
+ dot=dPxLx*dRxLx+dPyLy*dRyLy
+ ifdot<tolerance:
+ returnFalse
+
+ sqlen=dRxLx*dRxLx+dRyLy*dRyLy
+ ifdot-sqlen>-tolerance:
+ returnFalse
+
+ returnTrue
+
+
+ @staticmethod
+ def_lines_intersect(a0,a1,b0,b1,tolerance):
+"""Get an _IntersectionPoint object for the intersection of two line segments.
+
+ Args:
+ a0: BooleanPoint for the first point of the first line segment.
+ a1: BooleanPoint for the second point of the first line segment.
+ b0: BooleanPoint for the first point of the second line segment.
+ b1: BooleanPoint for the second point of the second line segment.
+ """
+ adx=a1.x-a0.x
+ ady=a1.y-a0.y
+ bdx=b1.x-b0.x
+ bdy=b1.y-b0.y
+
+ axb=adx*bdy-ady*bdx
+
+ ifabs(axb)<tolerance:
+ returnNone
+
+ dx=a0.x-b0.x
+ dy=a0.y-b0.y
+
+ a=(bdx*dy-bdy*dx)/axb
+ b=(adx*dy-ady*dx)/axb
+
+ return_IntersectionPoint(
+ BooleanPoint.__calc_along_using_value(a,tolerance),
+ BooleanPoint.__calc_along_using_value(b,tolerance),
+ BooleanPoint(a0.x+a*adx,a0.y+a*ady),
+ )
+
+ @staticmethod
+ def__calc_along_using_value(value,tolerance):
+ ifvalue<=-tolerance:
+ return-2
+ elifvalue<tolerance:
+ return-1
+ elifvalue-1<=-tolerance:
+ return0
+ elifvalue-1<tolerance:
+ return1
+ else:
+ return2
+
+ def__repr__(self):
+ return"{},{}".format(self.x,self.y)
+
+ def__str__(self):
+ return"{},{}".format(self.x,self.y)
+
+
+
+
+[docs]
+classBooleanPolygon:
+"""Polygon class used in polygon boolean operations.
+
+ Args:
+ regions: A list of lists of BooleanPoints representing the 2D points defining
+ the regions of the Polygon. The first sub-list is typically the
+ boundary of the polygon and each successive list represents a hole
+ within the boundary. It is also permissable for the holes
+ to lie outside the first polygon, in which case the shape is
+ interpreted as a MultiPolygon. As an alternative to BooleanPoints,
+ tuples of two float values are also permissable in which case the
+ values represent the X and Y coordinates of each vertex.
+ is_inverted: A boolean for whether the Polygon is inverted or not. For
+ polygons input to the boolean methods, this value should always be
+ False. (Default: False)
+ """
+
+ def__init__(self,regions,is_inverted=False):
+ _regions=[]
+ forregioninregions:
+ tmp=[]
+ forptinregion:
+ ifisinstance(pt,BooleanPoint):
+ tmp.append(pt)
+ elifisinstance(pt,tuple):
+ x,y=pt
+ tmp.append(BooleanPoint(x,y))
+ _regions.append(tmp)
+
+ self.regions=_regions
+ self.is_inverted=is_inverted
+[docs]
+defunion_all(polygons,tolerance):
+"""Get a BooleanPolygon for the union of multiple polygons.
+
+ Using this method is more computationally efficient than calling the union()
+ method multiple times as this method will only compute the intersection of
+ the segments once.
+
+ Args:
+ polygons: An array of BooleanPolygons for which the union will be computed.
+ tolerance: The minimum distance between points before they are
+ considered distinct from one another.
+
+ Returns:
+ A BooleanPolygon for the union across all of the input polygons.
+ """
+ seg1=_segments(polygons[0],tolerance)
+ foriinrange(1,len(polygons)):
+ seg2=_segments(polygons[i],tolerance)
+ comb=_combine(seg1,seg2,tolerance)
+ seg1=_select_union(comb)
+ return_polygon(seg1,tolerance)
+
+
+
+
+[docs]
+defintersect_all(polygons,tolerance):
+"""Get a BooleanPolygon for the intersection of multiple polygons.
+
+ Using this method is more computationally efficient than calling the intersect()
+ method multiple times as this method will only compute the intersection of
+ the segments once.
+
+ Args:
+ polygons: An array of BooleanPolygons for which the intersection will
+ be computed.
+ tolerance: The minimum distance between points before they are
+ considered distinct from one another.
+
+ Returns:
+ A BooleanPolygon for the intersection across all of the input polygons.
+ """
+ seg1=_segments(polygons[0],tolerance)
+ foriinrange(1,len(polygons)):
+ seg2=_segments(polygons[i],tolerance)
+ comb=_combine(seg1,seg2,tolerance)
+ seg1=_select_intersect(comb)
+ return_polygon(seg1,tolerance)
+
+
+
+
+[docs]
+defsplit(poly1,poly2,tolerance):
+"""Split two BooleanPolygons with one another to get the intersection and difference.
+
+ Using this method is more computationally efficient than calling the intersect()
+ and difference() methods individually as this method will only compute the
+ intersection of the segments once.
+
+ Args:
+ poly1: A BooleanPolygon for the first polygon that will be split with
+ the second polygon.
+ poly2: A BooleanPolygon for the second polygon that will be split with
+ the first polygon.
+ tolerance: The minimum distance between points before they are
+ considered distinct from one another.
+
+ Returns:
+ A tuple with three elements
+
+ - intersection: A BooleanPolygon for the intersection of the two
+ input polygons.
+
+ - poly1_difference: A BooleanPolygon for the portion of poly1 that does
+ not overlap with poly2. When combined with the intersection, this
+ makes a split version of poly1.
+
+ - poly2_difference: A BooleanPolygon for the portion of poly2 that does
+ not overlap with poly1. When combined with the intersection, this
+ makes a split version of poly2.
+ """
+ first_regions=_segments(poly1,tolerance)
+ second_regions=_segments(poly2,tolerance)
+ comb=_combine(first_regions,second_regions,tolerance)
+ intersection=_polygon(_select_intersect(comb),tolerance)
+ poly1_difference=_polygon(_select_difference(comb),tolerance)
+ poly2_difference=_polygon(_select_difference_rev(comb),tolerance)
+ returnintersection,poly1_difference,poly2_difference
+
+
+
+
+[docs]
+defunion(poly1,poly2,tolerance):
+"""Get a BooleanPolygon for the union of two polygons.
+
+ Note that the result will not differentiate hole polygons from boundary polygons.
+
+ Args:
+ poly1: A BooleanPolygon for the first polygon for which the union will
+ be computed.
+ poly2: A BooleanPolygon for the second polygon for which the union will
+ be computed.
+ tolerance: The minimum distance between points before they are
+ considered distinct from one another.
+
+ Returns:
+ A BooleanPolygon for the union of the two polygons.
+ """
+ return__operate(poly1,poly2,_select_union,tolerance)
+
+
+
+
+[docs]
+defintersect(poly1,poly2,tolerance):
+"""Get a BooleanPolygon for the intersection of two polygons.
+
+ Args:
+ poly1: A BooleanPolygon for the first polygon for which the intersection
+ will be computed.
+ poly2: A BooleanPolygon for the second polygon for which the intersection
+ will be computed.
+ tolerance: The minimum distance between points before they are
+ considered distinct from one another.
+
+ Returns:
+ A BooleanPolygon for the intersection of the two polygons.
+ """
+ return__operate(poly1,poly2,_select_intersect,tolerance)
+
+
+
+
+[docs]
+defdifference(poly1,poly2,tolerance):
+"""Get a BooleanPolygon for the subtraction of poly2 from poly1.
+
+ Args:
+ poly1: A BooleanPolygon for the the polygon that will be subtracted from.
+ poly2: A BooleanPolygon for the polygon to subtract with.
+ tolerance: The minimum distance between points before they are
+ considered distinct from one another.
+
+ Returns:
+ A BooleanPolygon for the difference of poly1 - poly2.
+ """
+ return__operate(poly1,poly2,_select_difference,tolerance)
+
+
+
+
+[docs]
+defdifference_reversed(poly1,poly2,tolerance):
+"""Get a BooleanPolygon for the subtraction of poly1 from poly2.
+
+ Args:
+ poly1: A BooleanPolygon for the polygon to subtract with.
+ poly2: A BooleanPolygon for the the polygon that will be subtracted from.
+ tolerance: The minimum distance between points before they are
+ considered distinct from one another.
+
+ Returns:
+ A BooleanPolygon for the difference of poly2 - poly1.
+ """
+ return__operate(poly1,poly2,_select_difference_rev,tolerance)
+
+
+
+
+[docs]
+defxor(poly1,poly2,tolerance):
+"""Get a BooleanPolygon for the exclusive disjunction of two Polygons.
+
+ Note that this method is prone to merging holes that may exist in the
+ result into the boundary to create a single list of joined vertices,
+ which may not always be desirable. In this case, it may be desirable
+ to do two separate difference calculations instead or use the split method.
+
+ Also note that, when the result includes separate polygons for holes,
+ it will not differentiate hole polygons from boundary polygons.
+
+ Args:
+ poly1: A BooleanPolygon for the first polygon for which the exclusive
+ disjunction will be computed.
+ poly2: A BooleanPolygon for the second polygon for which the exclusive
+ disjunction will be computed.
+ tolerance: The minimum distance between points before they are
+ considered distinct from one another.
+
+ Returns:
+ A BooleanPolygon for the exclusive disjunction of the two polygons.
+ """
+ return__operate(poly1,poly2,_select_xor,tolerance)
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/_modules/ladybug_geometry/bounding.html b/docs/_modules/ladybug_geometry/bounding.html
new file mode 100644
index 00000000..7b2a8f44
--- /dev/null
+++ b/docs/_modules/ladybug_geometry/bounding.html
@@ -0,0 +1,1384 @@
+
+
+
+
+
+
+ ladybug_geometry.bounding — ladybug geometry documentation
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+# coding=utf-8
+"""Utility functions for computing bounding boxes and extents around geometry."""
+from__future__importdivision
+
+fromladybug_geometry.geometry2d.pointvectorimportPoint2D
+fromladybug_geometry.geometry3d.pointvectorimportPoint3D
+
+
+
+[docs]
+defbounding_domain_x(geometries):
+"""Get minimum and maximum X coordinates of multiple geometries.
+
+ Args:
+ geometries: An array of any ladybug_geometry objects for which the extents
+ of the X domain will be computed. Note that all objects must have
+ a min and max property.
+
+ Returns:
+ A tuple with the min and the max X coordinates around the geometry.
+ """
+ min_x,max_x=geometries[0].min.x,geometries[0].max.x
+ forgeomingeometries[1:]:
+ ifgeom.min.x<min_x:
+ min_x=geom.min.x
+ ifgeom.max.x>max_x:
+ max_x=geom.max.x
+ returnmin_x,max_x
+
+
+
+
+[docs]
+defbounding_domain_y(geometries):
+"""Get minimum and maximum Y coordinates of multiple geometries.
+
+ Args:
+ geometries: An array of any ladybug_geometry objects for which the extents
+ of the Y domain will be computed. Note that all objects must have
+ a min and max property.
+
+ Returns:
+ A tuple with the min and the max Y coordinates around the geometry.
+ """
+ min_y,max_y=geometries[0].min.y,geometries[0].max.y
+ forgeomingeometries[1:]:
+ ifgeom.min.y<min_y:
+ min_y=geom.min.y
+ ifgeom.max.y>max_y:
+ max_y=geom.max.y
+ returnmin_y,max_y
+
+
+
+
+[docs]
+defbounding_domain_z(geometries):
+"""Get minimum and maximum Z coordinates of multiple geometries.
+
+ Args:
+ geometries: An array of any 3D ladybug_geometry objects for which the extents
+ of the Z domain will be computed. Note that all objects must have
+ a min and max property and they cannot be 2D objects.
+
+ Returns:
+ A tuple with the min and the max Z coordinates around the geometry.
+ """
+ min_z,max_z=geometries[0].min.z,geometries[0].max.z
+ forgeomingeometries:
+ ifgeom.max.z>max_z:
+ max_z=geom.max.z
+ ifgeom.min.z<min_z:
+ min_z=geom.min.z
+ returnmin_z,max_z
+
+
+
+
+[docs]
+defbounding_domain_z_2d_safe(geometries):
+"""Get minimum and maximum Z coordinates in a manner that is safe for 2D geometries.
+
+ Args:
+ geometries: An array of any ladybug_geometry objects for which the extents
+ of the Z domain will be computed. Any 2D objects within this list will
+ be assumed to have a Z-value of zero.
+
+ Returns:
+ A tuple with the min and the max Z coordinates around the geometry.
+ """
+ try:
+ min_z,max_z=geometries[0].min.z,geometries[0].max.z
+ exceptAttributeError:
+ min_z,max_z=0,0
+ forgeomingeometries:
+ try:
+ ifgeom.max.z>max_z:
+ max_z=geom.max.z
+ ifgeom.min.z<min_z:
+ min_z=geom.min.z
+ exceptAttributeError:
+ if0>max_z:
+ max_z=0
+ if0<min_z:
+ min_z=0
+ returnmin_z,max_z
+
+
+
+def_orient_geometry(geometries,axis_angle,center):
+"""Orient both 2D and 3D geometry to a given axis angle and center point.
+
+ This is used by the methods that compute bounding rectangles.
+ """
+ new_geometries=[]
+ forgeomingeometries:
+ try:# assume that it is a 2D geometry object
+ new_geometries.append(geom.rotate(-axis_angle,center))
+ exceptTypeError:# it's a 3D geometry object
+ new_geometries.append(geom.rotate_xy(-axis_angle,center))
+ returnnew_geometries
+
+
+
+[docs]
+defbounding_rectangle(geometries,axis_angle=0):
+"""Get the min and max of an oriented bounding rectangle around 2D or 3D geometry.
+
+ Args:
+ geometries: An array of 2D or 3D geometry objects. Note that all objects
+ must have a min and max property.
+ axis_angle: The counter-clockwise rotation angle in radians in the XY plane
+ to represent the orientation of the bounding rectangle extents. (Default: 0).
+
+ Returns:
+ A tuple with two Point2D objects representing the min point and max point
+ of the bounding rectangle respectively.
+ """
+ ifaxis_angle!=0:# rotate geometry to the bounding box
+ cpt=geometries[0].vertices[0]
+ geometries=_orient_geometry(geometries,axis_angle,cpt)
+ xx=bounding_domain_x(geometries)
+ yy=bounding_domain_y(geometries)
+ min_pt=Point2D(xx[0],yy[0])
+ max_pt=Point2D(xx[1],yy[1])
+ ifaxis_angle!=0:# rotate the points back
+ cpt=Point2D(cpt.x,cpt.y)# cast Point3D to Point2D
+ min_pt=min_pt.rotate(axis_angle,cpt)
+ max_pt=max_pt.rotate(axis_angle,cpt)
+ returnmin_pt,max_pt
+
+
+
+
+[docs]
+defbounding_rectangle_extents(geometries,axis_angle=0):
+"""Get the width and length of an oriented bounding rectangle around 2D or 3D geometry.
+
+ Args:
+ geometries: An array of 2D or 3D geometry objects. Note that all objects
+ must have a min and max property.
+ axis_angle: The counter-clockwise rotation angle in radians in the XY plane
+ to represent the orientation of the bounding rectangle extents. (Default: 0).
+
+ Returns:
+ A tuple with 2 values corresponding to the width and length of the bounding
+ rectangle.
+ """
+ ifaxis_angle!=0:
+ cpt=geometries[0].vertices[0]
+ geometries=_orient_geometry(geometries,axis_angle,cpt)
+ xx=bounding_domain_x(geometries)
+ yy=bounding_domain_y(geometries)
+ returnxx[1]-xx[0],yy[1]-yy[0]
+
+
+
+
+[docs]
+defbounding_box(geometries,axis_angle=0):
+"""Get the min and max of an oriented bounding box around 3D geometry.
+
+ Args:
+ geometries: An array of 3D geometry objects. Note that all objects must
+ have a min and max property.
+ axis_angle: The counter-clockwise rotation angle in radians in the XY plane
+ to represent the orientation of the bounding box extents. (Default: 0).
+
+ Returns:
+ A tuple with two Point3D objects representing the min point and max point
+ of the bounding box respectively.
+ """
+ ifaxis_angle!=0:# rotate geometry to the bounding box
+ cpt=geometries[0].vertices[0]
+ geometries=[geom.rotate_xy(-axis_angle,cpt)forgeomingeometries]
+ xx=bounding_domain_x(geometries)
+ yy=bounding_domain_y(geometries)
+ zz=bounding_domain_z_2d_safe(geometries)
+ min_pt=Point3D(xx[0],yy[0],zz[0])
+ max_pt=Point3D(xx[1],yy[1],zz[1])
+ ifaxis_angle!=0:# rotate the points back
+ min_pt=min_pt.rotate_xy(axis_angle,cpt)
+ max_pt=max_pt.rotate_xy(axis_angle,cpt)
+ returnmin_pt,max_pt
+
+
+
+
+[docs]
+defbounding_box_extents(geometries,axis_angle=0):
+"""Get the width, length and height of an oriented bounding box around 3D geometry.
+
+ Args:
+ geometries: An array of 3D geometry objects. Note that all objects must
+ have a min and max property.
+ axis_angle: The counter-clockwise rotation angle in radians in the XY plane
+ to represent the orientation of the bounding box extents. (Default: 0).
+
+ Returns:
+ A tuple with 3 values corresponding to the width, length and height of
+ the bounding box.
+ """
+ ifaxis_angle!=0:
+ cpt=geometries[0].vertices[0]
+ geometries=[geom.rotate_xy(-axis_angle,cpt)forgeomingeometries]
+ xx=bounding_domain_x(geometries)
+ yy=bounding_domain_y(geometries)
+ zz=bounding_domain_z_2d_safe(geometries)
+ returnxx[1]-xx[0],yy[1]-yy[0],zz[1]-zz[0]
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/_modules/ladybug_geometry/dictutil.html b/docs/_modules/ladybug_geometry/dictutil.html
new file mode 100644
index 00000000..d75b756f
--- /dev/null
+++ b/docs/_modules/ladybug_geometry/dictutil.html
@@ -0,0 +1,1224 @@
+
+
+
+
+
+
+ ladybug_geometry.dictutil — ladybug geometry documentation
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+# coding=utf-8
+"""Utilities to convert any Ladybug Geometry dictionary to Python objects.
+
+Note that importing this module will import almost all modules within the
+Ladybug_geometry library in order to be able to re-serialize almost any
+dictionary produced from the library.
+"""
+from__future__importdivision
+
+fromladybug_geometry.geometry2dimportVector2D,Point2D,Ray2D, \
+ LineSegment2D,Arc2D,Polyline2D,Polygon2D,Mesh2D
+fromladybug_geometry.geometry3dimportVector3D,Point3D,Ray3D,LineSegment3D, \
+ Arc3D,Polyline3D,Polyface3D,Mesh3D,Plane,Face3D,Sphere,Cone,Cylinder
+
+
+
+[docs]
+defgeometry_dict_to_object(ladybug_geom_dict,raise_exception=True):
+"""
+ Args:
+ ladybug_geom_dict (dict): A dictionary of any Ladybug Geometry object.
+ raise_exception (bool): Boolean to note whether an exception should be raised
+ if the object is not identified as a part of ladybug_geometry.
+ Default: True.
+
+ Returns:
+ A Python object derived from the input ladybug_geom_dict.
+ """
+
+ lbt_types={
+ 'Vector2D':Vector2D,
+ 'Point2D':Point2D,
+ 'Ray2D':Ray2D,
+ 'LineSegment2D':LineSegment2D,
+ 'Arc2D':Arc2D,
+ 'Polyline2D':Polyline2D,
+ 'Polygon2D':Polygon2D,
+ 'Mesh2D':Mesh2D,
+ 'Vector3D':Vector3D,
+ 'Point3D':Point3D,
+ 'Ray3D':Ray3D,
+ 'LineSegment3D':LineSegment3D,
+ 'Arc3D':Arc3D,
+ 'Polyline3D':Polyline3D,
+ 'Mesh3D':Mesh3D,
+ 'Plane':Plane,
+ 'Polyface3D':Polyface3D,
+ 'Face3D':Face3D,
+ 'Sphere':Sphere,
+ 'Cone':Cone,
+ 'Cylinder':Cylinder
+ }
+
+ # Get the ladybug_geometry object 'Type'
+ try:
+ obj_type=ladybug_geom_dict['type']
+ exceptKeyError:
+ raiseValueError('Ladybug dictionary lacks required "type" key.')
+
+ # Build a new Ladybug Python Object based on the "Type"
+ try:
+ lbt_class=lbt_types[obj_type]
+ returnlbt_class.from_dict(ladybug_geom_dict)
+ exceptKeyError:
+ ifraise_exception:
+ raiseValueError(
+ '{} is not a recognized ladybug geometry type'.format(obj_type))
+ else:
+ returnNone
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/_modules/ladybug_geometry/geometry2d/arc.html b/docs/_modules/ladybug_geometry/geometry2d/arc.html
new file mode 100644
index 00000000..33dae3a1
--- /dev/null
+++ b/docs/_modules/ladybug_geometry/geometry2d/arc.html
@@ -0,0 +1,1710 @@
+
+
+
+
+
+
+ ladybug_geometry.geometry2d.arc — ladybug geometry documentation
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+[docs]
+classArc2D(object):
+"""2D arc object.
+
+ Args:
+ c: A Point2D representing the center of the arc.
+ r: A number representing the radius of the arc.
+ a1: A number between 0 and 2 * pi for the start angle of the arc.
+ Note that the direction of the arc is always counterclockwise.
+ a2: A number between 0 and 2 * pi for the end angle of the arc.
+ Note that the direction of the arc is always counterclockwise.
+
+ Properties:
+ * c
+ * r
+ * a1
+ * a2
+ * p1
+ * p2
+ * midpoint
+ * min
+ * max
+ * length
+ * angle
+ * is_circle
+ * is_inverted
+ """
+ __slots__=(
+ '_c','_r','_a1','_a2','_cos_a1','_sin_a1','_cos_a2','_sin_a2',
+ '_min','_max')
+
+ def__init__(self,c,r,a1=0,a2=2*math.pi):
+"""Initialize Arc2D."""
+ assertisinstance(c,Point2D),"Expected Point2D. Got {}.".format(type(c))
+ assertr>0,'Arc radius must be greater than 0. Got {}.'.format(r)
+ assert0<=a1<=2*math.pi,'Arc start angle must be between 0 and 2*pi. ' \
+ 'Got {}.'.format(a1)
+ assert0<=a2<=2*math.pi,'Arc start angle must be between 0 and 2*pi. ' \
+ 'Got {}.'.format(a2)
+ self._c=c
+ self._r=r
+ self._a1=a1
+ self._a2=a2
+ self._cos_a1=math.cos(a1)
+ self._sin_a1=math.sin(a1)
+ self._cos_a2=math.cos(a2)
+ self._sin_a2=math.sin(a2)
+ self._min=None
+ self._max=None
+
+
+[docs]
+ @classmethod
+ deffrom_dict(cls,data):
+"""Create a Arc2D from a dictionary.
+
+ Args:
+ data: A python dictionary in the following format
+
+ .. code-block:: python
+
+ {
+ "type": "Arc2D"
+ "c": (10, 0),
+ "r": 5,
+ "a1": 0,
+ "a2": 3.14159
+ }
+ """
+ returncls(Point2D.from_array(data['c']),
+ data['r'],data['a1'],data['a2'])
+
+
+
+[docs]
+ @classmethod
+ deffrom_start_mid_end(cls,p1,m,p2,circle=False):
+"""Initialize a new arc from start, middle, and end points.
+
+ Note that input points will be assumed to be in counterclockwise order.
+
+ Args:
+ p1: The start point of the arc.
+ m: Any point along the length of the arc that is not the start or end.
+ p2: The end point of the arc.
+ circle: Set to True if you would like the output to be a full circle
+ defined by the three points instead of an arc with a start and end.
+ Default is False.
+ """
+ forptin(p1,m,p2):
+ assertisinstance(pt,Point2D),"Expected Point2D. Got {}.".format(type(pt))
+ e1=(p1.x**2+p1.y**2)
+ e2=(m.x**2+m.y**2)
+ e3=(p2.x**2+p2.y**2)
+ den=2*(p1.x*(m.y-p2.y)-p1.y*(m.x-p2.x)+m.x*p2.y-p2.x*m.y)
+ try:
+ x=-(e1*(p2.y-m.y)+e2*(p1.y-p2.y)+e3*(m.y-p1.y))/den
+ y=-(e1*(m.x-p2.x)+e2*(p2.x-p1.x)+e3*(p1.x-m.x))/den
+ exceptZeroDivisionError:
+ raiseValueError('Input points {}, {}, {} are colinear and '
+ 'cannot define an arc.'.format(p1,m,p2))
+ r=math.sqrt((x-p1.x)**2+(y-p1.y)**2)
+ ifcircleisTrue:
+ returncls(Point2D(x,y),r)
+ else:
+ a1=Vector2D(1,0).angle_counterclockwise(Vector2D(p1.x-x,p1.y-y))
+ a2=Vector2D(1,0).angle_counterclockwise(Vector2D(p2.x-x,p2.y-y))
+ returncls(Point2D(x,y),r,a1,a2)
+
+
+ @property
+ defc(self):
+"""Center point of the circle on which the arc lies."""
+ returnself._c
+
+ @property
+ defr(self):
+"""Radius of arc."""
+ returnself._r
+
+ @property
+ defa1(self):
+"""Start angle of the arc in radians."""
+ returnself._a1
+
+ @property
+ defa2(self):
+"""End angle of the arc in radians."""
+ returnself._a2
+
+ @property
+ defp1(self):
+"""Start point."""
+ returnPoint2D(
+ self.c.x+self._cos_a1*self.r,self.c.y+self._sin_a1*self.r)
+
+ @property
+ defp2(self):
+"""End point."""
+ returnPoint2D(
+ self.c.x+self._cos_a2*self.r,self.c.y+self._sin_a2*self.r)
+
+ @property
+ defmidpoint(self):
+"""Midpoint."""
+ returnself.point_at(0.5)
+
+ @property
+ defmin(self):
+"""A Point2D for the minimum bounding rectangle vertex around this geometry."""
+ ifself._minisNone:
+ self._calculate_min_max()
+ returnself._min
+
+ @property
+ defmax(self):
+"""A Point2D for the maximum bounding rectangle vertex around this geometry."""
+ ifself._maxisNone:
+ self._calculate_min_max()
+ returnself._max
+
+ @property
+ deflength(self):
+"""The length of the arc."""
+ returnself.angle*self.r
+
+ @property
+ defangle(self):
+"""The total angle over the domain of the arc in radians."""
+ _diff=self._a2-self._a1
+ return_diffifnotself.is_invertedelse2*math.pi+_diff
+
+ @property
+ defarea(self):
+"""Area of the circle to which the arc belongs."""
+ assertself.is_circle,'Arc must be a closed circle to access "area" property.'
+ returnmath.pi*self.r**2
+
+ @property
+ defis_circle(self):
+"""Boolean for whether the arc is a full circle (True) or not (False)."""
+ returnself.a1==0andself.a2==2*math.pi
+
+ @property
+ defis_inverted(self):
+"""Boolean noting whether the end angle a2 is smaller than the start angle a1."""
+ returnself._a2<self._a1
+
+
+[docs]
+ defmove(self,moving_vec):
+"""Get an arc that has been moved along a vector.
+
+ Args:
+ moving_vec: A Vector2D with the direction and distance to move the arc.
+ """
+ returnArc2D(self.c.move(moving_vec),self.r,self.a1,self.a2)
+
+
+
+[docs]
+ defrotate(self,angle,origin):
+"""Get a arc that is rotated counterclockwise by a certain angle.
+
+ Args:
+ angle: An angle for rotation in radians.
+ origin: A Point2D for the origin around which the arc will
+ be rotated.
+ """
+ _a1=self.a1+angle
+ _a2=self.a2+angle
+ _a1=_a1-2*math.piif_a1>2*math.pielse_a1
+ _a2=_a2-2*math.piif_a2>2*math.pielse_a2
+ returnArc2D(self.c.rotate(angle,origin),self.r,_a1,_a2)
+
+
+
+[docs]
+ defreflect(self,normal,origin):
+"""Get a arc reflected across a plane with the input normal vector and origin.
+
+ Args:
+ normal: A Vector2D representing the normal vector for the plane across
+ which the arc will be reflected. THIS VECTOR MUST BE NORMALIZED.
+ origin: A Point2D representing the origin from which to reflect.
+ """
+ returnArc2D.from_start_mid_end(self.p2.reflect(normal,origin),
+ self.midpoint.reflect(normal,origin),
+ self.p1.reflect(normal,origin))
+
+
+
+[docs]
+ defscale(self,factor,origin=None):
+"""Scale a arc by a factor from an origin point.
+
+ Args:
+ factor: A number representing how much the arc should be scaled.
+ origin: A Point2D representing the origin from which to scale.
+ If None, it will be scaled from the World origin (0, 0).
+ """
+ returnArc2D(self.c.scale(factor,origin),self.r*factor,self.a1,self.a2)
+
+
+
+[docs]
+ defsubdivide(self,distances):
+"""Get Point2D values along the arc that subdivide it based on input distances.
+
+ Args:
+ distances: A list of distances along the arc at which to subdivide it.
+ This can also be a single number that will be repeated until the
+ end of the arc.
+ """
+ ifisinstance(distances,(float,int)):
+ distances=[distances]
+ arc_length=self.length
+ dist=distances[0]
+ index=0
+ sub_pts=[self.p1]
+ whiledist<arc_length:
+ sub_pts.append(self.point_at_length(dist))
+ ifindex<len(distances)-1:
+ index+=1
+ dist+=distances[index]
+ sub_pts.append(self.p2)
+ returnsub_pts
+
+
+
+[docs]
+ defsubdivide_evenly(self,number):
+"""Get Point2D values along the arc that divide it into evenly-spaced segments.
+
+ Args:
+ number: The number of segments into which the arc will be divided.
+ """
+ interval=1/number
+ parameter=interval
+ sub_pts=[self.p1]
+ whileparameter<=1.000000001:
+ sub_pts.append(self.point_at(parameter))
+ parameter+=interval
+ returnsub_pts
+
+
+
+[docs]
+ defpoint_at(self,parameter):
+"""Get a point at a given fraction along the arc.
+
+ Args:
+ parameter: The fraction between the start and end point where the
+ desired point lies. For example, 0.5 will yield the midpoint.
+ """
+ _ang=self._a1+self.angle*parameter
+ _ang=_angif_ang<=math.pi*2else_ang-math.pi*2
+ returnPoint2D(
+ self.c.x+math.cos(_ang)*self.r,self.c.y+math.sin(_ang)*self.r)
+
+
+
+[docs]
+ defpoint_at_angle(self,angle):
+"""Get a point at a given angle along the arc.
+
+ Args:
+ angle: The angle in radians from the start point along the arc
+ to get the Point2D.
+ """
+ _ang=self._a1+angle
+ _ang=_angif_ang<=math.pi*2else_ang-math.pi*2
+ returnPoint2D(
+ self.c.x+math.cos(_ang)*self.r,self.c.y+math.sin(_ang)*self.r)
+
+
+
+[docs]
+ defpoint_at_length(self,length):
+"""Get a point at a given distance along the arc segment.
+
+ Args:
+ length: The distance along the arc from the start point where the
+ desired point lies.
+ """
+ returnself.point_at(length/self.length)
+
+
+
+[docs]
+ defclosest_point(self,point):
+"""Get the closest Point2D on this object to another Point2D.
+
+ Args:
+ point: A Point2D object to which the closest point on this object
+ will be computed.
+
+ Returns:
+ Point2D for the closest point on this line to the input point.
+ """
+ returnclosest_point2d_on_arc2d(point,self)
+
+
+
+[docs]
+ defdistance_to_point(self,point):
+"""Get the minimum distance between this object and the input point.
+
+ Args:
+ point: A Point2D object to which the minimum distance will be computed.
+
+ Returns:
+ The distance to the input point.
+ """
+ close_pt=self.closest_point(point)
+ returnpoint.distance_to_point(close_pt)
+
+
+
+[docs]
+ defintersect_line_ray(self,line_ray):
+"""Get the intersection between this Arc2D and another Ray2 or LineSegment2D.
+
+ Args:
+ line_ray: Another LineSegment2D or Ray2D or to intersect.
+
+ Returns:
+ A list of 2 Point2D objects if a full intersection exists.
+ A list with a single Point2D object if the line is tangent or intersects
+ only once. None if no intersection exists.
+ """
+ returnintersect_line2d_arc2d(line_ray,self)
+
+
+
+[docs]
+ defintersect_line_infinite(self,line_ray):
+"""Get the intersection between this Arc2D and an infinitely extending Ray2D.
+
+ Args:
+ line_ray: Another LineSegment2D or Ray2D or to intersect.
+
+ Returns:
+ A list of 2 Point2D objects if a full intersection exists.
+ A list with a single Point2D object if the line is tangent or intersects
+ only once. None if no intersection exists.
+ """
+ returnintersect_line2d_infinite_arc2d(line_ray,self)
+
+
+
+[docs]
+ defsplit_line_infinite(self,line_ray):
+"""Split this Arc2D in 2-3 using an infinitely extending Ray2D or LineSegment2D.
+
+ Args:
+ line_ray: A LineSegment2D or Ray2D that will be extended infinitely for
+ intersection.
+
+ Returns:
+ A list with 2 or 3 Arc2D objects if the split was successful.
+ Will be a list with 1 Arc2D if no intersection exists.
+ """
+ inters=intersect_line2d_infinite_arc2d(line_ray,self)
+ ifintersisNone:
+ return[self]
+ elifself.is_circle:
+ iflen(inters)!=2:
+ return[self]
+ a1=self._a_from_pt(inters[0])
+ a2=self._a_from_pt(inters[1])
+ return[Arc2D(self.c,self.r,a1,a2),Arc2D(self.c,self.r,a2,a1)]
+ eliflen(inters)==1:
+ am=self._a_from_pt(inters[0])
+ return[Arc2D(self.c,self.r,self.a1,am),
+ Arc2D(self.c,self.r,am,self.a2)]
+ eliflen(inters)==2:
+ am1=self._a_from_pt(inters[0])
+ am2=self._a_from_pt(inters[1])
+ ifself._cc_difference(am1)<self._cc_difference(am2):
+ return[Arc2D(self.c,self.r,self.a1,am1),
+ Arc2D(self.c,self.r,am1,am2),
+ Arc2D(self.c,self.r,am2,self.a2)]
+ else:
+ return[Arc2D(self.c,self.r,self.a1,am2),
+ Arc2D(self.c,self.r,am2,am1),
+ Arc2D(self.c,self.r,am1,self.a2)]
+
+
+
+[docs]
+ defto_polyline(self,divisions,interpolated=True):
+"""Get this Arc2D as an approximated Polyline2D.
+
+ Args:
+ divisions: The number of segments into which the arc will be divided.
+ interpolated: Boolean to note whether the polyline should be interpolated
+ between the input vertices when it is translated to other interfaces.
+ This property has no effect on the geometric calculations performed
+ by this library and is only present in order to assist with
+ display/translation. (Default: True)
+ """
+ pts=self.subdivide_evenly(divisions)
+ returnPolyline2D(pts,interpolated)
+
+
+
+[docs]
+ defto_dict(self):
+"""Get Arc2D as a dictionary."""
+ return{'type':'Arc2D','c':self.c.to_array(),
+ 'r':self.r,'a1':self.a1,'a2':self.a2}
+
+
+
+[docs]
+ defduplicate(self):
+"""Get a copy of this object."""
+ returnself.__copy__()
+
+
+ def_pt_in(self,point):
+ ifself.is_circle:
+ returnTrue
+ else:
+ v=Vector2D(point.x-self.c.x,point.y-self.c.y)
+ a=Vector2D(1,0).angle_counterclockwise(v)
+ return(notself.is_invertedandself.a1<a<self.a2)or \
+ (self.is_invertedandself.a1>a>self.a2)
+
+ def_a_from_pt(self,point):
+"""Get the angle along the arc given a point along the arc."""
+ v=Vector2D(point.x-self.c.x,point.y-self.c.y)
+ returnVector2D(1,0).angle_counterclockwise(v)
+
+ def_cc_difference(self,angle):
+"""Get counterclockwise different between an angle and the start of this arc."""
+ _diff=angle-self.a1
+ return_diffifnotangle<self.a1else2*math.pi+_diff
+
+ def_calculate_min_max(self):
+"""Calculate maximum and minimum Point2D for this object."""
+ # get the quadrants of the start and end of the arc
+ start_quad=self._angle_quadrant(self._a1)
+ end_quad=self._angle_quadrant(self._a2)
+ # get the min and max of the start and end points
+ x_cor=(self._cos_a1*self.r,self._cos_a2*self.r)
+ y_cor=(self._sin_a1*self.r,self._sin_a2*self.r)
+ mnx,mny=min(x_cor),min(y_cor)
+ mxx,mxy=max(x_cor),max(y_cor)
+ # build extremum matrices
+ r=self.r
+ x_max=((mxx,r,r,r),(mxx,mxx,r,r),
+ (mxx,mxx,mxx,r),(mxx,mxx,mxx,mxx))
+ y_max=((mxy,mxy,mxy,mxy),(r,mxy,r,r),
+ (r,mxy,mxy,r),(r,mxy,mxy,mxy))
+ x_min=((mnx,-r,mnx,mnx),(mnx,mnx,mnx,mnx),
+ (-r,-r,mnx,-r),(-r,-r,mnx,mnx))
+ y_min=((mny,-r,-r,mny),(mny,mny,-r,mny),
+ (mny,mny,mny,mny),(-r,-r,-r,mny))
+ # select the desired values from the extremum matrices
+ min_pt=(x_min[end_quad][start_quad],y_min[end_quad][start_quad])
+ max_pt=(x_max[end_quad][start_quad],y_max[end_quad][start_quad])
+ self._min=Point2D(min_pt[0]+self.c.x,min_pt[1]+self.c.y)
+ self._max=Point2D(max_pt[0]+self.c.x,max_pt[1]+self.c.y)
+
+ @staticmethod
+ def_angle_quadrant(angle):
+"""Get the quadrant of a given angle in radians."""
+ ifangle<math.pi/2:
+ return0
+ elifangle<math.pi:
+ return1
+ elifangle<math.pi*(3/2):
+ return2
+ return3
+
+ def__copy__(self):
+ returnArc2D(self.c,self.r,self.a1,self.a2)
+
+ def__key(self):
+"""A tuple based on the object properties, useful for hashing."""
+ return(self.c,self.r,self.a1,self.a2)
+
+ def__hash__(self):
+ returnhash(self.__key())
+
+ def__eq__(self,other):
+ returnisinstance(other,Arc2D)andself.__key()==other.__key()
+
+ def__ne__(self,other):
+ returnnotself.__eq__(other)
+
+
+[docs]
+classLineSegment2D(Base1DIn2D):
+"""2D line segment object.
+
+ Args:
+ p: A Point2D representing the first point of the line segment.
+ v: A Vector2D representing the vector to the second point.
+
+ Properties:
+ * p
+ * v
+ * p1
+ * p2
+ * min
+ * max
+ * center
+ * midpoint
+ * endpoints
+ * length
+ * vertices
+ """
+ __slots__=()
+
+ def__init__(self,p,v):
+"""Initialize LineSegment2D."""
+ Base1DIn2D.__init__(self,p,v)
+
+
+[docs]
+ @classmethod
+ deffrom_end_points(cls,p1,p2):
+"""Initialize a line segment from a start point and and end point.
+
+ Args:
+ p1: A Point2D representing the first point of the line segment.
+ p2: A Point2D representing the second point of the line segment.
+ """
+ v=p2-p1
+ returncls(p1,Vector2D(v.x,v.y))
+
+
+
+[docs]
+ @classmethod
+ deffrom_sdl(cls,s,d,length):
+"""Initialize a line segment from a start point, direction, and length.
+
+ Args:
+ s: A Point2D representing the start point of the line segment.
+ d: A Vector2D representing the direction of the line segment.
+ length: A number representing the length of the line segment.
+ """
+ returncls(s,d*length/d.magnitude)
+
+
+
+[docs]
+ @classmethod
+ deffrom_array(cls,line_array):
+""" Create a LineSegment2D from a nested array of two endpoint coordinates.
+
+ Args:
+ line_array: Nested tuples ((pt1.x, pt1.y), (pt2.x, pt2.y)), where
+ pt1 and pt2 represent the endpoints of the line segment.
+ """
+ returnLineSegment2D.from_end_points(*tuple(Point2D(*pt)forptinline_array))
+
+
+ @property
+ defp1(self):
+"""First point (same as p)."""
+ returnself.p
+
+ @property
+ defp2(self):
+"""Second point."""
+ returnPoint2D(self.p.x+self.v.x,self.p.y+self.v.y)
+
+ @property
+ defmidpoint(self):
+"""Midpoint."""
+ returnself.point_at(0.5)
+
+ @property
+ defendpoints(self):
+"""Tuple of endpoints """
+ return(self.p1,self.p2)
+
+ @property
+ deflength(self):
+"""The length of the line segment."""
+ returnself.v.magnitude
+
+ @property
+ defvertices(self):
+"""Tuple of both vertices in this object."""
+ return(self.p1,self.p2)
+
+
+[docs]
+ defis_equivalent(self,other,tolerance):
+"""Boolean noting equivalence (within tolerance) between this line and another.
+
+ The order of the line points do not matter for equivalence to be true.
+
+ Args:
+ other: LineSegment2D for comparison.
+ tolerance: float representing point equivalence.
+
+ Returns:
+ True if equivalent else False
+ """
+ tol=tolerance
+ return(
+ self.p1.is_equivalent(other.p1,tol)andself.p2.is_equivalent(other.p2,tol)
+ )or(
+ self.p1.is_equivalent(other.p2,tol)andself.p2.is_equivalent(other.p1,tol)
+ )
+
+
+
+[docs]
+ defflip(self):
+"""Get a copy of this line segment that is flipped."""
+ returnLineSegment2D(self.p2,self.v.reverse())
+
+
+
+[docs]
+ defmove(self,moving_vec):
+"""Get a line segment that has been moved along a vector.
+
+ Args:
+ moving_vec: A Vector2D with the direction and distance to move the ray.
+ """
+ returnLineSegment2D(self.p.move(moving_vec),self.v)
+
+
+
+[docs]
+ defrotate(self,angle,origin):
+"""Get a line segment that is rotated counterclockwise by a certain angle.
+
+ Args:
+ angle: An angle for rotation in radians.
+ origin: A Point2D for the origin around which the line segment will
+ be rotated.
+ """
+ returnLineSegment2D(self.p.rotate(angle,origin),self.v.rotate(angle))
+
+
+
+[docs]
+ defreflect(self,normal,origin):
+"""Get a line segment reflected across a plane with the input normal and origin.
+
+ Args:
+ normal: A Vector2D representing the normal vector for the plane across
+ which the line segment will be reflected. THIS VECTOR MUST BE NORMALIZED.
+ origin: A Point2D representing the origin from which to reflect.
+ """
+ returnLineSegment2D(self.p.reflect(normal,origin),self.v.reflect(normal))
+
+
+
+[docs]
+ defscale(self,factor,origin=None):
+"""Scale a line segment by a factor from an origin point.
+
+ Args:
+ factor: A number representing how much the line segment should be scaled.
+ origin: A Point2D representing the origin from which to scale.
+ If None, it will be scaled from the World origin (0, 0).
+ """
+ returnLineSegment2D(self.p.scale(factor,origin),self.v*factor)
+
+
+
+[docs]
+ defoffset(self,distance):
+"""Offset the line segment by a given distance.
+
+ Args:
+ distance: The distance that the line segment will be offset. Both positive
+ and negative values are accepted with positive values being offset
+ to the left of the line and negative values being offset to the
+ right of the line (starting from LineSegment.p and looking
+ in the direction of LineSegment.v).
+ """
+ ifdistance==0:
+ returnself
+ move_vec=self.v.rotate(math.pi/2).normalize()*distance
+ returnLineSegment2D(self.p.move(move_vec),self.v)
+
+
+
+[docs]
+ defsubdivide(self,distances):
+"""Get Point2D values along the line that subdivide it based on input distances.
+
+ Args:
+ distances: A list of distances along the line at which to subdivide it.
+ This can also be a single number that will be repeated until the
+ end of the line.
+ """
+ ifisinstance(distances,(float,int)):
+ distances=[distances]
+ line_length=self.length
+ dist=distances[0]
+ index=0
+ sub_pts=[self.p]
+ whiledist<line_length:
+ sub_pts.append(self.point_at_length(dist))
+ ifindex<len(distances)-1:
+ index+=1
+ dist+=distances[index]
+ sub_pts.append(self.p2)
+ returnsub_pts
+
+
+
+[docs]
+ defsubdivide_evenly(self,number):
+"""Get Point2D values along the line that divide it into evenly-spaced segments.
+
+ Args:
+ number: The number of segments into which the line will be divided.
+ """
+ interval=1/number
+ parameter=interval
+ sub_pts=[self.p]
+ whileparameter<=1:
+ sub_pts.append(self.point_at(parameter))
+ parameter+=interval
+ returnsub_pts
+
+
+
+[docs]
+ defpoint_at(self,parameter):
+"""Get a point at a given fraction along the line segment.
+
+ Args:
+ parameter: The fraction between the start and end point where the
+ desired point lies. For example, 0.5 will yield the midpoint.
+ """
+ returnself.p+self.v*parameter
+
+
+
+[docs]
+ defpoint_at_length(self,length):
+"""Get a point at a given distance along the line segment.
+
+ Args:
+ length: The distance along the line from the start point where the
+ desired point lies.
+ """
+ returnself.p+self.v*(length/self.length)
+
+
+
+[docs]
+ defintersect_line_ray(self,line_ray):
+"""Get the intersection between this object and another Ray2 or LineSegment2D.
+
+ Args:
+ line_ray: Another LineSegment2D or Ray2D or to intersect.
+
+ Returns:
+ Point2D of intersection if it exists. None if no intersection exists.
+ """
+ ifisinstance(line_ray,LineSegment2D):
+ returnintersect_line_segment2d(self,line_ray)
+ returnintersect_line2d(self,line_ray)
+
+
+
+[docs]
+ defclosest_points_between_line(self,line):
+"""Get the two closest Point2D between this object to another LineSegment2D.
+
+ Note that the line segments should not intersect for the result to be valid.
+
+ Args:
+ line: A LineSegment2D object to which the closest points
+ will be computed.
+
+ Returns:
+ Two Point2D objects representing
+
+ 1) The closest point on this object to the input line.
+ 2) The closest point on the input line to this object.
+ """
+ dist,pts=closest_point2d_between_line2d(self,line)
+ returnpts
+
+
+
+[docs]
+ defdistance_to_line(self,line):
+"""Get the minimum distance between this object and the input LineSegment2D.
+
+ Note that the line segments should not intersect for the result to be valid.
+
+ Args:
+ line: A LineSegment2D object to which the minimum distance will be computed.
+
+ Returns:
+ The minimum distance to the input line.
+ """
+ dist,pts=closest_point2d_between_line2d(self,line)
+ returndist
+
+
+
+[docs]
+ defto_dict(self):
+"""Get LineSegment2D as a dictionary."""
+ base=Base1DIn2D.to_dict(self)
+ base['type']='LineSegment2D'
+ returnbase
+
+
+
+[docs]
+ defto_array(self):
+""" A nested list representing the two line endpoint coordinates."""
+ return(self.p1.to_array(),self.p2.to_array())
+[docs]
+classMesh2D(MeshBase):
+"""2D Mesh object.
+
+ Args:
+ vertices: A list or tuple of Point2D objects for vertices.
+ faces: A list of tuples with each tuple having either 3 or 4 integers.
+ These integers correspond to indices within the list of vertices.
+ colors: An optional list of colors that correspond to either the faces
+ of the mesh or the vertices of the mesh. Default is None.
+
+ Properties:
+ * vertices
+ * faces
+ * colors
+ * is_color_by_face
+ * min
+ * max
+ * center
+ * area
+ * centroid
+ * face_areas
+ * face_centroids
+ * face_area_centroids
+ * face_vertices
+ * vertex_connected_faces
+ * edges
+ * naked_edges
+ * internal_edges
+ * non_manifold_edges
+ """
+ __slots__=('_min','_max','_center','_centroid')
+
+ def__init__(self,vertices,faces,colors=None):
+"""Initialize Mesh2D."""
+ self._vertices=self._check_vertices_input(vertices)
+ self._faces=self._check_faces_input(faces)
+ self._is_color_by_face=False# default if colors is None
+ self.colors=colors
+
+ self._min=None
+ self._max=None
+ self._center=None
+ self._area=None
+ self._centroid=None
+ self._face_areas=None
+ self._face_centroids=None
+ self._face_area_centroids=None
+ self._vertex_connected_faces=None
+ self._edge_indices=None
+ self._edge_types=None
+ self._edges=None
+ self._naked_edges=None
+ self._internal_edges=None
+ self._non_manifold_edges=None
+
+
+[docs]
+ @classmethod
+ deffrom_dict(cls,data):
+"""Create a Mesh2D from a dictionary.
+
+ Args:
+ data: A python dictionary in the following format
+
+ .. code-block:: python
+
+ {
+ "type": "Mesh2D",
+ "vertices": [(0, 0), (10, 0), (0, 10)],
+ "faces": [(0, 1, 2)],
+ "colors": [{"r": 255, "g": 0, "b": 0}]
+ }
+ """
+ colors=None
+ if'colors'indataanddata['colors']isnotNoneandlen(data['colors'])!=0:
+ try:
+ fromladybug.colorimportColor
+ exceptImportError:
+ raiseImportError('Colors are specified in input Mesh2D dictionary '
+ 'but failed to import ladybug.color')
+ colors=tuple(Color.from_dict(col)forcolindata['colors'])
+ fcs=tuple(tuple(f)forfindata['faces'])# cast to immutable type
+ returncls(tuple(Point2D.from_array(pt)forptindata['vertices']),fcs,colors)
+
+
+
+[docs]
+ @classmethod
+ deffrom_face_vertices(cls,faces,purge=True):
+"""Create a mesh from a list of faces with each face defined by Point2Ds.
+
+ Args:
+ faces: A list of faces with each face defined as a list of 3 or 4 Point2D.
+ purge: A boolean to indicate if duplicate vertices should be shared between
+ faces. Default is True to purge duplicate vertices, which can be slow
+ for large lists of faces but results in a higher-quality mesh with
+ a smaller size in memory. Note that vertices are only considered
+ duplicate if the coordinate values are equal to one another
+ within floating point tolerance. To remove duplicate vertices
+ within a specified tolerance other than floating point, the
+ from_purged_face_vertices method should be used instead.
+ """
+ vertices,face_collector=cls._interpret_input_from_face_vertices(faces,purge)
+ returncls(tuple(vertices),tuple(face_collector))
+
+
+
+[docs]
+ @classmethod
+ deffrom_purged_face_vertices(cls,faces,tolerance):
+"""Create a mesh from a list of faces with each face defined by Point3Ds.
+
+ This method is slower than 'from_face_vertices' but will result in a mesh
+ with fewer vertices and a smaller size in memory. This method is similar to
+ using the 'purge' option in 'from_face_vertices' but will result in more shared
+ vertices since it uses a tolerance to check equivalent vertices rather than
+ comparing within floating point tolerance.
+
+ Args:
+ faces: A list of faces with each face defined as a list of 3 or 4 Point3D.
+ tolerance: A number for the minimum difference between coordinate
+ values at which point vertices are considered equal to one another.
+ """
+ vertices,faces=cls._interpret_input_from_face_vertices_with_tolerance(
+ faces,tolerance)
+ returncls(tuple(vertices),tuple(faces))
+
+
+
+[docs]
+ @classmethod
+ deffrom_polygon_triangulated(cls,boundary_polygon,hole_polygons=None):
+"""Initialize a triangulated Mesh2D from a Polygon2D.
+
+ The triangles of the mesh faces will always completely fill the shape
+ defines by the input boundary_polygon with holes subtracted from it.
+
+ Args:
+ boundary_polygon: A Polygon2D object representing the boundary of the shape.
+ hole_polygons: Optional list of Polygon2D objects representing holes
+ within the boundary_polygon.
+ """
+ assertisinstance(boundary_polygon,Polygon2D),'boundary_polygon must be a ' \
+ 'Polygon2D to use from_polygon_triangulated. Got {}.'.format(
+ type(boundary_polygon))
+
+ ifhole_polygonsisNoneandboundary_polygon.is_convex:# fan triangulation!
+ _faces=[]
+ foriinxrange(1,len(boundary_polygon)-1):
+ _faces.append((0,i,i+1))
+ _new_mesh=cls(boundary_polygon.vertices,_faces)
+ else:# slower ear-clipping method
+ ifhole_polygonsisnotNone:
+ forholeinhole_polygons:
+ assertisinstance(hole,Polygon2D),'Hole must be a Polygon2D ' \
+ 'to use from_polygon_triangulated. Got {}.'.format(type(hole))
+ _vertices,_faces=Mesh2D._ear_clipping_triangulation(
+ boundary_polygon,hole_polygons)
+ _new_mesh=cls(_vertices,_faces)
+
+ return_new_mesh
+
+
+
+[docs]
+ @classmethod
+ deffrom_polygon_grid(cls,polygon,x_dim,y_dim,generate_centroids=True):
+"""Initialize a gridded Mesh2D from a Polygon2D.
+
+ Note that this gridded mesh will usually not completely fill the polygon.
+ Essentially, this method generates a grid over the domain of the polygon
+ and then removes any points that do not lie within the polygon.
+
+ Args:
+ polygon: A Polygon2D object.
+ x_dim: The x dimension of the grid cells as a number.
+ y_dim: The y dimension of the grid cells as a number.
+ generate_centroids: Set to True to have the face centroids generated
+ alongside the grid of vertices, which is much faster than having
+ them generated upon request as they typically are. However, if you
+ have no need for the face centroids, you would save memory by setting
+ this to False. Default is True.
+ """
+ assertisinstance(polygon,Polygon2D),'Expected Polygon2D for' \
+ ' Mesh2D.from_polygon_grid. Got {}'.format(type(polygon))
+ # figure out how many x and y cells to make
+ _x_dim,_num_x=Mesh2D._domain_dimensions(polygon.max.x-polygon.min.x,x_dim)
+ _y_dim,_num_y=Mesh2D._domain_dimensions(polygon.max.y-polygon.min.y,y_dim)
+ _poly_min=polygon.min
+
+ # generate the gid of points and faces
+ _verts=Mesh2D._grid_vertices(_poly_min,_num_x,_num_y,_x_dim,_y_dim)
+ _faces=Mesh2D._grid_faces(_num_x,_num_y)
+ _centroids=None
+ ifgenerate_centroidsisTrue:# calculate centroids if requested
+ _centroids=Mesh2D._grid_centroids(
+ _poly_min,_num_x,_num_y,_x_dim,_y_dim)
+
+ # figure out which vertices lie inside the polygon
+ # for tolerance reasons, we scale the polygon by a very small amount
+ # this avoids the fringe cases noted in the Polygon2d.is_point_inside description
+ tol_pt=Vector2D(0.0000001,0.0000001)
+ scaled_poly=Polygon2D(
+ tuple(pt.scale(1.000001,_poly_min)-tol_ptforptinpolygon.vertices))
+ _pattern=[scaled_poly.is_point_inside(_v)for_vin_verts]
+
+ # build the mesh
+ _mesh_init=cls(_verts,_faces)
+ _mesh_init._face_centroids=_centroids
+ _mesh_init._face_area_centroids=_centroids
+ _new_mesh,_face_pattern=_mesh_init.remove_vertices(_pattern)
+ _new_mesh._face_areas=x_dim*y_dim
+ return_new_mesh
+
+
+
+[docs]
+ @classmethod
+ deffrom_grid(cls,base_point=Point2D(),num_x=1,num_y=1,x_dim=1,y_dim=1,
+ generate_centroids=True):
+"""Initialize a Mesh2D from parameters that define a grid.
+
+ Args:
+ base_point: The base point from which the mesh grid will be generated.
+ Default is (0, 0).
+ num_x: An integer for the number of mesh cells to generate in the
+ x direction. Default is 1.
+ num_y: An integer for the number of mesh cells to generate in the
+ y direction. Default is 1.
+ x_dim: The x dimension of the grid cells as a number. Default is 1.
+ y_dim: The y dimension of the grid cells as a number. Default is 1.
+ generate_centroids: Set to True to have the face centroids generated
+ alongside the grid of vertices, which is much faster than having
+ them generated upon request as they typically are. However, if you
+ have no need for the face centroids, you would save memory by setting
+ this to False. Default is True.
+ """
+ _verts=Mesh2D._grid_vertices(base_point,num_x,num_y,x_dim,y_dim)
+ _faces=Mesh2D._grid_faces(num_x,num_y)
+ _centroids=None
+ ifgenerate_centroidsisTrue:
+ _centroids=Mesh2D._grid_centroids(base_point,num_x,num_y,x_dim,y_dim)
+
+ _new_mesh=cls(tuple(_verts),tuple(_faces))
+ _new_mesh._face_areas=x_dim*y_dim
+ _new_mesh._face_centroids=_centroids
+ _new_mesh._face_area_centroids=_centroids
+ return_new_mesh
+
+
+ @property
+ defmin(self):
+"""A Point2D for the minimum bounding rectangle vertex around this geometry."""
+ ifself._minisNone:
+ self._calculate_min_max()
+ returnself._min
+
+ @property
+ defmax(self):
+"""A Point2D for the maximum bounding rectangle vertex around this geometry."""
+ ifself._maxisNone:
+ self._calculate_min_max()
+ returnself._max
+
+ @property
+ defcenter(self):
+"""A Point2D for the center of the bounding rectangle around this geometry."""
+ ifself._centerisNone:
+ min,max=self.min,self.max
+ self._center=Point2D((min.x+max.x)/2,(min.y+max.y)/2)
+ returnself._center
+
+ @property
+ defface_areas(self):
+"""A tuple of face areas that parallels the faces property."""
+ ifself._face_areasisNone:
+ self._face_areas=tuple(self._face_area(face)forfaceinself.faces)
+ elifisinstance(self._face_areas,(float,int)):# grid of faces with same area
+ self._face_areas=tuple(self._face_areasforfaceinself.faces)
+ returnself._face_areas
+
+ @property
+ defcentroid(self):
+"""The centroid of the mesh as a Point2D (aka. center of mass).
+
+ Note that the centroid is more time consuming to compute than the center
+ (or the middle point of the bounding rectangle). So the center might be
+ preferred over the centroid if you just need a rough point for the middle
+ of the mesh.
+ """
+ ifself._centroidisNone:
+ _weight_x=0
+ _weight_y=0
+ for_c,_ainzip(self.face_area_centroids,self.face_areas):
+ _weight_x+=_c.x*_a
+ _weight_y+=_c.y*_a
+ self._centroid=Point2D(_weight_x/self.area,_weight_y/self.area)
+ returnself._centroid
+
+ @property
+ defface_edges(self):
+"""List of polylines with one Polyline2D for each face.
+
+ This is faster to compute compared to the edges and results in effectively
+ the same type of wireframe visualization.
+ """
+ _all_verts=self._vertices
+ f_edges=[]
+ forfaceinself._faces:
+ verts=tuple(_all_verts[v]forvinface)+(_all_verts[face[0]],)
+ f_edges.append(Polyline2D(verts))
+ returnf_edges
+
+ @property
+ defedges(self):
+""""Tuple of all edges in this Mesh3D as LineSegment3D objects."""
+ ifself._edgesisNone:
+ ifself._edge_indicesisNone:
+ self._compute_edge_info()
+ self._edges=tuple(LineSegment2D.from_end_points(
+ self.vertices[seg[0]],self.vertices[seg[1]])
+ forseginself._edge_indices)
+ returnself._edges
+
+ @property
+ defnaked_edges(self):
+""""Tuple of all naked edges in this Mesh3D as LineSegment3D objects.
+
+ Naked edges belong to only one face in the mesh (they are not
+ shared between faces).
+ """
+ ifself._naked_edgesisNone:
+ self._naked_edges=self._get_edge_type(0)
+ returnself._naked_edges
+
+ @property
+ definternal_edges(self):
+""""Tuple of all internal edges in this Mesh3D as LineSegment3D objects.
+
+ Internal edges are shared between two faces in the mesh.
+ """
+ ifself._internal_edgesisNone:
+ self._internal_edges=self._get_edge_type(1)
+ returnself._internal_edges
+
+ @property
+ defnon_manifold_edges(self):
+""""Tuple of all non-manifold edges in this mesh as LineSegment3D objects.
+
+ Non-manifold edges are shared between three or more faces.
+ """
+ ifself._non_manifold_edgesisNone:
+ ifself._edgesisNone:
+ self.edges
+ nm_edges=[]
+ fori,typeinenumerate(self._edge_types):
+ iftype>1:
+ nm_edges.append(self._edges[i])
+ self._non_manifold_edges=tuple(nm_edges)
+ returnself._non_manifold_edges
+
+
+[docs]
+ deftriangulated(self):
+"""Get a version of this Mesh2D where all quads have been triangulated."""
+ _new_faces=[]
+ forfaceinself.faces:
+ iflen(face)==3:
+ _new_faces.append(face)
+ else:
+ _triangles=Mesh2D._quad_to_triangles([self._vertices[i]foriinface])
+ _triangles=[tuple(face[vertex_idx]forvertex_idxinnew_face)
+ fornew_facein_triangles]
+ _new_faces.extend(_triangles)
+ _new_faces=tuple(_new_faces)
+
+ _new_colors=self.colors
+ ifself.is_color_by_faceisTrue:
+ _new_colors=[]
+ fori,faceinenumerate(self.faces):
+ iflen(face)==3:
+ _new_colors.append(self.colors[i])
+ else:
+ _new_colors.extend([self.colors[i]]*2)
+ _new_colors=tuple(_new_colors)
+
+ _new_mesh=Mesh2D(self.vertices,_new_faces,_new_colors)
+ return_new_mesh
+
+
+
+[docs]
+ defremove_vertices(self,pattern):
+"""Get a version of this mesh where vertices are removed according to a pattern.
+
+ Args:
+ pattern: A list of boolean values denoting whether a vertex should
+ remain in the mesh (True) or be removed from the mesh (False).
+ The length of this list must match the number of this mesh's vertices.
+
+ Returns:
+ A tuple with two elements
+
+ - new_mesh:
+ A mesh where the vertices have been removed according
+ to the input pattern.
+
+ - face_pattern:
+ A list of boolean values that corresponds to the
+ original mesh faces noting whether the face is in the new mesh (True)
+ or has been removed from the new mesh (False).
+ """
+ _new_verts,_new_faces,_new_colors,_new_f_cent,_new_f_area,face_pattern= \
+ self._remove_vertices(pattern)
+
+ new_mesh=Mesh2D(_new_verts,_new_faces,_new_colors)
+ new_mesh._face_centroids=_new_f_cent
+ new_mesh._face_areas=_new_f_area
+ returnnew_mesh,face_pattern
+
+
+
+[docs]
+ defremove_faces(self,pattern):
+"""Get a version of this mesh where faces are removed according to a pattern.
+
+ Args:
+ pattern: A list of boolean values denoting whether a face should
+ remain in the mesh (True) or be removed from the mesh (False).
+ The length of this list must match the number of this mesh's faces.
+
+ Returns:
+ A tuple with two elements
+
+ - new_mesh:
+ A mesh where the faces have been removed according
+ to the input pattern.
+
+ - vertex_pattern:
+ A list of boolean values that corresponds to the
+ original mesh vertices noting whether the vertex is in the new mesh
+ (True) or has been removed from the new mesh (False).
+ """
+ vertex_pattern=self._vertex_pattern_from_remove_faces(pattern)
+ _new_verts,_new_faces,_new_colors,_new_f_cent,_new_f_area,face_pattern= \
+ self._remove_vertices(vertex_pattern,pattern)
+
+ new_mesh=Mesh2D(_new_verts,_new_faces,_new_colors)
+ new_mesh._face_centroids=_new_f_cent
+ new_mesh._face_areas=_new_f_area
+ returnnew_mesh,vertex_pattern
+
+
+
+[docs]
+ defremove_faces_only(self,pattern):
+"""Get a version of this mesh where faces are removed and vertices are unaltered.
+
+ This is faster than the Mesh2D.remove_faces method but will likely result
+ a lower-quality mesh where several vertices exist in the mesh that are not
+ referenced by any face. This may be preferred if pure speed of removing
+ faces is a priority over smallest size of the mesh in memory.
+
+ Args:
+ pattern: A list of boolean values denoting whether a face should
+ remain in the mesh (True) or be removed from the mesh (False).
+ The length of this list must match the number of this mesh's faces.
+
+ Returns:
+ new_mesh -- A mesh where the faces have been removed according
+ to the input pattern.
+ """
+ _new_faces,_new_colors,_new_f_cent,_new_f_area= \
+ self._remove_faces_only(pattern)
+
+ new_mesh=Mesh2D(self.vertices,_new_faces,_new_colors)
+ new_mesh._face_centroids=_new_f_cent
+ new_mesh._face_areas=_new_f_area
+ returnnew_mesh
+
+
+
+[docs]
+ defrotate(self,angle,origin):
+"""Get a mesh that is rotated counterclockwise by a certain angle.
+
+ Args:
+ angle: An angle for rotation in radians.
+ origin: A Point2D for the origin around which the point will be rotated.
+ """
+ _verts=tuple([pt.rotate(angle,origin)forptinself.vertices])
+ returnself._mesh_transform(_verts)
+
+
+
+[docs]
+ defscale(self,factor,origin=None):
+"""Scale a mesh by a factor from an origin point.
+
+ Args:
+ factor: A number representing how much the mesh should be scaled.
+ origin: A Point representing the origin from which to scale.
+ If None, it will be scaled from the World origin (0, 0).
+ """
+ iforiginisNone:
+ _verts=tuple(
+ Point2D(pt.x*factor,pt.y*factor)forptinself.vertices)
+ else:
+ _verts=tuple(pt.scale(factor,origin)forptinself.vertices)
+ returnself._mesh_scale(_verts,factor)
+
+
+
+[docs]
+ defto_dict(self):
+"""Get Mesh2D as a dictionary."""
+ colors=None
+ ifself.colorsisnotNone:
+ colors=[col.to_dict()forcolinself.colors]
+ return{'type':'Mesh2D',
+ 'vertices':[pt.to_array()forptinself.vertices],
+ 'faces':self.faces,'colors':colors}
+
+
+
+[docs]
+ @staticmethod
+ defjoin_meshes(meshes):
+"""Join an array of Mesh2Ds into a single Mesh2D.
+
+ Args:
+ meshes: An array of meshes to be joined into one.
+
+ Returns:
+ A single Mesh2D object derived from the input meshes.
+ """
+ # set up empty lists of objects to be filled
+ verts=[]
+ faces=[]
+ colors=[]
+
+ # loop through all of the meshes and get new faces
+ total_v_i=0
+ formeshinmeshes:
+ verts.extend(mesh._vertices)
+ forfcinmesh._faces:
+ faces.append(tuple(v_i+total_v_iforv_iinfc))
+ total_v_i+=len(mesh._vertices)
+ ifmesh._colors:
+ colors.extend(mesh._colors)
+
+ # create the new mesh
+ iflen(colors)!=0:
+ new_mesh=Mesh2D(verts,faces,colors)
+ else:
+ new_mesh=Mesh2D(verts,faces)
+
+ # attempt to transfer the centroids and normals
+ ifall(msh._face_centroidsisnotNoneformshinmeshes):
+ new_mesh._face_centroids=tuple(ptformshinmeshesforptinmsh)
+ ifall(msh._face_areasisnotNoneformshinmeshes):
+ new_mesh._face_areas=tuple(aformshinmeshesforainmsh.face_areas)
+ returnnew_mesh
+
+
+ def_calculate_min_max(self):
+"""Calculate maximum and minimum Point2D for this object."""
+ min_pt=[self.vertices[0].x,self.vertices[0].y]
+ max_pt=[self.vertices[0].x,self.vertices[0].y]
+
+ forvinself.vertices[1:]:
+ ifv.x<min_pt[0]:
+ min_pt[0]=v.x
+ elifv.x>max_pt[0]:
+ max_pt[0]=v.x
+ ifv.y<min_pt[1]:
+ min_pt[1]=v.y
+ elifv.y>max_pt[1]:
+ max_pt[1]=v.y
+
+ self._min=Point2D(min_pt[0],min_pt[1])
+ self._max=Point2D(max_pt[0],max_pt[1])
+
+ def_get_edge_type(self,edge_type):
+"""Get all of the edges of a certain type in this mesh."""
+ ifself._edgesisNone:
+ self.edges
+ sel_edges=[]
+ fori,typeinenumerate(self._edge_types):
+ iftype==edge_type:
+ sel_edges.append(self._edges[i])
+ returntuple(sel_edges)
+
+ def_face_area(self,face):
+"""Return the area of a face."""
+ returnMesh2D._get_area(tuple(self._vertices[i]foriinface))
+
+ def_tri_face_centroid(self,face):
+"""Compute the centroid of a triangular face."""
+ returnMesh2D._tri_centroid(tuple(self._vertices[i]foriinface))
+
+ def_quad_face_centroid(self,face):
+"""Compute the centroid of a quadrilateral face."""
+ returnMesh2D._quad_centroid(tuple(self._vertices[i]foriinface))
+
+ def_mesh_transform(self,verts):
+"""Transform mesh in a way that transfers properties and avoids extra checks."""
+ _new_mesh=Mesh2D(verts,self.faces)
+ self._transfer_properties(_new_mesh)
+ return_new_mesh
+
+ def_mesh_scale(self,verts,factor):
+"""Scale mesh in a way that transfers properties and avoids extra checks."""
+ _new_mesh=Mesh2D(verts,self.faces)
+ self._transfer_properties_scale(_new_mesh,factor)
+ return_new_mesh
+
+ def_check_vertices_input(self,vertices):
+ ifnotisinstance(vertices,tuple):
+ vertices=tuple(vertices)
+ forvertinvertices:
+ assertisinstance(vert,Point2D), \
+ 'Expected Point2D for {} vertex. Got {}.'.format(
+ self.__class__.__name__,type(vert))
+ returnvertices
+
+ @staticmethod
+ def_ear_clipping_triangulation(polygon,holes=None):
+"""Triangulate a polygon and holes using the ear clipping method."""
+ # flatten the list of vertices and holes into a single list for earcut
+ vert_coords,hole_indices=[],None
+ forptinpolygon:
+ vert_coords.extend((pt.x,pt.y))
+ ifholesisnotNone:
+ hole_indices=[]
+ forholeinholes:
+ hole_indices.append(int(len(vert_coords)/2))
+ forptinhole:
+ vert_coords.extend((pt.x,pt.y))
+
+ # run the ear clipping triangulation
+ result_tri=earcut(vert_coords,hole_indices)
+ vertices=tuple(Point2D(*vert_coords[st:st+2])
+ forstinrange(0,len(vert_coords),2))
+ faces=tuple(tuple(result_tri[st:st+3])
+ forstinrange(0,len(result_tri),3))
+ returnvertices,faces
+
+ @staticmethod
+ def_quad_to_triangles(verts):
+"""Return two triangles that represent any quadrilateral."""
+ # check if the quad is convex
+ convex=True
+ pt1,pt2,pt3=verts[1],verts[2],verts[3]
+ start_val=Trueif(pt2.x-pt1.x)*(pt3.y-pt2.y)- \
+ (pt2.y-pt1.y)*(pt3.x-pt2.x)>0elseFalse
+ fori,pt3inenumerate(verts[:3]):
+ pt1=verts[i-2]
+ pt2=verts[i-1]
+ val=Trueif(pt2.x-pt1.x)*(pt3.y-pt2.y)- \
+ (pt2.y-pt1.y)*(pt3.x-pt2.x)>0elseFalse
+ ifvalisnotstart_val:
+ convex=False
+ break
+ ifconvexisTrue:
+ # if the quad is convex, either diagonal splits it into triangles
+ return[(0,1,2),(2,3,0)]
+ else:
+ # if it is concave, we need to select the right diagonal of the two
+ returnMesh2D._concave_quad_to_triangles(verts)
+
+ @staticmethod
+ def_concave_quad_to_triangles(verts):
+"""Return two triangles that represent a concave quadrilateral."""
+ quad_poly=Polygon2D(verts)
+ diagonal=LineSegment2D.from_end_points(quad_poly[0],quad_poly[2])
+ ifquad_poly.is_point_inside(diagonal.midpoint,Vector2D(1,0.00001)):
+ # if the diagonal midpoint is inside the quad, it splits it into two ears
+ return[(0,1,2),(2,3,0)]
+ else:
+ # if not, then the other diagonal splits it into two ears
+ return[(1,2,3),(3,0,1)]
+
+ @staticmethod
+ def_face_center(verts):
+"""Get the center of a list of Point3D vertices."""
+ _cent_x=sum([v.xforvinverts])
+ _cent_y=sum([v.yforvinverts])
+ v_count=len(verts)
+ returnPoint2D(_cent_x/v_count,_cent_y/v_count)
+
+ @staticmethod
+ def_quad_centroid(verts):
+"""Get the centroid of a list of 4 Point2D vertices."""
+ _tri_i=Mesh2D._quad_to_triangles(verts)
+ _tri_verts=([verts[i]foriin_tri_i[0]],[verts[i]foriin_tri_i[1]])
+ _tri_c=[Mesh2D._tri_centroid(tri)fortriin_tri_verts]
+ _tri_a=[Mesh2D._get_area(tri)fortriin_tri_verts]
+ _tot_a=sum(_tri_a)
+ _cent_x=(_tri_c[0].x*_tri_a[0]+_tri_c[1].x*_tri_a[1])/_tot_a
+ _cent_y=(_tri_c[0].y*_tri_a[0]+_tri_c[1].y*_tri_a[1])/_tot_a
+ returnPoint2D(_cent_x,_cent_y)
+
+ @staticmethod
+ def_tri_centroid(verts):
+"""Get the centroid of a list of 3 Point2D vertices."""
+ _cent_x=sum([v.xforvinverts])
+ _cent_y=sum([v.yforvinverts])
+ returnPoint2D(_cent_x/3,_cent_y/3)
+
+ @staticmethod
+ def_get_area(verts):
+"""Return the area of a list of Point2D vertices."""
+ _a=0
+ fori,ptinenumerate(verts):
+ _a+=verts[i-1].x*pt.y-verts[i-1].y*pt.x
+ returnabs(_a/2)
+
+ @staticmethod
+ def_domain_dimensions(_dom,_dim):
+"""Get corrected dimensions and number of cells over a domain."""
+ _num=int(_dom/_dim)
+ _num=1if_num==0else_num
+ _dim=_dom/_num
+ return_dim,_num
+
+ @staticmethod
+ def_grid_vertices(base_point,num_x,num_y,x_dim,y_dim):
+"""Generate Point2D vertices for a grid."""
+ _verts=[]
+ _x=base_point.x
+ foriinxrange(num_x+1):
+ _y=base_point.y
+ forjinxrange(num_y+1):
+ _verts.append(Point2D(_x,_y))
+ _y+=y_dim
+ _x+=x_dim
+ return_verts
+
+ @staticmethod
+ def_grid_faces(num_x,num_y):
+"""Generate face tuples for a grid."""
+ _faces=[]
+ _c=0
+ foriinxrange(num_x):
+ forjinxrange(num_y):
+ _faces.append((_c,_c+num_y+1,_c+num_y+2,_c+1))
+ _c+=1
+ _c+=1
+ return_faces
+
+ @staticmethod
+ def_grid_centroids(base_point,num_x,num_y,x_dim,y_dim):
+"""Generate Point2D centroids for a grid."""
+ _centroids=[]
+ _x_half=x_dim/2
+ _y_half=y_dim/2
+ _x=base_point.x
+ foriinxrange(num_x):
+ _y=base_point.y
+ forjinxrange(num_y):
+ _centroids.append(Point2D(_x+_x_half,_y+_y_half))
+ _y+=y_dim
+ _x+=x_dim
+ returntuple(_centroids)
+
+ def__copy__(self):
+ _new_mesh=Mesh2D(self.vertices,self.faces)
+ self._transfer_properties(_new_mesh)
+ _new_mesh._face_centroids=self._face_centroids
+ _new_mesh._centroid=self._centroid
+ return_new_mesh
+
+ def__key(self):
+"""A tuple based on the object properties, useful for hashing."""
+ returntuple(hash(pt)forptinself._vertices)+ \
+ tuple(hash(face)forfaceinself._faces)
+
+ def__hash__(self):
+ returnhash(self.__key())
+
+ def__eq__(self,other):
+ returnisinstance(other,Mesh2D)andself.__key()==other.__key()
+
+ def__repr__(self):
+ return'Ladybug Mesh2D ({} faces) ({} vertices)'.format(
+ len(self.faces),len(self))
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/_modules/ladybug_geometry/geometry2d/pointvector.html b/docs/_modules/ladybug_geometry/geometry2d/pointvector.html
new file mode 100644
index 00000000..9a63ac77
--- /dev/null
+++ b/docs/_modules/ladybug_geometry/geometry2d/pointvector.html
@@ -0,0 +1,1710 @@
+
+
+
+
+
+
+ ladybug_geometry.geometry2d.pointvector — ladybug geometry documentation
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+[docs]
+classVector2D(object):
+"""2D Vector object.
+
+ Args:
+ x: Number for the X coordinate.
+ y: Number for the Y coordinate.
+
+ Properties:
+ * x
+ * y
+ * magnitude
+ * magnitude_squared
+ * is_zero
+ """
+ __slots__=('_x','_y')
+
+ def__init__(self,x=0,y=0):
+"""Initialize 2D Vector."""
+ self._x=self._cast_to_float(x)
+ self._y=self._cast_to_float(y)
+
+
+[docs]
+ @classmethod
+ deffrom_dict(cls,data):
+"""Create a Vector2D/Point2D from a dictionary.
+
+ Args:
+ data: A python dictionary in the following format
+
+ .. code-block:: python
+
+ {
+ "x": 10,
+ "y": 0
+ }
+ """
+ returncls(data['x'],data['y'])
+
+
+
+[docs]
+ @classmethod
+ deffrom_array(cls,array):
+"""Initialize a Vector2D/Point2D from an array.
+
+ Args:
+ array: A tuple or list with two numbers representing the x and y
+ values of the point.
+ """
+ returncls(array[0],array[1])
+
+
+
+[docs]
+ defto_array(self):
+"""Get Vector2D/Point2D as a tuple of two numbers"""
+ return(self.x,self.y)
+
+
+ @property
+ defx(self):
+"""Get the X coordinate."""
+ returnself._x
+
+ @property
+ defy(self):
+"""Get the Y coordinate."""
+ returnself._y
+
+ @property
+ defmagnitude(self):
+"""Get the magnitude of the vector."""
+ returnself.__abs__()
+
+ @property
+ defmagnitude_squared(self):
+"""Get the magnitude squared of the vector."""
+ returnself.x**2+self.y**2
+
+ @property
+ defmin(self):
+"""Always equal to (0, 0).
+
+ This property exists to help with bounding box calculations.
+ """
+ returnPoint2D(0,0)
+
+ @property
+ defmax(self):
+"""Always equal to (0, 0).
+
+ This property exists to help with bounding box calculations.
+ """
+ returnPoint2D(0,0)
+
+
+[docs]
+ defis_zero(self,tolerance):
+"""Boolean to note whether the vector is within a given zero tolerance.
+
+ Args:
+ tolerance: The tolerance below which the vector is considered to
+ be a zero vector.
+ """
+ returnabs(self.x)<=toleranceandabs(self.y)<=tolerance
+
+
+
+[docs]
+ defis_equivalent(self,other,tolerance):
+"""Test whether this object is equivalent to another within a certain tolerance.
+
+ Note that if you want to test whether the coordinate values are perfectly
+ equal to one another, the == operator can be used.
+
+ Args:
+ other: Another Point2D for which geometric equivalency will be tested.
+ tolerance: The minimum difference between the coordinate values of two
+ objects at which they can be considered geometrically equivalent.
+ Returns:
+ True if equivalent. False if not equivalent.
+ """
+ returnabs(self.x-other.x)<=toleranceand \
+ abs(self.y-other.y)<=tolerance
+
+
+
+[docs]
+ defnormalize(self):
+"""Get a copy of the vector that is a unit vector (magnitude=1)."""
+ d=self.magnitude
+ try:
+ returnVector2D(self.x/d,self.y/d)
+ exceptZeroDivisionError:
+ returnself.duplicate()
+
+
+
+[docs]
+ defreverse(self):
+"""Get a copy of this vector that is reversed."""
+ returnself.__neg__()
+
+
+
+[docs]
+ defdot(self,other):
+"""Get the dot product of this vector with another."""
+ returnself.x*other.x+self.y*other.y
+
+
+
+[docs]
+ defdeterminant(self,other):
+"""Get the determinant between this vector and another 2D vector."""
+ returnself.x*other.y-self.y*other.x
+
+
+
+[docs]
+ defcross(self):
+"""Get the cross product of this vector."""
+ returnVector2D(self.y,-self.x)
+
+
+
+[docs]
+ defangle(self,other):
+"""Get the smallest angle between this vector and another."""
+ try:
+ returnmath.acos(self.dot(other)/(self.magnitude*other.magnitude))
+ exceptValueError:# python floating tolerance can cause math domain error
+ ifself.dot(other)<0:
+ returnmath.acos(-1)
+ returnmath.acos(1)
+
+
+
+[docs]
+ defangle_counterclockwise(self,other):
+"""Get the counterclockwise angle between this vector and another."""
+ inner=self.angle(other)
+ det=self.determinant(other)
+ ifdet>=0:
+ returninner# if the det > 0 then self is immediately clockwise of other
+ else:
+ return2*math.pi-inner# if the det < 0 then other is clockwise of self
+
+
+
+[docs]
+ defangle_clockwise(self,other):
+"""Get the clockwise angle between this vector and another."""
+ inner=self.angle(other)
+ det=self.determinant(other)
+ ifdet<=0:
+ returninner# if the det > 0 then self is immediately clockwise of other
+ else:
+ return2*math.pi-inner# if the det < 0 then other is clockwise of self
+
+
+
+[docs]
+ defrotate(self,angle):
+"""Get a vector that is rotated counterclockwise by a certain angle.
+
+ Args:
+ angle: An angle for rotation in radians.
+ """
+ returnVector2D._rotate(self,angle)
+
+
+
+[docs]
+ defreflect(self,normal):
+"""Get a vector that is reflected across a plane with the input normal vector.
+
+ Args:
+ normal: A Vector2D representing the normal vector for the plane across
+ which the vector will be reflected. THIS VECTOR MUST BE NORMALIZED.
+ """
+ returnVector2D._reflect(self,normal)
+
+
+
+[docs]
+ defduplicate(self):
+"""Get a copy of this vector."""
+ returnself.__copy__()
+
+
+
+[docs]
+ defto_dict(self):
+"""Get Vector2D as a dictionary."""
+ return{'type':'Vector2D',
+ 'x':self.x,
+ 'y':self.y}
+
+
+
+[docs]
+ @staticmethod
+ defcircular_mean(angles):
+"""Compute the circular mean across a list of angles in radians.
+
+ If no circular mean exists, the normal mean will be returned.
+
+ Args:
+ angles: A list of angles in radians.
+ """
+ avg_x=sum(math.cos(ang)foranginangles)/len(angles)
+ avg_y=sum(math.sin(ang)foranginangles)/len(angles)
+ if(avg_x,avg_y)==(0,0):# just return the normal mean
+ returnsum(angles)/len(angles)
+ returnmath.atan2(avg_y,avg_x)
+[docs]
+classPoint2D(Vector2D):
+"""2D Point object.
+
+ Args:
+ x: Number for the X coordinate.
+ y: Number for the Y coordinate.
+
+ Properties:
+ * x
+ * y
+ """
+ __slots__=()
+
+ @property
+ defmin(self):
+"""Always equal to the point itself.
+
+ This property exists to help with bounding box calculations.
+ """
+ returnself
+
+ @property
+ defmax(self):
+"""Always equal to the point itself.
+
+ This property exists to help with bounding box calculations.
+ """
+ returnself
+
+
+[docs]
+ defmove(self,moving_vec):
+"""Get a point that has been moved along a vector.
+
+ Args:
+ moving_vec: A Vector2D with the direction and distance to move the point.
+ """
+ returnPoint2D(self.x+moving_vec.x,self.y+moving_vec.y)
+
+
+
+[docs]
+ defrotate(self,angle,origin):
+"""Rotate a point counterclockwise by a certain angle around an origin.
+
+ Args:
+ angle: An angle for rotation in radians.
+ origin: A Point2D for the origin around which the point will be rotated.
+ """
+ returnVector2D._rotate(self-origin,angle)+origin
+
+
+
+[docs]
+ defreflect(self,normal,origin):
+"""Get a point reflected across a plane with the input normal vector and origin.
+
+ Args:
+ normal: A Vector2D representing the normal vector for the plane across
+ which the point will be reflected. THIS VECTOR MUST BE NORMALIZED.
+ origin: A Point2D representing the origin from which to reflect.
+ """
+ returnVector2D._reflect(self-origin,normal)+origin
+
+
+
+[docs]
+ defscale(self,factor,origin=None):
+"""Scale a point by a factor from an origin point.
+
+ Args:
+ factor: A number representing how much the point should be scaled.
+ origin: A Point2D representing the origin from which to scale.
+ If None, it will be scaled from the World origin (0, 0).
+ """
+ iforiginisNone:
+ returnPoint2D(self.x*factor,self.y*factor)
+ else:
+ return(factor*(self-origin))+origin
+
+
+
+[docs]
+ defdistance_to_point(self,point):
+"""Get the distance from this point to another Point2D."""
+ vec=(self.x-point.x,self.y-point.y)
+ returnmath.sqrt(vec[0]**2+vec[1]**2)
+
+
+
+[docs]
+ defto_dict(self):
+"""Get Point2D as a dictionary."""
+ return{'type':'Point2D',
+ 'x':self.x,
+ 'y':self.y}
+
+
+ def__add__(self,other):
+ # Point + Vector -> Point
+ # Point + Point -> Vector
+ ifisinstance(other,Point2D):
+ returnVector2D(self.x+other.x,self.y+other.y)
+ elifisinstance(other,Vector2D):
+ returnPoint2D(self.x+other.x,self.y+other.y)
+ else:
+ raiseTypeError('Cannot add Point2D and {}'.format(type(other)))
+
+ def__sub__(self,other):
+ # Point - Vector -> Point
+ # Point - Point -> Vector
+ ifisinstance(other,Point2D):
+ returnVector2D(self.x-other.x,self.y-other.y)
+ elifisinstance(other,Vector2D):
+ returnPoint2D(self.x-other.x,self.y-other.y)
+ else:
+ raiseTypeError('Cannot subtract Point2D and {}'.format(type(other)))
+
+ def__repr__(self):
+"""Point2D representation."""
+ return'Point2D (%.2f, %.2f)'%(self.x,self.y)
+
+ def__lt__(self,other):
+""" Lesser then inequality method. This is used by certain external
+ data structure libraries to efficiently store and retrieve point data.
+ """
+ ifisinstance(other,Vector2D):
+ returnself.x<other.x
+
+ def__gt__(self,other):
+""" Greater then inequality method. This is used by certain external
+ data structure libraries to efficiently store and retrieve point data.
+ """
+ ifisinstance(other,Vector2D):
+ returnself.x>other.x
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/_modules/ladybug_geometry/geometry2d/polygon.html b/docs/_modules/ladybug_geometry/geometry2d/polygon.html
new file mode 100644
index 00000000..b6bbcb1c
--- /dev/null
+++ b/docs/_modules/ladybug_geometry/geometry2d/polygon.html
@@ -0,0 +1,4074 @@
+
+
+
+
+
+
+ ladybug_geometry.geometry2d.polygon — ladybug geometry documentation
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+[docs]
+classPolygon2D(Base2DIn2D):
+"""2D polygon object.
+
+ Args:
+ vertices: A list of Point2D objects representing the vertices of the polygon.
+
+ Properties:
+ * vertices
+ * segments
+ * inside_angles
+ * outside_angles
+ * min
+ * max
+ * center
+ * perimeter
+ * area
+ * is_clockwise
+ * is_convex
+ * is_self_intersecting
+ * self_intersection_points
+ * is_valid
+ """
+ __slots__=('_segments','_inside_angles','_outside_angles','_perimeter','_area',
+ '_is_clockwise','_is_convex','_is_self_intersecting')
+
+ def__init__(self,vertices):
+"""Initialize Polygon2D."""
+ Base2DIn2D.__init__(self,vertices)
+ self._segments=None
+ self._perimeter=None
+ self._inside_angles=None
+ self._outside_angles=None
+ self._area=None
+ self._is_clockwise=None
+ self._is_convex=None
+ self._is_self_intersecting=None
+
+
+[docs]
+ @classmethod
+ deffrom_dict(cls,data):
+"""Create a Polygon2D from a dictionary.
+
+ Args:
+ data: A python dictionary in the following format
+
+ .. code-block:: python
+
+ {
+ "type": "Polygon2D",
+ "vertices": [(0, 0), (10, 0), (0, 10)]
+ }
+ """
+ returncls(tuple(Point2D.from_array(pt)forptindata['vertices']))
+
+
+
+[docs]
+ @classmethod
+ deffrom_array(cls,point_array):
+"""Create a Polygon2D from a nested array of vertex coordinates.
+
+ Args:
+ point_array: nested array of point arrays.
+ """
+ returnPolygon2D(Point2D(*point)forpointinpoint_array)
+
+
+
+[docs]
+ @classmethod
+ deffrom_rectangle(cls,base_point,height_vector,base,height):
+"""Initialize Polygon2D from rectangle parameters.
+
+ Initializing a polygon this way has the added benefit of having its properties
+ quickly computed.
+
+ Args:
+ base_point: A Point2D for the lower left vertex of the polygon.
+ height_vector: A vector denoting the direction of the rectangle height.
+ base: A number indicating the length of the base of the rectangle.
+ height: A number indicating the length of the height of the rectangle.
+ """
+ assertisinstance(base_point,Point2D), \
+ 'base_point must be Point2D. Got {}.'.format(type(base_point))
+ assertisinstance(height_vector,Vector2D), \
+ 'height_vector must be Vector2D. Got {}.'.format(type(height_vector))
+ assertisinstance(base,(float,int)),'base must be a number.'
+ assertisinstance(height,(float,int)),'height must be a number.'
+ _hv_norm=height_vector.normalize()
+ _bv=Vector2D(_hv_norm.y,-_hv_norm.x)*base
+ _hv=_hv_norm*height
+ _verts=(base_point,base_point+_bv,base_point+_hv+_bv,base_point+_hv)
+ polygon=cls(_verts)
+ polygon._perimeter=base*2+height*2
+ polygon._area=base*height
+ polygon._is_clockwise=False
+ polygon._is_convex=True
+ polygon._is_self_intersecting=False
+ returnpolygon
+
+
+
+[docs]
+ @classmethod
+ deffrom_regular_polygon(cls,number_of_sides,radius=1,base_point=Point2D()):
+"""Initialize Polygon2D from regular polygon parameters.
+
+ Args:
+ number_of_sides: An integer for the number of sides on the regular
+ polygon. This number must be greater than 2.
+ radius: A number indicating the distance from the polygon's center
+ where the vertices of the polygon will lie.
+ The default is set to 1.
+ base_point: A Point2D for the center of the regular polygon.
+ The default is the Origin at (0, 0).
+ """
+ assertisinstance(number_of_sides,int),'number_of_sides must be an ' \
+ 'integer. Got {}.'.format(type(number_of_sides))
+ assertnumber_of_sides>2,'number_of_sides must be greater than 2. ' \
+ 'Got {}.'.format(number_of_sides)
+ assertisinstance(base_point,Point2D), \
+ 'base_point must be Point2D. Got {}.'.format(type(base_point))
+ assertisinstance(radius,(float,int)),'height must be a number.'
+
+ # calculate angle at which each vertex is rotated from the previous one
+ angle=(math.pi*2)/number_of_sides
+ cos_a=math.cos(angle)
+ sin_a=math.sin(angle)
+
+ # pick a starting vertex that makes sense for the number of sides
+ ifnumber_of_sides%2==0:
+ start_vert=Point2D(base_point.x-radius,base_point.y)
+ start_vert=start_vert.rotate(angle/2,base_point)
+ else:
+ start_vert=Point2D(base_point.x,base_point.y+radius)
+ _vertices=[start_vert]
+
+ # generate the vertices
+ foriinrange(number_of_sides-1):
+ last_pt=_vertices[-1]
+ qx=cos_a*(last_pt.x-base_point.x)-sin_a*(last_pt.y-base_point.y)
+ qy=sin_a*(last_pt.x-base_point.x)+cos_a*(last_pt.y-base_point.y)
+ _vertices.append(Point2D(qx+base_point.x,qy+base_point.y))
+
+ # build the new polygon and set the properties that we know.
+ _new_poly=cls(_vertices)
+ _new_poly._is_clockwise=False
+ _new_poly._is_convex=True
+ _new_poly._is_self_intersecting=False
+ return_new_poly
+
+
+
+[docs]
+ @classmethod
+ deffrom_shape_with_hole(cls,boundary,hole):
+"""Initialize a Polygon2D from a boundary shape with a hole inside of it.
+
+ This method will convert the shape into a single concave polygon by drawing
+ a line from the hole to the outer boundary.
+
+ Args:
+ boundary: A list of Point2D objects for the outer boundary of the polygon
+ inside of which the hole is contained.
+ hole: A list of Point2D objects for the hole.
+ """
+ # check that the inputs are in the correct format
+ assertisinstance(boundary,list), \
+ 'boundary should be a list. Got {}'.format(type(boundary))
+ assertisinstance(hole,list), \
+ 'hole should be a list. Got {}'.format(type(hole))
+
+ # check that the direction of vertices for the hole is opposite the boundary
+ bound_direction=Polygon2D._are_clockwise(boundary)
+ ifcls._are_clockwise(hole)isbound_direction:
+ hole.reverse()
+
+ # join the hole with the boundary at the closest point
+ dist_dict={}
+ fori,b_ptinenumerate(boundary):
+ forj,h_ptinenumerate(hole):
+ dist_dict[b_pt.distance_to_point(h_pt)]=(i,j)
+ boundary=cls._merge_boundary_and_hole(boundary,hole,dist_dict)
+
+ # return the polygon with some properties set based on what we know
+ _new_poly=cls(boundary)
+ _new_poly._is_clockwise=bound_direction
+ _new_poly._is_convex=False
+ return_new_poly
+
+
+
+[docs]
+ @classmethod
+ deffrom_shape_with_holes(cls,boundary,holes):
+"""Initialize a Polygon2D from a boundary shape with holes inside of it.
+
+ This method will convert the shape into a single concave polygon by drawing
+ lines from the holes to the outer boundary.
+
+ Args:
+ boundary: A list of Point2D objects for the outer boundary of the polygon
+ inside of which all of the holes are contained.
+ holes: A list of lists with one list for each hole in the shape. Each hole
+ should be a list of at least 3 Point2D objects.
+ """
+ # check that the inputs are in the correct format.
+ assertisinstance(boundary,list), \
+ 'boundary should be a list. Got {}'.format(type(boundary))
+ assertisinstance(holes,list), \
+ 'holes should be a list. Got {}'.format(type(holes))
+ forholeinholes:
+ assertisinstance(hole,list), \
+ 'hole should be a list. Got {}'.format(type(hole))
+ assertlen(hole)>=3, \
+ 'hole should have at least 3 vertices. Got {}'.format(len(hole))
+
+ # check that the direction of vertices for the hole is opposite the boundary
+ bound_direction=cls._are_clockwise(boundary)
+ forholeinholes:
+ ifcls._are_clockwise(hole)isbound_direction:
+ hole.reverse()
+
+ # recursively add the nearest hole to the boundary until there are none left.
+ boundary=cls._merge_boundary_and_holes(boundary,holes)
+
+ # return the polygon with some properties set based on what we know
+ _new_poly=cls(boundary)
+ _new_poly._is_clockwise=bound_direction
+ _new_poly._is_convex=False
+ return_new_poly
+
+
+
+[docs]
+ @classmethod
+ deffrom_shape_with_holes_fast(cls,boundary,holes):
+"""Initialize a Polygon2D from a boundary shape with holes using a fast method.
+
+ This method is similar in principle to the from_shape_with_holes method
+ but it uses David Eberly's algorithm for finding a bridge between the holes
+ and outer polygon. This is extremely fast in comparison to the methods used
+ by from_shape_with_holes but is not always the prettiest or the shortest
+ pathway through the holes. Granted, it is very practical for shapes with
+ lots of holes (eg. 100 holes) and will run in a fraction of the time for
+ this case.
+
+ Args:
+ boundary: A list of Point2D objects for the outer boundary of the polygon
+ inside of which all of the holes are contained.
+ holes: A list of lists with one list for each hole in the shape. Each hole
+ should be a list of at least 3 Point2D objects.
+ """
+ # check the initial direction of the boundary vertices
+ bound_direction=cls._are_clockwise(boundary)
+ # format the coordinates for input to the earcut methods
+ vert_coords,hole_indices=[],None
+ forptinboundary:
+ vert_coords.append(pt.x)
+ vert_coords.append(pt.y)
+ hole_indices=[]
+ forholeinholes:
+ hole_indices.append(int(len(vert_coords)/2))
+ forptinhole:
+ vert_coords.append(pt.x)
+ vert_coords.append(pt.y)
+
+ # eliminate the holes within the list
+ outer_len=hole_indices[0]*2
+ outer_node=_linked_list(vert_coords,0,outer_len,2,True)
+ outer_node=_eliminate_holes(vert_coords,hole_indices,outer_node,2)
+
+ # loop through the chain of nodes and translate them to Point2D
+ start_i=outer_node.i
+ vertices=[Point2D(outer_node.x,outer_node.y)]
+ node=outer_node.next
+ node_counter,orig_start_i=0,0
+ whilenode.i!=start_i:
+ vertices.append(Point2D(node.x,node.y))
+ node_counter+=1
+ ifnode.i==0:
+ orig_start_i=node_counter
+ node=node.next
+
+ # ensure that the starting vertex is the same as the input boundary
+ vertices=vertices[orig_start_i:]+vertices[:orig_start_i]
+ vertices[0]=boundary[0]# this avoids issues of floating point tolerance
+
+ # return the polygon with some properties set based on what we know
+ _new_poly=cls(vertices)
+ _new_poly._is_clockwise=bound_direction
+ _new_poly._is_convex=False
+ _new_poly._is_self_intersecting=False
+ return_new_poly
+
+
+ @property
+ defvertices(self):
+"""Tuple of all vertices in this geometry."""
+ returnself._vertices
+
+ @property
+ defsegments(self):
+"""Tuple of all line segments in the polygon."""
+ ifself._segmentsisNone:
+ _segs=self._segments_from_vertices(self.vertices)
+ self._segments=tuple(_segs)
+ returnself._segments
+
+ @property
+ definside_angles(self):
+"""Tuple of angles in radians for the interior angles of the polygon.
+
+ These are aligned with the vertices such that the first angle corresponds
+ to the inside angle at the first vertex, the second at the second vertex,
+ and so on.
+ """
+ ifself._inside_anglesisNone:
+ angles,is_clock=[],self.is_clockwise
+ fori,ptinenumerate(self.vertices):
+ v1=self.vertices[i-2]-self.vertices[i-1]
+ v2=pt-self.vertices[i-1]
+ v_angle=v1.angle_counterclockwise(v2)ifis_clock \
+ elsev1.angle_clockwise(v2)
+ angles.append(v_angle)
+ angles.append(angles.pop(0))# move the start angle to the end
+ self._inside_angles=tuple(angles)
+ returnself._inside_angles
+
+ @property
+ defoutside_angles(self):
+"""Tuple of angles in radians for the exterior angles of the polygon.
+
+ These are aligned with the vertices such that the first angle corresponds
+ to the inside angle at the first vertex, the second at the second vertex,
+ and so on.
+ """
+ ifself._outside_anglesisNone:
+ pi2=math.pi*2
+ self._outside_angles=tuple(pi2-aforainself.inside_angles)
+ returnself._outside_angles
+
+ @property
+ defperimeter(self):
+"""The perimeter of the polygon."""
+ ifself._perimeterisNone:
+ self._perimeter=sum([seg.lengthforseginself.segments])
+ returnself._perimeter
+
+ @property
+ defarea(self):
+"""The area of the polygon."""
+ ifself._areaisNone:
+ _a=0
+ fori,ptinenumerate(self.vertices):
+ _a+=self.vertices[i-1].x*pt.y-self.vertices[i-1].y*pt.x
+ self._area=_a/2
+ returnabs(self._area)
+
+ @property
+ defis_clockwise(self):
+"""Boolean for whether the polygon vertices are in clockwise order."""
+ ifself._is_clockwiseisNone:
+ ifself._areaisNone:
+ self.area
+ self._is_clockwise=self._area<0
+ returnself._is_clockwise
+
+ @property
+ defis_convex(self):
+"""Boolean noting whether the polygon is convex (True) or non-convex (False)."""
+ ifself._is_convexisNone:
+ self._is_convex=True
+ iflen(self.vertices)==3:
+ pass
+ else:
+ _segs=self.segments
+ ifself.is_clockwise:
+ fori,_sinenumerate(_segs):
+ if_segs[i-1].v.determinant(_s.v)>0:# counterclockwise turn
+ self._is_convex=False
+ break
+ else:
+ fori,_sinenumerate(_segs):
+ if_segs[i-1].v.determinant(_s.v)<0:# clockwise turn
+ self._is_convex=False
+ break
+ returnself._is_convex
+
+ @property
+ defis_self_intersecting(self):
+"""Boolean noting whether the polygon has self-intersecting edges.
+
+ Note that this property is relatively computationally intense to obtain compared
+ to properties like area and is_convex. Also, most CAD programs forbid geometry
+ with self-intersecting edges. So it is recommended that this property only
+ be used in quality control scripts where the origin of the geometry is unknown.
+ """
+ ifself._is_self_intersectingisNone:
+ self._is_self_intersecting=False
+ _segs=self.segments
+ fori,_sinenumerate(_segs[1:len(_segs)-1]):
+ _skip=(i,i+1,i+2)
+ _other_segs=[xforj,xinenumerate(_segs)ifjnotin_skip]
+ for_oth_sin_other_segs:
+ if_s.intersect_line_ray(_oth_s)isnotNone:# intersection!
+ self._is_self_intersecting=True
+ break
+ ifself._is_self_intersectingisTrue:
+ break
+ returnself._is_self_intersecting
+
+ @property
+ defself_intersection_points(self):
+"""A tuple of Point2Ds for the locations where the polygon intersects itself.
+
+ This will be an empty tuple if the polygon is not self-intersecting and it
+ is generally recommended that the Polygon2D.is_self_intersecting property
+ be checked before using this property.
+ """
+ ifself.is_self_intersecting:
+ int_pts=[]
+ _segs=self.segments
+ fori,_sinenumerate(_segs[1:len(_segs)-1]):
+ _skip=(i,i+1,i+2)
+ _other_segs=[xforj,xinenumerate(_segs)ifjnotin_skip]
+ for_oth_sin_other_segs:
+ int_pt=_s.intersect_line_ray(_oth_s)
+ ifint_ptisnotNone:# intersection!
+ int_pts.append(int_pt)
+ returntuple(int_pts)
+ return()
+
+ @property
+ defis_valid(self):
+"""Boolean noting whether the polygon is valid (having a non-zero area).
+
+ Note that polygons are still considered valid if they have self-intersecting
+ edges, or duplicate/colinear vertices. The s_self_intersecting property
+ identifies self-intersecting edges, and the remove_colinear_vertices method
+ will remove duplicate/colinear vertices.
+ """
+ returnnotself.area==0
+
+
+[docs]
+ defis_equivalent(self,other,tolerance):
+"""Boolean for equivalence between this polygon and another (within tolerance).
+
+ The order of the polygon vertices do not have to start from the
+ same vertex for equivalence to be true, but must be in the same counterclockwise
+ or clockwise order.
+
+ Args:
+ other: Polygon2D for comparison.
+ tolerance: float representing point equivalence.
+
+ Returns:
+ True if equivalent else False
+ """
+
+ # Check number of points
+ iflen(self.vertices)!=len(other.vertices):
+ returnFalse
+
+ vertices=self.vertices
+
+ # Check order
+ ifnotvertices[0].is_equivalent(other.vertices[0],tolerance):
+ self_idx=None
+ other_pt=other.vertices[0]
+ fori,ptinenumerate(self.vertices):
+ ifpt.is_equivalent(other_pt,tolerance):
+ self_idx=i
+ break
+
+ ifself_idxisNone:
+ returnFalse
+
+ # Re-order polygon vertices to match other
+ vertices=vertices[self_idx:]+vertices[:self_idx]
+
+ is_equivalent=True
+ forpt,other_ptinzip(vertices[1:],other.vertices[1:]):
+ is_equivalent=is_equivalentandpt.is_equivalent(other_pt,tolerance)
+ returnis_equivalent
+
+
+
+[docs]
+ defis_rectangle(self,angle_tolerance):
+"""Test whether this Polygon2D is a rectangle given an angle tolerance.
+
+ Note that this method will return False if the Polygon2D does not have
+ four vertices, even if they are duplicated or colinear.
+
+ Args:
+ angle_tolerance: The max angle in radians that the corners of the
+ rectangle can differ from a right angle before it is not
+ considered a rectangle.
+ """
+ iflen(self.vertices)!=4:
+ returnFalse
+ min_ang=(math.pi/2)-angle_tolerance
+ max_ang=(math.pi/2)+angle_tolerance
+ fori,ptinenumerate(self.vertices):
+ v1=self.vertices[i-2]-self.vertices[i-1]
+ v2=pt-self.vertices[i-1]
+ v_angle=v1.angle(v2)
+ ifv_angle<min_angorv_angle>max_ang:
+ returnFalse
+ returnTrue
+
+
+
+[docs]
+ defrectangular_approximation(self):
+"""Get a rectangular Polygon2D with the same area and aspect ratio as this one.
+
+ This is useful when an interface requires a rectangular input but the
+ user-defined geometry can be any shape. The resulting rectangle will share
+ the same center as this one.
+ """
+ b_rect_len=self.max.x-self.min.x
+ b_rect_hgt=self.max.y-self.min.y
+ aspect_ratio=b_rect_len/b_rect_hgt
+ final_hgt=math.sqrt(self.area/aspect_ratio)
+ final_len=self.area/final_hgt
+ b_pt=Point2D(self.center.x-(final_len/2),self.center.y-(final_hgt/2))
+ returnPolygon2D.from_rectangle(b_pt,Vector2D(0,1),final_len,final_hgt)
+
+
+
+[docs]
+ defpole_of_inaccessibility(self,tolerance):
+"""Get the pole of inaccessibility for the polygon.
+
+ The pole of inaccessibility is the most distant internal point from the
+ polygon outline. It is not to be confused with the centroid, which
+ represents the "center of mass" of the polygon and may be outside of
+ the polygon if the shape is concave. The poly of inaccessibility is
+ useful for optimal placement of a text label on a polygon.
+
+ The algorithm here is a port of the polylabel library from MapBox
+ assembled by Michal Hatak. (https://github.com/Twista/python-polylabel).
+
+ Args:
+ tolerance: The precision to which the pole of inaccessibility
+ will be computed.
+ """
+ # compute the cell size from the bounding rectangle
+ min_x,min_y=self.min.x,self.min.y
+ max_x,max_y=self.max.x,self.max.y
+ width=max_x-min_x
+ height=max_y-min_y
+ cell_size=min(width,height)
+ h=cell_size/2.0
+ max_dim=max(width,height)
+ ifcell_size==0orself.area<max_dim*tolerance:
+ # degenerate polygon; just return the center
+ returnself.center
+
+ # get an array representation of the polygon and set up the priority queue
+ _polygon=tuple(pt.to_array()forptinself.vertices)
+ cell_queue=PriorityQueue()
+
+ # cover polygon with initial cells
+ x=min_x
+ whilex<max_x:
+ y=min_y
+ whiley<max_y:
+ c=_Cell(x+h,y+h,h,_polygon)
+ y+=cell_size
+ cell_queue.put((-c.max,time.time(),c))
+ x+=cell_size
+
+ best_cell=self._get_centroid_cell(_polygon)
+
+ bbox_cell=_Cell(min_x+width/2,min_y+height/2,0,_polygon)
+ ifbbox_cell.d>best_cell.d:
+ best_cell=bbox_cell
+
+ # recursively iterate until we find the pole
+ num_of_probes=cell_queue.qsize()
+ whilenotcell_queue.empty():
+ _,__,cell=cell_queue.get()
+
+ ifcell.d>best_cell.d:
+ best_cell=cell
+
+ ifcell.max-best_cell.d<=tolerance:
+ continue
+
+ h=cell.h/2
+ c=_Cell(cell.x-h,cell.y-h,h,_polygon)
+ cell_queue.put((-c.max,time.time(),c))
+ c=_Cell(cell.x+h,cell.y-h,h,_polygon)
+ cell_queue.put((-c.max,time.time(),c))
+ c=_Cell(cell.x-h,cell.y+h,h,_polygon)
+ cell_queue.put((-c.max,time.time(),c))
+ c=_Cell(cell.x+h,cell.y+h,h,_polygon)
+ cell_queue.put((-c.max,time.time(),c))
+ num_of_probes+=4
+ returnPoint2D(best_cell.x,best_cell.y)
+
+
+
+[docs]
+ defremove_duplicate_vertices(self,tolerance):
+"""Get a version of this polygon without duplicate vertices.
+
+ Args:
+ tolerance: The minimum distance between a two vertices at which
+ they are considered co-located or duplicated.
+ """
+ new_vertices=tuple(
+ ptfori,ptinenumerate(self._vertices)
+ ifnotpt.is_equivalent(self._vertices[i-1],tolerance))
+ returnPolygon2D(new_vertices)
+
+
+
+[docs]
+ defremove_colinear_vertices(self,tolerance):
+"""Get a version of this polygon without colinear or duplicate vertices.
+
+ Args:
+ tolerance: The minimum distance that a vertex can be from a line
+ before it is considered colinear.
+ """
+ new_vertices=[]# list to hold the new vertices
+ skip=0# track the number of vertices being skipped/removed
+ first_skip,is_first,=0,True# track the number skipped from first vertex
+ # loop through vertices and remove all cases of colinear verts
+ fori,_vinenumerate(self.vertices):
+ _v2,_v1=self[i-2-skip],self[i-1]
+ _a=_v2.determinant(_v1)+_v1.determinant(_v)+_v.determinant(_v2)
+ b_dist=_v.distance_to_point(_v2)
+ b_dist=toleranceifb_dist<toleranceelseb_dist
+ tri_tol=(b_dist*tolerance)/2# area of triangle with tolerance height
+ ifabs(_a)>=tri_tol:# triangle area > tolerance; not colinear
+ new_vertices.append(self[i-1])
+ skip=0
+ ifis_first:
+ is_first=False
+ first_skip=i-1
+ else:# colinear point to be removed
+ skip+=1
+ # catch case of last few vertices being equal but distinct from first point
+ ifskip!=0andfirst_skip!=-1:
+ assertabs(-2-skip)<=len(self), \
+ 'There must be at least 3 vertices for a Polygon2D.'
+ _v2,_v1,_v=self[-2-skip],self[-1],self[first_skip]
+ _a=_v2.determinant(_v1)+_v1.determinant(_v)+_v.determinant(_v2)
+ b_dist=_v.distance_to_point(_v2)
+ b_dist=toleranceifb_dist<toleranceelseb_dist
+ tri_tol=(b_dist*tolerance)/2# area of triangle with tolerance height
+ ifabs(_a)>=tri_tol:# triangle area > area tolerance; not colinear
+ new_vertices.append(_v1)
+ returnPolygon2D(new_vertices)
+
+
+
+[docs]
+ defsplit_through_self_intersection(self,tolerance):
+"""Get a list of non-intersecting Polygon2D if this polygon intersects itself.
+
+ If the Polygon2D does not intersect itself, then a list with the current
+ Polygon2D will be returned.
+
+ Args:
+ tolerance: The minimum difference between vertices before they are
+ considered co-located.
+ """
+ # loop over the segments and group the vertices by intersection points
+ intersect_groups=[[]]
+ _segs=self.segments
+ seg_count=len(_segs)
+ fori,_sinenumerate(_segs):
+ # loop over the other segments and find any intersection points
+ ifi==0:
+ _skip=(len(_segs)-1,i,i+1)
+ elifi==seg_count-1:
+ _skip=(i-1,i,0)
+ else:
+ _skip=(i-1,i,i+1)
+ _other_segs=[xforj,xinenumerate(_segs)ifjnotin_skip]
+ int_pts=[]
+ for_oth_sin_other_segs:
+ int_pt=_s.intersect_line_ray(_oth_s)
+ ifint_ptisnotNone:# intersection!
+ int_pts.append(int_pt)
+ # if intersection points were found, adjust the groups accordingly
+ iflen(int_pts)==0:# no self intersection on this segment
+ intersect_groups[-1].append(_s.p2)
+ eliflen(int_pts)==1:# typical self-intersection case we should split
+ intersect_groups[-1].append(int_pts[0])
+ intersect_groups.append([_s.p2])
+ else:# rare case of multiple intersections on the same segment
+ # sort the intersection points along the segment
+ dists=[_s.p1.distance_to_point(ipt)foriptinint_pts]
+ sort_pts=[ptfor_,ptinsorted(zip(dists,int_pts),
+ key=lambdapair:pair[0])]
+ intersect_groups[-1].append(sort_pts[0])
+ fors_ptinsort_pts[1:]:
+ intersect_groups.append([s_pt])
+ intersect_groups.append([_s.p2])
+
+ # process the intersect groups into polygon objects
+ iflen(intersect_groups)==1:
+ return[self]# not a self-intersecting shape
+ split_polygons=[]
+ poly_count=int(len(intersect_groups)/2)
+ iflen(intersect_groups[poly_count])==1:# rare case of start at intersect
+ foriinrange(poly_count):
+ vert_group=[intersect_groups[i],intersect_groups[-i-1]]
+ forverts_listinvert_group:
+ iflen(verts_list)>2:
+ try:
+ clean_poly=Polygon2D(verts_list)
+ clean_poly=clean_poly.remove_duplicate_vertices(tolerance)
+ split_polygons.append(clean_poly)
+ exceptAssertionError:# degenerate polygon that should not be added
+ pass
+ else:# typical case of intersection in the middle
+ foriinrange(poly_count):
+ verts_list=intersect_groups[i]+intersect_groups[-i-1]
+ iflen(verts_list)>2:
+ try:
+ clean_poly=Polygon2D(verts_list)
+ clean_poly=clean_poly.remove_duplicate_vertices(tolerance)
+ split_polygons.append(clean_poly)
+ exceptAssertionError:# degenerate polygon that should not be added
+ pass
+ final_verts=intersect_groups[i+1]
+ try:
+ clean_poly=Polygon2D(final_verts)
+ clean_poly=clean_poly.remove_duplicate_vertices(tolerance)
+ split_polygons.append(clean_poly)
+ exceptAssertionError:# degenerate polygon that should not be added
+ pass
+ returnsplit_polygons
+
+
+
+[docs]
+ defreverse(self):
+"""Get a copy of this polygon where the vertices are reversed."""
+ _new_poly=Polygon2D(tuple(ptforptinreversed(self.vertices)))
+ self._transfer_properties(_new_poly)
+ ifself._is_clockwiseisnotNone:
+ _new_poly._is_clockwise=notself._is_clockwise
+ return_new_poly
+
+
+
+[docs]
+ defmove(self,moving_vec):
+"""Get a polygon that has been moved along a vector.
+
+ Args:
+ moving_vec: A Vector2D with the direction and distance to move the polygon.
+ """
+ _new_poly=Polygon2D(tuple(pt.move(moving_vec)forptinself.vertices))
+ self._transfer_properties(_new_poly)
+ return_new_poly
+
+
+
+[docs]
+ defrotate(self,angle,origin):
+"""Get a polygon that is rotated counterclockwise by a certain angle.
+
+ Args:
+ angle: An angle for rotation in radians.
+ origin: A Point2D for the origin around which the point will be rotated.
+ """
+ _new_poly=Polygon2D(tuple(pt.rotate(angle,origin)forptinself.vertices))
+ self._transfer_properties(_new_poly)
+ return_new_poly
+
+
+
+[docs]
+ defreflect(self,normal,origin):
+"""Get a polygon reflected across a plane with the input normal and origin.
+
+ Args:
+ normal: A Vector2D representing the normal vector for the plane across
+ which the polygon will be reflected. THIS VECTOR MUST BE NORMALIZED.
+ origin: A Point2D representing the origin from which to reflect.
+ """
+ _new_poly=Polygon2D(tuple(pt.reflect(normal,origin)forptinself.vertices))
+ self._transfer_properties(_new_poly)
+ ifself._is_clockwiseisnotNone:
+ _new_poly._is_clockwise=notself._is_clockwise
+ return_new_poly
+
+
+
+[docs]
+ defscale(self,factor,origin=None):
+"""Scale a polygon by a factor from an origin point.
+
+ Args:
+ factor: A number representing how much the polygon should be scaled.
+ origin: A Point2D representing the origin from which to scale.
+ If None, it will be scaled from the World origin (0, 0).
+ """
+ iforiginisNone:
+ returnPolygon2D(tuple(
+ Point2D(pt.x*factor,pt.y*factor)forptinself.vertices))
+ else:
+ returnPolygon2D(tuple(pt.scale(factor,origin)forptinself.vertices))
+
+
+
+[docs]
+ defoffset(self,distance,check_intersection=False):
+"""Offset the polygon by a given distance inwards or outwards.
+
+ Note that the resulting shape may be self-intersecting if the distance
+ is large enough and the is_self_intersecting property may be used to identify
+ these shapes.
+
+ Args:
+ distance: The distance inwards that the polygon will be offset.
+ Positive values will always be offset inwards while negative ones
+ will be offset outwards.
+ check_intersection: A boolean to note whether the resulting operation
+ should be checked for self intersection and, if so, None will be
+ returned instead of the self-intersecting polygon.
+ """
+ # make sure the offset is not zero
+ ifdistance==0:
+ returnself
+
+ # loop through the vertices and get the new offset vectors
+ base_verts=self._verticesifnotself.is_clockwise \
+ elselist(reversed(self._vertices))
+ init_verts=[ptfori,ptinenumerate(base_verts)ifpt!=base_verts[i-1]]
+ iflen(init_verts)<3:# degenerate polygon
+ returnself# cannot be offset into a valid shape
+ move_vecs,max_i=[],len(init_verts)-1
+ fori,ptinenumerate(init_verts):
+ v1=init_verts[i-1]-pt
+ end_i=i+1ifi!=max_ielse0
+ v2=init_verts[end_i]-pt
+ ifnotself.is_clockwise:
+ ang=v1.angle_clockwise(v2)/2
+ ifang==0:
+ ang=math.pi/2
+ m_vec=v1.rotate(-ang).normalize()
+ m_dist=distance/math.sin(ang)
+ else:
+ ang=v1.angle_counterclockwise(v2)/2
+ ifang==0:
+ ang=math.pi/2
+ m_vec=v1.rotate(ang).normalize()
+ m_dist=-distance/math.sin(ang)
+ m_vec=m_vec*m_dist
+ move_vecs.append(m_vec)
+
+ # move the vertices by the offset to create the new Polygon2D
+ new_pts=tuple(pt.move(m_vec)forpt,m_vecinzip(init_verts,move_vecs))
+ ifself.is_clockwise:
+ new_pts=tuple(reversed(new_pts))
+ new_poly=Polygon2D(new_pts)
+
+ # check for self intersection between the moving vectors if requested
+ ifcheck_intersection:
+ poly_segs=new_poly.segmentsifnotself.is_clockwiseelse \
+ Polygon2D(tuple(reversed(new_pts))).segments
+ _segs=[LineSegment2D(p,v)forp,vinzip(init_verts,move_vecs)]
+ _skip=(0,len(_segs)-1)
+ _other_segs=[xforj,xinenumerate(poly_segs)ifjnotin_skip]
+ for_oth_sin_other_segs:
+ if_segs[0].intersect_line_ray(_oth_s)isnotNone:# intersection!
+ returnNone
+ fori,_sinenumerate(_segs[1:]):
+ _skip=(i,i+1)
+ _other_segs=[xforj,xinenumerate(poly_segs)ifjnotin_skip]
+ for_oth_sin_other_segs:
+ if_s.intersect_line_ray(_oth_s)isnotNone:# intersection!
+ returnNone
+ returnnew_poly
+
+
+
+[docs]
+ defintersect_line_ray(self,line_ray):
+"""Get the intersections between this polygon and a Ray2D or LineSegment2D.
+
+ Args:
+ line_ray: A LineSegment2D or Ray2D or to intersect.
+
+ Returns:
+ A list with Point2D objects for the intersections.
+ List will be empty if no intersection exists.
+ """
+ intersections=[]
+ for_sinself.segments:
+ inters=intersect_line2d(_s,line_ray)
+ ifintersisnotNone:
+ intersections.append(inters)
+ returnintersections
+
+
+
+[docs]
+ defintersect_line_infinite(self,ray):
+"""Get the intersections between this polygon and a Ray2D extended infinitely.
+
+ Args:
+ ray: A Ray2D or to intersect. This will be extended in both
+ directions infinitely for the intersection.
+
+ Returns:
+ A list with Point2D objects for the intersections.
+ List will be empty if no intersection exists.
+ """
+ intersections=[]
+ for_sinself.segments:
+ inters=intersect_line2d_infinite(_s,ray)
+ ifintersisnotNone:
+ intersections.append(inters)
+ returnintersections
+
+
+
+[docs]
+ defpoint_relationship(self,point,tolerance):
+"""Test whether a Point2D lies inside, outside or on the boundary of the polygon.
+
+ Compared to other methods like is_point_inside this method is slow. However,
+ it covers all edge cases, including the literal edge of the polygon.
+
+ Args:
+ point: A Point2D for which the relationship to the polygon will be tested.
+ tolerance: The minimum distance from the edge at which a point is
+ considered to lie on the edge.
+
+ Returns:
+ An integer denoting the relationship of the point.
+
+ This will be one of the following:
+
+ * -1 = Outside polygon
+ * 0 = On the edge of the polygon
+ * +1 = Inside polygon
+ """
+ ifself.is_point_on_edge(point,tolerance):
+ return0
+ ifself.is_point_inside_bound_rect(point):
+ return1
+ return-1
+
+
+
+[docs]
+ defis_point_on_edge(self,point,tolerance):
+"""Test whether a Point2D lies on the boundary edges of the polygon.
+
+ Args:
+ point: A Point2D for which the edge relationship will be tested.
+ tolerance: The minimum distance from the edge at which a point is
+ considered to lie on the edge.
+
+ Returns:
+ A boolean denoting whether the point lies on the polygon edges (True)
+ or not on the edges (False).
+ """
+ for_sinself.segments:
+ close_pt=closest_point2d_on_line2d(point,_s)
+ ifpoint.distance_to_point(close_pt)<=tolerance:
+ returnTrue
+ returnFalse
+
+
+
+[docs]
+ defis_point_inside_check(self,point):
+"""Test whether a Point2D lies inside the polygon with checks for fringe cases.
+
+ This method uses the same calculation as the the `is_point_inside` method
+ but it includes additional checks for the fringe cases noted in the
+ `is_point_inside` description. Using this method means that it will always
+ yield the right result for all convex polygons and concave polygons with
+ one concave turn (provided that they do not have colinear vertices).
+ This is suitable for nearly all practical purposes and the only cases
+ that could yield an incorrect result are when a point is co-linear with
+ two or more polygon edges along the X vector like so:
+
+ .. code-block:: shell
+
+ _____ _____ _____
+ | . |___| |___| |
+ |_________________________|
+
+ While this method covers most fringe cases, it will not test for whether
+ a point lies perfectly on the edge of the polygon so it assesses whether
+ a point lies inside the polygon up to Python floating point tolerance
+ (16 digits). If distinguishing edge conditions from inside/ outside is
+ important, the `point_relationship` method should be used.
+
+ Args:
+ point: A Point2D for which the inside/ outside relationship will be tested.
+ Returns:
+ A boolean denoting whether the point lies inside (True) or outside (False).
+ """
+ defnon_duplicate_intersect(test_ray):
+ inters=[]
+ n_int=0
+ for_sinself.segments:
+ inter=intersect_line2d(_s,test_ray)
+ ifinterisnotNone:
+ try:
+ ifinter!=inters[-1]:# ensure intersection is not duplicated
+ n_int+=1
+ inters.append(inter)
+ exceptIndexError:
+ n_int+=1
+ inters.append(inter)
+ returnn_int,inters
+
+ n_int,inters=non_duplicate_intersect(Ray2D(point,Vector2D(1,0)))
+ # check that intersections do not form a polygon segment co-linear with test_ray
+ ifself.is_convexisFalseandn_int==2:
+ for_sinself.segments:
+ if_s.p1==inters[0]and_s.p2==inters[1]:
+ returnself.is_point_inside(point,Vector2D(0,1))
+ ifn_int%2==0:
+ returnFalse
+
+ n_int,inters=non_duplicate_intersect(Ray2D(point,Vector2D(0,1)))
+ # check that intersections do not form a polygon segment co-linear with test_ray
+ ifself.is_convexisFalseandn_int==2:
+ for_sinself.segments:
+ if_s.p1==inters[0]and_s.p2==inters[1]:
+ returnself.is_point_inside(point,Vector2D(1,0))
+ ifn_int%2==0:
+ returnFalse
+ returnTrue
+
+
+
+[docs]
+ defis_point_inside(self,point,test_vector=Vector2D(1,0.00001)):
+"""Test whether a Point2D lies inside or outside the polygon.
+
+ This method is the fastest way to tell if a point is inside a polygon when
+ the given point lies inside the boundary rectangle of the polygon.
+ However, while this method gives the correct result in 99.9% of cases,
+ there are a few fringe cases where it will not give the correct result.
+ Specifically these are:
+
+ .. code-block:: shell
+
+ 1 - When the test_ray intersects perfectly with a polygon vertex.
+ For example, this case with an X-unit (1, 0) test_vector:
+ _____________
+ | . |
+ | /
+ |___________/
+ 2 - When there are two polygon vertices that are colinear with the point
+ along the test_ray. For example, this case with an X-unit test_vector:
+ _____
+ | . |____
+ |__________|
+
+ Use the `is_point_inside_check` method if a result that covers these fringe
+ cases is needed. Oftentimes, it is more practical to use a test_vector
+ with a low probability of encountering the fringe cases than to use the
+ (much longer) `is_point_inside_check` method.
+
+ Args:
+ point: A Point2D for which the inside/outside relationship will be tested.
+ test_vector: Optional vector to set the direction in which intersections
+ with the polygon edges will be evaluated to determine if the
+ point is inside. Default is a slight variation of the X-unit
+ vector with a low probability of encountering the unsupported
+ fringe cases.
+
+ Returns:
+ A boolean denoting whether the point lies inside (True) or outside (False).
+ """
+ test_ray=Ray2D(point,test_vector)
+ n_int=0
+ for_sinself.segments:
+ ifdoes_intersection_exist_line2d(_s,test_ray):
+ n_int+=1
+ ifn_int%2==0:
+ returnFalse
+ returnTrue
+
+
+
+[docs]
+ defis_point_inside_bound_rect(self,point,test_vector=Vector2D(1,0.00001)):
+"""Test whether a Point2D lies roughly inside or outside the polygon.
+
+ This function is virtually identical to the `is_point_inside`
+ method but will first do a check to see if the point lies inside the
+ polygon bounding rectangle. As such, it is a faster approach when one
+ expects many of tested points to lie far away from the polygon.
+
+ Args:
+ point: A Point2D for which the inside/ outside relationship will be tested.
+ test_vector: Optional vector to set the direction in which intersections
+ with the polygon edges will be evaluated to determine if the
+ point is inside. Default is the X unit vector.
+
+ Returns:
+ A boolean denoting whether the point lies inside (True) or outside (False).
+ """
+ min=self.min
+ max=self.max
+ ifpoint.x<min.xorpoint.y<min.yorpoint.x>max.xorpoint.y>max.y:
+ returnFalse
+ returnself.is_point_inside(point,test_vector)
+
+
+
+[docs]
+ defis_polygon_inside(self,polygon):
+"""Test whether another Polygon2D lies completely inside this polygon.
+
+ Args:
+ polygon: A Polygon2D to test whether it is completely inside this one.
+
+ Returns:
+ A boolean denoting whether the polygon lies inside (True) or not (False).
+ """
+ # if the first polygon vertex lies outside, we know it is not inside.
+ ifnotself.is_point_inside_bound_rect(polygon[0]):
+ returnFalse
+ # if one of the edges intersects, we know it has crossed outside.
+ forseginself.segments:
+ for_sinpolygon.segments:
+ ifdoes_intersection_exist_line2d(seg,_s):
+ returnFalse
+ returnTrue
+
+
+
+[docs]
+ defis_polygon_outside(self,polygon):
+"""Test whether another Polygon2D lies completely outside this polygon.
+
+ Args:
+ polygon: A Polygon2D to test whether it is completely outside this one.
+
+ Returns:
+ A boolean denoting whether the polygon lies outside (True) or not (False).
+ """
+ # if the first polygon vertex lies inside, we know it is not outside.
+ ifself.is_point_inside_bound_rect(polygon[0]):
+ returnFalse
+ # if one of the edges intersects, we know it has crossed inside.
+ forseginself.segments:
+ for_sinpolygon.segments:
+ ifdoes_intersection_exist_line2d(seg,_s):
+ returnFalse
+ returnTrue
+
+
+
+[docs]
+ defdoes_polygon_touch(self,polygon,tolerance):
+"""Test whether another Polygon2D touches, overlaps or is inside this polygon.
+
+ Args:
+ polygon: A Polygon2D to test whether it touches this polygon.
+ tolerance: The minimum distance from an edge at which a point is
+ considered to touch the edge.
+
+ Returns:
+ A boolean denoting whether the polygon touches (True) or not (False).
+ """
+ # perform a bounding rectangle check to see if the polygons cannot overlap
+ ifnotPolygon2D.overlapping_bounding_rect(self,polygon,tolerance):
+ returnFalse
+
+ # first evaluate the point relationships
+ pt_rels1=[self.point_relationship(pt,tolerance)forptinpolygon]
+ if0inpt_rels1or1inpt_rels1:
+ returnTrue# definitely touching polygons
+ pt_rels2=[polygon.point_relationship(pt,tolerance)forptinself]
+ if0inpt_rels2or1inpt_rels2:
+ returnTrue# definitely touching polygons
+
+ # if any of the segments intersect the other polygon, there is overlap
+ forseginself.segments:
+ for_sinpolygon.segments:
+ ifdoes_intersection_exist_line2d(seg,_s):
+ returnTrue
+
+ # we can reliably say that the polygons do not touch
+ returnFalse
+
+
+
+[docs]
+ defpolygon_relationship(self,polygon,tolerance):
+"""Test whether another Polygon2D lies inside, outside or overlaps this one.
+
+ This method is not usually the fastest for understanding the relationship
+ between polygons but it accurately accounts for tolerance such that the
+ case of the two polygons sharing edges will not determine the outcome.
+ Only when the polygon has vertices that are truly outside this polygon
+ within the tolerance will the relationship become outside (or intersecting
+ if one of the vertices is already inside within the tolerance).
+
+ In the case of the input polygon being identical to the current polygon,
+ the relationship will be Inside.
+
+ Args:
+ polygon: A Polygon2D for which the relationship to the current polygon
+ will be tested.
+ tolerance: The minimum distance from the edge at which a point is
+ considered to lie on the edge.
+
+ Returns:
+ An integer denoting the relationship of the polygon.
+
+ This will be one of the following:
+
+ * -1 = Outside this polygon
+ * 0 = Overlaps (intersects) this polygon
+ * +1 = Inside this polygon
+ """
+ # perform a bounding rectangle check to see if the polygons cannot overlap
+ ifnotPolygon2D.overlapping_bounding_rect(self,polygon,tolerance):
+ return-1
+
+ # first evaluate the point relationships to rule out the inside case
+ pt_rels1=[self.point_relationship(pt,tolerance)forptinpolygon]
+ pt_rels2=[polygon.point_relationship(pt,tolerance)forptinself]
+ ifall(r1>=0forr1inpt_rels1)andall(r2<=0forr2inpt_rels2):
+ poi=polygon._point_in_polygon(tolerance)
+ ifself.is_point_inside(poi)==1:
+ return1# definitely inside the polygon
+ if1inpt_rels1or1inpt_rels2:
+ return0# definitely overlap in the polygons
+ ifall(r2==0forr2inpt_rels2):
+ poi=self._point_in_polygon(tolerance)
+ ifpolygon.is_point_inside(poi)==1:
+ return0
+
+ # offset one of the polygons inward by the tolerance
+ off_poly=polygon.offset(tolerance)
+ # if any of the offset segments intersect the other polygon, there is overlap
+ forseginself.segments:
+ for_sinoff_poly.segments:
+ ifdoes_intersection_exist_line2d(seg,_s):
+ return0
+
+ # we can reliably say that the polygons have nothing to do with one another
+ return-1
+
+
+
+[docs]
+ defdistance_to_point(self,point):
+"""Get the minimum distance between this shape and a point.
+
+ Points that are inside the Polygon2D will return a distance of zero.
+ If the distance of an interior point to an edge is needed, the
+ distance_from_edge_to_point method should be used.
+
+ Args:
+ point: A Point2D object to which the minimum distance will be computed.
+
+ Returns:
+ The distance to the input point. Will be zero if the point is
+ inside the Polygon2D.
+ """
+ ifself.is_point_inside_bound_rect(point):
+ return0
+ returnmin(seg.distance_to_point(point)forseginself.segments)
+
+
+
+[docs]
+ defdistance_from_edge_to_point(self,point):
+"""Get the minimum distance between the edge of this shape and the input point.
+
+ Args:
+ point: A Point2D object to which the minimum distance will be computed.
+
+ Returns:
+ The distance to the input point from the nearest edge.
+ """
+ returnmin(seg.distance_to_point(point)forseginself.segments)
+
+
+
+[docs]
+ defsnap_to_polygon(self,polygon,tolerance):
+"""Snap another Polygon2D to this one for differences smaller than the tolerance.
+
+ This is useful to run before performing operations where small tolerance
+ differences are likely to cause issues, such as in boolean operations.
+
+ Args:
+ polygon: A Polygon2D which will be snapped to the current polygon.
+ tolerance: The minimum distance at which points will be snapped.
+
+ Returns:
+ A version of the polygon that is snapped to this Polygon2D.
+ """
+ new_verts=[]
+ forptinpolygon.vertices:
+ # first check if the point can be snapped to a vertex
+ fors_ptinself.vertices:
+ ifpt.is_equivalent(s_pt,tolerance):
+ new_verts.append(s_pt)
+ break
+ else:
+ # check if the point can be snapped to a segment
+ forseginself.segments:
+ s_pt=seg.closest_point(pt)
+ ifs_pt.distance_to_point(pt)<=tolerance:
+ new_verts.append(s_pt)
+ break
+ else:# point could not be snapped
+ new_verts.append(pt)
+ returnPolygon2D(new_verts)
+
+
+
+[docs]
+ defsnap_to_grid(self,grid_increment):
+"""Snap this polygon's vertices to the nearest grid node defined by an increment.
+
+ Args:
+ grid_increment: A positive number for dimension of each grid cell. This
+ typically should be equal to the tolerance or larger but should
+ not be larger than the smallest detail of the polygon that you
+ wish to resolve.
+
+ Returns:
+ A version of this polygon that is snapped to the grid.
+ """
+ new_verts=[]
+ forptinself.vertices:
+ new_x=grid_increment*round(pt.x/grid_increment)
+ new_y=grid_increment*round(pt.y/grid_increment)
+ new_verts.append(Point2D(new_x,new_y))
+ returnPolygon2D(new_verts)
+
+
+
+[docs]
+ defto_dict(self):
+"""Get Polygon2D as a dictionary."""
+ return{'type':'Polygon2D',
+ 'vertices':[pt.to_array()forptinself.vertices]}
+
+
+
+[docs]
+ defto_array(self):
+"""Get a tuple of tuples where each sub-tuple represents a Point2D vertex."""
+ returntuple(pt.to_array()forptinself.vertices)
+
+
+ def_to_bool_poly(self):
+"""Translate the Polygon2D to a BooleanPolygon."""
+ b_pts=(pb.BooleanPoint(pt.x,pt.y)forptinself.vertices)
+ returnpb.BooleanPolygon([b_pts])
+
+ def_to_snapped_bool_poly(self,snap_ref_polygon,tolerance):
+"""Snap a Polygon2D to this one and translate it to a BooleanPolygon.
+
+ This is necessary to ensure that boolean operations will succeed between
+ two polygons.
+ """
+ new_poly=snap_ref_polygon.snap_to_polygon(self,tolerance)
+ returnnew_poly._to_bool_poly()
+
+ @staticmethod
+ def_from_bool_poly(bool_polygon,tolerance=None):
+"""Get a list of Polygon2D from a BooleanPolygon object.
+
+ Args:
+ bool_polygon: A BooleanPolygon to be interpreted to a list of Polygon2D.
+ tolerance: An optional tolerance value to be used to remove
+ degenerate objects from the result. If None, the result may
+ contain degenerate objects.
+ """
+ polys=[]
+ fornew_polyinbool_polygon.regions:
+ iflen(new_poly)>2:
+ poly=Polygon2D(tuple(Point2D(pt.x,pt.y)forptinnew_poly))
+ iftoleranceisnotNone:
+ try:
+ poly=poly.remove_duplicate_vertices(tolerance)
+ polys.append(poly)
+ exceptAssertionError:
+ pass# degenerate polygon to be removed
+ else:
+ polys.append(poly)
+ returnpolys
+
+
+[docs]
+ defboolean_union(self,polygon,tolerance):
+"""Get a list of Polygon2D for the union of this Polygon and another.
+
+ Note that the result will not differentiate hole polygons from boundary
+ polygons and so it may be desirable to use the Polygon2D.is_polygon_inside
+ method to distinguish whether a given polygon in the result represents
+ a hole in another polygon in the result.
+
+ Also note that this method will return the original polygons when there
+ is no overlap in the two.
+
+ Args:
+ polygon: A Polygon2D for which the union with the current polygon
+ will be computed.
+ tolerance: The minimum distance between points before they are
+ considered distinct from one another.
+
+ Returns:
+ A list of Polygon2D representing the union of the two polygons.
+ """
+ result=pb.union(
+ self._to_bool_poly(),
+ polygon._to_snapped_bool_poly(self,tolerance),
+ tolerance/1000
+ )
+ returnPolygon2D._from_bool_poly(result,tolerance)
+
+
+
+[docs]
+ defboolean_intersect(self,polygon,tolerance):
+"""Get a list of Polygon2D for the intersection of this Polygon and another.
+
+ Args:
+ polygon: A Polygon2D for which the intersection with the current polygon
+ will be computed.
+ tolerance: The minimum distance between points before they are
+ considered distinct from one another.
+
+ Returns:
+ A list of Polygon2D representing the intersection of the two polygons.
+ Will be an empty list if no overlap exists between the polygons.
+ """
+ result=pb.intersect(
+ self._to_bool_poly(),
+ polygon._to_snapped_bool_poly(self,tolerance),
+ tolerance/1000
+ )
+ returnPolygon2D._from_bool_poly(result,tolerance)
+
+
+
+[docs]
+ defboolean_difference(self,polygon,tolerance):
+"""Get a list of Polygon2D for the subtraction of another polygon from this one.
+
+ Args:
+ polygon: A Polygon2D for which the difference with the current polygon
+ will be computed.
+ tolerance: The minimum distance between points before they are
+ considered distinct from one another.
+
+ Returns:
+ A list of Polygon2D representing the difference of the two polygons.
+ Will be an empty list if subtracting the polygons results in the complete
+ elimination of this polygon. Will be the original polygon when there
+ is no overlap between the polygons.
+ """
+ result=pb.difference(
+ self._to_bool_poly(),
+ polygon._to_snapped_bool_poly(self,tolerance),
+ tolerance/1000
+ )
+ returnPolygon2D._from_bool_poly(result,tolerance)
+
+
+
+[docs]
+ defboolean_xor(self,polygon,tolerance):
+"""Get Polygon2D list for the exclusive disjunction of this polygon and another.
+
+ Note that this method is prone to merging holes that may exist in the
+ result into the boundary to create a single list of joined vertices,
+ which may not always be desirable. In this case, it may be desirable
+ to do two separate boolean_difference calculations instead.
+
+ Also note that, when the result includes separate polygons for holes,
+ it will not differentiate hole polygons from boundary polygons
+ and so it may be desirable to use the Polygon2D.is_polygon_inside
+ method to distinguish whether a given polygon in the result represents
+ a hole within another polygon in the result.
+
+ Args:
+ polygon: A Polygon2D for which the exclusive disjunction with the
+ current polygon will be computed.
+ tolerance: The minimum distance between points before they are
+ considered distinct from one another.
+
+ Returns:
+ A list of Polygon2D representing the exclusive disjunction of the
+ two polygons. Will be the original polygons when there is no overlap
+ in the two.
+ """
+ result=pb.xor(
+ self._to_bool_poly(),
+ polygon._to_snapped_bool_poly(self,tolerance),
+ tolerance/1000
+ )
+ returnPolygon2D._from_bool_poly(result,tolerance)
+
+
+
+[docs]
+ @staticmethod
+ defsnap_polygons(polygons,tolerance):
+"""Snap several Polygon2D to each other if they differ less than the tolerance.
+
+ This is useful to run before performing operations where small tolerance
+ differences are likely to cause issues, such as in boolean operations.
+
+ Args:
+ polygons: A list of Polygon2D, which will be snapped to each other.
+ tolerance: The minimum distance at which points will be snapped.
+
+ Returns:
+ A list of the input polygon2D that have been snapped to one another.
+ """
+ new_polygons=list(polygons)
+ fori,poly_1inenumerate(new_polygons):
+ try:
+ forj,poly_2inenumerate(new_polygons[i+1:]):
+ new_polygons[i+j+1]=poly_1.snap_to_polygon(poly_2,tolerance)
+ exceptIndexError:
+ pass# we have reached the end of the list of polygons
+ returnnew_polygons
+
+
+
+[docs]
+ @staticmethod
+ defboolean_union_all(polygons,tolerance):
+"""Get a list of Polygon2D for the union of several Polygon2D.
+
+ Using this method is more computationally efficient than calling the
+ Polygon2D.boolean_union() method multiple times as this method will
+ only compute the intersection of the segments once.
+
+ Note that the result will not differentiate hole polygons from boundary
+ polygons and so it may be desirable to use the Polygon2D.is_polygon_inside
+ method to distinguish whether a given polygon in the result represents
+ a hole in another polygon in the result.
+
+ Also note that this method will return the original polygons when there
+ is no overlap in the two.
+
+ Args:
+ polygons: An array of Polygon2D for which the union will be computed.
+ tolerance: The minimum distance between points before they are
+ considered distinct from one another.
+
+ Returns:
+ A list of Polygon2D representing the union of all the polygons.
+ """
+ polygons=Polygon2D.snap_polygons(polygons,tolerance)
+ bool_polys=[poly._to_bool_poly()forpolyinpolygons]
+ result=pb.union_all(bool_polys,tolerance/1000)
+ returnPolygon2D._from_bool_poly(result,tolerance)
+
+
+
+[docs]
+ @staticmethod
+ defboolean_intersect_all(polygons,tolerance):
+"""Get a list of Polygon2D for the intersection of several Polygon2D.
+
+ Using this method is more computationally efficient than calling the
+ Polygon2D.boolean_intersect() method multiple times as this method will
+ only compute the intersection of the segments once.
+
+ Note that the result will not differentiate hole polygons from boundary
+ polygons and so it may be desirable to use the Polygon2D.is_polygon_inside
+ method to distinguish whether a given polygon in the result represents
+ a hole in another polygon in the result.
+
+ Also note that this method will return the original polygons when there
+ is no overlap in the two.
+
+ Args:
+ polygons: An array of Polygon2D for which the intersection will be computed.
+ tolerance: The minimum distance between points before they are
+ considered distinct from one another.
+
+ Returns:
+ A list of Polygon2D representing the intersection of all the polygons.
+ Will be an empty list if no overlap exists between the polygons.
+ """
+ polygons=Polygon2D.snap_polygons(polygons,tolerance)
+ bool_polys=[poly._to_bool_poly()forpolyinpolygons]
+ result=pb.intersect_all(bool_polys,tolerance/1000)
+ returnPolygon2D._from_bool_poly(result,tolerance)
+
+
+
+[docs]
+ @staticmethod
+ defboolean_split(polygon1,polygon2,tolerance):
+"""Split two Polygon2D with one another to get the intersection and difference.
+
+ Using this method is more computationally efficient than calling the
+ Polygon2D.intersect() and Polygon2D.difference() methods individually as
+ this method will only compute the intersection of the segments once.
+
+ Note that the result will not differentiate hole polygons from boundary
+ polygons and so it may be desirable to use the Polygon2D.is_polygon_inside
+ method to distinguish whether a given polygon in the result represents
+ a hole in another polygon in the result.
+
+ Args:
+ polygon1: A Polygon2D for the first polygon that will be split with
+ the second polygon.
+ polygon2: A Polygon2D for the second polygon that will be split with
+ the first polygon.
+ tolerance: The minimum distance between points before they are
+ considered distinct from one another.
+
+ Returns:
+ A tuple with three elements
+
+ - intersection: A list of Polygon2D for the intersection of the two
+ input polygons.
+
+ - poly1_difference: A list of Polygon2D for the portion of polygon1 that does
+ not overlap with polygon2. When combined with the intersection, this
+ makes a split version of polygon1.
+
+ - poly2_difference: A list of Polygon2D for the portion of polygon2 that does
+ not overlap with polygon1. When combined with the intersection, this
+ makes a split version of polygon2.
+ """
+ int_result,poly1_result,poly2_result=pb.split(
+ polygon1._to_bool_poly(),
+ polygon2._to_snapped_bool_poly(polygon1,tolerance),
+ tolerance/1000
+ )
+ intersection=Polygon2D._from_bool_poly(int_result,tolerance)
+ poly1_difference=Polygon2D._from_bool_poly(poly1_result,tolerance)
+ poly2_difference=Polygon2D._from_bool_poly(poly2_result,tolerance)
+ returnintersection,poly1_difference,poly2_difference
+
+
+
+[docs]
+ @staticmethod
+ defperimeter_core_by_offset(polygon,distance,holes=None):
+"""Compute perimeter and core sub-polygons using a simple offset method.
+
+ This method will only return polygons when the distance is shallow enough
+ that the perimeter offset does not intersect itself or turn inward on itself.
+ Otherwise, the method will simply return None.
+
+ Args:
+ polygon: A Polygon2D to split into perimeter and core sub-polygons.
+ distance: Distance in model units to offset perimeter sub-polygon.
+ holes: A list of Polygon2D objects representing holes in the
+ polygon. (Default: None).
+
+ Returns:
+ A tuple with two items.
+
+ * perimeter_sub_polys -- A list of perimeter sub-polygons as Polygon2D
+ objects. Will be None if the offset distance is too deep.
+
+ * core_sub_polys -- A list of core sub-polygons as Polygon2D objects. In the
+ event of a core sub-polygon with a hole, a list with be returned with
+ the first item being a boundary and successive items as hole polygons.
+ Will be None if the offset distance is too deep.
+ """
+ # extract the core polygon and make sure it doesn't intersect itself
+ core_sub_poly=polygon.offset(distance,check_intersection=True)
+ ifcore_sub_polyisNone:
+ returnNone,None
+ # generate the perimeter polygons
+ ifholesisNone:
+ perimeter_sub_polys=[]
+ forout_seg,in_seginzip(polygon.segments,core_sub_poly.segments):
+ pts=(out_seg.p1,out_seg.p2,in_seg.p2,in_seg.p1)
+ perimeter_sub_polys.append(Polygon2D(pts))
+ returnperimeter_sub_polys,[core_sub_poly]
+ else:
+ # offset all of the holes into the shape
+ core_sub_polys=[core_sub_poly]
+ forholeinholes:
+ hole_sub_poly=hole.offset(-distance,check_intersection=True)
+ ifhole_sub_polyisNone:
+ returnNone,None
+ core_sub_polys.append(hole_sub_poly)
+ # check that None of the holes intersect one another
+ fori,c_pgoninenumerate(core_sub_polys):
+ forother_pgonincore_sub_polys[i+1:]:
+ ifPolygon2D._do_polygons_intersect(c_pgon,other_pgon):
+ returnNone,None
+ # if nothing intersects, we can build the perimeter polygons
+ out_polys=[polygon]+list(holes)
+ perimeter_sub_polys=[]
+ forp_count,(out_poly,in_poly)inenumerate(zip(out_polys,core_sub_polys)):
+ forout_seg,in_seginzip(out_poly.segments,in_poly.segments):
+ ifp_count==0:
+ pts=(out_seg.p1,out_seg.p2,in_seg.p2,in_seg.p1)
+ else:
+ ifnotout_poly.is_clockwise:
+ pts=(out_seg.p1,in_seg.p1,in_seg.p2,out_seg.p2)
+ else:
+ (out_seg.p1,out_seg.p2,in_seg.p2,in_seg.p1)
+ perimeter_sub_polys.append(Polygon2D(pts))
+ returnperimeter_sub_polys,core_sub_polys
+
+
+ @staticmethod
+ def_do_polygons_intersect(polygon_1,polygon_2):
+"""Test to see if two polygons intersect one another."""
+ forseginpolygon_1.segments:
+ for_sinpolygon_2.segments:
+ ifdoes_intersection_exist_line2d(seg,_s):
+ returnTrue
+ returnFalse
+
+
+[docs]
+ @staticmethod
+ defintersect_polygon_segments(polygon_list,tolerance):
+"""Intersect the line segments of a Polygon2D array to ensure matching segments.
+
+ Specifically, this method checks a list of polygons in a pairwise manner to
+ see if one contains a vertex along an edge segment of the other within the
+ given tolerance. If so, the method creates a co-located vertex at that point,
+ partitioning the edge segment into two edge segments. Point ordering is
+ reserved within each Polygon2D and the order of Polygon2Ds within the input
+ polygon_list is also preserved.
+
+ Args:
+ polygon_list: List of Polygon2Ds which will have their segments
+ intersected with one another.
+ tolerance: Distance within which two points are considered to be
+ co-located.
+
+ Returns:
+ The input list of Polygon2D objects with extra vertices inserted
+ where necessary.
+ """
+ foriinrange(len(polygon_list)-1):
+ # No need for j to start at 0 since two polygons are passed
+ # and they are compared against one other within intersect_segments.
+ forjinrange(i+1,len(polygon_list)):
+ polygon_list[i],polygon_list[j]= \
+ Polygon2D.intersect_segments(polygon_list[i],polygon_list[j],
+ tolerance)
+ returnpolygon_list
+
+
+
+[docs]
+ @staticmethod
+ defintersect_segments(polygon1,polygon2,tolerance):
+"""Intersect the line segments of two Polygon2Ds to ensure matching segments.
+
+ Specifically, this method checks two adjacent polygons to see if one contains
+ a vertex along an edge segment of the other within the given tolerance. If so,
+ it creates a co-located vertex at that point, partitioning the edge segment
+ into two edge segments. Point ordering is preserved.
+
+ Args:
+ polygon1: First polygon to check.
+ polygon2: Second polygon to check.
+ tolerance: Distance within which two points are considered to be co-located.
+
+ Returns:
+ Two polygon objects with extra vertices inserted if necessary.
+ """
+ polygon1_updates=[]
+ polygon2_updates=[]
+
+ # bounding rectangle check
+ ifnotPolygon2D.overlapping_bounding_rect(polygon1,polygon2,tolerance):
+ returnpolygon1,polygon2# no overlap
+
+ # test if each point of polygon2 is within the tolerance distance of any segment
+ # of polygon1. If so, add the closest point on the segment to the polygon1
+ # update list. And vice versa (testing polygon2 against polygon1).
+ fori1,seg1inenumerate(polygon1.segments):
+ fori2,seg2inenumerate(polygon2.segments):
+ # Test polygon1 against polygon2
+ x=closest_point2d_on_line2d(seg2.p1,seg1)
+ ifall(p.distance_to_point(x)>toleranceforpinpolygon1.vertices) \
+ andx.distance_to_point(seg2.p1)<=tolerance:
+ polygon1_updates.append((i1,x))
+ # Test polygon2 against polygon1
+ y=closest_point2d_on_line2d(seg1.p1,seg2)
+ ifall(p.distance_to_point(y)>toleranceforpinpolygon2.vertices) \
+ andy.distance_to_point(seg1.p1)<=tolerance:
+ polygon2_updates.append((i2,y))
+
+ # apply any updates to polygon1
+ polygon1=Polygon2D._insert_updates_in_order(polygon1,polygon1_updates)
+
+ # Apply any updates to polygon2
+ polygon2=Polygon2D._insert_updates_in_order(polygon2,polygon2_updates)
+
+ returnpolygon1,polygon2
+
+
+
+[docs]
+ @staticmethod
+ defoverlapping_bounding_rect(polygon1,polygon2,tolerance):
+"""Check if the bounding rectangles of two polygons overlap within a tolerance.
+
+ This is particularly useful as a check before performing computationally intense
+ processes between two polygons like intersection or boolean operations.
+ Checking the overlap of the bounding boxes is extremely quick with this
+ method's use of the the Separating Axis Theorem.
+
+ Args:
+ polygon1: The first polygon to check.
+ polygon2: The second polygon to check.
+ tolerance: Distance within which two points are considered to be co-located.
+ """
+ # Bounding rectangle check using the Separating Axis Theorem
+ polygon1_width=polygon1.max.x-polygon1.min.x
+ polygon2_width=polygon2.max.x-polygon2.min.x
+ dist_btwn_x=abs(polygon1.center.x-polygon2.center.x)
+ x_gap_btwn_rect=dist_btwn_x-(0.5*polygon1_width)-(0.5*polygon2_width)
+
+ polygon1_height=polygon1.max.y-polygon1.min.y
+ polygon2_height=polygon2.max.y-polygon2.min.y
+ dist_btwn_y=abs(polygon1.center.y-polygon2.center.y)
+ y_gap_btwn_rect=dist_btwn_y-(0.5*polygon1_height)-(0.5*polygon2_height)
+
+ ifx_gap_btwn_rect>toleranceory_gap_btwn_rect>tolerance:
+ returnFalse# no overlap
+ returnTrue# overlap exists
+
+
+
+[docs]
+ @staticmethod
+ defgroup_by_overlap(polygons,tolerance):
+"""Group Polygon2Ds that overlap one another within the tolerance.
+
+ This is useful as a pre-step before running Polygon2D.boolean_union_all()
+ in order to assess whether unionizing is necessary and to ensure that
+ it is only performed among the necessary groups of polygons.
+
+ This method will return the minimal number of overlapping polygon groups
+ thanks to a recursive check of whether groups can be merged.
+
+ Args:
+ polygons: A list of Polygon2D to be grouped by their overlapping.
+ tolerance: The minimum distance from the edge of a neighboring polygon
+ at which a point is considered to overlap with that polygon.
+
+ Returns:
+ A list of lists where each sub-list represents a group of polygons
+ that all overlap with one another.
+ """
+ # sort the polygons by area to help larger ones grab smaller ones
+ polygons=list(sorted(polygons,key=lambdax:x.area,reverse=True))
+
+ # loop through the polygons and check to see if it overlaps with the others
+ grouped_polys=[[polygons[0]]]
+ forpolyinpolygons[1:]:
+ group_found=False
+ forpoly_groupingrouped_polys:
+ foroth_polyinpoly_group:
+ ifpoly.polygon_relationship(oth_poly,tolerance)>=0:
+ poly_group.append(poly)
+ group_found=True
+ break
+ ifgroup_found:
+ break
+ ifnotgroup_found:# the polygon does not overlap with any of the others
+ grouped_polys.append([poly])# make a new group for the polygon
+
+ # if some groups were found, recursively merge groups together
+ old_group_len=len(polygons)
+ whilelen(grouped_polys)!=old_group_len:
+ new_groups,g_to_remove=grouped_polys[:],[]
+ fori,group_1inenumerate(grouped_polys):
+ try:
+ forj,group_2inenumerate(grouped_polys[i+1:]):
+ ifPolygon2D._groups_overlap(group_1,group_2,tolerance):
+ new_groups[i]=new_groups[i]+group_2
+ g_to_remove.append(i+j+1)
+ exceptIndexError:
+ pass# we have reached the end of the list of polygons
+ iflen(g_to_remove)!=0:
+ g_to_remove=list(set(g_to_remove))
+ g_to_remove.sort()
+ forriinreversed(g_to_remove):
+ new_groups.pop(ri)
+ old_group_len=len(grouped_polys)
+ grouped_polys=new_groups
+ returngrouped_polys
+
+
+ @staticmethod
+ def_groups_overlap(group_1,group_2,tolerance):
+"""Evaluate whether two groups of Polygons overlap with one another."""
+ forpoly_1ingroup_1:
+ forpoly_2ingroup_2:
+ ifpoly_1.polygon_relationship(poly_2,tolerance)>=0:
+ returnTrue
+ returnFalse
+
+
+[docs]
+ @staticmethod
+ defgroup_by_touching(polygons,tolerance):
+"""Group Polygon2Ds that touch or overlap one another within the tolerance.
+
+ This is useful to group geometries together before extracting a bounding
+ rectangle or convex hull around multiple polygons.
+
+ This method will return the minimal number of polygon groups
+ thanks to a recursive check of whether groups can be merged.
+
+ Args:
+ polygons: A list of Polygon2D to be grouped by their touching.
+ tolerance: The minimum distance from the edge of a neighboring polygon
+ at which a point is considered to touch that polygon.
+
+ Returns:
+ A list of lists where each sub-list represents a group of polygons
+ that all touch or overlap with one another.
+ """
+ # sort the polygons by area to help larger ones grab smaller ones
+ polygons=list(sorted(polygons,key=lambdax:x.area,reverse=True))
+
+ # loop through the polygons and check to see if it overlaps with the others
+ grouped_polys=[[polygons[0]]]
+ forpolyinpolygons[1:]:
+ group_found=False
+ forpoly_groupingrouped_polys:
+ foroth_polyinpoly_group:
+ ifpoly.does_polygon_touch(oth_poly,tolerance):
+ poly_group.append(poly)
+ group_found=True
+ break
+ ifgroup_found:
+ break
+ ifnotgroup_found:# the polygon does not touch any of the others
+ grouped_polys.append([poly])# make a new group for the polygon
+
+ # if some groups were found, recursively merge groups together
+ old_group_len=len(polygons)
+ whilelen(grouped_polys)!=old_group_len:
+ new_groups,g_to_remove=grouped_polys[:],[]
+ fori,group_1inenumerate(grouped_polys):
+ try:
+ forj,group_2inenumerate(grouped_polys[i+1:]):
+ ifPolygon2D._groups_touch(group_1,group_2,tolerance):
+ new_groups[i]=new_groups[i]+group_2
+ g_to_remove.append(i+j+1)
+ exceptIndexError:
+ pass# we have reached the end of the list of polygons
+ iflen(g_to_remove)!=0:
+ g_to_remove=list(set(g_to_remove))
+ g_to_remove.sort()
+ forriinreversed(g_to_remove):
+ new_groups.pop(ri)
+ old_group_len=len(grouped_polys)
+ grouped_polys=new_groups
+ returngrouped_polys
+
+
+ @staticmethod
+ def_groups_touch(group_1,group_2,tolerance):
+"""Evaluate whether two groups of Polygons touch with one another."""
+ forpoly_1ingroup_1:
+ forpoly_2ingroup_2:
+ ifpoly_1.does_polygon_touch(poly_2,tolerance):
+ returnTrue
+ returnFalse
+
+
+[docs]
+ @staticmethod
+ defgroup_boundaries_and_holes(polygons,tolerance):
+"""Group polygons by whether they are contained within another.
+
+ Args:
+ polygons: A list of Polygon2Ds to be grouped according to boundary and
+ holes within those boundaries.
+ tolerance: The minimum distance between points at which they are
+ considered distinct.
+
+ Returns:
+ A list of lists where each sub-list contains Polygon2Ds and represents
+ one core geometry. Each sub-list will have has at least one Polygon2D
+ and, in the event that a core geometry has holes, there will be multiple
+ Polygon2Ds in the sub-list. The first item in the list will be the outer
+ boundary of the geometry and successive items represent hole polygons
+ contained within it.
+ """
+ # first check to be sure that there isn't just one polygon
+ iflen(polygons)==1:
+ return[polygons]
+ # sort the polygons by area and separate base polygon from the remaining
+ polygons=sorted(polygons,key=lambdax:x.area,reverse=True)
+ base_poly=polygons[0]
+ remain_polys=list(polygons[1:])
+
+ # merge the smaller polygons into the larger polygons
+ merged_polys=[]
+ whilelen(remain_polys)>0:
+ grp_poly=Polygon2D._match_holes_to_poly(base_poly,remain_polys,tolerance)
+ merged_polys.append(grp_poly)
+ iflen(remain_polys)>1:
+ base_poly=remain_polys[0]
+ delremain_polys[0]
+ eliflen(remain_polys)==1:# lone last Polygon2D
+ merged_polys.append([remain_polys[0]])
+ delremain_polys[0]
+ returnmerged_polys
+
+
+ @staticmethod
+ def_match_holes_to_poly(base_poly,other_polys,tolerance):
+"""Attempt to merge other polygons into a base polygon as holes.
+
+ Args:
+ base_poly: A Polygon2D to serve as the base.
+ other_polys: A list of other Polygon2D objects to attempt to merge into
+ the base_poly as a hole. This method will remove any Polygon2D
+ that are successfully merged into the output from this list.
+ tolerance: The minimum distance between points at which they are
+ considered distinct.
+
+ Returns:
+ A list of Polygon2D where the first item is the base_poly and successive
+ items represent holes in this geometry.
+ """
+ holes=[]
+ more_to_check=True
+ whilemore_to_check:
+ fori,r_polyinenumerate(other_polys):
+ ifbase_poly.polygon_relationship(r_poly,tolerance)==1:
+ holes.append(r_poly)
+ delother_polys[i]
+ break
+ else:
+ more_to_check=False
+ return[base_poly]+holes
+
+
+[docs]
+ @staticmethod
+ defjoined_intersected_boundary(polygons,tolerance):
+"""Get the boundary around several Polygon2D that are touching one another.
+
+ This method is faster and more reliable than the gap_crossing_boundary
+ but requires that the Polygon2D be touching one another within the tolerance.
+
+ Args:
+ polygons: The polygons to be joined into a boundary. These polygons
+ should have colinear vertices removed and they should not contain
+ degenerate polygons at the tolerance. The remove_colinear_vertices
+ method can be used to pre-process the input polygons to ensure they
+ meet these criteria.
+ tolerance: The tolerance at which the polygons are to be intersected
+ and then joined to give a resulting boundary.
+
+ Returns:
+ A list of Polygon2D that represent the boundary around the input polygons.
+ Note that some of these Polygon2D may represent 'holes' within others
+ and it may be necessary to assess this when interpreting the result.
+ """
+ # intersect the polygons with one another
+ int_poly=Polygon2D.intersect_polygon_segments(polygons,tolerance)
+
+ # get indices of all unique vertices across the polygons
+ vertices=[]# collection of vertices as point objects
+ poly_indices=[]# collection of polygon indices
+ forloopinint_poly:
+ ind=[]
+ forvinloop:
+ found=False
+ fori,vertinenumerate(vertices):
+ ifv.is_equivalent(vert,tolerance):
+ found=True
+ ind.append(i)
+ break
+ ifnotfound:# add new point
+ vertices.append(v)
+ ind.append(len(vertices)-1)
+ poly_indices.append(ind)
+
+ # use the unique vertices to extract naked edges
+ edge_i=[]
+ edge_t=[]
+ forpoly_iinpoly_indices:
+ fori,viinenumerate(poly_i):
+ try:# this can get slow for large number of vertices
+ ind=edge_i.index((vi,poly_i[i-1]))
+ edge_t[ind]+=1
+ exceptValueError:# make sure reversed edge isn't there
+ try:
+ ind=edge_i.index((poly_i[i-1],vi))
+ edge_t[ind]+=1
+ exceptValueError:# add a new edge
+ ifpoly_i[i-1]!=vi:# avoid cases of same start and end
+ edge_i.append((poly_i[i-1],vi))
+ edge_t.append(0)
+ ext_edges=[]
+ fori,etinenumerate(edge_t):
+ ifet==0:
+ edg_ind=edge_i[i]
+ pts_2d=(vertices[edg_ind[0]],vertices[edg_ind[1]])
+ ext_edges.append(LineSegment2D.from_end_points(*pts_2d))
+
+ # join the naked edges into closed polygons
+ outlines=Polyline2D.join_segments(ext_edges,tolerance)
+ closed_polys=[]
+ forbndinoutlines:
+ ifisinstance(bnd,Polyline2D)andbnd.is_closed(tolerance):
+ closed_polys.append(bnd.to_polygon(tolerance))
+ returnclosed_polys
+
+
+
+[docs]
+ @staticmethod
+ defgap_crossing_boundary(polygons,min_separation,tolerance):
+"""Get the boundary around several Polygon2D, crossing gaps of min_separation.
+
+ This method is less reliable than the joined_intersected_boundary because
+ higher values of min_separation that are greater than the lengths of polygon
+ segments can cause important details of the polygons to disappear. However,
+ when used appropriately, it can provide a boundary that jumps across gaps
+ to give resulting polygons that effectively bound all of the input polygons.
+
+ Args:
+ polygons: The polygons to be joined into a boundary. These polygons
+ should have colinear vertices removed and they should not contain
+ degenerate polygons at the tolerance. The remove_colinear_vertices
+ method can be used to pre-process the input polygons to ensure they
+ meet these criteria.
+ min_separation: A number for the minimum distance between Polygon2D that
+ is considered a meaningful separation. In other words, this is
+ the maximum distance of the gap across
+ tolerance: The maximum difference between coordinate values of two
+ vertices at which they can be considered equivalent.
+
+ Returns:
+ A list of Polygon2D that represent the boundary around the input polygons.
+ Note that some of these Polygon2D may represent 'holes' within others
+ and it may be necessary to assess this when interpreting the result.
+ """
+ # ensure that all of the input polygons are counterclockwise
+ cclock_poly=[]
+ forpolyinpolygons:
+ ifpoly.is_clockwise:
+ cclock_poly.append(poly.reverse())
+ else:
+ cclock_poly.append(poly)
+
+ # determine which Polygon2D segments are 'exterior' using the min_separation
+ right_ang=-math.pi/2
+ ext_segs=[]
+ fori,polyinenumerate(cclock_poly):
+ # remove any short segments
+ rel_segs=[sforsinpoly.segmentsifs.length>min_separation]
+
+ # create min_separation line segments to be used to test intersection
+ test_segs=[]
+ for_sinrel_segs:
+ d_vec=_s.v.rotate(right_ang).normalize()
+ seg_pts=_s.subdivide(min_separation)
+ iflen(seg_pts)<=3:
+ seg_pts=[_s.midpoint]
+ else:
+ seg_pts=seg_pts[1:-1]
+ spec_test_segs=[]
+ forsptinseg_pts:
+ m_pt=spt.move(d_vec*-tolerance)
+ spec_test_segs.append(LineSegment2D(m_pt,d_vec*min_separation))
+ test_segs.append(spec_test_segs)
+
+ # intersect the test line segments to asses which parts are exterior
+ non_int_segs=[]
+ other_poly=[pforj,pinenumerate(cclock_poly)ifj!=i]
+ forj,(_s,int_lins)inenumerate(zip(rel_segs,test_segs)):
+ int_vals=[0]*len(int_lins)
+ form,int_lininenumerate(int_lins):
+ for_oth_pinother_poly:
+ if_oth_p.intersect_line_ray(int_lin):# intersection!
+ int_vals[m]=1
+ break
+ ifsum(int_vals)==len(int_lins):# fully internal line
+ continue
+ else:# if the polygon is concave, also check for self intersection
+ ifnotpoly.is_convex:
+ _other_segs=[xfork,xinenumerate(rel_segs)ifk!=j]
+ form,int_lininenumerate(int_lins):
+ for_oth_sin_other_segs:
+ ifint_lin.intersect_line_ray(_oth_s)isnotNone:
+ int_vals[m]=1
+ break
+
+ # determine the exterior segments using the intersections
+ check_sum=sum(int_vals)
+ ifcheck_sum==0:# fully external line
+ non_int_segs.append(_s)
+ eliflen(int_vals)==1orcheck_sum==len(int_vals):
+ continue# fully internal line
+ else:# line that extends from inside to outside
+ # first see if the exterior part is meaningful
+ count_in_a_rows,repeat_count=[],0
+ forvinint_vals:
+ ifv==0:
+ repeat_count+=1
+ count_in_a_rows.append(repeat_count)
+ else:
+ repeat_count=0
+ max_repeat=max(count_in_a_rows)
+ # if the exterior part is meaningful, split it
+ ifmax_repeat!=1:
+ last_pt=_s.p1ifint_vals[0]==0elseNone
+ forv,tsinzip(int_vals,int_lins):
+ ifv==0andlast_ptisNone:
+ last_pt=ts.p1
+ elifv==1andlast_ptisnotNone:
+ lin_seg=LineSegment2D.from_end_points(last_pt,ts.p1)
+ last_pt=None
+ non_int_segs.append(lin_seg)
+ iflast_ptisnotNone:
+ lin_seg=LineSegment2D.from_end_points(last_pt,_s.p2)
+ non_int_segs.append(lin_seg)
+
+ ext_segs.extend(non_int_segs)
+
+ # loop through exterior segments and add segments across the min_separation
+ joining_segs=[]
+ fori,e_seginenumerate(ext_segs):
+ try:
+ foro_seginext_segs[i+1:]:
+ dist,pts=closest_end_point2d_between_line2d(e_seg,o_seg)
+ iftolerance<dist<=min_separation:
+ joining_segs.append(LineSegment2D.from_end_points(*pts))
+ exceptIndexError:
+ pass# we have reached the end of the list
+
+ # join all of the segments together into polylines
+ all_segs=ext_segs+joining_segs
+ ext_bounds=Polyline2D.join_segments(all_segs,tolerance)
+
+ # separate valid closed boundaries from open ones
+ closed_polys,open_bounds=[],[]
+ forbndinext_bounds:
+ ifisinstance(bnd,Polyline2D)andbnd.is_closed(tolerance):
+ try:
+ closed_polys.append(bnd.to_polygon(tolerance))
+ exceptAssertionError:# not a valid polygon
+ pass
+ else:
+ open_bounds.append(bnd)
+
+ # if the resulting polylines are not closed, join the nearest end points
+ iflen(closed_polys)!=len(ext_bounds):
+ extra_segs=[]
+ fori,s_bndinenumerate(open_bounds):
+ self_seg=LineSegment2D.from_end_points(s_bnd.p1,s_bnd.p2)
+ poss_segs=[self_seg]
+ try:
+ foro_bndinopen_bounds[i+1:]:
+ pts=[
+ (s_bnd.p1,o_bnd.p1),(s_bnd.p1,o_bnd.p2),
+ (s_bnd.p2,o_bnd.p1),(s_bnd.p2,o_bnd.p2)]
+ forcombinpts:
+ poss_segs.append(LineSegment2D.from_end_points(*comb))
+ exceptIndexError:
+ continue# we have reached the end of the list
+ # sort the possible segments by their length
+ poss_segs.sort(key=lambdax:x.length,reverse=False)
+ ifposs_segs[0]isself_seg:
+ extra_segs.append(poss_segs[0])
+ else:# two possible connecting segments
+ extra_segs.append(poss_segs[0])
+ extra_segs.append(poss_segs[1])
+ # remove any duplicates from the extra segment list
+ non_dup_segs=[]
+ fore_seginextra_segs:
+ forf_seginnon_dup_segs:
+ ife_seg.is_equivalent(f_seg,tolerance):
+ break
+ else:
+ non_dup_segs.append(e_seg)
+ extra_segs=non_dup_segs
+ # take the best available segments that fit the criteria
+ extra_segs.sort(key=lambdax:x.length,reverse=False)
+ extra_segs=extra_segs[:len(open_bounds)]
+
+ # join all segments, hopefully into a final closed polyline
+ all_segs=ext_segs+joining_segs+extra_segs
+ ext_bounds=Polyline2D.join_segments(all_segs,tolerance)
+ closed_polys=[]
+ forbndinext_bounds:
+ ifisinstance(bnd,Polyline2D)andbnd.is_closed(tolerance):
+ try:
+ closed_polys.append(bnd.to_polygon(tolerance))
+ exceptAssertionError:# not a valid polygon
+ pass
+
+ returnclosed_polys
+
+
+
+[docs]
+ @staticmethod
+ defcommon_axes(polygons,direction,min_distance,merge_distance,angle_tolerance):
+"""Get LineSegment2Ds for the most common axes across a set of Polygon2Ds.
+
+ This is often useful as a step before aligning a set of polygons to these
+ common axes.
+
+ Args:
+ polygons: A list or tuple of Polygon2D objects for which common axes
+ will be evaluated.
+ direction: A Vector2D object to represent the direction in which the
+ common axes will be evaluated and generated
+ min_distance: The minimum distance at which common axes will be evaluated.
+ This value should typically be a little larger than the model
+ tolerance (eg. 5 to 20 times the tolerance) in order to ensure that
+ possible common axes across the input polygons are not missed.
+ merge_distance: The distance at which common axes next to one another
+ will be merged into a single axis. This should typically be 2-3
+ times the min_distance in order to avoid generating several axes
+ that are immediately adjacent to one another. When using this
+ method to generate axes for alignment, this merge_distance should
+ be in the range of the alignment distance.
+ angle_tolerance: The max angle difference in radians that the polygon
+ segments direction can differ from the input direction before the
+ segments are not factored into this calculation of common axes.
+
+ Returns:
+ A tuple with two elements.
+
+ - common_axes: A list of LineSegment2D objects for the common
+ axes across the input polygons.
+
+ - axis_values: A list of integers that aligns with the common_axes
+ and denotes how many segments of the input polygons each axis
+ relates to. Higher numbers indicate that that the axis is more
+ common among all of the possible axes.
+ """
+ # gather the relevant segments of the input polygons
+ min_ang,max_ang=angle_tolerance,math.pi-angle_tolerance
+ rel_segs=[]
+ forp_goninpolygons:
+ forseginp_gon.segments:
+ try:
+ s_ang=direction.angle(seg.v)
+ ifs_ang<min_angors_ang>max_ang:
+ rel_segs.append(seg)
+ exceptZeroDivisionError:# zero length segment to ignore
+ continue
+ iflen(rel_segs)==0:
+ return[],[]# none of the polygon segments are relevant in the direction
+
+ # determine the extents around the polygons and the input direction
+ gen_vec=direction.rotate(math.pi/2)
+ axis_angle=Vector2D(0,1).angle_counterclockwise(gen_vec)
+ orient_poly=polygons
+ ifaxis_angle!=0:# rotate geometry to the bounding box
+ cpt=polygons[0].vertices[0]
+ orient_poly=[pl.rotate(-axis_angle,cpt)forplinpolygons]
+ xx=Polygon2D._bounding_domain_x(orient_poly)
+ yy=Polygon2D._bounding_domain_y(orient_poly)
+ min_pt=Point2D(xx[0],yy[0])
+ max_pt=Point2D(xx[1],yy[1])
+ ifaxis_angle!=0:# rotate the points back
+ min_pt=min_pt.rotate(axis_angle,cpt)
+ max_pt=max_pt.rotate(axis_angle,cpt)
+
+ # generate all possible axes from the extents and min_distance
+ axis_vec=direction.normalize()*(xx[1]-xx[0])
+ incr_vec=gen_vec.normalize()*(min_distance)
+ current_pt=min_pt
+ current_dist,max_dist=0,yy[1]-yy[0]
+ all_axes=[]
+ whilecurrent_dist<max_dist:
+ axis=LineSegment2D(current_pt,axis_vec)
+ all_axes.append(axis)
+ current_pt=current_pt.move(incr_vec)
+ current_dist+=min_distance
+
+ # evaluate the axes based on how many relevant segments they are next to
+ mid_pts=[seg.midpointforseginrel_segs]
+ rel_axes,axes_value=[],[]
+ foraxisinall_axes:
+ axis_val=0
+ forptinmid_pts:
+ close_pt=closest_point2d_on_line2d_infinite(pt,axis)
+ ifclose_pt.distance_to_point(pt)<=min_distance:
+ axis_val+=1
+ ifaxis_val!=0:
+ rel_axes.append(axis)
+ axes_value.append(axis_val)
+ iflen(rel_axes)==0:
+ return[],[]# none of the generated axes are relevant
+
+ # group the axes by proximity
+ last_ax=rel_axes[0]
+ axes_groups=[[last_ax]]
+ group_values=[[axes_value[0]]]
+ foraxis,valinzip(rel_axes[1:],axes_value[1:]):
+ ifaxis.p.distance_to_point(last_ax.p)<=merge_distance:
+ axes_groups[-1].append(axis)
+ group_values[-1].append(val)
+ else:# start a new group
+ axes_groups.append([axis])
+ group_values.append([val])
+ last_ax=axis
+
+ # average the line segments that are within the merge_distance of one another
+ axis_values=[max(val)forvalingroup_values]
+ common_axes=[]
+ forax_group,grp_valsinzip(axes_groups,group_values):
+ iflen(ax_group)==1:
+ common_axes.append(ax_group[0])
+ else:
+ index_max=max(range(len(grp_vals)),key=grp_vals.__getitem__)
+ common_axes.append(ax_group[index_max])
+ returncommon_axes,axis_values
+
+
+ @staticmethod
+ def_bounding_domain_x(geometries):
+"""Get minimum and maximum X coordinates of multiple polygons."""
+ min_x,max_x=geometries[0].min.x,geometries[0].max.x
+ forgeomingeometries[1:]:
+ ifgeom.min.x<min_x:
+ min_x=geom.min.x
+ ifgeom.max.x>max_x:
+ max_x=geom.max.x
+ returnmin_x,max_x
+
+ @staticmethod
+ def_bounding_domain_y(geometries):
+"""Get minimum and maximum Y coordinates of multiple polygons."""
+ min_y,max_y=geometries[0].min.y,geometries[0].max.y
+ forgeomingeometries[1:]:
+ ifgeom.min.y<min_y:
+ min_y=geom.min.y
+ ifgeom.max.y>max_y:
+ max_y=geom.max.y
+ returnmin_y,max_y
+
+ def_point_in_polygon(self,tolerance):
+"""Get a Point2D that is always reliably inside this Polygon2D.
+
+ The point will be close to the edge of the Polygon but it will always
+ be inside it for all concave geometries. Furthermore, it is relatively
+ fast compared with computing the pole_of_inaccessibility.
+ """
+ try:
+ poly=self.remove_colinear_vertices(tolerance)
+ move_vec,v_angle=self._inward_pointing_vec(poly)
+ except(AssertionError,ZeroDivisionError):# zero area Polygon2D; use center
+ returnself.center
+
+ move_vec=move_vec*((tolerance/math.sin(v_angle/2))+0.00001)
+ point_in_poly=poly.vertices[0]+move_vec
+ ifnotself.is_point_inside(point_in_poly):
+ point_in_poly=poly.vertices[0]-move_vec
+ returnpoint_in_poly
+
+ @staticmethod
+ def_inward_pointing_vec(polygon):
+"""Get a unit vector pointing inward/outward from the first vertex of the Polygon
+ """
+ v1=polygon.vertices[-1]-polygon.vertices[0]
+ v2=polygon.vertices[1]-polygon.vertices[0]
+ v_angle=v1.angle(v2)
+ ifv_angle==math.pi:# colinear vertices; prevent averaging to zero
+ rgt_ang=math.pi/2
+ returnv1.rotate(rgt_ang).normalize(),rgt_ang
+ else:# average the two edge vectors together
+ avg_coords=((v1.x+v2.x)/2),((v1.y+v2.y)/2)
+ returnVector2D(*avg_coords).normalize(),v_angle
+
+ def_transfer_properties(self,new_polygon):
+"""Transfer properties from this polygon to a new polygon.
+
+ This is used by the transform methods that don't alter the relationship of
+ face vertices to one another (move, rotate, reflect).
+ """
+ new_polygon._perimeter=self._perimeter
+ new_polygon._area=self._area
+ new_polygon._is_convex=self._is_convex
+ new_polygon._is_self_intersecting=self._is_self_intersecting
+ new_polygon._is_clockwise=self._is_clockwise
+
+ @staticmethod
+ def_get_centroid_cell(polygon):
+"""Get a Cell object at the centroid of the Polygon2D."""
+ area=0
+ x=0
+ y=0
+ b=polygon[-1]# prev
+ forainpolygon:
+ f=a[0]*b[1]-b[0]*a[1]
+ x+=(a[0]+b[0])*f
+ y+=(a[1]+b[1])*f
+ area+=f*3
+ b=a
+ ifarea==0:
+ return_Cell(polygon[0][0],polygon[0][1],0,polygon)
+ return_Cell(x/area,y/area,0,polygon)
+
+ @staticmethod
+ def_insert_updates_in_order(polygon,polygon_updates):
+"""Insert updates from the intersect_segments method into a polygon.
+
+ This method ensures that multiple updates to a single segment are inserted
+ in the correct order over the polygon.
+
+ Args:
+ polygon: A Polygon2D to be updated with intersection points
+ polygon_updates: A list of tuples where each tuple has two values. The
+ first is the index of the segment to be updated and the second is
+ the point to insert.
+ """
+ polygon_updates.sort(key=lambdax:x[0])# sort updates by order of insertion
+ poly_points=list(polygon.vertices)# convert tuple to mutable list
+ last_i=-1
+ colinear_count=0
+ forupdateinpolygon_updates[::-1]:# traverse backwards to preserve order
+ new_i=update[0]+1
+ ifnew_i==last_i:# check order of new intersections on the same segment
+ colinear_count+=1
+ p1=poly_points[update[0]]
+ fori,ptinenumerate(poly_points[new_i:new_i+colinear_count]):
+ ifp1.distance_to_point(pt)>p1.distance_to_point(update[1]):
+ poly_points.insert(new_i+i,update[1])
+ break
+ else:
+ poly_points.insert(new_i+colinear_count,update[1])
+ else:
+ colinear_count=0
+ poly_points.insert(new_i,update[1])
+ last_i=new_i
+ returnPolygon2D(poly_points)
+
+ @staticmethod
+ def_segments_from_vertices(vertices):
+ _segs=[]
+ fori,vertinenumerate(vertices):
+ _seg=LineSegment2D.from_end_points(vertices[i-1],vert)
+ _segs.append(_seg)
+ _segs.append(_segs.pop(0))# segments will start from the first point
+ return_segs
+
+ @staticmethod
+ def_merge_boundary_and_holes(boundary,holes,split=False):
+"""Return a list of points for a boundary merged with all holes.
+
+ The holes are merged one-by-one using the shortest distance from all of
+ the holes to the boundary to ensure one hole's seam does not cross another.
+ The run time of this method scales linearly with the total number of
+ vertices, which makes it significantly better for shapes with many holes
+ compared to recursively calling the Polygon2D._merge_boundary_and_closest_hole
+ method. However, it is not nearly as efficient as the method used in
+ Polygon2D.from_shape_with_holes_fast, which is typically not as beautiful
+ of a result as this method.
+
+ Args:
+ boundary: A list of Point2D objects for the outer boundary inside of
+ which the hole is contained.
+ hole: A list of lists where each sub-list represents a hole and contains
+ several Point2D objects that represent the hole.
+ split: A boolean to note whether the last hole should be merged into
+ the boundary, effectively splitting the shape into two lists of
+ vertices instead of a single list. This is useful when trying to
+ translate a shape with holes to a platform that does not support
+ holes or struggles with single lists of vertices that wind inward
+ to cut out the holes since this option returns two "normal" concave
+ polygons. However, it is possible that the shape cannot be
+ reliably split this way and, in this case, this method will
+ return None. (Default: False).
+
+ Returns:
+ A single list of vertices with the holes merged into the boundary. When
+ split is True and the splitting is successful, this will be two lists
+ of vertices for the split shapes. If splitting was not successful,
+ this method will return None and, if a hole-less split shape is
+ still required, it is recommended that triangulation be used to get
+ the hole-less shapes.
+ """
+ # compute the initial distances between the holes and the boundary
+ original_boundary=boundary[:]
+ hole_dicts,min_dists=[],[]
+ forholeinholes:
+ dist_dict={}
+ fori,b_ptinenumerate(boundary):
+ forj,h_ptinenumerate(hole):
+ dist_dict[b_pt.distance_to_point(h_pt)]=[i,j]
+ hole_dicts.append(dist_dict)
+ min_dists.append(min(dist_dict.keys()))
+ # merge each hole into the boundary, moving progressively by minimum distance
+ final_hole_count=0ifnotsplitelse1
+ whilelen(holes)>final_hole_count:
+ # merge the hole into the boundary
+ hole_index=min_dists.index(min(min_dists))
+ boundary,old_hole,b_ind=Polygon2D._merge_boundary_and_hole_detailed(
+ boundary,holes[hole_index],hole_dicts[hole_index])
+ # remove the hole from the older lists
+ hole_dicts.pop(hole_index)
+ holes.pop(hole_index)
+ # update the hole_dicts based on the new boundary
+ add_ind=len(old_hole)
+ forhdinhole_dicts:
+ forind_listinhd.values():
+ ifind_list[0]>b_ind:
+ ind_list[0]+=add_ind
+ # add the distances from the old hole to the remaining holes to hole_dicts
+ old_hole_ind=[b_ind+iforiinrange(add_ind)]
+ forhole,dist_dictinzip(holes,hole_dicts):
+ forbi,b_ptinzip(old_hole_ind,old_hole):
+ forj,h_ptinenumerate(hole):
+ dist_dict[b_pt.distance_to_point(h_pt)]=[bi,j]
+ # generated an updated min_dists list
+ min_dists=[min(dist_dict.keys())fordist_dictinhole_dicts]
+ ifnotsplit:
+ returnboundary
+
+ # sort the distances to find the closest point
+ last_hd=hole_dicts[0]
+ sort_dist=sorted(last_hd.keys())
+ # find the closest connection between the hole and the original boundary polygon
+ p1_indices=dist_dict[sort_dist[0]]
+ p2_index=1
+ p2_indices=dist_dict[sort_dist[p2_index]]
+ p2_bound_pt=boundary[p2_indices[0]]
+ whilep2_bound_ptnotinoriginal_boundary:
+ p2_index+=1
+ p2_indices=dist_dict[sort_dist[p2_index]]
+ p2_bound_pt=boundary[p2_indices[0]]
+ p2_hole_pt=hole[p2_indices[1]]
+ # merge the hole into the boundary
+ hole_deque=deque(hole)
+ hole_deque.rotate(-p1_indices[1])
+ hole_insert=[boundary[p1_indices[0]]]+list(hole_deque)+ \
+ [hole[p1_indices[1]]]
+ boundary[p1_indices[0]:p1_indices[0]]=hole_insert
+ # use the second most distant points to split the shape
+ p2_bound_i=boundary.index(p2_bound_pt)
+ p2_hole_i=boundary.index(p2_hole_pt)
+ ifp2_hole_i<p2_bound_i:
+ boundary_1=boundary[p2_hole_i:p2_bound_i+1]
+ boundary_2=boundary[:p2_hole_i+1]+boundary[p2_bound_i:]
+ else:
+ boundary_1=boundary[p2_bound_i:p2_hole_i+1]
+ boundary_2=boundary[:p2_bound_i+1]+boundary[p2_hole_i:]
+ poly_1,poly_2=Polygon2D(boundary_1),Polygon2D(boundary_2)
+
+ # if the split polygons are self-intersecting, try to find a solution
+ p2_index=0
+ whilepoly_1.is_self_intersectingorpoly_2.is_self_intersecting:
+ p2_index+=1
+ try:
+ p2_indices=dist_dict[sort_dist[p2_index]]
+ exceptIndexError:# no solution was found; just return None
+ returnNone
+ p2_bound_pt=boundary[p2_indices[0]]
+ p2_hole_pt=hole[p2_indices[1]]
+ p2_bound_i=boundary.index(p2_bound_pt)
+ p2_hole_i=boundary.index(p2_hole_pt)
+ ifp2_hole_i<p2_bound_i:
+ boundary_1=boundary[p2_hole_i:p2_bound_i+1]
+ boundary_2=boundary[:p2_hole_i+1]+boundary[p2_bound_i:]
+ else:
+ boundary_1=boundary[p2_bound_i:p2_hole_i+1]
+ boundary_2=boundary[:p2_bound_i+1]+boundary[p2_hole_i:]
+ try:
+ poly_1,poly_2=Polygon2D(boundary_1),Polygon2D(boundary_2)
+ exceptAssertionError:
+ pass# the polygons are not valid; keep searching
+ returnboundary_1,boundary_2
+
+ @staticmethod
+ def_merge_boundary_and_hole_detailed(boundary,hole,dist_dict):
+"""Create a single list of points with a hole and boundary.
+
+ This method will also return the newly-added vertices of the hole as
+ well as the index of where the hole was inserted in the larger boundary.
+
+ Args:
+ boundary: A list of Point2D objects for the outer boundary inside of
+ which the hole is contained.
+ hole: A list of Point2D objects for the hole.
+ dist_dict: A dictionary with keys of distances between each of the points
+ in the boundary and hole lists and values as tuples with two values:
+ (the index of the boundary point, the index of the hole point)
+
+ Returns:
+ A tuple with three values
+
+ - boundary: A single list of vertices with the input hole merged
+ into the boundary.
+
+ - hole_insert: A list of vertices representing the hole that has
+ been inserted into the boundary.
+
+ - insert_index: An integer for where the hole was inserted in the
+ boundary.
+ """
+ min_dist=min(dist_dict.keys())
+ min_indexes=dist_dict[min_dist]
+ hole_deque=deque(hole)
+ hole_deque.rotate(-min_indexes[1])
+ hole_insert=[boundary[min_indexes[0]]]+list(hole_deque)+ \
+ [hole[min_indexes[1]]]
+ boundary[min_indexes[0]:min_indexes[0]]=hole_insert
+ insert_index=min_indexes[0]
+ returnboundary,hole_insert,insert_index
+
+ @staticmethod
+ def_merge_boundary_and_closest_hole(boundary,holes):
+"""Return a list of points for a boundary merged with the closest hole."""
+ hole_dicts=[]
+ min_dists=[]
+ forholeinholes:
+ dist_dict={}
+ fori,b_ptinenumerate(boundary):
+ forj,h_ptinenumerate(hole):
+ dist_dict[b_pt.distance_to_point(h_pt)]=(i,j)
+ hole_dicts.append(dist_dict)
+ min_dists.append(min(dist_dict.keys()))
+ hole_index=min_dists.index(min(min_dists))
+ new_boundary=Polygon2D._merge_boundary_and_hole(
+ boundary,holes[hole_index],hole_dicts[hole_index])
+ holes.pop(hole_index)
+ returnnew_boundary,holes
+
+ @staticmethod
+ def_merge_boundary_and_hole(boundary,hole,dist_dict):
+"""Create a single list of points describing a boundary shape with a hole.
+
+ Args:
+ boundary: A list of Point2D objects for the outer boundary inside of
+ which the hole is contained.
+ hole: A list of Point2D objects for the hole.
+ dist_dict: A dictionary with keys of distances between each of the points
+ in the boundary and hole lists and values as tuples with two values:
+ (the index of the boundary point, the index of the hole point)
+ """
+ min_dist=min(dist_dict.keys())
+ min_indexes=dist_dict[min_dist]
+ hole_deque=deque(hole)
+ hole_deque.rotate(-min_indexes[1])
+ hole_insert=[boundary[min_indexes[0]]]+list(hole_deque)+ \
+ [hole[min_indexes[1]]]
+ boundary[min_indexes[0]:min_indexes[0]]=hole_insert
+ returnboundary
+
+ @staticmethod
+ def_are_clockwise(vertices):
+"""Check if a list of vertices are clockwise.
+
+ This is a quicker calculation when all you need is the direction and not area.
+ """
+ _a=0
+ fori,ptinenumerate(vertices):
+ _a+=vertices[i-1].x*pt.y-vertices[i-1].y*pt.x
+ return_a<0
+
+ def__copy__(self):
+ _new_poly=Polygon2D(self._vertices)
+ _new_poly._segments=self._segments
+ _new_poly._perimeter=self._perimeter
+ _new_poly._area=self._area
+ _new_poly._is_clockwise=self._is_clockwise
+ _new_poly._is_convex=self._is_convex
+ _new_poly._is_self_intersecting=self._is_self_intersecting
+ return_new_poly
+
+ def__key(self):
+"""A tuple based on the object properties, useful for hashing."""
+ returntuple(hash(pt)forptinself._vertices)
+
+ def__hash__(self):
+ returnhash(self.__key())
+
+ def__eq__(self,other):
+ returnisinstance(other,Polygon2D)andself.__key()==other.__key()
+
+ def__repr__(self):
+ return'Polygon2D ({} vertices)'.format(len(self))
+
+
+
+class_Cell(object):
+"""2D cell object used in certain Polygon computations (eg. pole_of_inaccessibility).
+
+ Args:
+ x: The X coordinate of the cell origin.
+ y: The Y coordinate of the cell origin.
+ h: The dimension of the cell.
+ polygon: An array representation of a Polygon2D.
+
+ Properties:
+ * x
+ * y
+ * h
+ * d
+ * max
+ """
+ __slots__=('x','y','h','d','max')
+
+ def__init__(self,x,y,h,polygon):
+ self.h=h
+ self.y=y
+ self.x=x
+ self.d=self._point_to_polygon_distance(x,y,polygon)
+ self.max=self.d+self.h*math.sqrt(2)
+
+ def_point_to_polygon_distance(self,x,y,polygon):
+"""Get the distance from an X,Y point to the edge of a Polygon."""
+ inside=False
+ min_dist_sq=inf
+
+ b=polygon[-1]
+ forainpolygon:
+
+ if(a[1]>y)!=(b[1]>y)and \
+ (x<(b[0]-a[0])*(y-a[1])/(b[1]-a[1])+a[0]):
+ inside=notinside
+
+ min_dist_sq=min(min_dist_sq,self._get_seg_dist_sq(x,y,a,b))
+ b=a
+
+ result=math.sqrt(min_dist_sq)
+ ifnotinside:
+ return-result
+ returnresult
+
+ @staticmethod
+ def_get_seg_dist_sq(px,py,a,b):
+"""Get the squared distance from a point to a segment."""
+ x=a[0]
+ y=a[1]
+ dx=b[0]-x
+ dy=b[1]-y
+
+ ifdx!=0ordy!=0:
+ t=((px-x)*dx+(py-y)*dy)/(dx*dx+dy*dy)
+
+ ift>1:
+ x=b[0]
+ y=b[1]
+
+ elift>0:
+ x+=dx*t
+ y+=dy*t
+
+ dx=px-x
+ dy=py-y
+
+ returndx*dx+dy*dy
+
+ def__lt__(self,other):
+ returnself.max<other.max
+
+ def__lte__(self,other):
+ returnself.max<=other.max
+
+ def__gt__(self,other):
+ returnself.max>other.max
+
+ def__gte__(self,other):
+ returnself.max>=other.max
+
+ def__eq__(self,other):
+ returnself.max==other.max
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/_modules/ladybug_geometry/geometry2d/polyline.html b/docs/_modules/ladybug_geometry/geometry2d/polyline.html
new file mode 100644
index 00000000..59c12653
--- /dev/null
+++ b/docs/_modules/ladybug_geometry/geometry2d/polyline.html
@@ -0,0 +1,1604 @@
+
+
+
+
+
+
+ ladybug_geometry.geometry2d.polyline — ladybug geometry documentation
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+[docs]
+classPolyline2D(Base2DIn2D):
+"""2D polyline object.
+
+ Args:
+ vertices: A list of Point2D objects representing the vertices of the polyline.
+ interpolated: Boolean to note whether the polyline should be interpolated
+ between the input vertices when it is translated to other interfaces.
+ Note that this property has no bearing on the geometric calculations
+ performed by this library and is only present in order to assist with
+ display/translation.
+
+ Properties:
+ * vertices
+ * segments
+ * min
+ * max
+ * center
+ * p1
+ * p2
+ * length
+ * is_self_intersecting
+ * interpolated
+ """
+ __slots__=('_interpolated','_segments','_length','_is_self_intersecting')
+
+ def__init__(self,vertices,interpolated=False):
+"""Initialize Polyline2D."""
+ Base2DIn2D.__init__(self,vertices)
+ self._interpolated=interpolated
+ self._segments=None
+ self._length=None
+ self._is_self_intersecting=None
+
+
+[docs]
+ @classmethod
+ deffrom_dict(cls,data):
+"""Create a Polyline2D from a dictionary.
+
+ Args:
+ data: A python dictionary in the following format.
+
+ .. code-block:: python
+
+ {
+ "type": "Polyline2D",
+ "vertices": [(0, 0), (10, 0), (0, 10)]
+ }
+ """
+ interp=data['interpolated']if'interpolated'indataelseFalse
+ returncls(tuple(Point2D.from_array(pt)forptindata['vertices']),interp)
+
+
+
+[docs]
+ @classmethod
+ deffrom_array(cls,point_array):
+"""Create a Polyline2D from a nested array of vertex coordinates.
+
+ Args:
+ point_array: Nested array of point arrays.
+ """
+ returnPolyline2D(Point2D(*point)forpointinpoint_array)
+
+
+
+[docs]
+ @classmethod
+ deffrom_polygon(cls,polygon):
+"""Create a closed Polyline2D from a Polygon2D.
+
+ Args:
+ polygon: A Polygon2D object to be converted to a Polyline2D.
+ """
+ returnPolyline2D(polygon.vertices+(polygon.vertices[0],))
+
+
+ @property
+ defsegments(self):
+"""Tuple of all line segments in the polyline."""
+ ifself._segmentsisNone:
+ self._segments= \
+ tuple(LineSegment2D.from_end_points(vert,self._vertices[i+1])
+ fori,vertinenumerate(self._vertices[:-1]))
+ returnself._segments
+
+ @property
+ deflength(self):
+"""The length of the polyline."""
+ ifself._lengthisNone:
+ self._length=sum([seg.lengthforseginself.segments])
+ returnself._length
+
+ @property
+ defp1(self):
+"""Starting point of the Polyline2D."""
+ returnself._vertices[0]
+
+ @property
+ defp2(self):
+"""End point of the Polyline2D."""
+ returnself._vertices[-1]
+
+ @property
+ defis_self_intersecting(self):
+"""Boolean noting whether the polyline has self-intersecting segments."""
+ ifself._is_self_intersectingisNone:
+ self._is_self_intersecting=False
+ _segs=self.segments
+ fori,_sinenumerate(_segs[1:len(_segs)-1]):
+ _skip=(i,i+1,i+2)
+ _other_segs=[xforj,xinenumerate(_segs)ifjnotin_skip]
+ for_oth_sin_other_segs:
+ if_s.intersect_line_ray(_oth_s)isnotNone:# intersection!
+ self._is_self_intersecting=True
+ break
+ ifself._is_self_intersectingisTrue:
+ break
+ returnself._is_self_intersecting
+
+ @property
+ definterpolated(self):
+"""Boolean noting whether the polyline should be interpolated upon translation.
+
+ Note that this property has no bearing on the geometric calculations
+ performed by this library and is only present in order to assist with
+ display/translation.
+ """
+ returnself._interpolated
+
+
+[docs]
+ defis_closed(self,tolerance):
+"""Test whether this polyline is closed to within the tolerance.
+
+ Args:
+ tolerance: The minimum difference between vertices below which vertices
+ are considered the same.
+ """
+ returnself._vertices[0].is_equivalent(self._vertices[-1],tolerance)
+
+
+
+[docs]
+ defremove_colinear_vertices(self,tolerance):
+"""Get a version of this polyline without colinear or duplicate vertices.
+
+ Args:
+ tolerance: The minimum distance that a vertex can be from a line
+ before it is considered colinear.
+ """
+ iflen(self.vertices)==3:
+ returnself# Polyline2D cannot have fewer than 3 vertices
+ new_vertices=[self.vertices[0]]# first vertex is always ok
+ skip=0# track the number of vertices being skipped/removed
+ # loop through vertices and remove all cases of colinear verts
+ fori,_vinenumerate(self.vertices[1:-1]):
+ _a=self[i-skip].determinant(_v)+_v.determinant(self[i+2])+ \
+ self[i+2].determinant(self[i-skip])
+ ifabs(_a)>=tolerance:
+ new_vertices.append(_v)
+ skip=0
+ else:
+ skip+=1
+ new_vertices.append(self[-1])# last vertex is always ok
+ _new_poly=Polyline2D(new_vertices)
+ self._transfer_properties(_new_poly)
+ return_new_poly
+
+
+
+[docs]
+ defreverse(self):
+"""Get a copy of this polyline where the vertices are reversed."""
+ _new_poly=Polyline2D(tuple(ptforptinreversed(self.vertices)))
+ self._transfer_properties(_new_poly)
+ return_new_poly
+
+
+
+[docs]
+ defmove(self,moving_vec):
+"""Get a polyline that has been moved along a vector.
+
+ Args:
+ moving_vec: A Vector2D with the direction and distance to move the polyline.
+ """
+ _new_poly=Polyline2D(tuple(pt.move(moving_vec)forptinself.vertices))
+ self._transfer_properties(_new_poly)
+ return_new_poly
+
+
+
+[docs]
+ defrotate(self,angle,origin):
+"""Get a polyline that is rotated counterclockwise by a certain angle.
+
+ Args:
+ angle: An angle for rotation in radians.
+ origin: A Point2D for the origin around which the point will be rotated.
+ """
+ _new_poly=Polyline2D(tuple(pt.rotate(angle,origin)forptinself.vertices))
+ self._transfer_properties(_new_poly)
+ return_new_poly
+
+
+
+[docs]
+ defreflect(self,normal,origin):
+"""Get a polyline reflected across a plane with the input normal and origin.
+
+ Args:
+ normal: A Vector2D representing the normal vector for the plane across
+ which the polyline will be reflected. THIS VECTOR MUST BE NORMALIZED.
+ origin: A Point2D representing the origin from which to reflect.
+ """
+ _new_poly=Polyline2D(tuple(pt.reflect(normal,origin)forptinself.vertices))
+ self._transfer_properties(_new_poly)
+ return_new_poly
+
+
+
+[docs]
+ defscale(self,factor,origin=None):
+"""Scale a polyline by a factor from an origin point.
+
+ Args:
+ factor: A number representing how much the polyline should be scaled.
+ origin: A Point2D representing the origin from which to scale.
+ If None, it will be scaled from the World origin (0, 0).
+ """
+ iforiginisNone:
+ _new_poly=Polyline2D(tuple(
+ Point2D(pt.x*factor,pt.y*factor)forptinself.vertices))
+ else:
+ _new_poly=Polyline2D(tuple(
+ pt.scale(factor,origin)forptinself.vertices))
+ _new_poly._interpolated=self._interpolated
+ return_new_poly
+
+
+
+[docs]
+ defoffset(self,distance,check_intersection=False):
+"""Offset the polyline by a given distance.
+
+ Note that the resulting shape may be self-intersecting if the distance
+ is large enough and the is_self_intersecting property may be used to identify
+ these shapes.
+
+ Args:
+ distance: The distance that the polyline will be offset. Both positive
+ and negative values are accepted with positive values being offset
+ to the left of the polyline line and negative values being offset
+ to the right of the polyline (starting from the first polyline point
+ and continuing down the polyline).
+ check_intersection: A boolean to note whether the resulting operation
+ should be checked for self intersection and, if so, None will be
+ returned instead of the self-intersecting polyline.
+ """
+ # make sure the offset is not zero
+ ifdistance==0:
+ returnself
+
+ # loop through the vertices and get the new offset vectors
+ middle_verts=list(self._vertices[1:-1])
+ iflen(middle_verts)!=1:
+ middle_verts=[ptfori,ptinenumerate(middle_verts)
+ ifpt!=middle_verts[i-1]]
+ all_verts=[self._vertices[0]]+middle_verts+[self._vertices[-1]]
+ move_vec_st=self.segments[0].v.rotate(math.pi/2).normalize()*distance
+ move_vecs=[move_vec_st]
+ fori,ptinenumerate(middle_verts):
+ v1=all_verts[i]-pt
+ v2=all_verts[i+2]-pt
+ ang=v1.angle_counterclockwise(v2)/2
+ ifang==0:
+ ang=math.pi/2
+ m_vec=v1.rotate(ang).normalize()
+ m_dist=-distance/math.sin(ang)
+ m_vec=m_vec*m_dist
+ move_vecs.append(m_vec)
+ move_vec_end=self.segments[-1].v.rotate(math.pi/2).normalize()*distance
+ move_vecs.append(move_vec_end)
+
+ # move the vertices by the offset to create the new Polygon2D
+ new_pts=tuple(pt.move(m_vec)forpt,m_vecinzip(all_verts,move_vecs))
+ new_poly=Polyline2D(new_pts,self.interpolated)
+
+ # check for self intersection between the moving vectors if requested
+ ifcheck_intersection:
+ poly_segs=new_poly.segments
+ _segs=[LineSegment2D(p,v)forp,vinzip(all_verts,move_vecs)]
+ _skip=(0,len(_segs)-1)
+ _other_segs=[xforj,xinenumerate(poly_segs)ifjnotin_skip]
+ for_oth_sin_other_segs:
+ if_segs[0].intersect_line_ray(_oth_s)isnotNone:# intersection!
+ returnNone
+ fori,_sinenumerate(_segs[1:len(_segs)]):
+ _skip=(i,i+1)
+ _other_segs=[xforj,xinenumerate(poly_segs)ifjnotin_skip]
+ for_oth_sin_other_segs:
+ if_s.intersect_line_ray(_oth_s)isnotNone:# intersection!
+ returnNone
+ returnnew_poly
+
+
+
+[docs]
+ defintersect_line_ray(self,line_ray):
+"""Get the intersections between this polyline and a Ray2D or LineSegment2D.
+
+ Args:
+ line_ray: A LineSegment2D or Ray2D or to intersect.
+
+ Returns:
+ A list with Point2D objects for the intersections.
+ List will be empty if no intersection exists.
+ """
+ intersections=[]
+ for_sinself.segments:
+ inters=intersect_line2d(_s,line_ray)
+ ifintersisnotNone:
+ intersections.append(inters)
+ returnintersections
+
+
+
+[docs]
+ defintersect_line_infinite(self,ray):
+"""Get the intersections between this polyline and a Ray2D extended infinitely.
+
+ Args:
+ ray: A Ray2D or to intersect. This will be extended in both
+ directions infinitely for the intersection.
+
+ Returns:
+ A list with Point2D objects for the intersections.
+ List will be empty if no intersection exists.
+ """
+ intersections=[]
+ for_sinself.segments:
+ inters=intersect_line2d_infinite(_s,ray)
+ ifintersisnotNone:
+ intersections.append(inters)
+ returnintersections
+
+
+
+[docs]
+ defto_dict(self):
+"""Get Polyline2D as a dictionary."""
+ base={'type':'Polyline2D',
+ 'vertices':[pt.to_array()forptinself.vertices]}
+ ifself.interpolated:
+ base['interpolated']=self.interpolated
+ returnbase
+
+
+
+[docs]
+ defto_array(self):
+"""Get a list of lists where each sub-list represents a Point2D vertex."""
+ returntuple(pt.to_array()forptinself.vertices)
+
+
+
+[docs]
+ defto_polygon(self,tolerance):
+"""Get a Polygon2D derived from this object.
+
+ If the polyline is closed to within the tolerance, the segments of this
+ polyline and the resulting polygon will match. Otherwise, an extra
+ LineSegment2D will be added to connect the start and end of the polyline.
+
+ Args:
+ tolerance: The minimum difference between vertices below which vertices
+ are considered the same.
+ """
+ from.polygonimportPolygon2D# must be imported here to avoid circular import
+ ifself.is_closed(tolerance):
+ returnPolygon2D(self._vertices[:-1])
+ returnPolygon2D(self._vertices)
+
+
+
+[docs]
+ @staticmethod
+ defjoin_segments(segments,tolerance):
+"""Get an array of Polyline2Ds from a list of LineSegment2Ds.
+
+ Args:
+ segments: An array of LineSegment2D objects.
+ tolerance: The minimum difference in X, Y, and Z values at which Point2Ds
+ are considered equivalent. Segments with points that match within the
+ tolerance will be joined.
+
+ Returns:
+ An array of Polyline2D and LineSegment2D objects assembled from the
+ joined segments.
+ """
+ # group the vertices that make up polylines
+ grouped_verts=_group_vertices(segments,tolerance)
+
+ # create the Polyline2D and LineSegment2D objects
+ joined_lines=[]
+ forv_listingrouped_verts:
+ iflen(v_list)==2:
+ joined_lines.append(LineSegment2D.from_end_points(v_list[0],v_list[1]))
+ else:
+ joined_lines.append(Polyline2D(v_list))
+ returnjoined_lines
+
+
+ def_transfer_properties(self,new_polyline):
+"""Transfer properties from this polyline to a new polyline."""
+ new_polyline._interpolated=self._interpolated
+ new_polyline._length=self._length
+ new_polyline._is_self_intersecting=self._is_self_intersecting
+
+ def__copy__(self):
+ returnPolyline2D(self._vertices,self._interpolated)
+
+ def__key(self):
+"""A tuple based on the object properties, useful for hashing."""
+ returntuple(hash(pt)forptinself._vertices)+(self._interpolated,)
+
+ def__hash__(self):
+ returnhash(self.__key())
+
+ def__eq__(self,other):
+ returnisinstance(other,Polyline2D)andself.__key()==other.__key()
+
+ def__repr__(self):
+ return'Polyline2D ({} vertices)'.format(len(self))
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/_modules/ladybug_geometry/geometry2d/ray.html b/docs/_modules/ladybug_geometry/geometry2d/ray.html
new file mode 100644
index 00000000..eb9c28b8
--- /dev/null
+++ b/docs/_modules/ladybug_geometry/geometry2d/ray.html
@@ -0,0 +1,1285 @@
+
+
+
+
+
+
+ ladybug_geometry.geometry2d.ray — ladybug geometry documentation
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+[docs]
+classRay2D(Base1DIn2D):
+"""2D Ray object.
+
+ Args:
+ p: A Point2D representing the base of the ray.
+ v: A Vector2D representing the direction of the ray.
+
+ Properties:
+ * p
+ * v
+ * min
+ * max
+ * center
+ """
+ __slots__=()
+
+ def__init__(self,p,v):
+"""Initialize Ray2D."""
+ Base1DIn2D.__init__(self,p,v)
+
+
+[docs]
+ @classmethod
+ deffrom_array(cls,ray_array):
+""" Create a Ray2D from a nested array with a point and a vector.
+
+ Args:
+ ray_array: Nested tuples ((p.x, p.y), (v.x, v.y)).
+ """
+ returnRay2D(Point2D(*ray_array[0]),Vector2D(*ray_array[1]))
+
+
+
+[docs]
+ defreverse(self):
+"""Get a copy of this ray that is reversed."""
+ returnRay2D(self.p,self.v.reverse())
+
+
+
+[docs]
+ defmove(self,moving_vec):
+"""Get a ray that has been moved along a vector.
+
+ Args:
+ moving_vec: A Vector2D with the direction and distance to move the ray.
+ """
+ returnRay2D(self.p.move(moving_vec),self.v)
+
+
+
+[docs]
+ defrotate(self,angle,origin):
+"""Get a ray that is rotated counterclockwise by a certain angle.
+
+ Args:
+ angle: An angle for rotation in radians.
+ origin: A Point2D for the origin around which the ray will be rotated.
+ """
+ returnRay2D(self.p.rotate(angle,origin),self.v.rotate(angle))
+
+
+
+[docs]
+ defreflect(self,normal,origin):
+"""Get a ray reflected across a plane with the input normal vector and origin.
+
+ Args:
+ normal: A Vector2D representing the normal vector for the plane across
+ which the ray will be reflected. THIS VECTOR MUST BE NORMALIZED.
+ origin: A Point2D representing the origin from which to reflect.
+ """
+ returnRay2D(self.p.reflect(normal,origin),self.v.reflect(normal))
+
+
+
+[docs]
+ defscale(self,factor,origin=None):
+"""Scale a ray by a factor from an origin point.
+
+ Args:
+ factor: A number representing how much the ray should be scaled.
+ origin: A Point2D representing the origin from which to scale.
+ If None, it will be scaled from the World origin (0, 0).
+ """
+ returnRay2D(self.p.scale(factor,origin),self.v*factor)
+
+
+
+[docs]
+ defto_dict(self):
+"""Get Ray2D as a dictionary."""
+ base=Base1DIn2D.to_dict(self)
+ base['type']='Ray2D'
+ returnbase
+
+
+
+[docs]
+ defto_array(self):
+"""A nested array representing the start point and vector."""
+ return(self.p.to_array(),self.v.to_array())
+[docs]
+classArc3D(object):
+"""3D arc object.
+
+ Args:
+ plane: A Plane in which the arc lies with an origin representing the
+ center of the circle for the arc.
+ radius: A number representing the radius of the arc.
+ a1: A number between 0 and 2 * pi for the start angle of the arc.
+ a2: A number between 0 and 2 * pi for the end angle of the arc.
+
+ Properties:
+ * plane
+ * radius
+ * a1
+ * a2
+ * p1
+ * p2
+ * midpoint
+ * c
+ * min
+ * max
+ * length
+ * angle
+ * is_circle
+ * is_inverted
+ * arc2d
+ """
+ __slots__=('_plane','_arc2d','_min','_max')
+
+ def__init__(self,plane,radius,a1=0,a2=2*math.pi):
+"""Initialize Arc3D."""
+ assertisinstance(plane,Plane),"Expected Plane. Got {}.".format(type(plane))
+ self._plane=plane
+ self._arc2d=Arc2D(Point2D(0,0),radius,a1,a2)
+ self._min=None
+ self._max=None
+
+
+[docs]
+ @classmethod
+ deffrom_dict(cls,data):
+"""Create a Arc3D from a dictionary.
+
+ Args:
+ data: A python dictionary in the following format
+
+ .. code-block:: python
+
+ {
+ "type": "Arc3D"
+ "plane": {"n": (0, 0, 1), "o": (0, 10, 0), "x": (1, 0, 0)},
+ "radius": 5,
+ "a1": 0,
+ "a2": 3.14159
+ }
+ """
+ returncls(Plane.from_dict(data['plane']),data['radius'],
+ data['a1'],data['a2'])
+
+
+
+[docs]
+ @classmethod
+ deffrom_start_mid_end(cls,p1,m,p2,circle=False):
+"""Initialize a new arc from start, middle, and end points.
+
+ Note that input points will be assumed to be in counterclockwise order.
+
+ Args:
+ p1: The start point of the arc.
+ m: Any point along the length of the arc that is not the start or end.
+ p2: The end point of the arc.
+ circle: Set to True if you would like the output to be a full circle
+ defined by the three points instead of an arc with a start and end.
+ Default is False.
+ """
+ plane=cls._plane_from_vertices(p1,m,p2)
+ p1_2d,m_2d,p2_2d=plane.xyz_to_xy(p1),plane.xyz_to_xy(m),plane.xyz_to_xy(p2)
+ arc_2d=Arc2D.from_start_mid_end(p1_2d,m_2d,p2_2d,circle)
+ returncls(Plane(plane.n,plane.xy_to_xyz(arc_2d.c),plane.x),
+ arc_2d.r,arc_2d.a1,arc_2d.a2)
+
+
+
+[docs]
+ @classmethod
+ deffrom_arc2d(cls,arc2d,z=0):
+"""Initialize a new Arc3D from an Arc2D and a z value.
+
+ Args:
+ arc2d: An Arc2D to be used to generate the Arc3D.
+ z: A number for the Z coordinate value of the arc.
+ """
+ plane=Plane(o=Point3D(arc2d.c.x,arc2d.c.y,z))
+ returncls(plane,arc2d.r,arc2d.a1,arc2d.a2)
+
+
+ @property
+ defplane(self):
+"""A Plane in which the arc lies with an origin for the center of the arc."""
+ returnself._plane
+
+ @property
+ defradius(self):
+"""Radius of arc."""
+ returnself._arc2d.r
+
+ @property
+ defa1(self):
+"""Start angle of the arc in radians."""
+ returnself._arc2d.a1
+
+ @property
+ defa2(self):
+"""End angle of the arc in radians."""
+ returnself._arc2d.a2
+
+ @property
+ defp1(self):
+"""Start point."""
+ returnself.plane.xy_to_xyz(self.arc2d.p1)
+
+ @property
+ defp2(self):
+"""End point."""
+ returnself.plane.xy_to_xyz(self.arc2d.p2)
+
+ @property
+ defmidpoint(self):
+"""Midpoint."""
+ returnself.point_at(0.5)
+
+ @property
+ defc(self):
+"""Center point of the circle on which the arc lies."""
+ returnself.plane.o
+
+ @property
+ defmin(self):
+"""A Point3D for the minimum bounding box vertex around this geometry."""
+ ifself._minisNone:
+ self._calculate_min_max()
+ returnself._min
+
+ @property
+ defmax(self):
+"""A Point3D for the maximum bounding box vertex around this geometry."""
+ ifself._maxisNone:
+ self._calculate_min_max()
+ returnself._max
+
+ @property
+ deflength(self):
+"""The length of the arc."""
+ returnself.angle*self.radius
+
+ @property
+ defangle(self):
+"""The total angle over the domain of the arc in radians."""
+ _diff=self.a2-self.a1
+ return_diffifnotself.is_invertedelse2*math.pi+_diff
+
+ @property
+ defarea(self):
+"""Area of the circle to which the arc belongs."""
+ assertself.is_circle,'Arc must be a closed circle to access "area" property.'
+ returnmath.pi*self.radius**2
+
+ @property
+ defis_circle(self):
+"""Boolean for whether the arc is a full circle (True) or not (False)."""
+ returnself.a1==0andself.a2==2*math.pi
+
+ @property
+ defis_inverted(self):
+"""Boolean noting whether the end angle a2 is smaller than the start angle a1."""
+ returnself.a2<self.a1
+
+ @property
+ defarc2d(self):
+"""An Arc2D within the plane of the Arc3D."""
+ returnself._arc2d
+
+
+[docs]
+ defmove(self,moving_vec):
+"""Get an arc that has been moved along a vector.
+
+ Args:
+ moving_vec: A Vector3D with the direction and distance to move the arc.
+ """
+ returnArc3D(self.plane.move(moving_vec),self.radius,self.a1,self.a2)
+
+
+
+[docs]
+ defrotate(self,axis,angle,origin):
+"""Rotate this arc by a certain angle around an axis and origin.
+
+ Right hand rule applies:
+ If axis has a positive orientation, rotation will be clockwise.
+ If axis has a negative orientation, rotation will be counterclockwise.
+
+ Args:
+ axis: A Vector3D axis representing the axis of rotation.
+ angle: An angle for rotation in radians.
+ origin: A Point3D for the origin around which the object will be rotated.
+ """
+ returnArc3D(self.plane.rotate(axis,angle,origin),
+ self.radius,self.a1,self.a2)
+
+
+
+[docs]
+ defrotate_xy(self,angle,origin):
+"""Get a arc that is rotated counterclockwise in the world XY plane by a certain angle.
+
+ Args:
+ angle: An angle for rotation in radians.
+ origin: A Point3D for the origin around which the arc will be rotated.
+ """
+ returnArc3D(self.plane.rotate_xy(angle,origin),self.radius,self.a1,self.a2)
+
+
+
+[docs]
+ defreflect(self,normal,origin):
+"""Get a arc reflected across a plane with the input normal vector and origin.
+
+ Args:
+ normal: A Vector3D representing the normal vector for the plane across
+ which the arc will be reflected. THIS VECTOR MUST BE NORMALIZED.
+ origin: A Point3D representing the origin from which to reflect.
+ """
+ arc2d=self.arc2d.reflect(Vector2D(0,1),Point2D(0,0))
+ returnArc3D(self.plane.reflect(normal,origin),self.radius,arc2d.a1,arc2d.a2)
+
+
+
+[docs]
+ defscale(self,factor,origin=None):
+"""Scale a arc by a factor from an origin point.
+
+ Args:
+ factor: A number representing how much the arc should be scaled.
+ origin: A Point2D representing the origin from which to scale.
+ If None, it will be scaled from the World origin (0, 0, 0).
+ """
+ returnArc3D(self.plane.scale(factor,origin),self.radius*factor,
+ self.a1,self.a2)
+
+
+
+[docs]
+ defsubdivide(self,distances):
+"""Get Point3D values along the arc that subdivide it based on input distances.
+
+ Args:
+ distances: A list of distances along the arc at which to subdivide it.
+ This can also be a single number that will be repeated until the
+ end of the arc.
+ """
+ return[self.plane.xy_to_xyz(pt)forptinself.arc2d.subdivide(distances)]
+
+
+
+[docs]
+ defsubdivide_evenly(self,number):
+"""Get Point3D values along the arc that divide it into evenly-spaced segments.
+
+ Args:
+ number: The number of segments into which the arc will be divided.
+ """
+ return[self.plane.xy_to_xyz(pt)forptinself.arc2d.subdivide_evenly(number)]
+
+
+
+[docs]
+ defpoint_at(self,parameter):
+"""Get a point at a given fraction along the arc.
+
+ Args:
+ parameter: The fraction between the start and end point where the
+ desired point lies. For example, 0.5 will yield the midpoint.
+ """
+ returnself.plane.xy_to_xyz(self.arc2d.point_at(parameter))
+
+
+
+[docs]
+ defpoint_at_angle(self,angle):
+"""Get a point at a given angle along the arc.
+
+ Args:
+ angle: The angle in radians from the start point along the arc
+ to get the Point3D.
+ """
+ returnself.plane.xy_to_xyz(self.arc2d.point_at_angle(angle))
+
+
+
+[docs]
+ defpoint_at_length(self,length):
+"""Get a point at a given distance along the arc segment.
+
+ Args:
+ length: The distance along the arc from the start point where the
+ desired point lies.
+ """
+ returnself.point_at(length/self.length)
+
+
+
+[docs]
+ defclosest_point(self,point):
+"""Get the closest Point3D on this object to another Point3D.
+
+ Args:
+ point: A Point3D object to which the closest point on this object
+ will be computed.
+
+ Returns:
+ Point3D for the closest point on this line to the input point.
+ """
+ plane_pt=self.plane.closest_point(point)
+ returnself.plane.xy_to_xyz(
+ self.arc2d.closest_point(self.plane.xyz_to_xy(plane_pt)))
+
+
+
+[docs]
+ defdistance_to_point(self,point):
+"""Get the minimum distance between this object and the input point.
+
+ Args:
+ point: A Point3D object to which the minimum distance will be computed.
+
+ Returns:
+ The distance to the input point.
+ """
+ close_pt=self.closest_point(point)
+ returnpoint.distance_to_point(close_pt)
+
+
+
+[docs]
+ defintersect_plane(self,plane):
+"""Get the intersection between this Arc3D and a Plane.
+
+ Args:
+ plane: A Plane that will be intersected with this arc.
+
+ Returns:
+ A list of Point3D objects if the intersection was successful.
+ None if no intersection exists.
+ """
+ _plane_int_ray=plane.intersect_plane(self.plane)
+ if_plane_int_rayisnotNone:
+ _p12d=self.plane.xyz_to_xy(_plane_int_ray.p)
+ _p22d=self.plane.xyz_to_xy(_plane_int_ray.p+_plane_int_ray.v)
+ _v2d=_p22d-_p12d
+ _int_ray2d=Ray2D(_p12d,_v2d)
+ _int_pt2d=self.arc2d.intersect_line_infinite(_int_ray2d)
+ if_int_pt2disnotNone:
+ return[self.plane.xy_to_xyz(pt)forptin_int_pt2d]
+ returnNone
+
+
+
+[docs]
+ defsplit_with_plane(self,plane):
+"""Split this Arc3D in 2 or 3 smaller arcs using a Plane.
+
+ Args:
+ plane: A Plane that will be used to split this arc.
+
+ Returns:
+ A list with two or three Arc3D objects if the split was successful.
+ Will be a list with 1 Arc3D if no intersection exists.
+ """
+ _plane_int_ray=plane.intersect_plane(self.plane)
+ if_plane_int_rayisnotNone:
+ _p12d=self.plane.xyz_to_xy(_plane_int_ray.p)
+ _p22d=self.plane.xyz_to_xy(_plane_int_ray.p+_plane_int_ray.v)
+ _v2d=_p22d-_p12d
+ _int_ray2d=Ray2D(_p12d,_v2d)
+ _int_pt2d=self.arc2d.split_line_infinite(_int_ray2d)
+ iflen(_int_pt2d)!=1:
+ return[Arc3D(self.plane,self.radius,arc.a1,arc.a2)
+ forarcin_int_pt2d]
+ return[self]
+
+
+
+[docs]
+ defto_polyline(self,divisions,interpolated=True):
+"""Get this Arc3D as an approximated Polyline3D.
+
+ Args:
+ divisions: The number of segments into which the arc will be divided.
+ interpolated: Boolean to note whether the polyline should be interpolated
+ between the input vertices when it is translated to other interfaces.
+ This property has no effect on the geometric calculations performed
+ by this library and is only present in order to assist with
+ display/translation. (Default: True)
+ """
+ pts=self.subdivide_evenly(divisions)
+ returnPolyline3D(pts,interpolated)
+
+
+
+[docs]
+ defto_dict(self):
+"""Get Arc3D as a dictionary."""
+ return{'type':'Arc3D','plane':self.plane.to_dict(),
+ 'radius':self.radius,'a1':self.a1,'a2':self.a2}
+
+
+
+[docs]
+ defduplicate(self):
+"""Get a copy of this object."""
+ returnself.__copy__()
+
+
+ def_calculate_min_max(self):
+"""Calculate maximum and minimum Point3D for this object.
+
+ At this point in time, this method only calculates the bounding box
+ around the circle of the arc using the formula here.
+ https://stackoverflow.com/questions/2592011/\
+ bounding-boxes-for-circle-and-arcs-in-3d
+ """
+ ifself.is_circle:
+ o,r=self._plane.o,self.radius
+ ax=self._plane.n.angle(Vector3D(1,0,0))
+ ay=self._plane.n.angle(Vector3D(0,1,0))
+ az=self._plane.n.angle(Vector3D(0,0,1))
+ r_vec=(math.sin(ax)*r,math.sin(ay)*r,math.sin(az)*r)
+ self._min=Point3D(o.x-r_vec[0],o.y-r_vec[1],o.z-r_vec[2])
+ self._max=Point3D(o.x+r_vec[0],o.y+r_vec[1],o.z+r_vec[2])
+ else:# get the min and max of the Arc2D
+ min_pt2d,max_pt2d=self._arc2d.min,self._arc2d.max
+ self._min=self.plane.xy_to_xyz(min_pt2d)
+ self._max=self.plane.xy_to_xyz(max_pt2d)
+
+ @staticmethod
+ def_plane_from_vertices(pt1,pt2,pt3):
+"""Get a plane from three vertices."""
+ try:
+ v1=pt2-pt1
+ v2=pt3-pt1
+ n=v1.cross(v2)
+ exceptExceptionase:
+ raiseValueError('Incorrect Point3D input for Arc3D:\n\t{}'.format(e))
+ returnPlane(n,pt1)
+
+ def__copy__(self):
+ returnArc3D(self.plane,self.radius,self.a1,self.a2)
+
+ def__key(self):
+"""A tuple based on the object properties, useful for hashing."""
+ return(hash(self.plane),self.radius,self.a1,self.a2)
+
+ def__hash__(self):
+ returnhash(self.__key())
+
+ def__eq__(self,other):
+ returnisinstance(other,Arc3D)andself.__key()==other.__key()
+
+ def__ne__(self,other):
+ returnnotself.__eq__(other)
+
+
+[docs]
+classCone(object):
+"""Cone object.
+
+ Args:
+ vertex: A Point3D at the tip of the cone.
+ axis: A Vector3D representing the direction and height of the cone.
+ The vector extends from the vertex to the center of the base.
+ angle: An angle in radians representing the half angle between
+ the axis and the surface.
+
+ Properties:
+ * vertex
+ * axis
+ * angle
+ * height
+ * slant_height
+ * radius
+ * area
+ * volume
+ * min
+ * max
+ * base
+ """
+ __slots__=('_vertex','_axis','_angle','_base','_min','_max')
+
+ def__init__(self,vertex,axis,angle):
+"""Initialize Cone."""
+ assertisinstance(vertex,Point3D), \
+ "Expected Point3D. Got {}.".format(type(vertex))
+ assertisinstance(axis,Vector3D), \
+ "Expected Vector3D. Got {}.".format(type(axis))
+ assertangle>0,'Cone angle must be greater than 0. Got {}.'.format(angle)
+ self._vertex=vertex
+ self._axis=axis
+ self._angle=angle
+ self._base=None
+ self._min=None
+ self._max=None
+
+
+[docs]
+ @classmethod
+ deffrom_dict(cls,data):
+"""Create a Cone from a dictionary.
+
+ Args:
+ data: A python dictionary in the following format
+
+ .. code-block:: python
+
+ {
+ "type": "Cone"
+ "vertex": (10, 0, 0),
+ "axis": (0, 0, 1),
+ "angle": 1.0
+ }
+ """
+ returncls(Point3D.from_array(data['vertex']),
+ Vector3D.from_array(data['axis']),
+ data['angle'])
+
+
+ @property
+ defvertex(self):
+"""Vertex of cone."""
+ returnself._vertex
+
+ @property
+ defaxis(self):
+"""Axis of cone."""
+ returnself._axis
+
+ @property
+ defangle(self):
+"""Angle of cone"""
+ returnself._angle
+
+ @property
+ defheight(self):
+"""Height of cone"""
+ returnself.axis.magnitude
+
+ @property
+ defradius(self):
+"""Radius of a cone"""
+ returnself.height*math.tan(self.angle)
+
+ @property
+ defslant_height(self):
+"""Slant height of a cone"""
+ returnmath.sqrt(self.radius**2+self.height**2)
+
+ @property
+ defarea(self):
+"""Surface area of a cone"""
+ returnmath.pi*self.radius**2+math.pi*self.radius*self.slant_height
+
+ @property
+ defvolume(self):
+"""Volume of a cone"""
+ return1/3*math.pi*self.radius**2*self.height
+
+ @property
+ defbase(self):
+"""Get an Arc3D representing the circular base of the cone."""
+ ifself._baseisNone:
+ plane=Plane(self.axis.reverse(),self.vertex+self.axis)
+ self._base=Arc3D(plane,self.radius)
+ returnself._base
+
+ @property
+ defmin(self):
+"""A Point3D for the minimum bounding box vertex around this geometry."""
+ ifself._minisNone:
+ self._calculate_min_max()
+ returnself._min
+
+ @property
+ defmax(self):
+"""A Point3D for the maximum bounding box vertex around this geometry."""
+ ifself._maxisNone:
+ self._calculate_min_max()
+ returnself._max
+
+
+[docs]
+ defmove(self,moving_vec):
+"""Get a cone that has been moved along a vector.
+
+ Args:
+ moving_vec: A Vector3D with the direction and distance to move the cone.
+ """
+ returnCone(self.vertex.move(moving_vec),self.axis,self.angle)
+
+
+
+[docs]
+ defrotate(self,axis,angle,origin):
+"""Rotate this cone by a certain angle around an axis and origin.
+
+ Right hand rule applies:
+ If axis has a positive orientation, rotation will be clockwise.
+ If axis has a negative orientation, rotation will be counterclockwise.
+
+ Args:
+ axis: A Vector3D axis representing the axis of rotation.
+ angle: An angle for rotation in radians.
+ origin: A Point3D for the origin around which the cone will be rotated.
+ """
+ returnCone(self.vertex.rotate(axis,angle,origin),
+ self.axis.rotate(axis,angle),
+ self.angle)
+
+
+
+[docs]
+ defrotate_xy(self,angle,origin):
+"""Get a cone that is rotated counterclockwise in the world XY plane by an angle.
+
+ Args:
+ angle: An angle for rotation in radians.
+ origin: A Point3D for the origin around which the cone will be rotated.
+ """
+ returnCone(self.vertex.rotate_xy(angle,origin),
+ self.axis.rotate_xy(angle),
+ self.angle)
+
+
+
+[docs]
+ defreflect(self,normal,origin):
+"""Get a cone reflected across a plane with the input normal vector and origin.
+
+ Args:
+ normal: A Vector3D representing the normal vector for the plane across
+ which the arc will be reflected. THIS VECTOR MUST BE NORMALIZED.
+ origin: A Point3D representing the origin from which to reflect.
+ """
+ returnCone(self.vertex.reflect(normal,origin),
+ self.axis.reflect(normal),
+ self.angle)
+
+
+
+[docs]
+ defscale(self,factor,origin=None):
+"""Scale a cone by a factor from an origin point.
+
+ Args:
+ factor: A number representing how much the cone should be scaled.
+ origin: A Point3D representing the origin from which to scale.
+ If None, it will be scaled from the World origin (0, 0, 0).
+ """
+ returnCone(self.vertex.scale(factor,origin),
+ self.axis*factor,
+ self.angle)
+
+
+
+[docs]
+ defduplicate(self):
+"""Get a copy of this object."""
+ returnself.__copy__()
+
+
+
+[docs]
+ defto_dict(self):
+"""Get Cone as a dictionary."""
+ return{
+ 'type':'Cone',
+ 'vertex':self.vertex.to_array(),
+ 'axis':self.axis.to_array(),
+ 'angle':self.angle
+ }
+
+
+ def_calculate_min_max(self):
+"""Calculate maximum and minimum Point3D for this object."""
+ base=self.base
+ bmn,bmx,ver=base.min,base.max,self.vertex
+ self._min=Point3D(min(bmn.x,ver.x),min(bmn.y,ver.y),min(bmn.z,ver.z))
+ self._max=Point3D(max(bmx.x,ver.x),max(bmx.y,ver.y),max(bmx.z,ver.z))
+
+ def__copy__(self):
+ returnCone(self.vertex,self.axis,self.angle)
+
+ def__key(self):
+"""A tuple based on the object properties, useful for hashing."""
+ return(self._vertex,self._axis,self._angle)
+
+ def__hash__(self):
+ returnhash(self.__key())
+
+ def__eq__(self,other):
+ returnisinstance(other,Cone)andself.__key()==other.__key()
+
+ def__ne__(self,other):
+ returnnotself.__eq__(other)
+
+
+[docs]
+classCylinder(object):
+"""Cylinder object.
+
+ Args:
+ center: A Point3D at the center of the bottom base of the cylinder.
+ axis: A Vector3D representing the direction and height of the cylinder.
+ The vector extends from the bottom base center to the top base center.
+ radius: A number representing the radius of the cylinder.
+
+ Properties:
+ * center
+ * axis
+ * radius
+ * center_end
+ * diameter
+ * height
+ * area
+ * volume
+ * min
+ * max
+ * base_bottom
+ * base_top
+ """
+ __slots__=('_center','_axis','_radius',
+ '_base_bottom','_base_top','_min','_max')
+
+ def__init__(self,center,axis,radius):
+"""Initialize Cylinder."""
+ assertisinstance(center,Point3D), \
+ "Expected Point3D. Got {}.".format(type(center))
+ assertisinstance(axis,Vector3D), \
+ "Expected Vector3D. Got {}.".format(type(axis))
+ assertradius>0, \
+ 'Cylinder radius must be greater than 0. Got {}.'.format(radius)
+ self._center=center
+ self._axis=axis
+ self._radius=radius
+ self._base_bottom=None
+ self._base_top=None
+ self._min=None
+ self._max=None
+
+
+[docs]
+ @classmethod
+ deffrom_start_end(cls,p1,p2,radius):
+"""Initialize a new cylinder from start and end points.
+
+ Args:
+ p1: The start point of the cylinder, represents the center of the
+ bottom base of the cylinder.
+ p2: The end point of the cylinder, represents the center of the top
+ base of the cylinder
+ radius: A number representing the radius of the cylinder.
+ """
+ axis=p2-p1
+ returncls(p1,axis,radius)
+
+
+
+[docs]
+ @classmethod
+ deffrom_dict(cls,data):
+"""Create a Cylinder from a dictionary.
+
+ Args:
+ data: A python dictionary in the following format
+
+ .. code-block:: python
+
+ {
+ "type": "Cylinder"
+ "center": (10, 0, 0),
+ "axis": (0, 0, 1),
+ "radius": 1.0
+ }
+ """
+ returncls(Point3D.from_array(data['center']),
+ Vector3D.from_array(data['axis']),
+ data['radius'])
+
+
+ @property
+ defcenter(self):
+"""Center of Cylinder."""
+ returnself._center
+
+ @property
+ defaxis(self):
+"""Axis of Cylinder."""
+ returnself._axis
+
+ @property
+ defradius(self):
+"""Radius of Cylinder"""
+ returnself._radius
+
+ @property
+ defcenter_end(self):
+"""Center of the opposite end of Cylinder."""
+ returnself.center+self.axis
+
+ @property
+ defdiameter(self):
+"""Diameter of Cylinder"""
+ returnself.radius*2
+
+ @property
+ defheight(self):
+"""Height of Cylinder"""
+ returnself.axis.magnitude
+
+ @property
+ defarea(self):
+"""Surface area of a Cylinder"""
+ return2*math.pi*self.radius*self.height+2*math.pi*self.radius**2
+
+ @property
+ defvolume(self):
+"""Volume of a Cylinder"""
+ returnmath.pi*self.radius**2*self.height
+
+ @property
+ defbase_bottom(self):
+"""Get an Arc3D representing the bottom circular base of the cylinder."""
+ ifself._base_bottomisNone:
+ self._base_bottom=Arc3D(Plane(self.axis,self.center),self.radius)
+ returnself._base_bottom
+
+ @property
+ defbase_top(self):
+"""Get an Arc3D representing the top circular base of the cylinder."""
+ ifself._base_topisNone:
+ plane=Plane(self.axis,self.center+self.axis)
+ self._base_top=Arc3D(plane,self.radius)
+ returnself._base_top
+
+ @property
+ defmin(self):
+"""A Point3D for the minimum bounding box vertex around this geometry."""
+ ifself._minisNone:
+ self._calculate_min_max()
+ returnself._min
+
+ @property
+ defmax(self):
+"""A Point3D for the maximum bounding box vertex around this geometry."""
+ ifself._maxisNone:
+ self._calculate_min_max()
+ returnself._max
+
+
+[docs]
+ defmove(self,moving_vec):
+"""Get a Cylinder that has been moved along a vector.
+
+ Args:
+ moving_vec: A Vector3D with the direction and distance to move the Cylinder.
+ """
+ returnCylinder(self.center.move(moving_vec),self.axis,self.radius)
+
+
+
+[docs]
+ defrotate(self,axis,angle,origin):
+"""Rotate this Cylinder by a certain angle around an axis and origin.
+
+ Right hand rule applies:
+ If axis has a positive orientation, rotation will be clockwise.
+ If axis has a negative orientation, rotation will be counterclockwise.
+
+ Args:
+ axis: A Vector3D axis representing the axis of rotation.
+ angle: An angle for rotation in radians.
+ origin: A Point3D for the origin around which the cylinder will be rotated.
+ """
+ returnCylinder(self.center.rotate(axis,angle,origin),
+ self.axis.rotate(axis,angle),
+ self.radius)
+
+
+
+[docs]
+ defrotate_xy(self,angle,origin):
+"""Get a Cylinder that is rotated counterclockwise in the world XY plane by an angle.
+
+ Args:
+ angle: An angle for rotation in radians.
+ origin: A Point3D for the origin around which the cylinder will be rotated.
+ """
+ returnCylinder(self.center.rotate_xy(angle,origin),
+ self.axis.rotate_xy(angle),
+ self.radius)
+
+
+
+[docs]
+ defreflect(self,normal,origin):
+"""Get a Cylinder reflected across a plane with the input normal vector and origin.
+
+ Args:
+ normal: A Vector3D representing the normal vector for the plane across
+ which the arc will be reflected. THIS VECTOR MUST BE NORMALIZED.
+ origin: A Point3D representing the origin from which to reflect.
+ """
+ returnCylinder(self.center.reflect(normal,origin),
+ self.axis.reflect(normal),
+ self.radius)
+
+
+
+[docs]
+ defscale(self,factor,origin=None):
+"""Scale a Cylinder by a factor from an origin point.
+
+ Args:
+ factor: A number representing how much the Cylinder should be scaled.
+ origin: A Point3D representing the origin from which to scale.
+ If None, it will be scaled from the World origin (0, 0, 0).
+ """
+ returnCylinder(self.center.scale(factor,origin),
+ self.axis*factor,
+ self.radius*factor)
+
+
+
+[docs]
+ defduplicate(self):
+"""Get a copy of this object."""
+ returnself.__copy__()
+
+
+
+[docs]
+ defto_dict(self):
+"""Get Cylinder as a dictionary."""
+ return{
+ 'type':'Cylinder',
+ 'center':self.center.to_array(),
+ 'axis':self.axis.to_array(),
+ 'radius':self.radius
+ }
+
+
+ def_calculate_min_max(self):
+"""Calculate maximum and minimum Point3D for this object."""
+ base1,base2=self.base_bottom,self.base_top
+ b1mn,b1mx,b2mn,b2mx=base1.min,base1.max,base2.min,base2.max
+ self._min=Point3D(
+ min(b1mn.x,b2mn.x),min(b1mn.y,b2mn.y),min(b1mn.z,b2mn.z))
+ self._max=Point3D(
+ max(b1mx.x,b2mx.x),max(b1mx.y,b2mx.y),max(b1mx.z,b2mx.z))
+
+ def__copy__(self):
+ returnCylinder(self.center,self.axis,self.radius)
+
+ def__key(self):
+"""A tuple based on the object properties, useful for hashing."""
+ return(self._center,self._axis,self._radius)
+
+ def__hash__(self):
+ returnhash(self.__key())
+
+ def__eq__(self,other):
+ returnisinstance(other,Cylinder)andself.__key()==other.__key()
+
+ def__ne__(self,other):
+ returnnotself.__eq__(other)
+
+
+[docs]
+classFace3D(Base2DIn3D):
+"""Planar Face in 3D space.
+
+ Args:
+ boundary: A list or tuple of Point3D objects representing the outer
+ boundary vertices of the face.
+ plane: A Plane object indicating the plane in which the face exists.
+ If None, the Plane normal will automatically be calculated by
+ analyzing the input vertices and the origin of the plane will be
+ the first vertex of the input vertices. Default: None.
+ holes: Optional list of lists with one list for each hole in the face.
+ Each hole should be a list of at least 3 Point3D objects.
+ If None, it will be assumed that there are no holes in the face.
+ The boundary and holes are stored as separate lists of Point3Ds on the
+ `boundary` and `holes` properties of this object. However, the
+ `vertices` property will always contain all vertices across the shape.
+ For a Face3D that has holes, it will trace out a single shape that
+ turns inwards from the boundary to cut out the holes.
+ enforce_right_hand: Boolean to note whether a check should be run to
+ ensure that input vertices are counterclockwise within the input plane,
+ thereby enforcing the right-hand rule. By default, this is True
+ and ensures that all Face3D objects adhere to the right-hand rule.
+ It is recommended that this only be set to False in cases where you
+ are certain that the input vertices are counter-clockwise
+ within the input plane and you would like to avoid the extra
+ unnecessary check.
+
+ Properties:
+ * vertices
+ * plane
+ * boundary
+ * holes
+ * polygon2d
+ * boundary_polygon2d
+ * hole_polygon2d
+ * triangulated_mesh2d
+ * triangulated_mesh3d
+ * boundary_segments
+ * hole_segments
+ * normal
+ * min
+ * max
+ * center
+ * perimeter
+ * area
+ * centroid
+ * azimuth
+ * altitude
+ * tilt
+ * is_clockwise
+ * is_convex
+ * is_self_intersecting
+ * self_intersection_points
+ * is_valid
+ * has_holes
+ * upper_left_corner
+ * lower_left_corner
+ * upper_right_corner
+ * lower_right_corner
+ * upper_left_counter_clockwise_vertices
+ * lower_left_counter_clockwise_vertices
+ * lower_right_counter_clockwise_vertices
+ * upper_right_counter_clockwise_boundary
+ * upper_left_counter_clockwise_boundary
+ * lower_left_counter_clockwise_boundary
+ * lower_right_counter_clockwise_boundary
+ * upper_right_counter_clockwise_boundary
+ """
+ __slots__=('_plane','_polygon2d','_mesh2d','_mesh3d',
+ '_boundary','_holes','_boundary_segments','_hole_segments',
+ '_boundary_polygon2d','_hole_polygon2d',
+ '_perimeter','_area','_centroid',
+ '_is_convex','_is_self_intersecting')
+ HOLE_VERTEX_THRESHOLD=400# threshold at which faster hole merging method is used
+
+ def__init__(self,boundary,plane=None,holes=None,enforce_right_hand=True):
+"""Initialize Face3D."""
+ # process the boundary and plane inputs
+ self._boundary=self._check_vertices_input(boundary)
+ ifplaneisnotNone:
+ assertisinstance(plane,Plane),'Expected Plane for Face3D.' \
+ ' Got {}.'.format(type(plane))
+ else:
+ plane=self._plane_from_vertices(boundary)
+ self._plane=plane
+
+ # process boundary and holes input
+ ifholes:
+ assertisinstance(holes,(tuple,list)), \
+ 'holes should be a tuple or list. Got {}'.format(type(holes))
+ self._holes=tuple(
+ self._check_vertices_input(hole,'hole')forholeinholes)
+ # create a Polygon2D from the vertices
+ _boundary2d=[self._plane.xyz_to_xy(_v)for_vinboundary]
+ _holes2d=[[self._plane.xyz_to_xy(_v)for_vinhole]forholeinholes]
+ v_count=len(_boundary2d)# count the vertices for hole merging method
+ forhin_holes2d:
+ v_count+=len(h)
+ _polygon2d=Polygon2D.from_shape_with_holes_fast(_boundary2d,_holes2d) \
+ ifv_count>self.HOLE_VERTEX_THRESHOLDelse \
+ Polygon2D.from_shape_with_holes(_boundary2d,_holes2d)
+ # convert Polygon2D vertices to 3D to become the vertices of the face.
+ self._vertices=tuple(self._plane.xy_to_xyz(_v)
+ for_vin_polygon2d.vertices)
+ self._polygon2d=_polygon2d
+ else:
+ self._holes=None
+ self._vertices=self._boundary
+ self._polygon2d=None
+
+ # perform a check of vertex orientation and enforce counter clockwise vertices
+ ifenforce_right_handisTrue:
+ ifself.is_clockwiseisTrue:
+ self._boundary=tuple(reversed(self._boundary))
+ self._vertices=tuple(reversed(self._vertices))
+ ifself._polygon2disnotNone:
+ self._polygon2d=self._polygon2d.reverse()
+
+ # set other properties to None for now
+ self._mesh2d=None
+ self._mesh3d=None
+ self._boundary_polygon2d=None
+ self._hole_polygon2d=None
+ self._boundary_segments=None
+ self._hole_segments=None
+ self._min=None
+ self._max=None
+ self._center=None
+ self._perimeter=None
+ self._area=None
+ self._centroid=None
+ self._is_convex=None
+ self._is_self_intersecting=None
+
+
+[docs]
+ @classmethod
+ deffrom_array(cls,point_array):
+"""Create a Face3D from a nested array of vertex coordinates.
+
+ Args:
+ point_array: A nested array of arrays where each sub-array represents
+ a loop of the Face3D. The first array is the boundary and subsequent
+ arrays represent holes in the Face3D. point arrays. Each sub-array
+ is composed of arrays that each have a length of 3 and denote 3D
+ points that define the face.
+ """
+ boundary=tuple(Point3D(*point)forpointinpoint_array[0])
+ holes=Noneiflen(point_array)==1else \
+ tuple(tuple(Point3D(*point)forpointinhole)forholeinpoint_array[1:])
+ returncls(boundary,None,holes)
+
+
+
+[docs]
+ @classmethod
+ deffrom_extrusion(cls,line_segment,extrusion_vector):
+"""Initialize Face3D by extruding a line segment.
+
+ Initializing a face this way has the added benefit of having its
+ properties quickly computed.
+
+ Args:
+ line_segment: A LineSegment3D to be extruded.
+ extrusion_vector: A vector denoting the direction and distance to
+ extrude the line segment.
+ """
+ assertisinstance(line_segment,LineSegment3D), \
+ 'line_segment must be LineSegment3D. Got {}.'.format(type(line_segment))
+ assertisinstance(extrusion_vector,Vector3D), \
+ 'extrusion_vector must be Vector3D. Got {}.'.format(type(extrusion_vector))
+ _p1=line_segment.p1
+ _p2=line_segment.p2
+ _verts=(_p1,_p2,_p2+extrusion_vector,_p1+extrusion_vector)
+ _plane=Plane(line_segment.v.cross(extrusion_vector),_p1)
+ face=cls(_verts,_plane,enforce_right_hand=False)
+ _base=line_segment.length
+ _dist=extrusion_vector.magnitude
+ _height=_dist*math.sin(extrusion_vector.angle(line_segment.v))
+ face._perimeter=_base*2+_dist*2
+ face._area=_base*_height
+ face._centroid=_p1+(line_segment.v*0.5)+(extrusion_vector*0.5)
+ face._is_convex=True
+ face._is_self_intersecting=False
+ returnface
+
+
+
+[docs]
+ @classmethod
+ deffrom_rectangle(cls,base,height,base_plane=None):
+"""Initialize Face3D from rectangle parameters (base + height) and a base plane.
+
+ Initializing a face this way has the added benefit of having its
+ properties quickly computed.
+
+ Args:
+ base: A number indicating the length of the base of the rectangle.
+ height: A number indicating the length of the height of the rectangle.
+ base_plane: A Plane object in which the rectangle will be created.
+ The origin of this plane will be the lower left corner of the
+ rectangle and the X and Y axes will form the sides.
+ Default is the world XY plane.
+ """
+ assertisinstance(base,(float,int)),'Rectangle base must be a number.'
+ assertisinstance(height,(float,int)),'Rectangle height must be a number.'
+ ifbase_planeisnotNone:
+ assertisinstance(base_plane,Plane), \
+ 'base_plane must be Plane. Got {}.'.format(type(base_plane))
+ else:
+ base_plane=Plane(Vector3D(0,0,1),Point3D(0,0,0))
+ _o=base_plane.o
+ _b_vec=base_plane.x*base
+ _h_vec=base_plane.y*height
+ _verts=(_o,_o+_b_vec,_o+_h_vec+_b_vec,_o+_h_vec)
+ face=cls(_verts,base_plane,enforce_right_hand=False)
+ face._perimeter=base*2+height*2
+ face._area=base*height
+ face._centroid=_o+(_b_vec*0.5)+(_h_vec*0.5)
+ face._is_convex=True
+ face._is_self_intersecting=False
+ returnface
+
+
+
+[docs]
+ @classmethod
+ deffrom_regular_polygon(cls,side_count,radius=1,base_plane=None):
+"""Initialize Face3D from regular polygon parameters and a base_plane.
+
+ Args:
+ side_count: An integer for the number of sides on the regular
+ polygon. This number must be greater than 2.
+ radius: A number indicating the distance from the polygon's center
+ where the vertices of the polygon will lie.
+ The default is set to 1.
+ base_plane: A Plane object for the plane in which the face exists.
+ The origin of this plane will be used as the center of the polygon.
+ If None, the default will be the WorldXY plane.
+ """
+ # set the default base_plane
+ ifbase_planeisnotNone:
+ assertisinstance(base_plane,Plane),'Expected Plane. Got {}'.format(
+ type(base_plane))
+ else:
+ base_plane=Plane(Vector3D(0,0,1),Point3D(0,0,0))
+
+ # create the regular polygon face
+ _polygon2d=Polygon2D.from_regular_polygon(side_count,radius)
+ _vert3d=tuple(base_plane.xy_to_xyz(_v)for_vin_polygon2d.vertices)
+ _face=cls(_vert3d,base_plane,enforce_right_hand=False)
+
+ # assign extra properties that we know to the face
+ _face._polygon2d=_polygon2d
+ _face._center=base_plane.o
+ _face._centroid=base_plane.o
+ _face._is_convex=True
+ _face._is_self_intersecting=False
+ return_face
+
+
+
+[docs]
+ @classmethod
+ deffrom_punched_geometry(cls,base_face,sub_faces):
+"""Create a face with holes punched in it from sub-faces.
+
+ Args:
+ base_face: A Face3D that acts as a parent to the sub_faces, completely
+ encircling them.
+ sub_faces: A list of Face3D objects that will be punched into the
+ base_face. These faces must lie completely within the base_face
+ for the result to be valid. The is_sub_face() method can be
+ used to check sub_faces before they are input here.
+ """
+ assertisinstance(base_face,Face3D), \
+ 'base_face should be a Face3D. Got {}'.format(type(base_face))
+ forholeinsub_faces:
+ assertisinstance(hole,Face3D), \
+ 'sub_face should be a list. Got {}'.format(type(hole))
+ hole_verts=[list(sf.boundary)forsfinsub_faces]
+ ifbase_face.has_holes:
+ hole_verts.extend([list(h)forhinbase_face.holes])
+ returncls(base_face.boundary,base_face.plane,hole_verts,
+ enforce_right_hand=False)
+
+
+ @property
+ defvertices(self):
+"""Tuple of all vertices in this face.
+
+ Note that, in the case of a face with holes, some vertices will be repeated
+ since this property effectively traces out a single boundary around the
+ whole shape, winding inward to cut out the holes.
+ """
+ returnself._vertices
+
+ @property
+ defplane(self):
+"""Tuple of all vertices in this face."""
+ returnself._plane
+
+ @property
+ defpolygon2d(self):
+"""A Polygon2D of this face in the 2D space of the face's plane.
+
+ Note that this is a single polygon object even when there are holes in the
+ face since such a polygon can be made by drawing a line from the holes to
+ the outer boundary.
+ """
+ ifself._polygon2disNone:
+ _vert2d=tuple(self._plane.xyz_to_xy(_v)for_vinself.vertices)
+ self._polygon2d=Polygon2D(_vert2d)
+ returnself._polygon2d
+
+ @property
+ deftriangulated_mesh2d(self):
+"""A triangulated Mesh2D in the 2D space of the face's plane."""
+ ifself._mesh2disNone:
+ self._mesh2d=Mesh2D.from_polygon_triangulated(
+ self.boundary_polygon2d,self.hole_polygon2d)
+ returnself._mesh2d
+
+ @property
+ deftriangulated_mesh3d(self):
+"""A triangulated Mesh3D of this face."""
+ ifself._mesh3disNone:
+ _vert3d=tuple(self._plane.xy_to_xyz(_v)for_vin
+ self.triangulated_mesh2d.vertices)
+ self._mesh3d=Mesh3D(_vert3d,self.triangulated_mesh2d.faces)
+ returnself._mesh3d
+
+ @property
+ defboundary(self):
+"""Tuple of vertices on the boundary of this face.
+
+ For most Face3D objects, this will be identical to the vertices property.
+ However, when the Face3D has holes within it, this property stores
+ the outer boundary of the shape.
+ """
+ returnself._boundary
+
+ @property
+ defholes(self):
+"""Tuple with one tuple of vertices for each hole within this face.
+
+ This property will be None when the face has no holes in it.
+ """
+ returnself._holes
+
+ @property
+ defboundary_segments(self):
+"""Tuple of all line segments bordering the face.
+
+ Note that this does not include segments for any holes in the face.
+ Just the outer boundary.
+ """
+ ifself._boundary_segmentsisNone:
+ _segs=[]
+ fori,vertinenumerate(self.boundary):
+ _seg=LineSegment3D.from_end_points(self.boundary[i-1],vert)
+ _segs.append(_seg)
+ _segs.append(_segs.pop(0))# segments will start from the first vertex
+ self._boundary_segments=tuple(_segs)
+ returnself._boundary_segments
+
+ @property
+ defhole_segments(self):
+"""Tuple with a tuple of line segments for each hole in the face.
+
+ This will be None if there are no holes in the face.
+ """
+ ifself._holesisnotNoneandself._hole_segmentsisNone:
+ _all_segs=[]
+ forholeinself.holes:
+ _segs=[]
+ fori,vertinenumerate(hole):
+ _seg=LineSegment3D.from_end_points(hole[i-1],vert)
+ _segs.append(_seg)
+ _segs.append(_segs.pop(0))# segments will start from the first vertex
+ _all_segs.append(_segs)
+ self._hole_segments=tuple(tuple(_s)for_sin_all_segs)
+ returnself._hole_segments
+
+ @property
+ defboundary_polygon2d(self):
+"""A Polygon2D of the face boundary in the 2D space of the face's plane.
+
+ Note that this does not include any holes in the face. Just the outer boundary.
+ """
+ ifself._boundary_polygon2disNone:
+ _vert2d=tuple(self._plane.xyz_to_xy(_v)for_vinself.boundary)
+ self._boundary_polygon2d=Polygon2D(_vert2d)
+ returnself._boundary_polygon2d
+
+ @property
+ defhole_polygon2d(self):
+"""A list of Polygon2D for the face holes in the 2D space of the face's plane.
+ """
+ ifself._holesisnotNoneandself._hole_polygon2disNone:
+ self._hole_polygon2d=[]
+ forholeinself.holes:
+ _vert2d=tuple(self._plane.xyz_to_xy(_v)for_vinhole)
+ self._hole_polygon2d.append(Polygon2D(_vert2d))
+ returnself._hole_polygon2d
+
+ @property
+ defnormal(self):
+"""Normal vector for the plane in which the face exists."""
+ returnself._plane.n
+
+ @property
+ defperimeter(self):
+"""The perimeter of the face. This includes the length of holes in the face."""
+ ifself._perimeterisNone:
+ self._perimeter=sum([seg.lengthforseginself.boundary_segments])
+ ifself._holesisnotNone:
+ forholeinself.hole_segments:
+ self._perimeter+=sum([seg.lengthforseginhole])
+ returnself._perimeter
+
+ @property
+ defarea(self):
+"""The area of the face."""
+ ifself._areaisNone:
+ self._area=self.polygon2d.area
+ returnself._area
+
+ @property
+ defcentroid(self):
+"""The centroid of the face as a Point3D (aka. center of mass).
+
+ Note that the centroid is more time consuming to compute than the center
+ (or the middle point of the face bounding box). So the center might be
+ preferred over the centroid if you just need a rough point for the middle
+ of the face.
+ """
+ ifself._centroidisNone:
+ _cent2d=self.triangulated_mesh2d.centroid
+ self._centroid=self._plane.xy_to_xyz(_cent2d)
+ returnself._centroid
+
+ @property
+ defazimuth(self):
+"""Get the azimuth of the Face3D (between 0 and 2 * Pi).
+
+ This will be zero if the Face3D is perfectly horizontal.
+ """
+ returnself.plane.azimuth
+
+ @property
+ defaltitude(self):
+"""Get the altitude of the Face3D. Between Pi/2 (up) and -Pi/2 (down)."""
+ returnself.plane.altitude
+
+ @property
+ deftilt(self):
+"""Get the tilt of the Face3D. Between 0 (up) and Pi (down)."""
+ returnself.plane.tilt
+
+ @property
+ defis_clockwise(self):
+"""Boolean for whether the face vertices and boundary are in clockwise order.
+
+ Note that all Face3D objects should have counterclockwise vertices (meaning
+ that this property should always be False). This property exists largely
+ for testing / debugging purposes.
+ """
+ returnself.polygon2d.is_clockwise
+
+ @property
+ defis_convex(self):
+"""Boolean noting whether the face is convex (True) or non-convex (False).
+
+ Note that any face with holes will be automatically considered non-convex
+ since the underlying polygon_2d is always non-convex in this case.
+ """
+ ifself._is_convexisNone:
+ self._is_convex=self.polygon2d.is_convex
+ returnself._is_convex
+
+ @property
+ defis_self_intersecting(self):
+"""Boolean noting whether the face has self-intersecting edges.
+
+ Note that this property is relatively computationally intense to obtain compared
+ to properties like area and is_convex. Also, most CAD programs forbid geometry
+ with self-intersecting edges. So it is recommended that this property only
+ be used in quality control scripts where the origin of the geometry is unknown.
+ """
+ ifself._is_self_intersectingisNone:
+ self._is_self_intersecting=False
+ ifself.boundary_polygon2d.is_self_intersecting:
+ self._is_self_intersecting=True
+ ifself.has_holes:
+ forhpinself.hole_polygon2d:
+ ifhp.is_self_intersecting:
+ self._is_self_intersecting=True
+ break
+ returnself._is_self_intersecting
+
+ @property
+ defself_intersection_points(self):
+"""A tuple of Point3Ds for the locations where the Face3D intersects itself.
+
+ This will be an empty tuple if the Face3D is not self-intersecting and it
+ is generally recommended that the Face3D.is_self_intersecting property
+ be checked before using this property.
+ """
+ ifself.is_self_intersecting:
+ int_pts=[]
+ forpt2inself.boundary_polygon2d.self_intersection_points:
+ int_pts.append(self.plane.xy_to_xyz(pt2))
+ ifself.has_holes:
+ forhpinself.hole_polygon2d:
+ forpt2inhp.self_intersection_points:
+ int_pts.append(self.plane.xy_to_xyz(pt2))
+ returntuple(int_pts)
+ return()
+
+ @property
+ defis_valid(self):
+"""Boolean noting whether the face is valid (having a non-zero area).
+
+ Note that faces are still considered valid if they have out-of-plane vertices,
+ self-intersecting edges, or duplicate/colinear vertices. The check_planar
+ method can be used to detect if there are out-of-plane vertices. The
+ is_self_intersecting property identifies self-intersecting edges, and the
+ remove_colinear_vertices method will remove duplicate/colinear vertices."""
+ returnnotself.area==0
+
+ @property
+ defhas_holes(self):
+"""Boolean noting whether the face has holes within it."""
+ returnself._holesisnotNone
+
+ @property
+ defupper_left_corner(self):
+"""Get the vertex in the upper-left corner of the face's bounding box."""
+ returnself._corner_point('min','max')
+
+ @property
+ deflower_left_corner(self):
+"""Get the vertex in the lower-left corner of the face's bounding box."""
+ returnself._corner_point('min','min')
+
+ @property
+ defupper_right_corner(self):
+"""Get the vertex in the upper-right corner of the face's bounding box."""
+ returnself._corner_point('max','max')
+
+ @property
+ deflower_right_corner(self):
+"""Get the vertex in the lower-right corner of the face's bounding box."""
+ returnself._corner_point('max','min')
+
+ @property
+ defupper_left_counter_clockwise_vertices(self):
+"""Get face vertices starting from the upper left and moving counterclockwise.
+
+ Horizontal faces will treat the positive Y axis as up. All other faces
+ treat the positive Z axis as up.
+ """
+ corner_pt,polygon=self._corner_point_and_polygon(self._vertices,'min','max')
+ verts3d,verts2d=self._counter_clockwise_verts(polygon)
+ returnself._corner_pt_verts(corner_pt,verts3d,verts2d)
+
+ @property
+ deflower_left_counter_clockwise_vertices(self):
+"""Get face vertices starting from the lower left and moving counterclockwise.
+
+ Horizontal faces will treat the positive Y axis as up. All other faces
+ treat the positive Z axis as up.
+ """
+ corner_pt,polygon=self._corner_point_and_polygon(self._vertices,'min','min')
+ verts3d,verts2d=self._counter_clockwise_verts(polygon)
+ returnself._corner_pt_verts(corner_pt,verts3d,verts2d)
+
+ @property
+ deflower_right_counter_clockwise_vertices(self):
+"""Get face vertices starting from the lower left and moving counterclockwise.
+
+ Horizontal faces will treat the positive Y axis as up. All other faces
+ treat the positive Z axis as up.
+ """
+ corner_pt,polygon=self._corner_point_and_polygon(self._vertices,'max','min')
+ verts3d,verts2d=self._counter_clockwise_verts(polygon)
+ returnself._corner_pt_verts(corner_pt,verts3d,verts2d)
+
+ @property
+ defupper_right_counter_clockwise_vertices(self):
+"""Get face vertices starting from the lower left and moving counterclockwise.
+
+ Horizontal faces will treat the positive Y axis as up. All other faces
+ treat the positive Z axis as up.
+ """
+ corner_pt,polygon=self._corner_point_and_polygon(self._vertices,'max','max')
+ verts3d,verts2d=self._counter_clockwise_verts(polygon)
+ returnself._corner_pt_verts(corner_pt,verts3d,verts2d)
+
+ @property
+ defupper_left_counter_clockwise_boundary(self):
+"""Get face boundary starting from the upper left and moving counterclockwise.
+
+ Horizontal faces will treat the positive Y axis as up. All other faces
+ treat the positive Z axis as up.
+ """
+ corner_pt,polygon=self._corner_point_and_polygon(self._boundary,'min','max')
+ verts3d,verts2d=self._counter_clockwise_bound(polygon)
+ returnself._corner_pt_verts(corner_pt,verts3d,verts2d)
+
+ @property
+ deflower_left_counter_clockwise_boundary(self):
+"""Get face boundary starting from the lower left and moving counterclockwise.
+
+ Horizontal faces will treat the positive Y axis as up. All other faces
+ treat the positive Z axis as up.
+ """
+ corner_pt,polygon=self._corner_point_and_polygon(self._boundary,'min','min')
+ verts3d,verts2d=self._counter_clockwise_bound(polygon)
+ returnself._corner_pt_verts(corner_pt,verts3d,verts2d)
+
+ @property
+ deflower_right_counter_clockwise_boundary(self):
+"""Get face boundary starting from the lower left and moving counterclockwise.
+
+ Horizontal faces will treat the positive Y axis as up. All other faces
+ treat the positive Z axis as up.
+ """
+ corner_pt,polygon=self._corner_point_and_polygon(self._boundary,'max','min')
+ verts3d,verts2d=self._counter_clockwise_bound(polygon)
+ returnself._corner_pt_verts(corner_pt,verts3d,verts2d)
+
+ @property
+ defupper_right_counter_clockwise_boundary(self):
+"""Get face boundary starting from the lower left and moving counterclockwise.
+
+ Horizontal faces will treat the positive Y axis as up. All other faces
+ treat the positive Z axis as up.
+ """
+ corner_pt,polygon=self._corner_point_and_polygon(self._boundary,'max','max')
+ verts3d,verts2d=self._counter_clockwise_bound(polygon)
+ returnself._corner_pt_verts(corner_pt,verts3d,verts2d)
+
+
+[docs]
+ defpole_of_inaccessibility(self,tolerance):
+"""Get the pole of inaccessibility for the Face3D.
+
+ The pole of inaccessibility is the most distant internal point from the
+ Face3D outline. It is not to be confused with the centroid, which
+ represents the "center of mass" of the shape and may be outside of
+ the Face3D if the shape is concave. The poly of inaccessibility is
+ useful for optimal placement of a text label on the Face3D.
+
+ Args:
+ tolerance: The precision to which the pole of inaccessibility
+ will be computed.
+ """
+ returnself.plane.xy_to_xyz(self.polygon2d.pole_of_inaccessibility(tolerance))
+
+
+
+[docs]
+ defis_horizontal(self,tolerance):
+"""Check whether a this face is horizontal within a given tolerance.
+
+ Args:
+ tolerance: The minimum difference between the coordinate values of two
+ vertices at which they can be considered equivalent.
+
+ Returns:
+ True if the face is horizontal. False if it is not.
+ """
+ returnself.max.z-self.min.z<=tolerance
+
+
+
+[docs]
+ defis_coplanar(self,face,tolerance):
+"""Check whether a this face is coplanar with another given tolerance.
+
+ This method will only evaluate the distance between the other face's
+ vertices and this face's plane so it does not rely on a check based
+ on angle tolerance.
+
+ Args:
+ face: A neighboring Face3D for which co-planarity will be checked.
+ tolerance: The minimum difference between the coordinate values of two
+ vertices at which they can be considered equivalent.
+
+ Returns:
+ True if the face is coplanar with this one. False if it is not.
+ """
+ forptinface.vertices:
+ ifself.plane.distance_to_point(pt)>tolerance:
+ returnFalse
+ returnTrue
+
+
+
+[docs]
+ defis_geometrically_equivalent(self,face,tolerance):
+"""Check whether a given face is geometrically equivalent to this Face.
+
+ Geometrical equivalence is defined as being coplanar with this face,
+ having the same number of vertices, and having each vertex map-able between
+ the faces. Clockwise relationships do not have to match nor does the normal
+ direction of the face. However, all other properties must be matching to
+ within the input tolerance.
+
+ This is useful for identifying matching surfaces when solving for adjacency
+ and you need to ensure that two faces match perfectly in their area and vertices.
+ Note that you may also want to use the remove_colinear_vertices() method
+ on input faces before using this method in order to count faces with the
+ same non-colinear vertices as geometrically equivalent.
+
+ Args:
+ face: Another face for which geometric equivalency will be tested.
+ tolerance: The minimum difference between the coordinate values of two
+ vertices at which they can be considered geometrically equivalent.
+
+ Returns:
+ True if geometrically equivalent. False if not geometrically equivalent.
+ """
+ # rule out surfaces if they don't fit key criteria
+ ifnotself.center.is_equivalent(face.center,tolerance):
+ returnFalse
+ iflen(self.vertices)!=len(face.vertices):
+ returnFalse
+
+ # see if we can find a matching vertex
+ match_i=None
+ fori,ptinenumerate(self.vertices):
+ ifpt.is_equivalent(face[0],tolerance):
+ match_i=iifi!=len(self.vertices)-1else-1
+ break
+
+ # check equivalency of each vertex
+ ifmatch_iisNone:
+ returnFalse
+ elifself[match_i-1].is_equivalent(face[1],tolerance):
+ foriinxrange(len(self.vertices)):
+ ifself[match_i-i].is_equivalent(face[i],tolerance)isFalse:
+ returnFalse
+ elifself[match_i+1].is_equivalent(face[1],tolerance):
+ foriinxrange(0,-len(self.vertices),-1):
+ ifself[match_i+i].is_equivalent(face[i],tolerance)isFalse:
+ returnFalse
+ else:
+ returnFalse
+ returnTrue
+
+
+
+[docs]
+ defis_centered_adjacent(self,face,tolerance):
+"""Check whether a given face is centered adjacent with this Face.
+
+ Centered adjacency is defined as sharing the same center point as this face
+ and being next to one another to within the tolerance.
+
+ This is useful for identifying matching faces when you want to quickly
+ solve for adjacency and you are not concerned about false positives in cases
+ where one face does not perfectly match the other in terms of vertex ordering.
+
+ Args:
+ face: Another face for which centered adjacency will be tested.
+ tolerance: The minimum difference between the coordinate values of two
+ centers at which they can be considered centered adjacent.
+ Returns:
+ True if centered adjacent. False if not centered adjacent.
+ """
+ ifnotself.center.is_equivalent(face.center,tolerance):# center check
+ returnFalse
+ # construct a ray using this face's normal and a point just behind this face
+ point_on_face=self._point_on_face(tolerance)
+ point_on_face=point_on_face-(self.normal*tolerance)# move below
+ test_ray=Ray3D(point_on_face,self.normal)
+ # shoot ray from this face to the other to verify adjacency
+ ifface.intersect_line_ray(test_ray):
+ returnTrue
+ returnFalse
+
+
+
+[docs]
+ defis_overlapping(self,face,tolerance):
+"""Check whether a this face overlaps with another given tolerance.
+
+ Overlapping faces must not only be coplanar but they also have overlapping
+ polygons when evaluated within the same plane. Note that, if the face
+ is a sub-face of this one, this method will return True.
+
+ Args:
+ face: A neighboring Face3D for which overlaps will be checked.
+ tolerance: The minimum difference between the coordinate values of two
+ vertices at which they can be considered equivalent.
+
+ Returns:
+ True if the face is overlapping with this one. False if it is not.
+ """
+ ifnotself.is_coplanar(face,tolerance):
+ returnFalse
+ verts2d=tuple(self.plane.xyz_to_xy(_v)for_vinface.vertices)
+ other_poly=Polygon2D(verts2d)
+ ifself.polygon2d.polygon_relationship(other_poly,tolerance)==-1:
+ returnFalse
+ returnTrue
+
+
+
+[docs]
+ defis_sub_face(self,face,tolerance,angle_tolerance):
+"""Check whether a given face is a sub-face of this face.
+
+ Sub-faces will lie in the same plane as this one and have all of their
+ vertices completely within the boundary of this face.
+
+ This is useful for identifying whether a given sub-face (ie. a window or door)
+ can be assigned as a child to this face.
+
+ Args:
+ face: Another face for which sub-face equivalency will be tested.
+ tolerance: The minimum difference between the coordinate values of two
+ vertices at which they can be considered equivalent.
+ angle_tolerance: The max angle in radians that the plane normals can
+ differ from one another in order for them to be considered coplanar.
+
+ Returns:
+ True if it can be a valid sub-face. False if it is not a valid sub-face.
+ """
+ # test whether the surface is coplanar
+ ifnotself.plane.is_coplanar_tolerance(face.plane,tolerance,angle_tolerance):
+ returnFalse
+
+ # if it is, convert sub-face to a polygon in this face's plane
+ returnself._is_sub_face(face)
+
+
+
+[docs]
+ defpolygon_in_face(self,sub_face,origin=None,flip=False):
+"""Get a Polygon2D for a sub_face within the plane of this Face3D.
+
+ Note that there is no check within this method to determine whether the
+ the sub_face is coplanar with this Face3D or is fully bounded by it.
+ So the is_sub_face method should be used to evaluate this before using
+ this method.
+
+ Args:
+ sub_face: A Face3D for which a Polygon2D in the plane of this
+ Face3D will be returned.
+ origin: An optional Point3D to set the origin of the plane in which
+ the sub_face will be evaluated. Plugging in values like the
+ Face's lower_left_corner can standardize the geometry rules
+ for the resulting polygon. If None, this face's own
+ plane will be used. (Default: None).
+ flip: Boolean to note whether the x-axis of the plane should be flipped
+ when translating this the sub_face vertices.
+ """
+ # set the process the origin into a plane
+ iforiginisNone:
+ plane=self.planeifnotflipelseself.plane.flip()
+ else:
+ ifself._plane.n.zin(1,-1):
+ plane=Plane(self._plane.n,origin,Vector3D(1,0,0))ifnotflip \
+ elsePlane(self._plane.n,origin,Vector3D(-1,0,0))
+ else:
+ proj_y=Vector3D(0,0,1).project(self._plane.n)
+ proj_x=proj_y.rotate(self._plane.n,math.pi/-2)
+ plane=Plane(self._plane.n,origin,proj_x)
+ pts_2d=tuple(plane.xyz_to_xy(pt)forptinsub_face.boundary)
+ returnPolygon2D(pts_2d)
+
+
+
+[docs]
+ defis_point_on_face(self,point,tolerance):
+"""Check whether a given point is on this face.
+
+ This includes both a check to be sure that the point is in the plane of this
+ face and a check to ensure that point lies in the boundary of the face.
+
+ Args:
+ point: A Point3D to evaluate whether it lies on the face.
+ tolerance: The minimum difference between the coordinate values of two
+ vertices at which they can be considered equivalent.
+ Returns:
+ True if the point is on the face. False if it is not.
+ """
+ # test whether the point is in the plane of the face
+ ifself.plane.distance_to_point(point)>tolerance:
+ returnFalse
+ # if it is, convert the point into this face's plane
+ vert2d=self.plane.xyz_to_xy(point)
+ returnself.polygon2d.is_point_inside(vert2d)
+
+
+
+[docs]
+ defcheck_planar(self,tolerance,raise_exception=True):
+"""Check that all of the face's vertices lie within the face's plane.
+
+ This check is not done by default when creating the face since
+ it is assumed that there is likely a check for planarity before the face
+ is created (ie. in CAD software where the face likely originates from).
+ This method is intended for quality control checking when the origin of
+ face geometry is unknown or is known to come from a place where no
+ planarity check was performed.
+
+ Args:
+ tolerance: The minimum distance between a given vertex and a the
+ face's plane at which the vertex is said to lie in the plane.
+ raise_exception: Boolean to note whether an exception should be raised
+ if a vertex does not lie within the face's plane. If True, an
+ exception message will be given in such cases, which notes the non-planar
+ vertex and its distance from the plane. If False, this method will
+ simply return a False boolean if a vertex is found that is out
+ of plane. Default is True to raise an exception.
+
+ Returns:
+ True if planar within the tolerance. False if not planar.
+ """
+ for_vinself.vertices:
+ ifself._plane.distance_to_point(_v)>=tolerance:
+ ifraise_exceptionisTrue:
+ raiseValueError(
+ 'Vertex {} is out of plane with its parent face.\nDistance '
+ 'to plane is {}'.format(_v,self._plane.distance_to_point(_v)))
+ else:
+ returnFalse
+ returnTrue
+
+
+
+[docs]
+ defnon_planar_vertices(self,tolerance):
+"""Get a tuple of Point3D for any vertices that lie outside the face's plane.
+
+ This will be an empty tuple when the Face3D is planar and it is recommended
+ that the Face3D.check_planar method be used before calling this one.
+
+ Args:
+ tolerance: The minimum distance between a given vertex and a the
+ face's plane at which the vertex is said to lie in the plane.
+ """
+ np_verts=[]
+ for_vinself.vertices:
+ ifself._plane.distance_to_point(_v)>=tolerance:
+ np_verts.append(_v)
+ returntuple(np_verts)
+
+
+
+[docs]
+ defremove_duplicate_vertices(self,tolerance):
+"""Get a version of this face without duplicate vertices.
+
+ Args:
+ tolerance: The minimum distance between a two vertices at which
+ they are considered co-located or duplicated.
+ """
+ ifnotself.has_holes:# we only need to evaluate one list of vertices
+ new_vertices=tuple(
+ ptfori,ptinenumerate(self._vertices)
+ ifnotpt.is_equivalent(self._vertices[i-1],tolerance))
+ _new_face=Face3D(new_vertices,self.plane,enforce_right_hand=False)
+ return_new_face
+ # the face has holes
+ _boundary=tuple(
+ ptfori,ptinenumerate(self._boundary)
+ ifnotpt.is_equivalent(self._boundary[i-1],tolerance))
+ _holes=tuple(
+ tuple(pfori,pinenumerate(h)ifnotp.is_equivalent(h[i-1],tolerance))
+ forj,hinenumerate(self._holes))
+ _new_face=Face3D(_boundary,self.plane,_holes,enforce_right_hand=False)
+ return_new_face
+
+
+
+[docs]
+ defremove_colinear_vertices(self,tolerance):
+"""Get a version of this face without colinear or duplicate vertices.
+
+ Args:
+ tolerance: The minimum distance between a vertex and the boundary segments
+ at which point the vertex is considered colinear.
+ """
+ ifnotself.has_holes:# we only need to evaluate one list of vertices
+ new_vertices=self._remove_colinear(
+ self._vertices,self.polygon2d,tolerance)
+ _new_face=Face3D(new_vertices,self.plane,enforce_right_hand=False)
+ return_new_face
+ # the face has holes
+ _boundary=self._remove_colinear(
+ self._boundary,self.boundary_polygon2d,tolerance)
+ _holes=tuple(self._remove_colinear(hole,self.hole_polygon2d[i],tolerance)
+ fori,holeinenumerate(self._holes))
+ _new_face=Face3D(_boundary,self.plane,_holes,enforce_right_hand=False)
+ return_new_face
+
+
+
+[docs]
+ defflip(self):
+"""Get a face with a flipped direction from this one."""
+ _new_face=Face3D(reversed(self.vertices),self.plane.flip(),
+ enforce_right_hand=False)
+ self._transfer_properties(_new_face)
+ ifself._holesisnotNone:
+ _new_face._boundary=tuple(reversed(self._boundary))
+ _new_face._holes=self._holes
+ return_new_face
+
+
+
+[docs]
+ defmove(self,moving_vec):
+"""Get a face that has been moved along a vector.
+
+ Args:
+ moving_vec: A Vector3D with the direction and distance to move the face.
+ """
+ _verts=self._move(self.vertices,moving_vec)
+ _new_face=self._face_transform(_verts,self.plane.move(moving_vec))
+ ifself._holesisnotNone:
+ _new_face._boundary=self._move(self._boundary,moving_vec)
+ _new_face._holes=tuple(self._move(hole,moving_vec)
+ forholeinself._holes)
+ return_new_face
+
+
+
+[docs]
+ defrotate(self,axis,angle,origin):
+"""Rotate a face by a certain angle around an axis and origin.
+
+ Right hand rule applies:
+ If axis has a positive orientation, rotation will be clockwise.
+ If axis has a negative orientation, rotation will be counterclockwise.
+
+ Args:
+ axis: A Vector3D axis representing the axis of rotation.
+ angle: An angle for rotation in radians.
+ origin: A Point3D for the origin around which the object will be rotated.
+ """
+ _verts=self._rotate(self.vertices,axis,angle,origin)
+ _new_face=self._face_transform(_verts,self.plane.rotate(axis,angle,origin))
+ ifself._holesisnotNone:
+ _new_face._boundary=self._rotate(self._boundary,axis,angle,origin)
+ _new_face._holes=tuple(self._rotate(hole,axis,angle,origin)
+ forholeinself._holes)
+ return_new_face
+
+
+
+[docs]
+ defrotate_xy(self,angle,origin):
+"""Get a face rotated counterclockwise in the world XY plane by a certain angle.
+
+ Args:
+ angle: An angle in radians.
+ origin: A Point3D for the origin around which the object will be rotated.
+ """
+ _verts=self._rotate_xy(self.vertices,angle,origin)
+ _new_face=self._face_transform(_verts,self.plane.rotate_xy(angle,origin))
+ ifself._holesisnotNone:
+ _new_face._boundary=self._rotate_xy(self._boundary,angle,origin)
+ _new_face._holes=tuple(self._rotate_xy(hole,angle,origin)
+ forholeinself._holes)
+ return_new_face
+
+
+
+[docs]
+ defreflect(self,normal,origin):
+"""Get a face reflected across a plane with the input normal vector and origin.
+
+ Args:
+ normal: A Vector3D representing the normal vector for the plane across
+ which the face will be reflected. THIS VECTOR MUST BE NORMALIZED.
+ origin: A Point3D representing the origin from which to reflect.
+ """
+ _verts=self._reflect(self.vertices,normal,origin)
+ _new_face=self._face_transform_reflect(
+ _verts,self.plane.reflect(normal,origin))
+ ifself._holesisnotNone:
+ _new_face._boundary=self._reflect(self._boundary,normal,origin)
+ _new_face._holes=tuple(self._reflect(hole,normal,origin)
+ forholeinself._holes)
+ return_new_face
+
+
+
+[docs]
+ defscale(self,factor,origin=None):
+"""Scale a face by a factor from an origin point.
+
+ Args:
+ factor: A number representing how much the face should be scaled.
+ origin: A Point3D representing the origin from which to scale.
+ If None, it will be scaled from the World origin (0, 0, 0).
+ """
+ _verts=self._scale(self.vertices,factor,origin)
+ _new_face=self._face_transform_scale(_verts,None,factor)
+ ifself._holesisnotNone:
+ _new_face._boundary=self._scale(self._boundary,factor,origin)
+ _new_face._holes=tuple(self._scale(hole,factor,origin)
+ forholeinself._holes)
+ return_new_face
+
+
+
+[docs]
+ defsplit_through_holes(self):
+"""Get this Face3D split through its holes to get Face3D without holes.
+
+ This method attempts to return the minimum number of non-holed shapes that
+ are needed to represent the original Face3D. If this fails, the result
+ will be derived from a triangulated shape. If getting a minimum number
+ of constituent Face3D is not important, it is more efficient to just
+ use all of the triangles in Face3D.triangulated_mesh3d instead of the
+ result of this method.
+
+ Returns:
+ A list of Face3D without holes that together form a geometric
+ representation of this Face3D. If this Face3D has no holes a list
+ with a single Face3D is returned.
+ """
+ def_shared_vertex_count(vert_set,verts):
+"""Get the number of shared vertices."""
+ in_set=tuple(vforvinvertsifvinvert_set)
+ returnlen(in_set)
+
+ def_shared_edge_count(edge_set,verts):
+"""Get the number of shared edges."""
+ edges=tuple((verts[i],verts[i-1])foriinrange(3))
+ in_set=tuple(eforeinedgesifeinedge_set)
+ returnlen(in_set)
+
+ ifnotself.has_holes:
+ return(self,)
+ # check that the direction of vertices for the hole is opposite the boundary
+ boundary=list(self.boundary_polygon2d.vertices)
+ holes=[list(hole.vertices)forholeinself.hole_polygon2d]
+ bound_direction=Polygon2D._are_clockwise(boundary)
+ forholeinholes:
+ ifPolygon2D._are_clockwise(hole)isbound_direction:
+ hole.reverse()
+ # try to split the polygon neatly in two
+ s_result=Polygon2D._merge_boundary_and_holes(boundary,holes,split=True)
+ ifs_resultisnotNone:
+ poly_1,poly_2=s_result
+ vert_1=tuple(self.plane.xy_to_xyz(pt)forptinpoly_1)
+ vert_2=tuple(self.plane.xy_to_xyz(pt)forptinpoly_2)
+ face_1=Face3D(vert_1,plane=self.plane)
+ face_2=Face3D(vert_2,plane=self.plane)
+ returnface_1,face_2
+ # if splitting in two did not work, then triangulate it and merge them together
+ tri_mesh=self.triangulated_mesh3d
+ tri_verts=tri_mesh.vertices
+ rel_f=tri_mesh.faces[0]
+ tri_faces=[[tuple(tri_verts[pt]forptinrel_f)]]
+ tri_face_sets=[set(rel_f)]
+ tri_edge_sets=[set((rel_f[i-1],rel_f[i])foriinrange(3))]
+ faces_to_test=list(tri_mesh.faces[1:])
+ # group the faces along matched edges
+ forfinfaces_to_test:
+ connected=False
+ fortfs,fs,esinzip(tri_faces,tri_face_sets,tri_edge_sets):
+ svc=_shared_vertex_count(fs,f)
+ sec=_shared_edge_count(es,f)
+ ifsvc==2andsec==1:# matched edge
+ tfs.append(tuple(tri_verts[pt]forptinf))
+ fori,vinenumerate(f):
+ fs.add(v)
+ es.add((f[i-1],f[i]))
+ break
+ elifsvc==3:# definitely a new shape
+ connected=True
+ else:# not ready to be merged; put it to the back
+ ifconnected:
+ tri_faces.append([tuple(tri_verts[pt]forptinf)])
+ tri_face_sets.append(set(f))
+ tri_edge_sets.append(set((f[i-1],f[i])foriinrange(3)))
+ else:
+ faces_to_test.append(f)
+ # create Face3Ds from the triangle groups
+ final_faces=[]
+ fortfintri_faces:
+ t_mesh=Mesh3D.from_face_vertices(tf)
+ ed_len=(seg.lengthforsegint_mesh.naked_edges)
+ tol=min(ed_len)/10
+ f_bound=Polyline3D.join_segments(t_mesh.naked_edges,tol)
+ final_faces.append(Face3D(f_bound[0].vertices,plane=self.plane))
+ returnfinal_faces
+
+
+
+[docs]
+ defsplit_with_line(self,line,tolerance):
+"""Split this face into two or more Face3D given a LineSegment3D.
+
+ If the input line is found to not exist in the plane of this Face3D
+ or it does not intersect this Face3D in a manner that splits it into two
+ or more pieces, None will be returned.
+
+ Args:
+ line: A LineSegment3D object in the plane of this Face3D, which will
+ be used to split it into two or more pieces.
+ tolerance: The maximum difference between point values for them to be
+ considered distinct from one another.
+
+ Returns:
+ A list of Face3D for the result of splitting this Face3D with the
+ input line. Will be None if the line is not in the plane of the
+ Face3D or if it does not split the Face3D into two or more pieces.
+ """
+ # first check that the line is in the plane of the Face3D
+ ifself.plane.distance_to_point(line.p1)>toleranceor \
+ self.plane.distance_to_point(line.p1)>tolerance:
+ returnNone
+
+ # change the line and face to be in 2D and check that it can split the Face
+ prim_pl=self.plane
+ bnd_poly=self.boundary_polygon2d
+ hole_polys=self.hole_polygon2d
+ line_2d=LineSegment2D.from_end_points(
+ prim_pl.xyz_to_xy(line.p1),prim_pl.xyz_to_xy(line.p2))
+ ifnotPolygon2D.overlapping_bounding_rect(bnd_poly,line_2d,tolerance):
+ returnNone
+
+ # create the network object and use it to find the cycles
+ dg=DirectedGraphNetwork.from_shape_to_split(
+ bnd_poly,hole_polys,[line_2d],tolerance)
+ split_faces=[]
+ forcycleindg.all_min_cycles():
+ iflen(cycle)>=3:
+ pt_3ds=[prim_pl.xy_to_xyz(node.pt)fornodeincycle]
+ new_face=Face3D(pt_3ds,plane=prim_pl)
+ try:
+ new_face=new_face.remove_colinear_vertices(tolerance)
+ split_faces.append(new_face)
+ exceptAssertionError:# degenerate geometry to ignore
+ pass
+
+ # rebuild the Face3D from the results and return them
+ iflen(split_faces)==1:
+ returnsplit_faces
+ returnFace3D.merge_faces_to_holes(split_faces,tolerance)
+
+
+
+[docs]
+ defsplit_with_polyline(self,polyline,tolerance):
+"""Split this face into two or more Face3D given an open Polyline3D.
+
+ If the input polyline is found to not exist in the plane of this Face3D,
+ or the polyline is self-intersecting (or closed), or it does not intersect
+ this Face3D in a manner that splits it into two or more pieces, None
+ will be returned.
+
+ Note that, if you wish to use an operation similar to this method but
+ with a closed Polyline3D (effectively another Face3D), then the
+ Face3D.coplanar_split() method should be used instead of this method.
+
+ Args:
+ polyline: A Polyline3D object in the plane of this Face3D, which will
+ be used to split it into two or more pieces.
+ tolerance: The maximum difference between point values for them to be
+ considered distinct from one another.
+
+ Returns:
+ A list of Face3D for the result of splitting this Face3D with the
+ input polyline. Will be None if the polyline is not in the plane of
+ the Face3D, or the polyline intersects itself (or is closed), or if it
+ does not split the Face3D into two or more pieces.
+ """
+ # first check that the polyline is in the plane of the Face3D
+ forpl_ptinpolyline.vertices:
+ ifself.plane.distance_to_point(pl_pt)>tolerance:
+ returnNone
+
+ # change the polyline and face to be in 2D and check that it can split the Face
+ prim_pl=self.plane
+ bnd_poly=self.boundary_polygon2d
+ hole_polys=self.hole_polygon2d
+ polyline_2d=Polyline2D([prim_pl.xyz_to_xy(pt)forptinpolyline])
+ ifnotPolygon2D.overlapping_bounding_rect(bnd_poly,polyline_2d,tolerance):
+ returnNone
+ rel_line_2ds=[]
+ intersect_count=0
+ forseginpolyline_2d.segments:
+ intersect_count+=len(bnd_poly.intersect_line_ray(seg))
+ ifseg.length>toleranceand \
+ Polygon2D.overlapping_bounding_rect(bnd_poly,seg,tolerance):
+ rel_line_2ds.append(seg)
+ iflen(rel_line_2ds)==0:
+ returnNone
+
+ # create the network object and use it to find the cycles
+ dg=DirectedGraphNetwork.from_shape_to_split(
+ bnd_poly,hole_polys,polyline_2d.segments,tolerance)
+ split_faces=[]
+ forcycleindg.all_min_cycles():
+ iflen(cycle)>=3:
+ pt_3ds=[prim_pl.xy_to_xyz(node.pt)fornodeincycle]
+ new_face=Face3D(pt_3ds,plane=prim_pl)
+ try:
+ new_face=new_face.remove_colinear_vertices(tolerance)
+ split_faces.append(new_face)
+ exceptAssertionError:# degenerate geometry to ignore
+ pass
+
+ # rebuild the Face3D from the results and return them
+ iflen(split_faces)==1:
+ returnsplit_faces
+ returnFace3D.merge_faces_to_holes(split_faces,tolerance)
+
+
+
+[docs]
+ defsplit_with_lines(self,lines,tolerance):
+"""Split this face into two or more Face3D given multiple LineSegment3D.
+
+ Using this method is distinct from looping over Face3D.split_with_line
+ in that this method will resolve cases where multiple segments branch out
+ from nodes in a network of input lines. So, if three line segments
+ meet at a point in the middle of this Face3D and each extend past the
+ edges of this Face3D, this method can split the Face3D in 3 parts whereas
+ looping over the Face3D.split_with_line will not do this given that each
+ individual segment cannot split the Face3D.
+
+ If the input lines together do not intersect this Face3D in a manner
+ that splits it into two or more pieces, None will be returned.
+
+ Args:
+ lines: A list of LineSegment3D objects in the plane of this Face3D,
+ which will be used to split it into two or more pieces.
+ tolerance: The maximum difference between point values for them to be
+ considered distinct from one another.
+
+ Returns:
+ A list of Face3D for the result of splitting this Face3D with the
+ input lines. Will be None if the line is not in the plane of the
+ Face3D or if it does not split the Face3D into two or more pieces.
+ """
+ # first check that the lines are in the plane of the Face3D
+ rel_line_3ds=[]
+ forlineinlines:
+ ifself.plane.distance_to_point(line.p1)<=toleranceor \
+ self.plane.distance_to_point(line.p1)<=tolerance:
+ rel_line_3ds.append(line)
+ iflen(rel_line_3ds)==0:
+ returnNone
+
+ # change the line and face to be in 2D and check that it can split the Face
+ prim_pl=self.plane
+ bnd_poly=self.boundary_polygon2d
+ hole_polys=self.hole_polygon2d
+ rel_line_2ds=[]
+ forlineinrel_line_3ds:
+ line_2d=LineSegment2D.from_end_points(
+ prim_pl.xyz_to_xy(line.p1),prim_pl.xyz_to_xy(line.p2))
+ ifline_2d.length>toleranceand \
+ Polygon2D.overlapping_bounding_rect(bnd_poly,line_2d,tolerance):
+ rel_line_2ds.append(line_2d)
+ iflen(rel_line_2ds)==0:
+ returnNone
+
+ # create the network object and use it to find the cycles
+ dg=DirectedGraphNetwork.from_shape_to_split(
+ bnd_poly,hole_polys,rel_line_2ds,tolerance)
+ split_faces=[]
+ forcycleindg.all_min_cycles():
+ iflen(cycle)>=3:
+ pt_3ds=[prim_pl.xy_to_xyz(node.pt)fornodeincycle]
+ new_face=Face3D(pt_3ds,plane=prim_pl)
+ try:
+ new_face=new_face.remove_colinear_vertices(tolerance)
+ split_faces.append(new_face)
+ exceptAssertionError:# degenerate geometry to ignore
+ pass
+
+ # rebuild the Face3D from the results and return them
+ iflen(split_faces)==1:
+ returnsplit_faces
+ returnFace3D.merge_faces_to_holes(split_faces,tolerance)
+
+
+
+[docs]
+ defintersect_line_ray(self,line_ray):
+"""Get the intersection between this face and the input LineSegment3D or Ray3D.
+
+ Args:
+ line_ray: A LineSegment3D or Ray3D object for which intersection
+ will be computed.
+
+ Returns:
+ Point3D for the intersection. Will be None if no intersection exists.
+ """
+ _plane_int=self._plane.intersect_line_ray(line_ray)
+ if_plane_intisnotNone:
+ _int2d=self._plane.xyz_to_xy(_plane_int)
+ ifself.polygon2d.is_point_inside_bound_rect(_int2d):
+ return_plane_int
+ returnNone
+
+
+
+[docs]
+ defintersect_plane(self,plane):
+"""Get the intersection between this face and the input plane.
+
+ Args:
+ plane: A Plane object for which intersection will be computed.
+
+ Returns:
+ List of LineSegment3D objects for the intersection.
+ Will be None if no intersection exists.
+ """
+ _plane_int_ray=self._plane.intersect_plane(plane)
+ if_plane_int_rayisnotNone:
+ _p12d=self._plane.xyz_to_xy(_plane_int_ray.p)
+ _p22d=self._plane.xyz_to_xy(_plane_int_ray.p+_plane_int_ray.v)
+ _v2d=_p22d-_p12d
+ _int_ray2d=Ray2D(_p12d,_v2d)
+ _int_pt2d=self.polygon2d.intersect_line_infinite(_int_ray2d)
+ iflen(_int_pt2d)!=0:
+ iflen(_int_pt2d)>2:# sort the points along the intersection line
+ _int_pt2d.sort(key=lambdapt:pt.x)
+ _int_pt3d=[self._plane.xy_to_xyz(pt)forptin_int_pt2d]
+ _int_seg3d=[]
+ foriinxrange(0,len(_int_pt3d)-1,2):
+ _int_seg3d.append(LineSegment3D.from_end_points(
+ _int_pt3d[i],_int_pt3d[i+1]))
+ return_int_seg3d
+ returnNone
+
+
+
+[docs]
+ defproject_point(self,point):
+"""Project a Point3D onto this face.
+
+ Note that this method does a check to see if the point can be projected to
+ within this face's boundary. If all that is needed is a point projected
+ into the plane of this face, the Plane.project_point() method should be
+ used with this face's plane property.
+
+ Args:
+ point: A Point3D object to project.
+
+ Returns:
+ Point3D for the point projected onto this face. Will be None if the
+ point cannot be projected to within the boundary of the face.
+ """
+ _plane_int=point.project(self._plane.n,self._plane.o)
+ _plane_int2d=self._plane.xyz_to_xy(_plane_int)
+ ifself.polygon2d.is_point_inside_bound_rect(_plane_int2d):
+ return_plane_int
+ returnNone
+
+
+
+[docs]
+ defmesh_grid(self,x_dim,y_dim=None,offset=None,flip=False,
+ generate_centroids=True):
+"""Get a gridded Mesh3D over this face.
+
+ This method generates a mesh grid over the domain of the face
+ and then removes any vertices that do not lie within it.
+
+ Note that the x_dim and y_dim refer to dimensions within the X and Y
+ coordinate system of this faces's plane. So rotating this plane will
+ result in rotated grid cells.
+
+ Args:
+ x_dim: The x dimension of the grid cells as a number.
+ y_dim: The y dimension of the grid cells as a number. Default is None,
+ which will assume the same cell dimension for y as is set for x.
+ offset: A number for how far to offset the grid from the base face.
+ Default is None, which will not offset the grid at all.
+ flip: Set to True to have the mesh normals reversed from the direction
+ of this face and to have the offset input move the mesh in the
+ opposite direction from this face's normal.
+ generate_centroids: Set to True to have the face centroids generated
+ alongside the grid of vertices, which is much faster than having
+ them generated upon request as they typically are. However, if you
+ have no need for the face centroids, you would save time and memory
+ by setting this to False. Default is True.
+ """
+ # check the inputs and set defaults
+ self._check_number_mesh_grid(x_dim,'x_dim')
+ ify_dimisnotNone:
+ self._check_number_mesh_grid(y_dim,'y_dim')
+ else:
+ y_dim=x_dim
+ ifoffsetisnotNone:
+ self._check_number_mesh_grid(offset,'offset')
+
+ # generate the mesh grid and convert it to a 3D mesh
+ grid_mesh2d=Mesh2D.from_polygon_grid(
+ self.polygon2d,x_dim,y_dim,generate_centroids)
+ ifoffsetisNoneoroffset==0:
+ vert_3d=tuple(self._plane.xy_to_xyz(pt)
+ forptingrid_mesh2d.vertices)
+ else:
+ _off_num=-1*offsetifflipisTrueelseoffset
+ _off_plane=self.plane.move(self.plane.n*_off_num)
+ vert_3d=tuple(_off_plane.xy_to_xyz(pt)
+ forptingrid_mesh2d.vertices)
+ grid_mesh3d=Mesh3D(vert_3d,grid_mesh2d.faces)
+ grid_mesh3d._face_areas=grid_mesh2d._face_areas
+
+ # assign the face plane normal to the mesh normals
+ ifflipisTrue:
+ grid_mesh3d._face_normals=self._plane.n.reverse()
+ grid_mesh3d._vertex_normals=self._plane.n.reverse()
+ grid_mesh3d._faces=tuple(
+ tuple(reversed(face))forfaceingrid_mesh3d._faces)# right-hand rule
+ else:
+ grid_mesh3d._face_normals=self._plane.n
+ grid_mesh3d._vertex_normals=self._plane.n
+
+ # transform the centroids to 3D space if they were generated
+ ifgenerate_centroidsisTrue:
+ _conv_plane=self._planeifoffsetisNoneoroffset==0else_off_plane
+ grid_mesh3d._face_centroids=tuple(_conv_plane.xy_to_xyz(pt)
+ forptingrid_mesh2d.face_centroids)
+
+ returngrid_mesh3d
+
+
+
+[docs]
+ defcontour_by_number(self,contour_count,direction_vector,flip_side,tolerance):
+"""Generate a list of LineSegment3D objects contouring the face.
+
+ Args:
+ contour_count: A positive integer for the number of contours
+ to generate over the face.
+ direction_vector: A Vector2D for the direction along which contours
+ are generated. This 2D vector will be interpreted into a 3D vector
+ within the plane of this Face. (0, 1) will usually generate
+ horizontal contours in 3D space, (1, 0) will generate vertical
+ contours, and (1, 1) will generate diagonal contours. Recommended
+ value is Vector2D(0, 1).
+ flip_side: Boolean to note whether the side the contours start from
+ should be flipped. Recommended value is False to have contours
+ on top or right.
+ Setting to True will start contours on the bottom or left.
+ tolerance: The minimum distance between coordinates that is considered
+ meaningful. Will be used to remove any contours with a length less
+ than the tolerance.
+ """
+ # interpret the 2D direction_vector into one that exists in 3D space
+ ref_plane=Plane(self._plane.n,Point3D(0,0,0),self._plane.x)
+ ifref_plane.y.z<0:
+ ref_plane=ref_plane.rotate(ref_plane.n,math.pi,ref_plane.o)
+ plane_normal=ref_plane.xy_to_xyz(direction_vector).normalize()
+
+ # get a diagonal going across the face
+ diagonal=self._diagonal_along_self(direction_vector,tolerance)
+ ifnotflip_side:
+ diagonal=diagonal.flip()# flip diagonal if user has requested it
+
+ # generate the contours
+ contours=[]
+ forptindiagonal.subdivide_evenly(contour_count)[:-1]:
+ result=self.intersect_plane(Plane(plane_normal,pt))
+ ifresultisnotNone:
+ contours.extend(result)
+
+ # remove any contours that are smaller than the tolerance.
+ iftolerance!=0:
+ contours=[l_segforl_segincontoursifl_seg.length>=tolerance]
+ returncontours
+
+
+
+[docs]
+ defcontour_by_distance_between(self,distance,direction_vector,flip_side,
+ tolerance):
+"""Generate a list of LineSegment3D objects contouring the face.
+
+ Args:
+ distance: A number for the distance between each contour.
+ direction_vector: A Vector2D for the direction along which contours
+ are generated. This 2D vector will be interpreted into a 3D vector
+ within the plane of this Face. (0, 1) will usually generate
+ horizontal contours in 3D space, (1, 0) will generate vertical
+ contours, and (1, 1) will generate diagonal contours. Recommended
+ value is Vector2D(0, 1).
+ flip_side: Boolean to note whether the side the contours start from
+ should be flipped. Recommended value is is False to have contours
+ start on top or right. Setting to True will start contours on
+ the bottom or left.
+ tolerance: The minimum distance between coordinates that is considered
+ meaningful. Will be used to remove any contours with a length less
+ than the tolerance.
+ """
+ # interpret the 2D direction_vector into one that exists in 3D space
+ ref_plane=Plane(self._plane.n,Point3D(0,0,0),self._plane.x)
+ ifref_plane.y.z<0:
+ ref_plane=ref_plane.rotate(ref_plane.n,math.pi,ref_plane.o)
+ plane_normal=ref_plane.xy_to_xyz(direction_vector).normalize()
+
+ # get a diagonal going across the face
+ diagonal=self._diagonal_along_self(direction_vector,tolerance)
+ ifnotflip_side:
+ diagonal=diagonal.flip()# flip diagonal if user has requested it
+
+ # compute the diagonal subdivision distance using the plane_normal
+ angle=plane_normal.angle(diagonal.v)
+ angle=abs(angle-math.pi)ifangle>math.pi/2elseangle
+ proj_dist=distance/math.cos(angle)
+
+ # generate the contours
+ contours=[]
+ forptindiagonal.subdivide(proj_dist)[:-1]:
+ pass
+ result=self.intersect_plane(Plane(plane_normal,pt))
+ ifresultisnotNone:
+ contours.extend(result)
+
+ # remove any contours that are smaller than the tolerance.
+ iftolerance!=0:
+ contours=[l_segforl_segincontoursifl_seg.length>=tolerance]
+ returncontours
+
+
+
+[docs]
+ defcontour_fins_by_number(self,fin_count,depth,offset,angle,
+ contour_vector,flip_side,tolerance):
+"""Generate a list of Fac3D objects over this face (like louvers or fins).
+
+ Args:
+ fin_count: A positive integer for the number of fins to generate.
+ depth: A number for the depth to extrude the fins.
+ offset: A number for the distance to offset fins from this face.
+ Recommended value is 0 for no offset.
+ angle: A number for the for an angle to rotate the fins in radians.
+ Recommended value is 0 for no rotation.
+ contour_vector: A Vector2D for the direction along which contours
+ are generated. This 2D vector will be interpreted into a 3D vector
+ within the plane of this Face. (0, 1) will usually generate
+ horizontal contours in 3D space, (1, 0) will generate vertical
+ contours, and (1, 1) will generate diagonal contours. Recommended
+ value is Vector2D(0, 1).
+ flip_side: Boolean to note whether the side the fins start from
+ should be flipped. Recommended value is False to have contours
+ start on top or right. Setting to True will start contours on
+ the bottom or left.
+ tolerance: The minimum distance between coordinates that is considered
+ meaningful. Will be used to remove any contours with a length less
+ than the tolerance.
+ """
+ extru_vec=self._get_fin_extrusion_vector(depth,angle,contour_vector)
+ contours=self.contour_by_number(
+ fin_count,contour_vector,flip_side,tolerance)
+ returnself._get_extrusion_fins(contours,extru_vec,offset)
+
+
+
+[docs]
+ defcontour_fins_by_distance_between(self,distance,depth,offset,angle,
+ contour_vector,flip_side,tolerance):
+"""Generate a list of Fac3D objects over this face (like louvers or fins).
+
+ Args:
+ distance: A number for the approximate distance between each contour.
+ depth: A number for the depth to extrude the fins.
+ offset: A number for the distance to offset fins from this face.
+ Recommended value is 0 for no offset.
+ angle: A number for the for an angle to rotate the fins in radians.
+ Recommended value is 0 for no rotation.
+ contour_vector: A Vector2D for the direction along which contours
+ are generated. This 2D vector will be interpreted into a 3D vector
+ within the plane of this Face. (0, 1) will usually generate
+ horizontal contours in 3D space, (1, 0) will generate vertical
+ contours, and (1, 1) will generate diagonal contours. Recommended
+ value is Vector2D(0, 1).
+ flip_side: Boolean to note whether the side the fins start from
+ should be flipped. Recommended value is False to have contours
+ start on top or right. Setting to True will start contours on
+ the bottom or left.
+ tolerance: The minimum distance between coordinates that is considered
+ meaningful. Will be used to remove any contours with a length less
+ than the tolerance.
+ """
+ extru_vec=self._get_fin_extrusion_vector(depth,angle,contour_vector)
+ contours=self.contour_by_distance_between(
+ distance,contour_vector,flip_side,tolerance)
+ returnself._get_extrusion_fins(contours,extru_vec,offset)
+
+
+
+[docs]
+ defsub_faces_by_ratio(self,ratio):
+"""Get a list of faces with a combined area equal to ratio times this face area.
+
+ All sub faces will lie inside the boundaries of this face and will have
+ the same normal as this face.
+
+ Args:
+ ratio: A number between 0 and 1 for the ratio between the area of
+ the sub faces and the area of this face.
+
+ Returns:
+ A list of Face3D objects for sub faces.
+ """
+ scale_factor=ratio**.5
+ ifself.is_convex:
+ return[self.scale(scale_factor,self.centroid)]
+ else:
+ _tri_mesh=self.triangulated_mesh3d
+ _tri_faces=[[_tri_mesh[i]foriinface]forfacein_tri_mesh.faces]
+ _scaled_verts=[]
+ fori,_triinenumerate(_tri_faces):
+ _scaled_verts.append(
+ [pt.scale(scale_factor,_tri_mesh.face_centroids[i])forptin_tri])
+ return[Face3D(_t,self.plane)for_tin_scaled_verts]
+
+
+
+[docs]
+ defsub_faces_by_ratio_gridded(self,ratio,x_dim,y_dim=None):
+"""Get a list of faces with a combined area equal to ratio times this face area.
+
+ All sub faces will lie inside the boundaries of this face and have the same
+ normal as this face.
+
+ Sub faces will be arranged in a grid derived from this face's plane property.
+ Because the x_dim and y_dim refer to dimensions within the X and Y
+ coordinate system of this faces's plane, rotating this plane will
+ result in rotated grid cells.
+
+ If the x_dim and/or y_dim are too large for this face, this method will
+ return essentially the same result as the sub_faces_by_ratio method.
+
+ Args:
+ ratio: A number between 0 and 1 for the ratio between the area of
+ the sub faces and the area of this face.
+ x_dim: The x dimension of the grid cells as a number.
+ y_dim: The y dimension of the grid cells as a number. Default is None,
+ which will assume the same cell dimension for y as is set for x.
+
+ Returns:
+ A list of Face3D objects for sub faces.
+ """
+ try:# get the gridded mesh derived from this face
+ grid_mesh=self.mesh_grid(x_dim,y_dim)
+ exceptAssertionError:# there are no faces; just return sub_faces_by_ratio
+ returnself.sub_faces_by_ratio(ratio)
+
+ # compute the area that each of the mesh faces need to be scaled to
+ _verts,_faces=grid_mesh.vertices,grid_mesh.faces
+ _x_dim=_verts[_faces[0][0]].distance_to_point(_verts[_faces[0][1]])
+ _y_dim=_verts[_faces[0][1]].distance_to_point(_verts[_faces[0][2]])
+ fac=(self.area*ratio)/(_x_dim*_y_dim*len(_faces))
+
+ # if the factor is greater than 1, sub-faces will be overlapping
+ iffac>=1:
+ returnself.sub_faces_by_ratio(ratio)
+ s_fac=fac**0.5
+
+ # generate the Face3D objects while scaling them to the correct size
+ sub_faces=[]
+ forface,centrinzip(_faces,grid_mesh.face_centroids):
+ _f=Face3D(tuple(_verts[i].scale(s_fac,centr)foriinface),self.plane)
+ ifself._is_sub_face(_f):# catch edge cases
+ sub_faces.append(_f)
+ returnsub_faces
+
+
+
+[docs]
+ defsub_faces_by_ratio_rectangle(self,ratio,tolerance):
+"""Get a list of faces with a combined area equal to ratio times this face area.
+
+ This function is virtually equivalent to the sub_faces_by_ratio method
+ but a check will be performed to see if any rectangles can be pulled out
+ of this face's geometry. This tends to make the result a bit cleaner,
+ especially for concave faces that have rectangles (like L-shaped faces).
+
+ Args:
+ ratio: A number between 0 and 1 for the ratio between the area of
+ the sub faces and the area of this face.
+ tolerance: The maximum difference between point values for them to be
+ considered a part of a rectangle.
+
+ Returns:
+ A list of Face3D objects for sub faces. If there is a rectangle in this
+ shape, the scaled rectangle will be the first item in this list.
+ """
+ rect_res=self.extract_rectangle(tolerance)
+ ifrect_resisNone:
+ returnself.sub_faces_by_ratio(ratio)
+ bottom_seg,top_seg,other_faces=rect_res
+ rect_face=Face3D((bottom_seg.p1,bottom_seg.p2,top_seg.p2,top_seg.p1),
+ self.plane)
+ scale_factor=ratio**.5
+ sub_faces=[rect_face.scale(scale_factor,rect_face.center)]
+ forfaceinother_faces:
+ sfs=face.sub_faces_by_ratio(ratio)
+ forsfinsfs:
+ ifsf.area>tolerance:
+ sub_faces.append(sf)
+ returnsub_faces
+
+
+
+[docs]
+ defsub_faces_by_ratio_sub_rectangle(self,ratio,sub_rect_height,sill_height,
+ horizontal_separation,vertical_separation,
+ tolerance):
+"""Get a list of faces with a combined area equal to ratio times this face area.
+
+ This function is virtually equivalent to the sub_faces_by_ratio_rectangle
+ method but any rectangles that are found will be broken down into sub-rectangles
+ using the other inputs (sub_rect_height, sill_height, horizontal_separation,
+ vertical_separation). This allows for the creation of a wide array of
+ rectangular sub-face geometries.
+
+ Args:
+ ratio: A number between 0 and 1 for the ratio between the area of
+ the sub faces and the area of this face.
+ sub_rect_height: A number for the target height of the output sub-
+ rectangles. Note that, if the ratio is too large for the height,
+ the ratio will take precedence and the sub-rectangle height will
+ be larger than this value.
+ sill_height: A number for the target height above the bottom edge of
+ the rectangle to start the sub-rectangles. Note that, if the
+ ratio is too large for the height, the ratio will take precedence
+ and the sub-rectangle height will be smaller than this value.
+ horizontal_separation: A number for the target separation between
+ individual sub-rectangle center lines. If this number is larger than
+ the parent rectangle base, only one sub-rectangle will be produced.
+ vertical_separation: An optional number to create a single vertical
+ separation between top and bottom sub-rectangles. The default is
+ 0 for no separation.
+ tolerance: The maximum difference between point values for them to be
+ considered a part of a rectangle.
+
+ Returns:
+ A list of Face3D objects for sub faces. If there is a rectangle in this
+ shape, the scaled rectangle will be the first item in this list.
+ """
+ rect_res=self.extract_rectangle(tolerance)
+ ifrect_resisNone:
+ returnself.sub_faces_by_ratio(ratio)
+ bottom_seg,top_seg,other_faces=rect_res
+ height_seg=LineSegment3D.from_end_points(bottom_seg.p,top_seg.p)
+ norm_tup=self._normal_from_3pts(bottom_seg.p,bottom_seg.p2,top_seg.p)
+ norm=Vector3D(*norm_tup).normalize()
+ base_plane=Plane(norm,bottom_seg.p,bottom_seg.v)
+ sub_faces=Face3D.sub_rects_from_rect_ratio(
+ base_plane,bottom_seg.length,height_seg.length,ratio,
+ sub_rect_height,sill_height,horizontal_separation,vertical_separation)
+ forfaceinother_faces:
+ sfs=face.sub_faces_by_ratio(ratio)
+ forsfinsfs:
+ ifsf.area>tolerance:
+ sub_faces.append(sf)
+ returnsub_faces
+
+
+
+[docs]
+ defsub_faces_by_dimension_rectangle(self,sub_rect_height,sub_rect_width,
+ sill_height,horizontal_separation,tolerance):
+"""Get a list of rectangular faces within this Face3D.
+
+ Note that this method will only yield results if there is a rectangle to
+ be extracted from this Face3D's geometry.
+
+ Args:
+ sub_rect_height: A number for the target height of the output rectangles.
+ sub_rect_width: A number for the target width of the output rectangles.
+ sill_height: A number for the target height above the bottom edge of
+ the rectangle to start the sub-rectangles. If the sub_rect_height
+ is too large for the sill_height to fit within the rectangle,
+ the sub_rect_height will take precedence.
+ horizontal_separation: A number for the target separation between
+ individual sub-rectangle center lines. If this number is larger than
+ the parent rectangle base, only one sub-rectangle will be produced.
+ tolerance: The maximum difference between point values for them to be
+ considered a part of a rectangle.
+
+ Returns:
+ A list of Face3D objects for sub faces.
+ """
+ rect_res=self.extract_rectangle(tolerance)
+ ifrect_resisNone:
+ return[]
+ bottom_seg,top_seg,_=rect_res
+ height_seg=LineSegment3D.from_end_points(bottom_seg.p,top_seg.p)
+ norm_tup=self._normal_from_3pts(bottom_seg.p,bottom_seg.p2,top_seg.p)
+ norm=Vector3D(*norm_tup).normalize()
+ base_plane=Plane(norm,bottom_seg.p,bottom_seg.v)
+ sub_faces=Face3D.sub_rects_from_rect_dimensions(
+ base_plane,bottom_seg.length,height_seg.length,sub_rect_height,
+ sub_rect_width,sill_height,horizontal_separation)
+ returnsub_faces
+
+
+
+[docs]
+ defget_top_bottom_horizontal_edges(self,tolerance):
+"""Get top and bottom horizontal edges of this Face if they exist.
+
+ Args:
+ tolerance: The maximum difference between the z values of the start and
+ end coordinates at which an edge is considered horizontal.
+
+ Returns:
+ (bottom_edge, top_edge) with each as LineSegment3D if they exist.
+ None if they do not exist.
+ """
+ # test if each of the edges are vertical.
+ horizontal_edges=[]
+ foredgeinself.boundary_segments:
+ ifedge.is_horizontal(tolerance):
+ horizontal_edges.append(edge)
+
+ iflen(horizontal_edges)<2:
+ returnNone
+ else:
+ sorted_edges=sorted(horizontal_edges,key=lambdaedge:edge.p.z)
+ returnsorted_edges[0],sorted_edges[1]
+
+
+
+[docs]
+ defget_left_right_vertical_edges(self,tolerance):
+"""Get left and right vertical edges of this Face if they exist.
+
+ Args:
+ tolerance: The maximum difference between the x any y values of the start
+ and end coordinates at which an edge is considered vertical.
+
+ Returns:
+ (left_edge, right_edge) with each as LineSegment3D if they exist. Left in
+ this case is defined as the edge with the lower X coordinates.
+ Result will be None if vertical edges do not exist.
+ """
+ # test if each of the edges are vertical.
+ vertical_edges=[]
+ foredgeinself.boundary_segments:
+ ifedge.is_vertical(tolerance):
+ vertical_edges.append(edge)
+
+ iflen(vertical_edges)<2:
+ returnNone
+ else:
+ ifabs(self.normal.x)!=1:
+ sorted_edges=sorted(vertical_edges,key=lambdaedge:edge.p.x)
+ else:
+ sorted_edges=sorted(vertical_edges,key=lambdaedge:edge.p.y)
+ returnsorted_edges[0],sorted_edges[-1]
+
+
+
+[docs]
+ defextract_rectangle(self,tolerance):
+"""Extract top and bottom line segments of a rectangle within this Face.
+
+ This method will only return geometry if:
+
+ 1) There are no holes in the face.
+
+ 2) The face is not parallel to the World XY plane.
+
+ 3) There are two parallel edges to this face, which are either
+ oriented horizontally or vertically.
+
+ 4) There must be enough overlap between these edges for a rectangle
+ to be drawn between them.
+
+ If this Face does not satisfy this criteria, None will be returned.
+
+ Args:
+ tolerance: The maximum difference between point values for them to be
+ considered a part of a rectangle.
+
+ Returns:
+ A tuple with three elements
+
+ - bottom_edge: A LineSegment3D representing the bottom of the rectangle.
+
+ - top_edge: A LineSegment3D representing the top of the rectangle.
+
+ - other_faces:
+ A list of Face3D objects for the parts of this face not
+ included in the rectangle. The length of this list will be between
+ 0 (if this face is already rectangular) and 2 (if there are non-
+ rectangular geometries on either side of the rectangle.)
+ """
+ # perform checks on the face to see if a rectangle is extractable
+ ifself.has_holes:
+ returnNone
+ ifabs(self.normal.x)<=toleranceandabs(self.normal.y)<=tolerance:
+ # face lies within a horizontal plane; we cannot distinguish top and bottom
+ returnNone
+ clean_face=self.remove_colinear_vertices(tolerance)
+
+ # try to extract a rectangle from horizontal curves
+ horiz_result=clean_face.get_top_bottom_horizontal_edges(tolerance)
+ ifhoriz_resultisnotNone:
+ bottom_seg,top_seg=horiz_result
+ split_res=clean_face._split_with_rectangle(bottom_seg,top_seg,tolerance)
+ ifsplit_resisnotNone:
+ returnLineSegment3D.from_end_points(split_res[0][1],split_res[0][3]), \
+ LineSegment3D.from_end_points(split_res[0][0],split_res[0][2]), \
+ split_res[1]
+
+ # try to extract a rectangle from vertical curves
+ vert_result=clean_face.get_left_right_vertical_edges(tolerance)
+ ifvert_resultisnotNone:
+ left_seg,right_seg=vert_result
+ split_res=clean_face._split_with_rectangle(left_seg,right_seg,tolerance)
+ ifsplit_resisnotNone:
+ seg_1=LineSegment3D.from_end_points(split_res[0][0],split_res[0][1])
+ seg_2=LineSegment3D.from_end_points(split_res[0][2],split_res[0][3])
+ sorted_edges=sorted([seg_1,seg_2],key=lambdaedge:edge.p.z)
+ returnsorted_edges[0],sorted_edges[1],split_res[1]
+ returnNone
+
+
+
+[docs]
+ @staticmethod
+ defsub_rects_from_rect_ratio(
+ base_plane,parent_base,parent_height,ratio,sub_rect_height,sill_height,
+ horizontal_separation,vertical_separation=0):
+"""Get a list of rectangular Face3D objects using an area ratio and parameters.
+
+ All of the resulting Face3D objects lie within a parent rectangle defined
+ by the parent_base, parent_height, and base_plane. The combined area of the
+ resulting rectangles is equal to the area of the larger rectangle multiplied
+ by the input ratio. This method is particularly useful for generating
+ rectangular window surfaces.
+
+ Args:
+ base_plane: A Plane object in which the rectangle exists.
+ The origin of this plane will be the lower left corner of the
+ rectangle and the X and Y axes will form the sides.
+ parent_base: A number indicating the length of the base of the
+ parent rectangle.
+ parent_height: A number indicating the length of the height of the
+ parent rectangle.
+ ratio: A number between 0 and 1 for the ratio between the area of
+ the sub rectangle faces and the area of this face.
+ sub_rect_height: A number for the target height of the output sub-
+ rectangles. Note that, if the ratio is too large for the height,
+ the ratio will take precedence and the sub-rectangle height will
+ be larger than this value.
+ sill_height: A number for the target height above the bottom edge of
+ the rectangle to start the sub-rectangles. Note that, if the
+ ratio is too large for the height, the ratio will take precedence
+ and the sub-rectangle height will be smaller than this value.
+ horizontal_separation: A number for the target separation between
+ individual sub-rectangle center lines. If this number is larger than
+ the parent rectangle base, only one sub-rectangle will be produced.
+ vertical_separation: An optional number to create a single vertical
+ separation between top and bottom sub-rectangles. The default is
+ 0 for no separation.
+
+ Returns:
+ A list of Face3D objects for sub faces.
+ """
+ # calculate the target area to make the combined sub-rectangles
+ target_area=parent_base*parent_height*ratio
+ # find the maximum area for subdivision into smaller, taller sub-rectangles
+ max_area_subdiv=parent_base*0.98*sub_rect_height
+ # if sub_rect_height > parent_height, set it to just under parent_height
+ max_subh=0.98*parent_height
+ sub_rect_height=max_subhifsub_rect_height>max_subhelsesub_rect_height
+ # if sill_height is close to 0, set it to just above 0.
+ min_sill=0.01*parent_height
+ sill_height=min_sillifsill_height<min_sillelsesill_height
+ # properties used throughout the computation of sub-rectangles
+ bottom_seg=LineSegment3D.from_sdl(base_plane.o,base_plane.x,parent_base)
+
+ iftarget_area<max_area_subdiv:
+ # divide up the rectangle into points on the bottom.
+ ifparent_base>(horizontal_separation/2):
+ num_div=round(parent_base/horizontal_separation,0)
+ else:
+ num_div=1
+ btm_div_pts=bottom_seg.subdivide_evenly(num_div)
+ btm_div_segs=tuple(LineSegment3D.from_end_points(pt,btm_div_pts[i+1])
+ fori,ptinenumerate(btm_div_pts[:-1]))
+ # move the segments to the sill height
+ max_sill_h=parent_height*0.99-sub_rect_height
+ sill_vec=base_plane.y*sill_heightifsill_height<max_sill_h \
+ elsebase_plane.y*max_sill_h
+ div_segs=tuple(seg.move(sill_vec)forseginbtm_div_segs)
+ # scale the segments along their center points
+ seg_width=div_segs[0].length
+ subrect_width=(target_area/sub_rect_height)/num_div
+ scale_fac=subrect_width/seg_width
+ scaled_segs=[seg.scale(scale_fac,seg.midpoint)forsegindiv_segs]
+ # find the maximum acceptable area for splitting the glazing vertically.
+ ifvertical_separation!=0:
+ max_split_vert=parent_height-sill_height-sub_rect_height \
+ -(0.02*parent_height)
+ ifvertical_separation<0ormax_split_vert<0:
+ vertical_separation=0
+ elifvertical_separation>max_split_vert:
+ vertical_separation=max_split_vert
+ # generate the vertices by 'extruding' along a window height vector.
+ final_faces=[]
+ ifvertical_separation!=0:
+ sub_rect_height=sub_rect_height/2
+ h_vec=base_plane.y*sub_rect_height
+ vert_move_vec=base_plane.y*(sub_rect_height+vertical_separation)
+ vert_segs=[seg.move(vert_move_vec)forseginscaled_segs]
+ forseginscaled_segs+vert_segs:
+ final_faces.append(Face3D(
+ (seg.p1,seg.p2,seg.p2+h_vec,seg.p1+h_vec),base_plane))
+ else:
+ h_vec=base_plane.y*sub_rect_height
+ forseginscaled_segs:
+ final_faces.append(Face3D(
+ (seg.p1,seg.p2,seg.p2+h_vec,seg.p1+h_vec),base_plane))
+ else:
+ # make a single sub-rectangle at an appropriate sill height
+ max_sill_h=parent_height*0.99-(target_area/(parent_base*0.98))
+ sill_vec=base_plane.y*sill_heightifsill_height<max_sill_h \
+ elsebase_plane.y*max_sill_h
+ seg_init=bottom_seg.move(sill_vec)
+ seg=seg_init.scale(0.98,seg_init.midpoint)
+ # find the maximum acceptable area for splitting the glazing vertically.
+ ifvertical_separation!=0:
+ max_split_vert=parent_height-sill_height- \
+ (target_area/(parent_base*0.98))-(0.02*parent_height)
+ ifvertical_separation<0ormax_split_vert<0:
+ vertical_separation=0
+ elifvertical_separation>max_split_vert:
+ vertical_separation=max_split_vert
+ # generate the vertices by 'extruding' along a window height vector.
+ ifvertical_separation!=0:
+ sub_rect_height=(target_area/(parent_base*0.98))/2
+ h_vec=base_plane.y*sub_rect_height
+ vert_move_vec=base_plane.y*(sub_rect_height+vertical_separation)
+ vert_seg=seg.move(vert_move_vec)
+ final_faces=[]
+ forsegin[seg,vert_seg]:
+ final_faces.append(Face3D(
+ (seg.p1,seg.p2,seg.p2+h_vec,seg.p1+h_vec),base_plane))
+ else:
+ h_vec=base_plane.y*(target_area/(parent_base*0.98))
+ final_faces=[Face3D((seg.p1,seg.p2,seg.p2+h_vec,seg.p1+h_vec),
+ base_plane)]
+ returnfinal_faces
+
+
+
+[docs]
+ @staticmethod
+ defsub_rects_from_rect_dimensions(
+ base_plane,parent_base,parent_height,sub_rect_height,sub_rect_width,
+ sill_height,horizontal_separation):
+"""Get a list of rectangular Face3D objects from dimensions and parameters.
+
+ All of the resulting Face3D objects lie within a parent rectangle defined
+ by the parent_base, parent_height, and base_plane.
+
+ Args:
+ base_plane: A Plane object in which the rectangle exists.
+ The origin of this plane will be the lower left corner of the
+ rectangle and the X and Y axes will form the sides.
+ parent_base: A number indicating the length of the base of the
+ parent rectangle.
+ parent_height: A number indicating the length of the height of the
+ parent rectangle.
+ sub_rect_height: A number for the target height of the output rectangles.
+ sub_rect_width: A number for the target width of the output rectangles.
+ sill_height: A number for the target height above the bottom edge of
+ the rectangle to start the sub-rectangles. If the sub_rect_height
+ is too large for the sill_height to fit within the rectangle,
+ the sub_rect_height will take precedence.
+ horizontal_separation: A number for the target separation between
+ individual sub-rectangle center lines. If this number is larger than
+ the parent rectangle base, only one sub-rectangle will be produced.
+
+ Returns:
+ A list of Face3D objects for sub faces.
+ """
+ # if sub_rect_height > parent_height, set it to just under parent_height
+ sub_rect_height=parent_height-0.02*parent_heightif \
+ sub_rect_height>=parent_heightelsesub_rect_height
+ # if sill_height is close to 0, set it to just above 0
+ sill_hgt=0.01*parent_heightifsill_height<0.01*parent_height \
+ elsesill_height
+ # adjust sill_hgt if sum of it and sub_rect_height > parent_height
+ ifsub_rect_height+sill_hgt>=parent_height:
+ sill_hgt=parent_height-sub_rect_height-(parent_height*0.01)
+
+ # ensure that the horizontal_separation is always greater than sub_rect_width
+ ifsub_rect_width>=horizontal_separation:
+ horizontal_separation=sub_rect_width*1.02
+
+ # determine if the parameters should yield multiple sub-windows or just one
+ max_width_break_up=parent_base/2
+ num_div=round(parent_base/horizontal_separation)if \
+ parent_base>horizontal_separation/2else1
+ # properties used throughout the computation of sub-rectangles
+ sill_vec=base_plane.y*sill_hgt
+ bottom_seg=LineSegment3D.from_sdl(base_plane.o,base_plane.x,parent_base)
+
+ ifsub_rect_width<max_width_break_up:
+ # determine the number of times that the rectangle should be subdivided
+ div_dist=parent_base/2ifnum_div==1elsehorizontal_separation
+ ifnum_div*sub_rect_width+(num_div-1)* \
+ (horizontal_separation-sub_rect_width)>parent_base:
+ num_div=math.floor(parent_base/horizontal_separation)
+
+ # Get a segment in the center of the bottom
+ scale_fac=(div_dist*num_div)/parent_base
+ rect_seg=bottom_seg.scale(scale_fac,bottom_seg.point_at(0.5))
+ rect_seg=rect_seg.move(sill_vec)
+ btm_div_pts=rect_seg.subdivide_evenly(num_div)
+ iflen(btm_div_pts)==num_div:
+ btm_div_pts.append(rect_seg.p2)
+
+ # divide up the rectangle into points on the bottom
+ btm_div_segs=tuple(LineSegment3D.from_end_points(pt,btm_div_pts[i+1])
+ fori,ptinenumerate(btm_div_pts[:-1]))
+ # scale the line segments along their center points
+ line_cent_pt=tuple(line.point_at(0.5)forlineinbtm_div_segs)
+ scale_factor=sub_rect_width/div_dist
+ btm_div_segs=tuple(line.scale(scale_factor,mid_pt)
+ forline,mid_ptinzip(btm_div_segs,line_cent_pt))
+ # generate the vertices by 'extruding' along window height vector
+ h_vec=base_plane.y*sub_rect_height
+ final_faces=[Face3D((line.p2,line.p1,line.p1+h_vec,line.p2+h_vec),
+ base_plane)forlineinbtm_div_segs]
+ else:# make a single sub-rectangle at an appropriate sill height
+ ifsub_rect_width>=parent_base:
+ sub_rect_width=parent_base*0.98
+ scale_fac=sub_rect_width/parent_base
+ rect_seg=bottom_seg.scale(scale_fac,bottom_seg.point_at(0.5))
+ seg=rect_seg.move(sill_vec)
+ # generate the vertices by 'extruding' along window height vector
+ h_vec=base_plane.y*sub_rect_height
+ final_faces=[Face3D((seg.p2,seg.p1,seg.p1+h_vec,seg.p2+h_vec),
+ base_plane)]
+ returnfinal_faces
+
+
+
+[docs]
+ defcoplanar_difference(self,faces,tolerance,angle_tolerance):
+"""Subtract one or more coplanar Face3D from this Face3D.
+
+ Note that, when the faces are not coplanar or they do not overlap, a list
+ with only the original face will be returned.
+
+ Args:
+ faces: A list of Face3D for which will be subtracted from this Face3D.
+ tolerance: The minimum difference between X, Y and Z values at which
+ vertices are considered distinct from one another.
+ angle_tolerance: The max angle in radians that the plane normals can
+ differ from one another in order for them to be considered coplanar.
+
+ Returns:
+ A List of Face3D representing the original Face3D with the input faces
+ subtracted from it.
+ """
+ # define the primary boolean polygon
+ prim_pl=self.plane
+ f1_poly=self.boundary_polygon2d
+ try:
+ f1_poly=f1_poly.remove_colinear_vertices(tolerance)
+ exceptAssertionError:# degenerate face input
+ return[self]
+ f1_polys=[(pb.BooleanPoint(pt.x,pt.y)forptinf1_poly.vertices)]
+ ifself.has_holes:
+ forholeinself.hole_polygon2d:
+ f1_polys.append((pb.BooleanPoint(pt.x,pt.y)forptinhole.vertices))
+ b_poly1=pb.BooleanPolygon(f1_polys)
+
+ # pre-process the Face3Ds to be intersected
+ relevant_b_polys=[]
+ forface2infaces:
+ # test whether the faces are coplanar
+ ifnotprim_pl.is_coplanar_tolerance(face2.plane,tolerance,angle_tolerance):
+ continue
+ # test whether the two polygons have any overlap in 2D space
+ f2_poly=Polygon2D(tuple(prim_pl.xyz_to_xy(pt)forptinface2.boundary))
+ iff1_poly.polygon_relationship(f2_poly,tolerance)==-1:
+ continue
+ # snap the polygons to one another to avoid tolerance issues
+ try:
+ f2_poly=f2_poly.remove_colinear_vertices(tolerance)
+ exceptAssertionError:# degenerate faces input
+ continue
+ s2_poly=f1_poly.snap_to_polygon(f2_poly,tolerance)
+ # get BooleanPolygons of the two faces
+ f2_polys=[(pb.BooleanPoint(pt.x,pt.y)forptins2_poly.vertices)]
+ ifface2.has_holes:
+ forholeinface2.holes:
+ h_pt2d=(prim_pl.xyz_to_xy(pt)forptinhole)
+ f2_polys.append((pb.BooleanPoint(pt.x,pt.y)forptinh_pt2d))
+ b_poly2=pb.BooleanPolygon(f2_polys)
+ relevant_b_polys.append(b_poly2)
+
+ # if no relevant polygons were found, return self
+ iflen(relevant_b_polys)==0:
+ return[self]
+
+ # loop through the boolean polygons and subtract them
+ int_tol=tolerance/1000
+ forb_poly2inrelevant_b_polys:
+ # subtract the boolean polygons
+ try:
+ b_poly1=pb.difference(b_poly1,b_poly2,int_tol)
+ exceptException:
+ return[self]# typically a tolerance issue causing failure
+
+ # rebuild the Face3D from the result of the subtraction
+ returnFace3D._from_bool_poly(b_poly1,prim_pl,tolerance)
+
+
+
+[docs]
+ @staticmethod
+ defcoplanar_union(face1,face2,tolerance,angle_tolerance):
+"""Boolean Union two coplanar Face3D with one another.
+
+ Args:
+ face1: A Face3D for the first face that will be unioned with the second face.
+ face2: A Face3D for the second face that will be unioned with the first face.
+ tolerance: The minimum difference between X, Y and Z values at which
+ vertices are considered distinct from one another.
+ angle_tolerance: The max angle in radians that the plane normals can
+ differ from one another in order for them to be considered coplanar.
+
+ Returns:
+ A single Face3D for the Union of the two input Face3D. When the faces
+ are not coplanar or they do not overlap, None will be returned.
+ """
+ # test whether the faces are coplanar
+ prim_pl=face1.plane
+ ifnotprim_pl.is_coplanar_tolerance(face2.plane,tolerance,angle_tolerance):
+ returnNone
+ # test whether the two polygons have any overlap in 2D space
+ f1_poly=face1.boundary_polygon2d
+ f2_poly=Polygon2D(tuple(prim_pl.xyz_to_xy(pt)forptinface2.boundary))
+ iff1_poly.polygon_relationship(f2_poly,tolerance)==-1:
+ returnNone
+ # snap the polygons to one another to avoid tolerance issues
+ try:
+ f1_poly=f1_poly.remove_colinear_vertices(tolerance)
+ f2_poly=f2_poly.remove_colinear_vertices(tolerance)
+ exceptAssertionError:# degenerate faces input
+ returnNone
+ s2_poly=f1_poly.snap_to_polygon(f2_poly,tolerance)
+ # get BooleanPolygons of the two faces
+ f1_polys=[(pb.BooleanPoint(pt.x,pt.y)forptinf1_poly.vertices)]
+ f2_polys=[(pb.BooleanPoint(pt.x,pt.y)forptins2_poly.vertices)]
+ ifface1.has_holes:
+ forholeinface1.hole_polygon2d:
+ f1_polys.append((pb.BooleanPoint(pt.x,pt.y)forptinhole.vertices))
+ ifface2.has_holes:
+ forholeinface2.holes:
+ h_pt2d=(prim_pl.xyz_to_xy(pt)forptinhole)
+ f2_polys.append((pb.BooleanPoint(pt.x,pt.y)forptinh_pt2d))
+ b_poly1=pb.BooleanPolygon(f1_polys)
+ b_poly2=pb.BooleanPolygon(f2_polys)
+ # union the two boolean polygons with one another
+ int_tol=tolerance/1000
+ try:
+ poly_result=pb.union(b_poly1,b_poly2,int_tol)
+ exceptException:
+ returnNone# typically a tolerance issue causing failure
+ # rebuild the Face3D from the results and return them
+ union_faces=Face3D._from_bool_poly(poly_result,prim_pl,tolerance)
+ returnunion_faces[0]
+
+
+
+[docs]
+ @staticmethod
+ defcoplanar_intersection(face1,face2,tolerance,angle_tolerance):
+"""Boolean Intersection two coplanar Face3D with one another.
+
+ Args:
+ face1: A Face3D for the first face that will be intersected with
+ the second face.
+ face2: A Face3D for the second face that will be intersected with
+ the first face.
+ tolerance: The minimum difference between X, Y and Z values at which
+ vertices are considered distinct from one another.
+ angle_tolerance: The max angle in radians that the plane normals can
+ differ from one another in order for them to be considered coplanar.
+
+ Returns:
+ A list of Face3D for the Intersection of the two input Face3D.
+ When the faces are not coplanar or they do not overlap, None will
+ be returned.
+ """
+ # test whether the faces are coplanar
+ prim_pl=face1.plane
+ ifnotprim_pl.is_coplanar_tolerance(face2.plane,tolerance,angle_tolerance):
+ returnNone
+ # test whether the two polygons have any overlap in 2D space
+ f1_poly=face1.boundary_polygon2d
+ f2_poly=Polygon2D(tuple(prim_pl.xyz_to_xy(pt)forptinface2.boundary))
+ iff1_poly.polygon_relationship(f2_poly,tolerance)==-1:
+ returnNone
+ # snap the polygons to one another to avoid tolerance issues
+ try:
+ f1_poly=f1_poly.remove_colinear_vertices(tolerance)
+ f2_poly=f2_poly.remove_colinear_vertices(tolerance)
+ exceptAssertionError:# degenerate faces input
+ returnNone
+ s2_poly=f1_poly.snap_to_polygon(f2_poly,tolerance)
+ # get BooleanPolygons of the two faces
+ f1_polys=[(pb.BooleanPoint(pt.x,pt.y)forptinf1_poly.vertices)]
+ f2_polys=[(pb.BooleanPoint(pt.x,pt.y)forptins2_poly.vertices)]
+ ifface1.has_holes:
+ forholeinface1.hole_polygon2d:
+ f1_polys.append((pb.BooleanPoint(pt.x,pt.y)forptinhole.vertices))
+ ifface2.has_holes:
+ forholeinface2.holes:
+ h_pt2d=(prim_pl.xyz_to_xy(pt)forptinhole)
+ f2_polys.append((pb.BooleanPoint(pt.x,pt.y)forptinh_pt2d))
+ b_poly1=pb.BooleanPolygon(f1_polys)
+ b_poly2=pb.BooleanPolygon(f2_polys)
+ # intersect the two boolean polygons with one another
+ int_tol=tolerance/1000
+ try:
+ poly_result=pb.intersect(b_poly1,b_poly2,int_tol)
+ exceptException:
+ returnNone# typically a tolerance issue causing failure
+ # rebuild the Face3D from the results and return them
+ int_faces=Face3D._from_bool_poly(poly_result,prim_pl,tolerance)
+ returnint_faces
+
+
+
+[docs]
+ @staticmethod
+ defcoplanar_split(face1,face2,tolerance,angle_tolerance):
+"""Split two coplanar Face3D with one another (ensuring matching overlapped area)
+
+ When the faces are not coplanar or they do not overlap, the original
+ faces will be returned.
+
+ Args:
+ face1: A Face3D for the first face that will be split with the second face.
+ face2: A Face3D for the second face that will be split with the first face.
+ tolerance: The minimum difference between X, Y and Z values at which
+ vertices are considered distinct from one another.
+ angle_tolerance: The max angle in radians that the plane normals can
+ differ from one another in order for them to be considered coplanar.
+
+ Returns:
+ A tuple with two elements
+
+ - face1_split: A list of Face3D for the split version of the input face1.
+
+ - face2_split: A list of Face3D for the split version of the input face2.
+ """
+ # test whether the faces are coplanar
+ prim_pl=face1.plane
+ ifnotprim_pl.is_coplanar_tolerance(face2.plane,tolerance,angle_tolerance):
+ return[face1],[face2]
+ # test whether the two polygons have any overlap in 2D space
+ f1_poly=face1.boundary_polygon2d
+ f2_poly=Polygon2D(tuple(prim_pl.xyz_to_xy(pt)forptinface2.boundary))
+ iff1_poly.polygon_relationship(f2_poly,tolerance)==-1:
+ return[face1],[face2]
+ # snap the polygons to one another to avoid tolerance issues
+ try:
+ f1_poly=f1_poly.remove_colinear_vertices(tolerance)
+ f2_poly=f2_poly.remove_colinear_vertices(tolerance)
+ exceptAssertionError:# degenerate faces input
+ return[face1],[face2]
+ s2_poly=f1_poly.snap_to_polygon(f2_poly,tolerance)
+ # get BooleanPolygons of the two faces
+ f1_polys=[(pb.BooleanPoint(pt.x,pt.y)forptinf1_poly.vertices)]
+ f2_polys=[(pb.BooleanPoint(pt.x,pt.y)forptins2_poly.vertices)]
+ ifface1.has_holesandface2.has_holes:# snap corresponding holes together
+ f1h_polys=face1.hole_polygon2d
+ f2h_polys=[Polygon2D(tuple(prim_pl.xyz_to_xy(pt)forptinh_pts))
+ forh_ptsinface2.holes]
+ forf1hpinf1h_polys:
+ forhi,f2hpinenumerate(f2h_polys):
+ iff1hp.center.distance_to_point(f2hp.center)<tolerance:
+ f2h_polys[hi]=f1hp.snap_to_polygon(f2hp,tolerance)
+ forholeinf1h_polys:
+ f1_polys.append((pb.BooleanPoint(pt.x,pt.y)forptinhole.vertices))
+ forholeinf2h_polys:
+ f2_polys.append((pb.BooleanPoint(pt.x,pt.y)forptinhole.vertices))
+ elifface1.has_holes:
+ forholeinface1.hole_polygon2d:
+ f1_polys.append((pb.BooleanPoint(pt.x,pt.y)forptinhole.vertices))
+ elifface2.has_holes:
+ forholeinface2.holes:
+ h_pt2d=(prim_pl.xyz_to_xy(pt)forptinhole)
+ f2_polys.append((pb.BooleanPoint(pt.x,pt.y)forptinh_pt2d))
+ b_poly1=pb.BooleanPolygon(f1_polys)
+ b_poly2=pb.BooleanPolygon(f2_polys)
+ # split the two boolean polygons with one another
+ int_tol=tolerance/1000
+ try:
+ int_result,poly1_result,poly2_result=pb.split(b_poly1,b_poly2,int_tol)
+ exceptException:
+ return[face1],[face2]# typically a tolerance issue causing failure
+ # rebuild the Face3D from the results and return them
+ int_faces=Face3D._from_bool_poly(int_result,prim_pl,tolerance)
+ poly1_faces=Face3D._from_bool_poly(poly1_result,prim_pl,tolerance)
+ poly2_faces=Face3D._from_bool_poly(poly2_result,prim_pl,tolerance)
+ face1_split=poly1_faces+int_faces
+ face2_split=poly2_faces+int_faces
+ returnface1_split,face2_split
+
+
+
+[docs]
+ @staticmethod
+ defcoplanar_union_all(faces,tolerance,angle_tolerance):
+"""Boolean Union several coplanar Face3D together.
+
+ Note that this method does not perform any check for whether the input
+ faces overlap before it performs the unioning operation. So it is
+ recommended that the Face3D.group_by_coplanar_overlap method be run
+ before using this method to union each group together.
+
+ Args:
+ faces: A list of Face3D that will be unioned together.
+ tolerance: The minimum difference between X, Y and Z values at which
+ vertices are considered distinct from one another.
+ angle_tolerance: The max angle in radians that the plane normals can
+ differ from one another in order for them to be considered coplanar.
+
+ Returns:
+ A list of Face3D for the Union of all the input Face3D. When the faces
+ are not coplanar, None will be returned.
+ """
+ # test whether the faces are coplanar
+ prim_pl=faces[0].plane
+ forofinfaces[1:]:
+ ifnotprim_pl.is_coplanar_tolerance(of.plane,tolerance,angle_tolerance):
+ returnNone
+ # convert all boundaries and holes to 2D space
+ hole_decoder=[False]
+ all_poly=[faces[0].boundary_polygon2d]
+ iffaces[0].has_holes:
+ forholeinfaces[0].hole_polygon2d:
+ all_poly.extend(hole)
+ hole_decoder.append(True)
+ forofinfaces[1:]:
+ of_poly=Polygon2D(tuple(prim_pl.xyz_to_xy(pt)forptinof.boundary))
+ all_poly.append(of_poly)
+ hole_decoder.append(False)
+ ifof.has_holes:
+ forholeinof.holes:
+ h_poly=Polygon2D(tuple(prim_pl.xyz_to_xy(pt)forptinhole))
+ all_poly.extend(h_poly)
+ hole_decoder.append(True)
+ # snap the polygons to one another to avoid tolerance issues
+ try:
+ all_poly=[ply.remove_colinear_vertices(tolerance)forplyinall_poly]
+ exceptAssertionError:# degenerate faces input
+ returnNone
+ all_poly=Polygon2D.snap_polygons(all_poly,tolerance)
+ # create BooleanPolygons of the faces
+ bool_polys=[]
+ prev_poly=None
+ forply,is_holeinzip(all_poly,hole_decoder):
+ bool_pts=(pb.BooleanPoint(pt.x,pt.y)forptinply.vertices)
+ ifnotis_hole:
+ ifprev_polyisnotNone:
+ bool_polys.append(pb.BooleanPolygon(prev_poly))
+ prev_poly=[bool_pts]
+ else:
+ prev_poly.append(bool_pts)
+ bool_polys.append(pb.BooleanPolygon(prev_poly))
+ # union the boolean polygons with one another
+ int_tol=tolerance/100
+ try:
+ poly_result=pb.union_all(bool_polys,int_tol)
+ exceptException:
+ returnNone# typically a tolerance issue causing failure
+ # rebuild the Face3D from the results and return them
+ union_faces=Face3D._from_bool_poly(poly_result,prim_pl,tolerance)
+ returnunion_faces
+
+
+ @staticmethod
+ def_from_bool_poly(bool_polygon,plane,tolerance=None):
+"""Get a list of Face3D from a BooleanPolygon.
+
+ This method will automatically check whether any of the regions is meant
+ to be a hole within the others when it creates the Face3D.
+
+ Args:
+ bool_polygon: A BooleanPolygon to be interpreted to Face3D.
+ plane: The Plane in which the resulting Face3Ds exist.
+ tolerance: An optional tolerance value to be used to remove
+ degenerate objects from the result. If None, the result may
+ contain degenerate objects.
+ """
+ # serialize the BooleanPolygon into Polygon2D
+ polys=[]
+ fornew_polyinbool_polygon.regions:
+ iflen(new_poly)>2:
+ poly=Polygon2D(tuple(Point2D(pt.x,pt.y)forptinnew_poly))
+ iftoleranceisnotNone:
+ try:
+ poly=poly.remove_duplicate_vertices(tolerance)
+ polys.append(poly)
+ exceptAssertionError:
+ pass# degenerate polygon to be removed
+ else:
+ polys.append(poly)
+ iflen(polys)==0:
+ return[]
+ iflen(polys)==1:
+ verts_3d=tuple(plane.xy_to_xyz(pt)forptinpolys[0].vertices)
+ return[Face3D(verts_3d,plane)]
+ # sort the polygons by area and check if any are inside the others
+ polys.sort(key=lambdax:x.area,reverse=True)
+ poly_groups=[[polys[0]]]
+ forsub_polyinpolys[1:]:
+ fori,pginenumerate(poly_groups):
+ ifpg[0].is_polygon_inside(sub_poly):# it's a hole
+ poly_groups[i].append(sub_poly)
+ break
+ else:# it's a separate Face3D
+ poly_groups.append([sub_poly])
+ # convert all vertices to 3D and return the Face3D
+ face_3d=[]
+ forpginpoly_groups:
+ pg_3d=[]
+ forshpinpg:
+ pg_3d.append(tuple(plane.xy_to_xyz(pt)forptinshp.vertices))
+ face_3d.append(Face3D(pg_3d[0],plane,holes=pg_3d[1:]))
+ returnface_3d
+
+
+[docs]
+ @staticmethod
+ defgroup_by_coplanar_overlap(faces,tolerance):
+"""Group coplanar Face3Ds depending on whether they overlap one another.
+
+ This is useful as a pre-step before running Face3D.coplanar_union()
+ in order to assess whether union-ing is necessary and to ensure that
+ it is only performed among the necessary groups of faces.
+
+ This method will return the minimal number of overlapping polygon groups
+ thanks to a recursive check of whether groups can be merged.
+
+ Args:
+ faces: A list of Face3D to be grouped by their overlapping.
+ tolerance: The minimum distance from the edge of a neighboring Face3D
+ at which a point is considered to overlap with that Face3D.
+
+ Returns:
+ A list of lists where each sub-list represents a group of Face3Ds
+ that all overlap with one another.
+ """
+ # sort the faces by area to ensure larger ones grab smaller ones
+ faces=list(sorted(faces,key=lambdax:x.area,reverse=True))
+ # create polygons for all of the faces
+ r_plane=faces[0].plane
+ polygons=[Polygon2D([r_plane.xyz_to_xy(pt)forptinface.vertices])
+ forfaceinfaces]
+
+ # loop through the polygons and check to see if it overlaps with the others
+ grouped_polys,grouped_faces=[[polygons[0]]],[[faces[0]]]
+ forpoly,faceinzip(polygons[1:],faces[1:]):
+ group_found=False
+ forpoly_group,face_groupinzip(grouped_polys,grouped_faces):
+ foroth_polyinpoly_group:
+ ifpoly.polygon_relationship(oth_poly,tolerance)>=0:
+ poly_group.append(poly)
+ face_group.append(face)
+ group_found=True
+ break
+ ifgroup_found:
+ break
+ ifnotgroup_found:# the polygon does not overlap with any of the others
+ grouped_polys.append([poly])# make a new group for the polygon
+ grouped_faces.append([face])# make a new group for the face
+
+ # if some groups were found, recursively merge groups together
+ old_group_len=len(polygons)
+ whilelen(grouped_polys)!=old_group_len:
+ new_poly_groups,new_face_groups=grouped_polys[:],grouped_faces[:]
+ g_to_remove=[]
+ fori,group_1inenumerate(grouped_polys):
+ try:
+ zip_obj=zip(grouped_polys[i+1:],grouped_faces[i+1:])
+ forj,(group_2,f2)inenumerate(zip_obj):
+ ifPolygon2D._groups_overlap(group_1,group_2,tolerance):
+ new_poly_groups[i]=new_poly_groups[i]+group_2
+ new_face_groups[i]=new_face_groups[i]+f2
+ g_to_remove.append(i+j+1)
+ exceptIndexError:
+ pass# we have reached the end of the list of polygons
+ iflen(g_to_remove)!=0:
+ g_to_remove=list(set(g_to_remove))
+ g_to_remove.sort()
+ forriinreversed(g_to_remove):
+ new_poly_groups.pop(ri)
+ new_face_groups.pop(ri)
+ old_group_len=len(grouped_polys)
+ grouped_polys=new_poly_groups
+ grouped_faces=new_face_groups
+ returngrouped_faces
+
+
+
+[docs]
+ @staticmethod
+ defjoin_coplanar_faces(faces,tolerance):
+"""Join a list of coplanar Face3Ds together to get as few as possible.
+
+ Note that this method does not perform any boolean union operations on
+ the input faces. It will only join the objects together along shared edges.
+
+ Args:
+ faces: A list of Face3D objects to be joined together. These should
+ all be coplanar but they do not need to have their colinear
+ vertices removed or be intersected for matching segments along
+ which they are joined.
+ tolerance: The maximum difference between values at which point vertices
+ are considered to be the same.
+
+ Returns:
+ A list of Face3Ds for the minimum number joined together.
+ """
+ # get polygons for the faces that all lie within the same plane
+ face_polys,base_plane=[],faces[0].plane
+ forfginfaces:
+ verts2d=tuple(base_plane.xyz_to_xy(_v)for_vinfg.boundary)
+ face_polys.append(Polygon2D(verts2d))
+ iffg.has_holes:
+ forholeinfg.holes:
+ verts2d=tuple(base_plane.xyz_to_xy(_v)for_vinhole)
+ face_polys.append(Polygon2D(verts2d))
+
+ # remove colinear vertices
+ clean_face_polys=[]
+ forgeoinface_polys:
+ try:
+ clean_face_polys.append(geo.remove_colinear_vertices(tolerance))
+ exceptAssertionError:# degenerate geometry to ignore
+ pass
+
+ # get the joined boundaries around the Polygon2D
+ joined_bounds=Polygon2D.joined_intersected_boundary(
+ clean_face_polys,tolerance)
+
+ # convert the boundary polygons back to Face3D
+ iflen(joined_bounds)==1:# can be represented with a single Face3D
+ verts3d=tuple(base_plane.xy_to_xyz(_v)for_vinjoined_bounds[0])
+ return[Face3D(verts3d,plane=base_plane)]
+ else:# need to separate holes from distinct Face3Ds
+ bound_faces=[]
+ forpolyinjoined_bounds:
+ verts3d=tuple(base_plane.xy_to_xyz(_v)for_vinpoly)
+ bound_faces.append(Face3D(verts3d,plane=base_plane))
+ returnFace3D.merge_faces_to_holes(bound_faces,tolerance)
+
+
+
+[docs]
+ @staticmethod
+ defmerge_faces_to_holes(faces,tolerance):
+"""Take of list of Face3Ds and merge any sub-faces into the others as holes.
+
+ This is particularly useful when translating 2D Polygons back into a 3D
+ space and it is unknown whether certain polygons represent holes in the
+ others.
+
+ Args:
+ faces: A list of Face3D which will be merged into fewer faces with
+ any sub-faces represented as holes.
+ tolerance: The tolerance to be used for evaluating sub-faces.
+ """
+ # sort the faces by area and separate base face from the remaining
+ faces=sorted(faces,key=lambdax:x.area,reverse=True)
+ base_face=faces[0]
+ remain_faces=list(faces[1:])
+
+ # merge the smaller faces into the larger faces
+ merged_face3ds=[]
+ whilelen(remain_faces)>0:
+ merged_face3ds.append(
+ Face3D._match_holes_to_face(base_face,remain_faces,tolerance))
+ iflen(remain_faces)>1:
+ base_face=remain_faces[0]
+ delremain_faces[0]
+ eliflen(remain_faces)==1:# lone last Face3D
+ merged_face3ds.append(remain_faces[0])
+ delremain_faces[0]
+ returnmerged_face3ds
+
+
+ @staticmethod
+ def_match_holes_to_face(base_face,other_faces,tol):
+"""Attempt to merge other faces into a base face as holes.
+
+ Args:
+ base_face: A Face3D to serve as the base.
+ other_faces: A list of other Face3D objects to attempt to merge into
+ the base_face as a hole. This method will delete any faces
+ that are successfully merged into the output from this list.
+ tol: The tolerance to be used for evaluating sub-faces.
+
+ Returns:
+ A Face3D which has holes in it if any of the other_faces is a valid
+ sub face.
+ """
+ holes=[]
+ more_to_check=True
+ whilemore_to_check:
+ fori,r_faceinenumerate(other_faces):
+ ifbase_face.is_sub_face(r_face,tol,1):
+ holes.append(r_face)
+ delother_faces[i]
+ break
+ else:
+ more_to_check=False
+ iflen(holes)==0:
+ returnbase_face
+ else:
+ hole_verts=[hole.verticesforholeinholes]
+ returnFace3D(base_face.vertices,base_face.plane,hole_verts)
+
+
+[docs]
+ defto_dict(self,include_plane=True,enforce_upper_left=False):
+"""Get Face3D as a dictionary.
+
+ Args:
+ include_plane: Set to True to include the Face3D plane in the
+ dictionary, which will preserve the underlying orientation
+ of the face plane. Default True.
+ enforce_upper_left: Set to True to ensure that the boundary vertices all
+ start from the upper-left corner. This takes extra time to compute but
+ ensures that the vertices in the dictionary are directly usable in an
+ EnergyPlus simulations. Default: False.
+ """
+ base={'type':'Face3D'}
+ ifnotenforce_upper_left:
+ base['boundary']=[pt.to_array()forptinself.boundary]
+ else:
+ base['boundary']=[pt.to_array()forptin
+ self._upper_left_counter_clockwise_boundary()]
+ ifinclude_plane:
+ base['plane']=self.plane.to_dict()
+ ifself.has_holes:
+ base['holes']=[[pt.to_array()forptinhole]
+ forholeinself.holes]
+ returnbase
+
+
+
+[docs]
+ defto_array(self):
+"""Get Face3D as a nested list of tuples where each sub-tuple represents loop.
+
+ The first loop is always the outer boundary and successive loops represent
+ holes in the face (if they exist). Each sub-tuple is composed of tuples
+ that each have a length of 3 and denote 3D points that define the face.
+ """
+ ifself.has_holes:
+ return(tuple(pt.to_array()forptinself.boundary),)+ \
+ tuple(tuple(pt.to_array()forptinhole)forholeinself.holes)
+ else:
+ return(tuple(pt.to_array()forptinself.boundary),)
+
+
+
+[docs]
+ @staticmethod
+ defextract_all_from_stl(file_path):
+"""Get a list of Face3Ds imported from all of the triangles in an STL file.
+
+ Args:
+ file_path: Path to an STL file as a text string. The STL file can be
+ in either ASCII or binary format.
+ """
+ fromladybug_geometry.interop.stlimportSTL# avoid circular import
+ stl_obj=STL.from_file(file_path)
+ all_faces=[]
+ forverts,normalinzip(stl_obj.face_vertices,stl_obj.face_normals):
+ all_faces.append(Face3D(verts,plane=Plane(normal,verts[0])))
+ returnall_faces
+
+
+ def_check_vertices_input(self,vertices,loop_name='boundary'):
+ ifnotisinstance(vertices,tuple):
+ vertices=tuple(vertices)
+ assertlen(vertices)>=3,'There must be at least 3 vertices for a Face3D {}.' \
+ ' Got {}'.format(loop_name,len(vertices))
+ forvertinvertices:
+ assertisinstance(vert,Point3D), \
+ 'Expected Point3D for Face3D {} vertex. Got {}.'.format(
+ loop_name,type(vert))
+ returnvertices
+
+ def_check_number_mesh_grid(self,input,name):
+ assertisinstance(input,(float,int)),'{} for Face3D.get_mesh_grid' \
+ ' must be a number. Got {}.'.format(name,type(input))
+
+ def_move(self,vertices,mov_vec):
+ returntuple(pt.move(mov_vec)forptinvertices)
+
+ def_rotate(self,vertices,axis,angle,origin):
+ returntuple(pt.rotate(axis,angle,origin)forptinvertices)
+
+ def_rotate_xy(self,vertices,angle,origin):
+ returntuple(pt.rotate_xy(angle,origin)forptinvertices)
+
+ def_reflect(self,vertices,normal,origin):
+ returntuple(pt.reflect(normal,origin)forptinreversed(vertices))
+
+ def_scale(self,vertices,factor,origin):
+ iforiginisNone:
+ returntuple(
+ Point3D(pt.x*factor,pt.y*factor,pt.z*factor)
+ forptinvertices)
+ else:
+ returntuple(pt.scale(factor,origin)forptinvertices)
+
+ def_face_transform(self,verts,plane):
+"""Transform face in a way that transfers properties and avoids checks."""
+ _new_face=Face3D(verts,plane,enforce_right_hand=False)
+ self._transfer_properties(_new_face)
+ _new_face._polygon2d=self._polygon2d
+ _new_face._mesh2d=self._mesh2d
+ return_new_face
+
+ def_face_transform_reflect(self,verts,plane):
+"""Reflect face in a way that transfers properties and avoids checks."""
+ _new_face=Face3D(verts,plane,enforce_right_hand=False)
+ self._transfer_properties(_new_face)
+ return_new_face
+
+ def_face_transform_scale(self,verts,plane,factor):
+"""Scale face in a way that transfers properties and avoids checks."""
+ _new_face=Face3D(verts,plane,enforce_right_hand=False)
+ self._transfer_properties_scale(_new_face,factor)
+ return_new_face
+
+ def_transfer_properties(self,new_face):
+"""Transfer properties from this face to a new face.
+
+ This is used by the transform methods that don't alter the relationship of
+ face vertices to one another (move, rotate, reflect).
+ """
+ new_face._perimeter=self._perimeter
+ new_face._area=self._area
+ new_face._is_convex=self._is_convex
+ new_face._is_self_intersecting=self._is_self_intersecting
+
+ def_transfer_properties_scale(self,new_face,factor):
+"""Transfer properties from this face to a new face.
+
+ This is used by the methods that scale the face.
+ """
+ new_face._is_convex=self._is_convex
+ new_face._is_self_intersecting=self._is_self_intersecting
+ ifself._perimeterisnotNone:
+ new_face._perimeter=self._perimeter*factor
+ ifself._areaisnotNone:
+ new_face._area=self._area*factor**2
+
+ def_calculate_min_max(self):
+"""Calculate maximum and minimum Point3D for this object."""
+ min_pt=[self.boundary[0].x,self.boundary[0].y,self.boundary[0].z]
+ max_pt=[self.boundary[0].x,self.boundary[0].y,self.boundary[0].z]
+
+ forvinself.boundary[1:]:
+ ifv.x<min_pt[0]:
+ min_pt[0]=v.x
+ elifv.x>max_pt[0]:
+ max_pt[0]=v.x
+ ifv.y<min_pt[1]:
+ min_pt[1]=v.y
+ elifv.y>max_pt[1]:
+ max_pt[1]=v.y
+ ifv.z<min_pt[2]:
+ min_pt[2]=v.z
+ elifv.z>max_pt[2]:
+ max_pt[2]=v.z
+
+ self._min=Point3D(min_pt[0],min_pt[1],min_pt[2])
+ self._max=Point3D(max_pt[0],max_pt[1],max_pt[2])
+
+ def_remove_colinear(self,pts_3d,pts_2d,tolerance):
+"""Remove colinear vertices from a list of Point2D.
+
+ This method determines co-linearity by checking whether the area of the
+ triangle formed by 3 vertices is less than the tolerance.
+ """
+ new_vertices=[]# list to hold the new vertices
+ skip=0# track the number of vertices being skipped/removed
+ first_skip,is_first,=0,True# track the number skipped from first vertex
+ # loop through vertices and remove all cases of colinear verts
+ fori,_vinenumerate(pts_2d):
+ _v2,_v1=pts_2d[i-2-skip],pts_2d[i-1]
+ _a=_v2.determinant(_v1)+_v1.determinant(_v)+_v.determinant(_v2)
+ b_dist=_v.distance_to_point(_v2)
+ b_dist=toleranceifb_dist<toleranceelseb_dist
+ tri_tol=(b_dist*tolerance)/2# area of triangle with tolerance height
+ ifabs(_a)>=tri_tol:# triangle area > area tolerance; not colinear
+ new_vertices.append(pts_3d[i-1])
+ skip=0
+ ifis_first:
+ is_first=False
+ first_skip=i-1
+ else:# colinear point to be removed
+ skip+=1
+ # catch case of last few vertices being equal but distinct from first point
+ ifskip!=0andfirst_skip!=-1:
+ assertabs(-2-skip)<=len(pts_2d), \
+ 'There must be at least 3 vertices for a Face3D.'
+ _v2,_v1,_v=pts_2d[-2-skip],pts_2d[-1],pts_2d[first_skip]
+ _a=_v2.determinant(_v1)+_v1.determinant(_v)+_v.determinant(_v2)
+ b_dist=_v.distance_to_point(_v2)
+ b_dist=toleranceifb_dist<toleranceelseb_dist
+ tri_tol=(b_dist*tolerance)/2# area of triangle with tolerance height
+ ifabs(_a)>=tri_tol:# triangle area > area tolerance; not colinear
+ new_vertices.append(pts_3d[-1])
+ returnnew_vertices
+
+ def_is_sub_face(self,face):
+"""Check if a face is a sub-face of this face, bypassing coplanar check.
+
+ Args:
+ face: Another face for which sub-face equivalency will be tested.
+ """
+ verts2d=tuple(self.plane.xyz_to_xy(_v)for_vinface.vertices)
+ sub_poly=Polygon2D(verts2d)
+
+ ifnotself.has_holes:
+ returnself.polygon2d.is_polygon_inside(sub_poly)
+ else:
+ ifnotself.boundary_polygon2d.is_polygon_inside(sub_poly):
+ returnFalse
+ forhole_polyinself.hole_polygon2d:
+ ifnothole_poly.is_polygon_outside(sub_poly):
+ returnFalse
+ returnTrue
+
+ def_vertices_between_points(self,start_pt,end_pt,tolerance):
+"""Get the vertices between a start and end point.
+
+ This method is used by the extract_rectangle method.
+ """
+ new_verts=[start_pt]
+ vert_ind=self.vertices.index(start_pt)
+ found_other=False
+ whilefound_otherisFalse:
+ vert_ind-=1
+ new_verts.append(self[vert_ind])
+ ifself[vert_ind].is_equivalent(end_pt,tolerance):
+ found_other=True
+ returnnew_verts
+
+ def_diagonal_along_self(self,direction_vector,tolerance):
+"""Get the diagonal oriented along this face and always starts on the left."""
+ tol_pt=Vector3D(1.0e-7,1.0e-7,1.0e-7)# closer than float tolerance
+ diagonal=LineSegment3D.from_end_points(self.min+tol_pt,self.max-tol_pt)
+ # invert the diagonal XY if it is not oriented with the face plane
+ ifself._plane.distance_to_point(diagonal.p)>tolerance:
+ start=Point3D(diagonal.p1.x,diagonal.p2.y,diagonal.p1.z)
+ end=Point3D(diagonal.p2.x,diagonal.p1.y,diagonal.p2.z)
+ diagonal=LineSegment3D.from_end_points(start,end)
+ # flip if there's a horizontal direction_vector to ensure always starts on left
+ ifdirection_vector.x!=0andself.normal.y>0:
+ diagonal=diagonal.flip()
+ returndiagonal
+
+ def_get_fin_extrusion_vector(self,depth,angle,contour_vector):
+"""Get the vector with which to extrude fins."""
+ extru_vec=self.plane.n*depth
+ ifangle!=0:
+ # interpret the complement of the 2D contour_vector into a 3D axis
+ cont_vec_complement=Vector2D(contour_vector.y,-contour_vector.x)
+ ref_plane=Plane(self._plane.n,Point3D(0,0,0),self._plane.x)
+ ifref_plane.y.z<0:
+ ref_plane=ref_plane.rotate(ref_plane.n,math.pi,ref_plane.o)
+ axis=ref_plane.xy_to_xyz(cont_vec_complement).normalize()
+ # rotate the extrusion vector around the axis
+ extru_vec=extru_vec.rotate(axis,angle)
+ returnextru_vec
+
+ def_get_extrusion_fins(self,contours,extru_vec,offset):
+"""Get fins from the contours and extrusion vector."""
+ ifoffset!=0:
+ off_vec=self.plane.n*offset
+ contours=tuple(seg.move(off_vec)forsegincontours)
+ returntuple(Face3D.from_extrusion(seg,extru_vec)forsegincontours)
+
+ def_split_with_rectangle(self,edge_1,edge_2,tolerance):
+"""Split this shape using two parallel edges of the face.
+
+ Result will be None if no rectangle can be obtained.
+
+ Returns:
+ rectangle_points: A tuple of 4 points that make the rectangle.
+ other_faces: A list of faces for the other parts of this Face that
+ are not a part of the rectangle.
+ """
+ # compute the 4 points defining the rectangle
+ close_pt_1=closest_point3d_on_line3d(edge_1.p1,edge_2)
+ close_pt_2=closest_point3d_on_line3d(edge_2.p2,edge_1)
+ close_pt_3=closest_point3d_on_line3d(edge_1.p2,edge_2)
+ close_pt_4=closest_point3d_on_line3d(edge_2.p1,edge_1)
+
+ # check that there is overlap between the top and bottom curves
+ ifclose_pt_1.is_equivalent(edge_2.p1,tolerance)or \
+ close_pt_3.is_equivalent(edge_2.p2,tolerance):
+ returnNone
+
+ # check that the two sides of the rectangle are inside the polygon.
+ mid_pt_1=self.plane.xyz_to_xy(
+ LineSegment3D.from_end_points(close_pt_1,close_pt_2).midpoint)
+ mid_pt_2=self.plane.xyz_to_xy(
+ LineSegment3D.from_end_points(close_pt_3,close_pt_4).midpoint)
+ ifself.polygon2d.point_relationship(mid_pt_1,tolerance)==-1or \
+ self.polygon2d.point_relationship(mid_pt_2,tolerance)==-1:
+ returnNone
+
+ # get extra faces outside of the rectangle
+ other_faces=[]
+ edge_pts_1=self._vertices_between_points(edge_1.p1,edge_2.p2,tolerance)
+ ifclose_pt_1.is_equivalent(edge_2.p2,tolerance)isFalse:
+ edge_pts_1.append(close_pt_1)
+ other_faces.append(Face3D(edge_pts_1,self.plane))
+ elifclose_pt_2.is_equivalent(edge_1.p1,tolerance)isFalse:
+ edge_pts_1.append(close_pt_2)
+ other_faces.append(Face3D(edge_pts_1,self.plane))
+ eliflen(edge_pts_1)>2:
+ other_faces.append(Face3D(edge_pts_1,self.plane))
+
+ edge_pts_2=self._vertices_between_points(edge_2.p1,edge_1.p2,tolerance)
+ ifclose_pt_3.is_equivalent(edge_2.p1,tolerance)isFalse:
+ edge_pts_2.append(close_pt_3)
+ other_faces.append(Face3D(edge_pts_2,self.plane))
+ elifclose_pt_4.is_equivalent(edge_1.p2,tolerance)isFalse:
+ edge_pts_2.append(close_pt_4)
+ other_faces.append(Face3D(edge_pts_2,self.plane))
+ eliflen(edge_pts_2)>2:
+ other_faces.append(Face3D(edge_pts_2,self.plane))
+
+ # check that any new faces are not self intersecting
+ fornew_faceinother_faces:
+ ifnew_face.is_self_intersecting:
+ returnNone
+
+ # return the rectangle edges and the extra faces
+ return(close_pt_1,close_pt_2,close_pt_3,close_pt_4),other_faces
+
+ def_point_on_face(self,tolerance):
+"""Get a point that is always reliably on this face.
+
+ The point will be close to the edge of the Face but it will always
+ be inside its boundary for all concave and holed geometries. Furthermore,
+ it is relatively fast compared with computing the pole_of_inaccessibility.
+ """
+ try:
+ face=self.remove_colinear_vertices(tolerance)
+ move_vec=self._inward_pointing_vec(face)
+ except(AssertionError,ZeroDivisionError):# zero area Face3D; use center
+ returnself.center
+
+ move_vec=move_vec*(tolerance+0.00001)
+ point_on_face=face.boundary[0]+move_vec
+ vert2d=face.plane.xyz_to_xy(point_on_face)
+ ifnotface.polygon2d.is_point_inside(vert2d):
+ point_on_face=face.boundary[0]-move_vec
+ returnpoint_on_face
+
+ def_upper_oriented_plane(self):
+"""Get a version of this Face3D's plane where Y is oriented towards positive Z.
+
+ If the Face3D is horizontal, the plane will be the World XY.
+ """
+ ifself._plane.n.z==1orself._plane.n.z==-1:# no vertex is above another
+ ref_plane=Plane(self._plane.n,self._plane.o,Vector3D(1,0,0))
+ else:
+ proj_y=Vector3D(0,0,1).project(self._plane.n)
+ proj_x=proj_y.rotate(self._plane.n,math.pi/-2)
+ ref_plane=Plane(self._plane.n,self._plane.o,proj_x)
+ returnref_plane
+
+ def_corner_point(self,x_corner='min',y_corner='min'):
+"""Get a Point3D that is in a particular corner of this Face3D.
+
+ Args:
+ x_corner: Either "min" or "max" depending on the desired corner.
+ y_corner: Either "min" or "max" depending on the desired corner.
+ """
+ # get a correctly-oriented polygon
+ ref_plane=self._upper_oriented_plane()
+ polygon=Polygon2D(tuple(ref_plane.xyz_to_xy(v)forvinself._boundary))
+ # sort points so that they start with the correct corner
+ x_pt=getattr(polygon,x_corner)
+ y_pt=getattr(polygon,y_corner)
+ returnref_plane.xy_to_xyz(Point2D(x_pt.x,y_pt.y))
+
+ def_corner_point_and_polygon(self,points_3d,x_corner='min',y_corner='min'):
+"""Get a Point2D and corresponding Polygon in a particular corner of this Face3D.
+
+ Args:
+ points_3d: A list of Point3Ds for the output Polygon.
+ x_corner: Either "min" or "max" depending on the desired corner.
+ y_corner: Either "min" or "max" depending on the desired corner.
+ """
+ ifself.is_horizontal(0.01):# EnergyPlus tolerance
+ polygon=Polygon2D(tuple(Point2D(v.x,v.y)forvinpoints_3d))
+ ifself._plane.n.z<0:# flip the direction of what counts as "right"
+ x_corner='max'ifx_corner=='min'else'min'
+ x_pt=getattr(self,x_corner)
+ y_pt=getattr(self,y_corner)
+ else:
+ # get a 2d polygon in the face plane that has a positive Y axis.
+ proj_y=Vector3D(0,0,1).project(self._plane.n)
+ proj_x=proj_y.rotate(self._plane.n,math.pi/-2)
+ ref_plane=Plane(self._plane.n,self._plane.o,proj_x)
+ polygon=Polygon2D(tuple(ref_plane.xyz_to_xy(v)forvinpoints_3d))
+ x_pt=getattr(polygon,x_corner)
+ y_pt=getattr(polygon,y_corner)
+ returnPoint2D(x_pt.x,y_pt.y),polygon
+
+ def_counter_clockwise_verts(self,polygon):
+"""Get aligned lists of counter-clockwise 2D and 3D vertices."""
+ ifself.is_clockwise:
+ returntuple(reversed(self.vertices)),tuple(reversed(polygon.vertices))
+ else:
+ returnself.vertices,polygon.vertices
+
+ def_counter_clockwise_bound(self,polygon):
+"""Get aligned lists of counter-clockwise 2D and 3D vertices."""
+ ifself.is_clockwise:
+ returntuple(reversed(self.boundary)),tuple(reversed(polygon.vertices))
+ else:
+ returnself.boundary,polygon.vertices
+
+ def_upper_left_counter_clockwise_boundary(self):
+"""Get this face's boundary starting from upper left and moving counterclockwise.
+
+ Horizontal faces will treat the positive Y axis as up. All other faces
+ treat the positive Z axis as up.
+
+ Unlike the upper_left_counter_clockwise_vertices property, this property
+ does not include any holes in the Face3D.
+ """
+ corner_pt,polygon=self._corner_point_and_polygon(self._boundary,'min','max')
+ ifself.is_clockwise:
+ verts3d,verts2d= \
+ tuple(reversed(self.boundary)),tuple(reversed(polygon.vertices))
+ else:
+ verts3d,verts2d=self.boundary,polygon.vertices
+ returnself._corner_pt_verts(corner_pt,verts3d,verts2d)
+
+ @staticmethod
+ def_inward_pointing_vec(face):
+"""Get a unit vector pointing inward/outward from the first vertex of a face."""
+ v1=face.boundary[-1]-face.boundary[0]
+ v2=face.boundary[1]-face.boundary[0]
+ ifv1.angle(v2)==math.pi:# colinear vertices; prevent averaging to zero
+ returnv1.rotate(face.normal,math.pi/2).normalize()
+ else:# average the two edge vectors together
+ avg_coords=((v1.x+v2.x)/2),((v1.y+v2.y)/2),((v1.z+v2.z)/2)
+ returnVector3D(*avg_coords).normalize()
+
+ @staticmethod
+ def_plane_from_vertices(verts):
+"""Get a plane from a list of vertices.
+
+ Args:
+ verts: The vertices to be used to extract the normal.
+ """
+ try:
+ # walk around the shape and get cross products
+ cprods,base_vert=[],verts[0]
+ foriinrange(len(verts)-2):
+ verts_3=(base_vert,verts[i+1],verts[i+2])
+ cprods.append(Face3D._normal_from_3pts(*verts_3))
+ # sum together the cross products
+ normal=[0,0,0]
+ forcprodxincprods:
+ normal[0]+=cprodx[0]
+ normal[1]+=cprodx[1]
+ normal[2]+=cprodx[2]
+ # normalize the vector
+ ifnormal!=[0,0,0]:
+ ds=math.sqrt(normal[0]**2+normal[1]**2+normal[2]**2)
+ normal_vec=Vector3D(normal[0]/ds,normal[1]/ds,normal[2]/ds)
+ else:# zero area Face3D; default to positive Z axis
+ normal_vec=Vector3D(0,0,1)
+ exceptExceptionase:
+ raiseValueError('Incorrect vertices input for Face3D:\n\t{}'.format(e))
+ returnPlane(normal_vec,verts[0])
+
+ @staticmethod
+ def_normal_from_3pts(pt1,pt2,pt3):
+"""Get a tuple representing a normal vector from 3 vertices.
+
+ The vector will have a magnitude of 0 if vertices are colinear.
+ This method effectively performs the cross product of two unit vectors but
+ the ladybug_geometry objects are not used in order to remove assertions
+ and increase speed.
+ """
+ # get two vectors for the two edges the 3 points form
+ v1=(pt2.x-pt1.x,pt2.y-pt1.y,pt2.z-pt1.z)
+ v2=(pt3.x-pt1.x,pt3.y-pt1.y,pt3.z-pt1.z)
+ # get the cross product of the two edge vectors
+ return(v1[1]*v2[2]-v1[2]*v2[1],
+ -v1[0]*v2[2]+v1[2]*v2[0],
+ v1[0]*v2[1]-v1[1]*v2[0])
+
+ @staticmethod
+ def_corner_pt_verts(corner_pt,verts3d,verts2d):
+"""Get verts3d starting from the one closes to the corner_pt."""
+ first_pt_index=0
+ min_dist=verts2d[0].distance_to_point(corner_pt)
+ forpt_index,ptinenumerate(verts2d[1:]):
+ new_dist=pt.distance_to_point(corner_pt)
+ ifnew_dist<min_dist:
+ first_pt_index=pt_index+1
+ min_dist=new_dist
+ iffirst_pt_index!=0:
+ verts3d=verts3d[first_pt_index:]+verts3d[:first_pt_index]
+ returnverts3d
+
+ def__copy__(self):
+ _new_face=Face3D(self.vertices,self.plane)
+ self._transfer_properties(_new_face)
+ _new_face._holes=self._holes
+ _new_face._polygon2d=self._polygon2d
+ _new_face._mesh2d=self._mesh2d
+ _new_face._mesh3d=self._mesh3d
+ return_new_face
+
+ def__key(self):
+"""A tuple based on the object properties, useful for hashing."""
+ returntuple(hash(pt)forptinself._vertices)+(hash(self._plane),)
+
+ def__hash__(self):
+ returnhash(self.__key())
+
+ def__eq__(self,other):
+ returnisinstance(other,Face3D)andself.__key()==other.__key()
+
+ def__repr__(self):
+ return'Face3D ({} vertices)'.format(len(self))
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/_modules/ladybug_geometry/geometry3d/line.html b/docs/_modules/ladybug_geometry/geometry3d/line.html
new file mode 100644
index 00000000..e337b77e
--- /dev/null
+++ b/docs/_modules/ladybug_geometry/geometry3d/line.html
@@ -0,0 +1,1506 @@
+
+
+
+
+
+
+ ladybug_geometry.geometry3d.line — ladybug geometry documentation
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+[docs]
+classLineSegment3D(Base1DIn3D):
+"""3D line segment object.
+
+ Args:
+ p: A Point3D representing the first point of the line segment.
+ v: A Vector3D representing the vector to the second point.
+
+ Properties:
+ * p
+ * v
+ * p1
+ * p2
+ * min
+ * max
+ * center
+ * midpoint
+ * endpoints
+ * length
+ * vertices
+ """
+ __slots__=()
+
+ def__init__(self,p,v):
+"""Initialize LineSegment3D."""
+ Base1DIn3D.__init__(self,p,v)
+
+
+[docs]
+ @classmethod
+ deffrom_end_points(cls,p1,p2):
+"""Initialize a line segment from a start point and and end point.
+
+ Args:
+ p1: A Point3D representing the first point of the line segment.
+ p2: A Point3D representing the second point of the line segment.
+ """
+ returncls(p1,p2-p1)
+
+
+
+[docs]
+ @classmethod
+ deffrom_sdl(cls,s,d,length):
+"""Initialize a line segment from a start point, direction, and length.
+
+ Args:
+ s: A Point3D representing the start point of the line segment.
+ d: A Vector3D representing the direction of the line segment.
+ length: A number representing the length of the line segment.
+ """
+ returncls(s,d*length/d.magnitude)
+
+
+
+[docs]
+ @classmethod
+ deffrom_array(cls,line_array):
+""" Create a LineSegment3D from a nested array of two endpoint coordinates.
+
+ Args:
+ line_array: Nested tuples ((pt1.x, pt1.y, pt.z), (pt2.x, pt2.y, pt.z)),
+ where pt1 and pt2 represent the endpoints of the line segment.
+ """
+ returnLineSegment3D.from_end_points(*tuple(Point3D(*pt)forptinline_array))
+
+
+
+[docs]
+ @classmethod
+ deffrom_line_segment2d(cls,line2d,z=0):
+"""Initialize a new LineSegment3D from an LineSegment2D and a z value.
+
+ Args:
+ line2d: A LineSegment2D to be used to generate the LineSegment3D.
+ z: A number for the Z coordinate value of the line.
+ """
+ base_p=Point3D(line2d.p.x,line2d.p.y,z)
+ base_v=Vector3D(line2d.v.x,line2d.v.y,0)
+ returncls(base_p,base_v)
+
+
+ @property
+ defp1(self):
+"""First point (same as p)."""
+ returnself.p
+
+ @property
+ defp2(self):
+"""Second point."""
+ returnPoint3D(self.p.x+self.v.x,self.p.y+self.v.y,self.p.z+self.v.z)
+
+ @property
+ defmidpoint(self):
+"""Midpoint."""
+ returnself.point_at(0.5)
+
+ @property
+ defendpoints(self):
+"""Tuple of endpoints """
+ return(self.p1,self.p2)
+
+ @property
+ deflength(self):
+"""The length of the line segment."""
+ returnself.v.magnitude
+
+ @property
+ defvertices(self):
+"""Tuple of both vertices in this object."""
+ return(self.p1,self.p2)
+
+
+[docs]
+ defis_horizontal(self,tolerance):
+"""Test whether this line segment is horizontal within a certain tolerance.
+
+ Args:
+ tolerance: The maximum difference between the z values of the start and
+ end coordinates at which the line segment is considered horizontal.
+ """
+ returnabs(self.v.z)<=tolerance
+
+
+
+[docs]
+ defis_vertical(self,tolerance):
+"""Test whether this line segment is vertical within a certain tolerance.
+
+ Args:
+ tolerance: The maximum difference between the x and y values of the start
+ and end coordinates at which the line segment is considered horizontal.
+ """
+ returnabs(self.v.x)<=toleranceandabs(self.v.y)<=tolerance
+
+
+
+[docs]
+ defflip(self):
+"""Get a copy of this line segment that is flipped."""
+ returnLineSegment3D(self.p2,self.v.reverse())
+
+
+
+[docs]
+ defmove(self,moving_vec):
+"""Get a line segment that has been moved along a vector.
+
+ Args:
+ moving_vec: A Vector3D with the direction and distance to move the ray.
+ """
+ returnLineSegment3D(self.p.move(moving_vec),self.v)
+
+
+
+[docs]
+ defrotate(self,axis,angle,origin):
+"""Rotate a line segment by a certain angle around an axis and origin.
+
+ Right hand rule applies:
+ If axis has a positive orientation, rotation will be clockwise.
+ If axis has a negative orientation, rotation will be counterclockwise.
+
+ Args:
+ axis: A Vector3D axis representing the axis of rotation.
+ angle: An angle for rotation in radians.
+ origin: A Point3D for the origin around which the object will be rotated.
+ """
+ returnLineSegment3D(self.p.rotate(axis,angle,origin),
+ self.v.rotate(axis,angle))
+
+
+
+[docs]
+ defrotate_xy(self,angle,origin):
+"""Get a line segment rotated counterclockwise in the XY plane by a certain angle.
+
+ Args:
+ angle: An angle in radians.
+ origin: A Point3D for the origin around which the object will be rotated.
+ """
+ returnLineSegment3D(self.p.rotate_xy(angle,origin),
+ self.v.rotate_xy(angle))
+
+
+
+[docs]
+ defreflect(self,normal,origin):
+"""Get a line segment reflected across a plane with the input normal vector and origin.
+
+ Args:
+ normal: A Vector3D representing the normal vector for the plane across
+ which the line segment will be reflected. THIS VECTOR MUST BE NORMALIZED.
+ origin: A Point3D representing the origin from which to reflect.
+ """
+ returnLineSegment3D(self.p.reflect(normal,origin),self.v.reflect(normal))
+
+
+
+[docs]
+ defscale(self,factor,origin=None):
+"""Scale a line segment by a factor from an origin point.
+
+ Args:
+ factor: A number representing how much the line segment should be scaled.
+ origin: A Point3D representing the origin from which to scale.
+ If None, it will be scaled from the World origin (0, 0, 0).
+ """
+ returnLineSegment3D(self.p.scale(factor,origin),self.v*factor)
+
+
+
+[docs]
+ defsubdivide(self,distances):
+"""Get Point3D values along the line that subdivide it based on input distances.
+
+ Args:
+ distances: A list of distances along the line at which to subdivide it.
+ This can also be a single number that will be repeated until the
+ end of the line.
+ """
+ ifisinstance(distances,(float,int)):
+ distances=[distances]
+ # this assert prevents the while loop from being infinite
+ assertsum(distances)>0,'Segment subdivisions must be greater than 0'
+ line_length=self.length
+ dist=distances[0]
+ index=0
+ sub_pts=[self.p]
+ whiledist<line_length:
+ sub_pts.append(self.point_at_length(dist))
+ ifindex<len(distances)-1:
+ index+=1
+ dist+=distances[index]
+ sub_pts.append(self.p2)
+ returnsub_pts
+
+
+
+[docs]
+ defsubdivide_evenly(self,number):
+"""Get Point3D values along the line that divide it into evenly-spaced segments.
+
+ Args:
+ number: Integer for the number of segments into which the line will
+ be divided.
+ """
+ # this assert prevents the while loop from being infinite
+ assertnumber>0,'Segment subdivisions must be greater than 0'
+ interval=1/number
+ parameter=interval
+ sub_pts=[self.p]
+ whileparameter<=1:
+ sub_pts.append(self.point_at(parameter))
+ parameter+=interval
+ iflen(sub_pts)!=number+1:# tolerance issue with last point
+ sub_pts.append(self.p2)
+ returnsub_pts
+
+
+
+[docs]
+ defpoint_at(self,parameter):
+"""Get a Point3D at a given fraction along the line segment.
+
+ Args:
+ parameter: The fraction between the start and end point where the
+ desired point lies. For example, 0.5 will yield the midpoint.
+ """
+ returnself.p+self.v*parameter
+
+
+
+[docs]
+ defpoint_at_length(self,length):
+"""Get a Point3D at a given distance along the line segment.
+
+ Args:
+ length: The distance along the line from the start point where the
+ desired point lies.
+ """
+ returnself.p+self.v*(length/self.length)
+
+
+
+[docs]
+ defsplit_with_plane(self,plane):
+"""Split this LineSegment3D in 2 smaller LineSegment3Ds using a Plane.
+
+ Args:
+ plane: A Plane that will be used to split this line segment.
+
+ Returns:
+ A list of two LineSegment3D objects if the split was successful.
+ Will be a list with 1 LineSegment3D if no intersection exists.
+ """
+ _plane_int=self.intersect_plane(plane)
+ if_plane_intisnotNone:
+ return[LineSegment3D.from_end_points(self.p1,_plane_int),
+ LineSegment3D.from_end_points(_plane_int,self.p2)]
+ return[self]
+
+
+
+[docs]
+ defto_dict(self):
+"""Get LineSegment3D as a dictionary."""
+ base=Base1DIn3D.to_dict(self)
+ base['type']='LineSegment3D'
+ returnbase
+
+
+
+[docs]
+ defto_array(self):
+""" A nested list representing the two line endpoint coordinates."""
+ return(self.p1.to_array(),self.p2.to_array())
+[docs]
+classMesh3D(MeshBase):
+"""3D Mesh object.
+
+ Args:
+ vertices: A list or tuple of Point3D objects for vertices.
+ faces: A list of tuples with each tuple having either 3 or 4 integers.
+ These integers correspond to indices within the list of vertices.
+ colors: An optional list of colors that correspond to either the faces
+ of the mesh or the vertices of the mesh. Default is None.
+
+ Properties:
+ * vertices
+ * faces
+ * colors
+ * is_color_by_face
+ * min
+ * max
+ * center
+ * area
+ * face_areas
+ * face_centroids
+ * face_area_centroids
+ * face_vertices
+ * face_normals
+ * vertex_normals
+ * vertex_connected_faces
+ * face_edges
+ * edges
+ * naked_edges
+ * internal_edges
+ * non_manifold_edges
+ """
+ __slots__=('_min','_max','_center','_face_normals','_vertex_normals')
+
+ def__init__(self,vertices,faces,colors=None):
+"""Initialize Mesh3D."""
+ self._vertices=self._check_vertices_input(vertices)
+ self._faces=self._check_faces_input(faces)
+
+ self._is_color_by_face=False# default if colors is None
+ self.colors=colors
+ self._min=None
+ self._max=None
+ self._center=None
+ self._area=None
+ self._face_areas=None
+ self._face_centroids=None
+ self._face_area_centroids=None
+ self._face_normals=None
+ self._vertex_normals=None
+ self._vertex_connected_faces=None
+ self._edge_indices=None
+ self._edge_types=None
+ self._edges=None
+ self._naked_edges=None
+ self._internal_edges=None
+ self._non_manifold_edges=None
+
+
+[docs]
+ @classmethod
+ deffrom_dict(cls,data):
+"""Create a Mesh3D from a dictionary.
+
+ Args:
+ data: A python dictionary in the following format
+
+ .. code-block:: python
+
+ {
+ "type": "Mesh3D",
+ "vertices": [(0, 0, 0), (10, 0, 0), (0, 10, 0)],
+ "faces": [(0, 1, 2)],
+ "colors": [{"r": 255, "g": 0, "b": 0}]
+ }
+ """
+ colors=None
+ if'colors'indataanddata['colors']isnotNoneandlen(data['colors'])!=0:
+ try:
+ fromladybug.colorimportColor
+ exceptImportError:
+ raiseImportError('Colors are specified in input Mesh2D dictionary '
+ 'but failed to import ladybug.color')
+ colors=tuple(Color.from_dict(col)forcolindata['colors'])
+ fcs=tuple(tuple(f)forfindata['faces'])# cast to immutable type
+ returncls(tuple(Point3D.from_array(pt)forptindata['vertices']),fcs,colors)
+
+
+
+[docs]
+ @classmethod
+ deffrom_face_vertices(cls,faces,purge=True):
+"""Create a mesh from a list of faces with each face defined by Point3Ds.
+
+ Args:
+ faces: A list of faces with each face defined as a list of 3 or 4 Point3D.
+ purge: A boolean to indicate if duplicate vertices should be shared between
+ faces. Default is True to purge duplicate vertices, which can be slow
+ for large lists of faces but results in a higher-quality mesh with
+ a smaller size in memory. Note that vertices are only considered
+ duplicate if the coordinate values are equal to one another
+ within floating point tolerance. To remove duplicate vertices
+ within a specified tolerance other than floating point, the
+ from_purged_face_vertices method should be used instead.
+ """
+ vertices,face_collector=cls._interpret_input_from_face_vertices(faces,purge)
+ returncls(tuple(vertices),tuple(face_collector))
+
+
+
+[docs]
+ @classmethod
+ deffrom_purged_face_vertices(cls,faces,tolerance):
+"""Create a mesh from a list of faces with each face defined by Point3Ds.
+
+ This method is slower than 'from_face_vertices' but will result in a mesh
+ with fewer vertices and a smaller size in memory. This method is similar to
+ using the 'purge' option in 'from_face_vertices' but will result in more shared
+ vertices since it uses a tolerance to check equivalent vertices rather than
+ comparing within floating point tolerance.
+
+ Args:
+ faces: A list of faces with each face defined as a list of 3 or 4 Point3D.
+ tolerance: A number for the minimum difference between coordinate
+ values at which point vertices are considered equal to one another.
+ """
+ vertices,faces=cls._interpret_input_from_face_vertices_with_tolerance(
+ faces,tolerance)
+ returncls(tuple(vertices),tuple(faces))
+
+
+
+[docs]
+ @classmethod
+ deffrom_mesh2d(cls,mesh_2d,plane=None):
+"""Create a Mesh3D from a Mesh2D and a Plane in which the mesh exists.
+
+ Args:
+ mesh_2d: A Mesh2D object.
+ plane: A Plane object to represent the plane in which the Mesh2D exists
+ within 3D space. If None, the WorldXY plane will be used.
+ """
+ assertisinstance(mesh_2d,Mesh2D),'Expected Mesh2D for from_mesh_2d. ' \
+ 'Got {}.'.format(type(mesh_2d))
+ ifplaneisNone:
+ returncls(tuple(Point3D(pt.x,pt.y,0)forptinmesh_2d.vertices),
+ mesh_2d.faces,mesh_2d.colors)
+ else:
+ assertisinstance(plane,Plane),'Expected Plane. Got {}'.format(type(plane))
+ _verts3d=tuple(plane.xy_to_xyz(_v)for_vinmesh_2d.vertices)
+ returncls(_verts3d,mesh_2d.faces,mesh_2d.colors)
+
+
+
+[docs]
+ @classmethod
+ deffrom_stl(cls,file_path):
+"""Create a Mesh3D from an STL file.
+
+ Args:
+ file_path: Path to an STL file as a text string. The STL file can be
+ in either ASCII or binary format.
+ """
+ fromladybug_geometry.interop.stlimportSTL# avoid circular import
+ face_vertices=STL.from_file(file_path).face_vertices
+ returncls.from_face_vertices(face_vertices)
+
+
+
+[docs]
+ @classmethod
+ deffrom_obj(cls,file_path):
+"""Create a Mesh3D from an OBJ file.
+
+ Args:
+ file_path: Path to an OBJ file as a text string.
+ """
+ fromladybug_geometry.interop.objimportOBJ# avoid circular import
+ transl_obj=OBJ.from_file(file_path)
+ returncls(transl_obj.vertices,transl_obj.faces,transl_obj.vertex_colors)
+
+
+ @property
+ defmin(self):
+"""A Point3D for the minimum bounding box vertex around this mesh."""
+ ifself._minisNone:
+ self._calculate_min_max()
+ returnself._min
+
+ @property
+ defmax(self):
+"""A Point3D for the maximum bounding box vertex around this mesh."""
+ ifself._maxisNone:
+ self._calculate_min_max()
+ returnself._max
+
+ @property
+ defcenter(self):
+"""A Point3D for the center of the bounding box around this mesh."""
+ ifself._centerisNone:
+ min,max=self.min,self.max
+ self._center=Point3D(
+ (min.x+max.x)/2,(min.y+max.y)/2,(min.z+max.z)/2)
+ returnself._center
+
+ @property
+ defface_areas(self):
+"""A tuple of face areas that parallels the faces property."""
+ ifself._face_normalsisNone:
+ self._calculate_face_areas_and_normals()
+ elifisinstance(self._face_areas,(float,int)):# same area for each face
+ self._face_areas=tuple(self._face_areasforfaceinself.faces)
+ returnself._face_areas
+
+ @property
+ defface_normals(self):
+"""Tuple of Vector3D objects for all face normals."""
+ ifself._face_normalsisNone:
+ self._calculate_face_areas_and_normals()
+ elifisinstance(self._face_normals,Vector3D):# same normal for each face
+ self._face_normals=tuple(self._face_normalsforfaceinself.faces)
+ returnself._face_normals
+
+ @property
+ defvertex_normals(self):
+"""Tuple of Vector3D objects for all vertex normals."""
+ ifnotself._vertex_normals:
+ self._calculate_vertex_normals()
+ elifisinstance(self._vertex_normals,Vector3D):# same normal for each vertex
+ self._vertex_normals=tuple(self._vertex_normalsforfaceinself.vertices)
+ returnself._vertex_normals
+
+ @property
+ defface_edges(self):
+"""List of polylines with one Polyline3D for each face.
+
+ This is faster to compute compared to the edges and results in effectively
+ the same type of wireframe visualization.
+ """
+ _all_verts=self._vertices
+ f_edges=[]
+ forfaceinself._faces:
+ verts=tuple(_all_verts[v]forvinface)+(_all_verts[face[0]],)
+ f_edges.append(Polyline3D(verts))
+ returnf_edges
+
+ @property
+ defedges(self):
+""""Tuple of all edges in this Mesh3D as LineSegment3D objects.
+
+ Note that this method will return only the unique edges in the mesh without
+ any duplicates. This is sometimes desirable but can take a lot of time
+ to compute for large meshes. For a faster property, use face_edges."""
+ ifself._edgesisNone:
+ ifself._edge_indicesisNone:
+ self._compute_edge_info()
+ self._edges=tuple(LineSegment3D.from_end_points(
+ self.vertices[seg[0]],self.vertices[seg[1]])
+ forseginself._edge_indices)
+ returnself._edges
+
+ @property
+ defnaked_edges(self):
+""""Tuple of all naked edges in this Mesh3D as LineSegment3D objects.
+
+ Naked edges belong to only one face in the mesh (they are not
+ shared between faces).
+ """
+ ifself._naked_edgesisNone:
+ self._naked_edges=self._get_edge_type(0)
+ returnself._naked_edges
+
+ @property
+ definternal_edges(self):
+""""Tuple of all internal edges in this Mesh3D as LineSegment3D objects.
+
+ Internal edges are shared between two faces in the mesh.
+ """
+ ifself._internal_edgesisNone:
+ self._internal_edges=self._get_edge_type(1)
+ returnself._internal_edges
+
+ @property
+ defnon_manifold_edges(self):
+""""Tuple of all non-manifold edges in this mesh as LineSegment3D objects.
+
+ Non-manifold edges are shared between three or more faces.
+ """
+ ifself._non_manifold_edgesisNone:
+ ifself._edgesisNone:
+ self.edges
+ nm_edges=[]
+ fori,typeinenumerate(self._edge_types):
+ iftype>1:
+ nm_edges.append(self._edges[i])
+ self._non_manifold_edges=tuple(nm_edges)
+ returnself._non_manifold_edges
+
+
+[docs]
+ defremove_vertices(self,pattern):
+"""Get a version of this mesh where vertices are removed according to a pattern.
+
+ Args:
+ pattern: A list of boolean values denoting whether a vertex should
+ remain in the mesh (True) or be removed from the mesh (False).
+ The length of this list must match the number of this mesh's vertices.
+
+ Returns:
+ A tuple with two elements.
+
+ - new_mesh:
+ A mesh where the vertices have been removed according
+ to the input pattern.
+
+ - face_pattern:
+ A list of boolean values that corresponds to the
+ original mesh faces noting whether the face is in the new mesh
+ (True) or has been removed from the new mesh (False).
+ """
+ _new_verts,_new_faces,_new_colors,_new_f_cent,_new_f_area,face_pattern= \
+ self._remove_vertices(pattern)
+
+ new_mesh=Mesh3D(_new_verts,_new_faces,_new_colors)
+ new_mesh._face_centroids=_new_f_cent
+ new_mesh._face_areas=_new_f_area
+ returnnew_mesh,face_pattern
+
+
+
+[docs]
+ defremove_faces(self,pattern):
+"""Get a version of this mesh where faces are removed according to a pattern.
+
+ Args:
+ pattern: A list of boolean values denoting whether a face should
+ remain in the mesh (True) or be removed from the mesh (False).
+ The length of this list must match the number of this mesh's faces.
+
+ Returns:
+ A tuple with two elements.
+
+ - new_mesh:
+ A mesh where the faces have been removed according
+ to the input pattern.
+
+ - vertex_pattern:
+ A list of boolean values that corresponds to the
+ original mesh vertices noting whether the vertex is in the new mesh
+ (True) or has been removed from the new mesh (False).
+ """
+ vertex_pattern=self._vertex_pattern_from_remove_faces(pattern)
+ _new_verts,_new_faces,_new_colors,_new_f_cent,_new_f_area,face_pattern= \
+ self._remove_vertices(vertex_pattern,pattern)
+
+ new_mesh=Mesh3D(_new_verts,_new_faces,_new_colors)
+ new_mesh._face_centroids=_new_f_cent
+ new_mesh._face_areas=_new_f_area
+ returnnew_mesh,vertex_pattern
+
+
+
+[docs]
+ defremove_faces_only(self,pattern):
+"""Get a version of this mesh where faces are removed and vertices are unaltered.
+
+ This is faster than the Mesh3D.remove_faces method but will likely result
+ a lower-quality mesh where several vertices exist in the mesh that are not
+ referenced by any face. This may be preferred if pure speed of removing
+ faces is a priority over smallest size of the mesh in memory.
+
+ Args:
+ pattern: A list of boolean values denoting whether a face should
+ remain in the mesh (True) or be removed from the mesh (False).
+ The length of this list must match the number of this mesh's faces.
+
+ Returns:
+ new_mesh -- A mesh where the faces have been removed according
+ to the input pattern.
+ """
+ _new_faces,_new_colors,_new_f_cent,_new_f_area= \
+ self._remove_faces_only(pattern)
+
+ new_mesh=Mesh3D(self.vertices,_new_faces,_new_colors)
+ new_mesh._face_centroids=_new_f_cent
+ new_mesh._face_areas=_new_f_area
+ returnnew_mesh
+
+
+
+[docs]
+ defrotate(self,axis,angle,origin):
+"""Rotate a mesh by a certain angle around an axis and origin.
+
+ Right hand rule applies:
+ If axis has a positive orientation, rotation will be clockwise.
+ If axis has a negative orientation, rotation will be counterclockwise.
+
+ Args:
+ axis: A Vector3D axis representing the axis of rotation.
+ angle: An angle for rotation in radians.
+ origin: A Point3D for the origin around which the point will be rotated.
+ """
+ _verts=tuple(pt.rotate(axis,angle,origin)forptinself.vertices)
+ returnself._mesh_transform(_verts)
+
+
+
+[docs]
+ defrotate_xy(self,angle,origin):
+"""Get a mesh rotated counterclockwise in the XY plane by a certain angle.
+
+ Args:
+ angle: An angle for rotation in radians.
+ origin: A Point3D for the origin around which the point will be rotated.
+ """
+ _verts=tuple(pt.rotate_xy(angle,origin)forptinself.vertices)
+ returnself._mesh_transform(_verts)
+
+
+
+[docs]
+ defscale(self,factor,origin=None):
+"""Scale a mesh by a factor from an origin point.
+
+ Args:
+ factor: A number representing how much the mesh should be scaled.
+ origin: A Point representing the origin from which to scale.
+ If None, it will be scaled from the World origin (0, 0, 0).
+ """
+ iforiginisNone:
+ _verts=tuple(
+ Point3D(pt.x*factor,pt.y*factor,pt.z*factor)
+ forptinself.vertices)
+ else:
+ _verts=tuple(pt.scale(factor,origin)forptinself.vertices)
+ returnself._mesh_scale(_verts,factor)
+
+
+
+[docs]
+ defoffset_mesh(self,distance):
+"""Get a Mesh3D that has been offset from this one by a certain difference.
+
+ Effectively, this method moves each mesh vertex along the vertex normal
+ by the offset distance.
+
+ Args:
+ distance: A number for the distance to offset the mesh.
+ """
+ new_verts=tuple(pt.move(norm*distance)forpt,normin
+ zip(self.vertices,self.vertex_normals))
+ returnMesh3D(new_verts,self.faces,self._colors)
+
+
+
+[docs]
+ defheight_field_mesh(self,values,domain):
+"""Get a Mesh3D that has faces or vertices offset according to a list of values.
+
+ Args:
+ values: A list of values that has a length matching the number of faces
+ or vertices in this mesh.
+ domain: A tuple or list of two numbers for the upper and lower distances
+ that the mesh vertices should be offset. (ie. (0, 3))
+ """
+ assertisinstance(domain,(tuple,list)),'Expected tuple for domain. '\
+ 'Got {}.'.format(type(domain))
+ assertlen(domain)==2,'Expected domain to be in the format (min, max). ' \
+ 'Got {}.'.format(domain)
+
+ iflen(values)==len(self.faces):
+ remap_vals=Mesh3D._remap_values(values,domain[0],domain[-1])
+ vert_remap_vals=[]
+ forvfinself.vertex_connected_faces:
+ v=0
+ forjinvf:
+ v+=remap_vals[j]
+ try:
+ v/=len(vf)# average the vertex value over its connected faces
+ exceptZeroDivisionError:
+ pass# lone vertex without any faces
+ vert_remap_vals.append(v)
+ new_verts=tuple(pt.move(norm*dist)forpt,norm,distin
+ zip(self.vertices,self.vertex_normals,vert_remap_vals))
+ eliflen(values)==len(self.vertices):
+ remap_vals=Mesh3D._remap_values(values,domain[0],domain[-1])
+ new_verts=tuple(pt.move(norm*dist)forpt,norm,distin
+ zip(self.vertices,self.vertex_normals,remap_vals))
+ else:
+ raiseValueError(
+ 'Input values for height_field_mesh ({}) does not match the number of'
+ ' mesh faces ({}) nor the number of vertices ({}).'
+ .format(len(values),len(self.faces),len(self.vertices)))
+ returnMesh3D(new_verts,self.faces,self._colors)
+
+
+
+[docs]
+ defto_dict(self):
+"""Get Mesh3D as a dictionary."""
+ base={'type':'Mesh3D',
+ 'vertices':[pt.to_array()forptinself.vertices],
+ 'faces':self.faces}
+ ifself.colorsisnotNone:
+ base['colors']=[col.to_dict()forcolinself.colors]
+ returnbase
+
+
+
+[docs]
+ defto_stl(self,folder,name=None):
+"""Write the Mesh3D to an ASCII STL file.
+
+ Args:
+ folder: A text string for the directory where the STL will be written.
+ name: A text string for the name of the STL file.
+ """
+ fromladybug_geometry.interop.stlimportSTL# avoid circular import
+ stl_obj=STL(self.face_vertices,self.face_normals)
+ returnstl_obj.to_file(folder,name)
+
+
+
+[docs]
+ defto_obj(self,folder,name,include_colors=True,include_normals=False,
+ triangulate_quads=False,include_mtl=False):
+"""Write the Mesh3D to an ASCII OBJ file.
+
+ Args:
+ folder: A text string for the directory where the OBJ will be written.
+ name: A text string for the name of the OBJ file.
+ include_colors: Boolean to note whether the Mesh3D colors should be
+ included in the OBJ file. (Default: True).
+ include_normals: Boolean to note whether the vertex normals should be
+ included in the OBJ file. (Default: False).
+ triangulate_quads: Boolean to note whether quad faces should be
+ triangulated upon export to OBJ. This may be needed for certain
+ software platforms that require the mesh to be composed entirely
+ of triangles (eg. Radiance). (Default: False).
+ include_mtl: Boolean to note whether an .mtl file should be automatically
+ generated next to the .obj file in the output folder. All materials
+ in the mtl file will be diffuse white, with the assumption that
+ these will be customized later. (Default: False).
+ """
+ fromladybug_geometry.interop.objimportOBJ# avoid circular import
+ transl_obj=OBJ.from_mesh3d(self,include_colors,include_normals)
+ returntransl_obj.to_file(folder,name,triangulate_quads,include_mtl)
+
+
+
+[docs]
+ @staticmethod
+ defjoin_meshes(meshes):
+"""Join an array of Mesh3Ds into a single Mesh3D.
+
+ Args:
+ meshes: An array of meshes to be joined into one.
+
+ Returns:
+ A single Mesh3D object derived from the input meshes.
+ """
+ # set up empty lists of objects to be filled
+ verts=[]
+ faces=[]
+ colors=[]
+
+ # loop through all of the meshes and get new faces
+ total_v_i=0
+ formeshinmeshes:
+ verts.extend(mesh._vertices)
+ forfcinmesh._faces:
+ faces.append(tuple(v_i+total_v_iforv_iinfc))
+ total_v_i+=len(mesh._vertices)
+ ifmesh._colors:
+ colors.extend(mesh._colors)
+
+ # create the new mesh
+ iflen(colors)!=0:
+ new_mesh=Mesh3D(verts,faces,colors)
+ else:
+ new_mesh=Mesh3D(verts,faces)
+ returnnew_mesh
+
+
+ def_calculate_min_max(self):
+"""Calculate maximum and minimum Point3D for this object."""
+ min_pt=[self.vertices[0].x,self.vertices[0].y,self.vertices[0].z]
+ max_pt=[self.vertices[0].x,self.vertices[0].y,self.vertices[0].z]
+
+ forvinself.vertices[1:]:
+ ifv.x<min_pt[0]:
+ min_pt[0]=v.x
+ elifv.x>max_pt[0]:
+ max_pt[0]=v.x
+ ifv.y<min_pt[1]:
+ min_pt[1]=v.y
+ elifv.y>max_pt[1]:
+ max_pt[1]=v.y
+ ifv.z<min_pt[2]:
+ min_pt[2]=v.z
+ elifv.z>max_pt[2]:
+ max_pt[2]=v.z
+
+ self._min=Point3D(min_pt[0],min_pt[1],min_pt[2])
+ self._max=Point3D(max_pt[0],max_pt[1],max_pt[2])
+
+ def_calculate_face_areas_and_normals(self):
+"""Calculate face areas and normals from vertices."""
+ _f_norm=[]
+ _f_area=[]
+ forfaceinself.faces:
+ pts=tuple(self._vertices[i]foriinface)
+ iflen(face)==3:
+ n,a=self._calculate_normal_and_area_for_triangle(pts)
+ else:
+ n,a=self._calculate_normal_and_area_for_quad(pts)
+ _f_norm.append(n)
+ _f_area.append(a)
+ self._face_normals=tuple(_f_norm)
+ self._face_areas=tuple(_f_area)
+
+ def_calculate_vertex_normals(self):
+"""Calculate vertex normals.
+
+ This is accomplished by normalizing the average of the surface normals
+ of the faces that contain that vertex. This particular method weights
+ this average by the area of each face, though this does not always need
+ to be the case as noted here:
+ https://en.wikipedia.org/wiki/Vertex_normal
+ """
+ # find shared faces for each vertices
+ mapper=[[]forvinxrange(len(self.vertices))]
+ forc,faceinenumerate(self.faces):
+ foriinface:
+ mapper[i].append(c)
+ # now calculate vertex normal based on face normals
+ vn=[]
+ fn=self.face_normals
+ fa=self.face_areas
+ forfiinmapper:
+ x,y,z=0,0,0
+ forn,ainzip(tuple(fn[i]foriinfi),tuple(fa[i]foriinfi)):
+ x+=n.x*a
+ y+=n.y*a
+ z+=n.z*a
+ _v=Vector3D(x,y,z)
+ vn.append(_v.normalize())
+ self._vertex_normals=tuple(vn)
+
+ def_get_edge_type(self,edge_type):
+"""Get all of the edges of a certain type in this mesh."""
+ ifself._edgesisNone:
+ self.edges
+ sel_edges=[]
+ fori,typeinenumerate(self._edge_types):
+ iftype==edge_type:
+ sel_edges.append(self._edges[i])
+ returntuple(sel_edges)
+
+ def_tri_face_centroid(self,face):
+"""Compute the centroid of a triangular face."""
+ returnMesh3D._tri_centroid(tuple(self._vertices[i]foriinface))
+
+ def_quad_face_centroid(self,face):
+"""Compute the centroid of a quadrilateral face."""
+ returnMesh3D._quad_centroid(tuple(self._vertices[i]foriinface))
+
+ def_mesh_transform(self,verts):
+"""Transform mesh in a way that transfers properties and avoids extra checks."""
+ _new_mesh=Mesh3D(verts,self.faces)
+ self._transfer_properties(_new_mesh)
+ return_new_mesh
+
+ def_mesh_transform_move(self,verts):
+"""Move mesh in a way that transfers properties and avoids extra checks."""
+ _new_mesh=Mesh3D(verts,self.faces)
+ self._transfer_properties(_new_mesh)
+ _new_mesh._face_normals=self._face_normals
+ _new_mesh._vertex_normals=self._vertex_normals
+ return_new_mesh
+
+ def_mesh_scale(self,verts,factor):
+"""Scale mesh in a way that transfers properties and avoids extra checks."""
+ _new_mesh=Mesh3D(verts,self.faces)
+ self._transfer_properties_scale(_new_mesh,factor)
+ _new_mesh._face_normals=self._face_normals
+ _new_mesh._vertex_normals=self._vertex_normals
+ return_new_mesh
+
+ def_check_vertices_input(self,vertices):
+"""Check the input vertices."""
+ ifnotisinstance(vertices,tuple):
+ vertices=tuple(vertices)
+ forvertinvertices:
+ assertisinstance(vert,Point3D), \
+ 'Expected Point3D for {} vertex. Got {}.'.format(
+ self.__class__.__name__,type(vert))
+ returnvertices
+
+ @staticmethod
+ def_calculate_normal_and_area_for_triangle(pts):
+"""Calculate normal and area for three points.
+
+ Returns:
+ n = Normalized normal vector for the triangle.
+ a = Area of the triangle.
+ """
+ v1=pts[1]-pts[0]
+ v2=pts[2]-pts[0]
+ n=v1.cross(v2)
+ a=n.magnitude/2
+ returnn.normalize(),a
+
+ @staticmethod
+ def_calculate_normal_and_area_for_quad(pts):
+"""Calculate normal and area for four points.
+
+ This method uses an area-weighted average of the two triangle normals
+ that compose the quad face.
+
+ Returns:
+ n = Normalized normal vector for the quad.
+ a = Area of the quad.
+ """
+ # TODO: Get this method to work for concave quads.
+ # This method is only reliable when quads are convex since we assume
+ # either diagonal of the quad splits it into two triangles.
+ # It seems Rhino never produces concave quads when it automatically meshes
+ # but we will likely want to add support for this if meshes have other origins
+ v1=pts[1]-pts[0]
+ v2=pts[2]-pts[0]
+ n1=v1.cross(v2)
+
+ v3=pts[3]-pts[2]
+ v4=pts[1]-pts[2]
+ n2=v3.cross(v4)
+
+ a=(n1.magnitude+n2.magnitude)/2
+ n=Vector3D((n1.x+n2.x)/2,(n1.y+n2.y)/2,(n1.z+n2.z)/2)
+ returnn.normalize(),a
+
+ @staticmethod
+ def_face_center(verts):
+"""Get the center of a list of Point3D vertices."""
+ _cent_x=sum([v.xforvinverts])
+ _cent_y=sum([v.yforvinverts])
+ _cent_z=sum([v.zforvinverts])
+ v_count=len(verts)
+ returnPoint3D(_cent_x/v_count,_cent_y/v_count,_cent_z/v_count)
+
+ @staticmethod
+ def_tri_centroid(verts):
+"""Get the centroid of a list of 3 Point3D vertices."""
+ _cent_x=sum([v.xforvinverts])
+ _cent_y=sum([v.yforvinverts])
+ _cent_z=sum([v.zforvinverts])
+ returnPoint3D(_cent_x/3,_cent_y/3,_cent_z/3)
+
+ @staticmethod
+ def_quad_centroid(verts):
+"""Get the centroid of a list of 4 Point3D vertices."""
+ # TODO: Get this method to recognize concave quads.
+ # This method is only reliable when quads are convex since we assume
+ # either diagonal of the quad splits it into two triangles.
+ # It seems Rhino never produces concave quads when it automatically meshes
+ _tri_verts=((verts[0],verts[1],verts[2]),(verts[2],verts[3],verts[0]))
+ _tri_c=[Mesh3D._tri_centroid(tri)fortriin_tri_verts]
+ _tri_a=[Mesh3D._get_tri_area(tri)fortriin_tri_verts]
+ _tot_a=sum(_tri_a)
+ try:
+ _cent_x=(_tri_c[0].x*_tri_a[0]+_tri_c[1].x*_tri_a[1])/_tot_a
+ _cent_y=(_tri_c[0].y*_tri_a[0]+_tri_c[1].y*_tri_a[1])/_tot_a
+ _cent_z=(_tri_c[0].z*_tri_a[0]+_tri_c[1].z*_tri_a[1])/_tot_a
+ exceptZeroDivisionError:
+ _cent_x=sum([v.xforvinverts])/4
+ _cent_y=sum([v.yforvinverts])/4
+ _cent_z=sum([v.zforvinverts])/4
+ returnPoint3D(_cent_x,_cent_y,_cent_z)
+
+ @staticmethod
+ def_get_tri_area(pts):
+"""Get the area of a triangle from three Point3D objects."""
+ v1=pts[1]-pts[0]
+ v2=pts[2]-pts[0]
+ n1=v1.cross(v2)
+ returnn1.magnitude/2
+
+ @staticmethod
+ def_remap_values(values,tmin,tmax):
+"""Remap a set of values to offset distances within a domain."""
+ omin=min(values)
+ omax=max(values)
+ odiff=omax-omin
+ tdiff=tmax-tmin
+ ifodiff==0:
+ return[tmin]*len(values)
+ else:
+ return[(v-omin)*tdiff/odiff+tminforvinvalues]
+
+ def__copy__(self):
+ _new_mesh=Mesh3D(self.vertices,self.faces)
+ self._transfer_properties(_new_mesh)
+ _new_mesh._face_centroids=self._face_centroids
+ _new_mesh._face_normals=self._face_normals
+ _new_mesh._vertex_normals=self._vertex_normals
+ return_new_mesh
+
+ def__key(self):
+"""A tuple based on the object properties, useful for hashing."""
+ returntuple(hash(pt)forptinself._vertices)+ \
+ tuple(hash(face)forfaceinself._faces)
+
+ def__hash__(self):
+ returnhash(self.__key())
+
+ def__eq__(self,other):
+ returnisinstance(other,Mesh3D)andself.__key()==other.__key()
+
+ def__repr__(self):
+ return'Mesh3D ({} faces) ({} vertices)'.format(
+ len(self.faces),len(self))
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/_modules/ladybug_geometry/geometry3d/plane.html b/docs/_modules/ladybug_geometry/geometry3d/plane.html
new file mode 100644
index 00000000..e3986e62
--- /dev/null
+++ b/docs/_modules/ladybug_geometry/geometry3d/plane.html
@@ -0,0 +1,1695 @@
+
+
+
+
+
+
+ ladybug_geometry.geometry3d.plane — ladybug geometry documentation
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+[docs]
+classPlane(object):
+"""Plane object.
+
+ Args:
+ n: A Vector3D representing the normal of the plane.
+ o: A Point3D representing the origin point of the plane.
+ x: An optional Vector3D for the X-Axis of the Plane.
+ Note that this vector must be orthogonal to the input normal vector.
+ If None, the default will find an X-Axis in the world XY plane.
+
+ Properties:
+ * n
+ * o
+ * k
+ * x
+ * y
+ * tilt
+ * altitude
+ * azimuth
+ * min
+ * max
+ """
+ __slots__=('_n','_o','_k','_x','_y','_altitude','_azimuth')
+
+ def__init__(self,n=Vector3D(0,0,1),o=Point3D(0,0,0),x=None):
+"""Initialize Plane."""
+ assertisinstance(n,Vector3D), \
+ "Expected Vector3D for plane normal. Got {}.".format(type(n))
+ assertisinstance(o,Point3D), \
+ "Expected Point3D for plane origin. Got {}.".format(type(o))
+ self._n=n.normalize()
+ self._o=o
+ self._k=self._n.dot(self._o)
+
+ ifxisNone:
+ ifself._n.x==0andself._n.y==0:
+ self._x=Vector3D(1,0,0)
+ else:
+ x=Vector3D(self._n.y,-self._n.x,0)
+ x=x.normalize()
+ self._x=x
+ else:
+ assertisinstance(x,Vector3D), \
+ "Expected Vector3D for plane X-axis. Got {}.".format(type(x))
+ x=x.normalize()
+ assertabs(self._n.x*x.x+self._n.y*x.y+self._n.z*x.z)<1e-2, \
+ 'Plane X-axis and normal vector are not orthogonal. Got angle of {} ' \
+ 'degrees between them.'.format(math.degrees(self._n.angle(x)))
+ self._x=x
+ self._y=self._n.cross(self._x)
+ self._altitude=None
+ self._azimuth=None
+
+
+[docs]
+ @classmethod
+ deffrom_three_points(cls,o,p2,p3):
+"""Initialize a Plane from three Point3D objects that are not co-linear.
+
+ Args:
+ o: A Point3D representing the origin point of the plane.
+ p2: A Point3D representing a point the plane.
+ p3: A Point3D representing a point the plane.
+ """
+ returncls((p2-o).cross(p3-o),o)
+
+
+
+[docs]
+ @classmethod
+ deffrom_normal_k(cls,n,k):
+"""Initialize a Plane from a normal vector and a scalar constant.
+
+ Args:
+ o: A Point3D representing the origin point of the plane.
+ k: Scalar constant relating origin point to normal vector
+ """
+ # get an arbitrary point on the plane for the origin
+ ifn.z:
+ o=Point3D(0.,0.,k/n.z)
+ elifn.y:
+ o=Point3D(0.,k/n.y,0.)
+ else:
+ o=Point3D(k/n.x,0.,0.)
+ returncls(n,o)
+
+
+ @property
+ defn(self):
+"""Normal vector. This vector will always be normalized (magnitude = 1)."""
+ returnself._n
+
+ @property
+ defo(self):
+"""Origin point."""
+ returnself._o
+
+ @property
+ defk(self):
+"""Scalar constant relating origin point to normal vector."""
+ returnself._k
+
+ @property
+ defx(self):
+"""Plane X-Axis. This vector will always be normalized (magnitude = 1)."""
+ returnself._x
+
+ @property
+ defy(self):
+"""Plane Y-Axis. This vector will always be normalized (magnitude = 1)."""
+ returnself._y
+
+ @property
+ defazimuth(self):
+"""Get the azimuth of the plane.
+
+ This is always between 0, indicating the positive Y-axis, and moving clockwise
+ up to 2 * Pi, which indicates a return to the positive Y-axis.
+
+ This will be zero if the plane is perfectly horizontal.
+ """
+ ifself._azimuthisNone:
+ try:
+ n_vec=Vector2D(0,1)
+ self._azimuth=n_vec.angle_clockwise(Vector2D(self.n.x,self.n.y))
+ exceptZeroDivisionError:# plane is perfectly horizontal
+ self._azimuth=0
+ returnself._azimuth
+
+ @property
+ defaltitude(self):
+"""Get the altitude of the plane. Between Pi/2 (up) and -Pi/2 (down)."""
+ ifself._altitudeisNone:
+ self._altitude=self.n.angle(Vector3D(0,0,-1))-math.pi/2
+ returnself._altitude
+
+ @property
+ deftilt(self):
+"""Get the tilt of the plane. Between 0 (up) and Pi (down)."""
+ returnabs(self.altitude-(math.pi/2))
+
+ @property
+ defmin(self):
+"""Returns the Plane origin."""
+ returnself._o
+
+ @property
+ defmax(self):
+"""Returns the Plane origin."""
+ returnself._o
+
+
+[docs]
+ defflip(self):
+"""Get a flipped version of this plane (facing the opposite direction)."""
+ returnPlane(self.n.reverse(),self.o,self.x)
+
+
+
+[docs]
+ defmove(self,moving_vec):
+"""Get a plane that has been moved along a vector.
+
+ Args:
+ moving_vec: A Vector3D with the direction and distance to move the plane.
+ """
+ returnPlane(self.n,self.o.move(moving_vec),self.x)
+
+
+
+[docs]
+ defrotate(self,axis,angle,origin):
+"""Rotate a plane by a certain angle around an axis and origin.
+
+ Right hand rule applies:
+ If axis has a positive orientation, rotation will be clockwise.
+ If axis has a negative orientation, rotation will be counterclockwise.
+
+ Args:
+ axis: A Vector3D axis representing the axis of rotation.
+ angle: An angle for rotation in radians.
+ origin: A Point3D for the origin around which the object will be rotated.
+ """
+ returnPlane(self.n.rotate(axis,angle),
+ self.o.rotate(axis,angle,origin),
+ self.x.rotate(axis,angle))
+
+
+
+[docs]
+ defrotate_xy(self,angle,origin):
+"""Get a plane rotated counterclockwise in the world XY plane by a certain angle.
+
+ Args:
+ angle: An angle in radians.
+ origin: A Point3D for the origin around which the object will be rotated.
+ """
+ returnPlane(self.n.rotate_xy(angle),
+ self.o.rotate_xy(angle,origin),
+ self.x.rotate_xy(angle))
+
+
+
+[docs]
+ defreflect(self,normal,origin):
+"""Get a plane reflected across a plane with the input normal vector and origin.
+
+ Args:
+ normal: A Vector3D representing the normal vector for the plane across
+ which the plane will be reflected. THIS VECTOR MUST BE NORMALIZED.
+ origin: A Point3D representing the origin from which to reflect.
+ """
+ returnPlane(self.n.reflect(normal),
+ self.o.reflect(normal,origin),
+ self.x.reflect(normal))
+
+
+
+[docs]
+ defscale(self,factor,origin=None):
+"""Scale a plane by a factor from an origin point.
+
+ Args:
+ factor: A number representing how much the plane should be scaled.
+ origin: A Point3D representing the origin from which to scale.
+ If None, it will be scaled from the World origin (0, 0, 0).
+ """
+ returnPlane(self.n,self.o.scale(factor,origin),self.x)
+
+
+
+[docs]
+ defxyz_to_xy(self,point):
+"""Get a Point2D in the coordinate system of this plane from a Point3D.
+
+ Note that the input Point3D should lie within this plane object in order
+ for the result to be valid.
+ """
+ _diff=Vector3D(point.x-self.o.x,point.y-self.o.y,point.z-self.o.z)
+ returnPoint2D(self.x.dot(_diff),self.y.dot(_diff))
+
+
+
+[docs]
+ defxy_to_xyz(self,point):
+"""Get a Point3D from a Point2D in the coordinate system of this plane."""
+ # This method returns the same result as the following code:
+ # self.o + (self.x * point.x) + (self.y * point.y)
+ # It has been written explicitly to cut out the isinstance() checks for speed
+ _u=(self.x.x*point.x,self.x.y*point.x,self.x.z*point.x)
+ _v=(self.y.x*point.y,self.y.y*point.y,self.y.z*point.y)
+ returnPoint3D(
+ self.o.x+_u[0]+_v[0],self.o.y+_u[1]+_v[1],self.o.z+_u[2]+_v[2])
+
+
+
+[docs]
+ defis_point_above(self,point):
+"""Test if a given point is above or below this plane.
+
+ Above is defined as being on the side of the plane that the plane normal
+ is pointing towards.
+
+ Args:
+ point: A Point3D object to test.
+
+ Returns:
+ True is point is above; False if below.
+ """
+ vec=Vector3D(point.x-self.o.x,point.y-self.o.y,point.z-self.o.z)
+ returnself.n.dot(vec)>0
+
+
+
+[docs]
+ defclosest_point(self,point):
+"""Get the closest Point3D on this plane to another Point3D.
+
+ Args:
+ point: A Point3D object to which the closest point on this plane
+ will be computed.
+
+ Returns:
+ Point3D for the closest point on this plane to the input point.
+ """
+ returnclosest_point3d_on_plane(point,self)
+
+
+
+[docs]
+ defdistance_to_point(self,point):
+"""Get the minimum distance between this plane and the input point.
+
+ Args:
+ point: A Point3D object to which the minimum distance will be computed.
+
+ Returns:
+ The distance to the input point.
+ """
+ close_pt=self.closest_point(point)
+ returnpoint.distance_to_point(close_pt)
+
+
+
+[docs]
+ defclosest_points_between_line(self,line_ray):
+"""Get the two closest Point3D between this plane and a Line3D or Ray3D.
+
+ Args:
+ line_ray: A Line3D or Ray3D object to which the closest points
+ will be computed.
+
+ Returns:
+ Two Point3D objects representing
+
+ 1) The closest point on the input line_ray to this plane.
+ 2) The closest point on this plane to the input line_ray.
+
+ Will be None if the line_ray intersects this plant
+ """
+ returnclosest_point3d_between_line3d_plane(line_ray,self)
+
+
+
+[docs]
+ defdistance_to_line(self,line_ray):
+"""Get the minimum distance between this plane and the input Line3D or Ray3D.
+
+ Args:
+ line_ray: A Line3D or Ray3D object to which the minimum distance
+ will be computed.
+
+ Returns:
+ The minimum distance to the input line_ray.
+ """
+ result=self.closest_points_between_line(line_ray)
+ ifresultisNone:# intersection
+ return0
+ else:
+ returnresult[0].distance_to_point(result[1])
+
+
+
+[docs]
+ defproject_point(self,point,projection_direction=None):
+"""Project a point onto this Plane given a certain projection direction.
+
+ Args:
+ point: A Point3D to be projected onto the plane
+ projection_direction: A Line3D or Ray3D object to set the direction
+ of projection. If None, this Plane's normal will be
+ used. (Default: None).
+
+ Returns:
+ Point3D for the projected point. Will be None if the projection_direction
+ is parallel to the plane.
+ """
+ int_ray=Ray3D(point,self.n)ifprojection_directionisNone \
+ elseRay3D(point,projection_direction)
+ returnintersect_line3d_plane_infinite(int_ray,self)
+
+
+
+[docs]
+ defintersect_line_ray(self,line_ray):
+"""Get the intersection between this plane and the input Line3D or Ray3D.
+
+ Args:
+ line_ray: A Line3D or Ray3D object for which intersection will be computed.
+
+ Returns:
+ Point3D for the intersection. Will be None if no intersection exists.
+ """
+ returnintersect_line3d_plane(line_ray,self)
+
+
+
+[docs]
+ defintersect_arc(self,arc):
+"""Get the intersection between this Plane and an Arc3D.
+
+ Args:
+ plane: A Plane object for which intersection will be computed.
+
+ Returns:
+ A list of 2 Point3D objects if a full intersection exists.
+ A list with a single Point3D object if the line is tangent or intersects
+ only once. None if no intersection exists.
+ """
+ _plane_int_ray=self.intersect_plane(arc.plane)
+ if_plane_int_rayisnotNone:
+ _p12d=arc.plane.xyz_to_xy(_plane_int_ray.p)
+ _p22d=arc.plane.xyz_to_xy(_plane_int_ray.p+_plane_int_ray.v)
+ _v2d=_p22d-_p12d
+ _int_ray2d=Ray2D(_p12d,_v2d)
+ _int_pt2d=arc.arc2d.intersect_line_infinite(_int_ray2d)
+ if_int_pt2disnotNone:
+ return[arc.plane.xy_to_xyz(pt)forptin_int_pt2d]
+ returnNone
+
+
+
+[docs]
+ defintersect_plane(self,plane):
+"""Get the intersection between this Plane and another Plane.
+
+ Args:
+ plane: A Plane object for which intersection will be computed.
+
+ Returns:
+ Ray3D for the intersection. Will be None if planes are parallel.
+ """
+ result=intersect_plane_plane(self,plane)
+ ifresultisnotNone:
+ returnRay3D(result[0],result[1])
+ returnNone
+
+
+
+[docs]
+ defis_coplanar(self,plane):
+"""Test if another Plane object is perfectly coplanar with this Plane.
+
+ Args:
+ plane: A Plane object for which co-planarity will be tested.
+
+ Returns:
+ True if plane is coplanar. False if it is not coplanar.
+ """
+ ifself.n==plane.n:
+ returnself.k==plane.k
+ elifself.n==plane.n.reverse():
+ returnself.k==-plane.k
+ returnFalse
+
+
+
+[docs]
+ defis_coplanar_tolerance(self,plane,tolerance,angle_tolerance):
+"""Test if another Plane object is coplanar within a certain tolerance.
+
+ Args:
+ plane: A Plane object for which co-planarity will be tested.
+ tolerance: The distance between the two planes at which point they can
+ be considered coplanar.
+ angle_tolerance: The angle in radians that the plane normals can
+ differ from one another in order for the planes to be considered
+ coplanar.
+
+ Returns:
+ True if plane is coplanar. False if it is not coplanar.
+ """
+ ifself.n.angle(plane.n)<=angle_toleranceor \
+ self.n.angle(plane.n.reverse())<=angle_tolerance:
+ returnself.distance_to_point(plane.o)<=tolerance
+ returnFalse
+
+
+
+[docs]
+ defduplicate(self):
+"""Get a copy of this object."""
+ returnself.__copy__()
+
+
+
+[docs]
+ defto_dict(self):
+"""Get Plane as a dictionary."""
+ return{'type':'Plane',
+ 'n':self.n.to_array(),
+ 'o':self.o.to_array(),
+ 'x':self.x.to_array()}
+
+
+ def__copy__(self):
+ returnPlane(self.n,self.o,self.x)
+
+ def__key(self):
+"""A tuple based on the object properties, useful for hashing."""
+ return(self.n,self.o,self.x)
+
+ def__hash__(self):
+ returnhash(self.__key())
+
+ def__eq__(self,other):
+ returnisinstance(other,Plane)andself.__key()==other.__key()
+
+ def__ne__(self,other):
+ returnnotself.__eq__(other)
+
+
Source code for ladybug_geometry.geometry3d.pointvector
+# coding=utf-8
+"""3D Vector and 3D Point"""
+from__future__importdivision
+
+from..geometry2d.pointvectorimportVector2D
+
+importmath
+importoperator
+
+
+
+[docs]
+classVector3D(object):
+"""3D Vector object.
+
+ Args:
+ x: Number for the X coordinate.
+ y: Number for the Y coordinate.
+ z: Number for the Z coordinate.
+
+ Properties:
+ * x
+ * y
+ * z
+ * magnitude
+ * magnitude_squared
+ * is_zero
+ """
+ __slots__=('_x','_y','_z')
+
+ def__init__(self,x=0,y=0,z=0):
+"""Initialize 3D Vector."""
+ self._x=self._cast_to_float(x)
+ self._y=self._cast_to_float(y)
+ self._z=self._cast_to_float(z)
+
+
+[docs]
+ @classmethod
+ deffrom_dict(cls,data):
+"""Create a Vector3D/Point3D from a dictionary.
+
+ Args:
+ data: A python dictionary in the following format
+
+ .. code-block:: python
+
+ {
+ "x": 10,
+ "y": 0,
+ "z": 0
+ }
+ """
+ returncls(data['x'],data['y'],data['z'])
+
+
+
+[docs]
+ @classmethod
+ deffrom_array(cls,array):
+"""Initialize a Vector3D/Point3D from an array.
+
+ Args:
+ array: A tuple or list with three numbers representing the x, y and z
+ values of the point.
+ """
+ returncls(array[0],array[1],array[2])
+
+
+
+[docs]
+ @classmethod
+ deffrom_vector2d(cls,vector2d,z=0):
+"""Initialize a new Vector3D from an Vector2D and a z value.
+
+ Args:
+ line2d: A Vector2D to be used to generate the Vector3D.
+ z: A number for the Z coordinate value of the line.
+ """
+ returncls(vector2d.x,vector2d.y,z)
+
+
+ @property
+ defx(self):
+"""Get the X coordinate."""
+ returnself._x
+
+ @property
+ defy(self):
+"""Get the Y coordinate."""
+ returnself._y
+
+ @property
+ defz(self):
+"""Get the Z coordinate."""
+ returnself._z
+
+ @property
+ defmagnitude(self):
+"""Get the magnitude of the vector."""
+ returnself.__abs__()
+
+ @property
+ defmagnitude_squared(self):
+"""Get the magnitude squared of the vector."""
+ returnself.x**2+self.y**2+self.z**2
+
+ @property
+ defmin(self):
+"""Always equal to (0, 0, 0).
+
+ This property exists to help with bounding box calculations.
+ """
+ returnPoint3D(0,0,0)
+
+ @property
+ defmax(self):
+"""Always equal to (0, 0, 0).
+
+ This property exists to help with bounding box calculations.
+ """
+ returnPoint3D(0,0,0)
+
+
+[docs]
+ defis_zero(self,tolerance):
+"""Boolean to note whether the vector is within a given zero tolerance.
+
+ Args:
+ tolerance: The tolerance below which the vector is considered to
+ be a zero vector.
+ """
+ returnabs(self.x)<=toleranceandabs(self.y)<=toleranceand \
+ abs(self.z)<=tolerance
+
+
+
+[docs]
+ defis_equivalent(self,other,tolerance):
+"""Test whether this object is equivalent to another within a certain tolerance.
+
+ Note that if you want to test whether the coordinate values are perfectly
+ equal to one another, the == operator can be used.
+
+ Args:
+ other: Another Point3D or Vector3D for which geometric equivalency
+ will be tested.
+ tolerance: The minimum difference between the coordinate values of two
+ objects at which they can be considered geometrically equivalent.
+
+ Returns:
+ True if equivalent. False if not equivalent.
+ """
+ returnabs(self.x-other.x)<=toleranceand \
+ abs(self.y-other.y)<=toleranceand \
+ abs(self.z-other.z)<=tolerance
+
+
+
+[docs]
+ defnormalize(self):
+"""Get a copy of the vector that is a unit vector (magnitude=1)."""
+ d=self.magnitude
+ try:
+ returnVector3D(self.x/d,self.y/d,self.z/d)
+ exceptZeroDivisionError:
+ returnself.duplicate()
+
+
+
+[docs]
+ defreverse(self):
+"""Get a copy of this vector that is reversed."""
+ returnself.__neg__()
+
+
+
+[docs]
+ defdot(self,other):
+"""Get the dot product of this vector with another."""
+ returnself.x*other.x+self.y*other.y+self.z*other.z
+
+
+
+[docs]
+ defcross(self,other):
+"""Get the cross product of this vector and another vector."""
+ returnVector3D(self.y*other.z-self.z*other.y,
+ -self.x*other.z+self.z*other.x,
+ self.x*other.y-self.y*other.x)
+
+
+
+[docs]
+ defangle(self,other):
+"""Get the smallest angle between this vector and another."""
+ try:
+ returnmath.acos(self.dot(other)/(self.magnitude*other.magnitude))
+ exceptValueError:# python floating tolerance can cause math domain error
+ ifself.dot(other)<0:
+ returnmath.acos(-1)
+ returnmath.acos(1)
+
+
+
+[docs]
+ defrotate(self,axis,angle):
+"""Get a vector rotated around an axis through an angle.
+
+ Right hand rule applies:
+ If axis has a positive orientation, rotation will be clockwise.
+ If axis has a negative orientation, rotation will be counterclockwise.
+
+ Args:
+ axis: A Vector3D axis representing the axis of rotation.
+ angle: An angle in radians.
+ """
+ returnVector3D._rotate(self,axis,angle)
+
+
+
+[docs]
+ defrotate_xy(self,angle):
+"""Get a vector rotated counterclockwise in the XY plane by a certain angle.
+
+ Args:
+ angle: An angle in radians.
+ """
+ vec_2=Vector2D._rotate(self,angle)
+ returnVector3D(vec_2.x,vec_2.y,self.z)
+
+
+
+[docs]
+ defreflect(self,normal):
+"""Get a vector that is reflected across a plane with the input normal vector.
+
+ Args:
+ normal: A Vector3D representing the normal vector for the plane across
+ which the vector will be reflected. THIS VECTOR MUST BE NORMALIZED.
+ """
+ returnVector3D._reflect(self,normal)
+
+
+
+[docs]
+ defproject(self,normal):
+"""Get a vector projected into a plane with a given normal.
+
+ Args:
+ normal: A Vector3D representing the normal vector of the plane into which
+ the plane will be projected. THIS VECTOR MUST BE NORMALIZED.
+ """
+ returnself-normal*self.dot(normal)
+
+
+
+[docs]
+ defduplicate(self):
+"""Get a copy of this vector."""
+ returnself.__copy__()
+
+
+
+[docs]
+ defto_dict(self):
+"""Get Vector3D as a dictionary."""
+ return{'type':'Vector3D',
+ 'x':self.x,
+ 'y':self.y,
+ 'z':self.z}
+
+
+
+[docs]
+ defto_array(self):
+"""Get Vector3D/Point3D as a tuple of three numbers"""
+ return(self.x,self.y,self.z)
+[docs]
+classPoint3D(Vector3D):
+"""3D Point object.
+
+ Args:
+ x: Number for the X coordinate.
+ y: Number for the Y coordinate.
+ z: Number for the Z coordinate.
+
+ Properties:
+ * x
+ * y
+ * z
+ """
+ __slots__=()
+
+
+[docs]
+ @classmethod
+ deffrom_point2d(cls,point2d,z=0):
+"""Initialize a new Point3D from an Point2D and a z value.
+
+ Args:
+ line2d: A Point2D to be used to generate the Point3D.
+ z: A number for the Z coordinate value of the line.
+ """
+ returncls(point2d.x,point2d.y,z)
+
+
+ @property
+ defmin(self):
+"""Always equal to the point itself.
+
+ This property exists to help with bounding box calculations.
+ """
+ returnself
+
+ @property
+ defmax(self):
+"""Always equal to the point itself.
+
+ This property exists to help with bounding box calculations.
+ """
+ returnself
+
+
+[docs]
+ defmove(self,moving_vec):
+"""Get a point that has been moved along a vector.
+
+ Args:
+ moving_vec: A Vector3D with the direction and distance to move the point.
+ """
+ returnPoint3D(self.x+moving_vec.x,
+ self.y+moving_vec.y,
+ self.z+moving_vec.z)
+
+
+
+[docs]
+ defrotate(self,axis,angle,origin):
+"""Rotate a point by a certain angle around an axis and origin.
+
+ Right hand rule applies:
+ If axis has a positive orientation, rotation will be clockwise.
+ If axis has a negative orientation, rotation will be counterclockwise.
+
+ Args:
+ axis: A Vector3D axis representing the axis of rotation.
+ angle: An angle for rotation in radians.
+ origin: A Point3D for the origin around which the point will be rotated.
+ """
+ returnVector3D._rotate(self-origin,axis,angle)+origin
+
+
+
+[docs]
+ defrotate_xy(self,angle,origin):
+"""Get a point rotated counterclockwise in the XY plane by a certain angle.
+
+ Args:
+ angle: An angle in radians.
+ origin: A Point3D for the origin around which the point will be rotated.
+ """
+ trans_self=self-origin
+ vec_2=Vector2D._rotate(trans_self,angle)
+ returnVector3D(vec_2.x,vec_2.y,trans_self.z)+origin
+
+
+
+[docs]
+ defreflect(self,normal,origin):
+"""Get a point reflected across a plane with the input normal vector and origin.
+
+ Args:
+ normal: A Vector3D representing the normal vector for the plane across
+ which the point will be reflected. THIS VECTOR MUST BE NORMALIZED.
+ origin: A Point3D representing the origin from which to reflect.
+ """
+ returnVector3D._reflect(self-origin,normal)+origin
+
+
+
+[docs]
+ defscale(self,factor,origin=None):
+"""Scale a point by a factor from an origin point.
+
+ Args:
+ factor: A number representing how much the point should be scaled.
+ origin: A Point3D representing the origin from which to scale.
+ If None, it will be scaled from the World origin (0, 0, 0).
+ """
+ iforiginisNone:
+ returnPoint3D(self.x*factor,self.y*factor,self.z*factor)
+ else:
+ return(factor*(self-origin))+origin
+
+
+
+[docs]
+ defproject(self,normal,origin):
+"""Get a point that is projected into a plane with a given normal and origin.
+
+ Args:
+ normal: A Vector3D representing the normal vector of the plane into which
+ the plane will be projected. THIS VECTOR MUST BE NORMALIZED.
+ origin: A Point3D representing the origin the plane into which the
+ point will be projected.
+ """
+ trans_self=self-origin
+ returnself-normal*trans_self.dot(normal)
+
+
+
+[docs]
+ defdistance_to_point(self,point):
+"""Get the distance from this point to another Point3D."""
+ vec=(self.x-point.x,self.y-point.y,self.z-point.z)
+ returnmath.sqrt(vec[0]**2+vec[1]**2+vec[2]**2)
+
+
+
+[docs]
+ defto_dict(self):
+"""Get Point3D as a dictionary."""
+ return{'type':'Point3D',
+ 'x':self.x,
+ 'y':self.y,
+ 'z':self.z}
+
+
+ def__add__(self,other):
+ # Point + Vector -> Point
+ # Point + Point -> Vector
+ ifisinstance(other,Point3D):
+ returnVector3D(self.x+other.x,self.y+other.y,self.z+other.z)
+ elifisinstance(other,Vector3D):
+ returnPoint3D(self.x+other.x,self.y+other.y,self.z+other.z)
+ else:
+ raiseTypeError('Cannot add Point3D and {}'.format(type(other)))
+
+ def__sub__(self,other):
+ # Point - Vector -> Point
+ # Point - Point -> Vector
+ ifisinstance(other,Point3D):
+ returnVector3D(self.x-other.x,self.y-other.y,self.z-other.z)
+ elifisinstance(other,Vector3D):
+ returnPoint3D(self.x-other.x,self.y-other.y,self.z-other.z)
+ else:
+ raiseTypeError('Cannot subtract Point3D and {}'.format(type(other)))
+
+ def__repr__(self):
+"""Point3D representation."""
+ return'Point3D (%.2f, %.2f, %.2f)'%(self.x,self.y,self.z)
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/_modules/ladybug_geometry/geometry3d/polyface.html b/docs/_modules/ladybug_geometry/geometry3d/polyface.html
new file mode 100644
index 00000000..14839336
--- /dev/null
+++ b/docs/_modules/ladybug_geometry/geometry3d/polyface.html
@@ -0,0 +1,2100 @@
+
+
+
+
+
+
+ ladybug_geometry.geometry3d.polyface — ladybug geometry documentation
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+[docs]
+classPolyface3D(Base2DIn3D):
+"""Object with Multiple Planar Faces in 3D Space. Includes solids and polyhedra.
+
+ Args:
+ vertices: A list of Point3D objects representing the vertices of
+ this PolyFace.
+ face_indices: A list of lists with one list for each face of the polyface.
+ Each face list must contain at least one tuple of integers corresponding
+ to indices within the vertices list. Additional tuples of integers may
+ follow this one such that the first tuple denotes the boundary of the
+ face while each subsequent tuple denotes a hole in the face.
+ edge_information: Optional edge information, which will speed up the
+ creation of the Polyface object if it is available but should be left
+ as None if it is unknown. If None, edge_information will be computed
+ from the vertices and face_indices inputs. Edge information
+ should be formatted as a dictionary with two keys as follows:
+
+ * 'edge_indices':
+ An array objects that each contain two integers.
+ These integers correspond to indices within the vertices list and
+ each tuple represents a line segment for an edge of the polyface.
+ * 'edge_types':
+ An array of integers for each edge that parallels the edge_indices
+ list. An integer of 0 denotes a naked edge, an integer of 1
+ denotes an internal edge. Anything higher is a non-manifold edge.
+
+ Properties:
+ * vertices
+ * faces
+ * edges
+ * naked_edges
+ * internal_edges
+ * non_manifold_edges
+ * face_indices
+ * edge_indices
+ * edge_types
+ * min
+ * max
+ * center
+ * area
+ * volume
+ * is_solid
+ """
+ __slots__=('_faces','_edges',
+ '_naked_edges','_internal_edges','_non_manifold_edges',
+ '_face_indices','_edge_indices','_edge_types',
+ '_area','_volume','_is_solid')
+
+ def__init__(self,vertices,face_indices,edge_information=None):
+"""Initialize Polyface3D."""
+ # assign input properties
+ Base2DIn3D.__init__(self,vertices)
+ self._face_indices=tuple(tuple(tuple(loop)forloopinface)
+ forfaceinface_indices)
+
+ ifedge_informationisnotNone:# unpack the input edge information
+ edge_i=edge_information['edge_indices']
+ edge_t=edge_information['edge_types']
+ else:# autocalculate the edge information from the vertices and faces
+ edge_i=[]
+ edge_t=[]
+ forfaceinface_indices:
+ forfiinface:
+ fori,viinenumerate(fi):
+ try:# this can get slow for large number of vertices
+ ind=edge_i.index((vi,fi[i-1]))
+ edge_t[ind]+=1
+ exceptValueError:# make sure reversed edge isn't there
+ try:
+ ind=edge_i.index((fi[i-1],vi))
+ edge_t[ind]+=1
+ exceptValueError:# add a new edge
+ iffi[i-1]!=vi:# avoid cases of same start and end
+ edge_i.append((fi[i-1],vi))
+ edge_t.append(0)
+ self._edge_indices=edge_iifisinstance(edge_i,tuple)elsetuple(edge_i)
+ self._edge_types=edge_tifisinstance(edge_t,tuple)elsetuple(edge_t)
+
+ # determine solidity of the polyface by checking for internal edges
+ self._is_solid=True
+ foredgeinself._edge_types:
+ ifedge!=1:
+ self._is_solid=False
+ break
+
+ # assign default properties
+ self._faces=None
+ self._edges=None
+ self._naked_edges=None
+ self._internal_edges=None
+ self._non_manifold_edges=None
+ self._area=None
+ self._volume=None
+
+
+[docs]
+ @classmethod
+ deffrom_faces(cls,faces,tolerance):
+"""Initialize Polyface3D from a list of Face3D objects.
+
+ Note that the Polyface3D.faces property of the resulting polyface will
+ have an order of faces that matches the order input to this classmethod.
+
+ Args:
+ faces: A list of Face3D objects representing the boundary of this Polyface.
+ tolerance: The maximum difference between x, y, and z values at which
+ the vertex of two adjacent faces is considered the same.
+ """
+ # extract unique vertices from the faces
+ vertices=[]# collection of vertices as point objects
+ face_indices=[]# collection of face indices
+ forfinfaces:
+ ind=[]
+ loops=(f.boundary,)ifnotf.has_holeselse(f.boundary,)+f.holes
+ forj,loopinenumerate(loops):
+ ind.append([])
+ forvinloop:
+ found=False
+ fori,vertinenumerate(vertices):
+ ifv.is_equivalent(vert,tolerance):
+ found=True
+ ind[j].append(i)
+ break
+ ifnotfound:# add new point
+ vertices.append(v)
+ ind[j].append(len(vertices)-1)
+ face_indices.append(tuple(ind))
+
+ # get the polyface object and assign correct faces to it
+ face_obj=cls(vertices,face_indices)
+ ifface_obj._is_solid:
+ face_obj._faces=cls.get_outward_faces(faces,0.01)
+ else:
+ face_obj._faces=tuple(faces)
+ returnface_obj
+
+
+
+[docs]
+ @classmethod
+ deffrom_box(cls,width,depth,height,base_plane=None):
+"""Initialize Polyface3D from parameters describing a box.
+
+ Initializing a polyface this way has the added benefit of having its
+ faces property quickly calculated.
+
+ Args:
+ width: A number for the width of the box (in the X direction).
+ depth: A number for the depth of the box (in the Y direction).
+ height: A number for the height of the box (in the Z direction).
+ base_plane: A Plane object from which to generate the box.
+ If None, default is the WorldXY plane.
+ """
+ assertisinstance(width,(float,int)),'Box width must be a number.'
+ assertisinstance(depth,(float,int)),'Box depth must be a number.'
+ assertisinstance(height,(float,int)),'Box height must be a number.'
+ ifbase_planeisnotNone:
+ assertisinstance(base_plane,Plane), \
+ 'base_plane must be Plane. Got {}.'.format(type(base_plane))
+ else:
+ base_plane=Plane(Vector3D(0,0,1),Point3D())
+ _o=base_plane.o
+ _w_vec=base_plane.x*width
+ _d_vec=base_plane.y*depth
+ _h_vec=base_plane.n*height
+ _verts=(_o,_o+_d_vec,_o+_d_vec+_w_vec,_o+_w_vec,
+ _o+_h_vec,_o+_d_vec+_h_vec,
+ _o+_d_vec+_w_vec+_h_vec,_o+_w_vec+_h_vec)
+ _face_indices=([(0,1,2,3)],[(2,1,5,6)],[(6,7,3,2)],
+ [(0,3,7,4)],[(0,4,5,1)],[(7,6,5,4)])
+ _edge_indices=((3,0),(0,1),(1,2),(2,3),(0,4),(4,5),
+ (5,1),(3,7),(7,4),(6,2),(5,6),(6,7))
+ polyface=cls(_verts,_face_indices,{'edge_indices':_edge_indices,
+ 'edge_types':[1]*12})
+ verts=tuple(tuple(_verts[i]foriinface[0])forfacein_face_indices)
+ bottom=Face3D(verts[0],base_plane.flip(),enforce_right_hand=False)
+ middle=tuple(Face3D(v,enforce_right_hand=False)forvinverts[1:5])
+ top=Face3D(verts[5],base_plane.move(_h_vec),enforce_right_hand=False)
+ polyface._faces=(bottom,)+middle+(top,)
+ polyface._volume=width*depth*height
+ returnpolyface
+
+
+
+[docs]
+ @classmethod
+ deffrom_offset_face(cls,face,offset):
+"""Initialize a solid Polyface3D from a Face3D offset along its normal.
+
+ The resulting polyface will always be offset in the direction of
+ the face normal.
+
+ When a polyface is initialized this way, the first face of the
+ Polyface3D.faces will always be the input face used to create the
+ object, the last face will be the offset version of the face, and all
+ other faces will form the extrusion connecting the two.
+
+ Args:
+ face: A Face3D to serve as a base for the polyface.
+ offset: A number for the distance to offset the face to make a solid.
+ """
+ assertisinstance(face,Face3D), \
+ 'face must be a Face3D. Got {}.'.format(type(face))
+ assertisinstance(offset,(float,int)), \
+ 'height must be a number. Got {}.'.format(type(offset))
+ # compute vertices, face indices, and edges of the extrusion
+ extru_vec=face.normal*offset
+ verts,face_ind_extru,edge_indices= \
+ Polyface3D._verts_faces_edges_from_boundary(face.boundary,extru_vec)
+ ifface.has_holes:
+ _st_i=len(verts)
+ fori,holeinenumerate(face.hole_polygon2d):
+ hole_verts=face._holes[i]ifhole.is_clockwiseelse \
+ tuple(reversed(face._holes[i]))
+ verts_2,face_ind_extru_2,edge_indices_2= \
+ Polyface3D._verts_faces_edges_from_boundary(
+ hole_verts,extru_vec,_st_i)
+ verts.extend(verts_2)
+ face_ind_extru.extend(face_ind_extru_2)
+ edge_indices.extend(edge_indices_2)
+ _st_i+=len(hole_verts*2)
+ face_ind_extru=[[fc]forfcinface_ind_extru]
+ # compute the final faces (accounting for top and bottom)
+ ifnotface.has_holes:
+ len_faces=len(face.boundary)
+ face_ind_bottom=[tuple(reversed(xrange(len_faces)))]
+ face_ind_top=[tuple(
+ reversed(xrange(len_faces*2-1,len_faces-1,-1)))]
+ else:
+ face_verts_bottom=[list(reversed(face.boundary))]+list(face.holes)
+ face_verts_top=[[pt.move(extru_vec)forptinreversed(loop)]
+ forloopinface_verts_bottom]
+ face_ind_bottom=[tuple(verts.index(pt)forptinloop)
+ forloopinface_verts_bottom]
+ face_ind_top=[tuple(verts.index(pt)forptinloop)
+ forloopinface_verts_top]
+ faces_ind=[face_ind_bottom]+face_ind_extru+[face_ind_top]
+ # create the polyface and assign known properties.
+ polyface=cls(verts,faces_ind,{'edge_indices':edge_indices,
+ 'edge_types':[1]*len(edge_indices)})
+ polyface._volume=face.area*offset
+ face_verts=tuple(
+ tuple(tuple(verts[i]foriinloop)forloopinf)forfinfaces_ind)
+ ifnotface.has_holes:
+ polyface._faces=tuple(Face3D(v[0],enforce_right_hand=False)
+ forvinface_verts)
+ else:
+ mid_faces=[Face3D(v[0],enforce_right_hand=False)
+ forvinface_verts[1:-1]]
+ bottom_face=face.flip()
+ top_face=face.move(extru_vec)
+ polyface._faces=tuple([bottom_face]+mid_faces+[top_face])
+ returnpolyface
+
+
+ @property
+ defvertices(self):
+"""Tuple of all vertices in this polyface.
+
+ Note that, in the case of a polyface with holes, some vertices will be repeated
+ since this property effectively traces out a single boundary around the
+ whole shape, winding inward to cut out the holes.
+ """
+ returnself._vertices
+
+ @property
+ deffaces(self):
+"""Tuple of all Face3D objects making up this polyface."""
+ ifself._facesisNone:
+ faces=[]
+ forfaceinself._face_indices:
+ boundary=tuple(self.vertices[i]foriinface[0])
+ iflen(face)==1:
+ faces.append(Face3D(boundary))
+ else:
+ holes=tuple(tuple(self.vertices[i]foriinf)forfinface[1:])
+ faces.append(Face3D(boundary=boundary,holes=holes))
+ ifself._is_solid:
+ self._faces=Polyface3D.get_outward_faces(faces,0.01)
+ else:
+ self._faces=tuple(faces)
+ returnself._faces
+
+ @property
+ defedges(self):
+""""Tuple of all edges in this polyface as LineSegment3D objects."""
+ ifself._edgesisNone:
+ self._edges=tuple(LineSegment3D.from_end_points(
+ self.vertices[seg[0]],self.vertices[seg[1]])
+ forseginself._edge_indices)
+ returnself._edges
+
+ @property
+ defnaked_edges(self):
+""""Tuple of all naked edges in this polyface as LineSegment3D objects.
+
+ Naked edges belong to only one face in the polyface (they are not
+ shared between faces).
+ """
+ ifself._naked_edgesisNone:
+ self._naked_edges=self._get_edge_type(0)
+ returnself._naked_edges
+
+ @property
+ definternal_edges(self):
+""""Tuple of all internal edges in this polyface as LineSegment3D objects.
+
+ Internal edges are shared between two faces in the polyface.
+ """
+ ifself._internal_edgesisNone:
+ self._internal_edges=self._get_edge_type(1)
+ returnself._internal_edges
+
+ @property
+ defnon_manifold_edges(self):
+""""Tuple of all non-manifold edges in this polyface as LineSegment3D objects.
+
+ Non-manifold edges are shared between three or more faces and are therefore
+ not allowed in solid polyfaces.
+ """
+ ifself._non_manifold_edgesisNone:
+ ifself._edgesisNone:
+ self.edges
+ nm_edges=[]
+ fori,typeinenumerate(self._edge_types):
+ iftype>1:
+ nm_edges.append(self._edges[i])
+ self._non_manifold_edges=tuple(nm_edges)
+ returnself._non_manifold_edges
+
+ @property
+ defface_indices(self):
+"""Tuple of face tuples with integers corresponding to indices of vertices."""
+ returnself._face_indices
+
+ @property
+ defedge_indices(self):
+"""Tuple of edge tuples with integers corresponding to indices of vertices."""
+ returnself._edge_indices
+
+ @property
+ defedge_types(self):
+"""Tuple of integers for each edge that denotes the type of edge.
+
+ 0 denotes a naked edge, 1 denotes an internal edge, and anything higher is a
+ non-manifold edge.
+ """
+ returnself._edge_types
+
+ @property
+ defedge_information(self):
+"""Dictionary with keys edge_indices, edge_types and corresponding properties.
+ """
+ return{'edge_indices':self._edge_indices,'edge_types':self._edge_types}
+
+ @property
+ defarea(self):
+"""The total surface area of the polyface."""
+ ifself._areaisNone:
+ self._area=sum([face.areaforfaceinself.faces])
+ returnself._area
+
+ @property
+ defvolume(self):
+"""The volume enclosed by the polyface.
+
+ Note that, if this polyface is not solid (with all face normals pointing
+ outward), the value of this property will not be valid.
+ """
+ ifself._volumeisNone:
+ # formula taken from https://en.wikipedia.org/wiki/Polyhedron#Volume
+ _v=0
+ fori,faceinenumerate(self.faces):
+ _v+=face[0].dot(face.normal)*face.area
+ self._volume=_v/3
+ returnself._volume
+
+ @property
+ defis_solid(self):
+"""A boolean to note whether the polyface is solid (True) or is open (False).
+
+ Note that all solid polyface objects will have faces pointing outwards.
+ """
+ returnself._is_solid
+
+
+[docs]
+ defmerge_overlapping_edges(self,tolerance,angle_tolerance):
+"""Get this object with overlapping naked edges merged into single internal edges
+
+ This can be used to determine if a polyface is truly solid since this check
+ is not performed by default when the Polyface3D is created from_faces.
+ In the default test of edge conditions, overlapping colinear edges are
+ considered naked when the could be interpreted a single internal edge
+ such as the case below:
+
+ .. code-block:: shell
+
+ | 1 |
+ A|______________________|C
+ | B| |
+ | | |
+ | 2 | 3 |
+
+ If Face 1 only has edge AC and not two separate edges for AB and BC, the
+ creation of the polyface will yield naked edges for AC, AB, and BC, meaning
+ the shape would not be considered solid when it might actually be so. This
+ merge_overlapping_edges method overcomes this by replacing the entire set
+ of 3 naked edges above a single internal edge running from A to C.
+
+ Args:
+ tolerance: The minimum distance between a vertex and the boundary segments
+ at which point the vertex is considered colinear.
+ angle_tolerance: The max angle in radians that vertices are allowed to
+ differ from one another in order to consider them colinear.
+ """
+ # get naked edges
+ naked_edges=list(self.naked_edges)
+ iflen(naked_edges)==0:
+ returnself
+
+ # establish lists that will be iteratively edited
+ remove_i=[]
+ add_edges=[]
+ naked_edge_i=[]
+ naked_edge_ind=[]
+ fori,xinenumerate(self.edge_types):
+ ifx==0:
+ naked_edge_i.append(i)
+ naked_edge_ind.append(self._edge_indices[i])
+
+ whilelen(naked_edge_i)>1:
+ # get all of the edges that are colinear with the first edge
+ coll_edges=list(naked_edge_ind[0])
+ coll_i=[naked_edge_i[0]]
+ kept_i,maybe_kept_i=[],[]
+ foredge,ind,nei,iinzip(
+ naked_edges[1:],naked_edge_ind[1:],naked_edge_i[1:],
+ xrange(1,len(naked_edges))):
+ try:
+ ifedge.is_colinear(naked_edges[0],tolerance,angle_tolerance):
+ coll_edges.extend(ind)
+ coll_i.append(nei)
+ maybe_kept_i.append(i)
+ else:
+ kept_i.append(i)
+ exceptZeroDivisionError:# duplicate vertices resulted in 0 length edge
+ coll_edges.extend(ind)
+ coll_i.append(nei)
+ maybe_kept_i.append(i)
+
+ # determine if colinear edges create a full double line along the edge
+ iflen(coll_edges)==1:# definitely a naked edge
+ overlapping=False
+ else:# all colinear edges are likely a part of the same loop
+ final_vi=[]
+ coll_edges_sort=sorted(coll_edges)
+ overlapping=True
+ foriinrange(0,len(coll_edges_sort),2):
+ final_vi.append(coll_edges_sort[i])
+ ifcoll_edges_sort[i]!=coll_edges_sort[i+1]:
+ overlapping=False
+ break
+ # there's still a chance we have multiple colinear loops
+ ifnotoverlapping:
+ dup={xforxincoll_edgesifcoll_edges.count(x)>1}
+ ifcoll_edges[0]indupandcoll_edges[1]indup:
+ rebuilt_edges=[(coll_edges[i],coll_edges[i+1])
+ foriinrange(0,len(coll_edges),2)]
+ loop_i=set(rebuilt_edges[0])
+ edge_to_check=rebuilt_edges[1:]
+ more_to_check=True
+ whilemore_to_check:
+ fori,r_seginenumerate(edge_to_check):
+ if(r_seg[0]inloop_iorr_seg[1]inloop_i):
+ loop_i.add(r_seg[0])
+ loop_i.add(r_seg[1])
+ deledge_to_check[i]
+ break
+ else:
+ more_to_check=False
+ ifall(liindupforliinloop_i):# we have found a loop!
+ final_vi=list(loop_i)
+ new_coll_i=[coll_i[0]]
+ zip_obj=zip(rebuilt_edges[1:],coll_i[1:],maybe_kept_i)
+ forind,nei,iinzip_obj:
+ ifind[0]inloop_i:
+ new_coll_i.append(nei)
+ else:
+ kept_i.append(i)
+ kept_i.sort()
+ coll_i=new_coll_i
+ overlapping=True
+
+ # if fully overlapping edges have been found, remake them into one
+ ifoverlapping:
+ remove_i.extend(coll_i)# remove overlapping edges from the list
+ verts=[self.vertices[j]forjinfinal_vi]
+ dir_vec=verts[0]-verts[1]
+ ifdir_vec.x!=0:
+ vert_coor=[v.xforvinverts]
+ elifdir_vec.y!=0:
+ vert_coor=[v.yforvinverts]
+ else:
+ vert_coor=[v.zforvinverts]
+ vert_coor,final_vi=zip(*sorted(zip(vert_coor,final_vi)))
+ add_edges.append((final_vi[0],final_vi[-1]))
+
+ # delete the colinear vertices that have been accounted for
+ naked_edges=[naked_edges[i]foriinkept_i]
+ naked_edge_ind=[naked_edge_ind[i]foriinkept_i]
+ naked_edge_i=[naked_edge_i[i]foriinkept_i]
+
+ # create the new edge information and the new polyface
+ new_edge_indices=list(self.edge_indices)
+ new_edge_types=list(self.edge_types)
+ add_i=[]
+ foriinrange(len(new_edge_indices)):
+ ifinotinremove_i:
+ add_i.append(i)
+ new_edge_indices=[new_edge_indices[i]foriinadd_i]
+ new_edge_types=[new_edge_types[i]foriinadd_i]
+ fornew_edgeinadd_edges:
+ new_edge_indices.append(new_edge)
+ new_edge_types.append(1)
+ _new_polyface=Polyface3D(
+ self._vertices,self._face_indices,
+ {'edge_indices':new_edge_indices,'edge_types':new_edge_types}
+ )
+
+ # if the result is still not solid, perform a check on the remaining edges
+ iflen(_new_polyface.naked_edges)!=0and \
+ len(_new_polyface.non_manifold_edges)==0:
+ # it's possible that the remaining gaps are smaller than the tolerance
+ small_gaps=True
+ joined_edges=Polyline3D.join_segments(_new_polyface.naked_edges,tolerance)
+ forbndinjoined_edges:
+ ifisinstance(bnd,Polyline3D)andbnd.is_closed(tolerance):
+ test_face=Face3D(bnd.vertices)
+ iftest_face.check_planar(tolerance,False):
+ min_,max_=test_face.min,test_face.max
+ max_dim=max(max_.x-min_.x,max_.y-min_.y,max_.z-min_.z)
+ tol_area=tolerance*max_dim
+ iftest_face.area>tol_area:
+ small_gaps=False
+ break
+ else:
+ small_gaps=False
+ break
+ else:
+ small_gaps=False
+ break
+ ifsmall_gaps:# the gaps are small enough to make the Polyface closed
+ new_edge_types=[1for_innew_edge_types]
+ _new_polyface=Polyface3D(
+ self._vertices,self._face_indices,
+ {'edge_indices':new_edge_indices,'edge_types':new_edge_types}
+ )
+
+ return_new_polyface
+
+
+
+[docs]
+ defmove(self,moving_vec):
+"""Get a polyface that has been moved along a vector.
+
+ Args:
+ moving_vec: A Vector3D with the direction and distance to move the polyface.
+ """
+ _verts=tuple(pt.move(moving_vec)forptinself.vertices)
+ _new_pface=Polyface3D(_verts,self.face_indices,self.edge_information)
+ ifself._facesisnotNone:
+ _new_pface._faces=tuple(face.move(moving_vec)forfaceinself._faces)
+ _new_pface._volume=self._volume
+ return_new_pface
+
+
+
+[docs]
+ defrotate(self,axis,angle,origin):
+"""Rotate a polyface by a certain angle around an axis and origin.
+
+ Right hand rule applies:
+ If axis has a positive orientation, rotation will be clockwise.
+ If axis has a negative orientation, rotation will be counterclockwise.
+
+ Args:
+ axis: A Vector3D axis representing the axis of rotation.
+ angle: An angle for rotation in radians.
+ origin: A Point3D for the origin around which the object will be rotated.
+ """
+ _verts=tuple(pt.rotate(axis,angle,origin)forptinself.vertices)
+ _new_pface=Polyface3D(_verts,self.face_indices,self.edge_information)
+ ifself._facesisnotNone:
+ _new_pface._faces=tuple(face.rotate(axis,angle,origin)
+ forfaceinself._faces)
+ _new_pface._volume=self._volume
+ return_new_pface
+
+
+
+[docs]
+ defrotate_xy(self,angle,origin):
+"""Get a polyface rotated counterclockwise in the world XY plane by an angle.
+
+ Args:
+ angle: An angle in radians.
+ origin: A Point3D for the origin around which the object will be rotated.
+ """
+ _verts=tuple(pt.rotate_xy(angle,origin)forptinself.vertices)
+ _new_pface=Polyface3D(_verts,self.face_indices,self.edge_information)
+ ifself._facesisnotNone:
+ _new_pface._faces=tuple(face.rotate_xy(angle,origin)
+ forfaceinself._faces)
+ _new_pface._volume=self._volume
+ return_new_pface
+
+
+
+[docs]
+ defreflect(self,normal,origin):
+"""Get a polyface reflected across a plane with the input normal and origin.
+
+ Args:
+ normal: A Vector3D representing the normal vector for the plane across
+ which the polyface will be reflected. THIS VECTOR MUST BE NORMALIZED.
+ origin: A Point3D representing the origin from which to reflect.
+ """
+ _verts=tuple(pt.reflect(normal,origin)forptinself.vertices)
+ _new_pface=Polyface3D(_verts,self.face_indices,self.edge_information)
+ ifself._facesisnotNone:
+ _new_pface._faces=tuple(face.reflect(normal,origin)
+ forfaceinself._faces)
+ _new_pface._volume=self._volume
+ return_new_pface
+
+
+
+[docs]
+ defscale(self,factor,origin=None):
+"""Scale a polyface by a factor from an origin point.
+
+ Args:
+ factor: A number representing how much the polyface should be scaled.
+ origin: A Point3D representing the origin from which to scale.
+ If None, it will be scaled from the World origin (0, 0, 0).
+ """
+ iforiginisNone:
+ _verts=tuple(Point3D(pt.x*factor,pt.y*factor,pt.z*factor)
+ forptinself._vertices)
+ else:
+ _verts=tuple(pt.scale(factor,origin)forptinself.vertices)
+ _new_pface=Polyface3D(_verts,self.face_indices,self.edge_information)
+ ifself._facesisnotNone:
+ _new_pface._faces=tuple(face.scale(factor,origin)
+ forfaceinself._faces)
+ _new_pface._volume=self._volume*factor**3 \
+ ifself._volumeisnotNoneelseNone
+ return_new_pface
+
+
+
+[docs]
+ defis_point_inside(self,point,test_vector=Vector3D(1,0,0)):
+"""Test whether a Point3D lies inside or outside the polyface.
+
+ Note that, if this polyface is not solid, the result will always be False.
+
+ Args:
+ point: A Point3D for which the inside/outside relationship will be tested.
+ test_vector: Optional vector to set the direction in which intersections
+ with the polyface faces will be evaluated to determine if the
+ point is inside. Default is the X-unit vector.
+
+ Returns:
+ A boolean denoting whether the point lies inside (True) or outside (False).
+ """
+ ifnotself.is_solid:
+ returnFalse
+ test_ray=Ray3D(point,test_vector)
+ n_int=0
+ for_finself.faces:
+ if_f.intersect_line_ray(test_ray):
+ n_int+=1
+ ifn_int%2==0:
+ returnFalse
+ returnTrue
+
+
+
+[docs]
+ defdoes_intersect_line_ray_exist(self,line_ray):
+"""Boolean for whether an intersection exists between the input Line3D or Ray3D.
+
+ Args:
+ line_ray: A Line3D or Ray3D object for which intersection will be evaluated.
+
+ Returns:
+ True if an intersection exists. False if it does not exist.
+ """
+ forfaceinself.faces:
+ _int=face.intersect_line_ray(line_ray)
+ if_intisnotNone:
+ returnTrue
+ returnFalse
+
+
+
+[docs]
+ defintersect_line_ray(self,line_ray):
+"""Get the intersections between this polyface and the input Line3D or Ray3D.
+
+ Args:
+ line_ray: A Line3D or Ray3D object for which intersection will be computed.
+
+ Returns:
+ A list of Point3D for the intersection. Will be an empty list if no
+ intersection exists.
+ """
+ _inters=[]
+ forfaceinself.faces:
+ _int=face.intersect_line_ray(line_ray)
+ if_intisnotNone:
+ _inters.append(_int)
+ return_inters
+
+
+
+[docs]
+ defintersect_plane(self,plane):
+"""Get the intersection between this polyface and the input plane.
+
+ Args:
+ plane: A Plane object for which intersection will be computed.
+
+ Returns:
+ List of LineSegment3D objects for the intersection.
+ Will be an empty list if no intersection exists.
+ """
+ _inters=[]
+ forfaceinself.faces:
+ _int=face.intersect_plane(plane)
+ if_intisnotNone:
+ _inters.extend(_int)
+ return_inters
+
+
+
+[docs]
+ @staticmethod
+ defoverlapping_bounding_boxes(polyface1,polyface2,tolerance):
+"""Check if the bounding boxes of two polyfaces overlap within a tolerance.
+
+ This is particularly useful as a check before performing computationally
+ intense processes between two polyfaces like intersection or checking for
+ adjacency. Checking the overlap of the bounding boxes is extremely quick
+ given this method's use of the Separating Axis Theorem.
+
+ Args:
+ polyface1: The first polyface to check.
+ polyface2: The second polyface to check.
+ tolerance: Distance within which two points are considered to be co-located.
+ """
+ # Bounding box check using the Separating Axis Theorem
+ polyf1_width=polyface1.max.x-polyface1.min.x
+ polyf2_width=polyface2.max.x-polyface2.min.x
+ dist_btwn_x=abs(polyface1.center.x-polyface2.center.x)
+ x_gap_btwn_box=dist_btwn_x-(0.5*polyf1_width)-(0.5*polyf2_width)
+
+ polyf1_depth=polyface1.max.y-polyface1.min.y
+ polyf2_depth=polyface2.max.y-polyface2.min.y
+ dist_btwn_y=abs(polyface1.center.y-polyface2.center.y)
+ y_gap_btwn_box=dist_btwn_y-(0.5*polyf1_depth)-(0.5*polyf2_depth)
+
+ polyf1_height=polyface1.max.z-polyface1.min.z
+ polyf2_height=polyface2.max.z-polyface2.min.z
+ dist_btwn_z=abs(polyface1.center.z-polyface2.center.z)
+ z_gap_btwn_box=dist_btwn_z-(0.5*polyf1_height)-(0.5*polyf2_height)
+
+ ifx_gap_btwn_box>toleranceory_gap_btwn_box>toleranceor \
+ z_gap_btwn_box>tolerance:
+ returnFalse# no overlap
+ returnTrue# overlap exists
+
+
+
+[docs]
+ @staticmethod
+ defget_outward_faces(faces,tolerance):
+"""Turn a list of faces forming a solid into one where they all point outward.
+
+ Note that, if the input faces do not form a closed solid, there may be some
+ output faces that are not pointing outward. However, if the gaps in the
+ combined solid are within the input tolerance, this should not be an issue.
+
+ Also, note that this method runs automatically for any solid polyface
+ (meaning every solid polyface automatically has outward-facing faces). So there
+ is no need to rerun this method for faces from a solid polyface.
+
+ Args:
+ faces: A list of Face3D objects that together form a solid.
+ tolerance: Optional tolerance for the permissable size of gap between
+ faces at which point the faces are considered to have a single edge.
+
+ Returns:
+ outward_faces -- A list of the input Face3D objects that all point outwards
+ (provided the input faces form a solid).
+ """
+ outward_faces=[]
+ fori,faceinenumerate(faces):
+ # construct a ray with the face normal and a point on the face
+ point_on_face=face._point_on_face(tolerance)
+ test_ray=Ray3D(point_on_face,face.normal)
+
+ # if the ray intersects with an even number of other faces, it is correct
+ n_int=0
+ for_finfaces[i+1:]:
+ if_f.intersect_line_ray(test_ray):
+ n_int+=1
+ for_finfaces[:i]:
+ if_f.intersect_line_ray(test_ray):
+ n_int+=1
+ ifn_int%2==0:
+ outward_faces.append(face)
+ else:
+ outward_faces.append(face.flip())
+ returnoutward_faces
+
+
+
+[docs]
+ defto_dict(self,include_edge_information=True):
+"""Get Polyface3D as a dictionary.
+
+ Args:
+ include_edge_information: Set to True to include the edge_information
+ in the dictionary, which will allow for fast initialization when
+ it is de-serialized. Default True.
+ """
+ base={'type':'Polyface3D',
+ 'vertices':[v.to_array()forvinself.vertices],
+ 'face_indices':self.face_indices}
+ ifinclude_edge_information:
+ base['edge_information']=self.edge_information
+ returnbase
+
+
+ def_get_edge_type(self,edge_type):
+"""Get all of the edges of a certain type in this polyface."""
+ ifself._edgesisNone:
+ self.edges
+ sel_edges=[]
+ fori,typeinenumerate(self._edge_types):
+ iftype==edge_type:
+ sel_edges.append(self._edges[i])
+ returntuple(sel_edges)
+
+ @staticmethod
+ def_verts_faces_edges_from_boundary(cclock_verts,extru_vec,st_i=0):
+"""Get vertices and face indices for a given Face3D loop (boundary or hole)."""
+ verts=list(cclock_verts)+[pt.move(extru_vec)forptincclock_verts]
+ len_faces=len(cclock_verts)
+ faces_ind=[]
+ foriinxrange(st_i,st_i+len_faces-1):
+ faces_ind.append((i,i+1,i+len_faces+1,i+len_faces))
+ faces_ind.append((st_i+len_faces-1,st_i,
+ st_i+len_faces,st_i+len_faces*2-1))
+ edge_i1=[(st_i+i,st_i+i+1)foriinxrange(len_faces-1)]
+ edge_i2=[(st_i+i,st_i+i+len_faces)foriinxrange(len_faces)]
+ edge_i3=[(st_i+len_faces+i,st_i+len_faces+i+1)
+ foriinxrange(len_faces-1)]
+ edge_indices=edge_i1+[(st_i+len_faces-1,st_i)]+edge_i2+edge_i3+ \
+ [(st_i+len_faces*2-1,st_i+len_faces)]
+ returnverts,faces_ind,edge_indices
+
+ def__copy__(self):
+ _new_poly=Polyface3D(self.vertices,self.face_indices,self.edge_information)
+ _new_poly._faces=self._faces
+ return_new_poly
+
+ def__key(self):
+"""A tuple based on the object properties, useful for hashing."""
+ returntuple(hash(pt)forptinself._vertices)+ \
+ tuple(hash(face)forfaceinself._face_indices)
+
+ def__hash__(self):
+ returnhash(self.__key())
+
+ def__eq__(self,other):
+ returnisinstance(other,Polyface3D)andself.__key()==other.__key()
+
+ def__repr__(self):
+ return'Polyface3D ({} faces) ({} vertices)'.format(
+ len(self.faces),len(self))
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/_modules/ladybug_geometry/geometry3d/polyline.html b/docs/_modules/ladybug_geometry/geometry3d/polyline.html
new file mode 100644
index 00000000..97a20e56
--- /dev/null
+++ b/docs/_modules/ladybug_geometry/geometry3d/polyline.html
@@ -0,0 +1,1536 @@
+
+
+
+
+
+
+ ladybug_geometry.geometry3d.polyline — ladybug geometry documentation
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+[docs]
+classPolyline3D(Base2DIn3D):
+"""3D polyline object.
+
+ Args:
+ vertices: A list of Point3D objects representing the vertices of the polyline.
+ interpolated: Boolean to note whether the polyline should be interpolated
+ between the input vertices when it is translated to other interfaces.
+ Note that this property has no bearing on the geometric calculations
+ performed by this library and is only present in order to assist with
+ display/translation.
+
+ Properties:
+ * vertices
+ * segments
+ * min
+ * max
+ * center
+ * p1
+ * p2
+ * length
+ * interpolated
+ """
+ __slots__=('_interpolated','_segments','_length')
+
+ def__init__(self,vertices,interpolated=False):
+"""Initialize Polyline3D."""
+ Base2DIn3D.__init__(self,vertices)
+ self._interpolated=interpolated
+ self._segments=None
+ self._length=None
+
+
+[docs]
+ @classmethod
+ deffrom_dict(cls,data):
+"""Create a Polyline3D from a dictionary.
+
+ Args:
+ data: A python dictionary in the following format.
+
+ .. code-block:: python
+
+ {
+ "type": "Polyline3D",
+ "vertices": [(0, 0, 0), (10, 0, 2), (0, 10, 4)]
+ }
+ """
+ interp=data['interpolated']if'interpolated'indataelseFalse
+ returncls(tuple(Point3D.from_array(pt)forptindata['vertices']),interp)
+
+
+
+[docs]
+ @classmethod
+ deffrom_array(cls,point_array):
+"""Create a Polyline3D from a nested array of vertex coordinates.
+
+ Args:
+ point_array: nested array of point arrays.
+ """
+ returnPolyline3D(Point3D(*point)forpointinpoint_array)
+
+
+
+[docs]
+ @classmethod
+ deffrom_polyline2d(cls,polyline2d,plane=None):
+"""Create a closed Polyline3D from a Polyline2D and a plane.
+
+ Args:
+ polyline2d: A Polyline2D object to be converted to a Polyline3D.
+ plane: A Plane in which the Polyline2D sits. If None, the WorldXY
+ plane will be used.
+ """
+ plane=Plane()ifplaneisNoneelseplane
+ returnPolyline3D((plane.xy_to_xyz(pt)forptinpolyline2d.vertices),
+ polyline2d.interpolated)
+
+
+ @property
+ defsegments(self):
+"""Tuple of all line segments in the polyline."""
+ ifself._segmentsisNone:
+ self._segments= \
+ tuple(LineSegment3D.from_end_points(vert,self._vertices[i+1])
+ fori,vertinenumerate(self._vertices[:-1]))
+ returnself._segments
+
+ @property
+ defp1(self):
+"""Starting point of the Polyline3D."""
+ returnself._vertices[0]
+
+ @property
+ defp2(self):
+"""End point of the Polyline3D."""
+ returnself._vertices[-1]
+
+ @property
+ deflength(self):
+"""The length of the polyline."""
+ ifself._lengthisNone:
+ self._length=sum([seg.lengthforseginself.segments])
+ returnself._length
+
+ @property
+ definterpolated(self):
+"""Boolean noting whether the polyline should be interpolated upon translation.
+
+ Note that this property has no bearing on the geometric calculations
+ performed by this library and is only present in order to assist with
+ display/translation.
+ """
+ returnself._interpolated
+
+
+[docs]
+ defis_closed(self,tolerance):
+"""Test whether this polyline is closed to within the tolerance.
+
+ Args:
+ tolerance: The minimum difference between vertices below which vertices
+ are considered the same.
+ """
+ returnself._vertices[0].is_equivalent(self._vertices[-1],tolerance)
+
+
+
+[docs]
+ defremove_colinear_vertices(self,tolerance):
+"""Get a version of this polyline without colinear or duplicate vertices.
+
+ Args:
+ tolerance: The minimum distance that a vertex can be from a line
+ before it is considered colinear.
+ """
+ iflen(self.vertices)==3:
+ returnself# Polyline3D cannot have fewer than 3 vertices
+ new_vertices=[self.vertices[0]]# first vertex is always ok
+ fori,_vinenumerate(self.vertices[1:-1]):
+ if(self[i]-_v).cross(self[i+2]-_v).magnitude>=tolerance:
+ new_vertices.append(_v)
+ new_vertices.append(self[-1])# last vertex is always ok
+ _new_poly=Polyline3D(new_vertices)
+ self._transfer_properties(_new_poly)
+ return_new_poly
+
+
+
+[docs]
+ defreverse(self):
+"""Get a copy of this polyline where the vertices are reversed."""
+ _new_poly=Polyline3D(tuple(ptforptinreversed(self.vertices)))
+ self._transfer_properties(_new_poly)
+ return_new_poly
+
+
+
+[docs]
+ defmove(self,moving_vec):
+"""Get a polyline that has been moved along a vector.
+
+ Args:
+ moving_vec: A Vector3D with the direction and distance to move the polyline.
+ """
+ _new_poly=Polyline3D(tuple(pt.move(moving_vec)forptinself.vertices))
+ self._transfer_properties(_new_poly)
+ return_new_poly
+
+
+
+[docs]
+ defrotate(self,axis,angle,origin):
+"""Rotate a polyline by a certain angle around an axis and origin.
+
+ Right hand rule applies:
+ If axis has a positive orientation, rotation will be clockwise.
+ If axis has a negative orientation, rotation will be counterclockwise.
+
+ Args:
+ axis: A Vector3D axis representing the axis of rotation.
+ angle: An angle for rotation in radians.
+ origin: A Point3D for the origin around which the point will be rotated.
+ """
+ _new_poly=Polyline3D(tuple(pt.rotate(axis,angle,origin)
+ forptinself.vertices))
+ self._transfer_properties(_new_poly)
+ return_new_poly
+
+
+
+[docs]
+ defrotate_xy(self,angle,origin):
+"""Get a polyline rotated counterclockwise in the XY plane by a certain angle.
+
+ Args:
+ angle: An angle in radians.
+ origin: A Point3D for the origin around which the object will be rotated.
+ """
+ _new_p=Polyline3D(tuple(pt.rotate_xy(angle,origin)forptinself.vertices))
+ self._transfer_properties(_new_p)
+ return_new_p
+
+
+
+[docs]
+ defreflect(self,normal,origin):
+"""Get a polyline reflected across a plane with the input normal and origin.
+
+ Args:
+ normal: A Vector3D representing the normal vector for the plane across
+ which the polyline will be reflected. THIS VECTOR MUST BE NORMALIZED.
+ origin: A Point3D representing the origin from which to reflect.
+ """
+ _new_poly=Polyline3D(tuple(pt.reflect(normal,origin)forptinself.vertices))
+ self._transfer_properties(_new_poly)
+ return_new_poly
+
+
+
+[docs]
+ defscale(self,factor,origin=None):
+"""Scale a polyline by a factor from an origin point.
+
+ Args:
+ factor: A number representing how much the polyline should be scaled.
+ origin: A Point3D representing the origin from which to scale.
+ If None, it will be scaled from the World origin (0, 0, 0).
+ """
+ iforiginisNone:
+ _new_poly=Polyline3D(tuple(
+ Point3D(pt.x*factor,pt.y*factor,pt.z*factor)
+ forptinself.vertices))
+ else:
+ _new_poly=Polyline3D(tuple(
+ pt.scale(factor,origin)forptinself.vertices))
+ _new_poly._interpolated=self._interpolated
+ return_new_poly
+
+
+
+[docs]
+ defintersect_plane(self,plane):
+"""Get the intersections between this polyline and a Plane.
+
+ Args:
+ plane: A Plane that will be intersected with this object.
+
+ Returns:
+ A list with Point3D objects for the intersections.
+ List will be empty if no intersection exists.
+ """
+ intersections=[]
+ for_sinself.segments:
+ inters=intersect_line3d_plane(_s,plane)
+ ifintersisnotNone:
+ intersections.append(inters)
+ returnintersections
+
+
+
+[docs]
+ defsplit_with_plane(self,plane):
+"""Split this Polyline3D into Polyline3Ds and LineSegment3Ds using a Plane.
+
+ Args:
+ plane: A Plane that will be used to split this polyline.
+
+ Returns:
+ A list of Polyline3D and LineSegment3D objects if the split was successful.
+ Will be a list with 1 Polyline3D if no intersection exists.
+ """
+ # group the vertices based on when they cross the plane
+ grouped_verts=[[self._vertices[0]]]
+ for_sinself.segments:
+ inters=intersect_line3d_plane(_s,plane)
+ ifintersisNone:
+ grouped_verts[-1].append(_s.p2)
+ else:# intersection; start a new group
+ grouped_verts[-1].append(inters)
+ grouped_verts.append([inters,_s.p2])
+
+ # make new Polyline3D and LineSegment3D objects based on the groups
+ returnself._grouped_verts_to_objs(grouped_verts,self._interpolated)
+
+
+
+[docs]
+ defto_dict(self):
+"""Get Polyline3D as a dictionary."""
+ base={'type':'Polyline3D',
+ 'vertices':[pt.to_array()forptinself.vertices]}
+ ifself.interpolated:
+ base['interpolated']=self.interpolated
+ returnbase
+
+
+
+[docs]
+ defto_array(self):
+"""Get a list of lists where each sub-list represents a Point3D vertex."""
+ returntuple(pt.to_array()forptinself.vertices)
+
+
+
+[docs]
+ defto_polyline2d(self):
+"""Get a Polyline2D in the XY plane derived from this 3D polyline."""
+ returnPolyline2D(
+ (Point2D(pt.x,pt.y)forptinself.vertices),self.interpolated)
+
+
+
+[docs]
+ @staticmethod
+ defjoin_segments(segments,tolerance):
+"""Get an array of Polyline3Ds from a list of LineSegment3Ds.
+
+ Args:
+ segments: An array of LineSegment3D objects.
+ tolerance: The minimum difference in X, Y, and Z values at which Point2Ds
+ are considered equivalent. Segments with points that match within the
+ tolerance will be joined.
+
+ Returns:
+ An array of Polyline3D and LineSegment3D objects assembled from the
+ joined segments.
+ """
+ # group the vertices that make up polylines
+ grouped_verts=_group_vertices(segments,tolerance)
+ # create the Polyline3D and LineSegment3D objects
+ returnPolyline3D._grouped_verts_to_objs(grouped_verts)
+
+
+ def_transfer_properties(self,new_polyline):
+"""Transfer properties from this polyline to a new polyline."""
+ new_polyline._interpolated=self._interpolated
+ new_polyline._length=self._length
+
+ @staticmethod
+ def_grouped_verts_to_objs(grouped_verts,interpolated=False):
+ joined_lines=[]
+ forv_listingrouped_verts:
+ iflen(v_list)==2:
+ joined_lines.append(LineSegment3D.from_end_points(v_list[0],v_list[1]))
+ else:
+ joined_lines.append(Polyline3D(v_list,interpolated))
+ returnjoined_lines
+
+ def__copy__(self):
+ returnPolyline3D(self._vertices,self._interpolated)
+
+ def__key(self):
+"""A tuple based on the object properties, useful for hashing."""
+ returntuple(hash(pt)forptinself._vertices)+(self._interpolated,)
+
+ def__hash__(self):
+ returnhash(self.__key())
+
+ def__eq__(self,other):
+ returnisinstance(other,Polyline3D)andself.__key()==other.__key()
+
+ def__repr__(self):
+ return'Polyline3D ({} vertices)'.format(len(self))
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/_modules/ladybug_geometry/geometry3d/ray.html b/docs/_modules/ladybug_geometry/geometry3d/ray.html
new file mode 100644
index 00000000..7cf61c11
--- /dev/null
+++ b/docs/_modules/ladybug_geometry/geometry3d/ray.html
@@ -0,0 +1,1331 @@
+
+
+
+
+
+
+ ladybug_geometry.geometry3d.ray — ladybug geometry documentation
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+[docs]
+classRay3D(Base1DIn3D):
+"""3D Ray object.
+
+ Args:
+ p: A Point3D representing the base of the ray.
+ v: A Vector3D representing the direction of the ray.
+
+ Properties:
+ * p
+ * v
+ * min
+ * max
+ * center
+ """
+ __slots__=()
+
+ def__init__(self,p,v):
+"""Initialize Ray3D."""
+ Base1DIn3D.__init__(self,p,v)
+
+
+[docs]
+ @classmethod
+ deffrom_array(cls,ray_array):
+""" Create a Ray3D from a nested array with a point and a vector.
+
+ Args:
+ ray_array: Nested tuples ((p.x, p.y), (v.x, v.y)).
+ """
+ returnRay3D(Point3D(*ray_array[0]),Vector3D(*ray_array[1]))
+
+
+
+[docs]
+ @classmethod
+ deffrom_ray2d(cls,ray2d,z=0):
+"""Initialize a new Ray3D from an Ray2D and a z value.
+
+ Args:
+ line2d: A Ray2D to be used to generate the Ray3D.
+ z: A number for the Z coordinate value of the line.
+ """
+ base_p=Point3D(ray2d.p.x,ray2d.p.y,z)
+ base_v=Vector3D(ray2d.v.x,ray2d.v.y,0)
+ returncls(base_p,base_v)
+
+
+
+[docs]
+ defreverse(self):
+"""Get a copy of this ray that is reversed."""
+ returnRay3D(self.p,self.v.reverse())
+
+
+
+[docs]
+ defmove(self,moving_vec):
+"""Get a ray that has been moved along a vector.
+
+ Args:
+ moving_vec: A Vector3D with the direction and distance to move the ray.
+ """
+ returnRay3D(self.p.move(moving_vec),self.v)
+
+
+
+[docs]
+ defrotate(self,axis,angle,origin):
+"""Rotate a ray by a certain angle around an axis and origin.
+
+ Right hand rule applies:
+ If axis has a positive orientation, rotation will be clockwise.
+ If axis has a negative orientation, rotation will be counterclockwise.
+
+ Args:
+ axis: A Vector3D axis representing the axis of rotation.
+ angle: An angle for rotation in radians.
+ origin: A Point3D for the origin around which the object will be rotated.
+ """
+ returnRay3D(self.p.rotate(axis,angle,origin),self.v.rotate(axis,angle))
+
+
+
+[docs]
+ defrotate_xy(self,angle,origin):
+"""Get a ray rotated counterclockwise in the XY plane by a certain angle.
+
+ Args:
+ angle: An angle in radians.
+ origin: A Point3D for the origin around which the object will be rotated.
+ """
+ returnRay3D(self.p.rotate_xy(angle,origin),self.v.rotate_xy(angle))
+
+
+
+[docs]
+ defreflect(self,normal,origin):
+"""Get a ray reflected across a plane with the input normal vector and origin.
+
+ Args:
+ normal: A Vector3D representing the normal vector for the plane across
+ which the ray will be reflected. THIS VECTOR MUST BE NORMALIZED.
+ origin: A Point3D representing the origin from which to reflect.
+ """
+ returnRay3D(self.p.reflect(normal,origin),self.v.reflect(normal))
+
+
+
+[docs]
+ defscale(self,factor,origin=None):
+"""Scale a ray by a factor from an origin point.
+
+ Args:
+ factor: A number representing how much the ray should be scaled.
+ origin: A Point3D representing the origin from which to scale.
+ If None, it will be scaled from the World origin (0, 0, 0).
+ """
+ returnRay3D(self.p.scale(factor,origin),self.v*factor)
+
+
+
+[docs]
+ defscale_world_origin(self,factor):
+"""Scale a ray by a factor from the world origin. Faster than Ray2D.scale.
+
+ Args:
+ factor: A number representing how much the ray should be scaled.
+ """
+ returnRay3D(self.p.scale_world_origin(factor),self.v*factor)
+
+
+
+[docs]
+ defto_dict(self):
+"""Get Ray3D as a dictionary."""
+ base=Base1DIn3D.to_dict(self)
+ base['type']='Ray3D'
+ returnbase
+
+
+
+[docs]
+ defto_array(self):
+"""A nested array representing the start point and vector."""
+ return(self.p.to_array(),self.v.to_array())
+[docs]
+classSphere(object):
+"""Sphere object.
+
+ Args:
+ center: A Point3D representing the center of the arc.
+ radius: A number representing the radius of the sphere.
+
+ Properties:
+ * center
+ * radius
+ * min
+ * max
+ * diameter
+ * circumference
+ * area
+ * volume
+ """
+ __slots__=('_center','_radius')
+
+ def__init__(self,center,radius):
+"""Initialize Sphere."""
+ assertisinstance(center,Point3D), \
+ "Expected Point3D. Got {}.".format(type(center))
+ assertradius>0,'Sphere radius must be greater than 0. Got {}.'.format(radius)
+ self._center=center
+ self._radius=radius
+
+
+[docs]
+ @classmethod
+ deffrom_dict(cls,data):
+"""Create a Sphere from a dictionary.
+
+ Args:
+ data: A python dictionary in the following format
+
+ .. code-block:: python
+
+ {
+ "type": "Sphere"
+ "center": (10, 0, 0),
+ "radius": 5
+ }
+ """
+ returncls(Point3D.from_array(data['center']),data['radius'])
+
+
+ @property
+ defcenter(self):
+"""Center of sphere."""
+ returnself._center
+
+ @property
+ defradius(self):
+"""Radius of sphere."""
+ returnself._radius
+
+ @property
+ defmin(self):
+"""A Point3D for the minimum bounding box vertex around this geometry."""
+ returnPoint3D(self.center.x-self.radius,self.center.y-self.radius,
+ self.center.z-self.radius)
+
+ @property
+ defmax(self):
+"""A Point3D for the maximum bounding box vertex around this geometry."""
+ returnPoint3D(self.center.x+self.radius,self.center.y+self.radius,
+ self.center.z+self.radius)
+
+ @property
+ defdiameter(self):
+"""Diameter of sphere"""
+ returnself.radius*2
+
+ @property
+ defcircumference(self):
+"""Circumference of sphere"""
+ return2*math.pi*self.radius
+
+ @property
+ defarea(self):
+"""Surface area of sphere"""
+ return4*math.pi*self.radius**2
+
+ @property
+ defvolume(self):
+"""Volume of sphere"""
+ return4/3*math.pi*self.radius**3
+
+
+[docs]
+ defmove(self,moving_vec):
+"""Get a sphere that has been moved along a vector.
+
+ Args:
+ moving_vec: A Vector3D with the direction and distance to move the sphere.
+ """
+ returnSphere(self.center.move(moving_vec),self.radius)
+
+
+
+[docs]
+ defrotate(self,axis,angle,origin):
+"""Rotate this sphere by a certain angle around an axis and origin.
+
+ Right hand rule applies:
+ If axis has a positive orientation, rotation will be clockwise.
+ If axis has a negative orientation, rotation will be counterclockwise.
+
+ Args:
+ axis: A Vector3D axis representing the axis of rotation.
+ angle: An angle for rotation in radians.
+ origin: A Point3D for the origin around which the sphere will be rotated.
+ """
+ returnSphere(self.center.rotate(axis,angle,origin),self.radius)
+
+
+
+[docs]
+ defrotate_xy(self,angle,origin):
+"""Get a sphere that is rotated counterclockwise in the world XY plane by an angle.
+
+ Args:
+ angle: An angle for rotation in radians.
+ origin: A Point3D for the origin around which the sphere will be rotated.
+ """
+ returnSphere(self.center.rotate_xy(angle,origin),self.radius)
+
+
+
+[docs]
+ defreflect(self,normal,origin):
+"""Get a sphere reflected across a plane with the input normal vector and origin.
+
+ Args:
+ normal: A Vector3D representing the normal vector for the plane across
+ which the arc will be reflected. THIS VECTOR MUST BE NORMALIZED.
+ origin: A Point3D representing the origin from which to reflect.
+ """
+ returnSphere(self.center.reflect(normal,origin),self.radius)
+
+
+
+[docs]
+ defscale(self,factor,origin=None):
+"""Scale a sphere by a factor from an origin point.
+
+ Args:
+ factor: A number representing how much the sphere should be scaled.
+ origin: A Point3D representing the origin from which to scale.
+ If None, it will be scaled from the World origin (0, 0, 0).
+ """
+ returnSphere(self.center.scale(factor,origin),self.radius*factor)
+
+
+
+[docs]
+ defintersect_plane(self,plane):
+"""Get the intersection of a plane with this Sphere object
+
+ Args:
+ plane: A Plane object.
+
+ Returns:
+ Arc3D representing a full circle if it exists.
+ None if no full intersection exists.
+ """
+ ip=intersect_plane_sphere(plane,self)# ip = [center pt, vector, radius]
+ returnNoneifipisNoneorisinstance(ip,Point3D)else \
+ Arc3D(Plane(ip[1],ip[0]),ip[2])
+
+
+
+[docs]
+ defintersect_line_ray(self,line_ray):
+"""Get the intersection between this Sphere object and a Ray2D/LineSegment2D.
+
+ Args:
+ line_ray: A LineSegment3D or Ray3D that will be extended infinitely
+ for intersection.
+
+ Returns:
+ A LineSegment3D object if a full intersection exists.
+ A Point if a tangent intersection exists.
+ None if no full intersection exists.
+ """
+ il=intersect_line3d_sphere(line_ray,self)
+ returnNoneifilisNoneelse \
+ ilifisinstance(il,Point3D)else \
+ LineSegment3D.from_end_points(il[0],il[1])
+
+
+
+[docs]
+ defduplicate(self):
+"""Get a copy of this object."""
+ returnself.__copy__()
+
+
+
+[docs]
+ defto_dict(self):
+"""Get Sphere as a dictionary."""
+ return{'type':'Sphere',
+ 'center':self.center.to_array(),
+ 'radius':self.radius}
+
+
+ def__copy__(self):
+ returnSphere(self._center,self._radius)
+
+ def__key(self):
+"""A tuple based on the object properties, useful for hashing."""
+ return(self._center,self._radius)
+
+ def__hash__(self):
+ returnhash(self.__key())
+
+ def__eq__(self,other):
+ returnisinstance(other,Sphere)andself.__key()==other.__key()
+
+ def__ne__(self,other):
+ returnnotself.__eq__(other)
+
+
+# coding=utf-8
+"""A class that supports the import and export of OBJ data to/from ladybug_geometry.
+"""
+importos
+
+try:
+ fromitertoolsimportizipaszip# python 2
+ writemode='wb'
+exceptImportError:
+ writemode='w'# python 3
+
+fromladybug_geometry.geometry2d.pointvectorimportPoint2D
+fromladybug_geometry.geometry3d.pointvectorimportVector3D,Point3D
+
+
+
+[docs]
+classOBJ(object):
+"""A class that supports the import and export of OBJ data to/from ladybug_geometry.
+
+ Note that ladybug_geometry Mesh3D can be easily created from this OBJ by
+ taking the vertices and normals.
+
+ Args:
+ vertices: A list or tuple of Point3D objects for vertices.
+ faces: A list of tuples with each tuple having either 3 or 4 integers.
+ These integers correspond to indices within the list of vertices.
+ vertex_texture_map: An optional list or tuple of Point2D that align with the
+ vertices input. All coordinate values of the Point2D should be between
+ 0 and 1 and are intended to map to the XY system of images to be mapped
+ onto the OBJ mesh. If None, the OBJ file is written without
+ textures. (Default: None).
+ vertex_normals: An optional list or tuple of Vector3D that align with the
+ vertices input and describe the normal vector to be used at each vertex.
+ If None, the OBJ file is written without normals. (Default: None).
+ vertex_colors: An optional list of colors that align with the vertices input.
+ Note that these are written into the OBJ alongside the vertex
+ coordinates separately from the texture map. Not all programs support
+ importing OBJs with this color information but Rhino does. (Default: None).
+ material_structure: A list of tuples where each tuple contains two elements.
+ The first is the identifier of a material that is used in the OBJ and
+ the second is the index of the face where the application of the new
+ material begins. If None, everything will be assumed to have the
+ same diffuse material. (Default: None).
+
+ Properties:
+ * vertices
+ * faces
+ * vertex_texture_map
+ * vertex_normals
+ * vertex_colors
+ * material_structure
+ """
+
+ __slots__=(
+ '_vertices','_faces','_vertex_texture_map','_vertex_normals',
+ '_vertex_colors','_material_structure'
+ )
+
+ def__init__(
+ self,vertices,faces,vertex_texture_map=None,vertex_normals=None,
+ vertex_colors=None,material_structure=None
+ ):
+ self._vertices=self._check_vertices_input(vertices)
+ self._faces=self._check_faces_input(faces)
+ self.vertex_texture_map=vertex_texture_map
+ self.vertex_normals=vertex_normals
+ self.vertex_colors=vertex_colors
+ self.material_structure=material_structure
+
+
+[docs]
+ @classmethod
+ deffrom_file(cls,file_path):
+"""Create an OBJ object from a .obj file.
+
+ Args:
+ file_path: Path to an OBJ file as a text string. Note that, if the file
+ includes texture mapping coordinates or vertex normals, the number
+ of texture coordinates and normals must align with the number of
+ vertices to be importable. Nearly all OBJ files follow this standard.
+ If any of the OBJ mesh faces contain more than 4 vertices, only
+ the first 4 vertices will be counted.
+ """
+ vertices,faces,vertex_texture_map,vertex_normals,vertex_colors= \
+ [],[],[],[],[]
+ mat_struct=[]
+ withopen(file_path,'r')asfp:
+ forlineinfp:
+ ifline.startswith('#'):
+ continue
+ wds=line.split()
+ iflen(wds)>0:
+ first_word=wds[0]
+ iffirst_word=='v':# start of a new vertex
+ vert=Point3D(float(wds[1]),float(wds[2]),float(wds[3]))
+ vertices.append(vert)
+ iflen(wds)>4:
+ vertex_colors.append(tuple(wds[4:]))
+ eliffirst_word=='f':# start of a new face
+ face=[]
+ forfvinwds[1:]:
+ face.append(int(fv.split('/')[0])-1)
+ iflen(face)>4:# truncate for compatibility with Mesh3D
+ face=face[:4]
+ faces.append(tuple(face))
+ eliffirst_word=='vn':# start of a new vertex normal
+ norm=Vector3D(float(wds[1]),float(wds[2]),float(wds[3]))
+ vertex_normals.append(norm)
+ eliffirst_word=='vt':# start of a new texture coordinate
+ texture=Point2D(float(wds[1]),float(wds[2]))
+ vertex_texture_map.append(texture)
+ eliffirst_word=='usemtl':# start of a new material application
+ mat_struct.append((wds[1],len(faces)))
+ returncls(vertices,faces,vertex_texture_map,vertex_normals,
+ vertex_colors,mat_struct)
+
+
+
+[docs]
+ @classmethod
+ deffrom_mesh3d(cls,mesh,include_colors=True,include_normals=False):
+"""Create an OBJ object from a ladybug_geometry Mesh3D.
+
+ If colors are specified on the Mesh3D, they will be correctly transferred
+ to the resulting OBJ object as long as include_colors is True.
+
+ Args:
+ mesh: A ladybug_geometry Mesh3D object to be converted to an OBJ object.
+ include_colors: Boolean to note whether the Mesh3D colors should be
+ transferred to the OBJ object. (Default: True).
+ include_normals: Boolean to note whether the vertex normals should be
+ included in the resulting OBJ object. (Default: False).
+ """
+ ifinclude_colorsandmesh.is_color_by_face:
+ # we need to duplicate vertices to preserve colors
+ vertices,faces,colors=[],[],[]
+ v_ct=0
+ forface_verts,colinzip(mesh.face_vertices,mesh.colors):
+ vertices.extend(face_verts)
+ iflen(face_verts)==4:
+ faces.append((v_ct,v_ct+1,v_ct+2,v_ct+3))
+ colors.extend([col]*4)
+ v_ct+=4
+ else:
+ faces.append((v_ct,v_ct+1,v_ct+2))
+ colors.extend([col]*3)
+ v_ct+=3
+ ifinclude_normals:
+ msh_norms=mesh.vertex_normals
+ vert_normals=[]
+ forfaceinmesh.faces:
+ forfiinface:
+ vert_normals.append(msh_norms[fi])
+ returncls(vertices,faces,vertex_normals=msh_norms,
+ vertex_colors=colors)
+ returncls(vertices,faces,vertex_colors=colors)
+ vertex_colors=mesh.colorsifinclude_colorselseNone
+ ifinclude_normals:
+ returncls(mesh.vertices,mesh.faces,vertex_normals=mesh.vertex_normals,
+ vertex_colors=vertex_colors)
+ returncls(mesh.vertices,mesh.faces,vertex_colors=vertex_colors)
+
+
+
+[docs]
+ @classmethod
+ deffrom_mesh3ds(cls,meshes,material_ids=None,include_normals=False):
+"""Create an OBJ object from a list of ladybug_geometry Mesh3D.
+
+ Mesh3D colors are ignored when using this method with the assumption that
+ materials are used to specify how the meshes should be rendered.
+
+ Args:
+ meshes: A list of ladybug_geometry Mesh3D objects to be converted
+ into an OBJ object.
+ material_ids: An optional list of strings that aligns with the input
+ meshes and denote materials assigned to each mesh. This list of
+ material IDs will be automatically converted into an efficient
+ material_structure for the OBJ object where materials used for
+ multiple meshes only include one reference to the material. If
+ None, the OBJ will have no material structure. (Default: None).
+ include_normals: Boolean to note whether the vertex normals should be
+ included in the resulting OBJ object. (Default: False).
+ """
+ # sort the meshes by material ID to ensure efficient material structure
+ ifmaterial_idsisnotNone:
+ assertlen(material_ids)==len(meshes),'Length of OBJ material_ids ({}) ' \
+ 'does not match the length of meshes ({}).'.format(
+ len(material_ids),len(meshes))
+ meshes=[xfor_,xinsorted(zip(material_ids,meshes))]
+ material_ids=sorted(material_ids)
+
+ # gather all vertices, faces, and (optionally) normals together
+ vertices,faces,normals,mat_struct=[],[],[],[]
+ v_count=0
+ ifmaterial_idsisnotNone:
+ last_mat=None
+ formesh,mat_idinzip(meshes,material_ids):
+ ifmat_id!=last_mat:
+ mat_struct.append((mat_id,len(faces)))
+ last_mat=mat_id
+ vertices.extend(mesh.vertices)
+ ifinclude_normals:
+ normals.extend(mesh.vertex_normals)
+ ifv_count==0:
+ faces.extend(mesh.faces)
+ else:
+ forfinmesh.faces:
+ faces.append(tuple(fi+v_countforfiinf))
+ v_count+=len(mesh.vertices)
+ else:
+ formeshinmeshes:
+ vertices.extend(mesh.vertices)
+ ifinclude_normals:
+ normals.extend(mesh.vertex_normals)
+ ifv_count==0:
+ faces.extend(mesh.faces)
+ else:
+ forfinmesh.faces:
+ faces.append(tuple(fi+v_countforfiinf))
+ v_count+=len(mesh.vertices)
+
+ returncls(
+ vertices,faces,vertex_normals=normals,material_structure=mat_struct)
+
+
+ @property
+ defvertices(self):
+"""Tuple of Point3D for all vertices in the OBJ."""
+ returnself._vertices
+
+ @property
+ deffaces(self):
+"""Tuple of tuples for all faces in the OBJ."""
+ returnself._faces
+
+ @property
+ defvertex_texture_map(self):
+"""Get or set a tuple of Point2D for texture image coordinates for each vertex.
+
+ Will be None if no texture map is assigned.
+ """
+ returnself._vertex_texture_map
+
+ @vertex_texture_map.setter
+ defvertex_texture_map(self,value):
+ ifvalueisnotNone:
+ assertisinstance(value,(list,tuple)),'vertex_texture_map should be ' \
+ 'a list or tuple. Got {}'.format(type(value))
+ ifisinstance(value,list):
+ value=tuple(value)
+ iflen(value)==0:
+ value=None
+ eliflen(value)!=len(self.vertices):
+ raiseValueError(
+ 'Number of items in vertex_texture_map ({}) does not match number'
+ 'of OBJ vertices ({}).'.format(len(value),len(self.vertices)))
+ else:
+ forvertinvalue:
+ assertisinstance(vert,Point2D),'Expected Point2D for OBJ ' \
+ 'vertex texture. Got {}.'.format(type(vert))
+ self._vertex_texture_map=value
+
+ @property
+ defvertex_normals(self):
+"""Get or set a tuple of Vector3D for vertex normals.
+
+ Will be None if no vertex normals are assigned.
+ """
+ returnself._vertex_normals
+
+ @vertex_normals.setter
+ defvertex_normals(self,value):
+ ifvalueisnotNone:
+ assertisinstance(value,(list,tuple)), \
+ 'vertex_normals should be a list or tuple. Got {}'.format(type(value))
+ ifisinstance(value,list):
+ value=tuple(value)
+ iflen(value)==0:
+ value=None
+ eliflen(value)!=len(self.vertices):
+ raiseValueError(
+ 'Number of OBJ vertex_normals ({}) does not match the number of'
+ ' OBJ vertices ({}).'.format(len(value),len(self.vertices)))
+ else:
+ fornorminvalue:
+ assertisinstance(norm,Vector3D),'Expected Vector3D for OBJ ' \
+ 'vertex normal. Got {}.'.format(type(norm))
+ self._vertex_normals=value
+
+ @property
+ defvertex_colors(self):
+"""Get or set a list of colors for the OBJ. Will be None if no colors assigned.
+ """
+ returnself._vertex_colors
+
+ @vertex_colors.setter
+ defvertex_colors(self,value):
+ ifvalueisnotNone:
+ assertisinstance(value,(list,tuple)), \
+ 'vertex_normals should be a list or tuple. Got {}'.format(type(value))
+ ifisinstance(value,list):
+ value=tuple(value)
+ iflen(value)==0:
+ value=None
+ eliflen(value)!=len(self.vertices):
+ raiseValueError(
+ 'Number of OBJ vertex_normals ({}) does not match the number of'
+ ' OBJ vertices ({}).'.format(len(value),len(self.vertices)))
+ self._vertex_colors=value
+
+ @property
+ defmaterial_structure(self):
+"""Get or set a tuple of tuples that specify the material structure of the obj.
+
+ Each sub-tuple contains two elements. The first is the identifier of a
+ material that is used in the OBJ and the second is the index of the face
+ where the application of the new material begins. If None, everything
+ will be assumed to have the same diffuse material.
+ """
+ returnself._material_structure
+
+ @material_structure.setter
+ defmaterial_structure(self,value):
+ ifvalueisnotNone:
+ assertisinstance(value,(list,tuple)), \
+ 'vertex_normals should be a list or tuple. Got {}'.format(type(value))
+ iflen(value)==0:
+ value=None
+ else:
+ formtinvalue:
+ assertisinstance(mt,tuple),'Expected tuple for OBJ material ' \
+ 'structure. Got {}.'.format(type(mt))
+ assertlen(mt)==2,'OBJ material structure must have 2 items. ' \
+ 'Got {}.'.format(len(mt))
+ assertisinstance(mt[0],str),'Expected String for OBJ material ' \
+ 'identifier. Got {}.'.format(type(mt[0]))
+ try:
+ self._faces[mt[1]]
+ exceptIndexError:
+ raiseIndexError(
+ 'OBJ material index {} does not correspond to any face. '
+ 'There are {} faces in the mesh.'.format(
+ mt[1],len(self._faces)))
+ exceptTypeError:
+ raiseTypeError(
+ 'OBJ material must use integers to reference faces. '
+ 'Got {}.'.format(type(mt[1])))
+ value=sorted(value,key=lambdax:x[1])
+ value=tuple(value)
+ self._material_structure=value
+
+
+[docs]
+ defto_file(self,folder,name,triangulate_quads=False,include_mtl=False):
+"""Write the OBJ object to an ASCII text file.
+
+ Args:
+ folder: A text string for the directory where the OBJ will be written.
+ name: A text string for the name of the OBJ file. Note that, if an image
+ texture is meant to be assigned to this OBJ, the image should have
+ the same name as the one input here except with the .mtl extension
+ instead of the .obj extension.
+ triangulate_quads: Boolean to note whether quad faces should be
+ triangulated upon export to OBJ. This may be needed for certain
+ software platforms that require the mesh to be composed entirely
+ of triangles (eg. Radiance). (Default: False).
+ include_mtl: Boolean to note whether an .mtl file should be automatically
+ generated from the material structure written next to the .obj
+ file in the output folder. All materials in the mtl file will
+ be diffuse white, with the assumption that these will be
+ customized later. (Default: False).
+ """
+ # set up a name and folder
+ file_name=nameifname.lower().endswith('.obj')else'{}.obj'.format(name)
+ obj_file=os.path.join(folder,file_name)
+ mtl_file='{}.mtl'.format(name)ifnotname.lower().endswith('.obj')else \
+ '{}.mtl'.format(name[:-4])
+
+ # write everything into the OBJ file
+ withopen(obj_file,writemode)asoutfile:
+ # add a comment at the top to note where the OBJ is written from
+ outfile.write('# OBJ file written by ladybug geometry\n\n')
+
+ # add material file name if include_mtl is true
+ ifself._material_structureisnotNoneorinclude_mtl:
+ ifinclude_mtl:
+ outfile.write('mtllib '+mtl_file+'\n')
+ ifself._material_structureisNone:
+ outfile.write('usemtl diffuse_0\n')
+
+ # loop through the vertices and add them to the file
+ ifself.vertex_colorsisNone:
+ forvinself.vertices:
+ outfile.write('v {}{}{}\n'.format(v.x,v.y,v.z))
+ else:# write the vertex colors alongside the vertices
+ iflen(self.vertex_colors[0])>3:
+ forv,cinzip(self.vertices,self.vertex_colors):
+ outfile.write(
+ 'v {}{}{}{}{}{}\n'.format(
+ v.x,v.y,v.z,c[0],c[1],c[2])
+ )
+ else:# might be a grayscale weight
+ forv,cinzip(self.vertices,self.vertex_colors):
+ outfile.write(
+ 'v {}{}{}{}\n'.format(v.x,v.y,v.z,' '.join(c))
+ )
+
+ # loop through the texture vertices, if present, and add them to the file
+ ifself.vertex_texture_mapisnotNone:
+ forvtinself.vertex_texture_map:
+ outfile.write('vt {}{}\n'.format(vt.x,vt.y))
+
+ # loop through the normals, if present, and add them to the file
+ ifself.vertex_normalsisnotNone:
+ forvninself.vertex_normals:
+ outfile.write('vn {}{}{}\n'.format(vn.x,vn.y,vn.z))
+
+ # triangulate the faces if requested
+ formatted_faces,formatted_mats=self.faces,self.material_structure
+ iftriangulate_quads:
+ formatted_faces=[]
+ ifformatted_matsisNoneorlen(formatted_mats)==1:
+ forfinself.faces:
+ iflen(f)>3:
+ formatted_faces.append((f[0],f[1],f[2]))
+ formatted_faces.append((f[2],f[3],f[0]))
+ else:
+ formatted_faces.append(f)
+ else:
+ mat_ind=[mat[1]formatinformatted_mats]
+ fori,finenumerate(self.faces):
+ iflen(f)>3:
+ formatted_faces.append((f[0],f[1],f[2]))
+ formatted_faces.append((f[2],f[3],f[0]))
+ forj,minenumerate(formatted_mats):
+ ifm[1]>i:
+ mat_ind[j]=mat_ind[j]+1
+ else:
+ formatted_faces.append(f)
+ formatted_mats= \
+ [(mn[0],mi)formn,miinzip(formatted_mats,mat_ind)]
+
+ # loop through the faces and get all lines of text for them
+ face_txt=[]
+ ifself.vertex_texture_mapisNoneandself.vertex_normalsisNone:
+ forfinformatted_faces:
+ face_txt.append('f '+' '.join(str(fi+1)forfiinf)+'\n')
+ else:
+ ifself.vertex_texture_mapisnotNoneand \
+ self.vertex_normalsisnotNone:
+ f_map='{0}/{0}/{0}'
+ elifself.vertex_texture_mapisNoneand \
+ self.vertex_normalsisnotNone:
+ f_map='{0}//{0}'
+ else:
+ f_map='{0}/{0}'
+ forfinformatted_faces:
+ face_txt.append(
+ 'f '+' '.join(f_map.format(fi+1)forfiinf)+'\n'
+ )
+
+ # write the faces into the file with the material structure
+ ifformatted_matsisnotNone:# insert the materials
+ formatinreversed(formatted_mats):
+ face_txt.insert(mat[1],'usemtl {}\n'.format(mat[0]))
+ forf_lininface_txt:
+ outfile.write(f_lin)
+
+ # write the MTL file if requested
+ ifinclude_mtl:
+ mat_struct=[('diffuse_0',0)]ifself._material_structureisNoneelse \
+ self._material_structure
+ mtl_fp=os.path.join(folder,mtl_file)
+ withopen(mtl_fp,writemode)asmtl_f:
+ mtl_f.write('# Ladybug Geometry\n')
+ formatinreversed(mat_struct):
+ mtl_str= \
+ 'newmtl {}\n' \
+ 'Ka 0.0000 0.0000 0.0000\n' \
+ 'Kd 1.0000 1.0000 1.0000\n' \
+ 'Ks 0.0000 0.0000 0.0000\n' \
+ 'Tf 0.0000 0.0000 0.0000\n' \
+ 'd 1.0000\n' \
+ 'Ns 0.0000\n'.format(mat[0])
+ mtl_f.write(mtl_str)
+
+ returnobj_file
+
+
+ def_check_vertices_input(self,vertices):
+"""Check the input vertices."""
+ ifnotisinstance(vertices,tuple):
+ vertices=tuple(vertices)
+ forvertinvertices:
+ assertisinstance(vert,Point3D), \
+ 'Expected Point3D for OBJ vertex. Got {}.'.format(type(vert))
+ returnvertices
+
+ def_check_faces_input(self,faces):
+"""Check input faces for correct formatting."""
+ ifnotisinstance(faces,tuple):
+ faces=tuple(faces)
+ assertlen(faces)>0,'OBJ mesh must have at least one face.'
+ forfinfaces:
+ assertisinstance(f,tuple), \
+ 'Expected tuple for Mesh face. Got {}.'.format(type(f))
+ assertlen(f)>=3, \
+ 'OBJ mesh face must have 3 or more vertices. Got {}.'.format(len(f))
+ forindinf:
+ try:
+ self._vertices[ind]
+ exceptIndexError:
+ raiseIndexError(
+ 'mesh face index {} does not correspond to any vertex. There '
+ 'are {} vertices in the mesh.'.format(ind,len(self._vertices)))
+ exceptTypeError:
+ raiseTypeError(
+ 'Mesh face must use integers to reference vertices. '
+ 'Got {}.'.format(type(ind)))
+ returnfaces
+
+ def__len__(self):
+ returnlen(self._vertices)
+
+ def__getitem__(self,key):
+ returnself._vertices[key]
+
+ def__iter__(self):
+ returniter(self._vertices)
+
+ def__repr__(self):
+ return'OBJ ({} vertices) ({} faces)'.format(
+ len(self._vertices),len(self._faces))
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/_modules/ladybug_geometry/interop/stl.html b/docs/_modules/ladybug_geometry/interop/stl.html
new file mode 100644
index 00000000..67646d6e
--- /dev/null
+++ b/docs/_modules/ladybug_geometry/interop/stl.html
@@ -0,0 +1,1476 @@
+
+
+
+
+
+
+ ladybug_geometry.interop.stl — ladybug geometry documentation
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+# coding=utf-8
+"""A class that supports the import and export of STL data to/from ladybug_geometry.
+
+The methods in the object below are inspired from pySTL module.
+
+[1] Daniel Balzerson. 2013. pySTL - Python code for working with .STL
+(sterolithography) files. https://github.com/proverbialsunrise/pySTL
+"""
+importos
+importstruct
+importre
+
+try:
+ fromitertoolsimportizipaszip# python 2
+ writemode='wb'
+exceptImportError:
+ writemode='w'# python 3
+
+fromladybug_geometry.geometry3d.pointvectorimportVector3D,Point3D
+
+
+
+[docs]
+classSTL(object):
+"""A class that supports the import and export of STL data to/from ladybug_geometry.
+
+ Args:
+ face_vertices: A list of tuples where each tuple is a triangular face
+ of three Point3Ds.
+ face_normals: A list of Vector3Ds for the normals of the faces in the STL.
+ name: Text string for the name of the solid object in the STL
+ file. (Default: polyhedron).
+
+ Properties:
+ * name
+ * face_vertices
+ * face_normals
+ """
+
+ __slots__=('_name','_face_vertices','_face_normals')
+
+ def__init__(self,face_vertices,face_normals,name='polyhedron'):
+ self.name=name
+ self._face_normals=None# bypass check on first time
+ self.face_vertices=face_vertices
+ self.face_normals=face_normals
+
+
+[docs]
+ @classmethod
+ deffrom_file(cls,file_path):
+"""Create an STL object from a .stl file.
+
+ Args:
+ file_path: Path to an STL file as a text string. The STL file can be
+ in either ASCII or binary format.
+ """
+ face_vertices,face_normals,name=cls._load_stl(file_path)
+ returncls(face_vertices,face_normals,name)
+
+
+
+[docs]
+ @classmethod
+ deffrom_mesh3d(cls,mesh,name='polyhedron'):
+"""Create an STL object from a ladybug_geometry Mesh3D object.
+
+ All quad faces will be automatically triangulated by using this method.
+
+ Args:
+ mesh: A ladybug_geometry Mesh3D object to be converted to an OBJ object.
+ name: Text string for the name of the solid object in the STL
+ file. (Default: polyhedron).
+ """
+ face_vertices,face_normals=[],[]
+ forf,fninzip(mesh.faces,mesh.face_normals):
+ iflen(f)==3:
+ face_vertices.append(tuple(mesh._vertices[i]foriinf))
+ face_normals.append(fn)
+ else:# it's a quad mesh to be triangulated
+ vts1=(mesh._vertices[f[0]],mesh._vertices[f[1]],mesh._vertices[f[2]])
+ vts2=(mesh._vertices[f[2]],mesh._vertices[f[3]],mesh._vertices[f[0]])
+ face_vertices.append(vts1)
+ face_vertices.append(vts2)
+ face_normals.append(fn)
+ face_normals.append(fn)
+ returncls(face_vertices,face_normals,name)
+
+
+ @property
+ defname(self):
+"""Get the name of the solid object in the STL file."""
+ returnself._name
+
+ @name.setter
+ defname(self,value):
+ input_name='STL object name'
+ try:
+ non_ascii=tuple(iforiinvalueiford(i)>=128)
+ exceptTypeError:
+ raiseTypeError('Input {} must be a text string. Got {}: {}.'.format(
+ input_name,type(value),value))
+ assertnon_ascii==(),'Illegal characters {} found in {}'.format(
+ non_ascii,input_name)
+ illegal_match=re.search(r'[,;!\n\t]',value)
+ assertillegal_matchisNone,'Illegal character "{}" found in {}'.format(
+ illegal_match.group(0),input_name)
+ assertlen(value)>0,'Input {} "{}" contains no characters.'.format(
+ input_name,value)
+ assertlen(value)<=80,'Input {} "{}" must be less than 80 characters.'.format(
+ input_name,value)
+ self._name=value
+
+ @property
+ defface_vertices(self):
+"""Get a list of tuples where each tuple is a triangular face of three Point3Ds.
+ """
+ returnself._face_vertices
+
+ @face_vertices.setter
+ defface_vertices(self,val):
+ assertisinstance(val,(list,tuple)), \
+ 'face_vertices should be a list or tuple. Got {}'.format(type(val))
+ ifisinstance(val,list):
+ val=tuple(val)
+ forfinval:
+ assertlen(f)==3,'All face_vertices of an STL must be triangles. ' \
+ 'Got face of length {}.'.format(len(f))
+ self._face_vertices=val
+ self._check_faces_match()
+
+ @property
+ defface_normals(self):
+"""Get a list of Vector3Ds for the normals of the faces in the STL."""
+ returnself._face_normals
+
+ @face_normals.setter
+ defface_normals(self,val):
+ assertisinstance(val,(list,tuple)), \
+ 'face_normals should be a list or tuple. Got {}'.format(type(val))
+ ifisinstance(val,list):
+ val=tuple(val)
+ self._face_normals=val
+ self._check_faces_match()
+
+
+[docs]
+ defto_file(self,folder,name=None):
+"""Write the STL object to an ASCII STL file.
+
+ Args:
+ folder: A text string for the directory where the STL will be written.
+ name: A text string for the name of the STL file. If None, the name
+ of the STL object will be used. (Default: None).
+ """
+ # set up a name and folder
+ ifnameisNone:
+ name=self.name
+ file_name=nameifname.lower().endswith('.stl')else'{}.stl'.format(name)
+ stl_file=os.path.join(folder,file_name)
+ # loop through the faces and normals to write them to the file
+ withopen(stl_file,writemode)asfp:
+ fp.write('solid {:s}\n'.format(self.name))
+ forfacet,nminzip(self.face_vertices,self.face_normals):
+ fp.write(
+ ' facet normal {0:.6E}{1:.6E}{2:.6E}\n'.format(nm.x,nm.y,nm.z)
+ )
+ fp.write(' outer loop\n')
+ forptinfacet:
+ fp.write(
+ ' vertex {0:.6E}{1:.6E}{2:.6E}\n'.format(pt.x,pt.y,pt.z)
+ )
+ fp.write(' endloop\n')
+ fp.write(' endfacet\n')
+ fp.write('endsolid {:s}\n'.format(self.name))
+ returnstl_file
+
+
+ def_check_faces_match(self):
+ ifself._face_normalsisnotNone:
+ assertlen(self._face_vertices)==len(self._face_normals), \
+ 'Number of STL face_vertices ({}) does not match the number ' \
+ 'of _face_normals ({}).'.format(
+ len(self._face_vertices),len(self._face_normals))
+
+ @staticmethod
+ def_load_stl(file_path):
+"""Load data from an STL file.
+
+ Args:
+ file_path: Path to an STL file as a text string. The STL file can be
+ in either ASCII or binary format.
+
+ Returns:
+ A tuple with three elements.
+
+ - face_vertices:
+ A list of tuples where each tuple is a triangular face of three Point3Ds.
+
+ - face_normals:
+ A list of Vector3Ds for the normals of the faces in the STL.
+
+ - name:
+ Text string for the name of the STL object
+ """
+ # check the first bytes of the file to determine whether it's ASCII or binary
+ assertos.path.isfile(file_path),'Failed to find %s'%file_path
+ withopen(file_path,'rb')asfp:
+ header=fp.read(80)# 80 characters should have the full name
+ first_word=header[0:5]
+ # load the STL data depending on whether it is ASCII or binary
+ iffirst_word.decode('utf-8')=='solid':
+ returnSTL._load_text_stl(file_path)
+ else:
+ returnSTL._load_binary_stl(file_path)
+
+ @staticmethod
+ def_load_text_stl(file_path):
+"""Read text stl file and extract triangular faces."""
+ _face_vertices,_face_normals,_name=[],[],'polyhedron'
+ withopen(file_path,'r')asfp:
+ forlineinfp:
+ words=line.split()
+ iflen(words)>0:
+ first_word=words[0]
+ iffirst_word=='facet':# start of a new face
+ vertices=[]
+ norm=Vector3D(
+ float(words[2]),float(words[3]),float(words[4])
+ )
+ _face_normals.append(norm)
+ eliffirst_word=='vertex':# vertex of a face
+ vertices.append(
+ Point3D(float(words[1]),float(words[2]),float(words[3]))
+ )
+ eliffirst_word=='endloop':# end of a face
+ _face_vertices.append(tuple(vertices))
+ eliffirst_word=='solid':# very start of the file
+ try:
+ _name=words[1]
+ exceptIndexError:# no name assigned; leave the default one
+ pass
+ return_face_vertices,_face_normals,_name
+
+ @staticmethod
+ def_load_binary_stl(file_path):
+"""Read binary stl file and extract triangular faces."""
+ _face_vertices,_face_normals,_name=[],[],'polyhedron'
+ withopen(file_path,'rb')asfp:
+ # interpret the 80-character header as the name of the object
+ _name=fp.read(80).decode('utf-8').strip()
+ # ignore the total face count in the first 4 characters
+ struct.unpack('I',fp.read(4))[0]
+
+ # loop through the file contents and load all vertices and vectors
+ count=0
+ whileTrue:
+ try:
+ # read the face normal
+ p=fp.read(12)
+ iflen(p)==12:
+ norm=Vector3D(
+ struct.unpack('f',p[0:4])[0],
+ struct.unpack('f',p[4:8])[0],
+ struct.unpack('f',p[8:12])[0]
+ )
+ else:
+ break
+ # read the first vertex
+ p=fp.read(12)
+ iflen(p)==12:
+ p1=Point3D(
+ struct.unpack('f',p[0:4])[0],
+ struct.unpack('f',p[4:8])[0],
+ struct.unpack('f',p[8:12])[0]
+ )
+ else:
+ break
+ # read the second vertex
+ p=fp.read(12)
+ iflen(p)==12:
+ p2=Point3D(
+ struct.unpack('f',p[0:4])[0],
+ struct.unpack('f',p[4:8])[0],
+ struct.unpack('f',p[8:12])[0]
+ )
+ else:
+ break
+ # read the third vertex
+ p=fp.read(12)
+ iflen(p)==12:
+ p3=Point3D(
+ struct.unpack('f',p[0:4])[0],
+ struct.unpack('f',p[4:8])[0],
+ struct.unpack('f',p[8:12])[0]
+ )
+ else:
+ break
+ # add the triangle to the face vertices
+ _face_vertices.append((p1,p2,p3))
+ _face_normals.append(norm)
+ count+=1
+ fp.read(2)
+
+ iflen(p)==0:
+ break# no more points to read
+ exceptEOFError:
+ break# we have reached the end of the file
+ return_face_vertices,_face_normals,_name
+
+ def__len__(self):
+ returnlen(self._face_vertices)
+
+ def__getitem__(self,key):
+ returnself._face_vertices[key]
+
+ def__iter__(self):
+ returniter(self._face_vertices)
+
+ def__repr__(self):
+ return'STL ({} faces)'.format(len(self._face_vertices))
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/_modules/ladybug_geometry/intersection2d.html b/docs/_modules/ladybug_geometry/intersection2d.html
new file mode 100644
index 00000000..5781ca87
--- /dev/null
+++ b/docs/_modules/ladybug_geometry/intersection2d.html
@@ -0,0 +1,1560 @@
+
+
+
+
+
+
+ ladybug_geometry.intersection2d — ladybug geometry documentation
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+# coding=utf-8
+"""Utility functions for computing intersections between geometry in 2D space.
+
+Taken mostly from the euclid package available at
+https://pypi.org/project/euclid/
+"""
+from__future__importdivision
+importmath
+
+from.geometry2d.pointvectorimportPoint2D,Vector2D
+
+
+def_isclose(a,b,rel_tol=1e-09,abs_tol=1e-09):
+"""Implementation of the math.isclose method from Python 3.5 onward."""
+ returnabs(a-b)<=max(rel_tol*max(abs(a),abs(b)),abs_tol)
+
+
+
+[docs]
+defintersect_line2d(line_ray_a,line_ray_b):
+"""Get the intersection between any Ray2D or LineSegment2D objects as a Point2D.
+
+ This function calculates scaling parameters for ua and ub where:
+ A.p + ua * A.v = B.p + ub * B.v
+ Which represents the intersection point between line A and line B.
+
+ The derivation of ua is achieved by crossing both sides of the above equation
+ with the direction vector of B, and rearranging the formula:
+
+ .. code-block:: python
+
+ A.p + ua * A.v = B.p + ub * B.v
+ (A.p + ua * A.v) x B.v = (B.p + ub * B.v) x B.v # Cross both sides with B.v
+ (A.p x B.v) + (ua * A.v x B.v) = (B.p x B.v) + (ub * B.v x B.v) # B.v x B.v = 0
+ ua = (B.p - A.p) x B.v / (A.v x B.v)
+
+ Args:
+ line_ray_a: A LineSegment2D or Ray2D object.
+ line_ray_b: Another LineSegment2D or Ray2D to intersect.
+
+ Returns:
+ Point2D of intersection if it exists. None if no intersection exists.
+ """
+ # d is the determinant between lines, if 0 lines are collinear
+ d=line_ray_b.v.y*line_ray_a.v.x-line_ray_b.v.x*line_ray_a.v.y
+ ifd==0:
+ returnNone
+
+ # (dx, dy) = A.p - B.p
+ dy=line_ray_a.p.y-line_ray_b.p.y
+ dx=line_ray_a.p.x-line_ray_b.p.x
+
+ # Find parameters ua and ub for intersection between two lines
+
+ # Calculate scaling parameter for line_ray_b
+ ua=(line_ray_b.v.x*dy-line_ray_b.v.y*dx)/d
+ # Checks the bounds of ua to ensure it obeys ray/line behavior
+ ifnotline_ray_a._u_in(ua):
+ returnNone
+
+ # Calculate scaling parameter for line_ray_b
+ ub=(line_ray_a.v.x*dy-line_ray_a.v.y*dx)/d
+ # Checks the bounds of ub to ensure it obeys ray/line behavior
+ ifnotline_ray_b._u_in(ub):
+ returnNone
+
+ returnPoint2D(line_ray_a.p.x+ua*line_ray_a.v.x,
+ line_ray_a.p.y+ua*line_ray_a.v.y)
+
+
+
+
+[docs]
+defintersect_line_segment2d(line_a,line_b):
+"""Get the intersection between two LineSegment2D objects as a Point2D.
+
+ This function is identical to intersect_line2d but has some extra checks to
+ avoid certain cases of floating point tolerance issues. It is only intended
+ to work with LineSegment2D and not Ray2D.
+
+ Args:
+ line_a: A LineSegment2D object.
+ line_b: Another LineSegment2D intersect.
+
+ Returns:
+ Point2D of intersection if it exists. None if no intersection exists.
+ """
+ # d is the determinant between lines, if 0 lines are collinear
+ d=line_b.v.y*line_a.v.x-line_b.v.x*line_a.v.y
+ ifd==0:
+ returnNone
+
+ # (dx, dy) = A.p - B.p
+ dy=line_a.p.y-line_b.p.y
+ dx=line_a.p.x-line_b.p.x
+
+ # Find parameters ua and ub for intersection between two lines
+
+ # Calculate scaling parameter for line_b
+ ua=(line_b.v.x*dy-line_b.v.y*dx)/d
+ # Checks the bounds of ua to ensure it obeys ray/line behavior
+ ifnotline_a._u_in(ua):
+ returnNone
+
+ # Calculate scaling parameter for line_b
+ ub=(line_a.v.x*dy-line_a.v.y*dx)/d
+ # Checks the bounds of ub to ensure it obeys ray/line behavior
+ ifnotline_b._u_in(ub):
+ returnNone
+
+ # compute the intersection point
+ int_pta=Point2D(line_a.p.x+ua*line_a.v.x,line_a.p.y+ua*line_a.v.y)
+ int_ptb=Point2D(line_b.p.x+ub*line_b.v.x,line_b.p.y+ub*line_b.v.y)
+
+ # if the two points are unequal, there's a floating point tolerance issue
+ if_isclose(int_pta.x,int_ptb.x)and_isclose(int_pta.y,int_ptb.y):
+ returnint_pta
+ returnNone
+
+
+
+
+[docs]
+defintersect_line2d_infinite(line_ray_a,line_ray_b):
+"""Get intersection between a Ray2D/LineSegment2D and another extended infinitely.
+
+ Args:
+ line_ray_a: A LineSegment2D or Ray2D object.
+ line_ray_b: A LineSegment2D or Ray2D that will be extended infinitely
+ for intersection.
+
+ Returns:
+ Point2D of intersection if it exists. None if no intersection exists.
+ """
+ d=line_ray_b.v.y*line_ray_a.v.x-line_ray_b.v.x*line_ray_a.v.y
+ ifd==0:
+ returnNone
+ dy=line_ray_a.p.y-line_ray_b.p.y
+ dx=line_ray_a.p.x-line_ray_b.p.x
+ ua=(line_ray_b.v.x*dy-line_ray_b.v.y*dx)/d
+ ifnotline_ray_a._u_in(ua):
+ returnNone
+ returnPoint2D(line_ray_a.p.x+ua*line_ray_a.v.x,
+ line_ray_a.p.y+ua*line_ray_a.v.y)
+
+
+
+
+[docs]
+defdoes_intersection_exist_line2d(line_ray_a,line_ray_b):
+"""Boolean denoting whether an intersection exists between Ray2D or LineSegment2D.
+
+ This is slightly faster than actually computing the intersection but should only be
+ used in cases where the actual point of intersection is not needed.
+
+ Args:
+ line_ray_a: A LineSegment2D or Ray2D object.
+ line_ray_b: Another LineSegment2D or Ray2D to intersect.
+
+ Returns:
+ True if an intersection exists. False if no intersection exists.
+ """
+ d=line_ray_b.v.y*line_ray_a.v.x-line_ray_b.v.x*line_ray_a.v.y
+ ifd==0:
+ returnFalse
+ dy=line_ray_a.p.y-line_ray_b.p.y
+ dx=line_ray_a.p.x-line_ray_b.p.x
+ ua=(line_ray_b.v.x*dy-line_ray_b.v.y*dx)/d
+ ifnotline_ray_a._u_in(ua):
+ returnFalse
+ ub=(line_ray_a.v.x*dy-line_ray_a.v.y*dx)/d
+ ifnotline_ray_b._u_in(ub):
+ returnFalse
+ returnTrue
+
+
+
+
+[docs]
+defintersect_line2d_arc2d(line_ray,arc):
+"""Get the intersection between any Ray2D/LineSegment2D and an Arc2D.
+
+ Args:
+ line_ray: A LineSegment2D or Ray2D object.
+ arc: An Arc2D object along which the closest point will be determined.
+
+ Returns:
+ A list of 2 Point2D objects if a full intersection exists.
+ A list with a single Point2D object if the line is tangent or intersects
+ only once. None if no intersection exists.
+ """
+ a=line_ray.v.magnitude_squared
+ b=2*(line_ray.v.x*(line_ray.p.x-arc.c.x)+
+ line_ray.v.y*(line_ray.p.y-arc.c.y))
+ c=arc.c.magnitude_squared+line_ray.p.magnitude_squared- \
+ 2*arc.c.dot(line_ray.p)-arc.r**2
+ det=b**2-4*a*c
+ ifdet<0:
+ returnNone
+ sq=math.sqrt(det)
+ u1=(-b+sq)/(2*a)
+ u2=(-b-sq)/(2*a)
+ pt1=Point2D(line_ray.p.x+u1*line_ray.v.x,
+ line_ray.p.y+u1*line_ray.v.y)ifline_ray._u_in(u1)elseNone
+ pt2=Point2D(line_ray.p.x+u2*line_ray.v.x,
+ line_ray.p.y+u2*line_ray.v.y)ifline_ray._u_in(u2)elseNone
+
+ ifu1==u2:# Tangent
+ pt=Point2D(line_ray.p.x+u1*line_ray.v.x,
+ line_ray.p.y+u1*line_ray.v.y)
+ returnptifarc._pt_in(pt)elseNone
+
+ pts=[pforpin(pt1,pt2)ifpisnotNoneandarc._pt_in(p)]
+ returnptsiflen(pts)!=0elseNone
+
+
+
+
+[docs]
+defintersect_line2d_infinite_arc2d(line_ray,arc):
+"""Get intersection between an Arc2D and a Ray2D/LineSegment2D extended infinitely.
+
+ Args:
+ line_ray: A LineSegment2D or Ray2D that will be extended infinitely
+ for intersection.
+ arc: An Arc2D object along which the closest point will be determined.
+
+ Returns:
+ A list of 2 Point2D objects if a full intersection exists.
+ A list with a single Point2D object if the line is tangent or intersects
+ only once. None if no intersection exists.
+ """
+ a=line_ray.v.magnitude_squared
+ b=2*(line_ray.v.x*(line_ray.p.x-arc.c.x)+
+ line_ray.v.y*(line_ray.p.y-arc.c.y))
+ c=arc.c.magnitude_squared+line_ray.p.magnitude_squared- \
+ 2*arc.c.dot(line_ray.p)-arc.r**2
+ det=b**2-4*a*c
+ ifdet<0:
+ returnNone
+ sq=math.sqrt(det)
+ u1=(-b+sq)/(2*a)
+ u2=(-b-sq)/(2*a)
+
+ ifu1==u2:# Tangent
+ pt=Point2D(line_ray.p.x+u1*line_ray.v.x,line_ray.p.y+u1*line_ray.v.y)
+ returnptifarc._pt_in(pt)elseNone
+
+ pt1=Point2D(line_ray.p.x+u1*line_ray.v.x,line_ray.p.y+u1*line_ray.v.y)
+ pt2=Point2D(line_ray.p.x+u2*line_ray.v.x,line_ray.p.y+u2*line_ray.v.y)
+ pts=[pforpin(pt1,pt2)ifarc._pt_in(p)]
+ returnptsiflen(pts)!=0elseNone
+
+
+
+
+[docs]
+defclosest_point2d_on_line2d(point,line_ray):
+"""Get the closest Point2D on a LineSegment2D or Ray2D to the input point.
+
+ Args:
+ point: A Point2D object.
+ line_ray: A LineSegment2D or Ray2D object along which the closest point
+ will be determined.
+
+ Returns:
+ Point2D for the closest point on the line_ray to point.
+ """
+ d=line_ray.v.magnitude_squared
+ ifd==0:# zero-length segment; just return the end point
+ returnline_ray.p
+ u=((point.x-line_ray.p.x)*line_ray.v.x+
+ (point.y-line_ray.p.y)*line_ray.v.y)/d
+ ifnotline_ray._u_in(u):
+ u=max(min(u,1.0),0.0)
+ returnPoint2D(line_ray.p.x+u*line_ray.v.x,line_ray.p.y+u*line_ray.v.y)
+
+
+
+
+[docs]
+defclosest_point2d_on_line2d_infinite(point,line_ray):
+"""Get the closest Point2D on a Ray2D/LineSegment2D extended infinitely.
+
+ Args:
+ point: A Point2D object.
+ line_ray: A LineSegment2D or Ray2D object that will be extended infinitely
+ to determine where the closest point lies.
+
+ Returns:
+ Point2D for the closest point on the line_ray to point.
+ """
+ d=line_ray.v.magnitude_squared
+ ifd==0:# zero-length segment; just return the end point
+ returnline_ray.p
+ u=((point.x-line_ray.p.x)*line_ray.v.x+
+ (point.y-line_ray.p.y)*line_ray.v.y)/d
+ returnPoint2D(line_ray.p.x+u*line_ray.v.x,line_ray.p.y+u*line_ray.v.y)
+
+
+
+
+[docs]
+defclosest_point2d_between_line2d(line_ray_a,line_ray_b):
+"""Get the two closest Point2D between two LineSegment2D objects.
+
+ When the closest point on one of the segments lies in the middle of the
+ segment, this will be accounted for. Also note that the line segments
+ should not intersect for the result to be valid.
+
+ Args:
+ line_ray_a: A LineSegment2D object.
+ line_ray_b: Another LineSegment2D to which closest points will
+ be determined.
+
+ Returns:
+ A tuple with two elements
+
+ - dists[0]: The distance between the two LineSegment2D objects.
+ - pts[0]: A tuple of two Point2D objects representing:
+
+ 1) The point on line_ray_a that is closest to line_ray_b
+ 2) The point on line_ray_b that is closest to line_ray_a
+ """
+ # one of the 4 endpoints must be a closest point
+ pt_1=closest_point2d_on_line2d(line_ray_a.p,line_ray_b)
+ dist_1=pt_1.distance_to_point(line_ray_a.p)
+ a_p2=line_ray_a.p2
+ pt_2=closest_point2d_on_line2d(a_p2,line_ray_b)
+ dist_2=pt_2.distance_to_point(a_p2)
+ pt_3=closest_point2d_on_line2d(line_ray_b.p,line_ray_a)
+ dist_3=pt_3.distance_to_point(line_ray_b.p)
+ b_p2=line_ray_b.p2
+ pt_4=closest_point2d_on_line2d(b_p2,line_ray_a)
+ dist_4=pt_4.distance_to_point(b_p2)
+
+ # sort the closest points based on their distance
+ dists=[dist_1,dist_2,dist_3,dist_4]
+ pts=[(line_ray_a.p,pt_1),(a_p2,pt_2),(pt_3,line_ray_b.p),(pt_4,b_p2)]
+ dists,i=zip(*sorted(zip(dists,range(len(pts)))))
+ returndists[0],pts[i[0]]
+
+
+
+
+[docs]
+defclosest_end_point2d_between_line2d(line_a,line_b):
+"""Get the two closest end Point2Ds between two LineSegment2D objects.
+
+ The result will always be composed of endpoints of the segments and will not
+ account for cases where the closest point lies in the middle of a segment.
+ For cases where such middle points are important, the
+ closest_point2d_between_line2d method should be used.
+
+ Args:
+ line_a: A LineSegment2D object.
+ line_b: Another LineSegment2D to which closest points will
+ be determined.
+
+ Returns:
+ A tuple with two elements
+
+ - dist: The distance between the two endpoints objects.
+ - pts: A tuple of two Point2D objects representing:
+
+ 1) The end point on line_a that is closest to line_b
+ 2) The end point on line_b that is closest to line_a
+ """
+ # one of the 4 endpoints must be a closest point
+ pts=[
+ (line_a.p1,line_b.p1),(line_a.p1,line_b.p2),
+ (line_a.p2,line_b.p1),(line_a.p2,line_b.p2)
+ ]
+ dists=[p1.distance_to_point(p2)forp1,p2inpts]
+ # sort the closest points based on their distance
+ dists,i=zip(*sorted(zip(dists,range(len(pts)))))
+ returndists[0],pts[i[0]]
+
+
+
+
+[docs]
+defclosest_point2d_on_arc2d(point,arc):
+"""Get the closest Point2D on a Arc2D to the input point.
+
+ Args:
+ point: A Point2D object.
+ arc: An Arc2D object along which the closest point will be determined.
+
+ Returns:
+ Point2D for the closest point on arc to point.
+ """
+ v=point-arc.c
+ v=v.normalize()*arc.r
+ ifarc.is_circle:
+ returnPoint2D(arc.c.x+v.x,arc.c.y+v.y)
+ else:
+ a=Vector2D(1,0).angle_counterclockwise(v)
+ if(notarc.is_invertedandarc.a1<a<arc.a2)or \
+ (arc.is_invertedandarc.a1>a>arc.a2):
+ returnPoint2D(arc.c.x+v.x,arc.c.y+v.y)
+ else:
+ ifarc.p1.distance_to_point(point)<=arc.p2.distance_to_point(point):
+ returnarc.p1
+ returnarc.p2
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/_modules/ladybug_geometry/intersection3d.html b/docs/_modules/ladybug_geometry/intersection3d.html
new file mode 100644
index 00000000..6325cc28
--- /dev/null
+++ b/docs/_modules/ladybug_geometry/intersection3d.html
@@ -0,0 +1,1426 @@
+
+
+
+
+
+
+ ladybug_geometry.intersection3d — ladybug geometry documentation
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+# coding=utf-8
+"""Utility functions for computing intersections between geometry in 3D space.
+
+Taken mostly from the euclid package available at
+https://pypi.org/project/euclid/
+"""
+from__future__importdivision
+
+from.geometry3d.pointvectorimportPoint3D
+
+importmath
+
+
+
+[docs]
+defintersect_line3d_plane(line_ray,plane):
+"""Get the intersection between a Ray3D/LineSegment3D and a Plane.
+
+ Args:
+ line_ray: A LineSegment3D or Ray3D object.
+ plane: A Plane object to intersect.
+
+ Returns:
+ Point3D of intersection if it exists. None if no intersection exists.
+ """
+ d=plane.n.dot(line_ray.v)
+ ifnotd:# parallel
+ returnNone
+ u=(plane.k-plane.n.dot(line_ray.p))/d
+ ifnotline_ray._u_in(u):# line or ray does not have its domain in the plane
+ returnNone
+ returnPoint3D(line_ray.p.x+u*line_ray.v.x,
+ line_ray.p.y+u*line_ray.v.y,
+ line_ray.p.z+u*line_ray.v.z)
+
+
+
+
+[docs]
+defintersect_line3d_plane_infinite(line_ray,plane):
+"""Get the intersection between a Plane and Ray2D/LineSegment2D extended infinitely.
+
+ Args:
+ line_ray: ALineSegment2D or Ray2D that will be extended infinitely
+ for intersection.
+ plane: A Plane object to intersect.
+
+ Returns:
+ Point3D of intersection if it exists. None if no intersection exists.
+ """
+ d=plane.n.dot(line_ray.v)
+ ifnotd:# parallel
+ returnNone
+ u=(plane.k-plane.n.dot(line_ray.p))/d
+ returnPoint3D(line_ray.p.x+u*line_ray.v.x,
+ line_ray.p.y+u*line_ray.v.y,
+ line_ray.p.z+u*line_ray.v.z)
+
+
+
+
+[docs]
+defintersect_plane_plane(plane_a,plane_b):
+"""Get the intersection between two Plane objects.
+
+ Args:
+ plane_a: A Plane object.
+ plane_b: Another Plane object to intersect.
+
+ Returns:
+ Two objects that define the intersection between two planes
+
+ 1) A Point3D that lies along the intersection of the two planes.
+ 2) A Vector3D that describes the direction of the intersection.
+
+ Will be None if no intersection exists (planes are parallel).
+ """
+ n1_m=plane_a.n.magnitude_squared
+ n2_m=plane_b.n.magnitude_squared
+ n1d2=plane_a.n.dot(plane_b.n)
+ det=n1_m*n2_m-n1d2**2
+ ifdet==0:# parallel
+ returnNone
+ c1=(plane_a.k*n2_m-plane_b.k*n1d2)/det
+ c2=(plane_b.k*n1_m-plane_a.k*n1d2)/det
+ returnPoint3D(c1*plane_a.n.x+c2*plane_b.n.x,
+ c1*plane_a.n.y+c2*plane_b.n.y,
+ c1*plane_a.n.z+c2*plane_b.n.z),plane_a.n.cross(plane_b.n)
+
+
+
+
+[docs]
+defclosest_point3d_on_line3d(point,line_ray):
+"""Get the closest Point3D on a LineSegment3D or Ray3D to the input point.
+
+ Args:
+ point: A Point3D object.
+ line_ray: A LineSegment3D or Ray3D object along which the closest point
+ will be determined.
+
+ Returns:
+ Point3D for the closest point on line_ray to point.
+ """
+ d=line_ray.v.magnitude_squared
+ ifd==0:# zero-length segment; just return the end point
+ returnline_ray.p
+ u=((point.x-line_ray.p.x)*line_ray.v.x+
+ (point.y-line_ray.p.y)*line_ray.v.y+
+ (point.z-line_ray.p.z)*line_ray.v.z)/d
+ ifnotline_ray._u_in(u):
+ u=max(min(u,1.0),0.0)
+ returnPoint3D(line_ray.p.x+u*line_ray.v.x,
+ line_ray.p.y+u*line_ray.v.y,
+ line_ray.p.z+u*line_ray.v.z)
+
+
+
+
+[docs]
+defclosest_point3d_on_line3d_infinite(point,line_ray):
+"""Get the closest Point3D on an infinite extension of a LineSegment3D or Ray3D.
+
+ Args:
+ point: A Point3D object.
+ line_ray: A LineSegment3D or Ray3D object along which the closest point
+ will be determined.
+
+ Returns:
+ Point3D for the closest point on the line_ray to the point.
+ """
+ d=line_ray.v.magnitude_squared
+ ifd==0:# zero-length segment; just return the end point
+ returnline_ray.p
+ u=((point.x-line_ray.p.x)*line_ray.v.x+
+ (point.y-line_ray.p.y)*line_ray.v.y+
+ (point.z-line_ray.p.z)*line_ray.v.z)/d
+ returnPoint3D(line_ray.p.x+u*line_ray.v.x,
+ line_ray.p.y+u*line_ray.v.y,
+ line_ray.p.z+u*line_ray.v.z)
+
+
+
+
+[docs]
+defclosest_point3d_on_plane(point,plane):
+"""Get the closest Point3D on a Plane to the input point.
+
+ Args:
+ point: A Point3D object.
+ plane: A Plane object in which the closest point will be determined.
+
+ Returns:
+ Point3D for the closest point on the plane to point.
+ """
+ n=plane.n
+ d=point.dot(plane.n)-plane.k
+ returnPoint3D(point.x-n.x*d,point.y-n.y*d,point.z-n.z*d)
+
+
+
+
+[docs]
+defclosest_point3d_between_line3d_plane(line_ray,plane):
+"""Get the two closest Point3D between a LineSegment3D/Ray3D and a Plane.
+
+ Args:
+ line_ray: A LineSegment3D or Ray3D object along which the closest point
+ will be determined.
+ plane: A Plane object on which a closest point will be determined.
+
+ Returns:
+ Two Point3D objects representing
+
+ 1) The point on the line_ray that is closest to the plane.
+ 2) The point on the plane that is closest to the line_ray.
+
+ Will be None if there is an intersection between line_ray and the plane
+ """
+ d=plane.n.dot(line_ray.v)
+ ifnotd:# parallel, choose an endpoint
+ returnline_ray.p,closest_point3d_on_plane(line_ray.p,plane)
+ u=(plane.k-plane.n.dot(line_ray.p))/d
+ ifnotline_ray._u_in(u):# intersects out of range of L, choose nearest endpoint
+ u=max(min(u,1.0),0.0)
+ close_pt=Point3D(line_ray.p.x+u*line_ray.v.x,
+ line_ray.p.y+u*line_ray.v.y,
+ line_ray.p.z+u*line_ray.v.z)
+ returnclose_pt,closest_point3d_on_plane(close_pt,plane)
+ returnNone# intersection
+
+
+
+
+[docs]
+defintersect_line3d_sphere(line_ray,sphere):
+"""Get the intersection between this Sphere object and a Ray2D/LineSegment2D.
+
+ Args:
+ line_ray: A LineSegment3D or Ray3D for intersection.
+ sphere: A Sphere to intersect.
+
+ Returns:
+ Two Point3D objects if a full intersection exists.
+ A Point3D if a point of tangency exists.
+ Will be None if no intersection exists.
+
+ """
+ L=line_ray
+ S=sphere
+ a=L.v.magnitude_squared
+ b=2*(L.v.x*(L.p.x-S.center.x)+
+ L.v.y*(L.p.y-S.center.y)+
+ L.v.z*(L.p.z-S.center.z))
+ c=S.center.magnitude_squared+ \
+ L.p.magnitude_squared- \
+ 2*S.center.dot(L.p)- \
+ S.radius**2
+ det=b**2-4*a*c
+ ifdet<0:
+ returnNone
+ sq=math.sqrt(det)
+ u1=(-b+sq)/(2*a)
+ u2=(-b-sq)/(2*a)
+ ifnotL._u_in(u1):
+ u1=max(min(u1,1.0),0.0)
+ ifnotL._u_in(u2):
+ u2=max(min(u2,1.0),0.0)
+ p1=Point3D(L.p.x+u1*L.v.x,L.p.y+u1*L.v.y,L.p.z+u1*L.v.z)
+ ifu1==u2:
+ returnp1
+ else:
+ p2=Point3D(L.p.x+u2*L.v.x,L.p.y+u2*L.v.y,L.p.z+u2*L.v.z)
+ returnp1,p2
+
+
+
+
+[docs]
+defintersect_plane_sphere(plane,sphere):
+"""Get the intersection of a plane with this Sphere object
+
+ Args:
+ plane: A Plane object.
+ sphere: A Sphere to intersect.
+
+ Returns:
+ If a full intersection exists
+
+ 1) A Point3D that represents the center of the intersection circle.
+ 2) A Vector3D that represents the normal of the intersection circle.
+ 3) A number that represents the radius of the intersection circle.
+
+ A Point3D Object if a point of tangency exists.
+ None if no intersection exists.
+ """
+ r=sphere.radius
+ pt_c=sphere.center
+ pt_o=plane.o
+ v_n=plane.n.normalize()
+
+ # Resulting circle radius. Radius² = r² - [(c-p).n]²
+ d=(pt_o-pt_c).dot(v_n)
+ ifabs(r)<abs(d):# No intersection if (r ** 2 - d ** 2) negative
+ returnNone
+ cut_r=math.sqrt(r**2-d**2)
+
+ # Intersection circle center point. Center_point = p - [(c-p).n]n
+ cut_center=pt_c+(d*v_n)
+
+ return(cut_center,v_n,cut_r)ifcut_r!=0elsecut_center
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/_modules/ladybug_geometry/network.html b/docs/_modules/ladybug_geometry/network.html
new file mode 100644
index 00000000..74d30cc8
--- /dev/null
+++ b/docs/_modules/ladybug_geometry/network.html
@@ -0,0 +1,2136 @@
+
+
+
+
+
+
+ ladybug_geometry.network — ladybug geometry documentation
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+# coding=utf-8
+"""A 2D Directed Graph Network data structure used for splitting polygons.
+
+A directed graph (or digraph) is a graph made up of a set of vertices (aka. nodes)
+connected by directed edges, often into a network where each node can have
+multiple connections.
+
+This class is used in all operations where a polygon or face is split using
+line segments or polylines.
+
+The overall strategies used in this module are inspired by operations performed by
+NetworkX but were constructed from scratch without working from any particular
+module or class in the package More information on NetworkX can be found here:
+https://github.com/networkx/networkx
+"""
+from__future__importdivision
+importmath
+
+fromladybug_geometry.intersection2dimportintersect_line_segment2d
+fromladybug_geometry.geometry2dimportLineSegment2D
+
+
+
+[docs]
+defcoordinates_hash(point,tolerance):
+"""Convert XY coordinates of a Point2D into a string useful for hashing.
+
+ Points that are co-located within the tolerance will receive the same string value
+ from this function, which helps convert line segments that contain duplicated
+ vertex references them into a singular network object where co-located vertices
+ are referenced only once.
+
+ Args:
+ point: A Point2D object.
+ tolerance: floating point precision tolerance.
+
+ Returns:
+ A string of rounded coordinates.
+ """
+ # get the relative tolerance using a log function
+ try:
+ rtol=int(math.log10(tolerance))*-1
+ exceptValueError:
+ rtol=0# the tol is equal to 1 (out of range for log)
+ # account for the fact that the tolerance may not be base 10
+ base=int(tolerance*10**(rtol+1))
+ ifbase==10orbase==0:# tolerance is base 10 (eg. 0.001)
+ base=1
+ else:# tolerance is not base 10 (eg. 0.003)
+ rtol+=1
+ # avoid cases of signed zeros messing with the hash
+ z_tol=tolerance/2
+ x_val=0.0ifabs(point.x)<z_tolelsepoint.x
+ y_val=0.0ifabs(point.y)<z_tolelsepoint.y
+ # convert the coordinate values to a hash
+ returnstr((
+ base*round(x_val/base,rtol),
+ base*round(y_val/base,rtol)
+ ))
+
+
+
+
+[docs]
+classNode(object):
+"""A Node within in DirectedGraphNetwork, optionally connected to other Nodes.
+
+ Args:
+ pt: A Point2D object for the node
+ key: String representation of the Point2D object which accounts for tolerance.
+ order: Integer for the order of the Node (based on directed graph propagation).
+ adj_lst: List of Node objects that are adjacent to this node.
+ exterior: Optional boolean to indicate if the Node is on the exterior of
+ the graph. If None, this value can be computed later based on the
+ position within the overall graph.
+
+ Properties:
+ * pt
+ * key
+ * adj_lst
+ * exterior
+ * adj_count
+ """
+ __slots__=('key','pt','_order','adj_lst','exterior')
+
+ def__init__(self,pt,key,order,adj_lst,exterior=None):
+"""Initialize Node."""
+ self.pt=pt
+ self.key=key
+ self._order=order
+ self.adj_lst=adj_lst
+ self.exterior=exterior
+
+ @property
+ defadj_count(self):
+"""Number of adjacent nodes"""
+ returnlen(self.adj_lst)
+
+ def__hash__(self):
+ returnhash(self.key)
+
+ def__eq__(self,other):
+ returnisinstance(other,Node)and \
+ self.key==other.key
+
+ def__ne__(self,other):
+ returnnotself.__eq__(other)
+
+ def__repr__(self):
+ return'{}: {}'.format(self._order,self.key)
+
+
+
+
+[docs]
+classDirectedGraphNetwork(object):
+"""A 2D Directed Graph Network data structure used for splitting polygons.
+
+ A directed graph (or digraph) is a graph made up of a set of vertices (aka. nodes)
+ connected by directed edges, often into a network where each node can have
+ multiple connections. This class contains for finding the shortest pathways
+ through the graph. It also helps differentiate interior from exterior parts
+ of the graph. Typically, interior pathways are bi-directional in the graph
+ while exterior pathways are uni-directional.
+
+ Args:
+ tolerance: The tolerance used to determine point equivalence throughout
+ the graph. This is used for hashing points within the network.
+
+ Properties:
+ * node_count: Integer for the number of nodes in graph.
+ * nodes: An iterable of nodes in graph.
+ * ordered_nodes: An iterable of nodes in graph in order they were added.
+ * connection_segments: List of LineSegment2D for the node connections.
+ * outer_root_node: A node for the outer root key.
+ * hole_root_nodes: A list of nodes for the hole root keys.
+ """
+ __slots__=('_directed_graph','_tolerance','outer_root_key','hole_root_keys')
+
+ def__init__(self,tolerance):
+"""Initialize a PolygonDirectedGraph."""
+ self._directed_graph={}# will be used to hold the nodes of the network
+ # multiply tolerance by 2 to catch both positive and negative point equivalence
+ self._tolerance=tolerance*2
+ self.outer_root_key=None# will be set during network creation
+ self.hole_root_keys=[]# will be set during network creation
+
+
+[docs]
+ @classmethod
+ deffrom_point_array(cls,point_array,tolerance,loop=True):
+"""Create a DirectedGraphNetwork for a 1-dimensional array of points.
+
+ Args:
+ point_array: Array of Point2D objects.
+ tolerance: The tolerance used to determine point equivalence throughout
+ the graph. This is used for hashing points within the network.
+ loop: Optional boolean, which will ensure that the input point_array
+ is connected into a loop. (Default: True).
+ """
+ ext=TrueifloopelseNone
+ dg=cls(tolerance)
+ foriinrange(len(point_array)-1):
+ k=dg.add_node(point_array[i],[point_array[i+1]],exterior=ext)
+ ifi==0:
+ dg.outer_root_key=k
+ ifloop:
+ dg.add_node(point_array[-1],[point_array[0]],exterior=ext)
+ returndg
+
+
+
+[docs]
+ @classmethod
+ deffrom_polygon(cls,polygon,tolerance):
+"""Create a DirectedGraphNetwork from a polygon.
+
+ Args:
+ polygon: A Polygon2D object.
+ tolerance: The tolerance used to determine point equivalence throughout
+ the graph. This is used for hashing points within the network.
+
+ Returns:
+ A PolygonDirectedGraph object that represents the polygon. The edges
+ are uni-directional and counterclockwise. The nodes have the exterior
+ property set to True.
+ """
+ # ensure the boundary and holes are oriented correctly for the graph
+ ifpolygon.is_clockwise:
+ polygon=polygon.reverse()
+ returncls.from_point_array(polygon.vertices,tolerance,loop=True)
+
+
+
+[docs]
+ @classmethod
+ deffrom_shape_with_holes(cls,boundary,holes,tolerance):
+"""Create a DirectedGraphNetwork for a shape with holes.
+
+ Args:
+ boundary: A Polygon2D for the boundary around the shape.
+ holes: An optional list of Polygon2D for the holes within the shape.
+ If None, it will be assumed that no holes exist in the shape.
+ tolerance: The tolerance used to determine point equivalence throughout
+ the graph. This is used for hashing points within the network.
+
+ Returns:
+ A PolygonDirectedGraph object that represents the boundary with holes.
+ The edges (including the boundary and holes) are uni-directional with
+ the outer boundary being counterclockwise and the holes being clockwise.
+ In other words, the fill of the shape is always to the left of each edge.
+ The nodes have the exterior property set to True.
+ """
+ # ensure the boundary and holes are oriented correctly for the graph
+ ifboundary.is_clockwise:
+ boundary=boundary.reverse()
+ loops=[boundary.vertices]
+ ifholesisnotNone:
+ forholeinholes:
+ ifhole.is_clockwise:
+ loops.append(hole.vertices)
+ else:
+ loops.append(hole.reverse().vertices)
+
+ # make the directed graph and add the nodes for the boundary + holes
+ dg=cls(tolerance=tolerance)
+ forloop_count,verticesinenumerate(loops):
+ forjinrange(len(vertices)-1):
+ curr_v=vertices[j]
+ next_v=vertices[j+1]
+ k=dg.add_node(curr_v,[next_v],exterior=True)
+ ifj==0:
+ ifloop_count==0:
+ dg.outer_root_key=k
+ else:
+ dg.hole_root_keys.append(k)
+ dg.add_node(vertices[-1],[vertices[0]],exterior=True)# close loop
+ returndg
+
+
+
+[docs]
+ @classmethod
+ deffrom_shape_to_split(cls,boundary,holes,split_segments,tolerance):
+"""Get a DirectedGraphNetwork for a shape to be split with segments.
+
+ The shape is composed of a boundary with optional holes and the
+ split_segments are an array of any line segments to be used to
+ split the shape.
+
+ Args:
+ boundary: A Polygon2D for the boundary around the shape.
+ holes: An optional list of Polygon2D for the holes within the shape.
+ If None, it will be assumed that no holes exist in the shape.
+ split_segments: An array of LineSegment2D to be used to split the shape.
+ tolerance: The tolerance used to determine point equivalence throughout
+ the graph. This is used for hashing points within the network.
+
+ Returns:
+ A PolygonDirectedGraph object that represents the network formed by
+ the boundary, holes, and split segments. Portions of the split_segments
+ that are outside of the boundary are excluded from the graph. All interior
+ connections between the split_segments in the graph are bi-directional.
+ The exterior edges (including the boundary and holes) are uni-directional
+ with the outer boundary being counterclockwise and the holes being
+ clockwise. In other words, the fill of the shape is always to the left
+ of each exterior edge. The nodes at the boundary and the holes have
+ the exterior property set to True.
+ """
+ # first split the boundary and holes with the split_segments
+ boundary=boundary.remove_colinear_vertices(tolerance)
+ bound_sgs=cls._intersect_segments(boundary.segments,split_segments,tolerance)
+ bound_pts=[seg.p1forseginbound_sgs]
+ split_boundary=boundary.__class__(bound_pts)
+ split_holes=None
+ ifholesisnotNone:
+ split_holes=[]
+ forholeinholes:
+ hole=hole.remove_colinear_vertices(tolerance)
+ hole_sgs=cls._intersect_segments(
+ hole.segments,split_segments,tolerance)
+ hole_pts=[seg.p1forseginhole_sgs]
+ split_holes.append(boundary.__class__(hole_pts))
+
+ # make the directed graph for the boundary + holes
+ dg=cls.from_shape_with_holes(split_boundary,split_holes,tolerance)
+
+ # process the split_segments for intersection
+ add_segs=list(boundary.segments)
+ ifholesisnotNone:
+ forholeinholes:
+ add_segs.extend(hole.segments)
+ split_seg=cls._intersect_segments(split_segments,add_segs,tolerance)
+ split_seg=cls._remove_segments_outside_boundary(split_seg,boundary,tolerance)
+ iflen(split_seg)==0:# none of the segments are inside the shape
+ returndg
+
+ # add the intersection segments to the graph
+ forseginsplit_seg:# add a bidirectional edge to represent interior edges
+ dg.add_node(seg.p2,[seg.p1],exterior=False)
+ dg.add_node(seg.p1,[seg.p2],exterior=False)
+ returndg
+
+
+ @property
+ defnode_count(self):
+ returnlen(self.nodes)
+
+ @property
+ defnodes(self):
+"""Get an iterable of pt nodes"""
+ returnself._directed_graph.values()
+
+ @property
+ defordered_nodes(self):
+"""Get an iterable of pt nodes in order of addition"""
+ nodes=list(self.nodes)
+ nodes.sort(key=lambdav:v._order)
+ returnnodes
+
+ @property
+ defouter_root_node(self):
+"""Get the node of the outer boundary root."""
+ returnself.node(self.outer_root_key)
+
+ @property
+ defhole_root_nodes(self):
+"""Get a list of nodes for the roots of the holes."""
+ return[self.node(hole_key)forhole_keyinself.hole_root_keys]
+
+ @property
+ defconnection_segments(self):
+"""Get a list of LineSegment2D for the node connections in the graph."""
+ traversed=set()
+ connections=[]
+ fornodeinself.nodes:
+ forconn_nodeinnode.adj_lst:
+ if(conn_node.key,node.key)notintraversed:
+ conn_seg=LineSegment2D.from_end_points(node.pt,conn_node.pt)
+ connections.append(conn_seg)
+ traversed.add((node.key,conn_node.key))
+ returnconnections
+
+
+[docs]
+ defnode(self,key):
+"""Retrieves the node based on passed value.
+
+ Args:
+ val: The key for a node in the directed graph.
+
+ Returns:
+ The node for the passed key.
+ """
+ try:
+ returnself._directed_graph[key]
+ exceptKeyError:
+ returnNone# broken connection
+
+
+
+[docs]
+ defadd_adj(self,node,adj_val_lst):
+"""Adds nodes to node.adj_lst.
+
+ This method will ensure no repetitions will occur in adj_lst.
+
+ Args:
+ node: Node to add adjacencies to.
+ adj_val_lst: List of Point2D objects to add as adjacent nodes.
+ """
+ adj_keys={n.key:Noneforninnode.adj_lst}
+ adj_keys[node.key]=None
+ foradj_valinadj_val_lst:
+ adj_key=coordinates_hash(adj_val,self._tolerance)
+ ifadj_keyinadj_keys:
+ continue
+
+ self._add_node(adj_key,adj_val,exterior=None)
+ adj_keys[adj_key]=None
+ node.adj_lst.append(self.node(adj_key))
+
+
+
+[docs]
+ defremove_adj(self,node,adj_key_lst):
+"""Removes nodes in node.adj_lst.
+
+ Args:
+ node: Node to remove adjacencies to.
+ adj_val_lst: List of adjacency keys to remove as adjacent nodes.
+ """
+ node.adj_lst=[nforninnode.adj_lstifn.keynotinset(adj_key_lst)]
+
+
+
+[docs]
+ defadd_node(self,val,adj_lst,exterior=None):
+"""Add a node into the PolygonDirectedGraph.
+
+ This method consumes a Point2D, computes its key value, and adds it in the
+ graph if it doesn't exist. If it does exist it appends adj_lst to existing pt.
+
+ Args:
+ val: A Point2D object.
+ adj_lst: A list of Point2D objects adjacent to the node.
+ exterior: Optional boolean for whether the Node is exterior.
+
+ Returns:
+ The hashed key from the existing or new node.
+ """
+ key=coordinates_hash(val,self._tolerance)# get key
+ self._add_node(key,val,exterior)# get node if it exists
+ node=self._directed_graph[key]
+ self.add_adj(node,adj_lst)# add the adj_lst to dg
+ # if the exterior boolean was passed, change the node attribute
+ ifexteriorisnotNone:
+ node.exterior=exterior
+ returnnode.key
+
+
+ def_add_node(self,key,val,exterior=None):
+"""Helper function for add_node.
+
+ If key doesn't currently exist in the graph, it is added with a new key.
+ """
+ ifkeynotinself._directed_graph:
+ self._directed_graph[key]=Node(val,key,self.node_count,[],exterior)
+ returnself._directed_graph[key]
+
+
+[docs]
+ definsert_node(self,base_node,new_val,next_node,exterior=None):
+"""Insert node in the middle of an edge defined by node and next_node.
+
+ Args:
+ base_node: Node object to the left.
+ new_val: A Point2D object for the new node in the middle.
+ next_node: Node object to the right.
+ exterior: Optional boolean for exterior attribute.
+
+ Returns:
+ key of new_val node.
+ """
+ # add new_val as a node, with next_node as an adjacency
+ new_key=self.add_node(new_val,[next_node.pt],exterior=exterior)
+ # update parent by adding new adjacency, and removing old adjacency
+ self.add_adj(base_node,[self.node(new_key).pt])
+
+ # catch the edge case where the new point is coincident to parent or next_point.
+ # this occurs when intersection passes through a corner.
+ if(new_key==next_node.key)or(new_key==base_node.key):
+ returnnew_key
+ self.remove_adj(base_node,[next_node.key])
+ returnnew_key
+
+
+
+[docs]
+ defnode_exists(self,key):
+"""Check if a node is in the graph. True if node in directed graph else False."""
+ returnkeyinself._directed_graph
+
+
+
+[docs]
+ defpt_exists(self,pt):
+"""True if a point (as Point2D) in directed graph exists as node else False.
+ """
+ returnself.node_exists(coordinates_hash(pt,self._tolerance))
+
+
+
+[docs]
+ defpolygon_exists(self,polygon):
+"""Check if a polygon is in the directed graph.
+
+ Args:
+ polygons: A Polygon2D object.
+
+ Return:
+ True if exists, else False.
+ """
+ vertices_loop=list(polygon.vertices)
+ vertices_loop=vertices_loop+[vertices_loop[0]]
+
+ foriinrange(len(vertices_loop)-1):
+ pt1=vertices_loop[i]
+ pt2=vertices_loop[i+1]
+
+ ifnotself.pt_exists(pt1):
+ returnFalse
+
+ node1=self.node(coordinates_hash(pt1,self._tolerance))
+ node2=self.node(coordinates_hash(pt2,self._tolerance))
+ ifnode2.keyin[n.keyforninnode1.adj_lst]:
+ returnFalse
+
+ returnTrue
+
+
+
+[docs]
+ defadj_matrix(self):
+"""Gets an adjacency matrix of the directed graph where:
+
+ * 1 = adjacency from row node to col node.
+ * 0 = no adjacency.
+
+ Returns:
+ N x N square matrix where N is number of nodes.
+ """
+ nodes=self.ordered_nodes
+ # initialize a mtx with no adjacencies
+ amtx=[[0foriinrange(self.node_count)]
+ forjinrange(self.node_count)]
+
+ foriinrange(self.node_count):
+ adj_indices=[adj._orderforadjinnodes[i].adj_lst]
+ foradj_idxinadj_indices:
+ amtx[i][adj_idx]=1
+
+ returnamtx
+
+
+
+[docs]
+ defadj_matrix_labels(self):
+"""Returns a dictionary where label key corresponds to index in adj_matrix
+ and value is node key"""
+ return{i:node.keyfori,nodeinenumerate(self.ordered_nodes)}
+
+
+
+[docs]
+ defmin_cycle(self,base_node,goal_node,ccw_only=False):
+"""Identify the shortest interior cycle between two exterior nodes.
+
+ Args:
+ base_node: The first exterior node of the edge.
+ goal_node: The end exterior node of the cycle that, together with
+ the base_node, constitutes an exterior edge.
+ ccw_only: A boolean to note whether the search should be limited
+ to the counter-clockwise direction only. (Default: False).
+
+ Returns:
+ A list of nodes that form a polygon if the cycle exists, else None.
+ """
+ # set up a queue for exploring the graph
+ explored=[]
+ queue=[[base_node]]
+ orig_dir=base_node.pt-goal_node.pt \
+ ifbase_node.key!=goal_node.keyelseNone
+ # loop to traverse the graph with the help of the queue
+ whilequeue:
+ path=queue.pop(0)
+ node=path[-1]
+ # make sure that the current node has not been visited
+ ifnodenotinexplored:
+ prev_dir=node.pt-path[-2].ptiflen(path)>1elseorig_dir
+ # iterate over the neighbors to determine relevant nodes
+ rel_neighbors,rel_angles=[],[]
+ last_resort_neighbors,last_resort_angles=[],[]
+ forneighborinnode.adj_lst:
+ ifneighbor==goal_node:# the shortest path was found!
+ path.append(goal_node)
+ returnpath
+ edge_dir=neighbor.pt-node.pt
+ cw_angle=prev_dir.angle_clockwise(edge_dir*-1) \
+ ifprev_dirisnotNoneelsemath.pi
+ if1e-5<cw_angle<(2*math.pi)-1e-5:
+ rel_neighbors.append(neighbor)
+ rel_angles.append(cw_angle)
+ else:# try to avoid back-tracking along the search
+ last_resort_neighbors.append(neighbor)
+ last_resort_angles.append(cw_angle)
+ iflen(rel_neighbors)==0:# back tracking is the only option
+ rel_neighbors=last_resort_neighbors
+ rel_angles=last_resort_angles
+ # sort the neighbors by clockwise angle
+ iflen(rel_neighbors)>1:
+ rel_neighbors=[nfor_,ninsorted(zip(rel_angles,rel_neighbors),
+ key=lambdapair:pair[0])]
+ # add the relevant neighbors to the path and the queue
+ ifccw_only:
+ new_path=list(path)
+ new_path.append(rel_neighbors[0])
+ queue.append(new_path)
+ else:# add all neighbors to the search
+ forneighborinrel_neighbors:
+ new_path=list(path)
+ new_path.append(neighbor)
+ queue.append(new_path)
+ explored.append(node)
+ # if we reached the end of the queue, then no path was found
+ returnNone
+
+
+
+[docs]
+ defall_min_cycles(self):
+"""Get a list of lists where each sub-list is a minimum cycle of Nodes.
+
+ The combination of all min cycles should account for the full area of
+ the input shape if the DirectedGraphNetwork was made using any of the
+ class methods that work from polygons. If the DirectedGraphNetwork was made
+ using the from_shape_to_split method, the resulting cycles here represent
+ the input shape split with the split_segments.
+ """
+ # first, figure out how many loops each node should be a part of
+ node_cycle_counts={}
+ fornodeinself.nodes:
+ node_cycle_counts[node.key]=len(node.adj_lst)
+
+ # loop through the nodes until all min cycles have been identified
+ all_cycles=[]
+ iter_count=0
+ max_iter=len(self.nodes)
+ remaining_nodes=self.ordered_nodes
+ explored_nodes=set()
+
+ whilelen(remaining_nodes)>1anditer_count<max_iter:
+ # try to identify two connected nodes which we can use to build a cycle
+ cycle_root=remaining_nodes[0]
+ next_node=cycle_root# if we can't find a connected node, connect to self
+ ext_cycle=False
+ ifcycle_root.exterior:# exterior cycles tend to have clear connections
+ next_node=DirectedGraphNetwork.next_exterior_node(cycle_root)
+ ifnext_nodeisnotNone:
+ ext_cycle=True
+ else:
+ next_node=cycle_root
+ ifnotext_cycle:# see if we can connect it to another incomplete node
+ for_next_nodeincycle_root.adj_lst:
+ ifnode_cycle_counts[_next_node.key]!=0:
+ next_node=_next_node
+ ext_cycle=True
+ break
+
+ # find the minimum cycle by searching counter-clockwise
+ min_cycle=self.min_cycle(next_node,cycle_root,True)
+
+ # if we found a minimum cycle, evaluate its validity by node connections
+ ifmin_cycleisnotNoneandlen(min_cycle)>=3:
+ ifnotext_cycle:
+ min_cycle.pop(-1)# take out the last duplicated node
+ is_valid_cycle=True
+ fornodeinmin_cycle:
+ ifnode_cycle_counts[node.key]-1<0:# we are re-traversing
+ is_valid_cycle=False# not a valid cycle
+
+ # add the valid cycle to the list to be returned
+ ifis_valid_cycle:
+ fornodeinmin_cycle:
+ node_cycle_counts[node.key]=node_cycle_counts[node.key]-1
+ ifnode_cycle_counts[node.key]==0:# all cycles for node found
+ fori,r_nodeinenumerate(remaining_nodes):
+ ifr_node.key==node.key:
+ remaining_nodes.pop(i)
+ break
+ all_cycles.append(min_cycle)
+ fornodeinmin_cycle:
+ explored_nodes.add(node.key)
+
+ # reorder the remaining nodes so unexplored nodes get prioritized
+ iflen(remaining_nodes)!=0:
+ forj,nodeinenumerate(remaining_nodes):
+ ifnode.keynotinexplored_nodes:
+ break
+ remaining_nodes.insert(0,remaining_nodes.pop(j))
+ iter_count+=1
+
+ # if we wer not able to address all nodes, see if they are all in the same loop
+ iflen(remaining_nodes)>=3:
+ current_node=remaining_nodes.pop(0)
+ current_node_adj=[node.keyfornodeinnode.adj_lst]
+ last_cycle=[current_node]
+ iter_count,max_iter=0,len(remaining_nodes)
+ whilelen(remaining_nodes)>0anditer_count<max_iter:
+ fork,nodeinenumerate(remaining_nodes):
+ ifnode.keyincurrent_node_adj:
+ current_node=remaining_nodes.pop(k)
+ current_node_adj=[node.keyfornodeinnode.adj_lst]
+ last_cycle.append(current_node)
+ break
+ iter_count+=1
+ iflen(last_cycle)>2:
+ all_cycles.append(last_cycle)
+
+ returnall_cycles
+
+
+
+[docs]
+ defexterior_cycle(self,cycle_root):
+"""Compute exterior boundary from a given node.
+
+ This method assumes that exterior edges are naked (unidirectional) and
+ interior edges are bidirectional.
+
+ Args:
+ cycle_root: Starting Node in exterior cycle.
+
+ Returns:
+ List of nodes on exterior if a cycle exists, else None.
+ """
+ # Get the first exterior edge
+ curr_node=cycle_root
+ next_node=DirectedGraphNetwork.next_exterior_node(curr_node)
+ ifnotnext_node:
+ returnNone
+
+ # loop through the cycle until we get it all or run out of points
+ max_iter=self.node_count+1# maximum length a cycle can be
+ ext_cycle=[curr_node]
+ iter_count=0
+ whilenext_node.key!=cycle_root.key:
+ ext_cycle.append(next_node)
+ next_node=DirectedGraphNetwork.next_exterior_node(next_node)
+ ifnotnext_node:
+ returnNone# we have hit a dead end in the cycle
+ iter_count+=1
+ ifiter_count>max_iter:
+ break# we have gotten stuck in a loop
+
+ returnext_cycle
+
+
+
+[docs]
+ defexterior_cycles(self):
+"""Get a list of lists where each sub-list is an exterior cycle of Nodes.
+
+ Exterior cycles refer to the cycles of both the boundary and the holes
+ of the DirectedGraphNetwork was created using the from_shape_to_split
+ class method.
+ """
+ exterior_poly_lst=[]# list to store cycles
+ explored_nodes=set()# set to note explored exterior nodes
+ max_iter=self.node_count+1# maximum length a cycle can be
+
+ # loop through all of the nodes of the graph and find cycles
+ forroot_nodeinself.ordered_nodes:
+ # make a note that the current node has been explored
+ explored_nodes.add(root_node.key)# mark the node as explored
+ # get next exterior adjacent node and check that it's valid
+ next_node=self.next_exterior_node(root_node)# mark the node as explored
+ is_valid=(next_nodeisnotNone)and(next_node.keynotinexplored_nodes)
+ ifnotis_valid:
+ continue
+ # make a note that the next node has been explored
+ explored_nodes.add(next_node.key)
+
+ # traverse the loop of points until we get back to start or hit a dead end
+ exterior_poly=[root_node]
+ prev_node=root_node
+ iter_count=0
+ whilenext_node.key!=root_node.key:
+ exterior_poly.append(next_node)
+ explored_nodes.add(next_node.key)# mark the node as explored
+ follow_node=self.next_exterior_node_no_backtrack(
+ next_node,prev_node,explored_nodes)
+ prev_node=next_node# set as the previous node for the next step
+ next_node=follow_node
+ ifnext_nodeisNone:
+ break# we have hit a dead end in the cycle
+ iter_count+=1
+ ifiter_count>max_iter:
+ print('Extraction of core polygons hit an endless loop.')
+ break# we have gotten stuck in a loop
+ exterior_poly_lst.append(exterior_poly)
+
+ # return all of the exterior loops that were found
+ returnexterior_poly_lst
+
+
+
+[docs]
+ @staticmethod
+ defnext_exterior_node_no_backtrack(node,previous_node,explored_nodes):
+"""Get the next exterior node adjacent to the input node.
+
+ This method is similar to the next_exterior_node method but it includes
+ extra checks to handle intersections with 3 or more segments in the
+ graph exterior cycles. In these cases a set of previously explored_nodes
+ is used to ensure that no back-tracking happens over the search of the
+ network, which can lead to infinite looping through the graph. Furthermore,
+ the previous_node is used to select the pathway with the smallest angle
+ difference with the previous direction. This leads the result towards
+ minimal polygons with fewer self-intersecting loops.
+
+ Args:
+ node: A Node object for which the next node will be returned.
+ previous_node: A Node object for the node that came before
+ the current one in the loop. This will be used in the event that
+ multiple exterior nodes are found connecting to the input node.
+ In this case, the exterior node with the smallest angle difference
+ with the previous direction will be returned. This leads the
+ result towards minimal polygons and away from self-intersecting
+ exterior loops like a bowtie.
+
+ Returns:
+ Next node that defines exterior edge, or None if all adjacencies are
+ bidirectional.
+ """
+ # loop through the all adjacent nodes and determine if they are exterior
+ next_nodes=[]
+ for_next_nodeinnode.adj_lst:
+ if_next_node.exterior:# user has labeled it as exterior; we're done!
+ return_next_node
+ elif_next_node.exteriorisNone:# don't know if it's interior or exterior
+ # if user-assigned attribute isn't defined, check bi-directionality
+ ifnotDirectedGraphNetwork.is_edge_bidirect(node,_next_node):
+ next_nodes.append(_next_node)
+
+ # evaluate whether there is one obvious choice for the next node
+ iflen(next_nodes)<=1:
+ returnnext_nodes[0]iflen(next_nodes)==1elseNone
+ next_nodes=[nnfornninnext_nodesifnn.keynotinexplored_nodes]
+ iflen(next_nodes)<=1:
+ returnnext_nodes[0]iflen(next_nodes)==1elseNone
+
+ # if we have multiple exterior nodes, use the previous node to find the best one
+ prev_dir=previous_node.pt-node.pt# yields a vector
+ next_angles=[]
+ fornext_nodeinnext_nodes:
+ edge_dir=next_node.pt-node.pt# yields a vector
+ next_angles.append(prev_dir.angle(edge_dir*-1))
+ sorted_nodes=[nfor_,ninsorted(zip(next_angles,next_nodes),
+ key=lambdapair:pair[0])]
+ returnsorted_nodes[0]# return the node making the smallest angle
+
+
+
+[docs]
+ @staticmethod
+ defnext_exterior_node(node):
+"""Get the next exterior node adjacent to consumed node.
+
+ If there are adjacent nodes that are labeled as exterior, with True or
+ False defining the Node.exterior property, the first of such nodes in
+ the adjacency list will be returned as the next one. Otherwise, the
+ bi-directionality will be used to determine whether the next node is
+ exterior.
+
+ Args:
+ node: A Node object for which the next node will be returned.
+
+ Returns:
+ Next node that defines exterior edge, or None if all adjacencies are
+ bidirectional.
+ """
+ # loop through the adjacency and find an exterior node
+ for_next_nodeinnode.adj_lst:
+ if_next_node.exterior:# user has labeled it as exterior; we're done!
+ return_next_node
+ elif_next_node.exteriorisNone:# don't know if it's interior or exterior
+ # if user-assigned attribute isn't defined, check bi-directionality
+ ifnotDirectedGraphNetwork.is_edge_bidirect(node,_next_node):
+ return_next_node
+ returnNone
+
+
+
+[docs]
+ @staticmethod
+ defis_edge_bidirect(node1,node2):
+"""Are two nodes bidirectional.
+
+ Args:
+ node1: Node object
+ node2: Node object
+
+ Returns:
+ True if node1 and node2 are in each other's adjacency list,
+ else False.
+ """
+ returnnode1.keyin(n.keyforninnode2.adj_lst)and \
+ node2.keyin(n.keyforninnode1.adj_lst)
+
+
+ @staticmethod
+ def_intersect_segments(segments,additional_segments,tolerance):
+"""Intersect a list of LineSegment2D and split them.
+
+ Args:
+ segments: A list of LineSegment2D for the segments to be split/intersected.
+ additional_segments: A list of additional LineSegment2Ds, which will be
+ used to split the input segments but will not be included in the
+ output themselves.
+ tolerance: The tolerance at which the intersection will be computed.
+
+ Returns:
+ A list of LineSegment2D for the input segments split through
+ self-intersection and intersection with the additional_segments.
+ """
+ # make sure that we are working with lists
+ ifnotisinstance(segments,list):
+ segments=list(segments)
+ ifnotisinstance(additional_segments,list):
+ additional_segments=list(additional_segments)
+
+ # extend segments a little to ensure intersections happen
+ under_tol=tolerance*0.99
+ ext_segments=[]
+ forseginsegments+additional_segments:
+ m_v=seg.v.normalize()*under_tol
+ ext_seg=LineSegment2D.from_end_points(seg.p1.move(-m_v),seg.p2.move(m_v))
+ ext_segments.append(ext_seg)
+
+ # compute all of the intersection points across the segments
+ intersect_pts=[[]for_insegments]
+ fori,seginenumerate(segments):
+ try:
+ forother_seginext_segments[:i]+ext_segments[i+1:]:
+ int_pt=intersect_line_segment2d(seg,other_seg)
+ ifint_ptisNoneorint_pt.is_equivalent(seg.p1,tolerance)or \
+ int_pt.is_equivalent(seg.p2,tolerance):
+ continue
+ # we have found an intersection point where segments should be split
+ intersect_pts[i].append(int_pt)
+ exceptIndexError:
+ pass# we have reached the end of the list
+
+ # loop through the segments and split them at the intersection points
+ split_segments=[]
+ forseg,split_ptsinzip(segments,intersect_pts):
+ iflen(split_pts)==0:
+ split_segments.append(seg)
+ eliflen(split_pts)==1:# split the segment in two
+ int_pt=split_pts[0]
+ split_segments.append(LineSegment2D.from_end_points(seg.p1,int_pt))
+ split_segments.append(LineSegment2D.from_end_points(int_pt,seg.p2))
+ else:# sort the points along the segment to split it
+ pt_dists=[seg.p1.distance_to_point(ipt)foriptinsplit_pts]
+ sort_obj=sorted(zip(pt_dists,split_pts),key=lambdapair:pair[0])
+ sort_pts=[xfor_,xinsort_obj]
+ sort_pts.append(seg.p2)
+ pr_pt=seg.p1
+ fors_ptinsort_pts:
+ ifnotpr_pt.is_equivalent(s_pt,tolerance):
+ split_segments.append(LineSegment2D.from_end_points(pr_pt,s_pt))
+ pr_pt=s_pt
+
+ returnsplit_segments
+
+ @staticmethod
+ def_remove_segments_outside_boundary(segments,boundary,tolerance):
+"""Remove LineSegment2D that are outside the boundary of the parent shape.
+
+ This can be used to clean up the result after intersection of segments.
+
+ Args:
+ segments: A list of LineSegment2D to be filtered for whether they are
+ inside the boundary.
+ boundary: A Polygon2D for the boundary of the shape. Segments that lie
+ outside of this boundary beyond the tolerance will be removed from
+ the result.
+ tolerance: The tolerance for distinguishing whether skeleton points lie
+ outside the boundary.
+
+ Returns:
+ A list of LineSegment2D objects with segments removed that outside
+ of the boundary.
+ """
+ clean_segments=[]
+ forseginsegments:
+ p1,p2=seg.p1,seg.p2
+ ifboundary.point_relationship(p2,tolerance)>=0and \
+ boundary.point_relationship(p1,tolerance)>=0:
+ clean_segments.append(seg)
+ returnclean_segments
+
+ def__repr__(self):
+"""Represent PolygonDirectedGraph."""
+ s=''
+ forninself.ordered_nodes:
+ s+='{}, [{}]\n'.format(
+ n.pt.to_array(),
+ ', '.join([str(_n.pt.to_array())for_ninn.adj_lst]))
+ returns
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/_modules/ladybug_geometry/triangulation.html b/docs/_modules/ladybug_geometry/triangulation.html
new file mode 100644
index 00000000..b20f014e
--- /dev/null
+++ b/docs/_modules/ladybug_geometry/triangulation.html
@@ -0,0 +1,1864 @@
+
+
+
+
+
+
+ ladybug_geometry.triangulation — ladybug geometry documentation
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+# coding=utf-8
+"""Core triangulation functions used by various geometry modules.
+
+The functions here are derived from the earcut-python library available at
+https://github.com/joshuaskelly/earcut-python
+
+The earcut-python library is, itself, a pure Python port of the earcut JavaScript
+triangulation library maintained by Mapbox. The original project can be found at
+https://github.com/mapbox/earcut
+
+The version here is based off of the JavaScript earcut 2.1.1 release, and is
+functionally identical.
+"""
+from__future__importdivision
+
+
+
+[docs]
+defearcut(data,hole_indices=None,dim=2):
+"""Triangulate a list of vertices that make up a shape, either with or without holes.
+
+ Args:
+ data: A flat array of vertex coordinates like [x0,y0, x1,y1, x2,y2, ...].
+ hole_indices: A flat array of the starting indices for each hole. For example,
+ [5, 8] for a 12-vertex input would mean one hole with vertices 5-7
+ and another with 8-11. If a single vertex is passed as as a hole,
+ Earcut treats it as a Steiner point. If None, no holes will be assumed
+ for the shape. (Default: None).
+ dim: An integer for the number of coordinates per vertex in the input
+ array. For example, 3 means each vertex exists in 3D space with
+ XX, Y, Z coordinates. (Default: 2 for 2D coordinates).
+ """
+ dim=dimor2
+ hasHoles=hole_indicesandlen(hole_indices)
+ outerLen=hole_indices[0]*dimifhasHoleselselen(data)
+ outerNode=_linked_list(data,0,outerLen,dim,True)
+ triangles=[]
+
+ ifnotouterNode:
+ returntriangles
+
+ minX=None
+ minY=None
+ maxX=None
+ maxY=None
+ x=None
+ y=None
+ size=None
+
+ ifhasHoles:
+ outerNode=_eliminate_holes(data,hole_indices,outerNode,dim)
+
+ # if the shape is not too simple, we'll use z-order curve hash later
+ if(len(data)>80*dim):# calculate polygon bbox
+ minX=maxX=data[0]
+ minY=maxY=data[1]
+
+ foriinrange(dim,outerLen,dim):
+ x=data[i]
+ y=data[i+1]
+ ifx<minX:
+ minX=x
+ ify<minY:
+ minY=y
+ ifx>maxX:
+ maxX=x
+ ify>maxY:
+ maxY=y
+
+ # minX, minY and size are later used to transform coords into integers
+ # integers are used for z-order calculation
+ size=max(maxX-minX,maxY-minY)
+
+ _earcut_linked(outerNode,triangles,dim,minX,minY,size)
+
+ returntriangles
+
+
+
+def_linked_list(data,start,end,dim,clockwise):
+"""Create a circular doubly linked list from polygon points.
+
+ Points will be in the specified winding order.
+ """
+ i=None
+ last=None
+
+ if(clockwise==(_signed_area(data,start,end,dim)>0)):
+ foriinrange(start,end,dim):
+ last=_insert_node(i,data[i],data[i+1],last)
+
+ else:
+ foriinreversed(range(start,end,dim)):
+ last=_insert_node(i,data[i],data[i+1],last)
+
+ if(lastand_equals(last,last.next)):
+ _remove_node(last)
+ last=last.next
+
+ returnlast
+
+
+def_signed_area(data,start,end,dim):
+"""Get the signed area from a list of coordinate data."""
+ sum=0
+ j=end-dim
+
+ foriinrange(start,end,dim):
+ sum+=(data[j]-data[i])*(data[i+1]+data[j+1])
+ j=i
+
+ returnsum
+
+
+def_filter_points(start,end=None):
+"""Eliminate colinear or duplicate points."""
+ ifnotstart:
+ returnstart
+ ifnotend:
+ end=start
+
+ p=start
+ again=True
+
+ whileagainorp!=end:
+ again=False
+
+ if(notp.steinerand(_equals(p,p.next)or_area(p.prev,p,p.next)==0)):
+ _remove_node(p)
+ p=end=p.prev
+ if(p==p.next):
+ returnNone
+
+ again=True
+
+ else:
+ p=p.next
+
+ returnend
+
+
+def_earcut_linked(ear,triangles,dim,minX,minY,size,_pass=None):
+"""Main ear slicing loop which triangulates a polygon (given as a linked list)."""
+ ifnotear:
+ return
+
+ # interlink polygon nodes in z-order
+ ifnot_passandsize:
+ _index_curve(ear,minX,minY,size)
+
+ stop=ear
+ prev=None
+ next=None
+
+ # iterate through ears, slicing them one by one
+ whileear.prev!=ear.next:
+ prev=ear.prev
+ next=ear.next
+
+ if_is_ear_hashed(ear,minX,minY,size)ifsizeelse_is_ear(ear):
+ # cut off the triangle
+ triangles.append(prev.i//dim)
+ triangles.append(ear.i//dim)
+ triangles.append(next.i//dim)
+
+ _remove_node(ear)
+
+ # skipping the next vertex leads to less sliver triangles
+ ear=next.next
+ stop=next.next
+
+ continue
+
+ ear=next
+
+ # if we looped through the whole remaining polygon and can't find any more ears
+ ifear==stop:
+ # try filtering points and slicing again
+ ifnot_pass:
+ _earcut_linked(_filter_points(ear),triangles,dim,minX,minY,size,1)
+
+ # if this didn't work, try curing all small self-intersections locally
+ elif_pass==1:
+ ear=_cure_local_intersections(ear,triangles,dim)
+ _earcut_linked(ear,triangles,dim,minX,minY,size,2)
+
+ # as a last resort, try splitting the remaining polygon into two
+ elif_pass==2:
+ _split_earcut(ear,triangles,dim,minX,minY,size)
+
+ break
+
+
+def_is_ear(ear):
+"""Check whether a polygon node forms a valid ear with adjacent nodes."""
+ a=ear.prev
+ b=ear
+ c=ear.next
+
+ if_area(a,b,c)>=0:
+ returnFalse# reflex, can't be an ear
+
+ # now make sure we don't have other points inside the potential ear
+ p=ear.next.next
+
+ whilep!=ear.prev:
+ if_point_in_triangle(a.x,a.y,b.x,b.y,c.x,c.y,p.x,p.y)and \
+ _area(p.prev,p,p.next)>=0:
+ returnFalse
+ p=p.next
+
+ returnTrue
+
+
+def_is_ear_hashed(ear,minX,minY,size):
+"""Check whether a polygon node forms a valid ear using hashes."""
+ a=ear.prev
+ b=ear
+ c=ear.next
+
+ if_area(a,b,c)>=0:
+ returnFalse# reflex, can't be an ear
+
+ # triangle bbox; min & max are calculated like this for speed
+ minTX=(a.xifa.x<c.xelsec.x)ifa.x<b.xelse(b.xifb.x<c.xelsec.x)
+ minTY=(a.yifa.y<c.yelsec.y)ifa.y<b.yelse(b.yifb.y<c.yelsec.y)
+ maxTX=(a.xifa.x>c.xelsec.x)ifa.x>b.xelse(b.xifb.x>c.xelsec.x)
+ maxTY=(a.yifa.y>c.yelsec.y)ifa.y>b.yelse(b.yifb.y>c.yelsec.y)
+
+ # z-order range for the current triangle bbox;
+ minZ=_z_order(minTX,minTY,minX,minY,size)
+ maxZ=_z_order(maxTX,maxTY,minX,minY,size)
+
+ # first look for points inside the triangle in increasing z-order
+ p=ear.nextZ
+
+ whilepandp.z<=maxZ:
+ ifp!=ear.prevandp!=ear.nextand \
+ _point_in_triangle(a.x,a.y,b.x,b.y,c.x,c.y,p.x,p.y)and \
+ _area(p.prev,p,p.next)>=0:
+ returnFalse
+ p=p.nextZ
+
+ # then look for points in decreasing z-order
+ p=ear.prevZ
+
+ whilepandp.z>=minZ:
+ ifp!=ear.prevandp!=ear.nextand \
+ _point_in_triangle(a.x,a.y,b.x,b.y,c.x,c.y,p.x,p.y)and \
+ _area(p.prev,p,p.next)>=0:
+ returnFalse
+ p=p.prevZ
+
+ returnTrue
+
+
+def_cure_local_intersections(start,triangles,dim):
+"""Go through all polygon nodes and cure small local self-intersections."""
+ do=True
+ p=start
+
+ whiledoorp!=start:
+ do=False
+
+ a=p.prev
+ b=p.next.next
+
+ ifnot_equals(a,b)and_intersects(a,p,p.next,b)and \
+ _locally_inside(a,b)and_locally_inside(b,a):
+ triangles.append(a.i//dim)
+ triangles.append(p.i//dim)
+ triangles.append(b.i//dim)
+
+ # remove two nodes involved
+ _remove_node(p)
+ _remove_node(p.next)
+
+ p=start=b
+
+ p=p.next
+
+ returnp
+
+
+def_split_earcut(start,triangles,dim,minX,minY,size):
+"""try splitting polygon into two and triangulate them independently."""
+ # look for a valid diagonal that divides the polygon into two
+ do=True
+ a=start
+
+ whiledoora!=start:
+ do=False
+ b=a.next.next
+
+ whileb!=a.prev:
+ ifa.i!=b.iand_is_valid_diagonal(a,b):
+ # split the polygon in two by the diagonal
+ c=_split_polygon(a,b)
+
+ # filter colinear points around the cuts
+ a=_filter_points(a,a.next)
+ c=_filter_points(c,c.next)
+
+ # run earcut on each half
+ _earcut_linked(a,triangles,dim,minX,minY,size)
+ _earcut_linked(c,triangles,dim,minX,minY,size)
+ return
+
+ b=b.next
+
+ a=a.next
+
+
+def_eliminate_holes(data,hole_indices,outerNode,dim):
+"""Link holes into the outer loop, producing a single-ring polygon without holes."""
+ queue=[]
+ i=None
+ _len=len(hole_indices)
+ start=None
+ end=None
+ _list=None
+
+ foriinrange(len(hole_indices)):
+ start=hole_indices[i]*dim
+ end=hole_indices[i+1]*dimifi<_len-1elselen(data)
+ _list=_linked_list(data,start,end,dim,False)
+
+ if(_list==_list.next):
+ _list.steiner=True
+
+ queue.append(_get_leftmost(_list))
+
+ queue=sorted(queue,key=lambdai:i.x)
+
+ # process holes from left to right
+ foriinrange(len(queue)):
+ _eliminate_hole(queue[i],outerNode)
+ outerNode=_filter_points(outerNode,outerNode.next)
+
+ returnouterNode
+
+
+def_eliminate_hole(hole,outerNode):
+"""Find a bridge between vertices that connects hole with an outer ring.
+
+ Return a shape with the hole linked into it."""
+ outerNode=_find_hole_bridge(hole,outerNode)
+ ifouterNode:
+ b=_split_polygon(outerNode,hole)
+ _filter_points(b,b.next)
+
+
+def_find_hole_bridge(hole,outerNode):
+"""David Eberly's algorithm for finding a bridge between hole and outer polygon."""
+ do=True
+ p=outerNode
+ hx=hole.x
+ hy=hole.y
+ qx=float('-inf')
+ m=None
+
+ # find a segment intersected by a ray from the hole's leftmost point to the left;
+ # segment's endpoint with lesser x will be potential connection point
+ whiledoorp!=outerNode:
+ do=False
+ ifhy<=p.yandhy>=p.next.yandp.next.y-p.y!=0:
+ x=p.x+(hy-p.y)*(p.next.x-p.x)/(p.next.y-p.y)
+
+ ifx<=hxandx>qx:
+ qx=x
+
+ if(x==hx):
+ ifhy==p.y:
+ returnp
+ ifhy==p.next.y:
+ returnp.next
+
+ m=pifp.x<p.next.xelsep.next
+
+ p=p.next
+
+ ifnotm:
+ returnNone
+
+ ifhx==qx:
+ returnm.prev# hole touches outer segment; pick lower endpoint
+
+ # check points inside the triangle of hole point, segment intersection and endpoint
+ # if there are no points found, we have a valid connection
+ # otherwise choose the point of the minimum angle with the ray as connection point
+
+ stop=m
+ mx=m.x
+ my=m.y
+ tanMin=float('inf')
+ tan=None
+
+ p=m.next
+
+ whilep!=stop:
+ hx_or_qx=hxifhy<myelseqx
+ qx_or_hx=qxifhy<myelsehx
+
+ ifhx>=p.xandp.x>=mxand \
+ _point_in_triangle(hx_or_qx,hy,mx,my,qx_or_hx,hy,p.x,p.y):
+ try:
+ tan=abs(hy-p.y)/(hx-p.x)# tangential
+ exceptZeroDivisionError:
+ break
+
+ if(tan<tanMinor(tan==tanMinandp.x>m.x))and \
+ _locally_inside(p,hole):
+ m=p
+ tanMin=tan
+
+ p=p.next
+
+ returnm
+
+
+def_index_curve(start,minX,minY,size):
+"""Interlink polygon nodes in z-order."""
+ do=True
+ p=start
+
+ whiledoorp!=start:
+ do=False
+
+ ifp.zisNone:
+ p.z=_z_order(p.x,p.y,minX,minY,size)
+
+ p.prevZ=p.prev
+ p.nextZ=p.next
+ p=p.next
+
+ p.prevZ.nextZ=None
+ p.prevZ=None
+
+ _sort_linked(p)
+
+
+def_sort_linked(_list):
+"""Simon Tatham's linked list merge sort algorithm.
+
+ More information available at https://www.chiark.greenend.org.uk/
+ """
+ do=True
+ i=None
+ p=None
+ q=None
+ e=None
+ tail=None
+ numMerges=None
+ pSize=None
+ qSize=None
+ inSize=1
+
+ whiledoornumMerges>1:
+ do=False
+ p=_list
+ _list=None
+ tail=None
+ numMerges=0
+
+ whilep:
+ numMerges+=1
+ q=p
+ pSize=0
+ foriinrange(inSize):
+ pSize+=1
+ q=q.nextZ
+ ifnotq:
+ break
+
+ qSize=inSize
+
+ whilepSize>0or(qSize>0andq):
+
+ ifpSize==0:
+ e=q
+ q=q.nextZ
+ qSize-=1
+
+ elif(qSize==0ornotq):
+ e=p
+ p=p.nextZ
+ pSize-=1
+
+ elif(p.z<=q.z):
+ e=p
+ p=p.nextZ
+ pSize-=1
+
+ else:
+ e=q
+ q=q.nextZ
+ qSize-=1
+
+ iftail:
+ tail.nextZ=e
+
+ else:
+ _list=e
+
+ e.prevZ=tail
+ tail=e
+
+ p=q
+
+ tail.nextZ=None
+ inSize*=2
+
+ return_list
+
+
+def_z_order(x,y,minX,minY,size):
+"""Z-order of a point given coords and size of the data bounding box."""
+ # coords are transformed into non-negative 15-bit integer range
+ x=int(32767*(x-minX)//size)
+ y=int(32767*(y-minY)//size)
+
+ x=(x|(x<<8))&0x00FF00FF
+ x=(x|(x<<4))&0x0F0F0F0F
+ x=(x|(x<<2))&0x33333333
+ x=(x|(x<<1))&0x55555555
+
+ y=(y|(y<<8))&0x00FF00FF
+ y=(y|(y<<4))&0x0F0F0F0F
+ y=(y|(y<<2))&0x33333333
+ y=(y|(y<<1))&0x55555555
+
+ returnx|(y<<1)
+
+
+def_get_leftmost(start):
+"""Find the leftmost node of a polygon ring."""
+ do=True
+ p=start
+ leftmost=start
+
+ whiledoorp!=start:
+ do=False
+ ifp.x<leftmost.x:
+ leftmost=p
+ p=p.next
+
+ returnleftmost
+
+
+def_point_in_triangle(ax,ay,bx,by,cx,cy,px,py):
+"""Check if a point lies within a convex triangle."""
+ return(cx-px)*(ay-py)-(ax-px)*(cy-py)>=0and \
+ (ax-px)*(by-py)-(bx-px)*(ay-py)>=0and \
+ (bx-px)*(cy-py)-(cx-px)*(by-py)>=0
+
+
+def_is_valid_diagonal(a,b):
+"""Check if a diagonal between two polygon nodes is valid.
+
+ A valid diagonal is defined as one that lies in polygon interior.
+ """
+ returna.next.i!=b.ianda.prev.i!=b.iandnot_intersects_polygon(a,b)and \
+ _locally_inside(a,b)and_locally_inside(b,a)and_middle_inside(a,b)
+
+
+def_area(p,q,r):
+"""Get the signed area of a triangle."""
+ return(q.y-p.y)*(r.x-q.x)-(q.x-p.x)*(r.y-q.y)
+
+
+def_equals(p1,p2):
+"""Check if two points are equal."""
+ returnp1.x==p2.xandp1.y==p2.y
+
+
+def_intersects(p1,q1,p2,q2):
+"""Check if two segments intersect."""
+ if(_equals(p1,q1)and_equals(p2,q2))or(_equals(p1,q2)and_equals(p2,q1)):
+ returnTrue
+
+ return_area(p1,q1,p2)>0!=_area(p1,q1,q2)>0and \
+ _area(p2,q2,p1)>0!=_area(p2,q2,q1)>0
+
+
+def_intersects_polygon(a,b):
+"""Check if a polygon diagonal intersects any polygon segments."""
+ do=True
+ p=a
+
+ whiledoorp!=a:
+ do=False
+ init_int=p.i!=a.iandp.next.i!=a.iandp.i!=b.iandp.next.i!=b.i
+ ifinit_intand_intersects(p,p.next,a,b):
+ returnTrue
+
+ p=p.next
+
+ returnFalse
+
+
+def_locally_inside(a,b):
+"""Check if a polygon diagonal is locally inside the polygon."""
+ if_area(a.prev,a,a.next)<0:
+ return_area(a,b,a.next)>=0and_area(a,a.prev,b)>=0
+ else:
+ return_area(a,b,a.prev)<0or_area(a,a.next,b)<0
+
+
+def_middle_inside(a,b):
+"""Check if the middle point of a polygon diagonal is inside a polygon."""
+ do=True
+ p=a
+ inside=False
+ px=(a.x+b.x)/2
+ py=(a.y+b.y)/2
+
+ whiledoorp!=a:
+ do=False
+ if((p.y>py)!=(p.next.y>py))and \
+ (px<(p.next.x-p.x)*(py-p.y)/(p.next.y-p.y)+p.x):
+ inside=notinside
+
+ p=p.next
+
+ returninside
+
+
+def_split_polygon(a,b):
+"""Link two polygon vertices with a bridge.
+
+ If the vertices belong to the same ring, the polygon will be split into two.
+ If one belongs to the outer ring and another to a hole, the hole will be merged
+ into a single ring.
+ """
+ a2=_Node(a.i,a.x,a.y)
+ b2=_Node(b.i,b.x,b.y)
+ an=a.next
+ bp=b.prev
+
+ a.next=b
+ b.prev=a
+
+ a2.next=an
+ an.prev=a2
+
+ b2.next=a2
+ a2.prev=b2
+
+ bp.next=b2
+ b2.prev=bp
+
+ returnb2
+
+
+def_insert_node(i,x,y,last):
+"""Create a node and optionally link it with previous one.
+
+ Linking is done in a circular doubly linked list.
+ """
+ p=_Node(i,x,y)
+
+ ifnotlast:
+ p.prev=p
+ p.next=p
+
+ else:
+ p.next=last.next
+ p.prev=last
+ last.next.prev=p
+ last.next=p
+
+ returnp
+
+
+def_remove_node(p):
+"""Remove a node from a list."""
+ p.next.prev=p.prev
+ p.prev.next=p.next
+
+ ifp.prevZ:
+ p.prevZ.nextZ=p.nextZ
+
+ ifp.nextZ:
+ p.nextZ.prevZ=p.prevZ
+
+
+class_Node(object):
+"""Node within a coordinate array."""
+
+ def__init__(self,i,x,y):
+ # vertex index in coordinates array
+ self.i=i
+
+ # vertex coordinates
+ self.x=x
+ self.y=y
+
+ # previous and next vertex nodes in a polygon ring
+ self.prev=None
+ self.next=None
+
+ # z-order curve value
+ self.z=None
+
+ # previous and next nodes in z-order
+ self.prevZ=None
+ self.nextZ=None
+
+ # indicates whether this is a steiner point
+ self.steiner=False
+