honeybee-radiance 1.66.190__py3-none-any.whl

honeybee_radiance/dynamic/stategeo.py

@@ -0,0 +1,352 @@
+# coding: utf-8
+"""Dynamic geometry that can be assigned to individual states."""
+from ..modifier import Modifier
+from ..geometry import Polygon
+from ..mutil import dict_to_modifier  # imports all modifiers classes
+from ..lib.modifiers import black, generic_exterior_shade
+
+from honeybee.typing import valid_rad_string
+from ladybug_geometry.geometry3d.pointvector import Point3D
+from ladybug_geometry.geometry3d.face import Face3D
+
+import math
+
+
+class StateGeometry(object):
+    """A single planar geometry that can be assigned to Radiance states.
+
+    Args:
+        identifier: Text string for a unique geometry ID. Must not contain any
+            spaces or special characters.
+        geometry: A ladybug-geometry Face3D.
+        modifier: A Honeybee Radiance Modifier object for the geometry. If None,
+            it will be the Generic Exterior Shade modifier in the lib. (Default: None).
+
+    Properties:
+        * identifier
+        * display_name
+        * geometry
+        * modifier
+        * modifier_direct
+        * parent
+        * has_parent
+        * vertices
+        * normal
+        * center
+        * area
+    """
+    __slots__ = ('_identifier', '_display_name', '_geometry', '_modifier',
+                 '_modifier_direct', '_parent')
+
+    def __init__(self, identifier, geometry, modifier=None):
+        """Initialize StateGeometry."""
+        # process the identifier
+        self._identifier = valid_rad_string(identifier, 'state geometry identifier')
+        self._display_name = self._identifier
+        # process the geometry
+        assert isinstance(geometry, Face3D), \
+            'Expected ladybug_geometry Face3D. Got {}'.format(type(geometry))
+        self._geometry = geometry
+        # process the modifier
+        self.modifier = modifier
+        self._modifier_direct = None
+        self._parent = None  # _parent will be set when the Geo is added to a state
+
+    @classmethod
+    def from_dict(cls, data):
+        """Initialize a StateGeometry from a dictionary.
+
+        Note that the dictionary must be a non-abridged version for this
+        classmethod to work.
+
+        Args:
+            data: A dictionary representation of an StateGeometry with the
+                format below.
+
+        .. code-block:: python
+
+            {
+            'type': 'StateGeometry',
+            'identifier': str,  # Text for the unique object identifier
+            'display_name': str,  # Optional text for the display name
+            'geometry': {},  # A ladybug_geometry Face3D dictionary
+            'modifier': {},  # A Honeybee Radiance Modifier dictionary
+            'modifier_direct': {}  # A Honeybee Radiance Modifier dictionary
+            }
+        """
+        # check the type of dictionary
+        assert data['type'] == 'StateGeometry', 'Expected StateGeometry dictionary. ' \
+            'Got {}.'.format(data['type'])
+        geo = cls(data['identifier'], Face3D.from_dict(data['geometry']))
+
+        if 'modifier' in data and data['modifier'] is not None:
+            geo.modifier = dict_to_modifier(data['modifier'])
+        if 'modifier_direct' in data and data['modifier_direct'] is not None:
+            geo.modifier_direct = dict_to_modifier(data['modifier_direct'])
+        if 'display_name' in data and data['display_name'] is not None:
+            geo.display_name = data['display_name']
+        return geo
+
+    @classmethod
+    def from_dict_abridged(cls, data, modifiers):
+        """Create StateGeometry from an abridged dictionary.
+
+        Args:
+            data: A dictionary representation of StateGeometryAbridged 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': 'StateGeometryAbridged',
+            'identifier': str,  # Text for the unique object identifier
+            'display_name': str,  # Optional text for the display name
+            'geometry': {},  # A ladybug_geometry Face3D dictionary
+            'modifier': str  # A Honeybee Radiance Modifier identifier
+            'modifier_direct': str  # A Honeybee Radiance Modifier identifier
+            }
+        """
+        # check the type of dictionary
+        assert data['type'] == 'StateGeometryAbridged', \
+            'Expected StateGeometryAbridged dictionary. Got {}.'.format(data['type'])
+        geo = cls(data['identifier'], Face3D.from_dict(data['geometry']))
+
+        if 'modifier' in data and data['modifier'] is not None:
+            geo.modifier = modifiers[data['modifier']]
+        if 'modifier_direct' in data and data['modifier_direct'] is not None:
+            geo.modifier_direct = modifiers[data['modifier_direct']]
+        if 'display_name' in data and data['display_name'] is not None:
+            geo.display_name = data['display_name']
+        return geo
+
+    @classmethod
+    def from_vertices(cls, identifier, vertices, modifier=None):
+        """Create StateGeometry from vertices with each vertex as an iterable of 3 floats.
+
+        Note that this method is not recommended for a geometry with one or more holes
+        since the distinction between hole vertices and boundary vertices cannot
+        be derived from a single list of vertices.
+
+        Args:
+            identifier: Text string for a unique geometry ID. Must not contain any
+                spaces or special characters.
+            vertices: A flattened list of 3 or more vertices as (x, y, z).
+            modifier: A Honeybee Radiance Modifier object for the geometry. If None, it
+                will be the Generic Exterior Shade modifier in the lib. (Default: None).
+        """
+        geometry = Face3D(tuple(Point3D(*v) for v in vertices))
+        return cls(identifier, geometry, modifier)
+
+    @property
+    def identifier(self):
+        """Get a text string for the unique object identifer.
+    
+        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
+
+    @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.
+        """
+        return self._display_name
+
+    @display_name.setter
+    def display_name(self, value):
+        try:
+            self._display_name = str(value)
+        except UnicodeEncodeError:  # Python 2 machine lacking the character set
+            self._display_name = value  # keep it as unicode
+
+    @property
+    def geometry(self):
+        """Get a ladybug_geometry Face3D object representing the Shade."""
+        return self._geometry
+
+    @property
+    def modifier(self):
+        """Get or set the object modifier."""
+        if self._modifier:  # set by user
+            return self._modifier
+        return generic_exterior_shade
+
+    @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_direct(self):
+        """Get or set a modifier to be used in direct solar 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_direct:  # set by user
+            return self._modifier_direct
+        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_direct.setter
+    def modifier_direct(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_direct = value
+
+    @property
+    def is_opaque(self):
+        """Boolean noting whether this geomtry has an opaque modifier."""
+        return True if self.modifier.is_void else self.modifier.is_opaque
+
+    @property
+    def parent(self):
+        """Get the parent State if assigned. None if not assigned."""
+        return self._parent
+
+    @property
+    def has_parent(self):
+        """Get a boolean noting whether this StateGeometry has a parent State."""
+        return self._parent is not None
+
+    @property
+    def vertices(self):
+        """Get a list of vertices for the geometry (in counter-clockwise order)."""
+        return self._geometry.vertices
+
+    @property
+    def normal(self):
+        """Get a ladybug_geometry Vector3D for the direction the geometry is pointing.
+        """
+        return self._geometry.normal
+
+    @property
+    def center(self):
+        """Get a ladybug_geometry Point3D for the center of the geometry.
+
+        Note that this is the center of the bounding rectangle around this geometry
+        and not the area centroid.
+        """
+        return self._geometry.center
+
+    @property
+    def area(self):
+        """Get the area of the geometry."""
+        return self._geometry.area
+
+    def move(self, moving_vec):
+        """Move this StateGeometry along a vector.
+
+        Args:
+            moving_vec: A ladybug_geometry Vector3D with the direction and distance
+                to move the face.
+        """
+        self._geometry = self.geometry.move(moving_vec)
+
+    def rotate(self, axis, angle, origin):
+        """Rotate this StateGeometry by a certain angle around an axis and origin.
+
+        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.
+        """
+        self._geometry = self.geometry.rotate(axis, math.radians(angle), origin)
+
+    def rotate_xy(self, angle, origin):
+        """Rotate this StateGeometry counterclockwise in the XY plane by a certain angle.
+
+        Args:
+            angle: An angle in degrees.
+            origin: A ladybug_geometry Point3D for the origin around which the
+                object will be rotated.
+        """
+        self._geometry = self.geometry.rotate_xy(math.radians(angle), origin)
+
+    def reflect(self, plane):
+        """Reflect this StateGeometry across a plane.
+
+        Args:
+            plane: A ladybug_geometry Plane across which the object will
+                be reflected.
+        """
+        self._geometry = self.geometry.reflect(plane.n, plane.o)
+
+    def scale(self, factor, origin=None):
+        """Scale this StateGeometry by a factor from an origin point.
+
+        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).
+        """
+        self._geometry = self.geometry.scale(factor, origin)
+
+    def to_dict(self, abridged=False):
+        """Return StateGeometry 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.
+        """
+        # assign required properties
+        base = {'type': 'StateGeometryAbridged'} if abridged else \
+            {'type': 'StateGeometry'}
+        base['identifier'] = self.identifier
+        base['display_name'] = self.display_name
+        base['geometry'] = self.geometry.to_dict()
+
+        # assign optional properties
+        if self._modifier:
+            base['modifier'] = self._modifier.identifier if abridged else \
+                self._modifier.to_dict()
+        if self._modifier_direct is not None:
+            base['modifier_direct'] = self._modifier_direct.identifier if abridged \
+                else self._modifier.to_dict()
+        return base
+
+    def to_radiance(self, direct=False, minimal=False):
+        """Generate a RAD string representation of this StateGeometry.
+
+        Note that the resulting string lacks modifiers.
+
+        Args:
+            direct: Boolean to note whether to write the "direct" version of the
+                state, which will have the modifier_direct applied. (Default: False)
+            minimal: Boolean to note whether the radiance string should be written
+                in a minimal format (with spaces instead of line breaks). Default: False.
+        """
+        modifier = self.modifier_direct if direct else self.modifier
+        base_poly = Polygon(self.identifier, self.vertices, modifier)
+        return base_poly.to_radiance(minimal, False, False)
+
+    def duplicate(self):
+        """Get a copy of this object."""
+        return self.__copy__()
+
+    def __copy__(self):
+        new_geo = StateGeometry(self.identifier, self.geometry, self._modifier)
+        new_geo._modifier_direct = self._modifier_direct
+        new_geo._display_name = self.display_name
+        return new_geo
+
+    def ToString(self):
+        return self.__repr__()
+
+    def __repr__(self):
+        return 'StateGeometry: %s' % self.display_name

honeybee_radiance/geometry/__init__.py

@@ -0,0 +1,13 @@
+"""Radiance Geometries."""
+
+from .bubble import Bubble
+from .cone import Cone
+from .cup import Cup
+from .cylinder import Cylinder
+from .instance import Instance
+from .mesh import Mesh
+from .polygon import Polygon
+from .ring import Ring
+from .source import Source
+from .sphere import Sphere
+from .tube import Tube

honeybee_radiance/geometry/bubble.py

@@ -0,0 +1,42 @@
+"""Radiance Bubble.
+
+http://radsite.lbl.gov/radiance/refer/ray.html#Bubble
+"""
+from .sphere import Sphere
+
+
+class Bubble(Sphere):
+    """Radiance Bubble.
+
+    A bubble is simply a sphere whose surface normal points inward.
+
+    .. code-block:: shell
+
+        mod bubble id
+        0
+        0
+        4 xcent ycent zcent radius
+
+    Args:
+        identifier: Text string for a unique Geometry ID. Must not contain spaces
+            or special characters. This will be used to identify the object across
+            a model and in the exported Radiance files.
+        center_pt: Sphere center point as (x, y, z) (Default: (0, 0 ,0)).
+        radius: Bubble radius as a number (Default: 10).
+        modifier: Geometry modifier (Default: None).
+        dependencies: A list of primitives that this primitive depends on. This
+            argument is only useful for defining advanced primitives where the
+            primitive is defined based on other primitives. (Default: [])
+
+    Properties:
+        * identifier
+        * display_name
+        * center_pt
+        * radius
+        * modifier
+        * dependencies
+        * values
+    """
+    __slots__ = ()
+
+    pass

honeybee_radiance/geometry/cone.py

@@ -0,0 +1,215 @@
+"""Radiance Cone.
+
+http://radsite.lbl.gov/radiance/refer/ray.html#Cone
+"""
+from .geometrybase import Geometry
+import honeybee.typing as typing
+
+
+class Cone(Geometry):
+    """Radiance Cone.
+
+    A cone is a megaphone-shaped object. It is truncated by two planes perpendicular to
+    its axis, and one of its ends may come to a point. It is given as two axis endpoints,
+    and the starting and ending radii:
+
+    .. code-block:: shell
+
+        mod cone id
+        0
+        0
+        8
+                x0      y0      z0
+                x1      y1      z1
+                r0      r1
+
+    Args:
+        identifier: Text string for a unique Geometry ID. Must not contain spaces
+            or special characters. This will be used to identify the object across
+            a model and in the exported Radiance files.
+        center_pt_start: Cone start center point as (x, y, z) (Default: (0, 0 ,0)).
+        radius_start: Cone start radius as a number (Default: 10).
+        center_pt_end: Cone end center point as (x, y, z) (Default: (0, 0 ,10)).
+        radius_end: Cone end radius as a number (Default: 0).
+        modifier: Geometry modifier (Default: None).
+        dependencies: A list of primitives that this primitive depends on. This
+            argument is only useful for defining advanced primitives where the
+            primitive is defined based on other primitives. (Default: [])
+
+    Properties:
+        * identifier
+        * display_name
+        * center_pt_start
+        * radius_start
+        * center_pt_end
+        * radius_end
+        * values
+        * modifier
+        * dependencies
+
+    """
+    __slots__ = ('_center_pt_start', '_radius_start', '_center_pt_end', '_radius_end')
+
+    def __init__(self, identifier, center_pt_start=None, radius_start=10,
+                 center_pt_end=None, radius_end=0, modifier=None, dependencies=None):
+        """Radiance Cone."""
+        Geometry.__init__(self, identifier, modifier=modifier, dependencies=dependencies)
+        self.center_pt_start = center_pt_start or (0, 0, 0)
+        self.radius_start = radius_start if radius_start is not None else 10
+        self.center_pt_end = center_pt_end or (0, 0, 10)
+        self.radius_end = radius_end if radius_end is not None else 0
+        self._update_values()
+
+    def _update_values(self):
+        """update value dictionaries."""
+        self._values[2] = \
+            [self.center_pt_start[0], self.center_pt_start[1], self.center_pt_start[2],
+             self.center_pt_end[0], self.center_pt_end[1], self.center_pt_end[2],
+             self.radius_start, self.radius_end]
+
+    @property
+    def center_pt_start(self):
+        """Cone start center point as (x, y, z). Default is (0, 0 ,0)."""
+        return self._center_pt_start
+
+    @center_pt_start.setter
+    def center_pt_start(self, value):
+        self._center_pt_start = tuple(float(v) for v in value)
+        assert len(self._center_pt_start) == 3, \
+            'Radiance Cone center point must have 3 values for (x, y, z).'
+
+    @property
+    def radius_start(self):
+        """Cone start radius as a number. Default is 10."""
+        return self._radius_start
+
+    @radius_start.setter
+    def radius_start(self, value):
+        self._radius_start = typing.float_positive(value)
+
+    @property
+    def center_pt_end(self):
+        """Cone end center point as (x, y, z). Default is (0, 0 ,10)."""
+        return self._center_pt_end
+
+    @center_pt_end.setter
+    def center_pt_end(self, value):
+        self._center_pt_end = tuple(float(v) for v in value)
+        assert len(self._center_pt_end) == 3, \
+            'Radiance Cone center point must have 3 values for (x, y, z).'
+
+    @property
+    def radius_end(self):
+        """ Cone end radius as a number. Default is 0."""
+        return self._radius_end
+
+    @radius_end.setter
+    def radius_end(self, value):
+        self._radius_end = typing.float_positive(value)
+
+    @classmethod
+    def from_primitive_dict(cls, primitive_dict):
+        """Initialize a Cone from a primitive dict.
+
+        Args:
+            data: A dictionary in the format below.
+
+        .. code-block:: python
+
+            {
+            "modifier": {},  # primitive modifier (Default: None)
+            "type": "cone",  # primitive type
+            "identifier": "",  # primitive identifier
+            "display_name": "",  # primitive display name
+            "values": [],  # values
+            "dependencies": []
+            }
+        """
+        assert 'type' in primitive_dict, 'Input dictionary is missing "type".'
+        if primitive_dict['type'] != cls.__name__.lower():
+            raise ValueError(
+                'Type must be %s not %s.' % (cls.__name__.lower(), primitive_dict['type'])
+            )
+
+        modifier, dependencies = cls.filter_dict_input(primitive_dict)
+        values = primitive_dict['values'][2]
+
+        cls_ = cls(
+            identifier=primitive_dict['identifier'],
+            center_pt_start=values[0:3],
+            radius_start=values[6],
+            center_pt_end=values[3:6],
+            radius_end=values[7],
+            modifier=modifier,
+            dependencies=dependencies
+        )
+        if 'display_name' in primitive_dict and primitive_dict['display_name'] is not None:
+            cls_.display_name = primitive_dict['display_name']
+
+        # this might look redundant but it is NOT. see glass for explanation.
+        cls_.values = primitive_dict['values']
+        return cls_
+
+    @classmethod
+    def from_dict(cls, data):
+        """Initialize a Cone from a dictionary.
+
+        Args:
+            data: A dictionary in the format below.
+
+        .. code-block:: python
+
+            {
+            "type": "cone",  # Geometry type
+            "modifier": {} ,
+            "identifier": "",  # Geometry identifer
+            "display_name": "",  # Geometry display name
+            "center_pt_start": (0, 0, 0),
+            "radius_start": float,
+            "center_pt_end": (0, 0, 10),
+            "radius_end": float,
+            "dependencies": []
+            }
+        """
+        assert 'type' in data, 'Input dictionary is missing "type".'
+        if data['type'] != cls.__name__.lower():
+            raise ValueError(
+                'Type must be %s not %s.' % (cls.__name__.lower(),
+                    data['type'])
+            )
+        modifier, dependencies = cls.filter_dict_input(data)
+
+        new_obj = cls(identifier=data["identifier"],
+                      center_pt_start=(data["center_pt_start"]),
+                      radius_start=data["radius_start"],
+                      center_pt_end=( data["center_pt_end"]),
+                      radius_end=data["radius_end"],
+                      modifier=modifier,
+                      dependencies=dependencies)
+        if 'display_name' in data and data['display_name'] is not None:
+            new_obj.display_name = data['display_name']
+        return new_obj
+
+    def to_dict(self):
+        """Translate this object to a dictionary."""
+        base = {
+            "modifier": self.modifier.to_dict(),
+            "type": self.__class__.__name__.lower(),
+            "identifier": self.identifier,
+            "radius_start": self.radius_start,
+            "center_pt_start": self.center_pt_start,
+            "radius_end": self.radius_end,
+            "center_pt_end": self.center_pt_end,
+            'dependencies': [dp.to_dict() for dp in self.dependencies]
+        }
+        if self._display_name is not None:
+            base['display_name'] = self.display_name
+        return base
+
+    def __copy__(self):
+        mod, depend = self._dup_mod_and_depend()
+        new_obj = self.__class__(
+            self.identifier, self.center_pt_start, self.radius_start, self.center_pt_end,
+            self.radius_end, mod, depend)
+        new_obj._display_name = self._display_name
+        return new_obj

honeybee_radiance/geometry/cup.py

@@ -0,0 +1,54 @@
+"""Radiance Cup.
+
+http://radsite.lbl.gov/radiance/refer/ray.html#Cup
+"""
+from .cone import Cone
+
+
+class Cup(Cone):
+    """Radiance Cup.
+
+    A cup is an inverted cone (i.e., has an inward surface normal).
+
+    A cone is a megaphone-shaped object. It is truncated by two planes perpendicular to
+    its axis, and one of its ends may come to a point. It is given as two axis endpoints,
+    and the starting and ending radii:
+
+    .. code-block:: shell
+
+        mod cup id
+        0
+        0
+        8
+                x0      y0      z0
+                x1      y1      z1
+                r0      r1
+
+    Args:
+        identifier: Text string for a unique Geometry ID. Must not contain spaces
+            or special characters. This will be used to identify the object across
+            a model and in the exported Radiance files.
+        center_pt_start: Cup start center point as (x, y, z) (Default: (0, 0 ,0)).
+        radius_start: Cup start radius as a number (Default: 10).
+        center_pt_end: Cup end center point as (x, y, z) (Default: (0, 0 ,10)).
+        radius_end: Cup end radius as a number (Default: 0).
+        modifier: Geometry modifier (Default: None).
+        dependencies: A list of primitives that this primitive depends on. This
+            argument is only useful for defining advanced primitives where the
+            primitive is defined based on other primitives. (Default: [])
+
+
+    Properties:
+        * identifier
+        * display_name
+        * center_pt_start
+        * radius_start
+        * center_pt_end
+        * radius_end
+        * values
+        * modifier
+        * dependencies
+    """
+    __slots__ = ()
+
+    pass