dragonfly.building module

Dragonfly Building.

class dragonfly.building.Building(identifier, unique_stories=None, room_3ds=None, sort_stories=True)

Bases: _BaseGeometry

A complete Building defined by Stories (and optional extra 3D rooms).

Buildings must have at least one dragonfly Story or one Honeybee Room under the room_3ds property.

Parameters:

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

• unique_stories – An array of unique Dragonfly Story objects that together form the entire building. Stories input here can be in any order but they will be automatically sorted from lowest floor to highest floor when they are assigned to the Building. Note that, if a given Story is repeated several times over the height of the Building, the unique Story included in this list should be the first (lowest) Story of the repeated floors. (Default: None).

• room_3ds – An optional array of 3D Honeybee Room objects for additional Rooms that are a part of the Building but are not represented within the unique_stories. This is useful when there are parts of the Building geometry that cannot easily be represented with the extruded floor plate and sloped roof assumptions that underlie Dragonfly Room2Ds and RoofSpecification. Cases where this input is most useful include sloped walls and certain types of domed roofs that become tedious to implement with RoofSpecification. Matching the Honeybee Room.story property to the Dragonfly Story.display_name of an object within the unique_stories will effectively place the Honeybee Room on that Story for the purposes of floor_area, exterior_wall_area, etc. However, note that the Honeybee Room.multiplier property takes precedence over whatever multiplier is assigned to the Dragonfly Story that the Room.story may reference. (Default: None).

• sort_stories – A boolean to note whether the unique_stories should be sorted from lowest to highest story upon initialization (True) or whether the input order of unique_stories should be left as-is. (Default: True).

Properties:

• identifier

• display_name

• full_id

• unique_stories

• unique_room_2ds

• room_3ds

• room_3d_faces

• room_3d_apertures

• room_3d_doors

• room_3d_shades

• has_room_2ds

• has_room_3ds

• room_2d_story_names

• room_3d_story_names

• story_count

• story_count_above_ground

• unique_stories_above_ground

• height

• height_above_ground

• height_from_first_floor

• footprint_area

• floor_area

• exterior_wall_area

• exterior_aperture_area

• volume

• min

• max

• user_data

ToString()

Overwrite .NET ToString.

add_prefix(prefix)

Change the object identifier 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 repeating buildings) 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 dragonfly identifiers.

add_roof_geometry(roof_geometry, tolerance=0.01, overlap_threshold=0)

Add roof geometry to the stories of this Building.

This method will attempt add each roof geometry to the best Story in the Building by checking for overlaps between the Story’s Room2Ds and the Roof geometry in plan. When a given roof geometry overlaps with several Stories more than the specified overlap_threshold, the top-most Story will get the roof geometry assigned to it unless this top Story has a floor_height above the roof geometry, in which case the next highest story will be checked until a compatible one is found. If a given roof geometry does not overlap with any story geometry or lies below all of the stories, it will not be assigned to the Building.

Parameters:

• roof_geometry – An array of Face3D objects representing the geometry of the Roof.

• tolerance – The maximum difference between values at which point vertices are considered to be the same. (Default: 0.01, suitable for objects in Meters).

• overlap_threshold – A number between 0 and 1 for the fraction of a room’s area that must be covered by a given roof geometry for it to be considered overlapping with that room. This is intended to prevent incorrect roof assignment in cases where roofs extend slightly past the room they are intended for. (Default: 0.05).

add_room_3ds(rooms, add_duplicate_ids=False)

Add additional 3D Honeybee Room objects to this Building.

Parameters:

• stories – A list or tuple of Honeybee Room objects to be added to this building.

• add_duplicate_ids – A boolean to note whether added Rooms that have matching identifiers within the current Building should be ignored (False) or they should be added to the Building creating an ID collision that can be resolved later (True). (Default: False).

add_stories(stories, add_duplicate_ids=False)

Add additional Story objects to this Building.

