dragonfly.clearstoryparameter module

Clearstory Parameters with instructions for generating clearstory windows.

class dragonfly.clearstoryparameter.DetailedClearstory(base_line, elevation, polygons, are_doors=None)

Bases: _ClearstoryParameterBase

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

Parameters:

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

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

• polygons – An array of ladybug_geometry Polygon2D objects within the plane of the base_line with one polygon for each clearstory window. The base_line plane is assumed to have an origin at the first 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 clearstory 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_clearstory_to_face(face, tolerance=0.01)

Add Apertures/Doors to a Honeybee Face using these Clearstory 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 clearstory 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 clearstory 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 clearstory 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 DetailedClearstory from a dictionary.

Parameters:

data – A dictionary in the format below.

{
"type": "DetailedClearstory",
"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 DetailedClearstory from Face3Ds.

Parameters:

• face3ds – A list of Face3D objects for the detailed clearstory 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 DetailedClearstory from an array of Honeybee Apertures and Doors.

Parameters:

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

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

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

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

Parameters:

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

• offset_boundary – Boolean to note whether the outer boundary of clearstory 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 clearstory geometries to account for the frame rather than just making the clearstory 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 clearstory 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 clearstory polygons that are close to one another into a single polygon.

This can be used to create a simpler set of clearstory 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 clearstory 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 clearstory 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 clearstory 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 DetailedClearstory 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 clearstory 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 clearstory 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 clearstory geometries that are overlapping.

This is used to create helper_geometry for the case of invalid clearstory 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 clearstory geometries. This list will be empty if none of the geometries overlap.

rectangularize(percent_area_change_threshold=None)

Convert clearstory 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 DetailedClearstory 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 clearstory 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 clearstory 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 clearstory parameters with small geometries removed.

Parameters:

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

remove_windows()

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

rotate(angle, origin)

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

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 clearstory geometries that are self-intersecting.

This is used to create helper_geometry for the case of invalid clearstory 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 clearstory geometries. This list will be empty if none of the geometries overlap.

to_dict()

Get DetailedClearstory as a dictionary.

union_overlaps(tolerance=0.01)

Union any clearstory 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 clearstory window polygons in plan.

property base_line_3d

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

property base_plane

Get LineSegment3D that places the clearstory 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 clearstory.

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)