honeybee-schema 1.59.1__py3-none-any.whl

honeybee_schema/radiance/asset.py

@@ -0,0 +1,191 @@
+"""SensorGrid and Sensor Schema"""
+from pydantic import Field, constr
+from typing import List
+from enum import Enum
+from ..geometry import Mesh3D, Face3D
+from .._base import NoExtraBaseModel
+from ._base import IDdRadianceBaseModel
+
+
+class _RadianceAsset(IDdRadianceBaseModel):
+    """Hidden base class for all Radiance Assets."""
+
+    room_identifier: str = Field(
+        None,
+        regex=r'^[.A-Za-z0-9_-]+$',
+        min_length=1,
+        max_length=100,
+        description='Optional text string for the Room identifier to which this '
+        'object belongs. This will be used to narrow down the number of '
+        'aperture groups that have to be run with this sensor grid. If None, '
+        'the grid will be run with all aperture groups in the model.'
+    )
+
+    light_path: List[List[str]] = Field(
+        None,
+        description='Get or set a list of lists for the light path from the object to '
+        'the sky. Each sub-list contains identifiers of aperture groups through which '
+        'light passes. (eg. [["SouthWindow1"], ["static_apertures", "NorthWindow2"]]).'
+        'Setting this property will override any auto-calculation of the light '
+        'path from the model and room_identifier upon export to the simulation.'
+    )
+
+
+class Sensor(NoExtraBaseModel):
+    """A single Radiance of sensors."""
+
+    type: constr(regex='^Sensor$') = 'Sensor'
+
+    pos: List[float] = Field(
+        ...,
+        description="Position of sensor in space as an array of (x, y, z) values.",
+        min_items=3,
+        max_items=3
+    )
+
+    dir: List[float] = Field(
+        ...,
+        description="Direction of sensor as an array of (x, y, z) values.",
+        min_items=3,
+        max_items=3
+    )
+
+
+class SensorGrid(_RadianceAsset):
+    """A grid of sensors."""
+
+    type: constr(regex='^SensorGrid$') = 'SensorGrid'
+
+    sensors: List[Sensor] = Field(
+        ...,
+        description='A list of sensors that belong to the grid.'
+    )
+
+    mesh: Mesh3D = Field(
+        None,
+        description='An optional Mesh3D that aligns with the sensors and can be '
+        'used for visualization of the grid. Note that the number of sensors in '
+        'the grid must match the number of faces or the number vertices within '
+        'the Mesh3D.'
+    )
+
+    base_geometry: List[Face3D] = Field(
+        None,
+        description='An optional array of Face3D used to represent the grid. '
+        'There are no restrictions on how this property relates to the sensors and it '
+        'is provided only to assist with the display of the grid when the number '
+        'of sensors or the mesh is too large to be practically visualized.'
+    )
+
+    group_identifier: str = Field(
+        default=None,
+        description="An optional string to note the sensor grid group ' \
+            'to which the sensor is a part of. Grids sharing the same ' \
+            'group_identifier will be written to the same subfolder in Radiance ' \
+            'folder (default: None)."
+    )
+
+
+class ViewType(str, Enum):
+    """A single character for the view type (-vt)."""
+    perspective = 'v'
+    hemispherical_fisheye = 'h'
+    parallel = 'l'
+    cylindrical_panorama = 'c'
+    angular_fisheye = 'a'
+    planisphere = 's'
+
+
+class View(_RadianceAsset):
+    """A single Radiance of sensors."""
+
+    type: constr(regex='^View$') = 'View'
+
+    position: List[float] = Field(
+        ...,
+        description='The view position (-vp) as an array of (x, y, z) values.'
+        'This is the focal point of a perspective view or the center of a '
+        'parallel projection.',
+        min_items=3,
+        max_items=3
+    )
+
+    direction: List[float] = Field(
+        ...,
+        description='The view direction (-vd) as an array of (x, y, z) values.'
+        'The length of this vector indicates the focal distance as needed by '
+        'the pixel depth of field (-pd) in rpict.',
+        min_items=3,
+        max_items=3
+    )
+
+    up_vector: List[float] = Field(
+        ...,
+        description='The view up (-vu) vector as an array of (x, y, z) values.',
+        min_items=3,
+        max_items=3
+    )
+
+    view_type: ViewType = ViewType.perspective
+
+    h_size: float = Field(
+        60,
+        description='A number for the horizontal field of view in degrees (for '
+        'all perspective projections including fisheye). For a parallel '
+        'projection, this is the view width in world coordinates.'
+    )
+
+    v_size: float = Field(
+        60,
+        description='A number for the vertical field of view in degrees (for '
+        'all perspective projections including fisheye). For a parallel '
+        'projection, this is the view width in world coordinates.'
+    )
+
+    shift: float = Field(
+        None,
+        description='The view shift (-vs). This is the amount the actual '
+        'image will be shifted to the right of the specified view. This '
+        'option is useful for generating skewed perspectives or rendering '
+        'an image a piece at a time. A value of 1 means that the rendered '
+        'image starts just to the right of the normal view. A value of -1 '
+        'would be to the left. Larger or fractional values are permitted '
+        'as well.'
+    )
+
+    lift: float = Field(
+        None,
+        description='The view lift (-vl). This is the amount the actual '
+        'image will be lifted up from the specified view. This '
+        'option is useful for generating skewed perspectives or rendering '
+        'an image a piece at a time. A value of 1 means that the rendered '
+        'image starts just to the right of the normal view. A value of -1 '
+        'would be to the left. Larger or fractional values are permitted '
+        'as well.'
+    )
+
+    fore_clip: float = Field(
+        None,
+        description='View fore clip (-vo) at a distance from the view point.'
+        'The plane will be perpendicular to the view direction for perspective '
+        'and parallel view types. For fisheye view types, the clipping plane is '
+        'actually a clipping sphere, centered on the view point with fore_clip radius. '
+        'Objects in front of this imaginary surface will not be visible.'
+    )
+
+    aft_clip: float = Field(
+        None,
+        description='View aft clip (-va) at a distance from the view point.'
+        'Like the view fore plane, it will be perpendicular to the view '
+        'direction for perspective and parallel view types. For fisheye '
+        'view types, the clipping plane is actually a clipping sphere, '
+        'centered on the view point with radius val.'
+    )
+
+    group_identifier: str = Field(
+        default=None,
+        description="An optional string to note the view group ' \
+            'to which the sensor is a part of. Views sharing the same ' \
+            'group_identifier will be written to the same subfolder in Radiance ' \
+            'folder (default: None)."
+    )

