honeybee-radiance 1.66.190__py3-none-any.whl

honeybee_radiance/properties/_base.py

@@ -0,0 +1,390 @@
+# coding=utf-8
+"""Base class of Radiance Properties for all planar geometry objects."""
+from ..modifier import Modifier
+from ..mutil import dict_to_modifier  # imports all modifiers classes
+from ..dynamic.state import _RadianceState
+from ..lib.modifiers import black
+
+from honeybee.typing import valid_rad_string
+from honeybee.checkdup import is_equivalent
+
+
+class _RadianceProperties(object):
+    """Base class of Radiance Properties for all planar geometry objects.
+
+    This includes (Face, Aperture, Door, Shade).
+
+    Args:
+        host: A honeybee_core object that hosts these properties.
+        modifier: A Honeybee Radiance Modifier for the object. If None,
+            it will be set by the parent Room ModifierSet or the Honeybee
+            default generic ModifierSet.
+        modifier_blk: A Honeybee Radiance Modifier to be used for this object
+            in direct solar simulations and in isolation studies (assessing
+            the contribution of individual Apertures).
+
+    Properties:
+        * host
+        * modifier
+        * modifier_blk
+        * is_opaque
+        * is_modifier_set_on_object
+        * is_blk_overridden
+    """
+
+    __slots__ = ('_host', '_modifier', '_modifier_blk')
+
+    def __init__(self, host, modifier=None, modifier_blk=None):
+        """Initialize GeometryRadianceProperties."""
+        self._host = host
+        self.modifier = modifier
+        self.modifier_blk = modifier_blk
+
+    @property
+    def host(self):
+        """Get the object hosting these properties."""
+        return self._host
+
+    @property
+    def modifier(self):
+        """Get or set the object modifier."""
+        return self._modifier
+
+    @modifier.setter
+    def modifier(self, value):
+        if value is not None:
+            assert isinstance(value, Modifier), \
+                'Expected Radiance Modifier for shade. Got {}'.format(type(value))
+            value.lock()  # lock editing in case modifier has multiple references
+        self._modifier = value
+
+    @property
+    def modifier_blk(self):
+        """Get or set a modifier to be used in direct solar and in isolation studies.
+
+        If None, this will be a completely black material if the object's modifier is
+        opaque and will be equal to the modifier if the object's modifier is non-opaque.
+        """
+        if self._modifier_blk:  # set by user
+            return self._modifier_blk
+        mod = self.modifier  # assign a default based on whether the modifier is opaque
+        if mod.is_void or mod.is_opaque:
+            return black
+        else:
+            return mod
+
+    @modifier_blk.setter
+    def modifier_blk(self, value):
+        if value is not None:
+            assert isinstance(value, Modifier), \
+                'Expected Radiance Modifier. Got {}'.format(type(value))
+            value.lock()  # lock editing in case modifier has multiple references
+        self._modifier_blk = value
+
+    @property
+    def is_opaque(self):
+        """Boolean noting whether this object has an opaque modifier.
+
+        This has repercussions for how this object is written into the Radiance
+        folder structure.
+        """
+        return True if self.modifier.is_void else self.modifier.is_opaque
+
+    @property
+    def is_modifier_set_on_object(self):
+        """Boolean noting if modifier is assigned on the level of this object.
+
+        This is opposed to having the modifier assigned by a ModifierSet.
+        """
+        return self._modifier is not None
+
+    @property
+    def is_blk_overridden(self):
+        """Boolean noting if modifier_blk has been overridden from default on this object.
+        """
+        return self._modifier is not None
+
+    def reset_to_default(self):
+        """Reset a Modifier assigned at the level of this Shade to the default.
+
+        This means that the Shade's modifier will be assigned by a ModifierSet instead.
+        """
+        self._modifier = None
+
+    def duplicate(self, new_host=None):
+        """Get a copy of this object.
+
+        new_host: A new object that hosts these properties.
+            If None, the properties will be duplicated with the same host.
+        """
+        _host = new_host or self._host
+        return self.__class__(_host, self._modifier, self._modifier_blk)
+
+    def is_equivalent(self, other):
+        """Check to see if these energy properties are equivalent to another object.
+
+        This will only be True if all properties match (except for the host) and
+        will otherwise be False.
+        """
+        if not is_equivalent(self._modifier, other._modifier):
+            return False
+        if not is_equivalent(self._modifier_blk, other._modifier_blk):
+            return False
+        return True
+
+    def _apply_modifiers_from_dict(self, abridged_data, modifiers):
+        """Apply modifiers from an Abridged dictionary.
+
+        Args:
+            abridged_data: An Abridged dictionary (typically coming from a Model).
+            modifiers: A dictionary of modifiers with modifier identifiers as keys,
+                which will be used to re-assign modifiers.
+        """
+        if 'modifier' in abridged_data and abridged_data['modifier'] is not None:
+            self.modifier = modifiers[abridged_data['modifier']]
+        if 'modifier_blk' in abridged_data and abridged_data['modifier_blk'] is not None:
+            self.modifier_blk = modifiers[abridged_data['modifier_blk']]
+
+    def _add_modifiers_to_dict(self, base, abridged=False):
+        """Add modifiers to a base dictionary.
+
+        Args:
+            base: A base dictionary to which modifiers will be added.
+            abridged: Boolean to note whether the full dictionary describing the
+                object should be returned (False) or just an abridged version (True).
+                Default: False.
+        """
+        if self._modifier is not None:
+            base['radiance']['modifier'] = self._modifier.identifier if \
+                abridged else self._modifier.to_dict()
+        if self._modifier_blk is not None:
+            base['radiance']['modifier_blk'] = self._modifier_blk.identifier if \
+                abridged else self._modifier_blk.to_dict()
+        return base
+
+    @staticmethod
+    def _restore_modifiers_from_dict(new_prop, data):
+        """Restore modifiers from a data dictionary to a new properties object."""
+        if 'modifier' in data and data['modifier'] is not None:
+            new_prop.modifier = dict_to_modifier(data['modifier'])
+        if 'modifier_blk' in data and data['modifier_blk'] is not None:
+            new_prop.modifier_blk = dict_to_modifier(data['modifier_blk'])
+        return new_prop
+
+    def ToString(self):
+        return self.__repr__()
+
+    def __repr__(self):
+        return 'Base Radiance Properties: [host: {}]'.format(self.host.display_name)
+
+
+class _DynamicRadianceProperties(_RadianceProperties):
+    """Base class of Radiance Properties for all planar geometry objects.
+
+    This includes Apertures and Shades.
+
+    Args:
+        host: A honeybee_core object that hosts these properties.
+        modifier: A Honeybee Radiance Modifier for the object. If None,
+            it will be set by the parent Room ModifierSet or the Honeybee
+            default generic ModifierSet.
+        modifier_blk: A Honeybee Radiance Modifier to be used for this object
+            in direct solar simulations and in isolation studies (assessing
+            the contribution of individual Apertures).
+        dynamic_group_identifier: An optional string to note the dynamic group
+            to which the object is a part of. Objects sharing the same
+            dynamic_group_identifier will have their states change in unison.
+            If None, the object is assumed to be static.
+
+    Properties:
+        * host
+        * modifier
+        * modifier_blk
+        * dynamic_group_identifier
+        * states
+        * state_count
+        * is_opaque
+        * is_modifier_set_on_object
+        * is_blk_overridden
+    """
+
+    __slots__ = ('_dynamic_group_identifier', '_states')
+
+    def __init__(self, host, modifier=None, modifier_blk=None,
+                 dynamic_group_identifier=None):
+        """Initialize radiance properties."""
+        _RadianceProperties.__init__(self, host, modifier, modifier_blk)
+        self._states = []
+        self.dynamic_group_identifier = dynamic_group_identifier
+
+    @property
+    def dynamic_group_identifier(self):
+        """Get or set a text string for the dynamic_group_identifier.
+
+        Objects sharing the same dynamic_group_identifier will have their
+        states change in unison. If None, the object is assumed to be static.
+        """
+        return self._dynamic_group_identifier
+
+    @dynamic_group_identifier.setter
+    def dynamic_group_identifier(self, identifier):
+        if identifier is not None:
+            identifier = valid_rad_string(identifier)
+        else:
+            assert len(self._states) == 0, 'dynamic_group_identifier cannot be ' \
+                'None while states are assigned. Use the remove_states method ' \
+                'before setting to None.'
+        self._dynamic_group_identifier = identifier
+
+    @property
+    def states(self):
+        """Get or set an array of radiance states assigned to this object.
+
+        These cannot be set unless there is also a dynamic_group_identifier for
+        the object.
+        """
+        return tuple(self._states)
+
+    @states.setter
+    def states(self, value):
+        if value is not None:
+            assert self._dynamic_group_identifier is not None, 'Object must have ' \
+                'a dynamic_group_identifier to assign states.'
+            try:
+                self._states = [self._check_state(st) for st in value]
+            except (ValueError, TypeError):
+                raise TypeError('Expected iterable for Object states. '
+                                'Got  {}.'.format(type(value)))
+        else:
+            self._states = []
+
+    @property
+    def state_count(self):
+        """Get an integer for the number of dynamic states assigned to the object."""
+        return len(self._states)
+
+    def remove_states(self):
+        """Remove all states assigned to this object."""
+        for state in self._states:
+            state._parent = None
+        self._states = []
+
+    def add_state(self, state):
+        """Add a Radiance state object to this object.
+
+        Args:
+            state: A Radiance state object to add to the this object.
+        """
+        assert self._dynamic_group_identifier is not None, 'Object must have ' \
+            'a dynamic_group_identifier to assign states.'
+        self._states.append(self._check_state(state))
+
+    def move(self, moving_vec):
+        """Move all state geometry along a vector.
+
+        Args:
+            moving_vec: A ladybug_geometry Vector3D with the direction and distance
+                to move the shades.
+        """
+        for state in self._states:
+            state.move(moving_vec)
+
+    def rotate(self, axis, angle, origin):
+        """Rotate all state geometry.
+
+        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 state in self._states:
+            state.rotate(axis, angle, origin)
+
+    def rotate_xy(self, angle, origin):
+        """Rotate all state geometry 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 state in self._states:
+            state.rotate_xy(angle, origin)
+
+    def reflect(self, plane):
+        """Reflect all state geometry across a plane.
+
+        Args:
+            plane: A ladybug_geometry Plane across which the object will
+                be reflected.
+        """
+        for state in self._states:
+            state.reflect(plane)
+
+    def scale(self, factor, origin=None):
+        """Scale all state geometry 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 state in self._states:
+            state.scale(factor, origin)
+
+    def duplicate(self, new_host=None):
+        """Get a copy of this object.
+
+        new_host: A new object that hosts these properties.
+            If None, the properties will be duplicated with the same host.
+        """
+        _host = new_host or self._host
+        new_prop = self.__class__(
+            _host, self._modifier, self._modifier_blk, self._dynamic_group_identifier)
+        new_prop._states = []
+        for st in self._states:
+            new_st = st.duplicate()
+            new_st._parent = _host
+            new_prop._states.append(new_st)
+        return new_prop
+
+    def is_equivalent(self, other):
+        """Check to see if these energy properties are equivalent to another object.
+
+        This will only be True if all properties match (except for the host) and
+        will otherwise be False.
+        """
+        if not is_equivalent(self._modifier, other._modifier):
+            return False
+        if not is_equivalent(self._modifier_blk, other._modifier_blk):
+            return False
+        if not is_equivalent(self._dynamic_group_identifier,
+                             other._dynamic_group_identifier):
+            return False
+        if not is_equivalent(self.state_count, other.state_count):
+            return False
+        return True
+
+    def _check_state(self, obj):
+        assert isinstance(obj, _RadianceState), \
+            'Expected RadianceState. Got {}.'.format(type(obj))
+        assert obj.parent is None, \
+            'RadianceState cannot already have a parent object.'
+        obj._parent = self.host
+        return obj
+
+    def _add_states_to_dict(self, base, abridged=False):
+        """Add states to a base dictionary.
+
+        Args:
+            base: A base dictionary to which states will be added.
+            abridged: Boolean to note whether the full dictionary describing the
+                object should be returned (False) or just an abridged version (True).
+                Default: False.
+        """
+        if self._dynamic_group_identifier is not None:
+            base['radiance']['dynamic_group_identifier'] = self.dynamic_group_identifier
+        if len(self._states) != 0:
+            base['radiance']['states'] = [st.to_dict(abridged) for st in self._states]
+        return base

honeybee_radiance/properties/aperture.py

@@ -0,0 +1,197 @@
+# coding=utf-8
+"""Aperture Radiance Properties."""
+from ._base import _DynamicRadianceProperties
+from ..modifier import Modifier
+from ..dynamic.state import RadianceSubFaceState
+from ..lib.modifiers import black
+from ..lib.modifiersets import generic_modifier_set_visible
+
+
+class ApertureRadianceProperties(_DynamicRadianceProperties):
+    """Radiance Properties for Honeybee Aperture.
+
+    Args:
+        host: A honeybee_core Aperture object that hosts these properties.
+        modifier: A Honeybee Radiance Modifier object for the aperture. If None,
+            it will be set by the parent Room ModifierSet or the Honeybee
+            default generic ModifierSet.
+        modifier_blk: A Honeybee Radiance Modifier object to be used for this
+            aperture in direct solar simulations and in isolation studies (assessing
+            the contribution of individual Apertures). If None, this will be
+            a completely black material.
+        dynamic_group_identifier: An optional string to note the dynamic group
+            to which the Aperture is a part of. Apertures sharing the same
+            dynamic_group_identifier will have their states change in unison.
+            If None, the Aperture is assumed to be static.
+
+    Properties:
+        * host
+        * modifier
+        * modifier_blk
+        * dynamic_group_identifier
+        * states
+        * state_count
+        * is_opaque
+        * is_modifier_set_on_object
+        * is_blk_overridden
+    """
+
+    __slots__ = ()
+
+    def __init__(self, host, modifier=None, modifier_blk=None,
+                 dynamic_group_identifier=None):
+        """Initialize Aperture radiance properties."""
+        _DynamicRadianceProperties.__init__(
+            self, host, modifier, modifier_blk, dynamic_group_identifier)
+
+    @property
+    def modifier(self):
+        """Get or set the Aperture modifier.
+
+        If the modifier is not set on the aperture-level, then it will be assigned
+        based on the ModifierSet assigned to the parent Room.  If there is no
+        parent Room or the parent Room's ModifierSet has no modifier for
+        the Aperture type and boundary_condition, it will be assigned using the
+        honeybee default generic ModifierSet.
+        """
+        if self._modifier:  # set by user
+            return self._modifier
+        elif self._host.has_parent and self._host.parent.has_parent:  # set by room
+            constr_set = self._host.parent.parent.properties.radiance.modifier_set
+            return constr_set.get_aperture_modifier(
+                self._host.boundary_condition.name, self._host.is_operable,
+                self._host.parent.type.name)
+        elif self._host.has_parent:  # generic but influenced by parent aperture
+            return generic_modifier_set_visible.get_aperture_modifier(
+                self._host.boundary_condition.name, self._host.is_operable,
+                self._host.parent.type.name)
+        else:
+            return generic_modifier_set_visible.get_aperture_modifier(
+                self._host.boundary_condition.name, self._host.is_operable, 'Wall')
+
+    @modifier.setter
+    def modifier(self, value):
+        if value is not None:
+            assert isinstance(value, Modifier), \
+                'Expected Radiance Modifier for aperture. Got {}'.format(type(value))
+            value.lock()  # lock editing in case modifier has multiple references
+        self._modifier = value
+
+    @property
+    def modifier_blk(self):
+        """Get or set a modifier to be used in direct solar and in isolation studies.
+
+        If None, this will be a completely black material.
+        """
+        if self._modifier_blk:  # set by user
+            return self._modifier_blk
+        return black
+
+    @modifier_blk.setter
+    def modifier_blk(self, value):
+        if value is not None:
+            assert isinstance(value, Modifier), \
+                'Expected Radiance Modifier for aperture. Got {}'.format(type(value))
+            value.lock()  # lock editing in case modifier has multiple references
+        self._modifier_blk = value
+
+    @classmethod
+    def from_dict(cls, data, host):
+        """Create ApertureRadianceProperties from a dictionary.
+
+        Note that the dictionary must be a non-abridged version for this
+        classmethod to work.
+
+        Args:
+            data: A dictionary representation of ApertureRadianceProperties with the
+                format below.
+            host: A Aperture object that hosts these properties.
+
+        .. code-block:: python
+
+            {
+            'type': 'ApertureRadianceProperties',
+            'modifier': {},  # A Honeybee Radiance Modifier dictionary
+            'modifier_blk': {},  # A Honeybee Radiance Modifier dictionary
+            'dynamic_group_identifier': str,  # An optional dynamic group identifier
+            'states': []  # An optional list of states
+            }
+        """
+        assert data['type'] == 'ApertureRadianceProperties', \
+            'Expected ApertureRadianceProperties. Got {}.'.format(data['type'])
+        new_prop = cls(host)
+        new_prop = cls._restore_modifiers_from_dict(new_prop, data)
+        return cls._restore_states_from_dict(new_prop, data)
+
+    def apply_properties_from_dict(self, abridged_data, modifiers):
+        """Apply properties from a ApertureRadiancePropertiesAbridged dictionary.
+
+        Args:
+            abridged_data: A ApertureRadiancePropertiesAbridged dictionary (typically
+                coming from a Model) with the format below.
+            modifiers: A dictionary of modifiers with modifier identifiers as keys,
+                which will be used to re-assign modifiers.
+
+        .. code-block:: python
+
+            {
+            'type': 'ApertureRadiancePropertiesAbridged',
+            'modifier': str,  # A Honeybee Radiance Modifier identifier
+            'modifier_blk': str,  # A Honeybee Radiance Modifier identifier
+            'dynamic_group_identifier': str,  # An optional dynamic group identifier
+            'states': []  # An optional list of states
+            }
+        """
+        self._apply_modifiers_from_dict(abridged_data, modifiers)
+        self._apply_states_from_dict(abridged_data, modifiers)
+
+    def to_dict(self, abridged=False):
+        """Return radiance properties as a dictionary.
+
+        Args:
+            abridged: Boolean to note whether the full dictionary describing the
+                object should be returned (False) or just an abridged version (True).
+                Default: False.
+        """
+        base = {'radiance': {}}
+        base['radiance']['type'] = 'ApertureRadianceProperties' if not \
+            abridged else 'ApertureRadiancePropertiesAbridged'
+        self._add_modifiers_to_dict(base, abridged)
+        return self._add_states_to_dict(base, abridged)
+
+    def _check_state(self, obj):
+        assert isinstance(obj, RadianceSubFaceState), \
+            'Expected RadianceSubFaceState. Got {}.'.format(type(obj))
+        assert obj.parent is None, \
+            'RadianceSubFaceState cannot already have a parent object.'
+        obj._parent = self.host
+        return obj
+
+    def _apply_states_from_dict(self, abridged_data, modifiers):
+        """Apply statess from an Abridged dictionary.
+
+        Args:
+            abridged_data: An Abridged dictionary (typically coming from a Model).
+            modifiers: A dictionary of modifiers with modifier identifiers as keys,
+                which will be used to re-assign modifiers.
+        """
+        if 'dynamic_group_identifier' in abridged_data and \
+                abridged_data['dynamic_group_identifier'] is not None:
+            self.dynamic_group_identifier = abridged_data['dynamic_group_identifier']
+        if 'states' in abridged_data and abridged_data['states'] is not None:
+            self.states = [RadianceSubFaceState.from_dict_abridged(st, modifiers)
+                           for st in abridged_data['states']]
+
+    @staticmethod
+    def _restore_states_from_dict(new_prop, data):
+        """Restore states from a data dictionary to a new properties object."""
+        if 'dynamic_group_identifier' in data and \
+                data['dynamic_group_identifier'] is not None:
+            new_prop.dynamic_group_identifier = data['dynamic_group_identifier']
+        if 'states' in data and data['states'] is not None:
+            new_prop.states = [RadianceSubFaceState.from_dict(shd)
+                               for shd in data['states']]
+        return new_prop
+
+    def __repr__(self):
+        return 'Aperture Radiance Properties: [host: {}]'.format(self.host.display_name)