fairyfly.shape module

Fairyfly Shape.

class fairyfly.shape.Shape(geometry, identifier=None)

Bases: _Base

A single planar shape.

Parameters:

• geometry – A ladybug-geometry Face3D.

• identifier – Text string for a unique Shape ID. Must be a UUID in the format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. If None, a UUID will automatically be generated. (Default: None).

Properties:

• identifier

• display_name

• therm_uuid

• full_id

• parent

• has_parent

• geometry

• vertices

• normal

• area

• perimeter

• min

• max

• center

• tilt

• altitude

• azimuth

• user_data

ToString()

Overwrite .NET ToString.

check_planar(tolerance=0.01, raise_exception=True, detailed=False)

Check whether all of the Shape’s vertices lie within the same plane.

Parameters:

• tolerance – The minimum distance between a given vertex and a the object’s plane at which the vertex is said to lie in the plane. Default: 0.01, suitable for objects in millimeters.

• raise_exception – Boolean to note whether an ValueError should be raised if a vertex does not lie within the object’s plane.

• detailed – Boolean for whether the returned object is a detailed list of dicts with error info or a string with a message. (Default: False).

Returns:

A string with the message or a list with a dictionary if detailed is True.

check_self_intersecting(tolerance=0.01, raise_exception=True, detailed=False)

Check whether the edges of the Shape intersect one another (like a bowtie).

Parameters:

• tolerance – The minimum difference between the coordinate values of two vertices at which they can be considered equivalent. Default: 0.01, suitable for objects in millimeters.

• raise_exception – If True, a ValueError will be raised if the object intersects with itself. Default: True.

• detailed – Boolean for whether the returned object is a detailed list of dicts with error info or a string with a message. (Default: False).

Returns:

A string with the message or a list with a dictionary if detailed is True.

duplicate()

Get a copy of this object.

classmethod from_dict(data)

Initialize an Shape from a dictionary.

Parameters:

data – A dictionary representation of an Shape object.

classmethod from_vertices(vertices, identifier=None)

Create a Shape from vertices with each vertex as an iterable of 3 floats.

Note that this method is not recommended for a shape with one or more holes since the distinction between hole vertices and boundary vertices cannot be derived from a single list of vertices.

Parameters:

• vertices – A flattened list of 3 or more vertices as (x, y, z).

• identifier – Text string for a unique Shape ID. Must be a UUID in the format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. If None, a UUID will automatically be generated. (Default: None).

insert_vertex(point, tolerance=0.01)

Insert a Point3D into this Shape’s geometry if it lies within the tolerance.

Parameters:

• point – A Point3D to be inserted into this Shape geometry if it lies within the tolerance of the Shape’s existing segments.

• tolerance – The minimum distance between a vertex and the boundary segments at which point the vertex is considered colinear. Default: 0.01, suitable for objects in millimeters.

static intersect_adjacency(shapes, tolerance=0.01, plane=None)

Intersect the line segments of Shapes to ensure matching adjacencies.

Parameters:

• shapes – A list of Shapes for which adjacent segments will be intersected.

• tolerance – The minimum difference between the coordinate values of two faces at which they can be considered adjacent. (Default: 0.01, suitable for objects in millimeters).

• plane – An optional ladybug-geometry Plane object to set the plane in which all Shape intersection will be evaluated. If None, the plane will automatically be senses from the input geometries and a ValueError will be raised if not all of the input Shapes lie within the same plane given the input tolerance. (Default: None).

Returns:

An array of Shapes that have been intersected with one another.

is_geo_equivalent(shape, tolerance=0.01)

Get a boolean for whether this object is geometrically equivalent to another.

The total number of vertices and the ordering of these vertices can be different but the geometries must share the same center point and be next to one another to within the tolerance.

Parameters:

• shape – Another Shape for which geometric equivalency will be tested.

• tolerance – The minimum difference between the coordinate values of two vertices at which they can be considered geometrically equivalent.

Returns:

True if geometrically equivalent. False if not geometrically equivalent.

move(moving_vec)

