honeybee-radiance 1.66.190__py3-none-any.whl

honeybee_radiance/modifier/material/mirror.py

@@ -0,0 +1,340 @@
+"""Radiance Mirror Material.
+
+http://radsite.lbl.gov/radiance/refer/ray.html#Mirror
+"""
+from __future__ import division
+from .materialbase import Material
+import honeybee.typing as typing
+from ...primitive import Void
+
+
+VOID = Void()
+
+
+class Mirror(Material):
+    """Radiance mirror material.
+
+    Mirror is used for planar surfaces that produce virtual source reflections. This
+    material should be used sparingly, as it may cause the light source calculation to
+    blow up if it is applied to many small surfaces. This material is only supported for
+    flat surfaces such as polygons and rings. The arguments are simply the
+    RGB reflectance values, which should be between 0 and 1.
+
+    An optional string argument may be used (like the illum type) to specify a different
+    material to be used for shading non-source rays. If this alternate material is given
+    as "void", then the mirror surface will be invisible. Using "void" is only
+    appropriate if the surface hides other (more detailed) geometry with the same
+    overall reflectance. 
+
+    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: 1).
+        g_reflectance: Reflectance for green. The value should be between 0 and 1
+            (Default: 1).
+        b_reflectance: Reflectance for blue. The value should be between 0 and 1
+            (Default: 1).
+        modifier: Material modifier (Default: None).
+        alternate_material: An optional material (like the illum type) used to
+            specify a different material to be used for shading non-source rays.
+            If None, this will keep the alternat_material as mirror. If this alternate
+            material is given as "void", then the mirror surface will be invisible.
+            Using "void" is only appropriate if the surface hides other (more
+            detailed) geometry with the same overall reflectance (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
+        * average_reflectance
+        * values
+        * modifier
+        * alternate_material
+        * dependencies
+        * is_modifier
+        * is_material
+
+    Usage:
+
+    .. code-block:: python
+
+        mirror_material = Mirror("mirror_material", 0.95, .95, .95)
+        print(mirror_material)
+    """
+
+    __slots__ = ('_r_reflectance', '_g_reflectance', '_b_reflectance',
+                 '_alternate_material',)
+
+    def __init__(
+        self, identifier, r_reflectance=1.0, g_reflectance=1.0, b_reflectance=1.0,
+            modifier=None, alternate_material=None, dependencies=None):
+        """Create mirror material."""
+        # add alternate material as a dependency if provided
+        self._alternate_material = None  # placeholder for alternate material
+        Material.__init__(self, identifier, modifier=modifier, dependencies=dependencies)
+        self.r_reflectance = r_reflectance
+        self.g_reflectance = g_reflectance
+        self.b_reflectance = b_reflectance
+        self.alternate_material = alternate_material
+        self._update_values()
+
+    def _update_values(self):
+        "update value dictionaries."
+        if self.alternate_material is not None:
+            self._values[0] = [self.alternate_material.identifier]
+        self._values[2] = [
+            self.r_reflectance, self.g_reflectance, self.b_reflectance,
+        ]
+
+    @property
+    def r_reflectance(self):
+        """Get or set the reflectance for red channel.
+
+        The value should be between 0 and 1 (Default: 0).
+        """
+        return self._r_reflectance
+
+    @r_reflectance.setter
+    def r_reflectance(self, reflectance):
+        self._r_reflectance = \
+            typing.float_in_range(reflectance, 0, 1, 'red reflectance')
+
+    @property
+    def g_reflectance(self):
+        """Get or set the reflectance for green channel.
+
+        The value should be between 0 and 1 (Default: 0).
+        """
+        return self._g_reflectance
+
+    @g_reflectance.setter
+    def g_reflectance(self, reflectance):
+        self._g_reflectance = \
+            typing.float_in_range(reflectance, 0, 1, 'green reflectance')
+
+    @property
+    def b_reflectance(self):
+        """Get or set the reflectance for blue channel.
+
+        The value should be between 0 and 1 (Default: 0).
+        """
+        return self._b_reflectance
+
+    @b_reflectance.setter
+    def b_reflectance(self, reflectance):
+        self._b_reflectance = \
+            typing.float_in_range(reflectance, 0, 1, 'blue reflectance')
+
+    @property
+    def alternate_material(self):
+        """Get or set an optional material for shading non-source rays.
+
+        If None, this will keep the alternat_material as mirror. If this alternate
+        material is given as "void", then the mirror surface will be invisible.
+        Using "void" is only appropriate if the surface hides other (more
+        detailed) geometry with the same overall reflectance.
+        """
+        return self._alternate_material
+
+    @alternate_material.setter
+    def alternate_material(self, material):
+        if material is not None:
+            assert isinstance(material, (Material, Void)), \
+                'alternate material must be from type Material not {}'.format(
+                type(material))
+
+        self._alternate_material = material
+
+    @property
+    def dependencies(self):
+        """Get list of dependencies for this primitive.
+
+        Additional dependencies can be added with the add_dependent method.
+        """
+        return self._dependencies if not self.alternate_material \
+            else self._dependencies + [self.alternate_material]
+
+    @classmethod
+    def from_single_reflectance(
+        cls, identifier, rgb_reflectance=0.0, modifier=None, alternate_material=None,
+            dependencies=None):
+        """Create mirror 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).
+            modifier: Material modifier (Default: None).
+            alternate_material: An optional material may be used like the illum type to
+                specify a different material to be used for shading non-source rays.
+                If None, this will keep the alternat_material as mirror. If this alternate
+                material is given as "void", then the mirror surface will be invisible.
+                Using "void" is only appropriate if the surface hides other (more
+                detailed) geometry with the same overall reflectance (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
+
+            wall_material = Mirror.by_single_reflect_value("mirror", 1.0)
+        """
+        return cls(
+            identifier, rgb_reflectance, rgb_reflectance, rgb_reflectance,
+            modifier, alternate_material, dependencies
+        )
+
+    @classmethod
+    def from_primitive_dict(cls, primitive_dict):
+        """Initialize mirror from a primitive dict.
+
+        Args:
+            data: A dictionary in the format below.
+
+        .. code-block:: python
+
+            {
+            "modifier": {},  # primitive modifier (Default: None)
+            "type": "mirror",  # 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)
+        if len(primitive_dict['values'][0]) == 1:
+            # find name
+            alt_id = primitive_dict['values'][0][0]
+            if alt_id == 'void':
+                alternate_material = VOID
+            elif isinstance(alt_id, dict):
+                try:  # see if the mutil module has already been imported
+                    mutil
+                except NameError:
+                    # import the module here to avoid a circular import
+                    import honeybee_radiance.mutil as mutil
+                alternate_material = mutil.dict_to_modifier(alt_id)
+            else:
+                alt_mats = [d for d in dependencies if d.identifier == alt_id]
+
+                assert len(alt_mats) == 1, \
+                    'Failed to find alternate material for mirror: "{}" in ' \
+                    'dependencies.'.format(alt_id)
+
+                # remove it from dependencies
+                alternate_material = alt_mats[0]
+                dependencies.remove(alternate_material)
+        else:
+            alternate_material = None
+
+        values = primitive_dict['values'][2]
+        cls_ = cls(
+            identifier=primitive_dict["identifier"],
+            r_reflectance=values[0],
+            g_reflectance=values[1],
+            b_reflectance=values[2],
+            modifier=modifier,
+            alternate_material=alternate_material,
+            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 Mirror from a dictionary.
+
+        Args:
+            data: A dictionary in the format below.
+
+        .. code-block:: python
+
+            {
+            "type": "Mirror",  # Material type
+            "identifier": "",  # Material identifier
+            "display_name": "",  # Material display name
+            "r_reflectance": float,  # Reflectance for red
+            "g_reflectance": float,  # Reflectance for green
+            "b_reflectance": float,  # Reflectance for blue
+            "modifier": {},  # Material modifier (Default: None)
+            "alternate_material": {},  # optional alternate material
+            "dependencies": []
+            }
+        """
+        cls._dict_type_check(cls.__name__, data)
+        modifier, dependencies = cls.filter_dict_input(data)
+        if 'alternate_material' in data and data['alternate_material']:
+            # alternate material
+            if data['alternate_material'] == 'void':
+                alternate_material = VOID
+            else:
+                try:  # see if the mutil module has already been imported
+                    mutil
+                except NameError:
+                    # import the module here to avoid a circular import
+                    import honeybee_radiance.mutil as mutil
+                alternate_material = mutil.dict_to_modifier(data['alternate_material'])
+        else:
+            alternate_material = None
+
+        new_obj = cls(identifier=data["identifier"],
+                      r_reflectance=data["r_reflectance"],
+                      g_reflectance=data["g_reflectance"],
+                      b_reflectance=data["b_reflectance"],
+                      modifier=modifier,
+                      alternate_material=alternate_material,
+                      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': 'Mirror',
+            'identifier': self.identifier,
+            'r_reflectance': self.r_reflectance,
+            'g_reflectance': self.g_reflectance,
+            'b_reflectance': self.b_reflectance,
+            # dependencies without alternate material
+            'dependencies': [dp.to_dict() for dp in self._dependencies]
+        }
+        if self.alternate_material:
+            if isinstance(self.alternate_material, Void):
+                base['alternate_material'] = {'type': 'void'}
+            else:
+                base['alternate_material'] = self.alternate_material.to_dict()
+        else:
+            base['alternate_material'] = None
+        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()
+        alt_mat = None if not self.alternate_material \
+            else self.alternate_material.duplicate()
+        new_obj = self.__class__(
+            self.identifier, self.r_reflectance, self.g_reflectance, self.b_reflectance,
+            mod, alt_mat, depend)
+        new_obj._display_name = self._display_name
+        return new_obj

