dragonfly.clerestoryparameter module

Clerestory Parameters with instructions for generating clerestory windows.

class dragonfly.clerestoryparameter.DetailedClerestory(base_line, elevation, polygons, are_doors=None)

Bases: _ClerestoryParameterBase

Instructions for detailed clerestory windows, defined by 2D Polygons.

Parameters:

• base_line – A ladybug_geometry LineSegment2D noting where on the floor plan of the model the clerestory window polygons are located. This establishes the plane and domain in which the clerestory geometries exist.

• elevation – A number for the Z-coordinate that places the base_line and the corresponding clerestory window polygons in 3D space. This elevation value should be below all of the 3D clerestory window geometries and sets the origin of the plane in which the clerestory geometries exist.

• polygons – An array of ladybug_geometry Polygon2D objects within the plane of the base_line with one polygon for each clerestory window. The base_line plane is assumed to have an origin at the end point of the line segment and an X-axis extending along the length of the segment. The plane’s Y-axis always points upwards. Therefore, both X and Y values of each point in the polygon should always be positive.

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

Properties:

• base_line

• elevation

• polygons

• are_doors

• user_data

• base_line_3d

• base_plane

ToString()

add_clerestory_to_face(face, tolerance=0.01)

Add Apertures/Doors to a Honeybee Face using these Clerestory 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).

aperture_area()

Get the Aperture area generated by these parameters.

area()

Get the sub-face area generated by these parameters.

area_from_face(face)

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

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 clerestory 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 clerestory parameters are valid for a given Face3D.

Parameters:

face – A vertical roof-generated 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 DetailedClerestory from a dictionary.

Parameters:

data – A dictionary in the format below.

{
"type": "DetailedClerestory",
"base_line": [(10, 5), (10, 10)],
"elevation": 5,
"polygons": [((0.5, 0.5), (2, 0.5), (2, 2), (0.5, 2)),
             ((3, 1), (4, 1), (4, 2))],
"are_doors": [False, False]
}

classmethod from_face3ds(face3ds, are_doors=None)

Create DetailedClerestory from Face3Ds.

Parameters:

• face3ds – A list of Face3D objects for the detailed clerestory windows.

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

classmethod from_honeybee(sub_faces)

Create DetailedClerestory from an array of Honeybee Apertures and Doors.

Parameters:

sub_faces – A list of Honeybee Apertures and/or Doors to be converted to Dragonfly DetailedClerestory. These Apertures and Doors must all be within the same plane for the resulting DetailedClerestory object to be valid.

make_flush(frame_distance, offset_boundary=False, tolerance=0.01, angle_tolerance=1.0)

Make the edges of clerestory geometry flush if they lie within frame_distance.

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

Parameters:

• frame_distance – Distance with which the edges of each clerestory window will be moved in order to make them flush with neighboring windows.

• offset_boundary – Boolean to note whether the outer boundary of clerestory groups that have been made flush with one another should be offset after all windows within the group have been made flush (True) or the boundary around the group should be left unchanged (False). Set to True when the intended result is more like an offset of clerestory geometries to account for the frame rather than just making the clerestory windows flush. (Default: True).

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

• angle_tolerance – The max angle difference in degrees that a clerestory segment direction can differ from the X or Y axis before it is excluded from being made flush. (Default: 1).

merge_and_simplify(max_separation, tolerance=0.01)

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

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

Parameters:

• max_separation – A number for the maximum distance between clerestory 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 clerestory windows 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 clerestory 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 DetailedClerestory 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 clerestory 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 Face3D representing the vertical wall geometry of a RoofSpecification to which these clerestory 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).

overlapping_geometries(tolerance=0.01)

Get Face3D representing clerestory geometries that are overlapping.

This is used to create helper_geometry for the case of invalid clerestory parameters.

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 list of Face3D representing overlapping clerestory geometries. This list will be empty if none of the geometries overlap.

rectangularize(percent_area_change_threshold=None)

Convert clerestory polygons into rectangles.

Note that rectangular conversion is done simply by taking the bounding rectangle around each polygon. If this bounding rectangle representation changes the area by more than the percent_area_change_threshold, it will not be converted to a rectangle.

Parameters:

percent_area_change_threshold – A positive number for the maximum permitted change in area that is allowed by the operation. For example, setting it to 100 will allow windows to double in size by this operation. Set to None to have all windows rectangularized no matter the change in area that this causes. Setting to zero will have no effect. (Default: None).

reflect(plane)

Get a reflected version of this DetailedClerestory across a plane.

Parameters:

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

remove_doors()

Get a version of this object with all door polygons removed.

remove_duplicate_windows(tolerance=0.01)

Get a version of these clerestory parameters with duplicate geometries removed.

Parameters:

tolerance – The minimum distance between points for them to be considered distinct. (Default: 0.01, suitable for objects in meters).

remove_self_intersecting(tolerance=0.01)

Get these clerestory parameters with self intersecting geometries removed.

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.

remove_small_windows(area_threshold)

Get a version of these clerestory parameters with small geometries removed.

Parameters:

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

remove_windows()

Get a version of this object with all window polygons removed.

rotate(angle, origin)

Get this DetailedClerestory 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 this DetailedClerestory.

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

self_intersecting_geometries(tolerance=0.01)

Get Face3D representing clerestory geometries that are self-intersecting.

This is used to create helper_geometry for the case of invalid clerestory parameters.

Parameters:

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

Returns:

A list of Face3D representing self-intersecting clerestory geometries. This list will be empty if none of the geometries overlap.

to_dict()

Get DetailedClerestory as a dictionary.

union_overlaps(tolerance=0.01)

Union any clerestory 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 base_line

Get LineSegment2D that places the clerestory window polygons in plan.

property base_line_3d

Get LineSegment3D that places the clerestory window polygons in 3D space.

property base_plane

Get LineSegment3D that places the clerestory window polygons in 3D space.

property elevation

Get the Z-coordinate that places the base_line in 3D space.

property polygons

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

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)