Move this Shape along a vector.

Parameters:

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

reflect(plane)

Reflect this Shape across a plane.

Parameters:

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

remove_colinear_vertices(tolerance=0.01)

Remove all colinear and duplicate vertices from this object’s geometry.

Parameters:

tolerance – The minimum distance between a vertex and the boundary segments at which point the vertex is considered colinear. Default: 0.01, suitable for objects in millimeters.

rename_by_attribute(format_str='{display_name} - {area}')

Set the display name of this Shape using a format string with attributes.

Parameters:

format_str – Text string for the pattern with which the Shape will be renamed. Any property on this class may be used and each property should be put in curly brackets. Nested properties can be specified by using “.” to denote nesting levels (eg. properties.energy.construction.display_name). Functions that return string outputs can also be passed here as long as these functions defaults specified for all arguments.

rotate(axis, angle, origin)

Rotate this Shape by a certain angle around an axis and origin.

Parameters:

• axis – A ladybug_geometry Vector3D axis representing the axis of rotation.

• angle – An angle for rotation in degrees.

• origin – A ladybug_geometry Point3D for the origin around which the object will be rotated.

rotate_xy(angle, origin)

Rotate this Shape counterclockwise in the world 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)

Scale this Shape 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).

to_dict(abridged=False, included_prop=None, include_plane=True)

Return Shape as a dictionary.

Parameters:

• abridged – Boolean to note whether the extension properties of the object (ie. THERM materials) should be included in detail (False) or just referenced by identifier (True). (Default: False).

• included_prop – List of properties to filter keys that must be included in output dictionary. For example [‘therm’] will include ‘therm’ key if available in properties to_dict. By default all the keys will be included. To exclude all the keys from extensions use an empty list.

• include_plane – Boolean to note wether the plane of the Face3D should be included in the output. This can preserve the orientation of the X/Y axes of the plane but is not required and can be removed to keep the dictionary smaller. (Default: True).

property altitude

Get the altitude of the geometry between +90 (up) and -90 (down).

property area

Get the area of the shape.

property azimuth

Get the azimuth of the geometry, between 0 and 360.

Given Y-axis as North, 0 = North, 90 = East, 180 = South, 270 = West This will be zero if the Face3D is perfectly horizontal.

property center

Get a ladybug_geometry Point3D for the center of the shape.

Note that this is the center of the bounding rectangle around this geometry and not the area centroid.

property display_name

Get or set a string for the object name without any character restrictions.

If not set, this will be equal to the identifier.

property full_id

Get a string with both the object display_name and identifier.

This is formatted as display_name[identifier].

This is useful in error messages to give users an easy means of finding invalid objects within models. If there is no display_name assigned, only the identifier will be returned.

property geometry

Get a ladybug_geometry Face3D object representing the Shape.

property has_parent

Get a boolean noting whether this Shape has a parent object.

property identifier

Get or set a text string for the unique object identifier.

This must be a UUID in the format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx and it remains constant as the object is mutated, copied, and serialized to different formats (eg. therm XML). As such, this property is used to reference the object across a Model.

property max

Get a Point3D for the maximum of the bounding box around the object.

property min

Get a Point3D for the minimum of the bounding box around the object.

property normal

Get a ladybug_geometry Vector3D for the direction the shape is pointing.

property parent

Get the parent object if assigned. None if not assigned.

The parent object is typically a GlazingSystem.

property perimeter

Get the perimeter of the shape.

property properties

Get object properties, including THERM and other properties.

property therm_uuid

Get the UUID of this object as it would appear in a THERM XML or thmz file.

This is always derived from the object identifier but this is slightly different than standard UUIDs, which have 4 more values in a 8-4-4-4-12 structure instead of a 8-4-4-12 structure used by THERM.

property tilt

Get the tilt of the geometry between 0 (up) and 180 (down).

property to

Shape writer object.

Use this method to access Writer class to write the shape in different formats.

Usage:

shape.to.therm(shape) -> therm XML element

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)

property vertices

Get a list of vertices for the shape (in counter-clockwise order).