honeybee-radiance 1.66.190__py3-none-any.whl

honeybee_radiance/modifier/material/illum.py

@@ -0,0 +1,51 @@
+"""Radiance Illum Material.
+
+http://radsite.lbl.gov/radiance/refer/ray.html#Illum
+"""
+from .materialbase import Material
+
+
+# TODO: Implement the class. It's currently only a generic Radiance Primitive
+class Illum(Material):
+    """Radiance Illum Material.
+
+    Illum is used for secondary light sources with broad distributions. A secondary light
+    source is treated like any other light source, except when viewed directly. It then
+    acts like it is made of a different material (indicated by the string argument), or
+    becomes invisible (if no string argument is given, or the argument is "void").
+    Secondary sources are useful when modeling windows or brightly illuminated surfaces.
+
+    .. code-block:: shell
+
+        mod illum id
+        1 material
+        0
+        3 red green blue
+
+    Args:
+        identifier: Text string for a unique Material 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.
+        modifier: Modifier. It can be primitive, mixture, texture or pattern.
+            (Default: None).
+        values: An array 3 arrays for primitive data. Each of the 3 sub-arrays
+            refer to a line number in the radiance primitive definitions and the
+            values in each array correspond to values occurring within each line.
+        is_opaque: A boolean to indicate whether this primitive is opaque.
+        dependencies: A list of primitives that this primitive depends on. This
+            argument is only useful for defining advanced primitives that are
+            defined based on other primitives. (Default: []).
+
+    Properties:
+        * identifier
+        * display_name
+        * values
+        * modifier
+        * dependencies
+        * is_modifier
+        * is_material
+        * is_opaque
+    """
+    __slots__ = ()
+
+    pass

honeybee_radiance/modifier/material/interface.py

@@ -0,0 +1,49 @@
+"""Radiance Interface Material.
+
+http://radsite.lbl.gov/radiance/refer/ray.html#Interface
+"""
+from .materialbase import Material
+
+
+# TODO: Implement the class. It's currently only a generic Radiance Primitive
+class Interface(Material):
+    """Radiance Interface Material.
+
+    An interface is a boundary between two dielectrics. The first transmission
+    coefficient and refractive index are for the inside; the second ones are for the
+    outside. Ordinary dielectrics are surrounded by a vacuum (1 1 1 1).
+
+    .. code-block:: shell
+
+        mod interface id
+        0
+        0
+        8 rtn1 gtn1 btn1 n1 rtn2 gtn2 btn2 n2
+
+    Args:
+        identifier: Text string for a unique Material 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.
+        modifier: Modifier. It can be primitive, mixture, texture or pattern.
+            (Default: None).
+        values: An array 3 arrays for primitive data. Each of the 3 sub-arrays
+            refer to a line number in the radiance primitive definitions and the
+            values in each array correspond to values occurring within each line.
+        is_opaque: A boolean to indicate whether this primitive is opaque.
+        dependencies: A list of primitives that this primitive depends on. This
+            argument is only useful for defining advanced primitives that are
+            defined based on other primitives. (Default: []).
+
+    Properties:
+        * identifier
+        * display_name
+        * values
+        * modifier
+        * dependencies
+        * is_modifier
+        * is_material
+        * is_opaque
+    """
+    __slots__ = ()
+
+    pass

honeybee_radiance/modifier/material/light.py

