honeybee.room module

Honeybee Room.

class honeybee.room.Room(identifier, faces, tolerance=0, angle_tolerance=0)

Bases: _BaseWithShade

A volume enclosed by faces, representing a single room or space.

Note that, if zero is input for tolerance and angle_tolerance, no checks will be performed to determine whether the room is a closed volume and no attempt will be made to flip faces in the event that they are not facing outward from the room volume. As such, an input tolerance of 0 is intended for workflows where the solidity of the room volume has been evaluated elsewhere.

Parameters:

• identifier – Text string for a unique Room ID. Must be < 100 characters and not contain any spaces or special characters.

• faces – A list or tuple of honeybee Face objects that together form the closed volume of a room.

• tolerance – The maximum difference between x, y, and z values at which vertices of adjacent faces are considered equivalent. This is used in determining whether the faces form a closed volume. Default is 0, which makes no attempt to evaluate whether the Room volume is closed.

• angle_tolerance – The max angle difference in degrees that vertices are allowed to differ from one another in order to consider them colinear. Default is 0, which makes no attempt to evaluate whether the Room volume is closed.

Properties:

• identifier

• display_name

• faces

• multiplier

• zone

• story

• exclude_floor_area

• indoor_furniture

• indoor_shades

• outdoor_shades

• walls

• floors

• roof_ceilings

• air_boundaries

• doors

• apertures

• exterior_apertures

• geometry

• center

• min

• max

• volume

• floor_area

• exposed_area

• exterior_wall_area

• exterior_aperture_area

• exterior_wall_aperture_area

• exterior_skylight_aperture_area

• average_floor_height

• user_data

ToString()

Overwrite .NET ToString.

add_indoor_furniture(shade)

Add a Shade object representing furniture to the Room.

Note that this method is identical to the add_indoor_shade method but it is provided here under an alternate name to make it clear that indoor furniture objects should be added here to the Room.

Parameters:

shade – A Shade object to add to the indoors of this Room, representing furniture, desks, partitions, etc.

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)

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.

average_orientation(north_vector=Vector2D(0.00, 1.00))

Get a number between 0 and 360 for the average orientation of exposed walls.

0 = North, 90 = East, 180 = South, 270 = West. Will be None if the zone has no exterior walls. Resulting value is weighted by the area of each of the wall faces.

Parameters:

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

check_degenerate(tolerance=0.01, raise_exception=True, detailed=False)

Check whether the Room is degenerate with zero volume.

Parameters:

• tolerance – tolerance: The maximum difference between x, y, and z values at which face vertices are considered equivalent. (Default: 0.01, suitable for objects in meters).