honeybee_radiance/modifier/material/mist.py

@@ -0,0 +1,86 @@
+"""Radiance Mist Material.
+
+http://radsite.lbl.gov/radiance/refer/ray.html#Mist
+"""
+from .materialbase import Material
+
+
+# TODO: Implement the class. It's currently only a generic Radiance Primitive
+class Mist(Material):
+    """Radiance Mist Material.
+
+    Mist is a virtual material used to delineate a volume of participating atmosphere. A
+    list of important light sources may be given, along with an extinction coefficient,
+    scattering albedo and scattering eccentricity parameter. The light sources named by
+    the string argument list will be tested for scattering within the volume. Sources are
+    identified by name, and virtual light sources may be indicated by giving the relaying
+    object followed by '>' followed by the source, i.e::
+
+           3  source1  mirror1>source10  mirror2>mirror1>source3
+
+    Normally, only one source is given per mist material, and there is an upper limit of
+    32 to the total number of active scattering sources. The extinction coefficient, if
+    given, is added the the global coefficient set on the command line. Extinction is in
+    units of 1/distance (distance based on the world coordinates), and indicates the
+    proportional loss of radiance over one unit distance. The scattering albedo, if
+    present, will override the global setting within the volume. An albedo of 0 0 0 means
+    a perfectly absorbing medium, and an albedo of 1 1 1 means a perfectly scattering
+    medium (no absorption). The scattering eccentricity parameter will likewise override
+    the global setting if it is present. Scattering eccentricity indicates how much
+    scattered light favors the forward direction, as fit by the Henyey-Greenstein
+    function::
+
+        P(theta) = (1 - g*g) / (1 + g*g - 2*g*cos(theta))^1.5
+
+    A perfectly isotropic scattering medium has a g parameter of 0, and a highly
+    directional material has a g parameter close to 1. Fits to the g parameter may be
+    found along with typical extinction coefficients and scattering albedos for various
+    atmospheres and cloud types in USGS meteorological tables. (A pattern will be applied
+    to the extinction values.)::
+
+        mod mist id
+        N src1 src2 .. srcN
+        0
+        0|3|6|7 [ rext gext bext [ ralb galb balb [ g ] ] ]
+
+    There are two usual uses of the mist type. One is to surround a beam from a spotlight
+    or laser so that it is visible during rendering. For this application, it is
+    important to use a cone (or cylinder) that is long enough and wide enough to contain
+    the important visible portion. Light source photometry and intervening objects will
+    have the desired effect, and crossing beams will result in additive scattering. For
+    this application, it is best to leave off the real arguments, and use the global
+    rendering parameters to control the atmosphere. The second application is to model
+    clouds or other localized media. Complex boundary geometry may be used to give shape
+    to a uniform medium, so long as the boundary encloses a proper volume. Alternatively,
+    a pattern may be used to set the line integral value through the cloud for a ray
+    entering or exiting a point in a given direction. For this application, it is best if
+    cloud volumes do not overlap each other, and opaque objects contained within them may
+    not be illuminated correctly unless the line integrals consider enclosed geometry.
+
+    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/plasdata.py

@@ -0,0 +1,58 @@
+"""Radiance Plasdata Material.
+
+http://radsite.lbl.gov/radiance/refer/ray.html#Plasdata
+"""
+from .materialbase import Material
+
+
+# TODO: Implement the class. It's currently only a generic Radiance Primitive
+class Plasdata(Material):
+    """Radiance Plasdata Material.
+
+    Plasdata is used for arbitrary BRDF's that are most conveniently given as
+    interpolated data. The arguments to this material are the data file and coordinate
+    index functions, as well as a function to optionally modify the data values.
+
+    .. code-block:: shell
+
+        mod plasdata id
+        3+n+
+                func datafile
+                funcfile x1 x2 .. xn transform
+        0
+        4+ red green blue spec A5 ..
+
+    The coordinate indices (x1, x2, etc.) are themselves functions of the x, y and z
+    direction to the incident light, plus the solid angle subtended by the light source
+    (usually ignored). The data function (func) takes five variables, the interpolated
+    value from the n-dimensional data file, followed by the x, y and z direction to the
+    incident light and the solid angle of the source. The light source direction and
+    size may of course be ignored by the function.
+
+    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/plasfunc.py

