honeybee.face module¶

Honeybee Face.

class honeybee.face.Face(identifier, geometry, type=None, boundary_condition=None)[source]¶

Bases: _BaseWithShade

A single planar face.

Parameters:

identifier – Text string for a unique Face ID. Must be < 100 characters and not contain any spaces or special characters.
geometry – A ladybug-geometry Face3D.
type – Face type. Default varies depending on the direction that the Face geometry is points. RoofCeiling = pointing upward within 30 degrees Wall = oriented vertically within +/- 60 degrees Floor = pointing downward within 30 degrees
boundary_condition – Face boundary condition (Outdoors, Ground, etc.) Default is Outdoors unless all vertices of the geometry lie below the below the XY plane, in which case it will be set to Ground.

Properties:

identifier
display_name
type
boundary_condition
apertures
doors
sub_faces
indoor_shades
outdoor_shades
parent
has_parent
has_sub_faces
can_be_ground
geometry
punched_geometry
vertices
punched_vertices
upper_left_vertices
normal
center
area
perimeter
min
max
aperture_area
aperture_ratio
tilt
altitude
azimuth
is_exterior
type_color
bc_color
user_data

ToString()¶: Overwrite .NET ToString.

add_aperture(aperture)[source]¶

Add an Aperture to this face.

This method does not check the co-planarity between this Face and the Aperture or whether the Aperture has all vertices within the boundary of this Face. To check this, the Face3D.is_sub_face() method can be used with the Aperture and Face geometry before using this method or the are_sub_faces_valid() method can be used afterwards.

Parameters:: aperture – An Aperture to add to this face.

add_apertures(apertures)[source]¶: Add a list of Apertures to this face.

add_door(door)[source]¶

Add a Door to this face.

This method does not check the co-planarity between this Face and the Door or whether the Door has all vertices within the boundary of this Face. To check this, the Face3D.is_sub_face() method can be used with the Door and Face geometry before using this method or the are_sub_faces_valid() method can be used afterwards.

Parameters:: door – A Door to add to this face.

add_doors(doors)[source]¶: Add a list of Doors to this face.

add_indoor_shade(shade)¶

Add a Shade object to be added to the indoors of this object.

Indoor Shade objects can be used to represent furniture, the interior portion of light shelves, the interior part of mullions, etc. For representing finely detailed objects like blinds or roller shades, it may be more appropriate to model them as materials assigned to Aperture properties (like Radiance materials or Energy constructions).

Parameters:: shade – A Shade object to add to the indoors of this object.

add_indoor_shades(shades)¶

Add a list of Shade objects to the indoors of this object.

Parameters:: shades – A list of Shade objects to add to the indoors of this object.

add_outdoor_shade(shade)¶

Add a Shade object to the outdoors of this object.

Outdoor Shade objects can be used to represent balconies, outdoor furniture, overhangs, light shelves, fins, the exterior part of mullions, etc. For representing larger shade objects like trees or other buildings, it may be more appropriate to add them to the Model as orphaned_shades without a specific parent object.

Parameters:: shade – A Shade object to add to the outdoors of this object.

add_outdoor_shades(shades)¶

Add a list of Shade objects to the outdoors of this object.

Parameters:: shades – A list of Shade objects to add to the outdoors of this object.

add_prefix(prefix)[source]¶

Change the identifier of this object and child objects by inserting a prefix.

This is particularly useful in workflows where you duplicate and edit a starting object and then want to combine it with the original object into one Model (like making a model of repeated rooms) since all objects within a Model must have unique identifiers.

Parameters:: prefix – Text that will be inserted at the start of this object’s (and child objects’) identifier and display_name. It is recommended that this prefix be short to avoid maxing out the 100 allowable characters for honeybee identifiers.

add_sub_face(sub_face)[source]¶: Add an Apertures or Doors to this face.

add_sub_faces(sub_faces)[source]¶: Add a list of Apertures and/or Doors to this face.

aperture_by_width_height(width, height, sill_height=1, aperture_identifier=None)[source]¶

Add a single rectangular aperture to the center of this Face.

A rectangular window with the input width and height will always be added by this method regardless of whether this parent Face contains a recognizable rectangular portion or not. Furthermore, this method preserves any existing apertures on the Face.

While the resulting aperture will always be in the plane of this Face, this method will not check to ensure that the aperture has all of its vertices completely within the boundary of this Face or that it does not intersect with other apertures in the Face. The are_sub_faces_valid() method can be used afterwards to check this.

Parameters:

width – A number for the Aperture width.
height – A number for the Aperture height.
sill_height – A number for the sill height. (Default: 1).
aperture_identifier – Optional string for the aperture identifier. If None, the default will follow the convention “[face_identifier]_Glz[count]” where [count] is one more than the current number of apertures in the face.

Returns:

The new Aperture object that has been generated.

Usage:

room = Room.from_box(3.0, 6.0, 3.2, 180)
room[1].aperture_by_width_height(2, 2, .7)  # aperture in front
room[2].aperture_by_width_height(4, 1.5, .5)  # aperture on right
room[2].aperture_by_width_height(4, 0.5, 2.2)  # aperture on right

apertures_by_ratio(ratio, tolerance=0.01, rect_split=True)[source]¶

Add apertures to this Face given a ratio of aperture area to face area.

Note that this method removes any existing apertures and doors on the Face. This method attempts to generate as few apertures as necessary to meet the ratio.

Parameters:

ratio – A number between 0 and 1 (but not perfectly equal to 1) for the desired ratio between aperture area and face area.
tolerance – The maximum difference between point values for them to be considered the same. This is used in the event that this face is concave and an attempt to subdivide the face into a rectangle is made. It does not affect the ability to produce apertures for convex Faces. Default: 0.01, suitable for objects in meters.
rect_split – Boolean to note whether rectangular portions of base Face should be extracted before scaling them to create apertures. For gabled geometries, the resulting apertures will consist of one rectangle and one triangle, which can often look more realistic and is a better input for engines like EnergyPlus that cannot model windows with more than 4 vertices. However, if a single pentagonal window is desired for a gabled shape, this input can be set to False to produce such a result.

Usage:

room = Room.from_box(3.0, 6.0, 3.2, 180)
room.faces[1].apertures_by_ratio(0.4)

apertures_by_ratio_gridded(ratio, x_dim, y_dim=None, tolerance=0.01)[source]¶

Add apertures to this face given a ratio of aperture area to face area.

Note that this method removes any existing apertures on the Face.

Apertures will be arranged in a grid derived from this face’s plane. 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. This is particularly useful for generating skylights based on a glazing ratio.

If the x_dim and/or y_dim are too large for this face, this method will return essentially the same result as the apertures_by_ratio method.

Parameters:

ratio – A number between 0 and 1 for the ratio between the area of the apertures 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.
tolerance – The maximum difference between point values for them to be considered a part of a rectangle. Default: 0.01, suitable for objects in meters.

Usage:

room = Room.from_box(3.0, 6.0, 3.2, 180)
room.faces[-1].apertures_by_ratio_gridded(0.05, 3)

apertures_by_ratio_rectangle(ratio, aperture_height, sill_height, horizontal_separation, vertical_separation=0, tolerance=0.01)[source]¶

Add apertures to this face given a ratio of aperture area to face area.

Note that this method removes any existing apertures on the Face.

This function is virtually equivalent to the apertures_by_ratio method but any rectangular portions of this face will produce customizable rectangular apertures using the other inputs (aperture_height, sill_height, horizontal_separation, vertical_separation).

Parameters:

ratio – A number between 0 and 0.95 for the ratio between the area of the apertures and the area of this face.
aperture_height – A number for the target height of the output apertures. Note that, if the ratio is too large for the height, the ratio will take precedence and the actual aperture_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 apertures. Note that, if the ratio is too large for the height, the ratio will take precedence and the sill_height will be smaller than this value.
horizontal_separation – A number for the target separation between individual aperture center lines. If this number is larger than the parent rectangle base, only one aperture will be produced.
vertical_separation – An optional number to create a single vertical separation between top and bottom apertures. The default is 0 for no separation.
tolerance – The maximum difference between point values for them to be considered a part of a rectangle. Default: 0.01, suitable for objects in meters.

Usage:

room = Room.from_box(3.0, 6.0, 3.2, 180)
room.faces[1].apertures_by_ratio_rectangle(0.4, 2, 0.9, 3)

apertures_by_width_height_rectangle(aperture_height, aperture_width, sill_height, horizontal_separation, tolerance=0.01)[source]¶

Add repeating apertures to this face given the aperture width and height.

Note that this method removes any existing apertures on the Face.

Note that this method will effectively fill any rectangular portions of this Face with apertures at the specified width, height and separation. If no rectangular portion of this Face can be identified, no apertures will be added.

Parameters:

aperture_height – A number for the target height of the apertures.
aperture_width – A number for the target width of the apertures.
sill_height – A number for the target height above the bottom edge of the rectangle to start the apertures. If the aperture_height is too large for the sill_height to fit within the rectangle, the aperture_height will take precedence.
horizontal_separation – A number for the target separation between individual apertures center lines. If this number is larger than the parent rectangle base, only one aperture will be produced.
tolerance – The maximum difference between point values for them to be considered a part of a rectangle. Default: 0.01, suitable for objects in meters.

Usage:

room = Room.from_box(5.0, 10.0, 3.2, 180)
room.faces[1].apertures_by_width_height_rectangle(1.5, 2, 0.8, 2.5)

cardinal_direction(north_vector=Vector2D(0.00, 1.00))[source]¶

Get text description for the cardinal direction that the face is pointing.

Will be one of the following: (‘North’, ‘NorthEast’, ‘East’, ‘SouthEast’, ‘South’, ‘SouthWest’, ‘West’, ‘NorthWest’).

Parameters:: north_vector – A ladybug_geometry Vector2D for the north direction. Default is the Y-axis (0, 1).

check_apertures_valid(tolerance=0.01, angle_tolerance=1, raise_exception=True, detailed=False)[source]¶

Check that apertures are co-planar with this Face within the Face boundary.

Note this does not check the planarity of the apertures themselves, whether they self-intersect, or whether they have a non-zero area.

Parameters:

tolerance – The minimum difference between the coordinate values of two vertices at which they can be considered equivalent. Default: 0.01, suitable for objects in meters.
angle_tolerance – The max angle in degrees that the plane normals can differ from one another in order for them to be considered coplanar. Default: 1 degree.
raise_exception – Boolean to note whether a ValueError should be raised if an aperture is not valid.
detailed – Boolean for whether the returned object is a detailed list of dicts with error info or a string with a message. (Default: False).

Returns:

A string with the message or a list with dictionaries if detailed is True.

check_doors_valid(tolerance=0.01, angle_tolerance=1, raise_exception=True, detailed=False)[source]¶

Check that doors are co-planar with this Face within the Face boundary.

Note this does not check the planarity of the doors themselves, whether they self-intersect, or whether they have a non-zero area.

Parameters:

tolerance – The minimum difference between the coordinate values of two vertices at which they can be considered equivalent. Default: 0.01, suitable for objects in meters.
angle_tolerance – The max angle in degrees that the plane normals can differ from one another in order for them to be considered coplanar. Default: 1 degree.
raise_exception – Boolean to note whether a ValueError should be raised if an door is not valid.
detailed – Boolean for whether the returned object is a detailed list of dicts with error info or a string with a message. (Default: False).

Returns:

A string with the message or a list with dictionaries if detailed is True.

check_planar(tolerance=0.01, raise_exception=True, detailed=False)[source]¶

Check whether all of the Face’s vertices lie within the same plane.

Parameters:

tolerance – The minimum distance between a given vertex and a the object’s plane at which the vertex is said to lie in the plane. Default: 0.01, suitable for objects in meters.
raise_exception – Boolean to note whether an ValueError should be raised if a vertex does not lie within the object’s plane.
detailed – Boolean for whether the returned object is a detailed list of dicts with error info or a string with a message. (Default: False).

Returns:

A string with the message or a list with a dictionary if detailed is True.

check_self_intersecting(tolerance=0.01, raise_exception=True, detailed=False)[source]¶

Check whether the edges of the Face intersect one another (like a bowtie).

Note that objects that have duplicate vertices will not be considered self-intersecting and are valid in honeybee.

Parameters:

tolerance – The minimum difference between the coordinate values of two vertices at which they can be considered equivalent. Default: 0.01, suitable for objects in meters.
raise_exception – If True, a ValueError will be raised if the object intersects with itself. Default: True.
detailed – Boolean for whether the returned object is a detailed list of dicts with error info or a string with a message. (Default: False).

Returns:

A string with the message or a list with a dictionary if detailed is True.

check_sub_faces_overlapping(tolerance=0.01, raise_exception=True, detailed=False)[source]¶

Check that this Face’s sub-faces do not overlap with one another.

Parameters:

tolerance – The minimum distance that two sub-faces must overlap in order for them to be considered overlapping and invalid. (Default: 0.01, suitable for objects in meters).
raise_exception – Boolean to note whether a ValueError should be raised if a sub-faces overlap with one another.
detailed – Boolean for whether the returned object is a detailed list of dicts with error info or a string with a message. (Default: False).

Returns:

A string with the message or a list with dictionaries if detailed is True.

