dragonfly.room2d module

Dragonfly Room2D.

class dragonfly.room2d.Room2D(identifier, floor_geometry, floor_to_ceiling_height, boundary_conditions=None, window_parameters=None, shading_parameters=None, is_ground_contact=False, is_top_exposed=False, tolerance=0)

Bases: _BaseGeometry

A volume defined by an extruded floor plate, representing a single room or space.

Parameters

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

• floor_geometry – A single horizontal Face3D object representing the floor plate of the Room. Note that this Face3D must be horizontal to be valid.

• floor_to_ceiling_height – A number for the height above the floor where the ceiling begins. This should be in the same units system as the input floor_geometry. Typical values range from 3 to 5 meters.

• boundary_conditions – A list of boundary conditions that match the number of segments in the input floor_geometry. These will be used to assign boundary conditions to each of the walls of the Room in the resulting model. If None, all boundary conditions will be Outdoors or Ground depending on whether ceiling of the room is below 0 (the assumed ground plane). Default: None.

• window_parameters – A list of WindowParameter objects that dictate how the window geometries will be generated for each of the walls. If None, no windows will exist over the entire Room2D. Default: None.

• shading_parameters – A list of ShadingParameter objects that dictate how the shade geometries will be generated for each of the walls. If None, no shades will exist over the entire Room2D. Default: None.

• is_ground_contact – A boolean noting whether this Room2D has its floor in contact with the ground. Default: False.

• is_top_exposed – A boolean noting whether this Room2D has its ceiling exposed to the outdoors. Default: False.

• tolerance – The maximum difference between z values at which point vertices are considered to be in the same horizontal plane. This is used to check that all vertices of the input floor_geometry lie in the same horizontal floor plane. Default is 0, which will not perform any check.

Properties:

• identifier

• display_name

• full_id

• floor_geometry

• floor_to_ceiling_height

• boundary_conditions

• window_parameters

• shading_parameters

• air_boundaries

• is_ground_contact

• is_top_exposed

• skylight_parameters

• parent

• has_parent

• floor_segments

• floor_segments_2d

• segment_count

• segment_normals

• floor_height

• ceiling_height

• volume

• floor_area

• exterior_wall_area

• exterior_aperture_area

• is_core

• is_perimeter

• min

• max

• center

• user_data

ToString()

Overwrite .NET ToString.

add_prefix(prefix)

Change the identifier of this object 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 segments’) identifier and display_name. It is recommended that this prefix be short to avoid maxing out the 100 allowable characters for dragonfly identifiers.

align(line_ray, distance)

Move any Room2D vertices within a given distance of a line to be on that line.

This is useful to clean up cases where wall segments have a lot of zig zags in them.

All properties assigned to the Room2D will be preserved and the number of vertices will remain constant. This means that this method can often create duplicate vertices and it might be desirable to run the remove_duplicate_vertices method after running this one.

Parameters

• line_ray – A ladybug_geometry Ray2D or LineSegment2D to which the Room2D vertices will be aligned. Ray2Ds will be interpreted as being infinite in both directions while LineSegment2Ds will be interpreted as only existing between two points.

• distance – The maximum distance between a vertex and the line_ray where the vertex will be moved to lie on the line_ray. Vertices beyond this distance will be left as they are.

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

Check whether the Room2D’s floor geometry is degenerate with 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).

• raise_exception – If True, a ValueError will be raised if the object intersects with itself. (Default: True).

• detailed – Boolean for whether the returned object is a detailed list of dicts with error info or a string with a message. (Default: False).

Returns

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

check_horizontal(tolerance=0.01, raise_exception=True)

Check whether the Room2D’s floor geometry is horizontal within a tolerance.

Parameters

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

• raise_exception – Boolean to note whether a ValueError should be raised if the room floor geometry is not horizontal.

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

Check whether the Room2D’s floor geometry intersects itself (like a bowtie).

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

Parameters

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

• raise_exception – If True, a ValueError will be raised if the object intersects with itself. (Default: True).

• detailed – Boolean for whether the returned object is a detailed list of dicts with error info or a string with a message. (Default: False).

Returns

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

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

Check whether the window and skylight parameters produce valid apertures.

This means that this Room’s windows do not overlap with one another and, in the case of detailed windows, the polygons do not self-intersect. It also means that skylights do not extend past the boundary of the room.

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 – Boolean to note whether a ValueError should be raised if the window parameters are not valid.