• raise_exception – Boolean to note whether a ValueError should be raised if the room geometry is degenerate. (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_planar(tolerance=0.01, raise_exception=True, detailed=False)

Check that all of the Room’s geometry components are planar.

This includes all of the Room’s Faces, Apertures, Doors and Shades.

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.

static check_room_volume_collisions(rooms, tolerance=0.01, detailed=False)

Check whether the volumes of Rooms collide with one another beyond tolerance.

At the moment, this method only checks for the case where coplanar Floor Faces of different Rooms overlap with one another, which clearly indicates that there is definitely a collision between the Room volumes. In the future, this method may be amended to sense more complex cases of colliding Room volumes. For now, it is designed to only detect the most common cases.

Parameters:

• rooms – A list of rooms that will be checked for volumetric collisions. For this method to run most efficiently, these input Rooms should be at the same horizontal floor level. The Room.group_by_floor_height() method can be used to group the Rooms of a model according to their height before running this method.

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

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

Check that no edges of the Room’s geometry components self-intersect.

This includes all of the Room’s Faces, Apertures, Doors and Shades.

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 an object intersects with itself (like a bow tie). (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_solid(tolerance=0.01, angle_tolerance=1, raise_exception=True, detailed=False)

Check whether the Room is a closed solid to within the input tolerances.

Parameters:

• tolerance – tolerance: The maximum difference between x, y, and z values at which face vertices are considered equivalent. Default: 0.01, suitable for objects in meters.

• angle_tolerance – The max angle difference in degrees that vertices are allowed to differ from one another in order to consider them colinear. Default: 1 degree.

• raise_exception – Boolean to note whether a ValueError should be raised if the room geometry does not form a closed solid.

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

Check that this Room’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. (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_valid(tolerance=0.01, angle_tolerance=1, raise_exception=True, detailed=False)

Check that room’s sub-faces are co-planar with faces and in 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. (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_upside_down_faces(angle_tolerance=1, raise_exception=True, detailed=False)

Check whether the Room’s Faces have 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.

clean_envelope(adjacency_dict, tolerance=0.01)

Remove colinear and duplicate vertices from this object’s Faces and Sub-faces.

This method also automatically removes degenerate Faces and coordinates adjacent Faces with the adjacency_dict to ensure matching numbers of vertices, which is a requirement for engines like EnergyPlus.

Parameters:

• adjacency_dict – A dictionary containing the identifiers of Room Faces as keys and Honeybee Face objects as values. This is used to indicate the target number of vertices that each Face should have after colinear vertices are removed. This can be used to ensure adjacent Faces have matching numbers of vertices, which is a requirement for certain interfaces like EnergyPlus.

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

Returns:

A dictionary containing the identifiers of adjacent Faces as keys and Honeybee Face objects as values. This can be used as an input in future Rooms on which this method is run to ensure adjacent Faces have matching numbers of vertices, which is a requirement for certain interfaces like EnergyPlus.

coplanar_split(geometry, tolerance=0.01, angle_tolerance=1)

Split the Faces of this Room with coplanar geometry (Polyface3D or Face3D).

This method attempts to preserve as many properties as possible for the split Faces, including all extension attributes and sub-faces (as long as they don’t fall in the path of the intersection).

Parameters:

• geometry – A list of coplanar geometry (either Polyface3D or Face3D) that will be used to split the Faces of this Room. Typically, these are Polyface3D of other Room geometries to be intersected with this one but they can also be Face3D if only one intersection is desired.

• tolerance – The minimum difference between the coordinate values of two faces at which they can be considered adjacent. 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).

Returns:

A list containing only the new Faces that were created as part of the splitting process. These new Faces will have as many properties of the original Face assigned to them as possible but they will not have a Surface boundary condition if the original Face had one. Having just the new Faces here can be used in operations like setting new Surface boundary conditions.

display_dict()

Get a list of DisplayFace3D dictionaries for visualizing the object.

duplicate()

Get a copy of this object.

faces_by_guide_surface(surface_geometry, directional_vector=None, tolerance=0.01, angle_tolerance=1.0)

Get the Faces of the Room that are touching and coplanar with a given surface.

This is useful in workflows were one would like to set the properties of a group of Faces using a guide surface, like setting a series of faces along a given stretch of a parti wall to be adiabatic.

Parameters:

• surface_geometry – An array of ladybug_geometry Face3D that together represent the guide surface.

• directional_vector – An optional Vector3D to select the room Faces that lie on a certain side of the surface_geometry. For example, using (0, 0, -1) will include all Faces that lie below the surface_geometry in the resulting selection.

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

static find_adjacency(rooms, tolerance=0.01)

Get a list with all adjacent pairs of Faces between input rooms.

Note that this method does not change any boundary conditions of the input rooms or mutate them in any way. It’s purely a geometric analysis of the faces between rooms.

Parameters:

• rooms – A list of rooms for which adjacencies will be solved.

• tolerance – The minimum difference between the coordinate values of two faces at which they can be considered centered adjacent. Default: 0.01, suitable for objects in meters.

Returns:

A list of tuples with each tuple containing 2 objects for Faces that are adjacent to one another.

classmethod from_box(identifier, width=3.0, depth=6.0, height=3.2, orientation_angle=0, origin=Point3D(0.00, 0.00, 0.00))

Initialize a Room from parameters describing a box.

The resulting faces of the room will always be ordered as follows: (Bottom, Front, Right, Back, Left, Top) where the front is facing the cardinal direction of the orientation_angle.

Parameters:

• identifier – Text string for a unique Room ID. Must be < 100 characters and not contain any spaces or special characters.

• width – Number for the width of the box (in the X direction). Default: 3.0.

• depth – Number for the depth of the box (in the Y direction). Default: 6.0.

• height – Number for the height of the box (in the Z direction). Default: 3.2.

• orientation_angle – A number between 0 and 360 for the clockwise orientation of the box in degrees. (0 = North, 90 = East, 180 = South, 270 = West)

• origin – A ladybug_geometry Point3D for the origin of the room.

classmethod from_dict(data, tolerance=0, angle_tolerance=0)

Initialize an Room from a dictionary.

Parameters:

• data – A dictionary representation of a Room object.

• tolerance – The maximum difference between x, y, and z values at which vertices of adjacent faces are considered equivalent. This is used in determining whether the faces form a closed volume. Default is 0, which makes no attempt to evaluate whether the Room volume is closed.

• angle_tolerance – The max angle difference in degrees that vertices are allowed to differ from one another in order to consider them colinear. Default is 0, which makes no attempt to evaluate whether the Room volume is closed.

classmethod from_polyface3d(identifier, polyface, roof_angle=60, floor_angle=130, ground_depth=0)

Initialize a Room from a ladybug_geometry Polyface3D object.

Parameters:

• identifier – Text string for a unique Room ID. Must be < 100 characters and not contain any spaces or special characters.

• polyface – A ladybug_geometry Polyface3D object representing the closed volume of a room. The Polyface3D.is_solid property can be used to determine whether the polyface is a closed solid before input here.

• roof_angle – A number between 0 and 90 to set the angle from the horizontal plane below which faces will be considered roofs instead of walls. 90 indicates that all vertical faces are roofs and 0 indicates that all horizontal faces are walls. (Default: 60, recommended by the ASHRAE 90.1 standard).

• floor_angle – A number between 90 and 180 to set the angle from the horizontal plane above which faces will be considered floors instead of walls. 180 indicates that all vertical faces are floors and 0 indicates that all horizontal faces are walls. (Default: 130, recommended by the ASHRAE 90.1 standard).

• ground_depth – The Z value above which faces are considered Outdoors instead of Ground. Faces will have a Ground boundary condition if all of their vertices lie at or below this value. Default: 0.

generate_exterior_aperture_grid(dimension, offset=0.1, aperture_type='All')

Get a gridded Mesh3D offset from the exterior Apertures of this room.

Will be None if the Room has no exterior Apertures.

Parameters:

• dimension – The dimension of the grid cells as a number.

• offset – A number for how far to offset the grid from the base aperture. Positive numbers indicate an offset towards the exterior while negative numbers indicate an offset towards the interior, essentially modeling the value of sun on the building interior. (Default is 0.1, which will offset the grid to be 0.1 unit from the apertures).

• aperture_type –

  Text to specify the type of Aperture that will be used to generate grids. Window indicates Apertures in Walls. Choose from the following. (Default: All).

  • Window

  • Skylight

  • All

Usage:

room = Room.from_box(3.0, 6.0, 3.2, 180)
room[3].apertures_by_ratio(0.4)
aperture_mesh = room.generate_exterior_aperture_grid(0.5)
test_points = aperture_mesh.face_centroids

generate_exterior_face_grid(dimension, offset=0.1, face_type='Wall', punched_geometry=False)

Get a gridded Mesh3D offset from the exterior Faces of this Room.

This will be None if the Room has no exterior Faces.

Parameters:

• dimension – The dimension of the grid cells as a number.

• offset – A number for how far to offset the grid from the base face. Positive numbers indicate an offset towards the exterior. (Default is 0.1, which will offset the grid to be 0.1 unit from the faces).

• face_type –

  Text to specify the type of face that will be used to generate grids. Note that only Faces with Outdoors boundary conditions will be used, meaning that most Floors will typically be excluded unless they represent the underside of a cantilever. Choose from the following. (Default: Wall).

  • Wall

  • Roof

  • Floor

  • All

• punched_geometry – Boolean to note whether the punched_geometry of the faces should be used (True) with the areas of sub-faces removed from the grid or the full geometry should be used (False). (Default:False).

Usage:

room = Room.from_box(3.0, 6.0, 3.2, 180)
face_mesh = room.generate_exterior_face_grid(0.5)
test_points = face_mesh.face_centroids

generate_grid(x_dim, y_dim=None, offset=1.0)

Get a gridded Mesh3D objects offset from the floors of this room.

Note that the x_dim and y_dim refer to dimensions within the XY coordinate system of the floor faces’s planes. So rotating the planes of the floor faces will result in rotated grid cells.

Will be None if the Room has no floor faces.

Parameters:

• 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 1.0, which will offset the grid to be 1 unit above the floor.

Usage:

room = Room.from_box(3.0, 6.0, 3.2, 180)
floor_mesh = room.generate_grid(0.5, 0.5, 1)
test_points = floor_mesh.face_centroids

ground_by_custom_surface(ground_geometry, tolerance=0.01, angle_tolerance=1.0)

Set ground boundary conditions using an array of Face3D for the ground.

Room faces that are coplanar with the ground surface or lie completely below it will get a Ground boundary condition while those above will get an Outdoors boundary condition. Existing Faces with an indoor boundary condition will be unaffected.

Parameters:

• ground_geometry – An array of ladybug_geometry Face3D that together represent the ground surface.

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

static group_by_adjacency(rooms)

Group Rooms together that are connected by adjacencies.

This is useful for separating rooms in the case where a Model contains multiple buildings or sections that are separated by adiabatic or outdoor boundary conditions.

Parameters:

rooms – A list of rooms to be grouped by their adjacency.

Returns:

A list of list with each sub-list containing rooms that share adjacencies.

static group_by_air_boundary_adjacency(rooms)

Group Rooms together that share air boundaries.

This is useful for understanding the radiant enclosures that will exist when a model is exported to EnergyPlus.

Parameters:

rooms – A list of rooms to be grouped by their air boundary adjacency.

Returns:

A list of list with each sub-list containing rooms that share adjacent air boundaries. If a Room has no air boundaries it will the the only item within its sub-list.

static group_by_floor_height(rooms, min_difference=0.01)

Group Rooms according to their average floor height.

Parameters:

• rooms – A list of honeybee rooms to be grouped by floor height.

• min_difference – An float value to denote the minimum difference in floor heights that is considered meaningful. This can be used to ensure rooms like those representing stair landings are grouped with those below them. Default: 0.01, which means that virtually any minor difference in floor heights will result in a new group. This assumption is suitable for models in meters.

Returns:

A tuple with two items.

• grouped_rooms - A list of lists of honeybee rooms with each sub-list representing a different floor height.

• floor_heights - A list of floor heights with one floor height for each sub-list of the output grouped_rooms.

static group_by_orientation(rooms, group_count=None, north_vector=Vector2D(0.00, 1.00))

Group Rooms with the same average outdoor wall orientation.

Parameters:

• rooms – A list of honeybee rooms to be grouped by orientation.

• group_count – An optional positive integer to set the number of orientation groups to use. For example, setting this to 4 will result in rooms being grouped by four orientations (North, East, South, West). If None, the maximum number of unique groups will be used.

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

Returns:

A tuple with three items.

• grouped_rooms - A list of lists of honeybee rooms with each sub-list representing a different orientation.

• core_rooms - A list of honeybee rooms with no identifiable orientation.

• orientations - A list of numbers between 0 and 360 with one orientation for each branch of the output grouped_rooms. This will be a list of angle ranges if a value is input for group_count.

static grouped_horizontal_boundary(rooms, min_separation=0, tolerance=0.01, floors_only=True)

Get a list of Face3D for the horizontal boundary around several Rooms.

This method will attempt to produce a boundary that follows along the outer parts of the Floors of the Rooms so it is not suitable for groups of Rooms that overlap one another in plan. This method may return an empty list if the min_separation is so large that a continuous boundary could not be determined.

Parameters:

• rooms – A list of Honeybee Rooms for which the horizontal boundary will be computed.

• min_separation – A number for the minimum distance between Rooms that is considered a meaningful separation. Gaps between Rooms that are less than this distance will be ignored and the boundary will continue across the gap. When the input rooms represent volumes of interior Faces, this input can be thought of as the maximum interior wall thickness, which should be ignored in the calculation of the overall boundary of the Rooms. When Rooms are touching one another (with Room volumes representing center lines of walls), this value can be set to zero or anything less than or equal to the tolerance. Doing so will yield a cleaner result for the boundary, which will be faster. Note that care should be taken not to set this value higher than the length of any meaningful exterior wall segments. Otherwise, the exterior segments will be ignored in the result. This can be particularly dangerous around curved exterior walls that have been planarized through subdivision into small segments. (Default: 0).

• tolerance – The maximum difference between coordinate values of two vertices at which they can be considered equivalent. (Default: 0.01, suitable for objects in meters).

• floors_only – A boolean to note whether the grouped boundary should only surround the Floor geometries of the Rooms (True) or if they should surround the entirety of the Room volumes in plan (False).

horizontal_boundary(match_walls=False, tolerance=0.01)

Get a Face3D representing the horizontal boundary around the Room.

This will be generated from all downward-facing Faces of the Room (essentially the Floor faces but can also include overhanging slanted walls). So, for a valid closed-volume Honeybee Room, the result should always represent the Room in the XY plane.

The Z height of the resulting Face3D will be at the minimum floor height.

Note that, if this Room is not solid, the computation of the horizontal boundary may fail with an exception.

Parameters:

• match_walls – Boolean to note whether vertices should be inserted into the final Face3D that will help match the segments of the result back to the walls that are adjacent to the floors. If False, the result may lack some colinear vertices that relate the Face3D to the Walls, though setting this to True does not guarantee that all walls will relate to a segment in the result. (Default: False).

• tolerance – The minimum difference between x, y, and z coordinate values at which points are considered distinct. (Default: 0.01, suitable for objects in Meters).

horizontal_floor_boundaries(match_walls=False, tolerance=0.01)

Get a list of horizontal Face3D for the boundaries around the Room’s Floors.

Unlike the horizontal_boundary method, which uses all downward-pointing geometries, this method will derive horizontal boundaries using only the Floors. This is useful when the resulting geometry is used to specify the floor area in the result.

The Z height of the resulting Face3D will be at the minimum floor height.

Parameters:

• match_walls – Boolean to note whether vertices should be inserted into the final Face3Ds that will help match the segments of the result back to the walls that are adjacent to the floors. If False, the result may lack some colinear vertices that relate the Face3Ds to the Walls, though setting this to True does not guarantee that all walls will relate to a segment in the result. (Default: False).

• tolerance – The minimum difference between x, y, and z coordinate values at which points are considered distinct. (Default: 0.01, suitable for objects in Meters).

static intersect_adjacency(rooms, tolerance=0.01, angle_tolerance=1)

Intersect the Faces of an array of Rooms to ensure matching adjacencies.

Note that this method may remove Apertures and Doors if they align with an intersection so it is typically recommended that this method be used before sub-faces are assigned (if possible). Sub-faces that do not fall along an intersection will be preserved.

Also note that this method does not actually set the walls that are next to one another to be adjacent. The solve_adjacency method must be used for this after running this method.

Parameters:

• rooms – A list of Rooms for which adjacent Faces will be intersected.

• tolerance – The minimum difference between the coordinate values of two faces at which they can be considered adjacent. 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).

Returns:

An array of Rooms that have been intersected with one another.

is_extrusion(tolerance=0.01, angle_tolerance=1.0)

Test if this Room is an extruded floor plate with a flat roof.

Parameters:

• tolerance – The absolute tolerance with which the Room geometry will be evaluated. (Default: 0.01, suitable for objects in meters).

• angle_tolerance – The angle tolerance at which the geometry will be evaluated in degrees. (Default: 1 degree).

Returns:

True if the 3D Room is a pure extrusion. False if not.

is_geo_equivalent(room, tolerance=0.01)

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

This will also check all child Faces, Apertures, Doors and Shades for equivalency.

Parameters:

• room – Another Room 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.

merge_coplanar_faces(tolerance=0.01, angle_tolerance=1, orthogonal_only=False)

Merge coplanar Faces of this Room.

This is often useful before running Room.intersect_adjacency between multiple Rooms as it will ensure the result is clean with any previous intersections erased.

This method attempts to preserve as many properties as possible for the split Faces but, when Faces are merged, the properties of one of the merged faces will determine the face type and boundary condition. Also, all Face extension attributes will be removed (reset to default) and, if merged Faces originally had Surface boundary conditions, they will be reset to Outdoors.

Parameters:

• tolerance – The minimum difference between the coordinate values of two faces at which they can be considered adjacent. 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).

• orthogonal_only – A boolean to note whether only vertical and horizontal coplanar faces should be merged, leaving faces with any other tilt intact. Useful for cases where alignment of walls with the Room.horizontal_boundary is desired without disrupting the roof geometry. (Default: False).

Returns:

A list containing only the new Faces that were created as part of the merging process. These new Faces will have as many properties of the original Face assigned to them as possible but they will not have a Surface boundary condition if the original Face had one. Having the new Faces here can be used in operations like setting new Surface boundary conditions or re-assigning extension attributes.

move(moving_vec)

Move this Room along a vector.

Parameters:

moving_vec – A ladybug_geometry Vector3D with the direction and distance to move the room.

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.

rectangularize_apertures(subdivision_distance=None, max_separation=None, merge_all=False, tolerance=0.01, angle_tolerance=1.0)

Convert all Apertures on this Room 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).