Using this method will ensure that Stories are ordered according to their floor height as they are added. Also, in the case that Story identifiers match an existing one in this Building, these Stories will be merged together. If add_duplicate_ids is False, Room2Ds that have matching identifiers within a merged Story will not be ignored in order to avoid ID conflicts.

Parameters:

• stories – A list or tuple of Story objects to be added to this Building.

• add_duplicate_ids – A boolean to note whether added Room2Ds that have matching identifiers within each Story should be ignored (False) or they should be added to the Story creating an ID collision that can be resolved later (True). (Default: False).

all_room_2ds()

Get a list of all Room2D objects that form the Building.

all_stories()

Get a list of all Story objects that form the Building.

The Story objects returned here each have a multiplier of 1 and repeated stories are represented will their own Story object. 3D Rooms are not included in this output.

static buildings_to_honeybee(buildings, context_shades=None, shade_distance=None, use_multiplier=True, add_plenum=False, cap=False, tolerance=0.01, enforce_adj=True, enforce_solid=True)

Convert an array of Buildings into several honeybee Models with self-shading.

Each input Building will be exported into its own Model. For each Model, the other input Buildings will appear as context shade geometry. Thus, each Model is its own simulate-able unit accounting for the total self-shading of the input Buildings.

Parameters:

• buildings – An array of Building objects to be converted into honeybee Models that account for their own shading of one another.

• context_shades – An optional array of ContextShade objects that will be added to the honeybee Models if their bounding box overlaps with a given building within the shade_distance.

• shade_distance – An optional number to note the distance beyond which other objects’ shade should not be exported into a given Model. This is helpful for reducing the simulation run time of each Model when other connected buildings are too far away to have a meaningful impact on the results. If None, all other buildings will be included as context shade in each and every Model. Set to 0 to exclude all neighboring buildings from the resulting models. Default: None.

• use_multiplier – If True, the multipliers on this Building’s Stories will be passed along to the generated Honeybee Room objects, indicating the simulation will be run once for each unique room and then results will be multiplied. If False, full geometry objects will be written for each and every floor in the building that are represented through multipliers and all room multipliers will be 1. (Default: True).

• add_plenum – Boolean to indicate whether ceiling/floor plenums should be auto-generated for the Rooms. (Default: False).

• cap – Boolean to note whether building shade representations should be capped with a top face. Usually, this is not necessary to account for blocked sun and is only needed when it’s important to account for reflected sun off of roofs. (Default: False).

• tolerance – The minimum distance in z values of floor_height and floor_to_ceiling_height at which adjacent Faces will be split. Default: 0.01, suitable for objects in meters.

• enforce_adj – Boolean to note whether an exception should be raised if an adjacency between two Room2Ds is invalid (True) or if the invalid Surface boundary condition should be replaced with an Outdoor boundary condition (False). If False, any Walls containing WindowParameters and an illegal boundary condition will also be replaced with an Outdoor boundary condition. (Default: True).

• enforce_solid – Boolean to note whether rooms should be translated as solid extrusions whenever translating them 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 list of honeybee Models that represent the Building.

convert_all_room_3ds_to_2d(extrusion_rooms_only=True, tolerance=0.01, angle_tolerance=1)

Convert all 3D Honeybee Rooms on this Building to a Dragonfly Room2Ds.

This process will add the Room2Ds to an existing Dragonfly Story on the Building if the Honeybee Room.story matches a Story.display_name on this object. If not, a new Story on this Building will be initialized.

Parameters:

• extrusion_rooms_only – A boolean to note whether only the 3D Rooms that can be represented as a Room2D without loss of geometry should be converted to Room2Ds. When True, all 3D Rooms that are not pure extrusions will be left as they are. If False, all 3D Rooms in the model will be translated to Room2D regardless of whether they are extrusions or not, meaning that there may be some loss of geometry or simplification of it.

• tolerance – The maximum difference between values at which point vertices are considered to be the same. (Default: 0.01, suitable for objects in Meters).