• detailed – Boolean for whether the returned object is a detailed list of dicts with error info or a string with a message. (Default: False).

Returns

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

coordinate_room_2d_vertices(room_2d, distance, tolerance=0.01)

Insert vertices to this Room2D to coordinate this Room2D with another Room2D.

This is sometimes a useful operation to run after using the pull_to_room_2d method in order to address the case that the Room2D to which this one was pulled has more vertices along the adjacency boundary than this Room2D. In this case, the adjacency between the two Room2Ds will not be clean and extra vertices must be inserted into this Room2D so that geometry matches along the room adjacency.

Any vertices of the neighboring input room_2d that are within the specified distance but cannot be matched to a vertex on this Room2D within the tolerance will be inserted into this Room2D, splitting the wall segment in the process.

Parameters

• room_2d – A Room2D with which the vertices of this Room2D will be coordinated.

• distance – The maximum distance between a Room2D vertex and the other Room2D where the vertex will be moved to lie on the other Room2D. Vertices beyond this distance will be left as they are.

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

duplicate()

Get a copy of this object.

static find_adjacency(room_2ds, tolerance=0.01)

Get a list with all adjacent pairs of segments between input Room2Ds.

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

Parameters

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

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

Returns

A list of tuples for each discovered adjacency. Each tuple contains 2 sub-tuples with two elements. The first element is the Room2D and the second is the index of the wall segment that is adjacent.

static floor_segment_by_index(geometry, segment_index)

Get a particular LineSegment3D from a Face3D object.

The logic applied by this method to select the segment is the same that is used to assign lists of values to the floor_geometry (eg. boundary conditions).

Parameters

• geometry – A Face3D representing floor geometry.

• segment_index – An integer for the index of the segment to return.

classmethod from_dict(data, tolerance=0, persist_abridged=False)

Initialize a Room2D from a dictionary.

Parameters

• data – A dictionary representation of a Room2D object.

• tolerance – The maximum difference between z values at which point vertices are considered to be in the same horizontal plane. This is used to check that all vertices of the input floor_geometry lie in the same horizontal floor plane. Default is 0, which will not perform any check.

• persist_abridged – Set to True when the properties of the Room2D dictionary are abridged and you want to ensure that these exact same abridged properties persist into the output of Room2D.to_dict(abridged=True). It is useful when trying to edit the Room2D independently of a Model and there are no plans to edit any extension properties of the Room2D. THIS IS AN ADVANCED OPTION. (Default: False).

classmethod from_honeybee(room, tolerance)

Initialize a Room2D from a Honeybee Room.

Note that Dragonfly Room2Ds are abstractions of Honeybee Rooms and there will be loss of information if the Honeybee Room is not an extruded floor plate or if extension properties are assigned to individual Faces or Apertures instead of at the Room level.

If the Honeybee Room contains no Floor Faces, None will be returned.

Parameters

• room – A Honeybee Room object.

• tolerance – The maximum difference between values at which point vertices are considered to be the same.

classmethod from_polygon(identifier, polygon, floor_height, floor_to_ceiling_height, boundary_conditions=None, window_parameters=None, shading_parameters=None, is_ground_contact=False, is_top_exposed=False)

Create a Room2D from a ladybug-geometry Polygon2D and a floor_height.

Note that this method is not recommended for a Room with one or more holes (like a courtyard) since polygons cannot have holes within them.

Parameters

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

• polygon – A single Polygon2D object representing the floor plate of the Room.

• floor_height – A float value to place the polygon within 3D space.

• floor_to_ceiling_height – A number for the height above the floor where the ceiling begins. Typical values range from 3 to 5 meters.

• boundary_conditions – A list of boundary conditions that match the number of segments in the input floor_geometry. These will be used to assign boundary conditions to each of the walls of the Room in the resulting model. If None, all boundary conditions will be Outdoors or Ground depending on whether ceiling of the room is below 0 (the assumed ground plane). Default: None.

• window_parameters – A list of WindowParameter objects that dictate how the window geometries will be generated for each of the walls. If None, no windows will exist over the entire Room2D. Default: None.

• shading_parameters – A list of ShadingParameter objects that dictate how the shade geometries will be generated for each of the walls. If None, no shades will exist over the entire Room2D. Default: None.

