honeybee.shade module

Honeybee Shade.

class honeybee.shade.Shade(identifier, geometry, is_detached=False)

Bases: _Base

A single planar shade.

Parameters:

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

• geometry – A ladybug-geometry Face3D.

• is_detached – Boolean to note whether this object is detached from other geometry. Cases where this should be True include shade representing surrounding buildings or context. (Default: False).

Properties:

• identifier

• display_name

• is_detached

• parent

• top_level_parent

• has_parent

• is_indoor

• geometry

• vertices

• upper_left_vertices

• normal

• center

• area

• perimeter

• min

• max

• tilt

• altitude

• azimuth

• type_color

• bc_color

• user_data

ToString()

Overwrite .NET ToString.

add_prefix(prefix)

Change the identifier of this object by inserting a prefix.

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

Parameters:

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

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

Check whether all of the Shade’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 Shade intersect one another (like a bowtie).

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 Shade from a dictionary.

Parameters:

data – A dictionary representation of an Shade object.

classmethod from_vertices(identifier, vertices, is_detached=False)

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

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

Parameters:

• identifier – Text string for a unique Shade 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).

• is_detached – Boolean to note whether this object is detached from other geometry. Cases where this should be True include shade representing surrounding buildings or context. (Default: False).

is_geo_equivalent(shade, 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:

• shade – Another Shade 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 Shade along a vector.

Parameters:

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

reflect(plane)

Reflect this Shade 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.

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.

rotate(axis, angle, origin)

Rotate this Shade 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_xy(angle, origin)

Rotate this Shade 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)

Scale this Shade 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).

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

Return Shade as a dictionary.

Parameters:

• abridged – Boolean to note whether the extension properties of the object (ie. modifiers, transmittance schedule) 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_COLOR = (R:120, G:75, B:190, A:255)

TYPE_COLORS = {(False, False): (R:120, G:75, B:190, A:255), (False, True): (R:80, G:50, B:128, A:255), (True, False): (R:159, G:99, B:255, A:255), (True, True): (R:159, G:99, B:255, A:255)}

property altitude

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

property area

Get the area of the shade.

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 center

Get a ladybug_geometry Point3D for the center of the shade.

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

property has_parent

Get a boolean noting whether this Shade has a parent object.

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 is_detached

Get or set a boolean for whether this object is detached from other geometry.

This will automatically be set to False if the shade is assigned to parent objects.

property is_indoor

Get a boolean for whether this Shade is on the indoors of its parent object.

Note that, if there is no parent assigned to this Shade, this property will be False.

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 shade is pointing.

property parent

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

The parent object can be either a Room, Face, Aperture or Door.

property perimeter

Get the perimeter of the shade.

property properties

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

property tilt

Get the tilt of the geometry between 0 (up) and 180 (down).

property to

Shade writer object.

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

Usage:

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

property top_level_parent

Get the top-level parent object if assigned.

This will be the highest-level parent in the hierarchy of the parent-child chain. Will be None if no parent is assigned.

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 shade (in counter-clockwise order).