honeybee-core 1.64.12__py3-none-any.whl

honeybee/__init__.py

@@ -0,0 +1,23 @@
+"""Honeybee core library."""
+import importlib
+import pkgutil
+import sys
+
+from honeybee.logutil import get_logger
+
+
+logger = get_logger(__name__)
+
+#  find and import honeybee extensions
+#  this is a critical step to add additional functionalities to honeybee core library.
+extensions = {}
+for finder, name, ispkg in pkgutil.iter_modules():
+    if not name.startswith('honeybee_') or name.count('_') > 1:
+        continue
+    try:
+        extensions[name] = importlib.import_module(name)
+    except Exception:
+        if (sys.version_info >= (3, 0)):
+            logger.exception('Failed to import {0}!'.format(name))
+    else:
+        logger.info('Successfully imported Honeybee plugin: {}'.format(name))

honeybee/__main__.py

@@ -0,0 +1,4 @@
+from honeybee.cli import main
+
+if __name__ == '__main__':
+    main()

honeybee/_base.py

@@ -0,0 +1,331 @@
+# coding: utf-8
+"""Base class for all geometry objects."""
+from ladybug_geometry.geometry3d.pointvector import Point3D
+
+from .typing import valid_string
+
+
+class _Base(object):
+    """A base class for all geometry objects.
+
+    Args:
+        identifier: Text string for a unique object ID. Must be < 100 characters and
+            not contain any spaces or special characters.
+
+    Properties:
+        * identifier
+        * display_name
+        * full_id
+        * user_data
+    """
+    __slots__ = ('_identifier', '_display_name', '_properties', '_user_data')
+
+    def __init__(self, identifier):
+        """Initialize base object."""
+        self.identifier = identifier
+        self._display_name = None
+        self._properties = None
+        self._user_data = None
+
+    @property
+    def identifier(self):
+        """Get or set a text string for the unique object identifier.
+
+        This identifier remains constant as the object is mutated, copied, and
+        serialized to different formats (eg. dict, idf, rad). As such, this
+        property is used to reference the object across a Model.
+        """
+        return self._identifier
+
+    @identifier.setter
+    def identifier(self, value):
+        self._identifier = valid_string(value, 'honeybee object identifier')
+
+    @property
+    def display_name(self):
+        """Get or set a string for the object name without any character restrictions.
+
+        If not set, this will be equal to the identifier.
+        """
+        if self._display_name is None:
+            return self._identifier
+        return self._display_name
+
+    @display_name.setter
+    def display_name(self, value):
+        if value is not None:
+            try:
+                value = str(value)
+            except UnicodeEncodeError:  # Python 2 machine lacking the character set
+                pass  # keep it as unicode
+        self._display_name = value
+
+    @property
+    def full_id(self):
+        """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.
+        """
+        if self._display_name is None:
+            return self._identifier
+        else:
+            return '{}[{}]'.format(self._display_name, self._identifier)
+
+    @property
+    def properties(self):
+        """Get object properties, including Radiance, Energy and other properties."""
+        return self._properties
+
+    @property
+    def user_data(self):
+        """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)
+        """
+        return self._user_data
+
+    @user_data.setter
+    def user_data(self, value):
+        if value is not None:
+            assert isinstance(value, dict), 'Expected dictionary for honeybee ' \
+                'object user_data. Got {}.'.format(type(value))
+        self._user_data = value
+
+    def duplicate(self):
+        """Get a copy of this object."""
+        return self.__copy__()
+
+    def display_dict(self):
+        """Get a list of DisplayFace3D dictionaries for visualizing the object."""
+        return []
+
+    def _changed_dict(self, other_object, tolerance):
+        """Get a dictionary reporting changes between this object and another.
+
+        Args:
+            other_object: Another object of the same type to be compared to this one.
+            tolerance: The tolerance to be used in checking whether the geometry
+                has been changed.
+
+        Returns:
+            A dictionary with a report of differences. This will be None if there
+            are no differences detected between this object and the other object.
+        """
+        # check whether each type of property has changed
+        geo_changed = not other_object.is_geo_equivalent(self, tolerance)
+        meta_changed = other_object.properties.is_equivalent(self.properties)
+        if not geo_changed and all(meta_changed.values()):
+            return None
+        # establish the base dictionary
+        base_dict = {
+            'type': 'ChangedObject',
+            'element_type': self.__class__.__name__,
+            'element_id': self.identifier,
+            'element_name': self.display_name,
+            'geometry_changed': geo_changed
+        }
+        # add booleans for whether metadata changed
+        for atr, equiv in meta_changed.items():
+            base_dict['{}_changed'.format(atr)] = not equiv
+        # add a representation of the geometry if it has changed
+        base_dict['geometry'] = other_object.display_dict()
+        if geo_changed:
+            base_dict['existing_geometry'] = self.display_dict()
+        return base_dict
+
+    def _base_report_dict(self, dict_type='AddedObject'):
+        """Get a dictionary reporting the object as an addition/deletion to/from a Model.
+        """
+        return {
+            'type': dict_type,
+            'element_type': self.__class__.__name__,
+            'element_id': self.identifier,
+            'element_name': self.display_name,
+            'geometry': self.display_dict()
+        }
+
+    def _validation_message(
+            self, message, raise_exception=True, detailed=False,
+            code='000000', extension='Core', error_type='Unknown Error'):
+        """Handle a validation error message given various options.
+
+        Args:
+            message: Text for the error message.
+            raise_exception: Boolean to note whether an ValueError should be
+                raised with the message. (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).
+            code: Text for the error code. (Default: 000000).
+            extension: Text for the name of the Honeybee extension for which duplicate
+                identifiers are being evaluated. (Default: Core).
+            error_type: Text for the type of error. This should be directly linked
+                to the error code and should simply be a human-readable version of
+                the error code. (Default: Unknown Error).
+
+        Returns:
+            A string with the message or a list with a dictionary if detailed is True.
+        """
+        # first check whether an exception should be raised or the message returned
+        if raise_exception:
+            raise ValueError(message)
+        if not detailed:
+            return message
+        # if not, then assemble a dictionary with detailed error information
+        error_dict = {
+            'type': 'ValidationError',
+            'code': code,
+            'error_type': error_type,
+            'extension_type': extension,
+            'element_type': self.__class__.__name__,
+            'element_id': [self.identifier],
+            'element_name': [self.display_name],
+            'message': message
+        }
+        # add parents to the error dictionary if they exist
+        if getattr(self, '_parent', None) is not None:
+            parents = []
+            rel_obj = self
+            while getattr(rel_obj, '_parent', None) is not None:
+                rel_obj = getattr(rel_obj, '_parent')
+                par_dict = {
+                    'parent_type': rel_obj.__class__.__name__,
+                    'id': rel_obj.identifier,
+                    'name': rel_obj.display_name
+                }
+                parents.append(par_dict)
+            error_dict['parents'] = [parents]
+        return [error_dict]
+
+    def _top_parent(self):
+        """Get the highest parent object that this object is a part of."""
+        if getattr(self, '_parent', None) is not None:
+            rel_obj = self
+            while getattr(rel_obj, '_parent', None) is not None:
+                rel_obj = getattr(rel_obj, '_parent')
+            return rel_obj
+
+    @staticmethod
+    def _validation_message_child(
+            message, child_obj, detailed=False, code='000000', extension='Core',
+            error_type='Unknown Error'):
+        """Process a validation error message of a child object.
+
+        Args:
+            message: Text for the error message.
+            child_obj: The child object instance for which the error message is for.
+            detailed: Boolean for whether the returned object is a detailed list of
+                dicts with error info or a string with a message. (Default: False).
+            code: Text for the error code. (Default: 000000).
+            extension: Text for the name of the Honeybee extension for which duplicate
+                identifiers are being evaluated. (Default: Core).
+            error_type: Text for the type of error. This should be directly linked
+                to the error code and should simply be a human-readable version of
+                the error code. (Default: Unknown Error).
+
+        Returns:
+            A string with the message or a dictionary if detailed is True.
+        """
+        # first check whether an exception should be raised or the message returned
+        if not detailed:
+            return message
+        # if not, then assemble a dictionary with detailed error information
+        error_dict = {
+            'type': 'ValidationError',
+            'code': code,
+            'error_type': error_type,
+            'extension_type': extension,
+            'element_type': child_obj.__class__.__name__,
+            'element_id': [child_obj.identifier],
+            'element_name': [child_obj.display_name],
+            'message': message
+        }
+        # add parents to the error dictionary
+        parents = []
+        rel_obj = child_obj
+        while getattr(rel_obj, '_parent', None) is not None:
+            rel_obj = getattr(rel_obj, '_parent')
+            par_dict = {
+                'parent_type': rel_obj.__class__.__name__,
+                'id': rel_obj.identifier,
+                'name': rel_obj.display_name
+            }
+            parents.append(par_dict)
+        error_dict['parents'] = [parents]
+        return error_dict
+
+    @staticmethod
+    def _from_dict_error_message(obj_dict, exception_obj):
+        """Give an error message when the object serialization from_dict fails.
+
+        This error message will include the identifier if it exists in the dict.
+
+        Args:
+            obj_dict: The objection dictionary that failed serialization.
+            exception_obj: The exception object to be included in the message.
+        """
+        obj_name = obj_dict['type'] if 'type' in obj_dict else 'Honeybee object'
+        full_id = ''
+        if 'identifier' in obj_dict and obj_dict['identifier'] is not None:
+            full_id = '{}[{}]'.format(obj_dict['display_name'], obj_dict['identifier']) \
+                if 'display_name' in obj_dict and obj_dict['display_name'] is not None \
+                else obj_dict['identifier']
+        msg = '{} "{}" is not valid and is not following honeybee-schema:\n{}'.format(
+            obj_name, full_id, exception_obj)
+        raise ValueError(msg)
+
+    @staticmethod
+    def _display_face(face3d, color):
+        """Create a DisplayFace3D dictionary from a Face3D and color."""
+        return {
+            'type': 'DisplayFace3D',
+            'geometry': face3d.to_dict(),
+            'color': color.to_dict(),
+            'display_mode': 'SurfaceWithEdges'
+        }
+
+    @staticmethod
+    def _calculate_min(geometry_objects):
+        """Calculate min Point3D around an array of geometry with min attributes."""
+        first_obj = geometry_objects[0]
+        min_pt = [first_obj.min.x, first_obj.min.y, first_obj.min.z]
+        for obj in geometry_objects[1:]:
+            if obj.min.x < min_pt[0]:
+                min_pt[0] = obj.min.x
+            if obj.min.y < min_pt[1]:
+                min_pt[1] = obj.min.y
+            if obj.min.z < min_pt[2]:
+                min_pt[2] = obj.min.z
+        return Point3D(*min_pt)
+
+    @staticmethod
+    def _calculate_max(geometry_objects):
+        """Calculate max Point3D around an array of geometry with max attributes."""
+        first_obj = geometry_objects[0]
+        max_pt = [first_obj.max.x, first_obj.max.y, first_obj.max.z]
+        for obj in geometry_objects[1:]:
+            if obj.max.x > max_pt[0]:
+                max_pt[0] = obj.max.x
+            if obj.max.y > max_pt[1]:
+                max_pt[1] = obj.max.y
+            if obj.max.z > max_pt[2]:
+                max_pt[2] = obj.max.z
+        return Point3D(*max_pt)
+
+    def __copy__(self):
+        new_obj = self.__class__(self.identifier)
+        new_obj._display_name = self._display_name
+        new_obj._user_data = None if self.user_data is None else self.user_data.copy()
+        return new_obj
+
+    def ToString(self):
+        """Overwrite .NET ToString."""
+        return self.__repr__()
+
+    def __repr__(self):
+        return 'Honeybee Base Object: %s' % self.display_name

