geomeppy.geom package¶

Submodules¶

geomeppy.geom.clippers module¶

Perform clipping operations on Polygons¶

PyClipper is used for clipping. It’s a wrapper for the C++ version of the Clipper library.

We implement a few of the functions of PyClipper here as .difference, .intersect, and .union methods of the Clipper2D and Clipper3D classes. These are then used as mixins for the Polygon2D and Polygon3D classes.

class geomeppy.geom.clippers.Clipper2D¶

Bases: object

This class is used to add clipping functionality to the Polygon2D class.

difference(poly)¶

Difference from another polygon.

Parameters:	poly – The clip polygon.
Returns:	A list of Polygons representing the difference.

intersect(poly)¶

Intersect with another polygon.

Parameters:	poly – The clip polygon.
Returns:	False if no intersection, otherwise a list of Polygons representing each intersection.

union(poly)¶

Union with another polygon.

Parameters:	poly – The clip polygon.
Returns:	A list of Polygons.

class geomeppy.geom.clippers.Clipper3D¶

Bases: geomeppy.geom.clippers.Clipper2D

This class is used to add clipping functionality to the Polygon3D class.

geomeppy.geom.intersect_match module¶

Intersect and match all surfaces in an IDF.

geomeppy.geom.intersect_match.intersect_idf_surfaces(idf)¶

Intersect all surfaces in an IDF.

Parameters:	idf – The IDF.

geomeppy.geom.intersect_match.match_idf_surfaces(idf)¶

Match all surfaces in an IDF.

Parameters:	idf – The IDF.

geomeppy.geom.intersect_match.sorted_tuple(m, s)¶: Used as a key for the matches.

geomeppy.geom.polygons module¶

Heavy lifting geometry for IDF surfaces.

class geomeppy.geom.polygons.Polygon(vertices)¶

Bases: geomeppy.geom.clippers.Clipper2D, collections.abc.MutableSequence

Base class for 2D and 3D polygons.

area¶

bounding_box¶

buffer(distance=None, join_style=2)¶

Returns a representation of all points within a given distance of the polygon.

Parameters:	join_style – The styles of joins between offset segments: 1 (round), 2 (mitre), and 3 (bevel).

centroid¶: The centroid of a polygon.

edges¶: A list of edges represented as Segment objects.

insert(key, value)¶: S.insert(index, value) – insert value before index

invert_orientation()¶

Reverse the order of the vertices.

This can be used to create a matching surface, e.g. the other side of a wall.

Returns:	A polygon.

is_convex¶

n_dims¶

normal_vector¶

points_matrix¶

Matrix representing the points in a polygon.

