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. None of these geometries should overlap in plan and, together, these Face3D should either completely cover or skip each Room2D of the Story to which the RoofSpecification is assigned.

Properties:

  • geometry

  • boundary_geometry_2d

  • planes

  • parent

  • has_parent

  • min

  • max

ToString()[source]

Overwrite .NET ToString.

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

Move naked 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 the point that they 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.

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

Parameters

tolerance – The minimum distance that two Roof geometries can overlap with one another and still be considered valid. 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.

reflect(plane)[source]

Reflect this RoofSpecification across a plane.

Parameters

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

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

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.

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

to_dict()[source]

Return RoofSpecification as a dictionary.

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 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 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 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 parent

Parent Story if assigned. None if not assigned.

property planes

Get a tuple of Planes for each Face3D in geometry.