• angle_tolerance – The max angle difference in degrees that Face3D normals are allowed to differ from the vertical or horizontal before they are no longer considered as such. (Default: 1 degree).

Returns:

A list of the newly-created Room2D objects from the converted Rooms.

convert_multipliers_to_stories()

Convert this Building’s stories with non-unity multipliers to geometry.

convert_room_3d_to_2d(room_3d_identifier, tolerance=0.01)

Convert a single 3D Honeybee Room to a Dragonfly Room2D on this Building.

This process will add the Room2D to an existing Dragonfly Story on the Building if the Honeybee Room.story matches a Story.display_name on this object. If not, a new Story on this Building will be initialized.

Parameters:

• room_3d_identifier – The identifier of the 3D honeybee Room on this Building that will be converted to a dragonfly Room2D.

• tolerance – The maximum difference between values at which point vertices are considered to be the same. (Default: 0.01, suitable for objects in Meters).

Returns:

The newly-created Room2D object from the converted Room. Will be None if the Honeybee Room is not a closed solid and cannot be converted to a valid Room2D.

convert_room_3ds_to_2d(room_3d_identifiers, tolerance=0.01)

Convert several 3D Honeybee Rooms on this Building to a Dragonfly Room2Ds.

This process will add the Room2Ds to an existing Dragonfly Story on the Building if the Honeybee Room.story matches a Story.display_name on this object. If not, a new Story on this Building will be initialized.

Parameters:

• room_3d_identifiers – A list of the identifiers for the 3D honeybee Rooms on this Building that will be converted to dragonfly Room2Ds.

• tolerance – The maximum difference between values at which point vertices are considered to be the same. (Default: 0.01, suitable for objects in Meters).

Returns:

A list of the newly-created Room2D objects from the converted Rooms. If a given 3D Room is not valid and cannot be converted to a Room2D, it will not be included in this output.

static district_to_honeybee(buildings, use_multiplier=True, add_plenum=False, tolerance=0.01, enforce_adj=True, enforce_solid=True)

Convert an array of Building objects into a single district honeybee Model.

Parameters:

• buildings – An array of Building objects to be converted into a honeybee Model.

• use_multiplier – If True, the multipliers on this Building’s Stories will be passed along to the generated Honeybee Room objects, indicating the simulation will be run once for each unique room and then results will be multiplied. If False, full geometry objects will be written for each and every floor in the building that are represented through multipliers and all resulting multipliers will be 1. (Default: True).

• add_plenum – Boolean to indicate whether ceiling/floor plenums should be auto-generated for the Rooms. (Default: False).

• tolerance – The minimum distance in z values of floor_height and floor_to_ceiling_height at which adjacent Faces will be split. Default: 0.01, suitable for objects in meters.

• enforce_adj – Boolean to note whether an exception should be raised if an adjacency between two Room2Ds is invalid (True) or if the invalid Surface boundary condition should be replaced with an Outdoor boundary condition (False). If False, any Walls containing WindowParameters and an illegal boundary condition will also be replaced with an Outdoor boundary condition. (Default: True).

• enforce_solid – Boolean to note whether rooms should be translated as solid extrusions whenever translating them 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 honeybee Model that represent the district.

duplicate()

Get a copy of this object.

find_adjacency_gaps(gap_distance=0.1, tolerance=0.01)

Identify gaps smaller than a gap_distance between this Building’s Room2Ds.

All cases where gaps can create failed adjacency solving or failed intersections between adjacent stories will be checked.

Parameters:

• gap_distance – The maximum distance between two Room2Ds that is considered an adjacency gap. Differences between Room2Ds that are higher than this distance are considered meaningful gaps to be preserved. This value should be higher than the tolerance to be meaningful. (Default: 0.1, suitable for objects in meters).

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

Returns:

A list of Point2Ds that note the location of any gaps between this Building’s Room2Ds, which are larger than the tolerance but less than the gap_distance.

footprint(tolerance=0.01)

