dragonfly.skylightparameter module

Skylight Parameters with instructions for generating skylights.

class dragonfly.skylightparameter.DetailedSkylights(polygons, are_doors=None)

Bases: _SkylightParameterBase

Instructions for detailed skylights, defined by 2D Polygons (lists of 2D vertices).

Note that these parameters are intended to represent skylights that are specific to a particular Room2D and, unlike the other SkylightsParameters, this class performs no automatic checks to ensure that the skylights lie within the boundary of the Roof that they are assigned to.

Parameters

• polygons – An array of ladybug_geometry Polygon2D objects in world XY coordinates with one polygon for each skylight. These coordinate values should lie within the Room2D’s Polygon2D.

• are_doors – An array of booleans that align with the polygons and note whether each of the polygons represents an overhead door (True) or a skylight (False). If None, it will be assumed that all polygons represent skylights and they will be translated to Apertures in any resulting Honeybee model. (Default: None).

Properties:

• polygons

• are_doors

ToString()

add_skylight_to_face(face, tolerance=0.01)

Add Apertures to a Honeybee Roof Face using these Skylight Parameters.

Parameters

• face – A honeybee-core Face object.

• tolerance – The maximum difference between point values for them to be considered distinct. (Default: 0.01, suitable for objects in meters).

area_from_face(face)

Get the skylight area generated by these parameters from a Room2D Face3D.

Parameters

face – A Roof Face3D to which these parameters are applied.

check_overlaps(tolerance=0.01)

Check whether any polygons overlap with one another.

Parameters

tolerance – The minimum distance that two polygons must overlap in order for them to be considered overlapping and invalid. (Default: 0.01, suitable for objects in meters).

Returns

A string with the message. Will be an empty string if valid.

check_self_intersecting(tolerance=0.01)

Check whether any polygons in these skylight parameters are self intersecting.

Parameters

tolerance – The minimum distance between a vertex coordinates where they are considered equivalent. (Default: 0.01, suitable for objects in meters).

Returns

A string with the message. Will be an empty string if valid.

check_valid_for_face(face)

Check that these skylight parameters are valid for a given Face3D.

Parameters

face – A Roof Face3D to which these parameters are applied.

Returns

A string with the message. Will be an empty string if valid.

duplicate()

Get a copy of this object.

classmethod from_dict(data)

Create DetailedSkylights from a dictionary.

Parameters

data – A dictionary in the format below.

{
"type": "DetailedSkylights",
"polygons": [((0.5, 0.5), (2, 0.5), (2, 2), (0.5, 2)),
             ((3, 1), (4, 1), (4, 2))],
"are_doors": [False]
}

merge_and_simplify(max_separation, tolerance=0.01)

Merge skylight polygons that are close to one another into a single polygon.

This can be used to create a simpler set of skylights that is easier to edit and is in the same location as the original skylights.

Parameters

• max_separation – A number for the maximum distance between skylight polygons at which point they will be merged into a single geometry. Typically, this max_separation should be set to a value that is slightly larger than the window frame. Setting this equal to the tolerance will simply join neighboring skylights together.

• tolerance – The maximum difference between point values for them to be considered distinct. (Default: 0.01, suitable for objects in meters).

merge_to_bounding_rectangle(tolerance=0.01)

Merge skylight polygons that touch or overlap with one another to a rectangle.

Parameters

tolerance – The minimum distance from the edge of a neighboring polygon at which a point is considered to touch that polygon. (Default: 0.01, suitable for objects in meters).

move(moving_vec)

Get this DetailedSkylights moved along a vector.

Parameters

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

offset_polygons_for_face(face_3d, offset_distance=0.05, tolerance=0.01)

Offset the polygons until all vertices are inside the boundaries of a Face3D.

Parameters

• face_3d – A horizontal Face3D representing the floor geometry of a Room2D to which these skylight parameters are assigned.

• offset_distance – Distance from the edge of the face_3d that the polygons will be offset to. (Default: 0.05, suitable for objects in meters).

• tolerance – The maximum difference between point values for them to be considered distinct. (Default: 0.01, suitable for objects in meters).

reflect(plane)

Get a reflected version of these DetailedSkylights across a plane.