reflect(plane)

Reflect this Room 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_colinear_vertices_envelope(tolerance=0.01, delete_degenerate=False)

Remove colinear and duplicate vertices from this object’s Faces and Sub-faces.

If degenerate geometry is found in the process of removing colinear vertices, an exception will be raised. Note that this does not affect the assigned 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.

• delete_degenerate – Boolean to note whether degenerate Faces, Apertures and Doors (objects that evaluate to less than 3 vertices at the tolerance) should be deleted from the Room instead of raising a ValueError. (Default: False).

remove_indoor_furniture()

Remove all indoor furniture assigned to this Room.

Note that this method is identical to the remove_indoor_shade method but it is provided here under an alternate name to make it clear that indoor furniture objects should be added here to the Room.

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.

static rooms_from_footprint(footprints, floor_to_floor_height, room_ids=None, unique_id=None, orientation_angle=0, story_count=1, outdoor_roof=True, ground_floor=True)

Create several Honeybee Rooms from footprint Face3Ds.

Parameters:

• footprints – A list of Face3Ds representing the floors of Rooms.

• floor_to_floor_height – Number for the height of each floor of the model (in the Z direction).

• room_ids – A list of strings for the identifiers of the Rooms to be generated. If None, default unique IDs will be generated. (Default: None)

