dragonfly.context module

Dragonfly Context Shade.

class dragonfly.context.ContextShade(identifier, geometry, is_detached=True)

Bases: _BaseGeometry

A Context Shade object defined by an array of Face3Ds and/or Mesh3Ds.

Parameters:

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

• geometry – An array of ladybug_geometry Face3D and/or Mesh3D objects that together represent the context shade.

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

Properties:

• identifier

• display_name

• geometry

• is_detached

• area

• min

• max

• 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 shades) 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 dragonfly identifiers.

apply_vertex_map(vertex_map)

Apply a vertex map to this object’s vertices.

Vertex maps are helpful for restoring vertices in geometry after performing a series of complex operations. For example, when performing a series of operations that edit the geometry in relation to a plane, a ContextShade.unconforming_vertex_map() can be generated to put back the vertices that did not relate to the plane of the grid.

Parameters:

• vertex_map – A list of lists where each sub-list represents a Face3D or Mesh3D

• where (in this object. Each Face3D is represented with a list of lists)

• represents (each sub-list is a loop of the Face3D. The first sub-list)

• in (the boundary and subsequent sub-lists represent holes. Each item)

• object (each sub-list represents a vertex. If a given vertex on this)

• is (is to be left as it)

• sub-list. (appear in the)

• Otherwise

• should (the Point3D to replace the vertex on this object)

• sub-list.

duplicate()

Get a copy of this object.

classmethod from_dict(data)

Initialize an ContextShade from a dictionary.

Parameters:

data – A dictionary representation of an ContextShade object.

classmethod from_honeybee(shade)

Initialize an ContextShade from a Honeybee Shade or ShadeMesh.

Parameters:

shade – A Honeybee Shade or ShadeMesh object.

move(moving_vec)

Move this ContextShade along a vector.

Parameters:

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

reflect(plane)

Reflect this ContextShade across a plane.

Parameters:

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

rotate_xy(angle, origin)

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

snap_to_grid(grid_increment, base_plane=None)

Snap this object to the nearest XY grid node defined by an increment.

Note that, even though ContextShade geometry is defined using 3D vertices, only the X and Y coordinates will be snapped, which is consistent with how the Room2D.snap_to_grid method works.

All properties assigned to the ContextShade will be preserved and any degenerate geometries are automatically cleaned out of the result.

Parameters:

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

• base_plane – An optional ladybug-geometry Plane object to set the coordinate system of the grid in which this Room will be snapped. If None, the World XY coordinate system will be used. (Default: None).

to_dict(abridged=False, included_prop=None)

Return ContextShade as a dictionary.

Parameters:

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

to_honeybee()

Convert Dragonfly ContextShade to a list of Honeybee Shades and ShadeMeshes.

unconforming_vertex_map(plane, angle_tolerance=1.0, min_length=0.01)

Analyze this object’s vertices for conformity with a plane’s XY axes.

Vertices of this object that do not conform to the plane will be highted in the result.

Parameters:

• plane – A ladybug-geometry Plane that will be used to evaluate whether each geometry vertex conforms to the plane or not.

• angle_tolerance – A number for the maximum difference in degrees that the geometry segments can differ from the XY axes of the plane for it to be considered non-conforming. (Default: 1.0).

• min_length – A number for the minimum length that a Room2D segment must be for it to be considered for non-conformity. Setting this to zero will evaluate all Room2D segments. (Default: 0.01; suitable for objects in meters).

Returns:

A list of lists where each sub-list represents a Face3D or Mesh3D in this object. Each Face3D is represented with a list of lists where each sub-list is a loop of the Face3D. The first sub-list represents the boundary and subsequent sub-lists represent holes. Each item in each sub-list represents a vertex. If a given vertex is conforming to the plane, it will show up as None in the sub-list. Otherwise, the Point3D for the non-conforming vertex will appear in the sub-list.

property area

Get a number for the total surface area of the ContextShade.

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 tuple of Face3D and/or Mesh3D objects that represent the context shade.

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 is_detached

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

property max

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

This is useful in calculations to determine if this ContextShade 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 ContextShade is in proximity to other objects.

property properties

Object properties, including Radiance, Energy and other properties.

property to

ContextShade writer object.

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

property user_data

Get or set an optional dictionary for additional meta data for this object.

This will be None until it has been set. All keys and values of this dictionary should be of a standard Python type to ensure correct serialization of the object to/from JSON (eg. str, float, int, list dict)