fairyfly.model module

Fairyfly Model.

class fairyfly.model.Model(shapes=None, boundaries=None, units='Millimeters', tolerance=None, angle_tolerance=1.0)

Bases: _Base

A collection of Shapes and Boundaries representing a model.

Parameters:

• shapes – A list of Shape objects in the model.

• boundaries – A list of the Boundary objects in the model.

• units –

  Text for the units system in which the model geometry exists. Default: ‘Millimeters’. Choose from the following:

  • Millimeters

  • Inches

  • Centimeters

  • Meters

  • Feet

• tolerance – The maximum difference between x, y, and z values at which vertices are considered equivalent. Zero indicates that no tolerance checks should be performed. None indicates that the tolerance will be set based on the units above, with the tolerance consistently being between 0.01 mm and 0.001 mm (roughly the tolerance implicit in THERM). (Default: None).

• angle_tolerance – The max angle difference in degrees that vertices are allowed to differ from one another in order to consider them colinear. Zero indicates that no angle tolerance checks should be performed. (Default: 1.0).

Properties:

• identifier

• display_name

• units

• tolerance

• angle_tolerance

• shapes

• boundaries

• shape_area

• boundary_length

• min

• max

• center

• user_data

ToString()

Overwrite .NET ToString.

add_boundaries(objs)

Add a list of Boundary objects to the model.

add_boundary(obj)

Add a Boundary object to the model.

add_model(other_model)

Add another Model object to this model.

add_shape(obj)

Add a Shape object to the model.

add_shapes(objs)

Add a list of Shape objects to the model.

boundaries_by_identifier(identifiers)

Get a list of Face objects in the model given the Face identifiers.

check_all(raise_exception=True, detailed=False, all_ext_checks=False)

Check all of the aspects of the Model for validation errors.

This includes basic geometry checks. Furthermore, all extension attributes will be checked assuming the extension Model properties have a check_all function.

Parameters:

• raise_exception – Boolean to note whether a ValueError should be raised if any Model errors are found. If False, this method will simply return a text string with all errors that were found. (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).

• all_ext_checks – Boolean to note whether every single check that is available for all installed extensions should be run (True) or only generic checks that cover all except the most limiting of cases should be run (False). Examples of checks that are skipped include DOE2’s lack of support for courtyards and floor plates with holes. (Default: False).

Returns:

A text string with all errors that were found or a list if detailed is True. This string (or list) will be empty if no errors were found.

check_all_duplicate_identifiers(raise_exception=True, detailed=False)

Check that there are no duplicate identifiers for any geometry objects.

This includes Shapes and Boundaries.

Parameters:

• raise_exception – Boolean to note whether a ValueError should be raised if any Model errors are found. If False, this method will simply return a text string with all errors that were found. (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 text string with all errors that were found or a list if detailed is True. This string (or list) will be empty if no errors were found.

check_duplicate_boundary_identifiers(raise_exception=True, detailed=False)

Check that there are no duplicate Boundary identifiers in the model.

Parameters:

• raise_exception – Boolean to note whether a ValueError should be raised if duplicate identifiers are found. (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.

check_duplicate_shape_identifiers(raise_exception=True, detailed=False)

Check that there are no duplicate Shape identifiers in the model.

Parameters:

• raise_exception – Boolean to note whether a ValueError should be raised if duplicate identifiers are found. (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.

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

Check that all of the Model’s geometry components are planar.

This includes all of the Model’s Shapes and Boundaries.

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. If None, the Model tolerance will be used. (Default: None).

• 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=None, raise_exception=True, detailed=False)

Check that no edges of the Model’s geometry components self-intersect.

This includes all of the Model’s Shapes.

Parameters:

• tolerance – The minimum difference between the coordinate values of two vertices at which they can be considered equivalent. If None, the Model tolerance will be used. (Default: None).

• raise_exception – If True, a ValueError will be raised if an object intersects with itself (like a bowtie). (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.

convert_to_units(units='Millimeters')

Convert all of the geometry in this model to certain units.

This involves scaling the geometry, scaling the Model tolerance, and changing the Model’s units property.

Parameters:

units –

Text for the units to which the Model geometry should be converted. Default: Millimeters. Choose from the following:

• Millimeters

• Inches

• Centimeters

• Meters

• Feet

duplicate()

Get a copy of this object.

classmethod from_dict(data)

Initialize a Model from a dictionary.

Parameters:

data – A dictionary representation of a Model object.

classmethod from_ffjson(ffjson_file)

Initialize a Model from a FFJSON file.

Parameters:

ffjson_file – Path to FFJSON file.

classmethod from_ffpkl(ffpkl_file)

Initialize a Model from a FFpkl file.

Parameters:

ffpkl_file – Path to FFpkl file.

classmethod from_file(hb_file)

Initialize a Model from a FFJSON or FFpkl file, auto-sensing the type.

Parameters:

hb_file – Path to either a FFJSON or FFpkl file.

classmethod from_layers(thicknesses, height=200, base_plane=None, units='Millimeters', tolerance=None, angle_tolerance=1.0)

Initialize a Model from a list of any type of fairyfly-core geometry objects.

Parameters:

• thicknesses – A list of numbers for the thicknesses of each layer in the construction. The first thickness is the outer-most layer and the second thickness is the inner-most layer.

• height – A number for the height of the construction in the Y dimension.

• base_plane – An optional Plane object to set the origin of the model. If None, the world XY plane will be used. (Default: None).

• units –

  Text for the units system in which the model geometry exists. Default: ‘Millimeters’. Choose from the following:

  • Millimeters

  • Inches

  • Centimeters

  • Meters

  • Feet

• tolerance – The maximum difference between x, y, and z values at which vertices are considered equivalent. Zero indicates that no tolerance checks should be performed. None indicates that the tolerance will be set based on the units above, with the tolerance consistently being between 0.01 mm and 0.001 mm (roughly the tolerance implicit in THERM). (Default: None).

• angle_tolerance – The max angle difference in degrees that vertices are allowed to differ from one another in order to consider them colinear. Zero indicates that no angle tolerance checks should be performed. (Default: 1.0).

classmethod from_objects(objects, units='Millimeters', tolerance=None, angle_tolerance=1.0)

Initialize a Model from a list of any type of fairyfly-core geometry objects.

Parameters:

• objects – A list of fairyfly Shapes and Boundaries.

• units –

  Text for the units system in which the model geometry exists. Default: ‘Millimeters’. Choose from the following:

  • Millimeters

  • Inches

  • Centimeters

  • Meters

  • Feet

• tolerance – The maximum difference between x, y, and z values at which vertices are considered equivalent. Zero indicates that no tolerance checks should be performed. None indicates that the tolerance will be set based on the units above, with the tolerance consistently being between 0.01 mm and 0.001 mm (roughly the tolerance implicit in THERM). (Default: None).

• angle_tolerance – The max angle difference in degrees that vertices are allowed to differ from one another in order to consider them colinear. Zero indicates that no angle tolerance checks should be performed. (Default: 1.0).

move(moving_vec)

Move this Model along a vector.

Parameters:

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

reflect(plane)

Reflect this Model across a plane with the input normal vector and origin.

Parameters:

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

remove_boundaries(boundary_ids=None)

Remove Boundaries from the model.

Parameters:

boundary_ids – An optional list of Boundary identifiers to only remove certain boundaries from the model. If None, all Boundaries will be removed. (Default: None).

remove_degenerate_geometry(tolerance=None)

Remove any degenerate geometry from the model.

Degenerate geometry refers to any objects that evaluate to less than 3 vertices when duplicate and colinear vertices are removed at the tolerance.

Parameters:

tolerance – The minimum distance between a vertex and the boundary segments at which point the vertex is considered distinct. If None, the Model’s tolerance will be used. (Default: None).

remove_shapes(shape_ids=None)

Remove Shapes from the model.

Parameters:

shape_ids – An optional list of Shape identifiers to only remove certain shapes from the model. If None, all Shapes will be removed. (Default: None).

reset_coordinate_system(new_origin=None)

Set the origin of the coordinate system in which the model exists.

This is useful for resolving cases where the model geometry lies so far from the origin in its current coordinate system that it creates problems. For example, the float values of the coordinates are so high that floating point tolerance interferes with the proper representation of the model’s details.

Parameters:

new_origin – A Point3D in the model’s current coordinate system that will become the origin of the new coordinate system. If unspecified, the minimum of the bounding box around the model geometry will be used. (Default: None).

rotate(axis, angle, origin)

Rotate this Model 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 Model 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 Model by a factor from an origin point.

Note that using this method does NOT scale the model tolerance and, if it is desired that this tolerance be scaled with the model geometry, it must be scaled separately.

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

shapes_by_identifier(identifiers)

Get a list of Shape objects in the model given the Shape identifiers.

to_dict(included_prop=None, include_plane=True)

Return Model as a dictionary.

Parameters:

• 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 planes of the Face3Ds should be included in the output. This can preserve the orientation of the X/Y axes of the planes but is not required and can be removed to keep the dictionary smaller. (Default: True).

to_ffjson(name=None, folder=None, indent=None, included_prop=None)

Write Fairyfly model to FFJSON.

Parameters:

• name – A text string for the name of the FFJSON file. If None, the model identifier wil be used. (Default: None).

• folder – A text string for the directory where the FFJSON will be written. If unspecified, the default simulation folder will be used. This is usually at “C:UsersUSERNAMEsimulation.”

• indent – A positive integer to set the indentation used in the resulting FFJSON file. (Default: None).

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

to_ffpkl(name=None, folder=None, included_prop=None, triangulate_sub_faces=False)

Write Fairyfly model to compressed pickle file (FFpkl).

Parameters:

• name – A text string for the name of the pickle file. If None, the model identifier wil be used. (Default: None).

• folder – A text string for the directory where the pickle file will be written. If unspecified, the default simulation folder will be used. This is usually at “C:UsersUSERNAMEsimulation.”

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

static validate(model, check_function='check_all', check_args=None, json_output=False)

Get a string of a validation report given a specific check_function.

Parameters:

• model – A Fairyfly Model object for which validation will be performed. This can also be the file path to a FFJSON or a JSON string representation of a Fairyfly Model. These latter two options may be useful if the type of validation issue with the Model is one that prevents serialization.

• check_function – Text for the name of a check function on this Model that will be used to generate the validation report. For example, check_all or check_planar. (Default: check_all),

• check_args – An optional list of arguments to be passed to the check_function. If None, all default values for the arguments will be used. (Default: None).

• json_output – Boolean to note whether the output validation report should be formatted as a JSON object instead of plain text.

ERROR_MAP = {'200001': 'check_duplicate_identifiers', '200101': 'check_planar', '200102': 'check_self_intersecting', '200103': 'check_degenerate_shapes', '200201': 'check_all_in_same_plane'}

UNITS = ('Meters', 'Millimeters', 'Feet', 'Inches', 'Centimeters')

UNITS_TOLERANCES = {'Centimeters': 0.001, 'Feet': 1e-05, 'Inches': 0.0001, 'Meters': 1e-05, 'Millimeters': 0.01}

property angle_tolerance

Get or set a number for the max meaningful angle difference in degrees.

Face3D normal vectors differing by this amount are not considered parallel and Face3D segments that differ from 180 by this amount are not considered colinear. Zero indicates cases where no angle_tolerance checks should be performed.

property boundaries

Get a tuple of all Boundary objects in the model.

property boundary_length

Get the combined length of all boundaries in the Model.

property center

A Point3D for the center of the bounding box around the object.

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 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 max bounding box vertex in the world XY plane.

property min

Get a Point3D for the min bounding box vertex in the world XY plane.

property properties

Get object properties, including THERM and other properties.

property shape_area

Get the combined area of all shapes in the Model.

property shapes

Get a tuple of all Shape objects in the model.

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 to

Model writer object.

Use this method to access Writer class to write the model in other formats.

Usage:

model.to.therm(model) -> Therm XML element.
model.to.thmz(model) -> thmz file.

property tolerance

Get or set a number for the max meaningful difference between x, y, z values.

This value should be in the Model’s units. Zero indicates cases where no tolerance checks should be performed.

property units

Get or set Text for the units system in which the model geometry exists.

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)