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

Offset the edges of all skylight polygons by a certain distance.

This is useful for translating between interfaces that expect the window frame to be included within or excluded from the geometry.

Note that this operation can often create polygons that collide with one another or extend past the parent Face. So it may be desirable to run the union_overlaps method after using this one.

Parameters:

• offset_distance – Distance with which the edges of each polygon will be offset from the original geometry. Positive values will offset the geometry outwards and negative values will offset the geometries inwards.

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

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.

remove_small_skylights(area_threshold)

Remove any small skylight polygons that are below a certain area threshold.

Parameters:

area_threshold – A number for the area below which a skylight polygon will be removed.

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

split(face_3ds, tolerance=0.01)

Split these skylight parameters across several Face3D.

This is useful when the Room2D to which the skylight is assigned has been split into multiple Room2Ds.

Parameters:

• face_3ds – A list of horizontal Face3D representing the floor geometries of a Room2D to which these skylight parameters are split across.

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

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.

split(face_3ds, tolerance=0.01)

Split these skylight parameters across several Face3D.

This is useful when the Room2D to which the skylight is assigned has been split into multiple Room2Ds.

Parameters:

• face_3ds – A list of horizontal Face3D representing the floor geometries of a Room2D to which these skylight parameters are split across.

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

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.

split(face_3ds, tolerance=0.01)

Split these skylight parameters across several Face3D.

This is useful when the Room2D to which the skylight is assigned has been split into multiple Room2Ds.

Parameters:

• face_3ds – A list of horizontal Face3D representing the floor geometries of a Room2D to which these skylight parameters are split across.

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

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.