honeybee/_basewithshade.py

@@ -0,0 +1,310 @@
+# coding: utf-8
+"""Base class for all geometry objects that can have shades as children."""
+from ._base import _Base
+from .shade import Shade
+from .typing import invalid_dict_error
+
+
+class _BaseWithShade(_Base):
+    """A base class for all objects that can have Shades nested on them.
+
+    Args:
+        identifier: Text string for a unique object ID. Must be < 100 characters and
+            not contain any spaces or special characters.
+
+    Properties:
+        * identifier
+        * display_name
+        * geometry
+        * outdoor_shades
+        * indoor_shades
+        * shades
+    """
+    __slots__ = ('_outdoor_shades', '_indoor_shades')
+
+    def __init__(self, identifier):
+        """Initialize base with shade object."""
+        _Base.__init__(self, identifier)  # process the identifier
+        self._outdoor_shades = []
+        self._indoor_shades = []
+
+    @property
+    def outdoor_shades(self):
+        """Get an array of all outdoor shades assigned to this object."""
+        return tuple(self._outdoor_shades)
+
+    @property
+    def indoor_shades(self):
+        """Get an array of all indoor shades assigned to this object."""
+        return tuple(self._indoor_shades)
+
+    @property
+    def shades(self):
+        """Get an array of all shades (indoor + outdoor) assigned to this object."""
+        return self._outdoor_shades + self._indoor_shades
+
+    def remove_shades(self):
+        """Remove all indoor and outdoor shades assigned to this object."""
+        self.remove_indoor_shades()
+        self.remove_outdoor_shades()
+
+    def remove_outdoor_shades(self):
+        """Remove all outdoor shades assigned to this object."""
+        for shade in self._outdoor_shades:
+            shade._parent = None
+        self._outdoor_shades = []
+
+    def remove_indoor_shades(self):
+        """Remove all indoor shades assigned to this object."""
+        for shade in self._indoor_shades:
+            shade._parent = None
+            shade._is_indoor = False
+        self._indoor_shades = []
+
+    def add_outdoor_shade(self, shade):
+        """Add a Shade object to the outdoors of this object.
+
+        Outdoor Shade objects can be used to represent balconies, outdoor furniture,
+        overhangs, light shelves, fins, the exterior part of mullions, etc.
+        For representing larger shade objects like trees or other buildings,
+        it may be more appropriate to add them to the Model as orphaned_shades
+        without a specific parent object.
+
+        Args:
+            shade: A Shade object to add to the outdoors of this object.
+        """
+        assert isinstance(shade, Shade), \
+            'Expected Shade for outdoor_shade. Got {}.'.format(type(shade))
+        assert shade.parent is None, 'Shade cannot have more than one parent object.'
+        shade._parent = self
+        shade._is_detached = False
+        self._outdoor_shades.append(shade)
+
+    def add_indoor_shade(self, shade):
+        """Add a Shade object to be added to the indoors of this object.
+
+        Indoor Shade objects can be used to represent furniture, the interior
+        portion of light shelves, the interior part of mullions, etc.
+        For representing finely detailed objects like blinds or roller shades,
+        it may be more appropriate to model them as materials assigned to
+        Aperture properties (like Radiance materials or Energy constructions).
+
+        Args:
+            shade: A Shade object to add to the indoors of this object.
+        """
+        assert isinstance(shade, Shade), \
+            'Expected Shade for indoor_shade. Got {}.'.format(type(shade))
+        assert shade.parent is None, 'Shade cannot have more than one parent object.'
+        shade._parent = self
+        shade._is_detached = False
+        shade._is_indoor = True
+        self._indoor_shades.append(shade)
+
+    def add_outdoor_shades(self, shades):
+        """Add a list of Shade objects to the outdoors of this object.
+
+        Args:
+            shades: A list of Shade objects to add to the outdoors of this object.
+        """
+        for shade in shades:
+            self.add_outdoor_shade(shade)
+
+    def add_indoor_shades(self, shades):
+        """Add a list of Shade objects to the indoors of this object.
+
+        Args:
+            shades: A list of Shade objects to add to the indoors of this object.
+        """
+        for shade in shades:
+            self.add_indoor_shade(shade)
+
+    def move_shades(self, moving_vec):
+        """Move all indoor and outdoor shades assigned to this object along a vector.
+
+        Args:
+            moving_vec: A ladybug_geometry Vector3D with the direction and distance
+                to move the shades.
+        """
+        for oshd in self._outdoor_shades:
+            oshd.move(moving_vec)
+        for ishd in self._indoor_shades:
+            ishd.move(moving_vec)
+
+    def rotate_shades(self, axis, angle, origin):
+        """Rotate all indoor and outdoor shades assigned to this object.
+
+        Args:
+            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.
+        """
+        for oshd in self._outdoor_shades:
+            oshd.rotate(axis, angle, origin)
+        for ishd in self._indoor_shades:
+            ishd.rotate(axis, angle, origin)
+
+    def rotate_xy_shades(self, angle, origin):
+        """Rotate all indoor and outdoor shades counterclockwise in the world XY plane.
+
+        Args:
+            angle: An angle in degrees.
+            origin: A ladybug_geometry Point3D for the origin around which the
+                object will be rotated.
+        """
+        for oshd in self._outdoor_shades:
+            oshd.rotate_xy(angle, origin)
+        for ishd in self._indoor_shades:
+            ishd.rotate_xy(angle, origin)
+
+    def reflect_shades(self, plane):
+        """Reflect all indoor and outdoor shades assigned to this object across a plane.
+
+        Args:
+            plane: A ladybug_geometry Plane across which the object will
+                be reflected.
+        """
+        for oshd in self._outdoor_shades:
+            oshd.reflect(plane)
+        for ishd in self._indoor_shades:
+            ishd.reflect(plane)
+
+    def scale_shades(self, factor, origin=None):
+        """Scale all indoor and outdoor shades assigned to this object by a factor.
+
+        Args:
+            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).
+        """
+        for oshd in self._outdoor_shades:
+            oshd.scale(factor, origin)
+        for ishd in self._indoor_shades:
+            ishd.scale(factor, origin)
+
+    def _add_prefix_shades(self, prefix):
+        """Change the name of all child shades by inserting a prefix.
+
+        Args:
+            prefix: Text that will be inserted at the start of this shades' name
+                and display_name.
+        """
+        for shade in self._outdoor_shades:
+            shade.add_prefix(prefix)
+        for shade in self._indoor_shades:
+            shade.add_prefix(prefix)
+
+    def _check_planar_shades(self, tolerance, detailed=False):
+        """Check that all of the child shades are planar."""
+        msgs = []
+        for oshd in self._outdoor_shades:
+            msgs.append(oshd.check_planar(tolerance, False, detailed))
+        for ishd in self._indoor_shades:
+            msgs.append(ishd.check_planar(tolerance, False, detailed))
+        flat_msgs = [m for m in msgs if m]
+        return flat_msgs if detailed else '\n'.join(flat_msgs)
+
+    def _check_self_intersecting_shades(self, tolerance, detailed=False):
+        """Check that no edges of the indoor or outdoor shades self-intersect."""
+        msgs = []
+        for oshd in self._outdoor_shades:
+            msgs.append(oshd.check_self_intersecting(tolerance, False, detailed))
+        for ishd in self._indoor_shades:
+            msgs.append(ishd.check_self_intersecting(tolerance, False, detailed))
+        flat_msgs = [m for m in msgs if m]
+        return flat_msgs if detailed else '\n'.join(flat_msgs)
+
+    def _add_shades_to_dict(
+            self, base, abridged=False, included_prop=None, include_plane=True):
+        """Method used to add child shades to the parent base dictionary.
+
+        Args:
+            base: The base object dictionary to which the child shades will be added.
+            abridged: Boolean to note whether the extension properties of the
+                object 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 ['energy'] will include 'energy' 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).
+        """
+        if self._outdoor_shades != []:
+            base['outdoor_shades'] = [shd.to_dict(abridged, included_prop, include_plane)
+                                      for shd in self._outdoor_shades]
+        if self._indoor_shades != []:
+            base['indoor_shades'] = [shd.to_dict(abridged, included_prop, include_plane)
+                                     for shd in self._indoor_shades]
+
+    def _recover_shades_from_dict(self, data):
+        """Method used to recover shades from a dictionary.
+
+        Args:
+            data: The dictionary representation of this object to which shades will
+                be added from the dictionary.
+        """
+        if 'outdoor_shades' in data and data['outdoor_shades'] is not None:
+            for sh in data['outdoor_shades']:
+                try:
+                    oshd = Shade.from_dict(sh)
+                    oshd._parent = self
+                    self._outdoor_shades.append(oshd)
+                except Exception as e:
+                    invalid_dict_error(sh, e)
+        if 'indoor_shades' in data and data['indoor_shades'] is not None:
+            for sh in data['indoor_shades']:
+                try:
+                    ishd = Shade.from_dict(sh)
+                    ishd._parent = self
+                    ishd._is_indoor = True
+                    self._indoor_shades.append(ishd)
+                except Exception as e:
+                    invalid_dict_error(sh, e)
+
+    def _duplicate_child_shades(self, new_object):
+        """Add duplicated child shades to a duplicated new_object."""
+        new_object._outdoor_shades = [oshd.duplicate() for oshd in self._outdoor_shades]
+        new_object._indoor_shades = [ishd.duplicate() for ishd in self._indoor_shades]
+        for oshd in new_object._outdoor_shades:
+            oshd._parent = new_object
+        for ishd in new_object._indoor_shades:
+            ishd._parent = new_object
+            ishd._is_indoor = True
+
+    def _min_with_shades(self, geometry):
+        """Calculate min Point3D around this object's geometry and its shades."""
+        all_geo = self._outdoor_shades + self._indoor_shades
+        all_geo.append(geometry)
+        return self._calculate_min(all_geo)
+
+    def _max_with_shades(self, geometry):
+        """Calculate max Point3D around this object's geometry and its shades."""
+        all_geo = self._outdoor_shades + self._indoor_shades
+        all_geo.append(geometry)
+        return self._calculate_max(all_geo)
+
+    def _are_shades_equivalent(self, other, tolerance=0.01):
+        """Get a boolean for whether this object's shades are equivalent to another.
+
+        Args:
+            other: Another object for which shade 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 shades are equivalent. False if shades are not equivalent.
+        """
+        if len(self._outdoor_shades) != len(other._outdoor_shades):
+            return False
+        for f1, f2 in zip(self._outdoor_shades, other._outdoor_shades):
+            if not f1.is_geo_equivalent(f2, tolerance):
+                return False
+        if len(self._indoor_shades) != len(other._indoor_shades):
+            return False
+        for f1, f2 in zip(self._indoor_shades, other._indoor_shades):
+            if not f1.is_geo_equivalent(f2, tolerance):
+                return False
+        return True