honeybee.door module

Honeybee Door.

class honeybee.door.Door(identifier, geometry, boundary_condition=None, is_glass=False)

Bases: _BaseWithShade

A single planar Door in a Face.

Parameters

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

• geometry – A ladybug-geometry Face3D.

• boundary_condition – Boundary condition object (Outdoors, Surface, etc.). Default: Outdoors.

• is_glass – Boolean to note whether this object is a glass door as opposed to an opaque door. Default: False.

Properties:

• identifier

• display_name

• boundary_condition

• is_glass

• indoor_shades

• outdoor_shades

• parent

• top_level_parent

• has_parent

• geometry

• vertices

• upper_left_vertices

• triangulated_mesh3d

• normal

• center

• area

• perimeter

• min

• max

• altitude

• azimuth

• type_color

• bc_color

• user_data

ToString()

Overwrite .NET ToString.

add_indoor_shade(shade)

Add a Shade object to be added to the indoors of this object.

Indoor Shade objects can be used to represent furniture, the interior portion of light shelves, the interior part of mullions, etc. For representing finely detailed objects like blinds or roller shades, it may be more appropriate to model them as materials assigned to Aperture properties (like Radiance materials or Energy constructions).

Parameters

shade – A Shade object to add to the indoors of this object.

add_indoor_shades(shades)

Add a list of Shade objects to the indoors of this object.

Parameters

shades – A list of Shade objects to add to the indoors of this object.

add_outdoor_shade(shade)

Add a Shade object to the outdoors of this object.

Outdoor Shade objects can be used to represent balconies, outdoor furniture, overhangs, light shelves, fins, the exterior part of mullions, etc. For representing larger shade objects like trees or other buildings, it may be more appropriate to add them to the Model as orphaned_shades without a specific parent object.

Parameters

shade – A Shade object to add to the outdoors of this object.

add_outdoor_shades(shades)

Add a list of Shade objects to the outdoors of this object.

Parameters

shades – A list of Shade objects to add to the outdoors of this object.

add_prefix(prefix)

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

This is particularly useful in workflows where you duplicate and edit a starting object and then want to combine it with the original object into one Model (like making a model of repeated rooms) since all objects within a Model must have unique identifiers.

Parameters

prefix – Text that will be inserted at the start of this object’s (and child objects’) identifier and display_name. It is recommended that this prefix be short to avoid maxing out the 100 allowable characters for honeybee identifiers.

cardinal_direction(north_vector=Vector2D(0.0, 1.0))

Get text description for the cardinal direction that the door is pointing.

Will be one of the following: (‘North’, ‘NorthEast’, ‘East’, ‘SouthEast’, ‘South’, ‘SouthWest’, ‘West’, ‘NorthWest’).

Parameters

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

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

Check whether all of the Door’s vertices lie within the same plane.

Parameters

• tolerance – The minimum distance between a given vertex and a the object’s plane at which the vertex is said to lie in the plane. Default: 0.01, suitable for objects in meters.

• raise_exception – Boolean to note whether an ValueError should be raised if a vertex does not lie within the object’s plane.

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

Returns

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

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

Check whether the edges of the Door intersect one another (like a bowtie).

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

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.

display_dict()

Get a list of DisplayFace3D dictionaries for visualizing the object.

duplicate()

Get a copy of this object.

classmethod from_dict(data)

Initialize an Door from a dictionary.

Parameters

data – A dictionary representation of an Door object.

classmethod from_vertices(identifier, vertices, boundary_condition=None, is_glass=False)

Create a Door from vertices with each vertex as an iterable of 3 floats.

Parameters

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

• vertices – A flattened list of 3 or more vertices as (x, y, z).

• boundary_condition – Boundary condition object (eg. Outdoors, Surface). Default: Outdoors.

• is_glass – Boolean to note whether this object is a glass door as opposed to an opaque door. Default: False.

horizontal_orientation(north_vector=Vector2D(0.0, 1.0))

Get a number between 0 and 360 for the orientation of the door in degrees.

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

is_geo_equivalent(door, tolerance=0.01)

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

The total number of vertices and the ordering of these vertices can be different but the geometries must share the same center point and be next to one another to within the tolerance.

Parameters

• door – Another Door for which geometric equivalency will be tested.

• tolerance – The minimum difference between the coordinate values of two vertices at which they can be considered geometrically equivalent.

Returns

True if geometrically equivalent. False if not geometrically equivalent.

move(moving_vec)

Move this Door along a vector.

Parameters

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

move_shades(moving_vec)

Move all indoor and outdoor shades assigned to this object along a vector.

Parameters

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

overhang(depth, angle=0, indoor=False, tolerance=0.01, base_name=None)

Add a single overhang for this Door. Can represent entryway awnings.

Parameters

• depth – A number for the overhang depth.

• angle – A number for the for an angle to rotate the overhang in degrees. Positive numbers indicate a downward rotation while negative numbers indicate an upward rotation. Default is 0 for no rotation.

• indoor – Boolean for whether the overhang should be generated facing the opposite direction of the aperture normal (typically meaning indoor geometry). Default: False.

• tolerance – An optional value to return None if the overhang has a length less than the tolerance. Default: 0.01, suitable for objects in meters.

• base_name – Optional base name for the shade objects. If None, the default is InOverhang or OutOverhang depending on whether indoor is True.

Returns

A list of the new Shade objects that have been generated.

reflect(plane)

Reflect this Door across a plane.

Parameters

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

reflect_shades(plane)

Reflect all indoor and outdoor shades assigned to this object across a plane.

Parameters

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

remove_colinear_vertices(tolerance=0.01)

Remove all colinear and duplicate vertices from this object’s geometry.