A list of Face3D objects representing the footprint of the building.

The footprint is derived from the lowest story of the building and, if all Room2Ds of this story can be joined into a single continuous polyface, then only one Face3D will be contained in the list output from this method. Otherwise, several Face3Ds may be output.

Parameters:

tolerance – The minimum distance between points at which they are not considered touching. Default: 0.01, suitable for objects in meters.

classmethod from_all_story_geometry(identifier, all_story_geometry, floor_to_floor_heights, perimeter_offset=0, tolerance=0.01)

Initialize a Building from an array of Face3Ds arrays representing all floors.

This method will test to see which of the stories are geometrically unique (accoutring for both the floor plate geometry and the floor_to_floor_heights). It will only include the unique floor geometries in the resulting Building.

All of the resulting Room2Ds will have a floor-to-ceiling height equal to the Story floor-to-floor height.

Parameters:

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

• all_story_geometry – An array of arrays with each sub-array possessing horizontal ladybug-geometry Face3Ds that representing the floor plates of the building. Together, these Face3Ds should represent all Stories of a building and each array of Face3Ds should together represent one Story.

• floor_to_floor_heights – An array of float values with a length equal to the number of stories in the Building. Each value in the list represents the floor_to_floor height of the Story starting from the first floor and then moving to the top floor. Note that numbers should be in the units system of the footprint geometry.

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

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

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

Initialize an Building from a dictionary.

Parameters:

• data – A dictionary representation of a Building 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.

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

• sort_stories – A boolean to note whether the unique_stories should be sorted from lowest to highest story upon initialization (True) or whether the input order of unique_stories should be left as-is. (Default: True).

classmethod from_footprint(identifier, footprint, floor_to_floor_heights, perimeter_offset=0, tolerance=0)

Initialize a Building from an array of Face3Ds representing a footprint.

All of the resulting Room2Ds will have a floor-to-ceiling height equal to the Story floor-to-floor height. Also, none of the Room2Ds will have contact with the ground or top exposure but the separate_top_bottom_floors method can be used to automatically break these floors out from the multiplier representation and assign these properties.

Parameters:

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

• footprint – An array of horizontal ladybug-geometry Face3Ds that together represent the the footprint of the Building.

• floor_to_floor_heights – An array of float values with a length equal to the number of stories in the Building. Each value in the list represents the floor_to_floor height of the Story starting from the first floor and then moving to the top floor. Note that numbers should be in the units system of the footprint geometry.

• perimeter_offset – An optional positive number that will be used to offset the perimeter of the footprint 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).

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

classmethod from_honeybee(model, conversion_method='AllRoom2D')

Initialize a Building from a Honeybee Model.

If each Room has a story, these will be used to determine the separation into Dragonfly stories. Otherwise, stories will be auto-generated based on the floor heights of rooms.

Parameters:

• model – A Honeybee Model to be converted to a Dragonfly Building.

• conversion_method –

  Text to indicate how the Honeybee Rooms should be converted to Dragonfly. Note that the AllRoom2D option may result in some loss or simplification of the 3D Honeybee geometry but ensures that all of Dragonfly’s features for editing the rooms can be used. The ExtrudedOnly method will convert only the 3D Rooms that would have no loss or simplification of geometry when converted to Room2D. AllRoom3D keeps all detailed 3D geometry on the Building.room_3ds property, enabling you to convert the 3D Rooms to Room2D using the Building.convert_room_3ds_to_2d() method as you see fit. (Default: AllRoom2D). Choose from the following options.

  • AllRoom2D - All Honeybee Rooms converted to Dragonfly Room2D

  • ExtrudedOnly - Only pure extrusions converted to Dragonfly Room2D

  • AllRoom3D - All Honeybee Rooms left as-is on Building.room_3ds

has_floors_ceilings(use_multiplier=True)

Get a list of tuples for each Room noting whether it has a floor/ceiling.

Parameters:

use_multiplier – Boolean to note whether the returned list should be assume that the Rooms use multipliers or not. The list will typically be longer when use_multiplier is False. (Default: True).

move(moving_vec)

Move this Building along a vector.

Parameters:

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

static process_alleys(buildings, distance=1.0, adiabatic=False, tolerance=0.01)

Remove windows from any walls that within a distance of other buildings.

This method can also optionally set the boundary conditions of these walls to adiabatic. This is helpful when attempting to account for alleys or parti walls that may exist between buildings of a denser urban district.

Note that this staticmethod will edit the buildings in place so it may be appropriate to duplicate the Buildings before running this method.

Parameters:

• buildings – Dragonfly Building objects which will have their windows removed if their walls lie within the distance of another building.

• distance – A number for the maximum distance of an alleyway in model units. If a wall is closer to another Building than this distance, the windows will be removed. (Default: 1.0; suitable for objects in meters).

• adiabatic – A boolean to note whether the walls that have their windows removed should also receive an Adiabatic boundary condition. This is useful when the alleyways are more like parti walls than distinct pathways that someone could traverse.

reflect(plane)

Reflect this Building across a plane.

Parameters:

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

remove_duplicate_roofs(tolerance=0.01)

Remove any roof geometries in the Building that appear more than once.

This includes duplicated roof geometries assigned to different stories.

Parameters:

tolerance – The maximum difference between values at which point vertices are considered to be the same. (Default: 0.01, suitable for objects in Meters).

room_2ds_by_display_name(room_name)

Get all of the Room2Ds with a given display_name in the Building.

room_3ds_by_display_name(room_name)

Get all of the 3D Rooms with a given display_name in the Building.

room_3ds_by_story(story_name)

Get all of the 3D Honeybee Room objects assigned to a particular story.

Parameters:

story_name – Text for the display_name of the Story for which Honeybee Room objects will be returned.

rotate_xy(angle, origin)

Rotate this Building 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 Building 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).

separate_mid_floors(tolerance=0.01)

Separate all Stories with non-unity multipliers into two or three Stories.

This method automatically assigns the first story Room2Ds to have a ground contact floor and will separate the top story of each unique story to have outdoor-exposed roofs when no Room2Ds are sensed above a given room.

This is particularly helpful when using to_honeybee workflows with multipliers but one wants to account for the heat exchange of the top or bottom floors with the ground or outdoors.

Parameters:

tolerance – The tolerance that will be used to compute the point within the floor boundary that is used to check whether there is geometry above each Room2D. It is recommended that this number not be less than 1 centimeter to avoid long computation times. Default: 0.01, suitable for objects in meters.

separate_top_bottom_floors()

Separate top/bottom Stories with non-unity multipliers into their own Stories.

The resulting first and last Stories will each have a multiplier of 1 and duplicated middle Stories will be added as needed. This method also automatically assigns the first story Room2Ds to have a ground contact floor and the top story Room2Ds to have an outdoor-exposed roof.

This is particularly helpful when using to_honeybee workflows with multipliers but one wants to account for the heat exchange of the top or bottom floors with the ground or outdoors.

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.

shade_representation(exclude_index=None, cap=False, include_room3ds=False, tolerance=0.01)

A list of honeybee Shade objects representing the building geometry.

These can be used to account for this Building’s shade in the simulation of another nearby Building.

Parameters:

• exclude_index – An optional index for a unique_story to be excluded from the shade representation. If None, all stories will be included in the result. (Default: None).

• cap – Boolean to note whether the shade representation should be capped with a top face. Usually, this is not necessary to account for blocked sun and is only needed when it’s important to account for reflected sun off of roofs. (Default: False).

• include_room3ds – Boolean to note whether the 3D Rooms assigned to this Building should be included in the shade representation. Only exterior geometries are included. (Default: False).

• tolerance – The minimum distance between points at which they are not considered touching. Default: 0.01, suitable for objects in meters.

sort_stories()

Sort the stories assigned to this Building by their floor heights