• unique_id – Text for a unique identifier to be incorporated into all Room identifiers. (Default: None).

• orientation_angle – A number between 0 and 360 for the counterclockwise orientation that the width of the box faces. (0=North, 90=East, 180=South, 270=West). (Default: 0).

• story_count – An integer for the number of stories to generate. (Default: 1).

• outdoor_roof – Boolean to note whether the roof faces of the top floor should be outdoor or adiabatic. (Default: True).

• ground_floor – Boolean to note whether the floor faces of the bottom floor should be ground or adiabatic. (Default: True).

static rooms_from_l_shaped_plan(width_1, length_1, width_2, length_2, floor_to_floor_height, perimeter_offset=0, story_count=1, orientation_angle=0, outdoor_roof=True, ground_floor=True, unique_id=None, tolerance=0.01)

Create a Rooms that represent an L-shaped floor plan.

Note that the resulting Rooms in the model won’t have any windows or solved adjacencies. These can be added by using the Room.solve_adjacency method and the various Face.apertures_by_XXX methods.

Parameters:

• width_1 – Number for the width of the lower part of the L segment.

• length_1 – Number for the length of the lower part of the L segment, not counting the overlap between the upper and lower segments.

• width_2 – Number for the width of the upper (left) part of the L segment.

• length_2 – Number for the length of the upper (left) part of the L segment, not counting the overlap between the upper and lower segments.