Parameters

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

rotate(angle, origin)

Get these DetailedSkylights rotated counterclockwise in the 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)

Get a scaled version of these DetailedSkylights.

This method is called within the scale methods of the Room2D.

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

Get DetailedSkylights as a dictionary.

union_overlaps(tolerance=0.01)

Union any skylight polygons that overlap with one another.

Parameters

tolerance – The minimum distance that two polygons must overlap in order for them to be considered overlapping. (Default: 0.01, suitable for objects in meters).

property are_doors

Get an array of booleans that note whether each polygon is a door.

property polygons

Get an array of Polygon2Ds with one polygon for each skylight.

class dragonfly.skylightparameter.GriddedSkylightArea(skylight_area, spacing=Autocalculate)

Bases: _SkylightParameterBase

Instructions for gridded skylights defined by an absolute area.

Parameters

• skylight_area – A number for the skylight area in current model units. If this area is larger than the area of the roof that it is applied to, the skylight will fill the parent roof at a 99% ratio.

• spacing – A number for the spacing between the centers of each grid cell. This should be less than a third of the dimension of the Roof geometry if multiple, evenly-spaced skylights are desired. If None or Autocalculate, a spacing of one third the smaller dimension of the parent Roof will be automatically assumed. (Default: Autocalculate).

Properties:

• skylight_area

• spacing

ToString()

add_skylight_to_face(face, tolerance=0.01)

Add Apertures to a Honeybee Roof Face using these Skylight Parameters.

Parameters

• face – A honeybee-core Face object.

• tolerance – The maximum difference between point values for them to be considered distinct. (Default: 0.01, suitable for objects in meters).

area_from_face(face)

Get the skylight area generated by these parameters from a Room2D Face3D.

Parameters

face – A Roof Face3D to which these parameters are applied.

duplicate()

Get a copy of this object.

classmethod from_dict(data)

Create GriddedSkylightArea from a dictionary.

{
"type": "GriddedSkylightArea",
"skylight_area": 2.5,
"spacing": 2
}

scale(factor)

Get a scaled version of these SkylightParameters.

This method is called within the scale methods of the Room2D.

Parameters

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

to_dict()

Get GriddedSkylightArea as a dictionary.

property skylight_area

Get a number for the skylight area in current model units.

property spacing

Get a number or the spacing between the skylights.

None indicates that the spacing will always be one third of the smaller dimension of the parent Roof.

class dragonfly.skylightparameter.GriddedSkylightRatio(skylight_ratio, spacing=Autocalculate)

Bases: _SkylightParameterBase

Instructions for gridded skylights derived from an area ratio with the roof.

Parameters

• skylight_ratio – A number between 0 and 1 for the ratio between the skylight area and the total Roof face area.

• spacing – A number for the spacing between the centers of each grid cell. This should be less than a third of the dimension of the Roof geometry if multiple, evenly-spaced skylights are desired. If None or Autocalculate, a spacing of one third the smaller dimension of the parent Roof will be automatically assumed. (Default: Autocalculate).

Properties:

• skylight_ratio

• spacing

ToString()

add_skylight_to_face(face, tolerance=0.01)

Add Apertures to a Honeybee Roof Face using these Skylight Parameters.

Parameters

• face – A honeybee-core Face object.

• tolerance – The maximum difference between point values for them to be considered distinct. (Default: 0.01, suitable for objects in meters).

area_from_face(face)

Get the skylight area generated by these parameters from a Room2D Face3D.

Parameters

face – A Roof Face3D to which these parameters are applied.

duplicate()

Get a copy of this object.

classmethod from_dict(data)

Create GriddedSkylightRatio from a dictionary.

{
"type": "GriddedSkylightRatio",
"skylight_ratio": 0.05,
"spacing": 2
}

scale(factor)

Get a scaled version of these SkylightParameters.

This method is called within the scale methods of the Room2D.

Parameters

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

to_dict()

Get GriddedSkylightRatio as a dictionary.

property skylight_ratio

Get a number between 0 and 1 for the skylight ratio.

property spacing

Get a number or the spacing between the skylights.

None indicates that the spacing will always be one third of the smaller dimension of the parent Roof.