check_sub_faces_valid(tolerance=0.01, angle_tolerance=1, raise_exception=True, detailed=False)[source]¶

Check that sub-faces are co-planar with this Face within the Face boundary.

Note this does not check the planarity of the sub-faces themselves, whether they self-intersect, or whether they have a non-zero area.

Parameters:

tolerance – The minimum difference between the coordinate values of two vertices at which they can be considered equivalent. Default: 0.01, suitable for objects in meters.
angle_tolerance – The max angle in degrees that the plane normals can differ from one another in order for them to be considered coplanar. Default: 1 degree.
raise_exception – Boolean to note whether a ValueError should be raised if an sub-face is not valid.
detailed – Boolean for whether the returned object is a detailed list of dicts with error info or a string with a message. (Default: False).

Returns:

A string with the message or a list with dictionaries if detailed is True.

check_upside_down(angle_tolerance=1, raise_exception=True, detailed=False)[source]¶

Check whether the face is pointing in the correct direction for the face type.

This method will only report Floors that are pointing upwards or RoofCeilings that are pointed downwards. These cases are likely modeling errors and are in danger of having their vertices flipped by EnergyPlus, causing them to not see the sun.

Parameters:

angle_tolerance – The max angle in degrees that the Face normal can differ from up or down before it is considered a case of a downward pointing RoofCeiling or upward pointing Floor. Default: 1 degree.
raise_exception – Boolean to note whether an ValueError should be raised if the Face is an an upward pointing Floor or a downward pointing RoofCeiling.
detailed – Boolean for whether the returned object is a detailed list of dicts with error info or a string with a message. (Default: False).

Returns:

A string with the message or a list with a dictionary if detailed is True.

display_dict()[source]¶: Get a list of DisplayFace3D dictionaries for visualizing the object.

duplicate()¶: Get a copy of this object.

fix_invalid_sub_faces(trim_with_parent=True, union_overlaps=True, offset_distance=0.05, tolerance=0.01)[source]¶

Fix invalid Apertures and Doors on this face by performing two operations.

First, sub-faces that extend past their parent Face are trimmed with the parent and will have their edges offset towards the inside of the Face. Second, any sub-faces that overlap or touch one another will be unioned into a single Aperture or Door.

Parameters:

trim_with_parent – Boolean to note whether the fixing operation should check all sub-faces that extend past their parent and trim them, offsetting them towards the inside of the Face. (Default: True).
union_overlaps – Boolean to note whether the fixing operation should check all sub-faces that overlap with one another and union any sub-faces together that overlap. (Default: True).
offset_distance –
Distance from the edge of the parent Face that the sub-faces will be offset to in order to make them valid. This should be larger than the tolerance. (Default: 0.05, suitable for

objects in meters).
tolerance – The minimum difference between point values for them to be considered the distinct. (Default: 0.01, suitable for objects in meters).

classmethod from_dict(data)[source]¶

Initialize an Face from a dictionary.

Parameters:: data – A dictionary representation of an Face object.

classmethod from_vertices(identifier, vertices, type=None, boundary_condition=None)[source]¶

Create a Face from vertices with each vertex as an iterable of 3 floats.

Note that this method is not recommended for a face with one or more holes since the distinction between hole vertices and boundary vertices cannot be derived from a single list of vertices.

Parameters:

identifier – Text string for a unique Face ID. Must be < 100 characters and not contain any spaces or special characters.
vertices – A flattened list of 3 or more vertices as (x, y, z).
type – Face type object (eg. Wall, Floor).
boundary_condition – Boundary condition object (eg. Outdoors, Ground)

horizontal_orientation(north_vector=Vector2D(0.00, 1.00))[source]¶

Get a number between 0 and 360 for the orientation of the face in degrees.

0 = North, 90 = East, 180 = South, 270 = West

Parameters:: north_vector – A ladybug_geometry Vector2D for the north direction. Default is the Y-axis (0, 1).

is_geo_equivalent(face, tolerance=0.01)[source]¶

Get a boolean for whether this object is geometrically equivalent to another.

This will also check all child Apertures and Doors for equivalency but not assigned shades.

Parameters:

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.

louvers(depth, louver_count=None, distance=None, offset=0, angle=0, contour_vector=Vector2D(0.00, 1.00), flip_start_side=False, indoor=False, tolerance=0.01, base_name=None)[source]¶

Add a series of louvered Shade objects over this Face.

If both louver_count and distance are None, this method will add a single louver shade following the other criteria.

Parameters:

depth – A number for the depth to extrude the louvers.
louver_count – A positive integer for the number of louvers to generate. If None, louvers will be generated to fill the Face at the specified distance. (Default: None).
distance – A number for the approximate distance between each louver. If None, louvers will be generated to fill the Face at the specified louver_count. (Default: None).
offset – A number for the distance to louvers from this Face. Default is 0 for no offset.
angle – A number for the for an angle to rotate the louvers in degrees. Positive numbers indicate a downward rotation while negative numbers indicate an upward rotation. Default 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. Default: (0, 1).
flip_start_side – Boolean to note whether the side the louvers start from should be flipped. Default is False to have louvers on top or right. Setting to True will start contours on the bottom or left.
indoor – Boolean for whether louvers should be generated facing the opposite direction of the Face normal (typically meaning indoor geometry). Default: False.
tolerance – An optional value to remove any louvers with a length less than the tolerance. Default: 0.01, suitable for objects in meters.
base_name – Optional base identifier for the shade objects. If None, the default is InShd or OutShd depending on whether indoor is True.

Returns:

A list of the new Shade objects that have been generated.

louvers_by_count(louver_count, depth, offset=0, angle=0, contour_vector=Vector2D(0.00, 1.00), flip_start_side=False, indoor=False, tolerance=0.01, base_name=None)[source]¶

Add louvered Shade objects over this Face to hit a target louver_count.

Parameters:

louver_count – A positive integer for the number of louvers to generate.
depth – A number for the depth to extrude the louvers.
offset – A number for the distance to louvers from this Face. Default is 0 for no offset.
angle – A number for the for an angle to rotate the louvers in degrees. Positive numbers indicate a downward rotation while negative numbers indicate an upward rotation. Default 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. Default: (0, 1).
flip_start_side – Boolean to note whether the side the louvers start from should be flipped. Default is False to have louvers on top or right. Setting to True will start contours on the bottom or left.
indoor – Boolean for whether louvers should be generated facing the opposite direction of the Face normal (typically meaning indoor geometry). Default: False.
tolerance – An optional value to remove any louvers with a length less than the tolerance. Default: 0.01, suitable for objects in meters.
base_name – Optional base identifier for the shade objects. If None, the default is InShd or OutShd depending on whether indoor is True.

Returns:

A list of the new Shade objects that have been generated.

louvers_by_distance_between(distance, depth, offset=0, angle=0, contour_vector=Vector2D(0.00, 1.00), flip_start_side=False, indoor=False, tolerance=0.01, max_count=None, base_name=None)[source]¶

Add louvered Shade objects over this Face to hit a target distance between.

Parameters:

distance – A number for the approximate distance between each louver.
depth – A number for the depth to extrude the louvers.
offset – A number for the distance to louvers from this Face. Default is 0 for no offset.
angle – A number for the for an angle to rotate the louvers in degrees. Positive numbers indicate a downward rotation while negative numbers indicate an upward rotation. Default 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. Default: (0, 1).
flip_start_side – Boolean to note whether the side the louvers start from should be flipped. Default is False to have contours on top or right. Setting to True will start contours on the bottom or left.
indoor – Boolean for whether louvers should be generated facing the opposite direction of the Face normal (typically meaning indoor geometry). Default: False.
tolerance – An optional value to remove any louvers with a length less than the tolerance. Default: 0.01, suitable for objects in meters.
max_count – Optional integer to set the maximum number of louvers that will be generated. If None, louvers will cover the entire face.
base_name – Optional base identifier for the shade objects. If None, the default is InShd or OutShd depending on whether indoor is True.

Returns:

A list of the new Shade objects that have been generated.

merge_neighboring_sub_faces(merge_distance=0.05, tolerance=0.01)[source]¶

Merge neighboring Apertures and/or Doors on this Face together.

This method is particularly useful for simplifying Apertures in concave Faces since trying to simplify such Apertures down to a ratio will produce a triangulated result that is not particularly clean.

Parameters:

merge_distance – Distance between Apertures and/or Doors at which point they will be merged into a single Aperture. When this value is less than or equal to the tolerance, apertures will only be merged if they touch one another. (Default: 0.05, suitable for objects in meters).
tolerance – The minimum difference between point values for them to be considered the distinct. (Default: 0.01, suitable for objects in meters).

move(moving_vec)[source]¶

Move this Face along a vector.

Parameters:: moving_vec – A ladybug_geometry Vector3D with the direction and distance to move the face.

move_shades(moving_vec)¶

Move all indoor and outdoor shades assigned to this object along a vector.

Parameters:: moving_vec – A ladybug_geometry Vector3D with the direction and distance to move the shades.

