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.

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, tolerance=0.01)

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.

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

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.

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)