Format::: [[x1, x2,… xn] [y1, y2,… yn] [z1, z2,… zn] # all 0 for 2D polygon

vector_class¶

vertices_list¶

A list of the vertices in the format required by pyclipper.

Returns:	A list of tuples like [(x1, y1), (x2, y2),… (xn, yn)].

xs¶

ys¶

zs¶

class geomeppy.geom.polygons.Polygon2D(vertices)¶

Bases: geomeppy.geom.polygons.Polygon

Two-dimensional polygon.

n_dims = 2¶

normal_vector¶

project_to_3D(example3d)¶

Project the 2D polygon rotated into 3D space.

This is used to return a previously rotated 3D polygon back to its original orientation, or to to put polygons generated from pyclipper into the desired orientation.

Parameters:	example3D – A 3D polygon in the desired plane.
Returns:	A 3D polygon.

vector_class¶: alias of geomeppy.geom.vectors.Vector2D

zs¶

class geomeppy.geom.polygons.Polygon3D(vertices)¶

Bases: geomeppy.geom.clippers.Clipper3D, geomeppy.geom.polygons.Polygon

Three-dimensional polygon.

distance¶

Distance from the origin to the polygon.

Where v[0] * x + v[1] * y + v[2] * z = a is the equation of the plane containing the polygon (and where v is the polygon normal vector).

Returns:	The distance from the origin to the polygon.

from_wkt(wkt_poly)¶

Convert a wkt representation of a polygon to GeomEppy.

This also accounts for the possible presence of inner rings by linking them to the outer ring.

Parameters:	wkt_poly – A text representation of a polygon in well known text (wkt) format.
Returns:	A polygon.

is_clockwise(viewpoint)¶

Check if vertices are ordered clockwise

This function checks the vertices as seen from the viewpoint.

Parameters:	viewpoint – A point from which to view the polygon.
Returns:	True if vertices are ordered clockwise when observed from the given viewpoint.

is_coplanar(other)¶

Check if polygon is in the same plane as another polygon.

This includes the same plane but opposite orientation.

Parameters:	other – Another polygon.
Returns:	True if the two polygons are coplanar, else False.

is_horizontal¶

Check if polygon is in the xy plane.

Returns:	True if the polygon is in the xy plane, else False.

n_dims = 3¶

normal_vector¶

Unit normal vector perpendicular to the polygon in the outward direction.

We use Newell’s Method since the cross-product of two edge vectors is not valid for concave polygons. https://www.opengl.org/wiki/Calculating_a_Surface_Normal#Newell.27s_Method

normalize_coords(ggr)¶

Order points, respecting the global geometry rules

Parameters:	ggr – EnergyPlus GlobalGeometryRules object.
Returns:	The normalized polygon.

order_points(starting_position)¶

Reorder the vertices based on a starting position rule.

Parameters:	starting_position – The string that defines vertex starting position in EnergyPlus.
Returns:	The reordered polygon.

outside_point(entry_direction='counterclockwise')¶

Return a point outside the zone to which the surface belongs.

The point will be outside the zone, respecting the global geometry rules for vertex entry direction.

Parameters:	entry_direction – Either “clockwise” or “counterclockwise”, as seen from outside the space.
Returns:	A point vector.

project_to_2D()¶

Project the 3D polygon into 2D space.

This is so that we can perform operations on it using pyclipper library.

Project onto either the xy, yz, or xz plane. (We choose the one that avoids degenerate configurations, which is the purpose of proj_axis.)

Returns:	A 2D polygon.

projection_axis¶

An axis which will not lead to a degenerate surface.

Returns:	The axis index.

vector_class¶: alias of geomeppy.geom.vectors.Vector3D

zs¶

geomeppy.geom.polygons.bounding_box(polygons)¶

The bounding box which encompasses all of the polygons in the x,y plane.

Parameters:	polygons – A list of polygons.
Returns:	A 2D polygon.

geomeppy.geom.polygons.break_polygons(poly, hole)¶

Break up a surface with a hole in it.

This produces two surfaces, neither of which have a hole in them.

Parameters:	poly – The surface with a hole in. hole – The hole.
Returns:	Two Polygon3D objects.

geomeppy.geom.polygons.intersect(poly1, poly2)¶

Calculate the polygons to represent the intersection of two polygons.

Parameters:	poly1 – The first polygon. poly2 – The second polygon.
Returns:	A list of unique polygons.

geomeppy.geom.polygons.is_convex_polygon(polygon)¶

Return True if the polynomial defined by the sequence of 2D points is ‘strictly convex’: points are valid, side lengths non- zero, interior angles are strictly between zero and a straight angle, and the polygon does not intersect itself.

See: https://stackoverflow.com/a/45372025/1706564

:: NOTES:

Algorithm: the signed changes of the direction angles from one side to the next side must be all positive or all negative, and their sum must equal plus-or-minus one full turn (2 pi radians). Also check for too few, invalid, or repeated points.
No check is explicitly done for zero internal angles (180 degree direction-change angle) as this is covered in other ways, including the n < 3 check.

geomeppy.geom.polygons.is_hole(surface, possible_hole)¶

Identify if an intersection is a hole in the surface.

Check the intersection touches an edge of the surface. If it doesn’t then it represents a hole, and this needs further processing into valid EnergyPlus surfaces.

Parameters:	surface – The first surface. possible_hole – The intersection into the surface.
Returns:	True if the possible hole is a hole in the surface.

geomeppy.geom.polygons.normalize_coords(poly, outside_pt, ggr=None)¶

Put coordinates into the correct format for EnergyPlus dependent on Global Geometry Rules (GGR).

Parameters:	poly – Polygon with new coordinates, but not yet checked for compliance with GGR. outside_pt – An outside point of the new polygon. ggr – EnergyPlus GlobalGeometryRules object.
Returns:	The normalized polygon.

geomeppy.geom.polygons.project(pt, proj_axis)¶

Project point pt onto either the xy, yz, or xz plane

We choose the one that avoids degenerate configurations, which is the purpose of proj_axis. See http://stackoverflow.com/a/39008641/1706564

geomeppy.geom.polygons.project_inv(pt, proj_axis, a, v)¶

Returns the vector w in the surface’s plane such that project(w) equals x.

See http://stackoverflow.com/a/39008641/1706564

Parameters:	pt – A two-dimensional point. proj_axis – The axis to project into. a – Distance to the origin for the plane to project into. v – Normal vector of the plane to project into.
Returns:	The transformed point.

geomeppy.geom.polygons.project_to_2D(vertices, proj_axis)¶

Project a 3D polygon into 2D space.

Parameters:	vertices – The three-dimensional vertices of the polygon. proj_axis – The axis to project into.
Returns:	The transformed vertices.

geomeppy.geom.polygons.project_to_3D(vertices, proj_axis, a, v)¶

Project a 2D polygon into 3D space.

Parameters:	vertices – The two-dimensional vertices of the polygon. proj_axis – The axis to project into. a – Distance to the origin for the plane to project into. v – Normal vector of the plane to project into.
Returns:	The transformed vertices.

geomeppy.geom.polygons.section(first, last, coords)¶

geomeppy.geom.polygons.set_entry_direction(poly, outside_pt, ggr=None)¶

Check and set entry direction for a polygon.

Parameters:	poly – A polygon. outside_pt – A point beyond the outside face of the polygon. ggr – EnergyPlus global geometry rules
Returns:	A polygon with the vertices correctly oriented.

geomeppy.geom.polygons.set_starting_position(poly, ggr=None)¶: Check and set starting position.

geomeppy.geom.segments module¶

Segment class, representing a line segment.

class geomeppy.geom.segments.Segment(*vertices)¶

Bases: object

Line segment in 3D.

geomeppy.geom.surfaces module¶

A collection of functions which act on surfaces or lists of surfaces.

geomeppy.geom.surfaces.get_adjacencies(surfaces)¶

Create a dictionary mapping surfaces to their adjacent surfaces.

Parameters:	surfaces – A mutable list of surfaces.
Returns:	Mapping of surfaces to adjacent surfaces.

geomeppy.geom.surfaces.getidfplanes(surfaces)¶

Fast access data structure for potentially matched surfaces.

Get a data structure populated with all the surfaces in the IDF, keyed by their distance from the origin, and their normal vector.

Parameters:	surfaces – List of all the surfaces.
Returns:	Mapping to look up IDF surfaces.

geomeppy.geom.surfaces.minimal_set(polys)¶

Remove overlaps from a set of polygons.

Parameters:	polys – List of polygons.
Returns:	List of polygons with no overlaps.

geomeppy.geom.surfaces.populate_adjacencies(adjacencies, s1, s2)¶

Update the adjacencies dict with any intersections between two surfaces.

Parameters:	adjacencies – Dict to contain lists of adjacent surfaces. s1 – Object representing an EnergyPlus surface. s2 – Object representing an EnergyPlus surface.
Returns:	An updated dict of adjacencies.

geomeppy.geom.surfaces.set_coords(surface, coords, ggr)¶

Update the coordinates of a surface.

Parameters:	surface – The surface to modify. coords – The new coordinates as lists of [x,y,z] lists. ggr – Global geometry rules.

geomeppy.geom.surfaces.set_matched_surfaces(surface, matched)¶

Set boundary conditions for two adjoining surfaces.

Parameters:	surface – The first surface. matched – The second surface.

geomeppy.geom.surfaces.set_unmatched_surface(surface, vector)¶

Set boundary conditions for a surface which does not adjoin another one.

Parameters:	surface – The surface. vector – The surface normal vector.

geomeppy.geom.transformations module¶

A module to handle translations, using Christopher Gohlke’s transforms3d as far as possible, but also trying to respect the intent of the algorithms used in OpenStudio for the sake of consistency between tools based on EnergyPlus.

class geomeppy.geom.transformations.Transformation(mat=None)¶: Bases: object

geomeppy.geom.transformations.align_face(polygon)¶

Transformation to align face with z-axis.

Parameters:	polygon – Polygon to be aligned.
Returns:	Polygon3D aligned with the z-axis.

geomeppy.geom.transformations.invert_align_face(original, poly2)¶

Transformation to align face with original position.

Parameters:	original – Polygon in the desired orientation. poly2 – Polygon previously aligned with align_face.
Returns:	Polygon returned to the original orientation.

geomeppy.geom.vectors module¶

2D and 3D vector classes.

These are used to represent points in 2D and 3D, as well as directions for translations.

class geomeppy.geom.vectors.Vector2D(*args)¶

Bases: collections.abc.Sized, collections.abc.Iterable, typing.Generic

Two dimensional point.

as_array(dims=3)¶

Convert a point to a numpy array.

Converts a Vector3D to a numpy.array([x,y,z]) or a Vector2D to a numpy.array([x,y]). Ensures all values are floats since some other types cause problems in pyclipper (notably where sympy.Zero is used to represent 0.0).

Parameters:	pt – The point to convert. dims – Number of dimensions {default : 3}.
Returns:	Vector as a Numpy array.

as_tuple(dims=3)¶

Convert a point to a numpy array.

Convert a Vector3D to an (x,y,z) tuple or a Vector2D to an (x,y) tuple. Ensures all values are floats since some other types cause problems in pyclipper (notably where sympy.Zero is used to represent 0.0).

Parameters:	pt – The point to convert. dims – Number of dimensions {default : 3}.
Returns:	Vector as a tuple.

closest(poly)¶

Find the closest vector in a polygon.

Parameters:	poly – Polygon or Polygon3D

cross(other)¶

dot(other)¶

invert()¶

length¶: The length of a vector.

normalize()¶

relative_distance(v2)¶

A distance function for sorting vectors by distance.

This only provides relative distance, not actual distance since we only use it for sorting.

Parameters:	v2 – Another vector.
Returns:	Relative distance between two point vectors.

set_length(new_length)¶

class geomeppy.geom.vectors.Vector3D(x, y, z=0)¶

Bases: geomeppy.geom.vectors.Vector2D

Three dimensional point.

geomeppy.geom.vectors.inverse_vector(v)¶

Convert a vector to the same vector but in the opposite direction

Parameters:	v – The vector.
Returns:	The vector reversed.