offset_aperture_edges(offset_distance, tolerance=0.01)[source]¶

Offset the edges of all apertures by a certain distance.

This is useful for translating between interfaces that expect the window frame to be included within or excluded from the geometry of the Aperture.

Note that this operation can often create Apertures that collide with one another or extend past the parent Face. So it may be desirable to run the fix_invalid_sub_faces after using this method.

Parameters:

offset_distance – Distance with which the edges of each Aperture will be offset from the original geometry. Positive values will offset the geometry outwards and negative values will offset the geometries inwards.
tolerance – The minimum difference between point values for them to be considered the distinct. (Default: 0.01, suitable for objects in meters).

overhang(depth, angle=0, indoor=False, tolerance=0.01, base_name=None)[source]¶

Add an overhang to this Face.

Parameters:

depth – A number for the overhang depth.
angle – A number for the for an angle to rotate the overhang in degrees. Positive numbers indicate a downward rotation while negative numbers indicate an upward rotation. Default is 0 for no rotation.
indoor – Boolean for whether the overhang should be generated facing the opposite direction of the aperture normal (typically meaning indoor geometry). Default: False.
tolerance – An optional value to not add the overhang if it has a length less than the tolerance. Default: 0.01, suitable for objects in meters.
base_name – Optional base identifier for the shade objects. If None, the default is InOverhang or OutOverhang depending on whether indoor is True.

Returns:

A list of the new Shade objects that have been generated.

project_and_add_sub_face(sub_face, angle_tolerance=None)[source]¶

Project an Aperture or Door into this Face and add it to the Face.

Parameters:

sub_face – An Aperture or Door to be projected into this Face and added to it.
angle_tolerance – An optional angle tolerance in degrees to be used to check whether the plane of the sub-face is parallel with this Face before merging.If None, no check will be performed. (Default: None).

rectangularize_apertures(subdivision_distance=None, max_separation=None, merge_all=False, tolerance=0.01, angle_tolerance=1.0)[source]¶

Convert all Apertures on this Face to be rectangular.

This is useful when exporting to simulation engines that only accept rectangular window geometry. This method will always result ing Rooms where all Apertures are rectangular. However, if the subdivision_distance is not set, some Apertures may extend past the parent Face or may collide with one another.

Parameters:

subdivision_distance – A number for the resolution at which the non-rectangular Apertures will be subdivided into smaller rectangular units. Specifying a number here ensures that the resulting rectangular Apertures do not extend past the parent Face or collide with one another. If None, all non-rectangular Apertures will be rectangularized by taking the bounding rectangle around the Aperture. (Default: None).
max_separation – A number for the maximum distance between non-rectangular Apertures at which point the Apertures will be merged into a single rectangular geometry. This is often helpful when there are several triangular Apertures that together make a rectangle when they are merged across their frames. In such cases, this max_separation should be set to a value that is slightly larger than the window frame. If None, no merging of Apertures will happen before they are converted to rectangles. (Default: None).
merge_all – Boolean to note whether all apertures should be merged before they are rectangularized. If False, only non-rectangular apertures will be merged before rectangularization. Note that this argument has no effect when the max_separation is None. (Default: False).
tolerance – The maximum difference between point values for them to be considered equivalent. (Default: 0.01, suitable for objects in meters).
angle_tolerance – The max angle in degrees that the corners of the rectangle can differ from a right angle before it is not considered a rectangle. (Default: 1).

Returns:

True if the Apertures were changed. False if they were unchanged.

reflect(plane)[source]¶

Reflect this Face across a plane.

Parameters:: plane – A ladybug_geometry Plane across which the object will be reflected.

reflect_shades(plane)¶

Reflect all indoor and outdoor shades assigned to this object across a plane.

Parameters:: plane – A ladybug_geometry Plane across which the object will be reflected.

remove_apertures()[source]¶: Remove all apertures from the face.

remove_colinear_vertices(tolerance=0.01)[source]¶

Remove all colinear and duplicate vertices from this object’s geometry.

Note that this does not affect any assigned Apertures, Doors or Shades.

Parameters:: tolerance – The minimum distance between a vertex and the boundary segments at which point the vertex is considered colinear. Default: 0.01, suitable for objects in meters.

remove_degenerate_sub_faces(tolerance=0.01)[source]¶

Remove colinear vertices from sub-faces and eliminate degenerate ones.

Parameters:: tolerance – The minimum distance between a vertex and the boundary segments at which point the vertex is considered colinear. Default: 0.01, suitable for objects in meters.

