dragonfly.model module

Dragonfly Model.

class dragonfly.model.Model(identifier, buildings=None, context_shades=None, units='Meters', tolerance=None, angle_tolerance=1.0, reference_vector=None)[source]

Bases: _BaseGeometry

A collection of Buildings and ContextShades for an entire model.

Parameters:

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

  • buildings – A list of Building objects in the model.

  • context_shades – A list of ContextShade objects in the model.

  • units –

    Text for the units system in which the model geometry exists. Default: ‘Meters’. Choose from the following:

    • Meters

    • Millimeters

    • Feet

    • Inches

    • Centimeters

  • tolerance – The maximum difference between x, y, and z values at which vertices are considered equivalent. Zero indicates that no tolerance checks should be performed and certain capabilities like to_honeybee will not be available. None indicates that the tolerance will be set based on the units above, with the tolerance consistently being between 1 cm and 1 mm (roughly the tolerance implicit in the OpenStudio SDK). (Default: None).

  • angle_tolerance – The max angle difference in degrees that vertices are allowed to differ from one another in order to consider them colinear. Zero indicates that no angle tolerance checks should be performed. (Default: 1.0).

  • reference_vector – An optional Vector3D to relate the model back to an original source coordinate system. This is useful if the model has been moved from its original location and there may be future operations of merging geometry from the original source model. (Default: None).

Properties:

  • identifier

  • display_name

  • full_id

  • units

  • tolerance

  • angle_tolerance

  • reference_vector

  • buildings

  • context_shades

  • stories

  • room_2ds

  • room_3ds

  • average_story_count

  • average_story_count_above_ground

  • average_height

  • average_height_above_ground

  • footprint_area

  • floor_area

  • exterior_wall_area

  • exterior_aperture_area

  • volume

  • min

  • max

  • user_data

ToString()

Overwrite .NET ToString.

add_building(obj)[source]

Add a Building object to the model.

In the case that the Building or Story identifiers of the input obj match one the current model, these objects will be merged together. Room2Ds that are identical within a merged Story will not be merged in order to avoid ID conflicts.

add_context_shade(obj)[source]

Add a ContextShade object to the model.

add_model(other_model)[source]

Add another Dragonfly Model object to this one.

In the case that Building or Story identifiers in the other_model match one the current model, these objects will be merged together. Room2Ds that have matching identifiers within a merged Story will not be added in order to avoid ID conflicts. Context Shades will also not be added if their identifier matches one that is already in the Model.

Note that the other model’s unit system does not have to match this one since the other_model will automatically be converted to this model’s units before merging. Also, if this model has a reference_vector assigned, it will be used to translate the other_model before it is merged into this one.

add_prefix(prefix)[source]

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

This is particularly useful in workflows where you duplicate and edit a starting object and then want to combine it with the original object since all objects within a Model must have unique identifiers to be valid.

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

buildings_by_identifier(identifiers)[source]

Get a list of Building objects in the model given Building identifiers.

check_all(raise_exception=True, detailed=False)[source]

Check all of the aspects of the Model for possible errors.