• is_ground_contact – A boolean to note whether this Room2D has its floor in contact with the ground. Default: False.

• is_top_exposed – A boolean to note whether this Room2D has its ceiling exposed to the outdoors. Default: False.

classmethod from_vertices(identifier, vertices, floor_height, floor_to_ceiling_height, boundary_conditions=None, window_parameters=None, shading_parameters=None, is_ground_contact=False, is_top_exposed=False)

Create a Room2D from 2D vertices with each vertex as an iterable of 2 floats.

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

Parameters

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

• vertices – A flattened list of 2 or more vertices as (x, y) that trace the outline of the floor plate.

• floor_height – A float value to place the polygon within 3D space.

• floor_to_ceiling_height – A number for the height above the floor where the ceiling begins. Typical values range from 3 to 5 meters.

• boundary_conditions – A list of boundary conditions that match the number of segments in the input floor_geometry. These will be used to assign boundary conditions to each of the walls of the Room in the resulting model. If None, all boundary conditions will be Outdoors or Ground depending on whether ceiling of the room is below 0 (the assumed ground plane). Default: None.

• window_parameters – A list of WindowParameter objects that dictate how the window geometries will be generated for each of the walls. If None, no windows will exist over the entire Room2D. Default: None.

• shading_parameters – A list of ShadingParameter objects that dictate how the shade geometries will be generated for each of the walls. If None, no shades will exist over the entire Room2D. Default: None.

• is_ground_contact – A boolean to note whether this Room2D has its floor in contact with the ground. Default: False.

• is_top_exposed – A boolean to note whether this Room2D has its ceiling exposed to the outdoors. Default: False.

static generate_alignment_axes(room_2ds, distance, direction=Vector2D(0.0, 1.0), angle_tolerance=1.0)

Get suggested LineSegment2Ds for the Room2D.align method.

This method will return the most common axes across the input Room2D geometry along with the number of Room2D segments that correspond to each axis. The latter can be used to filter the suggested alignment axes to get only the most common ones across the input Room2Ds.

Parameters

• room_2ds – A list of Room2D objects for which common axes will be evaluated.

• distance – A number for the distance that will be used in the alignment operation. This will be used to determine the resolution at which alignment axes are generated and evaluated. Smaller alignment distances will result in the generation of more common_axes since a finer resolution can differentiate common that would typically be grouped together. For typical building geometry, an alignment distance of 0.3 meters or 1 foot is typically suitable for eliminating unwanted details while not changing the geometry too much from its original location.

• direction – A Vector2D object to represent the direction in which the common axes will be evaluated and generated.

• angle_tolerance – The max angle difference in radians that the Room2D segment direction can differ from the input direction before the segments are not factored into this calculation of common axes.

• Returns – A tuple with two elements.

• common_axes (-) – A list of LineSegment2D objects for the common axes across the input Room2Ds.

• axis_values (-) – A list of integers that aligns with the common_axes and denotes how many segments of the input Room2D each axis relates to. Higher numbers indicate that that the axis is more commonly aligned across the Room2Ds.

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

Get a gridded Mesh3D object offset from the floor of this room.

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

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.

static group_by_adjacency(rooms)

Group Room2Ds together that are connected by adjacencies.

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

Parameters

rooms – A list of Room2Ds 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 Room2Ds 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 Room2Ds to be grouped by their air boundary adjacency.

Returns

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

static grouped_horizontal_boundary(room_2ds, min_separation=0, tolerance=0.01)

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

This method will attempt to produce a boundary that follows along the walls of the Room2Ds and it is not suitable for groups of Room2Ds 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 or if overlaps between input Room2Ds result in failure.

Parameters

• room_2ds – A list of Room2Ds for which the horizontal boundary will be computed.

• min_separation – A number for the minimum distance between Room2Ds that is considered a meaningful separation. Gaps between Room2Ds that are less than this distance will be ignored and the boundary will continue across the gap. When the input Room2Ds have floor_geometry representing the boundaries defined by the interior wall finishes, 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 Room2Ds. When Room2Ds are touching one another (with Room2D floor_geometry drawn to the center lines of interior 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).

static intersect_adjacency(room_2ds, tolerance=0.01, preserve_wall_props=True)

Intersect the line segments of an array of Room2Ds to ensure matching walls.

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