remove_doors()[source]¶: Remove all doors from the face.

remove_indoor_shades()¶: Remove all indoor shades assigned to this object.

remove_outdoor_shades()¶: Remove all outdoor shades assigned to this object.

remove_shades()¶: Remove all indoor and outdoor shades assigned to this object.

remove_sub_faces()[source]¶: Remove all apertures and doors from the face.

replace_apertures(apertures)[source]¶: Replace all sub-faces assigned to this Face with a new list of Apertures.

rotate(axis, angle, origin)[source]¶

Rotate this Face by a certain angle around an axis and origin.

Parameters:

axis – A ladybug_geometry Vector3D axis representing the axis of rotation.
angle – An angle for rotation in degrees.
origin – A ladybug_geometry Point3D for the origin around which the object will be rotated.

rotate_shades(axis, angle, origin)¶

Rotate all indoor and outdoor shades assigned to this object.

Parameters:

axis – A ladybug_geometry Vector3D axis representing the axis of rotation.
angle – An angle for rotation in degrees.
origin – A ladybug_geometry Point3D for the origin around which the object will be rotated.

rotate_xy(angle, origin)[source]¶

Rotate this Face counterclockwise in the world XY plane by a certain angle.

Parameters:

angle – An angle in degrees.
origin – A ladybug_geometry Point3D for the origin around which the object will be rotated.

rotate_xy_shades(angle, origin)¶

Rotate all indoor and outdoor shades counterclockwise in the world XY plane.

Parameters:

angle – An angle in degrees.
origin – A ladybug_geometry Point3D for the origin around which the object will be rotated.

scale(factor, origin=None)[source]¶

Scale this Face by a factor from an origin point.

Parameters:

factor – A number representing how much the object should be scaled.
origin – A ladybug_geometry Point3D representing the origin from which to scale. If None, it will be scaled from the World origin (0, 0, 0).

scale_shades(factor, origin=None)¶

Scale all indoor and outdoor shades assigned to this object by a factor.

Parameters:

factor – A number representing how much the object should be scaled.
origin – A ladybug_geometry Point3D representing the origin from which to scale. If None, it will be scaled from the World origin (0, 0, 0).

set_adjacency(other_face, tolerance=0.01)[source]¶

Set this face adjacent to another and set the other face adjacent to this one.

Note that this method does not verify whether the other_face geometry is co-planar or compatible with this one so it is recommended that either the Face3D.is_centered_adjacent() or the Face3D.is_geometrically_equivalent() method be used with this face geometry and the other_face geometry before using this method in order to verify these criteria.

However, this method will use the proximity of apertures and doors within the input tolerance to determine which of the sub faces in the other_face are adjacent to the ones in this face. An exception will be thrown if not all sub-faces can be matched.

Parameters:

other_face – Another Face object to be set adjacent to this one.
tolerance – The minimum distance between the center of two aperture geometries at which they are considered adjacent. Default: 0.01, suitable for objects in meters.

Returns:

A dictionary of adjacency information with the following keys

adjacent_apertures - A list of tuples with each tuple containing 2 objects for Apertures paired in the process of solving adjacency.
adjacent_doors - A list of tuples with each tuple containing 2 objects for Doors paired in the process of solving adjacency.

to_dict(abridged=False, included_prop=None, include_plane=True)[source]¶

Return Face as a dictionary.

Parameters:

abridged – Boolean to note whether the extension properties of the object (ie. materials, constructions) should be included in detail (False) or just referenced by identifier (True). (Default: False).
included_prop – List of properties to filter keys that must be included in output dictionary. For example [‘energy’] will include ‘energy’ key if available in properties to_dict. By default all the keys will be included. To exclude all the keys from extensions use an empty list.
include_plane – Boolean to note wether the plane of the Face3D should be included in the output. This can preserve the orientation of the X/Y axes of the plane but is not required and can be removed to keep the dictionary smaller. (Default: True).

BC_COLORS = {'Adiabatic': (R:255, G:128, B:128, A:255), 'Ground': (R:165, G:82, B:0, A:255), 'Other': (R:255, G:255, B:200, A:255), 'Outdoors': (R:64, G:180, B:255, A:255), 'Surface': (R:0, G:128, B:0, A:255)}¶

TYPES = Face Types: air_boundary floor roof_ceiling wall¶