Parameters:

  • raise_exception – Boolean to note whether a ValueError should be raised if any Model errors are found. If False, this method will simply return a text string with all errors that were found. (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 text string with all errors that were found. This string will be empty of no errors were found.

check_all_duplicate_identifiers(raise_exception=True, detailed=False)[source]

Check that there are no duplicate identifiers for any geometry objects.

This includes Buildings, Stories, Room2Ds, and ContextShades.

Parameters:

  • raise_exception – Boolean to note whether a ValueError should be raised if any duplicate IDs are found. If False, this method will simply return a text string with all errors that were found. (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 text string with all errors that were found or a list if detailed is True. This string (or list) will be empty if no errors were found.

check_all_room3d(tolerance=None, angle_tolerance=None, raise_exception=True, detailed=False)[source]

Check all attributes of 3D Honeybee Rooms assigned to the Model’s Buildings.

This includes checking for duplicate Room/Face/Aperture/Door/Shade identifiers, checking planarity/self-intersection/degeneracy, checking that all rooms are, solid, and checking the adjacencies (among other attributes).

Parameters:

  • tolerance – tolerance: The maximum difference between x, y, and z values at which face vertices are considered equivalent. If None, the Model tolerance will be used. (Default: None).

  • angle_tolerance – The max angle difference in degrees that vertices are allowed to differ from one another in order to consider them colinear. If None, the Model angle_tolerance will be used. (Default: None).

  • raise_exception – Boolean to note whether a ValueError should be raised if an error is found. (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_all_room_collisions(raise_exception=True, detailed=False)[source]

Check all types of Room2D collisions and major geometry errors.

This includes checking for degenerate and self-interesting Room2Ds as well as checking for Room2D overlaps within Stories and collisions between Stories.

Parameters:

  • raise_exception – Boolean to note whether a ValueError should be raised if any duplicate IDs are found. If False, this method will simply return a text string with all errors that were found. (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 text string with all errors that were found or a list if detailed is True. This string (or list) will be empty if no errors were found.

check_collisions_between_stories(tolerance=None, raise_exception=True, detailed=False)[source]

Check that Room2Ds of each Story do not collide with others in each Building.

Parameters:

  • tolerance – The minimum distance that two Room2Ds geometries can collide with one another and still be considered valid. If None, the Model tolerance will be used. (Default: None).

  • raise_exception – Boolean to note whether a ValueError should be raised if colliding geometries are found. (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_degenerate_room_2ds(tolerance=None, raise_exception=True, detailed=False)[source]

Check that all Room2Ds are not degenerate with zero area.

Parameters:

  • tolerance – The minimum difference between the coordinate values of two vertices at which they can be considered equivalent. If None, the Model tolerance will be used. (Default: None).

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

check_duplicate_building_identifiers(raise_exception=True, detailed=False)[source]

Check that there are no duplicate Building identifiers in the model.

Parameters:

  • raise_exception – Boolean to note whether a ValueError should be raised if duplicate identifiers are found. (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_duplicate_context_shade_identifiers(raise_exception=True, detailed=False)[source]

Check that there are no duplicate ContextShade identifiers in the model.

Parameters:

  • raise_exception – Boolean to note whether a ValueError should be raised if duplicate identifiers are found. (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_duplicate_room_2d_identifiers(raise_exception=True, detailed=False)[source]

Check that there are no duplicate Room2D identifiers in the model.

Parameters:

  • raise_exception – Boolean to note whether a ValueError should be raised if duplicate identifiers are found. (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_duplicate_story_identifiers(raise_exception=True, detailed=False)[source]

Check that there are no duplicate Story identifiers in the model.

Parameters:

  • raise_exception – Boolean to note whether a ValueError should be raised if duplicate identifiers are found. (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_for_extension(extension_name='All', raise_exception=True, detailed=False)[source]

Check that the Model is valid for a specific Dragonfly extension.

This process will typically include both dragonfly-core checks as well as checks that apply only to the extension. However, any checks that are not relevant for the specified extension will be ignored.

Note that the specified Dragonfly extension must be installed in order for this method to run successfully.

Parameters:

  • extension_name –

    Text for the name of the extension to be checked. The value input here is case-insensitive such that “radiance” and “Radiance” will both result in the model being checked for validity with dragonfly-radiance. This value can also be set to “All” in order to run checks for all installed extensions. Some common dragonfly extension names that can be input here if they are installed include:

    • Radiance

    • EnergyPlus

    • OpenStudio

    • DesignBuilder

    • DOE2

    • IESVE

    • IDAICE

    Note that EnergyPlus, OpenStudio, and DesignBuilder are all set to run the same checks with dragonfly-energy.

  • raise_exception – Boolean to note whether a ValueError should be raised if any errors are found. If False, this method will simply return a text string with all errors that were found. (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 text string with all errors that were found or a list if detailed is True. This string (or list) will be empty if no errors were found.

check_missing_adjacencies(raise_exception=True, detailed=False)[source]

Check that all Room2Ds have adjacent objects that exist within each Story.

Parameters:

  • raise_exception – Boolean to note whether a ValueError should be raised if missing or invalid adjacencies are found. (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_no_roof_overlaps(tolerance=None, raise_exception=True, detailed=False)[source]

Check that geometries of RoofSpecifications do not overlap with one another.

This is NOT a requirement for the Model to be valid but it is sometimes useful to check when trying to make the simplest and cleanest representation of the roofs.

Parameters:

  • tolerance – The minimum distance that two Roof geometries can overlap with one another and still be considered valid. If None, the Model tolerance will be used. (Default: None).

  • raise_exception – Boolean to note whether a ValueError should be raised if overlapping geometries are found. (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_no_room2d_overlaps(tolerance=None, raise_exception=True, detailed=False)[source]

Check that geometries of Room2Ds do not overlap with one another.

Overlaps in Room2Ds mean that the Room volumes will collide with one another during translation to Honeybee.

Parameters:

  • tolerance – The minimum distance that two Room2Ds geometries can overlap with one another and still be considered valid. If None, the Model tolerance will be used. (Default: None).

  • raise_exception – Boolean to note whether a ValueError should be raised if overlapping geometries are found. (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_plenum_depths(tolerance=0.01, raise_exception=True, detailed=False)[source]

Check that all Room2Ds have valid plenum depths.

Valid plenum depths do not exceed the Room2D.floor_to_ceiling_height and do not contradict the Room2D.has_floor or has_ceiling properties.

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 will be raised if invalid plenum depths are discovered. (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_roofs_above_rooms(tolerance=None, raise_exception=True, detailed=False)[source]

Check that all roof geometries lie above the Room2Ds of the model.

Roofs that lie below or intersect the Room2D floor plates (or the plenum floors) will cause an invalid calculation of the Room volume when translated to Honeybee. Roofs touching the edges of floor plates within the tolerance are permitted and can be translated to closed Honeybee Room volumes.

Parameters:

  • tolerance – The minimum distance that two Roof geometries can overlap with one another and still be considered valid. If None, the Model tolerance will be used. (Default: None).

  • raise_exception – Boolean to note whether a ValueError should be raised if overlapping geometries are found. (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_room2d_floor_heights_valid(raise_exception=True, detailed=False)[source]

Check that all Room2Ds have floor elevations in range to be on the same Story.

Parameters:

  • raise_exception – Boolean to note whether a ValueError should be raised if rooms with inappropriate floor elevations are found. (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_self_intersecting_room_2ds(tolerance=None, raise_exception=True, detailed=False)[source]

Check that all Room2Ds do not intersect with themselves (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. If None, the Model tolerance will be used. (Default: None).

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

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

Check that all Room2Ds have window parameters produce valid apertures.

This means that the resulting Apertures are completely bounded by their parent wall Face and attributes like window to wall ratio are accurate.

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.

context_shade_by_identifier(identifiers)[source]

Get a list of ContextShade objects in the model given identifiers.

convert_to_units(units='Meters')[source]

Convert all of the geometry in this model to certain units.

This involves scaling the geometry, scaling the Model tolerance, and changing the Model’s units property.

Parameters:

units –

Text for the units to which the Model geometry should be converted. Default: Meters. Choose from the following:

  • Meters

  • Millimeters

  • Feet

  • Inches

  • Centimeters

duplicate()

Get a copy of this object.

classmethod from_dfjson(dfjson_file)[source]

Initialize a Model from a DFJSON file.

Parameters:

dfjson_file – Path to DFJSON file. This can also be a HBJSON from which a Dragonfly model should be derived.

classmethod from_dfpkl(dfpkl_file)[source]

Initialize a Model from a DFpkl file.

Parameters:

dfpkl_file – Path to DFpkl file. This can also be a HBpkl from which a Dragonfly model should be derived.

classmethod from_dict(data)[source]

Initialize a Model from a dictionary.

Parameters:

data – A dictionary representation of a Model object.

classmethod from_file(df_file)[source]

Initialize a Model from a DFJSON or DFpkl file, auto-sensing the type.

This will also sense if the input is a Honeybee Model and, if so, the loaded Dragonfly model will be derived from the Honeybee one.

Parameters:

df_file – Path to either a DFJSON or DFpkl file. This can also be a HBJSON or a HBpkl from which a Dragonfly model should be derived.

classmethod from_geojson(geojson_file_path, location=None, point=Point2D(0.00, 0.00), all_polygons_to_buildings=False, existing_to_context=False, units='Meters', tolerance=None, angle_tolerance=1.0)[source]

Make a Model from a geojson file.

Parameters:

  • geojson_file_path – Text for the full path to the geojson file to load as Model.

  • location – An optional ladybug location object with longitude and latitude data defining the origin of the geojson file. If nothing is passed, the origin is autocalculated as the bottom-left corner of the bounding box of all building footprints in the geojson file (Default: None).

  • point – A ladybug_geometry Point2D for where the location object exists within the space of a scene. The coordinates of this point are expected to be in the expected units of this Model (Default: (0, 0)).

  • all_polygons_to_buildings – Boolean to indicate if all geometries in the geojson file should be considered buildings. If False, this method will only generate footprints from geometries that are defined as a “Building” in the type field of its corresponding properties. (Default: False).

  • existing_to_context – Boolean to indicate whether polygons possessing a building_status of “Existing” under their properties should be imported as ContextShade instead of Building objects. (Default: False).

  • units –

    Text for the units system in which the model geometry exists. Default: ‘Meters’. Choose from the following:

    • Meters

    • Millimeters

    • Feet

    • Inches

    • Centimeters

    Note that this method assumes the point coordinates are in the same units.

  • tolerance – The maximum difference between x, y, and z values at which vertices are considered equivalent. Zero indicates that no tolerance checks should be performed and certain capabilities like to_honeybee will not be available. None indicates that the tolerance will be set based on the units above, with the tolerance consistently being between 1 cm and 1 mm (roughly the tolerance implicit in the OpenStudio SDK). (Default: None).

  • angle_tolerance – The max angle difference in degrees that vertices are allowed to differ from one another in order to consider them colinear. Zero indicates that no angle tolerance checks should be performed. (Default: 1.0).

Returns:

A tuple with the two items below.

  • model – A dragonfly Model derived from the geoJSON.

  • location – A ladybug Location object, which contains latitude and

    longitude information and can be used to re-serialize the model back to geoJSON.

classmethod from_honeybee(model, conversion_method='AllRoom2D')[source]

Initialize a Dragonfly Model from a Honeybee Model.

Parameters:

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

  • 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

classmethod from_pomf(pomf_file)[source]

Initialize a Model from a Pollination Model File (POMF).

Parameters:

pomf_file – Path to POMF file containing a dragonfly Model.

static lines_from_pomf(pomf_file)[source]

Extract all line geometry objects from a POMF file.

This includes LineSegment2Ds, Polyline2Ds and Polygon2Ds.

Parameters:

pomf_file – Path to POMF file containing line geometry.

static model_dict_room_2d_subset(model_dict, room_2d_ids)[source]

Get a dragonfly Model dictionary that has been filtered for a Room2D subset.

This is useful when you are only interested in visualizing or exporting a subset of Room2Ds to a file and so it is not desirable to serialize the entire Dragonfly Model.

Parameters:

  • model_dict – A dictionary of a Dragonfly Model.

  • room_2d_ids – An optional list of the identifiers for the Room2Ds to be included in the output dictionary.

Returns:

A copy of the input Dragonfly Model dictionary, which contains only the Room2Ds listed in the room_2d_ids. All ContextShade and 3D Honeybee Rooms are removed but slanted Roof geometries are included if they are relevant to the Room2Ds.

static model_dict_subset(model_dict, room_2d_ids=None, room_3d_ids=None, shade_ids=None)[source]

Get a dragonfly Model dictionary that has been filtered for certain objects.

This is useful when you are only interested in visualizing or exporting a subset of objects to a file and so it is not desirable to serialize the entire Dragonfly Model.

Parameters:

  • model_dict – A dictionary of a Dragonfly Model.

  • room_2d_ids – An optional list of the identifiers for the Room2Ds to be included in the output dictionary. If None, no Room2D dictionaries will be in the result. (Default: None).

  • room_3d_ids – An optional list of the identifiers for the 3D Rooms to be included in the output dictionary. If None, no 3D Room dictionaries will be in the result. (Default: None).

  • shade_ids – An optional list of the identifiers for the ContextShades to be included in the output dictionary. If None, no ContextShade dictionaries will be in the result. (Default: None).

Returns:

A copy of the input Dragonfly Model dictionary, which contains only the Room2Ds listed in the room_2d_ids, the 3D Rooms listed in the room_3d_ids, and ContextShades in the shade_ids. Slanted Roof geometries are included if they are relevant to the Room2Ds.

move(moving_vec)[source]

Move this Model along a vector.

Parameters:

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

reflect(plane)[source]

Reflect this Model across a plane with the input normal vector and origin.

Parameters:

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

remove_duplicate_roofs()[source]

Remove any roof geometries that appear more than once in each building.

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

reset_coordinate_system(new_origin=None)[source]

Set the origin of the coordinate system in which the model exists.

This is useful for resolving cases where the model geometry lies so far from the origin in its current coordinate system that it creates problems. For example, the model geometry might be so high above the origin that EnergyPlus models it in the conditions of the stratosphere. Another possibility is that the float values of the coordinates are so high that floating point tolerance interferes with the proper representation of the model’s details.

In addition to moving the model such that the new_origin sets the coordinate values of the geometry, this method will also set the reference_vector of this object such that any models added into this one from the original source coordinate system respect the new system.

Parameters:

new_origin – A Point3D in the model’s current coordinate system that will become the origin of the new coordinate system. If unspecified, the minimum of the bounding box around the model geometry will be used and the average_height_above_ground will be used to set the Z coordinate. (Default: None).

reset_ids(repair_surface_bcs=True)[source]

Reset the identifiers of all Model objects to be derived from display_names.

In the event that duplicate identifiers are found, an integer will be automatically appended to the new ID to make it unique. This is similar to the routines that automatically assign unique names to OpenStudio SDK objects.

Parameters:

repair_surface_bcs – A Boolean to note whether all Surface boundary conditions across the model should be updated with the new identifiers that were generated from the display names. (Default: True).

resolve_id_collisions()[source]

Resolve collisions of duplicate identifiers that exist in the Model.

In the case that Building or Story identifiers are duplicated, these objects will be merged together. In the case that Room2Ds that have matching identifiers, an integer will be automatically appended to the Room2D ID to make it unique. Context Shades and 3D Rooms that collide will similarly have their IDs tweaked with an integer if they are duplicated.

room_2ds_by_identifier(identifiers)[source]

Get a list of Room2D objects in the model given Room2D identifiers.

room_3ds_by_identifier(identifiers)[source]

Get a list of 3D Honeybee Room objects in the model given Room identifiers.

rotate_xy(angle, origin)[source]

Rotate this Model 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.

scale(factor, origin=None)[source]

Scale this Model 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_top_bottom_floors(separate_mid=False)[source]

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.

separate_mid: Boolean to note whether all mid-level Stories with non-unity

multipliers should be separated into two or three Stories. This means that the top of each unique story will have outdoor-exposed roofs when no Room2Ds are sensed above a given room. (Default: False).

set_outdoor_shading_parameters(shading_parameter)[source]

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

set_outdoor_window_parameters(window_parameter)[source]

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

stories_by_identifier(identifiers)[source]

Get a list of Story objects in the model given Story identifiers.

to_dfjson(name=None, folder=None, indent=None, included_prop=None)[source]

Write Dragonfly model to DFJSON.

Parameters:

  • name – A text string for the name of the DFJSON file. If None, the model identifier wil be used. (Default: None).

  • folder – A text string for the directory where the DFJSON will be written. If unspecified, the default simulation folder will be used. This is usually at “C:UsersUSERNAMEsimulation” on Windows.

  • indent – A positive integer to set the indentation used in the resulting DFJSON file. (Default: None).

  • 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_dfpkl(name=None, folder=None, included_prop=None)[source]

Writes Dragonfly model to compressed pickle file (DFpkl).

Parameters:

  • name – A text string for the name of the pickle file. If None, the model identifier wil be used. (Default: None).

  • folder – A text string for the directory where the pickle will be written. If unspecified, the default simulation folder will be used. This is usually at “C:UsersUSERNAMEsimulation.”

  • 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_dict(included_prop=None)[source]

Return Model as a dictionary.

Parameters:

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_geojson(location, point=Point2D(0.00, 0.00), folder=None, tolerance=None)[source]

Convert Dragonfly Model to a geoJSON of buildings footprints.

This geoJSON will be in a format that is compatible with the URBANopt SDK, including properties for floor_area, footprint_area, and detailed_model_filename, which will align with the paths to OpenStudio model (.osm) files output from honeybee Models translated to OSM.

Parameters:

  • location – A ladybug Location object possessing longitude and latitude data.

  • point – A ladybug_geometry Point2D for where the location object exists within the space of a scene. The coordinates of this point are expected to be in the units of this Model. (Default: (0, 0)).

  • folder – Text for the full path to where the geojson file will be written. If None, a sub-folder within the honeybee default simulation folder will be used. (Default: None).

  • tolerance – The minimum distance between points at which they are not considered touching. If None, the Model’s own tolerance will be used. (Default: None).

Returns:

The path to a geoJSON file that contains polygons for all of the Buildings within the dragonfly model along with their properties (floor area, number of stories, etc.). The polygons will also possess detailed_model_filename keys that align with where OpenStudio models would be written, assuming the input folder matches that used to export OpenStudio models.

to_geojson_dict(location, point=Point2D(0.00, 0.00), tolerance=None)[source]

Convert Dragonfly Model to a geoJSON-style Python dictionary.

This dictionary can be written into a JSON, which is then a valid geoJSON that can be visualized in any geoJSON viewer. Each dragonfly Building will appear in the geoJSON as a single feature (either as a Polygon or a MultiPolygon).

Parameters:

  • location – A ladybug Location object possessing longitude and latitude data.

  • point – A ladybug_geometry Point2D for where the location object exists within the space of a scene. The coordinates of this point are expected to be in the units of this Model. (Default: (0, 0)).

  • tolerance – The minimum distance between points at which they are not considered touching. If None, the Model’s own tolerance will be used. (Default: None).

Returns:

A Python dictionary in a geoJSON style with each Building in the Model as a separate feature.

to_honeybee(object_per_model='Building', shade_distance=None, use_multiplier=True, exclude_plenums=False, cap=False, solve_ceiling_adjacencies=False, tolerance=None, enforce_adj=True, enforce_solid=True)[source]

Convert Dragonfly Model to an array of Honeybee Models.

Parameters:

  • object_per_model –

    Text to describe how the input Buildings should be divided across the output Models. (Default: ‘Building’). Choose from the following options:

    • District - All buildings will be added to a single Honeybee Model. Such a Model can take a long time to simulate so this is only recommended for small numbers of buildings or cases where exchange of data between Buildings is necessary.

    • Building - Each building will be exported into its own Model. For each Model, the other buildings input to this component will appear as context shade geometry.

    • Story - Each Story of each 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.

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

  • exclude_plenums – Boolean to indicate whether ceiling/floor plenum depths assigned to Room2Ds should be ignored during translation. This results in each Room2D translating to a single Honeybee Room at the full floor_to_ceiling_height instead of a base Room with (a) plenum Room(s). (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).

  • solve_ceiling_adjacencies – Boolean to note whether adjacencies should be solved between interior stories when Room2D floor and ceiling geometries are coplanar. This ensures that Surface boundary conditions are used instead of Adiabatic ones. Note that this input has no effect when the object_per_model is Story. (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. This must be a positive, non-zero number. If None, the Model’s own tolerance will be used. (Default: None).

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

An array of Honeybee Models that together represent this Dragonfly Model.

to_rectangular_windows()[source]

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

static validate(model, check_function='check_for_extension', check_args=None, json_output=False)[source]

Get a string of a validation report given a specific check_function.

Parameters:

  • model – A Dragonfly Model object for which validation will be performed. This can also be the file path to a DFJSON or a JSON string representation of a Dragonfly Model. These latter two options may be useful if the type of validation issue with the Model is one that prevents serialization.

  • check_function – Text for the name of a check function on this Model that will be used to generate the validation report. For example, check_all or check_rooms_solid. (Default: check_for_extension),

  • check_args – An optional list of arguments to be passed to the check_function. If None, all default values for the arguments will be used. (Default: None).

  • json_output – Boolean to note whether the output validation report should be formatted as a JSON object instead of plain text.

property angle_tolerance

Get or set a number for the max meaningful angle difference in degrees.

Face3D normal vectors differing by this amount are not considered parallel and Face3D segments that differ from 180 by this amount are not considered colinear. Zero indicates cases where no angle_tolerance checks should be performed.

property average_height

Get the average height of the Buildings as an absolute Z-coordinate.

property average_height_above_ground

Get the average building height relative to the first floor above ground.

property average_story_count

Get the average number of stories for the buildings in the model.

Note that this will be a float and not an integer in most cases.

property average_story_count_above_ground

Get the average number of above-ground stories for the buildings in the model.

Note that this will be a float and not an integer in most cases.

property buildings

Get or set a tuple of all Building objects in the model.

property context_shades

Get or set a tuple of all ContextShade objects in the model.

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 aperture area for all Buildings.

property exterior_wall_area

Get a number for the total exterior wall area for all Buildings in the Model.

property floor_area

Get a number for the total floor area of all Buildings in the Model.

property footprint_area

Get a number for the total footprint area of all Buildings in the Model.

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 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 Model 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 Model is in proximity to other objects.

property properties

Object properties, including Radiance, Energy and other properties.

property reference_vector

Get or set a Vector3D relating the model to a source coordinate system.

This is useful if the model has been moved from its original location and there may be future operations of merging geometry from the original source model.

property room_2ds

Get a tuple of all unique Room2D objects in the model.

property room_3ds

Get a tuple of all 3D Honeybee Room objects in the model.

property stories

Get a tuple of all unique Story objects in the model.

property to

Model writer object.

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

property tolerance

Get or set a number for the max meaningful difference between x, y, z values.

This value should be in the Model’s units. Zero indicates cases where no tolerance checks should be performed.

property units

Get or set Text for the units system in which the model geometry exists.

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 Buildings in the Model.