• room_2ds – A list of Room2Ds for which adjacent segments 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.

• preserve_wall_props – Boolean to note whether existing window parameters, shading parameters and boundary conditions should be preserved as vertices are added during intersection. If False, all boundary conditions are replaced with Outdoors, all window parameters are erased, and this method will execute quickly. If True, an attempt will be made to split window parameters new across colinear segments. Existing boundary conditions will also be kept. (Default: True).

Returns

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

static join_by_boundary(room_2ds, polygon, hole_polygons=None, floor_to_ceiling_height=None, identifier=None, display_name=None, tolerance=0.01)

Join several Room2D together using a boundary Polygon as a guide.

All properties of segments along the boundary polygon will be preserved. The largest Room2D that is identified within the boundary polygon will determine the extension properties of the resulting Room unless the supplied identifier matches an existing Room2D inside the polygon. Skylights will be merged if they are of the same type or if they are None.

It is recommended that the Room2Ds be aligned to the boundaries of the polygon and duplicate vertices be removed before passing them through this method. However, colinear vertices should not be removed where possible. This helps ensure that relevant Room2D segments are colinear with the polygon and so they can influence the result.

Parameters

• room_2ds – A list of Room2Ds which will be joined together using the polygon.

• polygon – A ladybug_geometry Polygon2D which will become the boundary of the output joined Room2D.

• hole_polygons – An optional list of hole polygons, which will add holes into the output joined Room2D polygon. (Default: None).

• floor_to_ceiling_height – An optional number to set the floor-to-ceiling height of the resulting Room2D. If None, it will be the maximum of the Room2Ds that are found inside the polygon, which ensures that all window geometries are included in the output. If specified and it is lower than the maximum Room2D height, any detailed windows will be automatically trimmed to accommodate the new floor-to-ceiling height. (Default: None).

• identifier – An optional text string for the identifier of the new joined Room2D. If this matches an existing Room2D inside of the polygon, the existing Room2D will be used to set the extension properties of the output Room2D. If None, the identifier and extension properties of the output Room2D will be those of the largest Room2D found inside of the polygon. (Default: None).

• display_name – An optional text string for the display_name of the new joined Room2D. If None, the display_name will be taken from the largest existing Room2D inside the polygon or the existing Room2D matching the identifier above. (Default: None).

• tolerance – The minimum distance between a vertex and the polygon boundary at which point the vertex is considered to lie on the polygon. (Default: 0.01, suitable for objects in meters).

static join_room_2ds(room_2ds, min_separation=0, tolerance=0.01)

Join Room2Ds together that are touching one another within a min_separation.

When the min_separation is less than or equal to the tolerance, all properties of segments for the input Room2Ds will be preserved. When the min_separation is larger than the tolerance, an attempt is made to preserve all wall properties but there is a risk of losing some windows just in the region where two Room2Ds are joined together across a gap between them. This risk can be overcome by inserting Room2D vertices around where the gap will be crossed between that Room2D and the other Room2D.

The largest Room2D that is identified within each connected group will determine the extension properties of the resulting Room2D. Skylights will be merged across rooms if they are of the same type or if they are None.

Parameters

• room_2ds – A list of Room2Ds which will be joined together where they touch one another.