• floor_to_floor_height – Number for the height of each floor of the model (in the Z direction).

• perimeter_offset – An optional positive number that will be used to offset the perimeter to create core/perimeter Rooms. If this value is 0, no offset will occur and each floor will have one Room. (Default: 0).

• story_count – An integer for the number of stories to generate. (Default: 1).

• orientation_angle – A number between 0 and 360 for the counterclockwise orientation that the width of the box faces. (0=North, 90=East, 180=South, 270=West). (Default: 0).

• outdoor_roof – Boolean to note whether the roof faces of the top floor should be outdoor or adiabatic. (Default: True).

• ground_floor – Boolean to note whether the floor faces of the bottom floor should be ground or adiabatic. (Default: True).

• unique_id – Text for a unique identifier to be incorporated into all of the Room identifiers. If None, a default one will be generated.

• tolerance – The maximum difference between x, y, and z values at which vertices are considered equivalent. (Default: 0.01, suitable for objects in meters).

static rooms_from_rectangle_plan(width, length, floor_to_floor_height, perimeter_offset=0, story_count=1, orientation_angle=0, outdoor_roof=True, ground_floor=True, unique_id=None, tolerance=0.01)

Create a Rooms that represent a rectangular floor plan.

Note that the resulting Rooms won’t have any windows or solved adjacencies. These can be added by using the Room.solve_adjacency method and the various Face.apertures_by_XXX methods.