@@ -0,0 +1,206 @@
+"""Radiance Light Material.
+
+http://radsite.lbl.gov/radiance/refer/ray.html#Light
+"""
+
+from .materialbase import Material
+import honeybee.typing as typing
+
+
+class Light(Material):
+    """Radiance Light material.
+
+    Args:
+        identifier: Text string for a unique Material 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.
+        r_emittance: A positive value for the Red channel of the light (Default: 0).
+        g_emittance: A positive value for the Green channel of the light (Default: 0).
+        b_emittance: A positive value for the Blue channel of the light (Default: 0).
+        modifier: Material 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
+        * r_emittance
+        * g_emittance
+        * b_emittance
+        * values
+        * modifier
+        * dependencies
+        * is_modifier
+        * is_material
+    """
+
+    __slots__ = ('_r_emittance', '_g_emittance', '_b_emittance')
+
+    def __init__(self, identifier, r_emittance=0, g_emittance=0, b_emittance=0,
+                 modifier=None, dependencies=None):
+        """Radiance Light material."""
+        Material.__init__(self, identifier, modifier=modifier,
+                          dependencies=dependencies)
+        self.r_emittance = r_emittance
+        self.g_emittance = g_emittance
+        self.b_emittance = b_emittance
+        self._update_values()
+
+    def _update_values(self):
+        "update value dictionaries."
+        self._values[2] = [self.r_emittance, self.g_emittance, self.b_emittance]
+
+    @property
+    def r_emittance(self):
+        """A positive value for the Red channel of the light.
+
+        The value must be positive (Default: 0).
+        """
+        return self._r_emittance
+
+    @r_emittance.setter
+    def r_emittance(self, value):
+        self._r_emittance = typing.float_positive(value)
+
+    @property
+    def g_emittance(self):
+        """A positive value for the Green channel of the light.
+
+        The value must be positive (Default: 0).
+        """
+        return self._g_emittance
+
+    @g_emittance.setter
+    def g_emittance(self, value):
+        self._g_emittance = typing.float_positive(value)
+
+    @property
+    def b_emittance(self):
+        """A positive value for the Blue channel of the light.
+
+        The value must be positive (Default: 0).
+        """
+        return self._b_emittance
+
+    @b_emittance.setter
+    def b_emittance(self, value):
+        self._b_emittance = typing.float_positive(value)
+
+    @classmethod
+    def from_single_value(cls, identifier, rgb=0, modifier=None, dependencies=None):
+        """Create light material with single value.
+
+        Args:
+            identifier: Text string for a unique Material 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.
+            rgb: Input for r_emittance, g_emittance and b_emittance. The value should be
+                between 0 and 1 (Default: 0).
+            modifier: Material 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: [])
+
+        Usage:
+
+        .. code-block:: python
+
+            sample_light = Light.from_single_value("sample_light", 1)
+            print(sample_light)
+        """
+        return cls(identifier, r_emittance=rgb, g_emittance=rgb, b_emittance=rgb,
+                   modifier=modifier, dependencies=dependencies)
+
+    @classmethod
+    def from_primitive_dict(cls, primitive_dict):
+        """Initialize Light from a primitive dict.
+
+        Args:
+            data: A dictionary in the format below.
+
+        .. code-block:: python
+
+            {
+            "modifier": {}  # primitive modifier (Default: None)
+            "type": "light",  # primitive type
+            "identifier": "",  # primitive identifier
+            "display_name": "",  # primitive display name
+            "values": [],  # values
+            "dependencies": []
+            }
+        """
+        cls._dict_type_check(cls.__name__, primitive_dict)
+        modifier, dependencies = cls.filter_dict_input(primitive_dict)
+        values = primitive_dict['values'][2]
+
+        cls_ = cls(
+            identifier=primitive_dict["identifier"],
+            r_emittance=values[0],
+            g_emittance=values[1],
+            b_emittance=values[2],
+            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 Light from a dictionary.
+
+        Args:
+            data: A dictionary in the format below.
+
+        .. code-block:: python
+
+            {
+            "type": "Light",  # primitive type
+            "identifier": "",  # Material identifier
+            "display_name": ""  # Material display name
+            "r_emittance": float,  # A positive value for the Red channel of the glow
+            "g_emittance": float,  # A positive value for the Green channel of the glow
+            "b_emittance": float,  # A positive value for the Blue channel of the glow
+            "radius": float,  # Maximum radius for shadow testing
+            "dependencies: []
+            }
+        """
+        cls._dict_type_check(cls.__name__, data)
+        modifier, dependencies = cls.filter_dict_input(data)
+
+        new_obj = cls(identifier=data["identifier"],
+                      r_emittance=data["r_emittance"],
+                      g_emittance=data["g_emittance"],
+                      b_emittance=data["b_emittance"],
+                      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': 'Light',
+            'identifier': self.identifier,
+            'r_emittance': self.r_emittance,
+            'g_emittance': self.g_emittance,
+            'b_emittance': self.b_emittance,
+            '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.r_emittance, self.g_emittance,
+                                 self.b_emittance, mod, depend)
+        new_obj._display_name = self._display_name
+        return new_obj

honeybee_radiance/modifier/material/materialbase.py

@@ -0,0 +1,36 @@
+"""Base Radiance Material class (e.g plastic, glass, etc.).
+
+More information on Radiance Materials can be found at:
+
+http://radsite.lbl.gov/radiance/refer/ray.html#Materials
+"""
+from ..modifierbase import Modifier
+
+
+class Material(Modifier):
+    """Base class for Radiance materials.
+
+    Properties:
+        * identifier
+        * display_name
+        * values
+        * modifier
+        * dependencies
+        * is_modifier
+        * is_material
+
+    """
+
+    __slots__ = ()
+
+    @property
+    def is_material(self):
+        """Get a boolean noting whether this object is a material modifier."""
+        return True
+
+    @staticmethod
+    def _dict_type_check(class_name, data):
+        """Check that the 'type' key of a material dict suits the class."""
+        assert 'type' in data, 'Input dictionary is missing "type".'
+        if data['type'].lower() != class_name.lower():
+            raise ValueError('Type must be %s not %s.' % (class_name, data['type']))

honeybee_radiance/modifier/material/metal.py

@@ -0,0 +1,167 @@
+"""Radiance Metal Material.
+
+http://radsite.lbl.gov/radiance/refer/ray.html#Metal
+"""
+from __future__ import division
+
+from .plastic import Plastic
+
+
+class Metal(Plastic):
+    """Radiance metal material.
+
+    Metal is similar to plastic, but specular highlights are modified by the
+    material color. Specularity of metals is usually .9 or greater.
+
+    Args:
+        identifier: Text string for a unique Material 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.
+        r_reflectance: Reflectance for red. The value should be between 0 and 1
+            (Default: 0).
+        g_reflectance: Reflectance for green. The value should be between 0 and 1
+            (Default: 0).
+        b_reflectance: Reflectance for blue. The value should be between 0 and 1
+            (Default: 0).
+        specularity: Fraction of specularity. Specularity of metals is usually
+            0.9 or greater. (Default: 0.9).
+        roughness: Roughness is specified as the rms slope of surface facets. A
+            value of 0 corresponds to a perfectly smooth surface, and a value of 1
+            would be a very rough surface. Roughness values greater than 0.2 are not
+            very realistic. (Default: 0).
+        modifier: Material 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
+        * r_reflectance
+        * g_reflectance
+        * b_reflectance
+        * specularity
+        * roughness
+        * average_reflectance
+        * values
+        * modifier
+        * dependencies
+        * is_modifier
+        * is_material
+    """
+
+    __slots__ = ()
+
+    def __init__(self, identifier, r_reflectance=0.0, g_reflectance=0.0, b_reflectance=0.0,
+                 specularity=0.9, roughness=0.0, modifier=None, dependencies=None):
+        """Create metal material."""
+        Plastic.__init__(self, identifier, r_reflectance, g_reflectance, b_reflectance,
+                         specularity, roughness, modifier, dependencies)
+
+    def _update_values(self):
+        "update value dictionaries."
+        self._values[2] = [
+            self.r_reflectance, self.g_reflectance, self.b_reflectance,
+            self.specularity, self.roughness
+        ]
+        if self.specularity < 0.9:
+            print("Warning: Specularity of metals is usually .9 or greater.")
+        if self.roughness > 0.2:
+            print("Warning: Roughness values above .2 is uncommon.")
+    
+    @classmethod
+    def from_single_reflectance(
+        cls, identifier, rgb_reflectance=0.0, specularity=0.9, roughness=0.0,
+        modifier=None, dependencies=None):
+        """Create Metal material with single reflectance value.
+
+        Args:
+            identifier: Text string for a unique Material 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.
+            rgb_reflectance: Reflectance for red, green and blue. The value should be
+                between 0 and 1 (Default: 0).
+            specularity: Fraction of specularity. Specularity of metals is usually
+                0.9 or greater. (Default: 0.9).
+            roughness: Roughness is specified as the rms slope of surface facets. A value
+                of 0 corresponds to a perfectly smooth surface, and a value of 1 would be
+                a very rough surface. Roughness values greater than 0.2 are not very
+                realistic. (Default: 0).
+            modifier: Material 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: None).
+
+        Usage:
+
+        .. code-block:: python
+
+            wall_material = Metal.from_single_reflectance("sheet_metal", .55)
+            print(wall_material)
+        """
+        return cls(identifier, r_reflectance=rgb_reflectance,
+                   g_reflectance=rgb_reflectance, b_reflectance=rgb_reflectance,
+                   specularity=specularity, roughness=roughness,
+                   modifier=modifier, dependencies=dependencies)
+
+    @classmethod
+    def from_reflected_specularity(
+            cls, identifier, r_reflectance=0.0, g_reflectance=0.0, b_reflectance=0.0,
+            reflected_specularity=0.9, roughness=0.0, modifier=None, dependencies=None):
+        """Create metal material from reflected specularity.
+
+        This method assumes that all of the input fractions for reflectance are
+        absolute fractions of the total amount of light hitting the modifier.
+        This is different than how Radiance natively interprets the properties.
+
+        Args:
+            identifier: Text string for a unique Material 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.
+            r_reflectance: Reflectance for red. The value should be between 0 and 1
+                (Default: 0).
+            g_reflectance: Reflectance for green. The value should be between 0 and 1
+                (Default: 0).
+            b_reflectance: Reflectance for blue. The value should be between 0 and 1
+                (Default: 0).
+            reflected_specularity: Fraction of reflected specular. Specularity
+                fractions greater than 0.1 are not common in non-metallic
+                materials. (Default: 0).
+            roughness: Roughness is specified as the rms slope of surface facets. A
+                value of 0 corresponds to a perfectly smooth surface, and a value of 1
+                would be a very rough surface. Roughness values greater than 0.2 are not
+                very realistic. (Default: 0).
+            modifier: Material 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: [])
+        """
+        cr, cg, cb, rs = \
+            r_reflectance, g_reflectance, b_reflectance, reflected_specularity
+
+        rd = (0.265 * cr + 0.670 * cg + 0.065 * cb)
+
+        absorb = 1 - rd - rs
+        if absorb < 0:
+            summ = rd + rs
+            msg = 'Sum of Diffuse Reflection (%.3f) and Specular Reflection (%.3f) ' \
+                'cannot be more than 1 (%.3f).' % (rd, rs, summ)
+            raise ValueError(msg)
+
+        a1 = cr / ((1 - rs))
+        a2 = cg / ((1 - rs))
+        a3 = cb / ((1 - rs))
+        if a3 > 1 or a2 > 1 or a1 > 1:
+            if a1 > 1:
+                channel, val = 'Red', a1
+            elif a2 > 1:
+                channel, val = 'Green', a2
+            else:
+                channel, val = 'Blue', a3
+            raise ValueError(
+                'This material has a physically impossible reflectance value for '
+                'the {} channel\nwhen specular and diffuse fractions are added '
+                '({}).'.format(channel, val))
+
+        return cls(identifier, a1, a2, a3, rs, roughness,
+                   modifier=modifier, dependencies=dependencies)

honeybee_radiance/modifier/material/metal2.py

@@ -0,0 +1,41 @@
+"""Radiance Metal2 Material.
+
+http://radsite.lbl.gov/radiance/refer/ray.html#Metal2
+"""
+from .materialbase import Material
+
+
+# TODO: Implement the class. It's currently only a generic Radiance Primitive
+class Metal2(Material):
+    """Radiance Metal2 Material.
+
+    Metal2 is the same as plastic2, except that the highlights are modified by the
+    material color.
+
+    Args:
+        identifier: Text string for a unique Material 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.
+        modifier: Modifier. It can be primitive, mixture, texture or pattern.
+            (Default: None).
+        values: An array 3 arrays for primitive data. Each of the 3 sub-arrays
+            refer to a line number in the radiance primitive definitions and the
+            values in each array correspond to values occurring within each line.
+        is_opaque: A boolean to indicate whether this primitive is opaque.
+        dependencies: A list of primitives that this primitive depends on. This
+            argument is only useful for defining advanced primitives that are
+            defined based on other primitives. (Default: []).
+
+    Properties:
+        * identifier
+        * display_name
+        * values
+        * modifier
+        * dependencies
+        * is_modifier
+        * is_material
+        * is_opaque
+    """
+    __slots__ = ()
+
+    pass

honeybee_radiance/modifier/material/metdata.py

@@ -0,0 +1,41 @@
+"""Radiance Metdata Material.
+
+http://radsite.lbl.gov/radiance/refer/ray.html#Metdata
+"""
+from .materialbase import Material
+
+
+# TODO: Implement the class. It's currently only a generic Radiance Primitive
+class Metdata(Material):
+    """Radiance Metdata Material.
+
+    As metfunc is to plasfunc, metdata is to plasdata. Metdata takes the same arguments
+    as plasdata, but the specular component is modified by the given material color.
+
+    Args:
+        identifier: Text string for a unique Material 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.
+        modifier: Modifier. It can be primitive, mixture, texture or pattern.
+            (Default: None).
+        values: An array 3 arrays for primitive data. Each of the 3 sub-arrays
+            refer to a line number in the radiance primitive definitions and the
+            values in each array correspond to values occurring within each line.
+        is_opaque: A boolean to indicate whether this primitive is opaque.
+        dependencies: A list of primitives that this primitive depends on. This
+            argument is only useful for defining advanced primitives that are
+            defined based on other primitives. (Default: []).
+
+    Properties:
+        * identifier
+        * display_name
+        * values
+        * modifier
+        * dependencies
+        * is_modifier
+        * is_material
+        * is_opaque
+    """
+    __slots__ = ()
+
+    pass

honeybee_radiance/modifier/material/metfunc.py

@@ -0,0 +1,41 @@
+"""Radiance Metfunc Material.
+
+http://radsite.lbl.gov/radiance/refer/ray.html#Metfunc
+"""
+from .materialbase import Material
+
+
+# TODO: Implement the class. It's currently only a generic Radiance Primitive
+class Metfunc(Material):
+    """Radiance Metfunc Material.
+
+    Metfunc is identical to plasfunc and takes the same arguments, but the specular
+    component is multiplied also by the material color.
+
+    Args:
+        identifier: Text string for a unique Material 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.
+        modifier: Modifier. It can be primitive, mixture, texture or pattern.
+            (Default: None).
+        values: An array 3 arrays for primitive data. Each of the 3 sub-arrays
+            refer to a line number in the radiance primitive definitions and the
+            values in each array correspond to values occurring within each line.
+        is_opaque: A boolean to indicate whether this primitive is opaque.
+        dependencies: A list of primitives that this primitive depends on. This
+            argument is only useful for defining advanced primitives that are
+            defined based on other primitives. (Default: []).
+
+    Properties:
+        * identifier
+        * display_name
+        * values
+        * modifier
+        * dependencies
+        * is_modifier
+        * is_material
+        * is_opaque
+    """
+    __slots__ = ()
+
+    pass