• min_separation – A number for the minimum distance between Room2Ds that is considered a meaningful separation. Gaps between Room2Ds that are less than this distance will result in the Room2Ds being joined across the gap. When the input Room2Ds have floor_geometry representing the boundaries defined by the interior wall finishes, this input can be thought of as the maximum interior wall thickness. When Room2Ds are perfectly touching one another within the tolerance (with Room2D floor_geometry drawn to the center lines of interior 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 and more reliable. 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 minimum distance between a vertex and the polygon boundary at which point the vertex is considered to lie on the polygon. (Default: 0.01, suitable for objects in meters).

label_point(tolerance=0.01)

Get a Point3D to label this Room2D in 3D space.

This point will always lie within the polygon formed by the floor_geometry regardless of whether this geometry is concave or has holes.

Parameters

tolerance – The tolerance to which the pole_of_inaccessibility will be computed in the event that the floor_geometry is concave or has holes. Note that this does not need to be equal to the Model tolerance and should usually be larger than the Model tolerance to avoid long calculation times. (Default: 0.01).

move(moving_vec)

Move this Room2D along a vector.

Parameters

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

offset_skylight_parameters(offset_distance=0.05, tolerance=0.01)

Offset detailed skylights so all vertices are inside the Room2D.

Parameters

• offset_distance – Distance from the edge of the room that the polygons will be offset to. (Default: 0.05, suitable for objects in meters).

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

pull_to_polygon(polygon, distance, snap_vertices=True)

Pull this Room2D’s vertices to a Polygon2D.

This includes both an alignment to the polygon’s segments as well as an optional snapping to the polygon’s vertices.

All properties assigned to this Room2D will be preserved and the number of vertices will remain constant. This means that this method can often create duplicate vertices and it might be desirable to run the remove_duplicate_vertices method after running this one.

Parameters

• polygon – A ladybug_geometry Polygon2D to which this Room2D’s vertices will be pulled.

• distance – The maximum distance between a Room2D vertex and the polygon where the vertex will be moved to lie on the polygon. Vertices beyond this distance will be left as they are.

• snap_vertices – A boolean to note whether Room2D vertices that are close to the polygon vertices within the distance should be snapped to the polygon vertex instead of simply being aligned to the nearest polygon segment. (Default: True).

pull_to_polyline(polyline, distance, snap_vertices=True)

Pull this Room2D’s vertices to a Polyline2D.

This includes both an alignment to the polyline’s segments as well as an optional snapping to the polyline’s vertices.

All properties assigned to this Room2D will be preserved and the number of vertices will remain constant. This means that this method can often create duplicate vertices and it might be desirable to run the remove_duplicate_vertices method after running this one.

Parameters

• polyline – A ladybug_geometry Polyline2D to which this Room2D’s vertices will be pulled.

• distance – The maximum distance between a Room2D vertex and the polyline where the vertex will be moved to lie on the polyline. Vertices beyond this distance will be left as they are.

• snap_vertices – A boolean to note whether Room2D vertices that are close to the polyline vertices within the distance should be snapped to the polyline vertex instead of simply being aligned to the nearest polyline segment. (Default: True).

pull_to_room_2d(room_2d, distance, snap_vertices=True)

Pull this Room2D’s vertices to another Room2D.

This includes both an alignment to the other Room2D’s segments as well as an optional snapping to the Room2D’s vertices.

All properties assigned to this Room2D will be preserved and the number of vertices will remain constant. This means that this method can often create duplicate vertices and it might be desirable to run the remove_duplicate_vertices method after running this one.

Parameters

• room_2d – A Room2D to which this Room2D’s vertices will be pulled.

• distance – The maximum distance between a Room2D vertex and the other Room2D where the vertex will be moved to lie on the other Room2D. Vertices beyond this distance will be left as they are.

• snap_vertices – A boolean to note whether Room2D vertices that are close to the other Room2D vertices within the distance should be snapped to the Room2D vertex instead of simply being aligned to the nearest Room2D segment. (Default: True).

reflect(plane)

Reflect this Room2D across a plane.

Parameters

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

remove_colinear_vertices(tolerance=0.01, preserve_wall_props=True)

Get a version of this Room2D without colinear or duplicate vertices.

Parameters

• tolerance – The minimum distance between a vertex and the line it lies upon at which point the vertex is considered colinear. Default: 0.01, suitable for objects in meters.

• preserve_wall_props – Boolean to note whether existing window parameters and Ground boundary conditions should be preserved as vertices are removed. If False, all boundary conditions are replaced with Outdoors, all window parameters are erased, and this method will execute quickly. If True, an attempt will be made to merge window parameters together across colinear segments, translating simple window parameters to rectangular ones if necessary. Also, existing Ground boundary conditions will be kept. (Default: True).

Returns

A new Room2D derived from this one with its colinear vertices removed.

remove_degenerate_holes(tolerance=0.01)

Remove any holes in this Room2D with an area that evaluates to zero.

All properties assigned to the Room2D will be preserved.

Parameters

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

remove_duplicate_vertices(tolerance=0.01)

Remove duplicate vertices from this Room2D.

All properties assigned to the Room2D will be preserved.

Parameters

tolerance – The minimum distance between a vertex and the line it lies upon at which point the vertex is considered colinear. (Default: 0.01, suitable for objects in meters).

Returns

A list of integers for the indices of segments that have been removed.

remove_short_segments(distance, angle_tolerance=1.0)

Get a version of this Room2D with consecutive short segments removed.

To patch over the segments, an attempt will first be made to find the intersection of the two neighboring segments. If these two lines are parallel, they will simply be connected with a segment.

Properties assigned to the Room2D will be preserved for the segments that are not removed.

Parameters

• distance – The maximum length of a segment below which the segment will be considered for removal.

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

remove_small_holes(area_threshold)

Remove any holes in this Room2D that are below a certain area threshold.

All properties assigned to the Room2D will be preserved.

Parameters

area_threshold – A number for the area below which holes will be removed.

reset_adjacency()

Set all Surface boundary conditions of this Room2D to be Outdoors.

rotate_xy(angle, origin)

Rotate this Room2D counterclockwise in the 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.

scale(factor, origin=None)

Scale this Room2D by a factor from an origin point.

Note that this will scale both the Room2D geometry and the WindowParameters and FacadeParameters assigned to this Room2D.

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

segment_orientations(north_vector=Vector2D(0.0, 1.0))

A list of numbers between 0 and 360 for the orientation of the segments.

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

Parameters

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

set_adjacency(other_room_2d, self_seg_index, other_seg_index, resolve_window_conflicts=True)

Set a segment of this Room2D to be adjacent to another and vice versa.

Note that, adjacent segments must possess matching WindowParameters in order to be valid.

Parameters

• other_room_2d – Another Room2D object to be set adjacent to this one.

• self_seg_index – An integer for the wall segment of this Room2D that will be set adjacent to the other_room_2d.

• other_seg_index – An integer for the wall segment of the other_room_2d that will be set adjacent to this Room2D.

• resolve_window_conflicts – Boolean to note whether conflicts between window parameters of adjacent segments should be resolved during adjacency setting or an error should be raised about the mismatch. Resolving conflicts will default to the window parameters with the larger are and assign them to the other segment. (Default: True).

set_air_boundary(seg_index)

Set a single segment of this Room2D to have an air boundary type.

Parameters

seg_index – An integer for the wall segment of this Room2D for which the boundary condition will be set.

set_boundary_condition(seg_index, boundary_condition)

Set a single segment of this Room2D to have a certain boundary condition.

Parameters

• seg_index – An integer for the wall segment of this Room2D for which the boundary condition will be set.

• boundary_condition – A boundary condition object.

set_outdoor_shading_parameters(shading_parameter)

Set all of the outdoor walls to have the same shading parameters.

set_outdoor_window_parameters(window_parameter)

Set all of the outdoor walls to have the same window parameters.

set_window_parameter(seg_index, window_parameter=None)

Set a single segment of this Room2D to have a certain window parameter.

Parameters

• seg_index – An integer for the wall segment of this Room2D for which the window parameter will be set.

• window_parameter – A window parameter object to be assigned to the segment. If None, any existing WindowParameters assigned to the segment will be removed. (Default: None).

snap_to_grid(grid_increment)

Snap this Room2D’s vertices to the nearest grid node defined by an increment.

All properties assigned to the Room2D will be preserved and the number of vertices will remain constant. This means that this method can often create duplicate vertices and it might be desirable to run the remove_duplicate_vertices method after running this one.

Parameters

grid_increment – A positive number for dimension of each grid cell. This typically should be equal to the tolerance or larger but should not be larger than the smallest detail of the Room2D that you wish to resolve.

snap_to_line_end_points(line, distance)

Snap this Room2D’s vertices to the endpoints of a line segment.

All properties assigned to this Room2D will be preserved and the number of vertices will remain constant. This means that this method can often create duplicate vertices and it might be desirable to run the remove_duplicate_vertices method after running this one.

Parameters

• line – A ladybug_geometry LineSegment2D to which the Room2D vertices will be snapped if they are near the end points.

• distance – The maximum distance between a Room2D vertex and the polyline where the vertex will be moved to lie on the polyline. Vertices beyond this distance will be left as they are.

static solve_adjacency(room_2ds, tolerance=0.01, resolve_window_conflicts=True)

Solve for all adjacencies between a list of input Room2Ds.

Parameters

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

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

• resolve_window_conflicts – Boolean to note whether conflicts between window parameters of adjacent segments should be resolved during adjacency setting or an error should be raised about the mismatch. Resolving conflicts will default to the window parameters with the larger are and assign them to the other segment. (Default: True).

Returns

A list of tuples with each tuple containing 2 sub-tuples for wall segments paired in the process of solving adjacency. Sub-tuples have the Room2D as the first item and the index of the adjacent wall as the second item. This data can be used to assign custom properties to the new adjacent walls (like assigning custom window parameters for interior windows, assigning air boundaries, or custom boundary conditions).

to_core_perimeter(perimeter_offset, air_boundary=False, tolerance=0.01)

Translate this Room2D into a list of Room2Ds separated by core and perimeter.

All of the resulting Room2Ds will have the same properties as this initial Room2D with all windows and boundary conditions conserved. All of the newly-created interior walls between the core and perimeter Room2Ds will have Surface boundary conditions.

Parameters

• perimeter_offset – An optional positive number that will be used to offset the perimeter of the all_story_geometry to create core/perimeter zones. If this value is 0, no offset will occur and each story will be represented with a single Room2D per polygon (Default: 0).

• air_boundary – A boolean to note whether all of the new wall adjacencies should be set to an AirBoundary type. (Default: False).

• tolerance – The maximum difference between x, y, and z values at which point vertices are considered to be the same. This is also needed as a means to determine which floor geometries are equivalent to one another and should be a part the same Story. Default: 0.01, suitable for objects in meters.

Returns

A list of Room2D for core Room2Ds followed by perimeter Room2Ds. If the current Room2D cannot be converted into core and perimeter Room2Ds, a list with the current Room2D instance will be returned.

to_dict(abridged=False, included_prop=None)

Return Room2D as a dictionary.

Parameters

• abridged – Boolean to note whether the extension properties of the object (ie. program_type, construction_set) 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.

to_honeybee(multiplier=1, add_plenum=False, tolerance=0.01, enforce_bc=True, enforce_solid=True)

Convert Dragonfly Room2D to a Honeybee Room.

Parameters

• multiplier – An integer greater than 0 that denotes the number of times the room is repeated. You may want to set this differently depending on whether you are exporting each room as its own geometry (in which case, this should be 1) or you only want to simulate the “unique” room once and have the results multiplied. Default: 1.

• add_plenum – Boolean to indicate whether ceiling/floor plenums should be auto-generated for the Room in which case this output will be a list instead of a single Room. The height of the ceiling plenum will be autocalculated as the difference between the Room2D ceiling height and Story ceiling height. The height of the floor plenum will be autocalculated as the difference between the Room2D floor height and Story floor height. (Default: False).

• tolerance – The minimum distance in z values of floor_height and floor_to_ceiling_height at which adjacent Faces will be split. This is also used in the generation of Windows, and to check if the Room ceiling is adjacent to the upper floor of the Story before generating a plenum. Default: 0.01, suitable for objects in meters.

• enforce_bc – Boolean to note whether an exception should be raised if apertures are assigned to Wall with an illegal boundary conditions (True) or if the invalid boundary condition should be replaced with an Outdoor boundary condition (False). (Default: True).

• enforce_solid – Boolean to note whether the room should be translated as a solid extrusion whenever translating the room with custom roof geometry produces a non-solid result (True) or the non-solid room geometry should be allowed to remain in the result (False). The latter is useful for understanding why a particular roof geometry has produced a non-solid result. (Default: True).

Returns

A tuple with the two items below.

• hb_room – If add_plenum is False, this will be honeybee-core Room

  representing the dragonfly Room2D. If the add_plenum argument is True, this item will be a list of honeybee-core Rooms, with the hb_room as the first item, and up to two additional items:

  • ceil_plenum – A honeybee-core Room representing the ceiling

    plenum. If there isn’t enough space between the Story floor_to_floor_height and the Room2D floor_to_ceiling height, this item will be None.

  • floor_plenum – A honeybee-core Room representing the floor plenum.

    If there isn’t enough space between the Story floor_height and the Room2D floor_height, this item will be None.

• adjacencies – A list of tuples that record any adjacencies that

  should be set on the level of the Story to which the Room2D belongs. Each tuple will have a honeybee Face as the first item and a tuple of Surface.boundary_condition_objects as the second item.

to_rectangular_windows()

Convert all of the windows of the Room2D to the RectangularWindows format.

update_floor_geometry(new_floor_geometry, edit_code, tolerance=0.01)

Change the floor_geometry of the Room2D with segment-altering specifications.

This method is intended to be used when the floor geometry has been edited by some external means and this Room2D should be updated for coordination.

The method tries to infer whether an removed floor segment means that an original segment has been merged into another or removed completely using the colinearity of the original segments. A removed segment that is colinear with its neighbor will be merged into it while a removed segment that was not colinear will simply be deleted. Similarly, the method will infer if an added segment indicates a split in an original segment using colinearity. When the result in the new_floor_geometry is two colinear segments, properties of the original segment will be split across the new segments. Otherwise the new segment will receive default properties.

Parameters

• new_floor_geometry – A Face3D for the new floor_geometry of this Room2D. Note that this method expects the plane of this Face3D to match the original floor_geometry Face3D and for the counter-clockwise vertex ordering of the segments to be the same as the original floor geometry (though segments can obviously be added or removed).

• edit_code –

  A text string that indicates the operations that were performed on the original floor_geometry segments to yield the new_floor_geometry. The following letters are used in this code to indicate the following:

  • K = a segment that has been kept (possibly moved but not removed)

  • X = a segment that has been removed

  • A = a segment that has been added

  For example, KXKAKKA means that the first segment was kept, the next removed, the next kept, the next added, followed by two kept segments and ending in an added segment.

• tolerance – The minimum difference between the coordinate values at which they are considered co-located, used to determine colinearity. Default: 0.01, suitable for objects in meters.

property air_boundaries

Get or set a tuple of booleans for whether each wall has an air boundary type.

False values indicate a standard opaque type while True values indicate an AirBoundary type. All walls will be False by default. Note that any walls with a True air boundary must have a Surface boundary condition without any windows.

property boundary_conditions

Get or set a tuple of boundary conditions for the wall boundary conditions.

property ceiling_height

Get a number for the height of the ceiling above the ground.

property center

Get a Point2D for the center bounding rectangle vertex in the XY plane.

This is useful in calculations to determine if this Room2D is inside other polygons.

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 exterior_aperture_area

Get a the total aperture area of the Room with an Outdoors boundary condition.

property exterior_wall_area

Get a the total wall area of the Room with an Outdoors boundary condition.

property floor_area

Get a number for the floor area of the Room.

property floor_geometry

A horizontal Face3D object representing the floor plate of the Room.

property floor_height

Get a number for the height of the floor above the ground.

property floor_segments

Get a list of LineSegment3D objects for each wall of the Room.

property floor_segments_2d

Get a list of LineSegment2D objects for each wall of the Room.

property floor_to_ceiling_height

Get or set a number for the distance between the floor and the ceiling.

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 has_parent

Get a boolean noting whether this Room2D has a parent Story.

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). This property is also used to reference the object across a Model.