Parameters:

• width – Number for the width of the plan (in the X direction).

• length – Number for the length of the plan (in the Y direction).

• floor_to_floor_height – Number for the height of each floor of the model (in the Z direction).

• perimeter_offset – An optional positive number that will be used to offset the perimeter to create core/perimeter Rooms. If this value is 0, no offset will occur and each floor will have one Room. (Default: 0).

• story_count – An integer for the number of stories to generate. (Default: 1).

• orientation_angle – A number between 0 and 360 for the counterclockwise orientation that the width of the box faces. (0=North, 90=East, 180=South, 270=West). (Default: 0).

• outdoor_roof – Boolean to note whether the roof faces of the top floor should be outdoor or adiabatic. (Default: True).

• ground_floor – Boolean to note whether the floor faces of the bottom floor should be ground or adiabatic. (Default: True).

• unique_id – Text for a unique identifier to be incorporated into all of the Room identifiers. If None, a default one will be generated.

• tolerance – The maximum difference between x, y, and z values at which vertices are considered equivalent. (Default: 0.01, suitable for objects in meters).

rotate(axis, angle, origin)

Rotate this Room 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)

Rotate this Room 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)

Scale this Room 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).

simplify_apertures(tolerance=0.01)

Convert all Apertures on this Room to be a simple window ratio.