split_room_2d_vertically(room_id, tolerance=0.01)

Split a Room2D in this Building vertically if it crosses multiple stories.

Parameters:

• room_id – The identifier of a Room2D within this Building which will be split vertically with the Stories above it.

• tolerance – The tolerance to be used for determining whether the Room2D should be split. Default: 0.01, suitable for objects in meters.

Returns:

A list of all the new rooms created by running the method. This can be used to post-process the rooms for attributes like adjacency within the Story they are placed.

static stories_to_honeybee(buildings, context_shades=None, shade_distance=None, use_multiplier=True, add_plenum=False, cap=False, tolerance=0.01, enforce_adj=True, enforce_solid=True)

Convert an array of Buildings into one honeybee Model per story.

Each Story of each input Building will be exported into its own Model. For each Honeybee Model, the other input Buildings will appear as context shade geometry as will all of the other stories of the same building. Thus, each Model is its own simulate-able unit accounting for the total self-shading of the input Buildings.

Parameters:

• buildings – An array of Building objects to be converted into an array of honeybee Models with one story per model.

• context_shades – An optional array of ContextShade objects that will be added to the honeybee Models if their bounding box overlaps with a given building within the shade_distance.

• shade_distance – An optional number to note the distance beyond which other objects’ shade should not be exported into a given Model. This is helpful for reducing the simulation run time of each Model when other connected buildings are too far away to have a meaningful impact on the results. If None, all other buildings will be included as context shade in each and every Model. Set to 0 to exclude all neighboring buildings from the resulting models. Default: None.

• use_multiplier – If True, the multipliers on this Building’s Stories will be passed along to the generated Honeybee Room objects, indicating the simulation will be run once for each unique room and then results will be multiplied. If False, full geometry objects will be written for each and every floor in the building that are represented through multipliers and all room multipliers will be 1. (Default: True).

• add_plenum – Boolean to indicate whether ceiling/floor plenums should be auto-generated for the Rooms. (Default: False).

• cap – Boolean to note whether building shade representations should be capped with a top face. Usually, this is not necessary to account for blocked sun and is only needed when it’s important to account for reflected sun off of roofs. (Default: False).

• tolerance – The minimum distance in z values of floor_height and floor_to_ceiling_height at which adjacent Faces will be split. Default: 0.01, suitable for objects in meters.

• enforce_adj – Boolean to note whether an exception should be raised if an adjacency between two Room2Ds is invalid (True) or if the invalid Surface boundary condition should be replaced with an Outdoor boundary condition (False). If False, any Walls containing WindowParameters and an illegal boundary condition will also be replaced with an Outdoor boundary condition. (Default: True).

• enforce_solid – Boolean to note whether rooms should be translated as solid extrusions whenever translating them 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 list of honeybee Models that represent the Stories.

suggested_alignment_axes(distance, direction=Vector2D(0.00, 1.00), angle_tolerance=1.0)

Get suggested LineSegment2Ds to be used for this Building.

This method will return the most common axes across the Building’s 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 Building.

Parameters:

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

to_dict(abridged=False, included_prop=None)

Return Building 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.

to_honeybee(use_multiplier=True, add_plenum=False, tolerance=0.01, enforce_adj=True, enforce_solid=True)

Convert Dragonfly Building to a Honeybee Model.

Parameters:

• use_multiplier – If True, the multipliers on this Building’s Stories will be passed along to the generated Honeybee Room objects, indicating the simulation will be run once for each unique room and then results will be multiplied. If False, full geometry objects will be written for each and every floor in the building that are represented through multipliers and all resulting multipliers will be 1. (Default: True).

• add_plenum – Boolean to indicate whether ceiling/floor plenums should be auto-generated for the Rooms. (Default: False).

• tolerance – The minimum distance in z values of floor_height and floor_to_ceiling_height at which adjacent Faces will be split. Default: 0.01, suitable for objects in meters.