Note that this does not affect any assigned Shades.

Parameters

tolerance – The minimum distance between a vertex and the boundary segments at which point the vertex is considered colinear. Default: 0.01, suitable for objects in meters.

remove_indoor_shades()

Remove all indoor shades assigned to this object.

remove_outdoor_shades()

Remove all outdoor shades assigned to this object.

remove_shades()

Remove all indoor and outdoor shades assigned to this object.

rotate(axis, angle, origin)

Rotate this Door by a certain angle around an axis and origin.

Parameters

• axis – A ladybug_geometry Vector3D axis representing the axis of rotation.

• angle – An angle for rotation in degrees.

• origin – A ladybug_geometry Point3D for the origin around which the object will be rotated.

rotate_shades(axis, angle, origin)

Rotate all indoor and outdoor shades assigned to this object.

Parameters

• axis – A ladybug_geometry Vector3D axis representing the axis of rotation.

• angle – An angle for rotation in degrees.

• origin – A ladybug_geometry Point3D for the origin around which the object will be rotated.

rotate_xy(angle, origin)

Rotate this Door counterclockwise in the world XY plane by a certain angle.

Parameters

• angle – An angle in degrees.

• origin – A ladybug_geometry Point3D for the origin around which the object will be rotated.

rotate_xy_shades(angle, origin)

Rotate all indoor and outdoor shades counterclockwise in the world XY plane.

Parameters

• angle – An angle in degrees.

• origin – A ladybug_geometry Point3D for the origin around which the object will be rotated.

scale(factor, origin=None)

Scale this Door by a factor from an origin point.

Parameters

• factor – A number representing how much the object should be scaled.

• origin – A ladybug_geometry Point3D representing the origin from which to scale. If None, it will be scaled from the World origin (0, 0, 0).

scale_shades(factor, origin=None)

Scale all indoor and outdoor shades assigned to this object by a factor.

Parameters

• factor – A number representing how much the object should be scaled.

• origin – A ladybug_geometry Point3D representing the origin from which to scale. If None, it will be scaled from the World origin (0, 0, 0).

set_adjacency(other_door)

Set this door to be adjacent to another (and vice versa).

Note that this method does not verify whether the other_door geometry is co-planar or compatible with this one so it is recommended that a test be performed before using this method in order to verify these criteria. The Face3D.is_centered_adjacent() or the Face3D.is_geometrically_equivalent() methods are both suitable for this purpose.

Parameters

other_door – Another Door object to be set adjacent to this one.

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

Return Door as a dictionary.

Parameters

• abridged – Boolean to note whether the extension properties of the object (ie. materials, constructions) should be included in detail (False) or just referenced by identifier (True). (Default: False).

• included_prop – List of properties to filter keys that must be included in output dictionary. For example [‘energy’] will include ‘energy’ key if available in properties to_dict. By default all the keys will be included. To exclude all the keys from extensions use an empty list.

• include_plane – Boolean to note wether the plane of the Face3D should be included in the output. This can preserve the orientation of the X/Y axes of the plane but is not required and can be removed to keep the dictionary smaller. (Default: True).

BC_COLORS = {'Outdoors': (R:128, G:204, B:255, A:255), 'Surface': (R:0, G:190, B:0, A:255)}

TYPE_COLORS = {False: (R:160, G:150, B:100, A:255), True: (R:128, G:204, B:255, A:100)}

property altitude

Get the altitude of the geometry between +90 (up) and -90 (down).

property area

Get the area of the door.

property azimuth

Get the azimuth of the geometry, between 0 and 360.

Given Y-axis as North, 0 = North, 90 = East, 180 = South, 270 = West This will be zero if the Face3D is perfectly horizontal.

property bc_color

Get a Color to be used in visualizations by boundary condition.

property boundary_condition

Get or set the boundary condition of this door.

property center

Get a ladybug_geometry Point3D for the center of the door.

Note that this is the center of the bounding rectangle around this geometry and not the area centroid.

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 full_id

Get a string with both the object display_name and identifier.

This is formatted as display_name[identifier].

This is useful in error messages to give users an easy means of finding invalid objects within models. If there is no display_name assigned, only the identifier will be returned.

property geometry

Get a ladybug_geometry Face3D object representing the door.

property has_parent

Get a boolean noting whether this Door has a parent Face.

property identifier

Get or set a text string for the unique object identifier.

This identifier remains constant as the object is mutated, copied, and serialized to different formats (eg. dict, idf, rad). As such, this property is used to reference the object across a Model.

property indoor_shades

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

property is_glass

Get or set a boolean to note whether this object is a glass door.

property max

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

property min

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

property normal

Get a ladybug_geometry Vector3D for the direction the door is pointing.

property outdoor_shades

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

property parent

Get the parent Face if assigned. None if not assigned.

property perimeter

Get the perimeter of the door.

property properties

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

property shades

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

property to

Door writer object.

Use this method to access Writer class to write the door in different formats.

Usage:

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

property top_level_parent

Get the top-level parent object if assigned.

This will be a Room if there is a parent Face that has a parent Room and will be a Face if the parent Face is orphaned. Will be None if no parent is assigned.

property triangulated_mesh3d

Get a ladybug_geometry Mesh3D of the door geometry composed of triangles.

In EnergyPlus / OpenStudio workflows, this property is used to subdivide the door when it has more than 4 vertices. This is necessary since EnergyPlus cannot accept sub-faces with more than 4 vertices.

property type_color

Get a Color to be used in visualizations by type.

property upper_left_vertices

Get a list of vertices starting from the upper-left corner.

This property should be used when exporting to EnergyPlus / OpenStudio.

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 vertices

Get a list of vertices for the door (in counter-clockwise order).