honeybee_schema/radiance/global_modifierset.py

@@ -0,0 +1,92 @@
+"""Global modifier-set for Model."""
+import pathlib
+import json
+
+from typing import List, Union
+from pydantic import constr, Field
+
+from honeybee_standards import radiance_default
+
+from .._base import NoExtraBaseModel
+from .modifierset import WallModifierSetAbridged, FloorModifierSetAbridged, \
+    RoofCeilingModifierSetAbridged, ApertureModifierSetAbridged, \
+    DoorModifierSetAbridged, ShadeModifierSetAbridged
+from .modifier import Plastic, Glass, Trans
+
+
+# import modifierset default values from honeybee standards
+_DEFAULTS = json.loads(pathlib.Path(radiance_default).read_text())
+_MOD_SET = [
+    ms for ms in _DEFAULTS['modifier_sets']
+    if ms['identifier'] == 'Generic_Interior_Visible_Modifier_Set'][0]
+_MODIFIER_NAMES = [
+    'generic_wall_0.50', 'generic_floor_0.20', 'generic_ceiling_0.80',
+    'generic_interior_window_vis_0.88', 'generic_exterior_window_vis_0.64',
+    'generic_opaque_door_0.50', 'generic_interior_shade_0.50',
+    'generic_exterior_shade_0.35', 'generic_context_0.20', 'air_boundary'
+]
+_MODIFIERS = [
+    Plastic.parse_obj(m) if m['type'] == 'Plastic'
+    else Glass.parse_obj(m) if m['type'] == 'Glass'
+    else Trans.parse_obj(m)
+    for m in _DEFAULTS['modifiers'] if m['identifier'] in _MODIFIER_NAMES
+]
+
+
+class GlobalModifierSet(NoExtraBaseModel):
+
+    type: constr(regex='^GlobalModifierSet$') = 'GlobalModifierSet'
+
+    modifiers: List[Union[Plastic, Glass, Trans]] = Field(
+        default=_MODIFIERS,
+        description='Global Honeybee Radiance modifiers.',
+        readOnly=True
+    )
+
+    wall_set: WallModifierSetAbridged = Field(
+        default=WallModifierSetAbridged.parse_obj(_MOD_SET['wall_set']),
+        description='Global Honeybee WallModifierSet.',
+        readOnly=True
+    )
+
+    floor_set: FloorModifierSetAbridged = Field(
+        default=FloorModifierSetAbridged.parse_obj(_MOD_SET['floor_set']),
+        description='Global Honeybee FloorModifierSet.',
+        readOnly=True
+    )
+
+    roof_ceiling_set: RoofCeilingModifierSetAbridged = Field(
+        default=RoofCeilingModifierSetAbridged.parse_obj(_MOD_SET['roof_ceiling_set']),
+        description='Global Honeybee RoofCeilingModifierSet.',
+        readOnly=True
+    )
+
+    aperture_set: ApertureModifierSetAbridged = Field(
+        default=ApertureModifierSetAbridged.parse_obj(_MOD_SET['aperture_set']),
+        description='Global Honeybee ApertureModifierSet.',
+        readOnly=True
+    )
+
+    door_set: DoorModifierSetAbridged = Field(
+        default=DoorModifierSetAbridged.parse_obj(_MOD_SET['door_set']),
+        description='Global Honeybee DoorModifierSet.',
+        readOnly=True
+    )
+
+    shade_set: ShadeModifierSetAbridged = Field(
+        default=ShadeModifierSetAbridged.parse_obj(_MOD_SET['shade_set']),
+        description='Global Honeybee ShadeModifierSet.',
+        readOnly=True
+    )
+
+    air_boundary_modifier: str = Field(
+        default=_MOD_SET['air_boundary_modifier'],
+        description='Global Honeybee Modifier for AirBoundary Faces.',
+        readOnly=True
+    )
+
+    context_modifier: str = Field(
+        default='generic_context_0.20',
+        description='Global Honeybee Modifier for context Shades.',
+        readOnly=True
+    )