• enforce_adj – Boolean to note whether an exception should be raised if an adjacency between two Room2Ds is invalid (True) or if the invalid Surface boundary condition should be replaced with an Outdoor boundary condition (False). If False, any Walls containing WindowParameters and an illegal boundary condition will also be replaced with an Outdoor boundary condition. (Default: True).

• enforce_solid – Boolean to note whether rooms should be translated as solid extrusions whenever translating them 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 honeybee Model that represent the Building.

to_rectangular_windows()

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

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 number for the total exterior wall aperture area in the Building.

This property uses both the 2D Story multipliers and the 3D Room multipliers to determine the total exterior wall aperture area. All skylights apertures are excluded.

property exterior_wall_area

Get a number for the total exterior wall area in the Building.

This property uses both the 2D Story multipliers and the 3D Room multipliers to determine the total exterior wall area.

property floor_area

Get a number for the total floor area in the Building.

This property uses both the 2D Story multipliers and the 3D Room multipliers to determine the total floor area.

property footprint_area

Get a number for the total footprint area of the Building.

The footprint is derived from the lowest dragonfly Story of the building unless the Building is composed entirely of 3D Rooms, in which case it is the combined floor area of the Rooms belonging to the lowest story.

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_room_2ds

Get a boolean noting whether this Building has Room2Ds assigned under stories.

property has_room_3ds

Get a boolean noting whether this Building has 3D Honeybee Rooms.

property height

Get a number for the roof height of the Building as an absolute Z-coordinate.

This property will account for the fact that the tallest Room may be a 3D Honeybee Room.

property height_above_ground

Get a the height difference between the roof and first floor above the ground.

This property will account for any 3D Room if they exist.

property height_from_first_floor

Get a the height difference between the roof and the bottom-most floor.

This property will account for any 3D Room if they exist.

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 max

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

This is useful in calculations to determine if this Building is in proximity to other objects.

property min

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

This is useful in calculations to determine if this Building is in proximity to other objects.

property properties

Object properties, including Radiance, Energy and other properties.

property room_2d_story_names

Get a tuple of all Story display_names that have Room2Ds on them.

property room_3d_apertures

Get a list of all Aperture objects for the 3D Honeybee Rooms in the Building.

property room_3d_doors

Get a list of all Door objects for the 3D Honeybee Rooms in the Building.

property room_3d_faces

Get a list of all Face objects for the 3D Honeybee Rooms in the Building.

property room_3d_shades

Get a list of all Shade objects for the 3D Honeybee Rooms in the Building.

property room_3d_story_names

Get a tuple of all story display_names that have 3D Honeybee Rooms on them.

property room_3ds

Get a tuple of additional 3D Honeybee Rooms assigned to the Building.

These rooms are a part of the Building but are not represented within the unique_stories or unique_room_2ds. Matching the Honeybee Room.story property to the Dragonfly Story.display_name of an object within the unique_stories will effectively place the Honeybee Room on that Story for the purposes of floor_area, exterior_wall_area, etc. However, note that the Honeybee Room.multiplier property takes precedence over whatever multiplier is assigned to the Dragonfly Story that the Room.story may reference.

property story_count

Get an integer for the number of stories in the building.

This includes both the Room2Ds within unique_stories (including the Story.multiplier) as well as all stories defined by the room_3ds.

property story_count_above_ground

Get an integer for the number of stories above the ground.

All stories defined by 3D Rooms are assumed to be above ground.

property to

Building writer object.

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

property unique_room_2ds

Get a list of the unique Room2D objects that form the Building.

property unique_stories

Get a tuple of only unique Story objects that form the Building.

Repeated stories are represented only once but will have a non-unity multiplier.

property unique_stories_above_ground

Get a tuple of unique Story objects that are above the ground.

A story is considered above the ground if at least one of its Room2Ds has an outdoor boundary condition.

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 all the Rooms in the Building.

This property uses both the 2D Story multipliers and the 3D Room multipliers to determine the total Building volume.