@@ -0,0 +1,59 @@
+"""Radiance Plasfunc Material.
+
+http://radsite.lbl.gov/radiance/refer/ray.html#Plasfunc
+"""
+from .materialbase import Material
+
+
+# TODO: Implement the class. It's currently only a generic Radiance Primitive
+class Plasfunc(Material):
+    """Radiance Plasfunc Material.
+
+    Plasfunc in used for the procedural definition of plastic-like materials with
+    arbitrary bidirectional reflectance distribution functions (BRDF's). The arguments
+    to this material include the color and specularity, as well as the function defining
+    the specular distribution and the auxiliary file where it may be found.
+
+    .. code-block:: shell
+
+            mod plasfunc id
+            2+ refl funcfile transform
+            0
+            4+ red green blue spec A5 ..
+
+    The function refl takes four arguments, the x, y and z direction towards the incident
+    light, and the solid angle subtended by the source. The solid angle is provided to
+    facilitate averaging, and is usually ignored. The refl function should integrate to
+    1 over the projected hemisphere to maintain energy balance. At least four real
+    arguments must be given, and these are made available along with any additional
+    values to the reflectance function. Currently, only the contribution from direct
+    light sources is considered in the specular calculation. As in most material types,
+    the surface normal is always altered to face the incoming ray.
+
+    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