honeybee.room module¶
Honeybee Room.

class
honeybee.room.
Room
(identifier, faces, tolerance=0, angle_tolerance=0)[source]¶ Bases:
honeybee._basewithshade._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
story
exclude_floor_area
indoor_furniture
indoor_shades
outdoor_shades
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
()¶

add_indoor_furniture
(shade)[source]¶ 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)[source]¶ Change the identifier of this object and all 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.0, 1.0))[source]¶ 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 Yaxis (0, 1).

check_non_zero
(tolerance=0.0001, raise_exception=True, detailed=False)[source]¶ Check that the Room’s geometry components are above a “zero” area tolerance.
This includes all of the Room’s Faces, Apertures, Doors and Shades.
 Parameters
tolerance – The minimum acceptable area of the object. Default is 0.0001, which is equal to 1 cm2 when model units are meters. This is just above the smallest size that OpenStudio will accept.
raise_exception – If True, a ValueError will be raised if the object area is below the tolerance. (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)[source]¶ 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.

check_self_intersecting
(tolerance=0.01, raise_exception=True, detailed=False)[source]¶ Check that no edges of the Room’s geometry components selfintersect.
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)[source]¶ 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
(raise_exception=True, detailed=False)[source]¶ Check that this Face’s subfaces do not overlap with one another.
 Parameters
raise_exception – Boolean to note whether a ValueError should be raised if a subfaces 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)[source]¶ Check that room’s subfaces are coplanar with faces and in the face boundary.
Note this does not check the planarity of the subfaces themselves, whether they selfintersect, or whether they have a nonzero 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 subface 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.

duplicate
()¶ Get a copy of this object.

faces_by_guide_surface
(surface_geometry, directional_vector=None, tolerance=0.01, angle_tolerance=1.0)[source]¶ 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)[source]¶ 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.0, 0.0, 0.0))[source]¶ 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)[source]¶ 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)[source]¶ 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_grid
(x_dim, y_dim=None, offset=1.0)[source]¶ Get a list of 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 not 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)[source]¶ 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)[source]¶ 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 sublist containing rooms that share adjacencies.

static
group_by_air_boundary_adjacency
(rooms)[source]¶ 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 sublist containing rooms that share adjacent air boundaries. If a Room has no air boundaries it will the the only item within its sublist.

static
group_by_floor_height
(rooms, min_difference=0.01)[source]¶ 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 sublist representing a different floor height.
floor_heights  A list of floor heights with one floor height for each sublist of the output grouped_rooms.

static
group_by_orientation
(rooms, group_count=None, north_vector=Vector2D(0.0, 1.0))[source]¶ 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 Yaxis (0, 1).
 Returns
A tuple with three items.
grouped_rooms  A list of lists of honeybee rooms with each sublist 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.

is_geo_equivalent
(room, tolerance=0.01)[source]¶ Get a boolean for whether this object is geometrically equivalent to another.
This will also check all child Faces, Apertures and Doors for equivalency but not assigned shades.
 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.

move
(moving_vec)[source]¶ 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.

reflect
(plane)[source]¶ 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)[source]¶ Remove colinear and duplicate vertices from this object’s Faces and Subfaces.
Note that this does not affect any 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
()[source]¶ 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)[source]¶ 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)[source]¶ Create a Rooms that represent an Lshaped 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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).

skylight_apertures_by_ratio
(ratio, tolerance=0.01)[source]¶ 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 a part of a rectangle. 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.
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)[source]¶ 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.

static
stories_by_floor_height
(rooms, min_difference=2.0)[source]¶ 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)[source]¶ 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).

wall_apertures_by_ratio
(ratio, tolerance=0.01)[source]¶ 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 a part of a rectangle. 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.
Usage:
room = Room.from_box(3.0, 6.0, 3.2, 180) room.wall_apertures_by_ratio(0.4)

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