ladybug_geometry.boolean module

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.

class ladybug_geometry.boolean.BooleanPoint(x, y)[source]

Bases: object

2D Point class used in polygon boolean operations.

Parameters:

  • x – Float for X coordinate.

  • y – Float for Y coordinate

static between(point, left, right, tolerance)[source]

Get a boolean for whether a point is between two points.

Parameters:

  • point – BooleanPoint to be evaluated.

  • left – BooleanPoint for the left.

  • right – BooleanPoint for the right.

static collinear(pt1, pt2, pt3, tolerance)[source]

Get a boolean for whether 3 points are colinear.

static compare(pt1, pt2, tolerance)[source]

Get an integer for the relationship between two points.

Zero indicates equal. Positive 1 is to the right. Negative 1 is to the left.

is_equivalent(other_pt, tol)[source]

Check if this point is equivalent ot another within tolerance.

static point_above_or_on_line(point, left, right, tolerance)[source]

Get a boolean for whether a point is above or on a line.

Parameters:

  • point – BooleanPoint to be evaluated.

  • left – BooleanPoint for the left of the line segment.

  • right – BooleanPoint for the right of the line segment

class ladybug_geometry.boolean.BooleanPolygon(regions, is_inverted=False)[source]

Bases: object

Polygon class used in polygon boolean operations.

Parameters:

  • 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)

ladybug_geometry.boolean.difference(poly1, poly2, tolerance)[source]

Get a BooleanPolygon for the subtraction of poly2 from poly1.

Parameters:

  • 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.

ladybug_geometry.boolean.difference_reversed(poly1, poly2, tolerance)[source]

Get a BooleanPolygon for the subtraction of poly1 from poly2.

Parameters:

  • 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.

ladybug_geometry.boolean.intersect(poly1, poly2, tolerance)[source]

Get a BooleanPolygon for the intersection of two polygons.

Parameters:

  • 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.

ladybug_geometry.boolean.intersect_all(polygons, tolerance)[source]

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.

Parameters:

  • 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.

ladybug_geometry.boolean.split(poly1, poly2, tolerance)[source]

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.

Parameters:

  • 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.

ladybug_geometry.boolean.union(poly1, poly2, tolerance)[source]

Get a BooleanPolygon for the union of two polygons.

Note that the result will not differentiate hole polygons from boundary polygons.

Parameters:

  • 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.

ladybug_geometry.boolean.union_all(polygons, tolerance)[source]

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.

Parameters:

  • 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.

ladybug_geometry.boolean.xor(poly1, poly2, tolerance)[source]

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.

Parameters:

  • 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.