dragonfly.roof module

Roof specification with instructions for generating sloped roofs over a Story.

class dragonfly.roof.RoofSpecification(geometry)[source]

Bases: object

A roof specification with instructions for generating sloped roofs over a Story.

Parameters:

geometry – An array of Face3D objects representing the geometry of the Roof. Together, these Face3D should either completely cover or completely avoid each Room2D of the Story to which the RoofSpecification is assigned. Cases where Room2Ds are only partially covered by roofs will result in those Room2Ds being extruded to their floor_to_ceiling_height.

Properties:

  • geometry

  • boundary_geometry_2d

  • planes

  • parent

  • has_parent

  • min

  • max

  • min_height

  • max_height

  • center_heights

  • azimuths

  • altitudes

  • tilts

ToString()[source]

Overwrite .NET ToString.

align(line_ray, distance, tolerance=0.01)[source]

Move roof vertices within a given distance of a line to be on that line.

This is useful for coordinating the Roof specification with the alignment of Room2Ds that belong to the same Story as this Roof.

Note that the planes of the input roof Face3Ds will be preserved. This way, the internal structure of the roof geometry will be conserved but the roof will be extended to cover Room2Ds that might have otherwise been aligned to have no Roof geometry above them.

Parameters:

  • line_ray – A ladybug_geometry Ray2D or LineSegment2D to which the roof vertices will be aligned. Ray2Ds will be interpreted as being infinite in both directions while LineSegment2Ds will be interpreted as only existing between two points.

  • distance – The maximum distance between a vertex and the line_ray where the vertex will be moved to lie on the line_ray. Vertices beyond this distance will be left as they are.

  • tolerance – The minimum distance between vertices below which they are considered co-located. This is used to ensure that the alignment process does not create new overlaps in the roof geometry. (Default: 0.01, suitable for objects in meters).

duplicate()[source]

Get a copy of this object.

find_gaps(gap_distance=0.1, tolerance=0.01)[source]

Identify gaps between the geometries that are smaller than a gap_distance.

This is useful for identifying cases where gaps can result in messy room volumes when translating to Honeybee.

Parameters:

  • gap_distance – The maximum distance between two roof geometries that is considered an unwanted gap. Differences between roofs that are higher than this distance are considered meaningful gaps to be preserved. This value should be higher than the tolerance to be meaningful. (Default: 0.1, suitable for objects in meters).

  • selected_indices – An optional list of indices for specific roof geometries to be snapped to the grid. If None, all of the roof geometry will be snapped. (Default: None).

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

Returns:

A list of Point2Ds that note the location of any gaps between the input room_2ds, which are larger than the tolerance but less than the gap_distance.

classmethod from_dict(data)[source]

Initialize an RoofSpecification from a dictionary.

Parameters:

data – A dictionary representation of an RoofSpecification object.

move(moving_vec)[source]

Move this RoofSpecification along a vector.

Parameters:

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

overlap_count(tolerance=0.01)[source]

Get the number of times that the Roof geometries overlap with one another.

This should be zero for the RoofSpecification to be be translated to Honeybee without any loss of geometry.

Parameters:

tolerance – The minimum distance that two Roof geometries can overlap with one another and still be considered distinct. (Default: 0.01, suitable for objects in meters).

Returns:

An integer for the number of times that the roof geometries overlap with one another beyond the tolerance.

pull_to_segments(line_segments, distance, snap_vertices=True, selected_indices=None, tolerance=0.01)[source]

Pull the vertices of this roof to several LineSegment2D.

This includes both an alignment to the line segments as well as an optional snapping to the line end points. The planes of the input roof Face3Ds will be preserved.

The benefit of calling this method as opposed to iterating over the segments and calling align is that this method will only align and snap to the closest segment across all of the input line_segments. This often helps avoid snapping to undesirable line segments, particularly when there are two ore more segments that are within the distance.

Parameters:

  • line_segments – A list of ladybug_geometry LineSegment2D to which this roof’s vertices will be pulled.

  • distance – The maximum distance between a roof vertex and the line_segments where the vertex will be moved to lie on the segments. Vertices beyond this distance will be left as they are.

  • snap_vertices – A boolean to note whether roof vertices that are close to the segment end points within the distance should be snapped to the end point instead of simply being aligned to the nearest segment. (Default: True).

  • selected_indices – An optional list of indices for specific roof geometries to be split with the input polygon. If None, all of the roof geometry will be tested for intersection with the input polygon. (Default: None).

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

reflect(plane)[source]

Reflect this RoofSpecification across a plane.

Parameters:

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

resolved_geometry(tolerance=0.01)[source]

Get a version of this object’s geometry with all overlaps in plan resolved.

In the case of overlaps, the roof geometry that has the lowest average z-value for the overlap will become the “correct” one that actually bounds the room geometry.

Parameters:

tolerance – The minimum distance that two Roof geometries can overlap with one another and still be considered distinct. (Default: 0.01, suitable for objects in meters).

Returns:

A list of Face3D that have no overlaps in plan.

rotate_xy(angle, origin)[source]

Rotate RoofSpecification 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)[source]

Scale this RoofSpecification 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, selected_indices=None, tolerance=0.01)[source]

Snap naked roof vertices to the nearest grid node defined by an increment.

This is useful for coordinating the Roof specification with the grid snapping of Room2Ds that belong to the same Story as this Roof.