honeybee_schema/radiance/modifier.py

@@ -0,0 +1,373 @@
+"""Modifier Schema"""
+from __future__ import annotations
+from pydantic import Field, BaseModel, constr, validator
+from typing import List, Union, Optional
+from ._base import IDdRadianceBaseModel
+
+
+class Void(BaseModel):
+    """Void modifier"""
+
+    type: constr(regex='^Void$') = 'Void'
+
+
+class ModifierBase(IDdRadianceBaseModel):
+    """Base class for Radiance Modifiers"""
+
+    type: constr(regex='^ModifierBase$') = 'ModifierBase'
+
+
+class Mirror(ModifierBase):
+    """Radiance mirror material."""
+
+    type: constr(regex='^Mirror$') = 'Mirror'
+
+    modifier: Optional[_REFERENCE_UNION_MODIFIERS] = Field(
+        default=Void(),
+        description='Material modifier.'
+    )
+
+    dependencies: List[_REFERENCE_UNION_MODIFIERS] = Field(
+        default=None,
+        description='List of modifiers that this modifier depends on. This argument '
+        'is only useful for defining advanced modifiers where the modifier is defined '
+        'based on other modifiers.'
+    )
+
+    r_reflectance: float = Field(
+        default=1,
+        ge=0,
+        le=1,
+        description='A value between 0 and 1 for the red channel reflectance.'
+    )
+
+    g_reflectance: float = Field(
+        default=1,
+        ge=0,
+        le=1,
+        description='A value between 0 and 1 for the green channel reflectance.'
+    )
+
+    b_reflectance: float = Field(
+        default=1,
+        ge=0,
+        le=1,
+        description='A value between 0 and 1 for the blue channel reflectance.'
+    )
+
+    alternate_material: _REFERENCE_UNION_MODIFIERS = Field(
+        default=None,
+        description='An optional material (like the illum type) that may be 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.'
+    )
+
+
+class Plastic(ModifierBase):
+    """Radiance plastic material."""
+
+    type: constr(regex='^Plastic$') = 'Plastic'
+
+    modifier: Optional[_REFERENCE_UNION_MODIFIERS] = Field(
+        default=Void(),
+        description='Material modifier.'
+    )
+
+    dependencies: List[_REFERENCE_UNION_MODIFIERS] = Field(
+        default=None,
+        description='List of modifiers that this modifier depends on. This argument '
+        'is only useful for defining advanced modifiers where the modifier is defined '
+        'based on other modifiers.'
+    )
+
+    r_reflectance: float = Field(
+        default=0.0,
+        ge=0,
+        le=1,
+        description='A value between 0 and 1 for the red channel reflectance.'
+    )
+
+    g_reflectance: float = Field(
+        default=0.0,
+        ge=0,
+        le=1,
+        description='A value between 0 and 1 for the green channel reflectance.'
+    )
+
+    b_reflectance: float = Field(
+        default=0.0,
+        ge=0,
+        le=1,
+        description='A value between 0 and 1 for the blue channel reflectance.'
+    )
+
+    specularity: float = Field(
+        default=0,
+        ge=0,
+        le=1,
+        description='A value between 0 and 1 for the fraction of specularity. '
+        'Specularity fractions greater than 0.1 are not realistic for non-metallic '
+        'materials.'
+    )
+
+    roughness: float = Field(
+        default=0,
+        ge=0,
+        le=1,
+        description='A value between 0 and 1 for the roughness, specified as the '
+        'RMS slope of surface facets. Roughness greater than 0.2 are not realistic.'
+    )
+
+
+class Metal(Plastic):
+    """Radiance metal material."""
+
+    type: constr(regex='^Metal$') = 'Metal'
+
+    specularity: float = Field(
+        default=0.9,
+        ge=0,
+        le=1,
+        description='A value between 0 and 1 for the fraction of specularity. '
+        'Specularity fractions lower than 0.9 are not realistic for metallic materials.'
+    )
+
+
+class Trans(Plastic):
+    """Radiance Translucent material."""
+
+    type: constr(regex='^Trans$') = 'Trans'
+
+    transmitted_diff: float = Field(
+        default=0,
+        ge=0,
+        le=1,
+        description='The fraction of transmitted light that is transmitted diffusely in '
+        'a scattering fashion.'
+    )
+
+    transmitted_spec: float = Field(
+        default=0,
+        ge=0,
+        le=1,
+        description='The fraction of transmitted light that is not diffusely scattered.'
+    )
+
+
+class Glass(ModifierBase):
+    """Radiance glass material."""
+
+    type: constr(regex='^Glass$') = 'Glass'
+
+    modifier: Optional[_REFERENCE_UNION_MODIFIERS] = Field(
+        default=Void(),
+        description='Material modifier.'
+    )
+
+    dependencies: List[_REFERENCE_UNION_MODIFIERS] = Field(
+        default=None,
+        description='List of modifiers that this modifier depends on. This argument '
+        'is only useful for defining advanced modifiers where the modifier is '
+        'defined based on other modifiers.'
+    )
+
+    r_transmissivity: float = Field(
+        default=0.0,
+        ge=0,
+        le=1,
+        description='A value between 0 and 1 for the red channel transmissivity.'
+    )
+
+    g_transmissivity: float = Field(
+        default=0.0,
+        ge=0,
+        le=1,
+        description='A value between 0 and 1 for the green channel transmissivity.'
+    )
+
+    b_transmissivity: float = Field(
+        default=0.0,
+        ge=0,
+        le=1,
+        description='A value between 0 and 1 for the blue channel transmissivity.'
+    )
+
+    refraction_index: Optional[float] = Field(
+        default=1.52,
+        gt=1,
+        description='A value greater than 1 for the index of refraction. Typical '
+        'values are 1.52 for float glass and 1.4 for ETFE.'
+    )
+
+
+class BSDF(ModifierBase):
+    """Radiance BSDF (Bidirectional Scattering Distribution Function) material."""
+
+    type: constr(regex='^BSDF$') = 'BSDF'
+
+    modifier: Optional[_REFERENCE_UNION_MODIFIERS] = Field(
+        default=Void(),
+        description='Material modifier.'
+    )
+
+    dependencies: List[_REFERENCE_UNION_MODIFIERS] = Field(
+        default=None,
+        description='List of modifiers that this modifier depends on. This argument '
+        'is only useful for defining advanced modifiers where the modifier is defined '
+        'based on other modifiers.'
+    )
+
+    up_orientation: List[float] = Field(
+        default=(0.01, 0.01, 1.00),
+        min_items=3,
+        max_items=3,
+        description='Vector as sequence that sets the hemisphere that the BSDF '
+        'material faces.'
+    )
+
+    thickness: float = Field(
+        default=0,
+        description='Optional number to set the thickness of the BSDF material '
+        'Sign of thickness indicates whether proxied geometry is behind the BSDF '
+        'surface (when thickness is positive) or in front (when thickness is '
+        'negative).'
+    )
+
+    function_file: str = Field(
+        default='.',
+        min_length=1,
+        max_length=100,
+        description='Optional input for function file. Using "." will ensure that '
+        'BSDF data is written to the root of wherever a given study is run.'
+    )
+
+    transform: str = Field(
+        default=None,
+        min_length=1,
+        max_length=100,
+        description='Optional transform input to scale the thickness and reorient '
+        'the up vector.'
+    )
+
+    bsdf_data: str = Field(
+        ...,
+        description='A string with the contents of the BSDF XML file.'
+    )
+
+    front_diffuse_reflectance: List[float] = Field(
+        default=None,
+        min_items=3,
+        max_items=3,
+        description='Optional additional front diffuse reflectance as sequence of '
+        'three RGB numbers.'
+    )
+
+    back_diffuse_reflectance: List[float] = Field(
+        default=None,
+        min_items=3,
+        max_items=3,
+        description='Optional additional back diffuse reflectance as sequence of '
+        'three RGB numbers.'
+    )
+
+    diffuse_transmittance: List[float] = Field(
+        default=None,
+        min_items=3,
+        max_items=3,
+        description='Optional additional diffuse transmittance as sequence of '
+        'three RGB numbers.'
+    )
+
+    @validator('front_diffuse_reflectance')
+    def check_front_diff_value(cls, values):
+        """Ensure every list value is between 0 and 1."""
+        assert all(0 <= v <= 1 for v in values), \
+            'Every value in front diffuse reflectance must be between 0 and 1.'
+        return values
+
+    @validator('back_diffuse_reflectance')
+    def check_back_diff_value(cls, values):
+        """Ensure every list value is between 0 and 1."""
+        assert all(0 <= v <= 1 for v in values), \
+            'Every value in back diffuse reflectance must be between 0 and 1.'
+        return values
+
+    @validator('diffuse_transmittance')
+    def check_diff_trans_value(cls, values):
+        """Ensure every list value is between 0 and 1."""
+        assert all(0 <= v <= 1 for v in values), \
+            'Every value in diffuse transmittance must be between 0 and 1.'
+        return values
+
+
+class Light(ModifierBase):
+    """Radiance Light material."""
+
+    type: constr(regex='^Light$') = 'Light'
+
+    modifier: Optional[_REFERENCE_UNION_MODIFIERS] = Field(
+        default=Void(),
+        description='Material modifier.'
+    )
+
+    dependencies: List[_REFERENCE_UNION_MODIFIERS] = Field(
+        default=None,
+        description='List of modifiers that this modifier depends on. This argument '
+        'is only useful for defining advanced modifiers where the modifier is '
+        'defined based on other modifiers.'
+    )
+
+    r_emittance: float = Field(
+        default=0.0,
+        ge=0,
+        le=1,
+        description='A value between 0 and 1 for the red channel of the modifier.'
+    )
+
+    g_emittance: float = Field(
+        default=0.0,
+        ge=0,
+        le=1,
+        description='A value between 0 and 1 for the green channel of the modifier.'
+    )
+
+    b_emittance: float = Field(
+        default=0.0,
+        ge=0,
+        le=1,
+        description='A value between 0 and 1 for the blue channel of the modifier.'
+    )
+
+
+class Glow(Light):
+    """Radiance Glow material."""
+
+    type: constr(regex='^Glow$') = 'Glow'
+
+    max_radius: float = Field(
+        default=0,
+        description='Maximum radius for shadow testing. Objects with zero radius '
+        'are permissable and may participate in interreflection calculation (though '
+        'they are not representative of real light sources). Negative values will '
+        'never contribute to scene illumination.'
+    )
+
+
+# Union Modifier Schema objects defined for type reference
+_REFERENCE_UNION_MODIFIERS = \
+    Union[Plastic, Glass, BSDF, Glow, Light, Trans, Metal, Void, Mirror]
+
+# Required for self.referencing model
+# see https://pydantic-docs.helpmanual.io/#self-referencing-models
+Mirror.update_forward_refs()
+Plastic.update_forward_refs()
+Glass.update_forward_refs()
+BSDF.update_forward_refs()
+Glow.update_forward_refs()
+Light.update_forward_refs()
+Trans.update_forward_refs()
+Metal.update_forward_refs()
+Void.update_forward_refs()