TYPE_COLORS = {'AirBoundary': (R:255, G:255, B:200, A:100), 'Floor': (R:128, G:128, B:128, A:255), 'InteriorAirBoundary': (R:255, G:255, B:200, A:100), 'InteriorFloor': (R:255, G:128, B:128, A:255), 'InteriorRoofCeiling': (R:255, G:128, B:128, A:255), 'InteriorWall': (R:230, G:215, B:150, A:255), 'RoofCeiling': (R:128, G:20, B:20, A:255), 'Wall': (R:230, G:180, B:60, A:255)}¶

property altitude¶: Get the altitude of the geometry between +90 (up) and -90 (down).

property aperture_area¶: Get the combined area of the face’s apertures.

property aperture_ratio¶: Get a number between 0 and 1 for the area ratio of the apertures to the face.

property apertures¶: Get a tuple of apertures in this Face.

property area¶: Get the area of the face.

property azimuth¶

Get the azimuth of the geometry, between 0 and 360.

Given Y-axis as North, 0 = North, 90 = East, 180 = South, 270 = West This will be zero if the Face3D is perfectly horizontal.

property bc_color¶: Get a Color to be used in visualizations by boundary condition.

property boundary_condition¶: Get or set the boundary condition of the Face. (ie. Outdoors, Ground, etc.).

property can_be_ground¶: Get a boolean for whether this Face can support a Ground boundary condition.

property center¶

Get a ladybug_geometry Point3D for the center of the face.

Note that this is the center of the bounding rectangle around this geometry and not the area centroid.

property display_name¶

Get or set a string for the object name without any character restrictions.

If not set, this will be equal to the identifier.

property doors¶: Get a tuple of doors in this Face.

property full_id¶

Get a string with both the object display_name and identifier.

This is formatted as display_name[identifier].

This is useful in error messages to give users an easy means of finding invalid objects within models. If there is no display_name assigned, only the identifier will be returned.

property geometry¶

Get a ladybug_geometry Face3D object representing the Face.

Note that this Face3D only represents the parent face and does not have any holes cut in it for apertures or doors.

property has_parent¶: Get a boolean noting whether this Face has a parent Room.

property has_sub_faces¶: Get a boolean noting whether this Face has Apertures or Doors.

property identifier¶

Get or set a text string for the unique object identifier.

This identifier remains constant as the object is mutated, copied, and serialized to different formats (eg. dict, idf, rad). As such, this property is used to reference the object across a Model.

property indoor_shades¶: Get an array of all indoor shades assigned to this object.

property is_exterior¶: Get a boolean for whether this object has an Outdoors boundary condition.

property max¶: Get a Point3D for the maximum of the bounding box around the object.

property min¶: Get a Point3D for the minimum of the bounding box around the object.

property normal¶: Get a Vector3D for the direction in which the face is pointing.

property outdoor_shades¶: Get an array of all outdoor shades assigned to this object.

property parent¶: Get the parent Room if assigned. None if not assigned.

property perimeter¶: Get the perimeter of the face. This includes the length of holes in the face.

property properties¶: Get object properties, including Radiance, Energy and other properties.

property punched_geometry¶: Get a Face3D object with holes cut in it for apertures and doors.

property punched_vertices¶

Get a list of vertices with holes cut in it for apertures and doors.

Note that some vertices will be repeated since the vertices effectively trace out a single boundary around the whole shape, winding inward to cut out the holes. This property should be used when exporting to Radiance.

property shades¶: Get an array of all shades (indoor + outdoor) assigned to this object.

property sub_faces¶: Get a tuple of apertures and doors in this Face.

property tilt¶: Get the tilt of the geometry between 0 (up) and 180 (down).

property to¶

Face writer object.

Use this method to access Writer class to write the face in other formats.

Usage:

face.to.idf(face) -> idf string.
face.to.radiance(face) -> Radiance string.

property type¶

Get or set an object for Type of Face (ie. Wall, Floor, Roof).

Note that setting this property will reset extension attributes on this Face to their default values.

property type_color¶: Get a Color to be used in visualizations by type.

property upper_left_vertices¶

Get a list of vertices starting from the upper-left corner.

This property obeys the same rules as the vertices property but always starts from the upper-left-most vertex. This property should be used when exporting to EnergyPlus / OpenStudio.

property user_data¶

Get or set an optional dictionary for additional meta data for this object.

This will be None until it has been set. All keys and values of this dictionary should be of a standard Python type to ensure correct serialization of the object to/from JSON (eg. str, float, int, list, dict)

property vertices¶

Get a list of vertices for the face (in counter-clockwise order).

Note that these vertices only represent the outer boundary of the face and do not account for holes cut in the face by apertures or doors.