This is useful for studies where faster simulation times are desired and the window ratio is the critical factor driving the results (as opposed to the detailed geometry of the window). Apertures assigned to concave Faces will not be simplified given that the apertures_by_ratio method likely won’t improve the cleanliness of the apertures for such cases.

Parameters:

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

skylight_apertures_by_ratio(ratio, tolerance=0.01)

Add apertures to all exterior roofs given a ratio of aperture to face area.

Note this method removes any existing apertures and overhead doors on the Room’s roofs. 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 equivalent. (Default: 0.01, suitable for objects in meters).

Usage:

room = Room.from_box(3.0, 6.0, 3.2, 180)
room.skylight_apertures_by_ratio(0.05)

static solve_adjacency(rooms, tolerance=0.01)

Solve for adjacencies between a list of rooms.

Note that this method will mutate the input rooms by setting Surface boundary conditions for any adjacent objects. However, it does NOT overwrite existing Surface boundary conditions and only adds new ones if faces are found to be adjacent with equivalent areas.

Parameters:

• rooms – A list of rooms for which adjacencies will be solved.

• tolerance – The minimum difference between the coordinate values of two faces at which they can be considered centered adjacent. Default: 0.01, suitable for objects in meters.

Returns:

A dictionary of information about the objects that had their adjacency set. The dictionary has the following keys.

• adjacent_faces - A list of tuples with each tuple containing 2 objects for Faces paired in the process of solving adjacency. This data can be used to assign custom properties to the new adjacent Faces (like making all adjacencies an AirBoundary face type or assigning custom materials/constructions).

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

split_through_holes(tolerance=0.01, angle_tolerance=1)

Split any Faces of this Room with holes such that they no longer have holes.

This method is useful for destination engines that cannot support holes either through dedicated hole loops that are separate from the boundary loop or as a single collapsed list of vertices that winds inward to cut out the holes.

This method attempts to preserve as many properties as possible for the split Faces, including all extension attributes and sub-faces (as long as they don’t fall in the path of the intersection).

Parameters:

• tolerance – The minimum difference between the coordinate values of two faces at which they can be considered adjacent. 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).

Returns:

A list containing only the new Faces that were created as part of the splitting process. These new Faces will have as many properties of the original Face assigned to them as possible but they will not have a Surface boundary condition if the original Face had one. Having just the new Faces here can be used in operations like setting new Surface boundary conditions.

static stories_by_floor_height(rooms, min_difference=2.0)

Assign story properties to a set of Rooms using their floor heights.

Stories will be named with a standard convention (‘Floor1’, ‘Floor2’, etc.). Note that this method will only assign stories to Rooms that do not have a story identifier already assigned to them.

Parameters:

• rooms – A list of rooms for which story properties will be automatically assigned.

• min_difference – An float value to denote the minimum difference in floor heights that is considered meaningful. This can be used to ensure rooms like those representing stair landings are grouped with those below them. Default: 2.0, which means that any difference in floor heights less than 2.0 will be considered a part of the same story. This assumption is suitable for models in meters.

Returns:

A list of the unique story names that were assigned to the input rooms.

to_dict(abridged=False, included_prop=None, include_plane=True)

Return Room as a dictionary.

Parameters:

• abridged – Boolean to note whether the extension properties of the object (ie. construction sets) 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 planes of the Face3Ds should be included in the output. This can preserve the orientation of the X/Y axes of the planes but is not required and can be removed to keep the dictionary smaller. (Default: True).

to_extrusion(tolerance=0.01, angle_tolerance=1.0)

Get a version of this Room that is an extruded floor plate with a flat roof.

All boundary conditions and windows applied to vertical walls will be preserved and the resulting Room should have a volume that matches the current Room. If adding back apertures to the room extrusion results in these apertures going past the parent wall Face, the windows of the Face will be reduced to a simple window ratio. Any Surface boundary conditions will be converted to Adiabatic (if honeybee-energy is installed) or Outdoors (if not).

The multiplier and all extension properties will also be preserved.

This method is useful for exporting to platforms that cannot model Room geometry beyond simple extrusions. The fact that the resulting room has window areas and volumes that match the original detailed geometry should help ensure the results in these platforms are close to what they would be had the detailed geometry been modeled.

Parameters:

• tolerance – The minimum difference between the coordinate values of two vertices at which point they are considered co-located. (Default: 0.01, suitable for objects in meters).

• angle_tolerance – The angle tolerance at which the geometry will be evaluated in degrees. (Default: 1 degree).

Returns:

A Room that is an extruded floor plate with a flat roof. Note that, if the Room is already an extrusion, the current Room instance will be returned.

wall_apertures_by_ratio(ratio, tolerance=0.01)

Add apertures to all exterior walls given a ratio of aperture to face area.

Note this method removes any existing apertures and doors on the Room’s walls. 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 equivalent. (Default: 0.01, suitable for objects in meters).

Usage:

room = Room.from_box(3.0, 6.0, 3.2, 180)
room.wall_apertures_by_ratio(0.4)

property air_boundaries

Get a tuple of all of the AirBoundary Faces of the Room.

property apertures

Get a tuple of all Apertures of the Room.

property average_floor_height

Get the height of the room floor averaged over all floor faces in the room.

The resulting value is weighted by the area of each of the floor faces. Will be the minimum Z value of the Room volume if the room possesses no floors.

property center

Get a ladybug_geometry Point3D for the center of the room.

Note that this is the center of the bounding box around the room Polyface geometry and not the volume centroid. Also note that shades assigned to this room are not included in this center calculation.

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 all Doors of the Room.

property exclude_floor_area

Get or set a boolean for whether the floor area contributes to the Model.

Note that this will not affect the floor_area property of this Room but it will ensure the Room’s floor area is excluded from any calculations when the Room is part of a Model.

property exposed_area

Get the combined area of all room faces with outdoor boundary conditions.

Useful for estimating infiltration, often expressed as a flow per unit exposed envelope area.

property exterior_aperture_area

Get the combined area of all exterior apertures on the room.

property exterior_apertures

Get a tuple of all exterior Apertures of the Room.

property exterior_roof_area

Get the combined area of all exterior roofs on the room.

This is NOT the area of the roof’s punched_geometry and it includes BOTH the area of opaque and transparent parts of the roofs.

property exterior_skylight_aperture_area

Get the combined area of all apertures on exterior roofs of the room.

property exterior_wall_aperture_area

Get the combined area of all apertures on exterior walls of the room.

property exterior_wall_area

Get the combined area of all exterior walls on the room.

This is NOT the area of the wall’s punched_geometry and it includes BOTH the area of opaque and transparent parts of the walls.

property faces

Get a tuple of all honeybee Faces making up this room volume.

property floor_area

Get the combined area of all room floor faces.

property floors

Get a tuple of all of the Floor Faces of the Room.

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 Polyface3D object representing the room.

property has_parent

Always False as Rooms cannot have parents.

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_furniture

Array of all indoor furniture Shade objects assigned to this Room.

Note that this property is identical to the indoor_shades property but it is provided here under an alternate name to make it clear that indoor furniture objects should be added here to the Room.

property indoor_shades

Get an array of all indoor shades assigned to this object.

property max

Get a Point3D for the maximum of the bounding box around the object.

This includes any shades assigned to this object or its children.

property min

Get a Point3D for the minimum of the bounding box around the object.

This includes any shades assigned to this object or its children.

property multiplier

Get or set an integer noting how many times this Room is repeated.

Multipliers are used to speed up the calculation when similar Rooms are repeated more than once. Essentially, a given simulation with the Room is run once and then the result is multiplied by the multiplier. This means that the “repetition” isn’t in a particular direction (it’s essentially in the exact same location) and this comes with some inaccuracy. However, this error might not be too large if the Rooms are similar enough and it can often be worth it since it can greatly speed up the calculation.

property outdoor_shades

Get an array of all outdoor shades assigned to this object.

property properties

Get object properties, including Radiance, Energy and other properties.

property roof_ceilings

Get a tuple of all of the RoofCeiling Faces of the Room.

property shades

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

property story

Get or set text for the story identifier to which this Room belongs.

Rooms sharing the same story identifier are considered part of the same story in a Model. Note that the story identifier has no character restrictions much like display_name.

property to

Room writer object.

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

Usage:

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

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 volume

Get the volume of the room.

Note that, if this room faces do not form a closed solid the value of this property will not be accurate.

property walls

Get a tuple of all of the Wall Faces of the Room.

property zone

Get or set text for the zone identifier to which this Room belongs.

Rooms sharing the same zone identifier are considered part of the same zone in a Model. If the zone identifier has not been specified, it will be the same as the Room identifier.

Note that the zone identifier has no character restrictions much like display_name.