Note that the planes of the input roof Face3Ds will be preserved. This way, the internal structure of the roof geometry will be conserved but the roof will be extended to cover Room2Ds that might have otherwise been snapped to the a node where they have no Roof geometry above them. This command will preserve all roof ridge lines and vertices along them will only be moved if the ridge line is oriented to the X or Y axis.

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 Room2D that you wish to resolve.

  • selected_indices – An optional list of indices for specific roof geometries to be snapped to the grid. If None, all of the roof geometry will be snapped. (Default: None).

  • tolerance – The minimum distance between vertices below which they are considered co-located. (Default: 0.01, suitable for objects in meters).

split_with_lines(lines, selected_indices=None, tolerance=0.01)[source]

Split the geometry of this roof using multiple line segments together.

If the input lines do not intersect the roof geometry in a manner that splits it, this roof will remain unaltered.

Parameters:

  • lines – A list of LineSegment2D objects that will be used to split this roof geometry.

  • selected_indices – An optional list of indices for specific roof geometries to be split with the input lines. If None, all of the roof geometry will be tested for intersection with the input polygon. (Default: None).

  • tolerance – The maximum difference between point values for them to be considered distinct from one another. (Default: 0.01; suitable for objects in Meters).

split_with_polygon(polygon, selected_indices=None, tolerance=0.01)[source]

Split the geometry of this roof using a polygon.

If the input polygon does not intersect the roof geometry in a manner that splits it, this roof will remain unaltered.

Parameters:

  • polygon – A Polygon2D object that will be used to split the roof geometry.

  • selected_indices – An optional list of indices for specific roof geometries to be split with the input polygon. If None, all of the roof geometry will be tested for intersection with the input polygon. (Default: None).

  • tolerance – The maximum difference between point values for them to be considered distinct from one another. (Default: 0.01; suitable for objects in Meters).

subtract_roofs(minuend_index, subtrahend_indices, tolerance=0.01)[source]

Subtract one or more geometries in this roof from a given geometry.

This is useful for resolving overlaps between geometries in the roof, particularly when one geometry above another one should take precedence.

Parameters:

  • minuend_index – The index of a geometry in this roof from which the subtrahend roof geometries will be subtracted.

  • subtrahend_indices – A list of indices for geometries in this roof that will be used to remove part of the geometry at the minuend_index.

  • tolerance – The maximum difference between point values for them to be considered distinct from one another. (Default: 0.01; suitable for objects in Meters).

to_dict()[source]

Return RoofSpecification as a dictionary.

union_coplanar(tolerance=0.01, angle_tolerance=1.0)[source]

Union coplanar and overlapping geometries on this Roof together.

This is useful for removing duplicated roof geometries that would otherwise slow down the translation process and potentially create unwanted results.

Parameters:

  • tolerance – The minimum distance between two roof geometries at which point they will be unioned together. (Default: 0.01, suitable for objects in meters).

  • angle_tolerance – The max angle difference in degrees that planes can differ from one another for them to be considered coplanar. (Default: 1.0).

update_geometry_2d(new_polygon_2d, polygon_index)[source]

Change one of the Face3D in this roof by supplying a 2D Polygon.

This method is intended to be used when the roof geometry has been edited by some external means and this RoofSpecification should be updated for coordination. It it particularly helpful when the external means of editing has happened in 2D plan view and only the boundary of the roof should be updated while the plane of the roof geometry is held constant.

Parameters:

  • new_polygon_2d – A Polygon2D for a new roof geometry that is to replace one of the existing geometries in the roof. Ideally, this is one of this RoofSpecification’s boundary_geometry_2d polygons that has been edited.

  • polygon_index – An integer for the index of the boundary polygon in the roof to be replaced.

update_geometry_3d(new_face_3d, face_index)[source]

Change one of the Face3D in this RoofSpecification.geometry.

This method is intended to be used when the roof geometry has been edited by some external means and this RoofSpecification should be updated for coordination.

Parameters:

  • new_face_3d – A Face3D for a new roof geometry that is to replace one of the existing Face3D in the roof.

  • face_index – An integer for the index of the Face3D in the roof to be replaced.

property altitudes

Get a tuple of altitudes for each roof geometry in degrees.

These values range from 0 (vertical) up to 90 (horizontal).

property azimuths

Get a tuple of azimuths for each roof geometry in degrees.

These values start from 0, indicating the positive Y-axis, and move clockwise up to 360, which indicates a return to the positive Y-axis.

This will be zero if a geometry is perfectly horizontal.

property boundary_geometry_2d

Get a tuple of Polygon2D for the boundaries around each Face3D in geometry.

These Polygons will be in the World XY coordinate system instead of the coordinate system of the Face3D’s plane.

property center_heights

Get a tuple of average Z-values for each roof geometry.

property geometry

Get or set a tuple of Face3D objects representing the geometry of the Roof.

property has_parent

Boolean noting whether this RoofSpecification has a parent Story.

property max

Get a Point2D for the max bounding rectangle vertex in the XY plane.

This is useful in calculations to determine if this RoofSpecification is in proximity to other objects.

property max_height

Get highest Z-value of the roof geometry.

property min

Get a Point2D for the min bounding rectangle vertex in the XY plane.

This is useful in calculations to determine if this RoofSpecification is in proximity to other objects.

property min_height

Get lowest Z-value of the roof geometry.

property parent

Parent Story if assigned. None if not assigned.

property planes

Get a tuple of Planes for each Face3D in geometry.

property tilts

Get a tuple of tilts for each roof geometry in degrees.

These values range from 0 (horizontal) up to 90 (vertical).