property interior_wall_area

Get a the total wall area of the Room without an Outdoors or Ground BC.

property is_core

Get a boolean for whether the Room2D is in the core of a story.

Core Room2Ds have no walls exposed to the outdoors.

property is_ground_contact

Get or set a boolean noting whether the floor is in contact with the ground.

property is_perimeter

Get a boolean for whether the Room2D is on the perimeter of a story.

Perimeter Room2Ds have walls exposed to the outdoors.

property is_top_exposed

Get or set a boolean noting whether the ceiling is exposed to the outdoors.

property max

Get a Point2D for the max bounding rectangle vertex in the XY plane.

This is useful in calculations to determine if this Room2D is in proximity to other Room2Ds.

property min

Get a Point2D for the min bounding rectangle vertex in the XY plane.

This is useful in calculations to determine if this Room2D is in proximity to other Room2Ds.

property parent

Get the parent Story if it is assigned. None if it is not assigned.

property properties

Object properties, including Radiance, Energy and other properties.

property segment_count

Get the number of segments making up the floor geometry.

This is equal to the number of walls making up the Room.

property segment_normals

Get a list of Vector2D objects for the normal of each segment.

property shading_parameters

Get or set a tuple of ShadingParameters describing how to generate shades.

property skylight_parameters

Get or set SkylightParameters describing how to generate skylights.

property to

Room2D writer object.

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

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 a number for the volume of the Room.

property window_parameters

Get or set a tuple of WindowParameters describing how to generate windows.