This primer provides an overview of the Honeybee Radiance components for Grasshopper.

Honeybee-radiance extends the core capabilities of the honeybee plugin to enable enable simulation of models in Radiance.

Installation

See the Wiki of the lbt-grasshopper repository for the installation instructions for the entire Ladybug Tools Grasshopper plugin (including honeybee-grasshopper-radiance).

Resources

Post your questions to Ladybug Tools forum and see the honeybee-grasshopper-radiance repository for source code.

Please let us know if you find any mistakes in grammar or spelling in this primer and we will gladly fix them.

- [source code]

Create a StateGeometry object that can be assigned to the shades_ of a dynamic state using the "HB Dynamic State" component.

Inputs

• geo [Required]

  Rhino Brep or Mesh geometry to be converted to StateGeometry.

• name

  Text to set the name for the StateGeometry and to be incorporated into unique StateGeometry identifier. If the name is not provided, a random name will be assigned.

• modifier

  A Honeybee Radiance Modifier object for the geometry. If None, it will be the Generic Exterior Shade modifier in the lib. (Default: None).

Outputs

• geo

  A Honeybee StateGeometry object representing planar geometry that can be assigned to Radiance states. This can be assigned using the "HB Dynamic State" component.

• Face Radiance Attributes

• Room Radiance Attributes

• Automatic Aperture Group

• Dynamic Aperture Group

• Dynamic State

• Dynamic State Geometry

• Radial Grid from Rooms

• Sensor Grid

• Sensor Grid from Apertures

• Sensor Grid from Rooms

• View

• View from Viewport

• Assign Grids and Views

• Get Grids and Views

• Dynamic Shade Group

• Get Dynamic Groups

• Radial Sensor Grid

• Section Plane View

• Sensor Grid from Faces

- [source code]

List of all radiance attirbutes assigned to Honeybee Rooms.

- [source code]

Combine Honeybee Apertures into a single dynamic group. Apertures that are a part of the same dynamic group will have their states change in unison. If an aperture has no dynamic group, it is assumed to be static.

This component can also be used to combine apertures that already have states assigned to them into one group since existing states are not overwritten if nothing is connected to states_. In this case, the total number of states in the dynamic group is equal to that of the object with the highest number of states. After a dynamic aperture with fewer states than that of it's dynamic group has hit its highest state, it remains in that state as the other dynamic apertures continue to change.

Inputs

• apertures [Required]

  A list of Honeybee Apertures to be grouped together into a single dynamic group. Door objects can also be connected here to be included in the group.

• name

  Text to be incorporated into a unique identifier for the dynamic Aperture group. If the name is not provided, a random name will be assigned.

• states

  An optional list of Honeybee State objects ordered based on how they will be switched on. The first state is the default state and, typically, higher states are more shaded. If the objects in the group have no states, the modifiers already assigned the apertures will be used for all states.

Outputs

• group_aps

  Honeybee apertures that are a part of the same dynamic group. These can be used directly in radiance simulations or can be added to Honeybee faces and rooms.

-

Create a Honeybee View for an image-based analysis using a Rhino viewport.

Inputs

• name

Text to set the name for the modifier and to be incorporated into a unique modifier identifier.

• viewport

The Rhino viewport name which will be used to generate a radiance View object. Typical inputs include "Perspective", "Top", "Bottom", "Left", "Right", "Front", "Back" or any viewport name that you have saved within the Rhino file. If no text is input here, the default will be the currently active viewport (the last viewport in which you navigated).

• view_type

An integer to set the view type (-vt). Choose from the choices below. Default: 0 if the viewport is in perspective; 2 if it is parallel.

• refresh

Connect a Grasshopper "button" component to refresh the orientation upon hitting the button.

Outputs

• view

A Honeybee View object that can be used in a view-based recipe.

- [source code]

Add radiance Sensor Grids and/or Views to a Honeybee Model.

This assignment is necessary for any Radiance study, though whether a grid or a view is required for a particular type of study is depenednet upon the recipe used.

Multiple copies of this component can be used in series and each will add the grids or views to any that already exist.

Inputs

• model [Required]

A Honeybee Model to which the input grids_ and views_ will be assigned.

• grids

A list of Honeybee-Radiance SensorGrids, which will be assigned to the input _model.

• views

A list of Honeybee-Radiance Views, which will be assigned to the input _model.

Outputs

• model

The input Honeybee Model with the grids_ and views_ assigned to it.

-

Get Radiance Sensor Grids and/or Views from a Honeybee Model and visualize them in the Rhino scene.

Inputs

• model [Required]

  A Honeybee Model for which grids and views will be output.

Outputs

• views

  A list of Honeybee-Radiance Views that are assigned to the input _model.

• grids

  A list of Honeybee-Radiance SensorGrids that are assigned to the input _model.

• points

  The points that are at the center of each grid cell.

• meshes

  Mesh for each sensor grid, which can be passed to the "LB Spatial Heatmap" component.

- [source code]

Calculate Aperture groups for exterior Apertures.

The Apertures are grouped by orientation unless view_factor is set to True.

If grouping based on view factor the component calculates view factor from Apertures to sky patches (rfluxmtx). Each Aperture is represented by a sensor grid, and the view factor for the whole Aperture is the average of the grid. The RMSE of the view factor to each sky patch is calculated between all Apertures. Agglomerative hierarchical clustering (with complete-linkage method) is used to group the Apertures by using a distance matrix of the RMSE values. The view factor approach is Radiance-based (and slower) and will likely group Apertures more accurately considering the context geometry of the Honeybee Model.

Inputs

• model [Required]

A Honeybee Model for which Apertures will be grouped automatically. Note that this model must have Apertures with Outdoors boundary condition assigned to it.

• room_based

A boolean to note whether the Apertures should be grouped on a room basis. If grouped on a room basis Apertures from different room cannot be in the same group. (Default: True).

• view_factor

A boolean to note whether the Apertures should be grouped by calculating view factors for the Apertures to a discretized sky or simply by the normal orientation of the Apertures. (Default: False).

• size

Aperture grid size for view factor calculation. A lower number will give a finer grid and more accurate results but the calculation time will increase. This option is only used if view_factor is set to True. (Default: 0.2).

• vert_tolerance

A float value for vertical tolerance between two Apertures. If the vertical distance between two Apertures is larger than this tolerance the Apertures cannot be grouped. If no value is given the vertical grouping will be skipped. (Default: None).

• states

An optional list of Honeybee State objects to be applied to all the generated groups. These states should be ordered based on how they will be switched on. The first state is the default state and, typically, higher states are more shaded. If the objects in the group have no states, the modifiers already assigned the apertures will be used for all states.

• run [Required]

Set to True to run the automatic Aperture grouping.

Outputs

• model

The input Honeybee Model object where all Apertures with Outdoors boundary condition have been assigned a dynamic group identifier.

- [source code]

List of all radiance attirbutes assigned to Honeybee Faces and Subfaces.

- [source code]

Create a State object representing a single dynamic group state.

Inputs

• modifier

  A Honeybee Radiance Modifier object to be applied to this state's parent in this state. This is used to swap out the modifier in multi-phase studies. If None, it will be the parent's default modifier.

• shades

  An optional array of StateGeometry objects to be included with this state.

Outputs

• state

  A Honeybee State object representing a single dynamic group state. This can be assigned to apertures or shades using the "HB Dynamic Aperture Group" componet or the "HB Dynamic Shade Group" component.

- [source code]

Generate SensorGrids of radial directions around positions from the floors of rooms.

This type of sensor grid is particularly helpful for studies of multiple view directions, such as imageless glare studies.

The names of the grids will be the same as the rooms that they came from.

Inputs

• rooms [Required]

A list of honeybee Rooms for which sensor grids will be generated. This can also be an entire Honeybee Model from which Rooms will be extracted.

• grid_size [Required]

Number for the size of the grid cells.

• dist_floor

Number for the distance to move points from the floors of the input rooms. (Default: 1.2 meters).

• dir_count

A positive integer for the number of radial directions to be generated around each position. (Default: 8).

• start_vec

A Vector3D to set the start direction of the generated directions. This can be used to orient the resulting sensors to specific parts of the scene. It can also change the elevation of the resulting directions since this start vector will always be rotated in the XY plane to generate the resulting directions. (Default: (0, -1, 0)).

• wall_offset

A number for the distance at which sensors close to walls should be removed.

Outputs

• grid

A SensorGrid object that can be used in a grid-based recipe.

• points

The points that are at the center of each circle. These align with the vecs output below and can be visualized with the native Grasshopper vector display component.

• vecs

The vectors for the directions of each sensor. These align with the points output above and can be visualized with the native Grasshopper vector display component.

• mesh

Analysis mesh that can be passed to the 'Spatial Heatmap' component.

- [source code]

Create a Honeybee View for an image-based analysis.

Inputs

• name

Text to set the name for the modifier and to be incorporated into a unique modifier identifier.

• position [Required]

An point to set the position of the view in 3D space (-vp). This is the focal point of a perspective view or the center of a parallel projection.

• direction [Required]

A vector for the direction that the veiw is facing (-vd). The length of this vector indicates the focal distance as needed by the pixel depth of field (-pd) in rpict.

• up_vector

An optional vector to set the vertical direction of the view (-vu). (Default: (0, 0, 1)).

• view_type

An integer to set the view type (-vt). Choose from the choices below. (Default: 0).

* 0 Perspective (v)

* 1 Hemispherical fisheye (h)

* 2 Parallel (l)

* 3 Cylindrical panorama (c)

* 4 Angular fisheye (a)

* 5 Planisphere [stereographic] projection (s)For more detailed description about view types check rpict manual page (http://radsite.lbl.gov/radiance/man_html/rpict.1.html) 

• h_angle

A number for the view horizontal size (-vh) in degrees. For a perspective projection (including fisheye views), val is the horizontal field of view. For a parallel projection, val is the view width in world coordinates. (Default: 60).

• v_angle

A number for the view vertical size (-vv) in degrees. For a perspective projection (including fisheye views), val is the horizontal field of view. For a parallel projection, val is the view width in world coordinates. (Default: 60).

Outputs

• view

A Honeybee View object that can be used in an view-based recipe.

- [source code]

Create a Sensor Grid object that can be used in a grid-based recipe.

Inputs

• name

A name for this sensor grid.

• positions [Required]

A list or a datatree of points with one point for the position of each sensor. Each branch of the datatree will be considered as a separate sensor grid.

• directions

A list or a datatree of vectors with one vector for the direction of each sensor. The input here MUST therefor align with the input _positions. If no value is provided (0, 0, 1) will be assigned for all the sensors.

• mesh

An optional mesh that aligns with the sensors. This is useful for generating visualizations of the sensor grid beyond the sensor positions. Note that the number of sensors in the grid must match the number of faces or the number vertices within the mesh.

• base_geo

An optional Brep for the geometry used to make the grid. There are no restrictions on how this brep 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.

Outputs

• grid

An SensorGrid object that can be used in a grid-based recipe.

- [source code]

Create a Bidirectional Scattering Distribution Function (BSDF) radiance modifier from an XML file.

Inputs

• xml_file [Required]

Path to an XML file contining BSDF data. These files can be produced using the LBNL WINDOW software among other sources.

• up_vec

A vector that sets the hemisphere that the BSDF modifier faces. For materials that are symmetrical about the face plane (like non-angled venetian blinds), this can be any vector that is not perfectly normal/perpendicular to the face. For asymmetrica materials like angled venetian blinds, this variable should be coordinated with the direction that the geometry is facing. The default is set to (0.01, 0.01, 1.00), which should hopefully not be normal to any typical face.

• thickness

Optional number to set the thickness of the BSDF. Thickness is not supported for aBSDF type. (Default: 0).

• bsdf_type

An integer to set the bsdf type. Choose from the choices below. (Default: 0).

* 0 BSDF

* 1 aBSDFChoose aBSDF (peak extraction) for systems with a strong specular transmission component. A proposed guideline for when to use aBSDF can be found in chapter 6 in "BSDF generation procedures for daylighting systems". Find the white paper at: 

* https://task61.iea-shc.org/publications

Outputs

• modifier

A BSDF modifier that can be assigned to a Honeybee geometry or Modifier Sets.

- [source code]

Generate SensorGrid objects from exterior Apertures.

These SensorGrids can be used in any grid-based recipe and are particularly useful for irradiance studies that evaluate solar gain of buildings, such as peak solar irradiance studies.

Inputs

• hb_objs [Required]

A list of honeybee Faces or Rooms for which sensor grids will be generated. This can also be an entire Honeybee Model.

• grid_size [Required]

Number for the size of the grid cells.

• offset

Number for the distance to move points from the base geometry. Positive numbers indicate an offset towards the exterior while negative numbers indicate an offset towards the interior, essentially modeling the value of trasnmitted sun through the glass. The default is 0.1 meters.

• ap_type

Text or an integer to specify the type of aperture that will be used to generate grids. Choose from the following. (Default: All).

* 1 - Window

* 2 - Skylight

* 3 - All

• quad_only

Boolean to note whether meshing should be done using Rhino's defaults (False), which fills the entire aperture geometry to the edges with both quad and tringulated faces, or a mesh with only quad faces should be generated. (Default: False).

Outputs

• grid

A SensorGrid object that can be used in a grid-based recipe.

• points

The points that are at the center of each grid cell.

• mesh

Analysis mesh that can be passed to the 'Spatial Heatmap' component.

- [source code]

Generate SensorGrid objects from the floors of honeybee Rooms. These SensorGrids can be used in a grid-based recipe.

The names of the grids will be the same as the rooms that they came from.

Inputs

• rooms [Required]

A list of honeybee Rooms for which sensor grids will be generated. This can also be an entire Honeybee Model from which Rooms will be extracted.

• grid_size [Required]

Number for the size of the grid cells.

• dist_floor

Number for the distance to move points from the floors of the input rooms. The default is 0.8 meters.

• quad_only

Boolean to note whether meshing should be done using Rhino's defaults (False), which fills the entire floor geometry to the edges with both quad and tringulated faces, or a mesh with only quad faces should be generated. FOR ADVANCED USERS: This input can also be a vector object that will be used to set the orientation of the quad-only grid. Note that, if a vector is input here that is not aligned with the plane of the room's floors, an error will be raised.

• remove_out

Boolean to note whether an extra check should be run to remove sensor points that lie outside the Room volume. Note that this can add significantly to the component's run time and this check is usually not necessary in the case that all walls are vertical and all floors are horizontal (Default: False).

• wall_offset

A number for the distance at which sensors close to walls should be removed.

Outputs

• grid

A SensorGrid object that can be used in a grid-based recipe.

• points

The points that are at the center of each grid cell.

• mesh

Analysis mesh that can be passed to the 'Spatial Heatmap' component.

-

Combine Honeybee Shades into a single dynamic group. Shades that are a part of the same dynamic group will have their states change in unison. If an shade has no dynamic group, it is assumed to be static.

This component can also be used to combine shades that already have states assigned to them into one group since existing states are not overwritten if nothing is connected to states_. In this case, the total number of states in the dynamic group is equal to that of the object with the highest number of states. After a dynamic shade with fewer states than that of it's dynamic group has hit its highest state, it remains in that state as the other dynamic shades continue to change.

Inputs

• shades [Required]

  A list of Honeybee Shades to be grouped together into a single dynamic group.

• name

  Text to be incorporated into a unique identifier for the dynamic Shade group. If the name is not provided, a random name will be assigned.

• states

  An optional list of Honeybee State objects ordered based on how they will be switched on. The first state is the default state and, typically, higher states are more shaded. If the objects in the group have no states, the modifiers already assigned the shades will be used for all states.

Outputs

• group_shds

  Honeybee shades that are a part of the same dynamic group. These can be used directly in radiance simulations or can be added to Honeybee faces and rooms.

- [source code]

Search for available Mofidier Sets within the honeybee standards library.

Inputs

• keywords

Optional keywords to be used to narrow down the output list of modifier sets. If nothing is input here, all available modifier sets will be output.

• join_words

If False or None, this component will automatically split any strings of multiple keywords (spearated by spaces) into separate keywords for searching. This results in a greater liklihood of finding an item in the search but it may not be appropropriate for all cases. You may want to set it to True when you are searching for a specific phrase that includes spaces. Default: False.

Outputs

• mod_sets

A list of modifier sets within the honeybee radiance standards library (filtered by keywords_ if they are input).

- [source code]

Apply a section plane to a Honeybee Radiance View.

The plane will always 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.

Objects in front of this imaginary plane will not be visible. This may be useful for seeing through walls (to get a longer perspective from an exterior view point) or for incremental rendering.

Inputs

• view [Required]

A Honeybee Radiance View object to which a section plane should be applied.

• origin [Required]

An point to set the origin of the section plane in 3D space. Note that the section plane is always perpenicular to the view direction for perspective and parallel views.

Outputs

• view

A Honeybee View object that can be used in a view-based recipe.

- [source code]

Create a Sensor Grid object from radial directions around sensor positions.

This type of sensor grid is particularly helpful for studies of multiple view directions, such as imageless glare studies.

Inputs

• name

A name for this sensor grid.

• positions [Required]

A list or a datatree of points with one point for the position of each radial sensor. Each branch of the datatree will be considered as a separate sensor grid.

• dir_count

A positive integer for the number of radial directions to be generated around each position. (Default: 8).

• start_vec

A Vector3D to set the start direction of the generated directions. This can be used to orient the resulting sensors to specific parts of the scene. It can also change the elevation of the resulting directions since this start vector will always be rotated in the XY plane to generate the resulting directions. (Default: (0, -1, 0)).

• mesh_radius

An optional number that can be used to generate a mesh that is aligned with the resulting sensors and will automatically be assigned to the grid. Such meshes will resemble a circle around each sensor with the specified radius and will contain triangular faces that can be colored with simulation results. If zero, no mesh will be generated for the sensor grid. (Default: 0.2 meters).

Outputs

• grid

An SensorGrid object that can be used in a grid-based recipe.

• points

Script variable SensorGrid

• vecs

Script variable SensorGrid

• mesh

Analysis mesh that can be passed to the 'Spatial Heatmap' component.

- [source code]

Get all of the Dynamic Radiance Groups assigned to a Model.

Inputs

• model [Required]

A Honeybee Model for which dynamic groups will be output.

Outputs

• group_ids

The identifiers of the dynamic groups assigned to the Model.

• group_aps

A data tree of Dynamic Apertures in the Model. Each branch of the tree represents a different Dynamic Aperture Group and corresponds to the group_ids above. The data tree can be exploded with the native Grasshopper "Explod Tree" component to assign schedules to each Dynamic Group for postprocessing.

-

Search for available Mofidiers within the honeybee standards library.

Inputs

• keywords

Optional keywords to be used to narrow down the output list of modifiers. If nothing is input here, all available modifiers will be output.

• join_words

If False or None, this component will automatically split any strings of multiple keywords (spearated by spaces) into separate keywords for searching. This results in a greater liklihood of finding an item in the search but it may not be appropropriate for all cases. You may want to set it to True when you are searching for a specific phrase that includes spaces. Default: False.

Outputs

• modifiers

A list of modifiers within the honeybee radiance standards library (filtered by keywords_ if they are input).

-

Generate SensorGrid objects from exterior Faces (Walls, Roofs, and Floors).

These SensorGrids can be used in any grid-based recipe and are particularly useful for radiation studies of roofs for photovoltaic potential or solar gain studies of walls.

Inputs

• hb_objs [Required]

A list of honeybee Faces or Rooms for which sensor grids will be generated. This can also be an entire Honeybee Model.

• grid_size [Required]

Number for the size of the grid cells.

• offset

Number for the distance to move points from the base geometry. The default is 0.1 meters.

• face_type

Text or an integer to specify the type of face that will be used to generate grids. Note that only Faces with Outdoors boundary conditions will be used, meaning that most Floors will typically be excluded unless they represent the underside of a cantilever. Choose from the following. (Default: Wall).

• punched

Boolean to note whether the punched_geometry of the faces should be used (True) with the areas of sub-faces removed from the grid or the full geometry should be used (False). (Default:False).

• quad_only

Boolean to note whether meshing should be done using Rhino's defaults (False), which fills the entire face geometry to the edges with both quad and tringulated faces, or a mesh with only quad faces should be generated. (Default: False).

Outputs

• grid

A SensorGrid object that can be used in a grid-based recipe.

• points

The points that are at the center of each grid cell.

• mesh

Analysis mesh that can be passed to the 'Spatial Heatmap' component.

- [source code]

Create a translucent radiance modifier from a reflectance and transmittance.

The sum of the reflectances and transmittances must be less than 1 and any energy not transmitted or reflected is assumed to be absorbed. The resulting material will always be grey with equivalent red, green and blue channels.

Inputs

• name

Text to set the name for the modifier and to be incorporated into a unique modifier identifier.

• diff_ref [Required]

A number between 0 and 1 for the diffuse reflectance of the material.

• diff_trans [Required]

A number between 0 and 1 for the transmitted diffuse component. This is the fraction of transmitted light that is diffusely scattered.

• spec_trans

A number between 0 and 1 for the transmitted specular component. This is the fraction of transmitted light that is not diffusely scattered but passes through like a beam. (Default: 0).

• spec

A number between 0 and 1 for the fraction of specularity. Specularity fractions greater than 0.1 are not common in non-metallic materials. (Default: 0).

• rough

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).

Outputs

• modifier

A translucent modifier that can be assigned to a Honeybee geometry or Modifier Sets.

- [source code]

Create a mirror radiance modifier from a single reflectance.

Inputs

• name

  Text to set the name for the modifier and to be incorporated into a unique modifier identifier.

• reflect [Required]

  A number between 0 and 1 for the mirror reflectance. This reflectance will be the same for the red, green and blue channels.

Outputs

• modifier

  A mirror modifier that can be assigned to a Honeybee geometry or Modifier Sets.

- [source code]

Create an opaque radiance modifier from a single reflectance.

Inputs

• name

Text to set the name for the modifier and to be incorporated into a unique modifier identifier.

• reflect [Required]

A number between 0 and 1 for the absolute diffuse reflectance of the modifier. This reflectance will be the same for the red, green and blue channels.

• spec

A number between 0 and 1 for the absolute specular reflectance of the modifier. Note that the sum of this value and the diffuse _reflect should be less than one. Specular reflectances greater than 0.1 are rare for non-metallic materials. (Default: 0).

• rough

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).

Outputs

• modifier

An opaque modifier that can be assigned to a Honeybee geometry or Modifier Sets.

- [source code]

Create a metal radiance modifier from a single reflectance.

Inputs

• name

Text to set the name for the modifier and to be incorporated into a unique modifier identifier.

• diff

Script variable MetalMod

• spec

A number between 0 and 1 for the absolute specular reflectance of the modifier. Note that the sum of this value and the diffuse _reflect should be less than one. Specularity of metals is usually 0.9 or greater. (Default: 0.9)

• rough

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).

Outputs

• modifier

A metal modifier that can be assigned to a Honeybee geometry or Modifier Sets.

- [source code]

Create an glass radiance modifier from a single transmittance.

Inputs

• name

  Text to set the name for the modifier and to be incorporated into a unique modifier identifier.

• trans [Required]

  A number between 0 and 1 for the glass modifier transmittance. This transmittance will be the same for the red, green and blue channels.

• refract

  Index of refraction. Typical values are 1.52 for float glass and 1.4 for ETFE. If None, Radiance will default to using 1.52 for glass (Default: None).

Outputs

• modifier

  A glass modifier that can be assigned to a Honeybee geometry or Modifier Sets.

-

Create a list of interior modifiers that can be used to edit or create a ModifierSet object.

Inputs

• interior_wall

  A modifier object for interior walls (or text for the identifier of the modifier within the library).

• ceiling

  A modifier object for ceilings (or text for the identifier of the modifier within the library).

• interior_floor

  A modifier object for interior floors (or text for the identifier of the modifier within the library).

• interior_window

  A modifier object for all apertures with a Surface boundary condition. This can also be text for the identifier of the modifier within the library.

• interior_door

  A modifier object for all opaque doors with a Surface boundary condition. This can also be text for the identifier of the modifier within the library.

• int_glass_door

  A modifier object for all glass doors with a Surface boundary condition. This can also be text for the identifier of the modifier within the library.

Outputs

• interior_set

  A list of interior modifiers that can be used to edit or create a ModifierSet object.

-

Create a ModifierSet object containing all radiance modifiers needed to create an radiance model. ModifierSets can be assigned to Honeybee Rooms to specify all default modifiers on the Room.

Inputs

• name

  Text to set the name for the ModifierSet and to be incorporated into a unique ModifierSet identifier. If None, a random one will be genrated.

• base_mod_set

  An optional ModifierSet object that will be used as the starting point for the new ModifierSet output from this component. This can also be text for the name of a ModifierSet within the library such as that output from the "HB Search Modifier Sets" component. If None, the Honeybee "Generic Default Modifier Set" will be used as the base.

• exterior_subset

  A modifier subset list from the "HB Exterior Modifier Subset" component. Note that None values in this list correspond to no change to the given modifier in the basemod_set.

• interior_subset

  A modifier subset list from the "HB Interior Modifier Subset" component. Note that None values in this list correspond to no change to the given modifier in the basemod_set.

• subface_subset

  A modifier subset list from the "HB Subface Subset" component. Note that None values in this list correspond to no change to the given modifier in the basemod_set.

• shade_subset

  A modifier subset list from the "HB Shade Modifier Subset" component. Note that None values in this list correspond to no change to the given modifier in the basemod_set.

Outputs

• mod_set

  A ModifierSet object that can be assigned to Honeybee Rooms in order to specify all default modifiers on the Room.

-

Deconstruct a modifier set into its constituient interior modifiers.

Inputs

• mod_set [Required]

  A modifier set to be deconstructed. This can also be text for a modifier set to be looked up in the modifier set library.

Outputs

• interior_wall

  A modifier object for the set's interior walls.

• ceiling

  A modifier object for the set's interior roofs.

• interior_floor

  A modifier object for the set's interior floors.

• interior_window

  A modifier object for all apertures with a Surface boundary condition.

• interior_door

  A modifier object for all opaque doors with a Surface boundary condition.

• int_glass_door

  A modifier object for all glass doors with a Surface boundary condition.

• interior_shade

  A modifier object for all interior shades.

-

Create a list of exterior modifiers that can be used to edit or create a ModifierSet object.

Inputs

• exterior_wall

  A modifier object for exterior walls (or text for the identifier of the modifier within the library).

• exterior_roof

  A modifier object for exterior roofs (or text for the identifier of the modifier within the library).

• exposed_floor

  A modifier object for exposed floors (or text for the identifier of the modifier within the library).

Outputs

• exterior_set

  A list of exterior modifiers that can be used to edit or create a ModifierSet object.

- [source code]

Create a list of modifiers that can be used to edit or create a ModifierSet object.

Inputs

• exterior_shade

  A modifier object for exterior shades (or text for the identifier of the modifier within the library).

• interior_shade

  A modifier object for interior shades (or text for the identifier of the modifier within the library).

Outputs

• shade_set

  A list of shade modifiers that can be used to edit or create a ModifierSet object.

- [source code]

Create a list of exterior subface (apertures + doors) modifiers that can be used to edit or create a ModifierSet object.

Inputs

• window

  A modifier object for apertures with an Outdoors boundary condition and a Wall face type for their parent face. This can also be text for the identifier of the modifier within the library.

• skylight

  A modifier object for apertures with an Outdoors boundary condition and a RoofCeiling or Floor face type for their parent face. This can also be text for the identifier of the modifier within the library.

• operable

  A modifier object for apertures with an Outdoors boundary condition and True is_operable property. This can also be text for the identifier of the modifier within the library.

• exterior_door

  A modifier object for opaque doors with an Outdoors boundary condition and a Wall face type for their parent face. This can also be text for the identifier of the modifier within the library.

• overhead_door

  A modifier object for opaque doors with an Outdoors boundary condition and a RoofCeiling or Floor face type for their parent face. This can also be text for the identifier of the modifier within the library.

• glass_door

  A modifier object for all glass doors with an Outdoors boundary condition. This can also be text for the identifier of the modifier within the library.

Outputs

• subface_set

  A list of exterior subface modifiers that can be used to edit or create a ModifierSet object.

- [source code]

Deconstruct a modifier set into its constituient exterior modifiers.

Inputs

• mod_set [Required]

  A modifier set to be deconstructed. This can also be text for a modifier set to be looked up in the modifier set library.

Outputs

• exterior_wall

  A modifier object for the set's exterior walls.

• exterior_roof

  A modifier object for the set's exterior roofs.

• exposed_floor

  A modifier object for the set's exposed floors.

• window

  A modifier object for apertures with an Outdoors boundary condition and a Wall face type for their parent face.

• skylight

  A modifier object for apertures with an Outdoors boundary condition and a RoofCeiling or Floor face type for their parent face.

• operable

  A modifier object for apertures with an Outdoors boundary condition and True is_operable property.

• exterior_door

  A modifier object for opaque doors with an Outdoors boundary condition and a Wall face type for their parent face.

• overhead_door

  A modifier object for opaque doors with an Outdoors boundary condition and a RoofCeiling or Floor face type for their parent face.

• glass_door

  A modifier object for all glass doors with an Outdoors boundary condition.

• exterior_shade

  A modifier object for all exterior shades.

-

Apply ModifierSet to Honeybee Rooms.

Inputs

• rooms [Required]

Honeybee Rooms to which the input _mod_set should be assigned. This can also be a Honeybee Model for which all Rooms will be assigned the ModifierSet.

• mod_set [Required]

A Honeybee ModifierSet to be applied to the input _room. This can also be text for a modifier set to be looked up in the modifier set library.

Outputs

• rooms

The input Rooms with their modifier sets edited.

-

Apply a Modifier to Honeybee Faces, Doors or Room walls.

This component supports the assigning of different modifiers based on cardinal orientation, provided that a list of Modifiers are input to the _mod.

Inputs

• hb_objs [Required]

Honeybee Faces, Doors, Rooms or a Model to which the input _mod should be assigned. For the case of Rooms or a Model, the modifier will only be applied to the Room's outdoor walls. Note that, if you need to assign a modifier to all the roofs, floors, etc. of a Room, the best practice is to create a ModifierSet and assing that to the Room.

• mod [Required]

A Honeybee Modifier to be applied to the input _hb_objs. This can also be text for a modifier to be looked up in the modifier library. If an array of text or modifier objects are input here, different modifiers will be assigned based on cardinal direction, starting with north and moving clockwise.

Outputs

• hb_objs

The input honeybee objects with their modifiers edited.

-

Apply a Modifier to Honeybee Shade objects. Alternatively, it can assign a Modifier to all of the child shades of an Aperture, Door, Face, or a Room.

This component supports the assigning of different modifiers based on cardinal orientation, provided that a list of Modifiers are input to the _mod.

Inputs

• hb_objs [Required]

Honeybee Shades, Apertures, Doors, Faces, Rooms, or a Model to which the input _mod should be assigned. For the case of a Honeybee Aperture, Door, Face, Room or Model, the Modifier will be assigned to only the child shades directly assigned to that object. So passing in a Room will not change the modifier of shades assigned to Apertures of the Room's Faces. If this is the desired outcome, then the Room should be deconstructed into its child objects before using this component.

• mod [Required]

A Honeybee Modifier to be applied to the input _hb_objs. This can also be text for a modifier to be looked up in the shade modifier library. If an array of text or modifier objects are input here, different modifiers will be assigned based on cardinal direction, starting with north and moving clockwise.

Outputs

• hb_objs

The input honeybee objects with their modifiers edited.

- [source code]

Create an glass radiance modifier from a red, green, and blue transmittances

Inputs

• name

  Text to set the name for the modifier and to be incorporated into a unique modifier identifier.

• r_trans [Required]

  A number between 0 and 1 for the transmittance of the red channel. (Default: 0).

• g_trans [Required]

  A number between 0 and 1 for the transmittance of the green channel. (Default: 0).

• b_trans [Required]

  A number between 0 and 1 for the transmittance of the blue channel. (Default: 0).

• refract

  Index of refraction. Typical values are 1.52 for float glass and 1.4 for ETFE. If None, Radiance will default to using 1.52 for glass (Default: None).

Outputs

• modifier

  A glass modifier that can be assigned to a Honeybee geometry or Modifier Sets.

- [source code]

Apply Modifier to Honeybee Apertures or glass Doors. Alternatively, it can assign Modifiers to the child apertures of input Faces or the apertures within Room walls.

This component supports the assigning of different modifiers based on cardinal orientation, provided that a list of Modifiers are input to the _mod.

Inputs

• hb_objs [Required]

Honeybee Apertures, Faces, Doors, Rooms or a Model to which the input _mod should be assigned. For the case of Rooms or a Model, the modifier will only be applied to the apertures in the the Room's outdoor walls. Note that, if you need to assign a modifier to all the skylights, glass doors, etc. of a Room, the best practice is to create a ModifierSet and assing that to the Room.

• mod [Required]

A Honeybee Modifier to be applied to the input _hb_objs. This can also be text for a modifier to be looked up in the window modifier library. If an array of text or modifier objects are input here, different modifiers will be assigned based on cardinal direction, starting with north and moving clockwise.

Outputs

• hb_objs

The input honeybee objects with their modifiers edited.

-

Deconstruct a modifier into a radiance string.

Inputs

• mod [Required]

  A modifier to be deconstructed or text for a modifier to be looked up in the modifier library.

Outputs

• rad_str

  A Radiance string that includes all of the attributes that define the modifier.

- [source code]

Create an opaque radiance modifier from red, green, and blue reflectances.

Inputs

• name

Text to set the name for the modifier and to be incorporated into a unique modifier identifier.

• r_ref [Required]

A number between 0 and 1 for the absolute diffuse red reflectance.

• g_ref [Required]

A number between 0 and 1 for the absolute diffuse green reflectance.

• b_ref [Required]

A number between 0 and 1 for the absolute diffuse blue reflectance.

• spec

A number between 0 and 1 for the absolute specular reflectance of the modifier. Note that the sum of this value and the diffuse should be less than one. Specular reflectances greater than 0.1 are rare for non-metallic materials. (Default: 0).

• rough

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).

Outputs

• modifier

An opaque modifier that can be assigned to a Honeybee geometry or Modifier Sets.

- [source code]

Create a metal radiance modifier from red, green, and blue reflectances.

Inputs

• name

Text to set the name for the modifier and to be incorporated into a unique modifier identifier.

• r_diff

A number between 0 and 1 for the absolute diffuse red reflectance. (Default: 0).

• g_diff

A number between 0 and 1 for the absolute diffuse green reflectance. (Default: 0).

• b_diff

A number between 0 and 1 for the absolute diffuse blue reflectance. (Default: 0).

• spec

A number between 0 and 1 for the absolute specular reflectance of the modifier. Note that the sum of this value and the diffuse should be less than one. Specularity of metals is usually 0.9 or greater. (Default: 0.9)

• rough

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).

Outputs

• modifier

A metal modifier that can be assigned to a Honeybee geometry or Modifier Sets.

- [source code]

Create a translucent radiance modifier from reflectances and transmittances.

The sum of the reflectances and transmittances must be less than 1 and any energy not transmitted or reflected is assumed to be absorbed.

Inputs

• name

Text to set the name for the modifier and to be incorporated into a unique modifier identifier.

• r_diff_ref [Required]

A number between 0 and 1 for the red diffuse reflectance.

• g_diff_ref [Required]

A number between 0 and 1 for the green diffuse reflectance.

• b_diff_ref [Required]

A number between 0 and 1 for the blue diffuse reflectance.

• diff_trans [Required]

A number between 0 and 1 for the transmitted diffuse component. This is the fraction of transmitted light that is diffusely scattered.

• spec_trans

A number between 0 and 1 for the transmitted specular component. This is the fraction of transmitted light that is not diffusely scattered but passes through like a beam. (Default: 0).

• spec

A number between 0 and 1 for the fraction of specularity. Specularity fractions greater than 0.1 are not common in non-metallic materials. (Default: 0).

• rough

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).

Outputs

• modifier

A translucent modifier that can be assigned to a Honeybee geometry or Modifier Sets.

- [source code]

Create an mirror radiance modifier from a single reflectance.

Inputs

• name

  Text to set the name for the modifier and to be incorporated into a unique modifier identifier.

• r_ref [Required]

  A number between 0 and 1 for the red reflectance.

• g_ref [Required]

  A number between 0 and 1 for the green reflectance.

• b_ref [Required]

  A number between 0 and 1 for the blue reflectance.

Outputs

• modifier

  An mirror modifier that can be assigned to a Honeybee geometry or Modifier Sets.

-

Create a point-in-time standard Radiance CIE sky.

Inputs

• north

  A number between 0 and 360 that represents the degrees off from the y-axis to make North. This can also be a vector to set the North. Default is 0. The default North direction is the Y-axis (0 degrees).

• location [Required]

  A Ladybug location object.

• month

  An integer between 1 and 12 for the month of the year (default: 6).

• day

  An integer between 1 and 31 for the day of the month (default: 21).

• hour

  A number between 0 and 23.999 for the hour of the day (default: 12).

• type

  An integer between 0..5 to indicate CIE Sky Type (default: 0).

  • 0 = Sunny with sun

  • 1 = sunny without sun

  • 2 = intermediate with sun

  • 3 = intermediate without sun

  • 4 = cloudy sky

  • 5 = uniform sky

Outputs

• sky

  A honeybee sky that can be used to create a point-in-time recipe.

-

Create a uniform sky that yields a certain illuminance.

Inputs

• value

  Desired value for sky horizontal illuminance in lux. (Default: 10000).

Outputs

• sky

  A honeybee sky that can be used to create a point-in-time recipe.

-

Create a WEA object using the original ASHRAE Clear Sky formula.

Inputs

• location [Required]

  A Ladybug Location object which will set the sun poisition for the clear sky Wea. Locations can be obtained from the "LB Import EPW" or the "LB Construct Location" component.

• clearness

  A factor to be multiplied by the output of the clear sky model. This is to help account for locations where clear, dry skies predominate (e.g., at high elevations) or, conversely, where hazy and humid conditions are frequent. See Threlkeld and Jordan (1958) for recommended values. Typical values range from 0.95 to 1.05 and are usually never more than 1.2. (Default: 1.0).

• hoys

  An optional list of hours of the year (numbers from 0 to 8759) for which the Wea will be filtered. HOYs can be generated from the "LB Analysis Period" component or they can be obtained through other means like analysis of the values in an occupancy schedule. By default, the Wea will be generated for the whole year.

• timestep

  An integer representing the timestep with which to make the WEA object. (Default: 1, for 1 step per hour of the year).

Outputs

• wea

  A wea object from stat file. This wea object represents an original ASHRAE Clear Sky, which is intended to determine peak solar load and sizing parmeters for HVAC systems.

-

Create a point-in-time climate-based sky from a Wea.

Inputs

• north

A number between 0 and 360 that represents the degrees off from the y-axis to make North. This can also be a vector to set the North. Default is 0. The default North direction is the Y-axis (0 degrees).

• wea [Required]

A Ladybug Wea object.

• month

An integer between 1 and 12 for the month of the year (default: 6).

• day

An integer between 1 and 31 for the day of the month (default: 21).

• hour

A number between 0 and 23.999.. for the hour of the day (default: 12).

• colored

Boolean to note whether the sky will be rendered in full color (True) or it will simple be a grey sky with the same average value as the colored sky (False). (Default: False).

Outputs

• sky

A Honeybee sky that can be used to create a point-in-time recipe.

-

Create a Custom sky from direct and diffuse irradiance.

Inputs

• north

A number between 0 and 360 that represents the degrees off from the y-axis to make North. This can also be a vector to set the North. Default is 0. The default North direction is the Y-axis (0 degrees).

• location [Required]

A Ladybug location object.

• dir_rad [Required]

Direct normal irradiance (W/m2).

• diff_rad [Required]

Diffuse horizontal irradiance (W/m2).

• month

An integer between 1 and 12 for the month of the year (default: 6).

• day

An integer between 1 and 31 for the day of the month (default: 21).

• hour

A number between 0 and 23.999 for the hour of the day (default: 12).

• colored

Boolean to note whether the sky will be rendered in full color (True) or it will simple be a grey sky with the same average value as the colored sky (False). (Default: False).

Outputs

• sky

Honeybee sky. You can use this sky to create a daylight recipe.

- [source code]

Deconstruct a Wea object into data collections of direct, diffuse, and golbal irradiance at each timestep of the file.

Inputs

• wea [Required]

  A Honeybee WEA object.

Outputs

• dir

  A data collection of direct normal irradiance values at each timestep of the Wea.

• diff

  A data collection of diffuse sky solar irradiance values at each timestep of the Wea.

• glob

  A data collection of global horizontal irradiance values at each timestep of the Wea.

- [source code]

Create a Wea object from an EPW file.

Inputs

• epw_file [Required]

  Full path to an .epw weather file.

• hoys

  An optional list of hours of the year (numbers from 0 to 8759) for which the Wea will be filtered. HOYs can be generated from the "LB Analysis Period" component or they can be obtained through other means like analysis of the values in an occupancy schedule. By default, the Wea will be generated for the whole year.

• timestep

  An integer representing the timestep with which to make the WEA object. Default is set to 1 for 1 step per hour of the year.

Outputs

• wea

  A wea object from epw file.

- [source code]

Visualize a sky as a High Dynamic Range (HDR) image file.

Inputs

• sky [Required]

  A Radiance sky from any of the sky components under the "Light Sources" tab. Text string representations of skies are also acceptable.

• size

  A number for the X and Y dimension of the imgae in pixles. (Default: 500 px)

Outputs

• hdr

  Path to the High Dynamic Range (HDR) image file of the sky. This can be plugged into the Ladybug "Image Viewer" component to preview the image. It can also be plugged into the "HB False Color" component to convert the image into a false color version. Lastly, it can be connected to the "HB HDR to GIF" component to get a GIF image that is more portable and easily previewed by different software.

• ghi

  The global horizontal irradiance (W/m2) for an upstructed test point under the sky.

- [source code]

Create a WEA object for an ASHRAE Revised Clear Sky (Tau Model) using a STAT file.

Inputs

• stat_file [Required]

  Full path to .stat file that will be used to make the clear sky Wea. Note that an error will be raised if no atmospheric optical data is found in the file. In this case, the "HB Wea from Clear Sky" component can be used.

• hoys

  An optional list of hours of the year (numbers from 0 to 8759) for which the Wea will be filtered. HOYs can be generated from the "LB Analysis Period" component or they can be obtained through other means like analysis of the values in an occupancy schedule. By default, the Wea will be generated for the whole year.

• timestep

  An integer representing the timestep with which to make the WEA object. Default is set to 1 for 1 step per hour of the year.

Outputs

• wea

  A wea object from stat file. This wea object represents an ASHRAE Revised Clear Sky ("Tau Model"), which is intended to determine peak solar load and sizing parmeters for HVAC systems. The "Tau Model" uses monthly optical depths found within a .stat file.

-

Construct a WEA from hourly data collections and the Zhang-Huang Solar Model.

Inputs

• location [Required]

  A Ladybug Location object.

• cloud_cover [Required]

  Hourly DataCollection with the fraction of total sky cover (tenths of coverage). (eg. 1 is 1/10 covered. 10 is total coverage)

• rel_humidity [Required]

  Hourly DataCollection with relative humidity [%].

• dry_bulb_temp [Required]

  Hourly DataCollection with dry bulb temperature [C].

• wind_speed [Required]

  Hourly DataCollection with wind speed [m/s].

• atmos_pressure

  Hourly DataCollection with amtospheric pressure [Pa]. If no value is connected here, pressure at sea level will be assumed (101,325 Pa).

Outputs

• wea

  A wea object from the input data collections and the Zhang-Huang solar model.

- [source code]

Run an annual glare study for a Honeybee model to compute hourly Daylight Glare Probability (DGP) for each sensor in a model's sensor grids.

This recipe uses the image-less glare method developed by Nathaniel Jones to estimate glare at each sensor. More information on this method can be found here: https://github.com/nljones/Accelerad/wiki/The-Imageless-Method-for-Spatial-and-Annual-Glare-Analysis

The resulting DGP is used to compute Glare Autonomy (GA), which is the percentage of occupied time that a view is free of glare.

Inputs

• model [Required]

A Honeybee Model for which Annual Daylight Glare Probability (DGP) will be simulated. Note that this model must have grids assigned to it and, typically, these are radial grids created using the "radial grid" components.

• wea [Required]

A Wea object produced from the Wea components that are under the Light Sources tab. This can also be the path to a .wea or a .epw file. Note that the Wea must have a timestep of 1 to be used with this recipe.

• north

A number between -360 and 360 for the counterclockwise difference between the North and the positive Y-axis in degrees. This can also be Vector for the direction to North. (Default: 0).

• glare_thresh

A fractional number for the threshold of DGP above which conditions are considered to induce glare. This value is used when calculating glare autonomy, which is the percent of hours in which the view is free of glare. (Default: 0.4 for disturbing or intolerable glare).

• luminance_fac

Luminance factor in cd/m2. If the sky patch brightness is above this factor it will act as a glare source. (Default: 2000).

• schedule

An annual occupancy schedule, either as a Ladybug Hourly Continuous Data Collection or a HB-Energy schedule object. This can also be the path to a CSV file with 8760 rows or the identifier of a schedule in the honeybee-energy schedule library. Any value in this schedule that is 0.1 or above will be considered occupied.

• grid_filter

Text for a grid identifer or a pattern to filter the sensor grids of the model that are simulated. For instance, first_floor_* will simulate only the sensor grids that have an identifier that starts with first_floor_. By default, all grids in the model will be simulated.

• radiance_par

Text for the radiance parameters to be used for ray tracing. (Default: -ab 2 -ad 5000 -lw 2e-05).

• run_settings

Settings from the "HB Recipe Settings" component that specify how the recipe should be run. This can also be a text string of recipe settings.

• run [Required]

Set to True to run the recipe and get results. This input can also be the integer "2" to run the recipe silently.

Outputs

• report

Reports, errors, warnings, etc.

• results

Raw result files (.dgp) that contain Daylight Glare Probability (DGP) matrices for each sensor at each hour of the simulation. These can be postprocessed using various components under the 4::Results sub-tab.

• GA

Glare Autonomy (GA) results in percent. GA is the percentage of occupied hours that each view is free of glare (with a DGP below the glare threshold). These can be plugged into the "LB Spatial Heatmap" component along with meshes of the sensor grids to visualize results.

- [source code]

Run a point-in-time grid-based study for a Honeybee model.

Point-in-time recipes require a sky and can output illuminance, irradiance, luminance or radiance.

Inputs

• model [Required]

A Honeybee Model for which a point-in-time grid-based study will be run. Note that this model should have grids assigned to it in order to produce meaningfule results.

• sky [Required]

A Radiance sky from any of the sky components under the "Light Sources" tab. Skies can be either CIE, ClimateBased/Custom, or for a specific Illuminance/Irradiance. This input can also just be a text definition of a sky's paramters. Examples include:

* cie 21 Mar 9:00 -lat 41.78 -lon -87.75 -tz 5 -type 0

* climate-based 21 Jun 12:00 -lat 41.78 -lon -87.75 -tz 5 -dni 800 -dhi 120

* irradiance 0

• metric

Either an integer or the full name of a point-in-time metric to be computed by the recipe. (Default: illuminance). Choose from the following:

* 0 = illuminance

* 1 = irradiance

* 2 = luminance

* 3 = radiance

• grid_filter

Text for a grid identifer or a pattern to filter the sensor grids of the model that are simulated. For instance, first_floor_* will simulate only the sensor grids that have an identifier that starts with first_floor_. By default, all grids in the model will be simulated.

• radiance_par

Text for the radiance parameters to be used for ray tracing. (Default: -ab 2 -aa 0.1 -ad 2048 -ar 64).

• run_settings

Settings from the "HB Recipe Settings" component that specify how the recipe should be run. This can also be a text string of recipe settings.

• run [Required]

Set to True to run the recipe and get results. This input can also be the integer "2" to run the recipe silently.

Outputs

• report

Reports, errors, warnings, etc.

• results

Numbers for the point-in-time value at each sensor. Values are in the standard SI units of the requested input metric. These can be plugged into the "LB Spatial Heatmap" component along with meshes of the sensor grids to visualize results.

* illuminance = lux (aka. lm/m2)

* irradiance = W/m2

* luminance = cd/m2 (aka. lm/m2-sr)

* radiance = W/m2-sr

- [source code]

Run an annual irradiance study for a Honeybee model to compute hourly solar irradiance for each sensor in a model's sensor grids.

The fundamental calculation of this recipe is the same as that of "HB Annual Daylight" in that an enhaced 2-phase method is used to accurately account for direct sun at each simulation step. However, this recipe computes broadband solar irradiance in W/m2 instead of visible illuminance in lux.

Consequently, the average irradiance and cumulative radiation values produced from this recipe are more accurate than those produced by the "HB Cumulative Radiation" recipe. Furthermore, because the hourly irriadiance values are accurate, this recipe can be used to evaluate peak_irradiance and determine the worst-case solar loads over clear sky Weas that represent cooling design days.

Inputs

• model [Required]

A Honeybee Model for which Annual Irradiance will be simulated. Note that this model must have grids assigned to it.

• wea [Required]

A Wea object produced from the Wea components that are under the Light Sources tab. This can also be the path to a .wea or a .epw file.

• timestep

An integer for the timestep of the inpput _wea. This value is used to compute average irradiance and cumulative radiation. (Default: 1)

• visible

Boolean to indicate the type of irradiance output, which can be solar (False) or visible (True). Note that the output values will still be irradiance (W/m2) when "visible" is selected but these irradiance values will be just for the visible portion of the electromagnetic spectrum. The visible irradiance values can be converted into illuminance by multiplying them by the Radiance luminous efficacy factor of 179. (Default: False).

• north

A number between -360 and 360 for the counterclockwise difference between the North and the positive Y-axis in degrees. This can also be Vector for the direction to North. (Default: 0).

• grid_filter

Text for a grid identifer or a pattern to filter the sensor grids of the model that are simulated. For instance, first_floor_* will simulate only the sensor grids that have an identifier that starts with first_floor_. By default, all grids in the model will be simulated.

• radiance_par

Text for the radiance parameters to be used for ray tracing. (Default: -ab 2 -ad 5000 -lw 2e-05).

• run_settings

Settings from the "HB Recipe Settings" component that specify how the recipe should be run. This can also be a text string of recipe settings.

• run [Required]

Set to True to run the recipe and get results. This input can also be the integer "2" to run the recipe silently.

Outputs

• report

Reports, errors, warnings, etc.

• results

Raw result files (.ill) that contain matrices of irradiance in W/m2 for each time step of the wea.

• res_direct

Raw result files (.ill) that contain irradiance matrices for just the direct sun at each hour of the simulation. These can be postprocessed using various components under the 4::Results sub-tab.

• avg_irr

The average irradiance in W/m2 for each sensor over the Wea time period.

• peak_irr

The highest irradiance value in W/m2 during the Wea time period. This is suitable for assessing the worst-case solar load of clear skies on cooling design days. It can also be used to determine the highest radiant temperatures that occupants might experience in over the time period of the Wea.

• radiation

The cumulative radiation in kWh/m2 over the Wea time period.

-

Run a point-in-time view-based study for a Honeybee model.

Point-in-time view-based recipes require a sky and can output High Dynamic Range (HDR) images of illuminance, irradiance, luminance or radiance.

The view_count_ input can be used to split each view for parallel processing, producing multiple images that are recombined into a single .HDR for the view at the end of the recipe. The recombination process automatically includes an anti-aliasing pass that smooths and improves the quality of the image. The recipe also performs an overture calculation prior to splitting each view, which results in an image with better interpolation between neighboring pixels.

Inputs

• model [Required]

A Honeybee Model for which a point-in-time view-based study will be run. Note that this model should have views assigned to it in order to produce meaningfule results.

• sky [Required]

A Radiance sky from any of the sky components under the "Light Sources" tab. Skies can be either CIE, ClimateBased/Custom, or for a specific Illuminance/Irradiance. This input can also just be a text definition of a sky's paramters. Examples include:

• metric

Either an integer or the full name of a point-in-time metric to be computed by the recipe. (Default: luminance). Choose from the following:

• resolution

An integer for the maximum dimension of each image in pixels (either width or height depending on the input view angle and type). (Default: 800).

• view_filter

Text for a view identifer or a pattern to filter the views of the model that are simulated. For instance, first_floor_* will simulate only the views that have an identifier that starts with first_floor_. By default, all views in the model will be simulated.

• skip_overture

A boolean to note whether an ambient file (.amb) should be generated for an overture calculation before the view is split into smaller views. With an overture calculation, the ambient file (aka ambient cache) is first populated with values. Thereby ensuring that - when reused to create an image - Radiance uses interpolation between already calculated values rather than less reliable extrapolation. The overture calculation has comparatively small computation time to full rendering but is single-core can become time consuming in situations with a high view_count_ and workers.

• radiance_par

Text for the radiance parameters to be used for ray tracing. (Default: -ab 2 -aa 0.25 -ad 512 -ar 16).

• run_settings

Settings from the "HB Recipe Settings" component that specify how the recipe should be run. This can also be a text string of recipe settings.

• run [Required]

Set to True to run the recipe and get results. This input can also be the integer "2" to run the recipe silently.

Outputs

• report

Reports, errors, warnings, etc.

• results

High Dynamic Range (HDR) images for each View in the model. These can be plugged into the Ladybug "Image Viewer" component to preview the image. They can also be plugged into the "HB False Color" component to convert the image into a false color version. Lastly, it can be connected to the "HB HDR to GIF" component to get a GIF image that is more portable and easily previewed by different software. Pixel values are in the standard SI units of the requested input metric.

- [source code]

Run a cumulative radiation study for a Honeybee model.

This recipe calculates cumulative radiation (kWh/m2) and average irradiance (W/m2) over the time period of a specified Wea.

The fundamental calculation of this recipe is the same as that of the "LB Incident Radiation" component except that this recipe uses Radiance and can therefore account for ambient reflections. Like LB Incident Radiation, the direct sun in this recipe is diffused between several sky patches and so the precise line between shadow and sun for each hour is blurred. This approximation is acceptable for studies where one is only concerned about the average/total conditions over time and the timestep-by-timestep irradiance values do not need to be exact. For accurate modeling of direct irradiance on a timestep-by-timestep basis, see the "HB Annual Irradiance" recipe.

Inputs

• model [Required]

A Honeybee Model for which Cumulative Radiation will be simulated. Note that this model should have grids assigned to it.

• wea [Required]

A Wea object produced from the Wea components that are under the Light Sources tab. This can also be the path to a .wea or a .epw file.

• timestep

An integer for the timestep of the inpput _wea. (Default: 1)

• sky_density

An integer for the number of times that that the original Tregenza sky patches are subdivided. 1 indicates that 145 patches are used to describe the sky hemisphere, 2 indicates that 577 patches describe the hemisphere, and each successive value will roughly quadruple the number of patches used. Setting this to a high value will result in a more accurate analysis but will take longer to run. (Default: 1).

• north

A number between -360 and 360 for the counterclockwise difference between the North and the positive Y-axis in degrees. This can also be Vector for the direction to North. (Default: 0).

• grid_filter

Text for a grid identifer or a pattern to filter the sensor grids of the model that are simulated. For instance, first_floor_* will simulate only the sensor grids that have an identifier that starts with first_floor_. By default, all grids in the model will be simulated.

• radiance_par

Text for the radiance parameters to be used for ray tracing. (Default: -ab 2 -ad 5000 -lw 2e-05).

• run_settings

Settings from the "HB Recipe Settings" component that specify how the recipe should be run. This can also be a text string of recipe settings.

• run [Required]

Set to True to run the recipe and get results. This input can also be the integer "2" to run the recipe silently.

Outputs

• report

Reports, errors, warnings, etc.

• avg_irr

The average irradiance in W/m2 for each sensor over the Wea time period.

• radiation

The cumulative radiation in kWh/m2 over the Wea time period.

-

Run a daylight factor study for a Honeybee model.

Daylight Factor (DF) is defined as the ratio of the indoor daylight illuminance to outdoor illuminance under an unobstructed overcast sky. It is expressed as a percentage between 0 and 100.

Because daylight factor is computed using an overcast sky, it does not change with [North, East, South, West] orientation. As such, it is more suited to assessing daylight in climates where cloudy conditions are common. The "HB Annual Daylight" recipe yields a much more accurate assessment of daylight and is suitable for all climates, though it requires a significantly longer calculation time than Daylight Factor.

Inputs

• model [Required]

A Honeybee Model for which Daylight Factor will be simulated. Note that this model should have grids assigned to it in order to produce meaningfule results.

• grid_filter

Text for a grid identifer or a pattern to filter the sensor grids of the model that are simulated. For instance, first_floor_* will simulate only the sensor grids that have an identifier that starts with first_floor_. By default, all grids in the model will be simulated.

• radiance_par

Text for the radiance parameters to be used for ray tracing. (Default: -ab 2 -aa 0.1 -ad 2048 -ar 64).

• run_settings

Settings from the "HB Recipe Settings" component that specify how the recipe should be run. This can also be a text string of recipe settings.

• run [Required]

Set to True to run the recipe and get results. This input can also be the integer "2" to run the recipe silently.

Outputs

• report

Reports, errors, warnings, etc.

• results

The daylight factor values from the simulation in percent. Each value is for a different sensor of the grid. These can be plugged into the "LB Spatial Heatmap" component along with meshes of the sensor grids to visualize results.

-

Calculate the number of hours of direct sun received by grids of sensors in a Honeybee model.

The fundamental calculation of this recipe is the same as that of the "LB Direct Sun Hours" component except that this recipe uses Radiance, which allows the simulation to scale better for large numbers of sensors.

Inputs

• model [Required]

A Honeybee Model for which Direct Sun Hours will be simulated. Note that this model should have grids assigned to it in order to produce meaningfule results.

• wea [Required]

A Wea object produced from the Wea components that are under the Light Sources tab. This can also be the path to a .wea or a .epw file.

• timestep

An integer for the timestep of the inpput _wea. This value will be used to ensure the units of the results are in hours. (Default: 1)

• north

A number between -360 and 360 for the counterclockwise difference between the North and the positive Y-axis in degrees. This can also be Vector for the direction to North. (Default: 0).

• grid_filter

Text for a grid identifer or a pattern to filter the sensor grids of the model that are simulated. For instance, first_floor_* will simulate only the sensor grids that have an identifier that starts with first_floor_. By default, all grids in the model will be simulated.

• run_settings

Settings from the "HB Recipe Settings" component that specify how the recipe should be run. This can also be a text string of recipe settings.

• run [Required]

Set to True to run the recipe and get results. This input can also be the integer "2" to run the recipe silently.

Outputs

• report

Reports, errors, warnings, etc.

• results

Raw result files (.ill) that contain matrices of zero/one values indicating whether each sensor is exposed to the sun at a given time step of the input Wea.

• hours

The cumulative number of hours that each sensor can see the sun. Each value is always in hours provided that the input timestep is the same as the input Wea.

- [source code]

Run a Sky View (SV) study for a Honeybee model.

Sky View is defined as the percent of the sky dome seen by a surface. These can be computed either using a uniform (default) sky or a cloudy sky.

Note that computing cloudy Sky View for a vertically-oriented geometry (horizontal sensor direction) will yield Vertical Sky Component (VSC) as described by the UK Building Research Establishment (BRE). VSC is defined as the ratio of cloudy sky illuminance falling on a vertical wall to the simultaneous horizontal illuminance under an unobstructed sky [Littlefair, 1991].

Also note that this recipe still respects the transparency of objects, reducing the percentage of the sky visible through a certain geometry by the transmittance of that geometry.

Inputs

• model [Required]

A Honeybee Model for which Sky View or Wky Exposure will be simulated. Note that this model should have grids assigned to it in order to produce meaningful results.

• cloudy_sky

A boolean to note whether a uniform sky should be used (False) or a cloudy overcast sky (True). (Default: False).

• grid_filter

Text for a grid identifer or a pattern to filter the sensor grids of the model that are simulated. For instance, first_floor_* will simulate only the sensor grids that have an identifier that starts with first_floor_. By default, all grids in the model will be simulated.

• radiance_par

Text for the radiance parameters to be used for ray tracing. (Default: -ab 2 -aa 0.1 -ad 2048 -ar 64).

• run_settings

Settings from the "HB Recipe Settings" component that specify how the recipe should be run. This can also be a text string of recipe settings.

• run [Required]

Set to True to run the recipe and get results.

Outputs

• report

Reports, errors, warnings, etc.

• results

Numbers for the sky view or sky exposure at each sensor. These can be plugged into the "LB Spatial Heatmap" component along with meshes of the sensor grids to visualize results. Values are in percent (between 0 and 100).

- [source code]

Run an annual daylight study for a Honeybee model to compute hourly illuminance for each sensor in a model's sensor grids.

By default, this recipe uses an enhanced 2-phase method, which accurately models direct sun by tracing rays from each sensor to the solar position at each hour of the calculation. This makes the result suitable for computing Annual Sun Exposure (ASE) and for modeling the effects of dynamic shades and apertures.

When the enhanced_ option is set to False, a standard 2-phase method for simulation, which is much faster because it simply determines the relationship between each sensor and sky patch and then multiplies the value of each sky patch at each hour by the relationship coefficient. However, this means that the direct sun is spread out across a few sky patches, making it unsuitable for ASE.

The resulting illuminance is used to compute the following metrics:

• Daylight Autonomy (DA) - The percentage of occupied hours that each sensor recieves more than the illuminance threshold. * Continuous Daylight Autonomy (cDA) - Similar to DA except that values below the illuminance threshold can still count partially towards the final percentage. * Useful Daylight Illuminance (UDI) - The percentage of occupied hours that illuminace falls between minimum and maximum thresholds

Inputs

• model [Required]

A Honeybee Model for which Annual Daylight will be simulated. Note that this model must have grids assigned to it.

• wea [Required]

A Wea object produced from the Wea components that are under the Light Sources tab. This can also be the path to a .wea or a .epw file. Note that the Wea must have a timestep of 1 to be used with this recipe.

• north

A number between -360 and 360 for the counterclockwise difference between the North and the positive Y-axis in degrees. This can also be Vector for the direction to North. (Default: 0).

• thresholds

A string to change the threshold for daylight autonomy and useful daylight illuminance. Valid keys are -t for daylight autonomy threshold,

-lt for the lower threshold for useful daylight illuminance and

-ut for the upper threshold. The order of the keys is not importantand you can include one or all of them. For instance if you only want to change the upper threshold to 2000 lux you should use -ut 2000 as the input. (Default: -t 300 -lt 100 -ut 3000). 

• schedule

An annual occupancy schedule, either as a Ladybug Hourly Continuous Data Collection or a HB-Energy schedule object. This can also be the path to a CSV file with 8760 rows or the identifier of a schedule in the honeybee-energy schedule library. Any value in this schedule that is 0.1 or above will be considered occupied. If not provided, a default schedule that runs from 8 AM to 5 PM on weekdays will be used.

• grid_filter

Text for a grid identifer or a pattern to filter the sensor grids of the model that are simulated. For instance, first_floor_* will simulate only the sensor grids that have an identifier that starts with first_floor_. By default, all grids in the model will be simulated.

• radiance_par

Text for the radiance parameters to be used for ray tracing. (Default: -ab 2 -ad 5000 -lw 2e-05).

• enhanced

Boolean to note whether an enhanced version of the 2-phase ray tracing simulation should be used, which will more accurately account for direct sun at each time step. If False, only a 2-phase daylight coefficient calculation with sky patches will be used, which is much faster but spreads the direct sun out across a few sky patches, making it unsuitable for ASE. (Default: True).

• run_settings

Settings from the "HB Recipe Settings" component that specify how the recipe should be run. This can also be a text string of recipe settings.

• run [Required]

Set to True to run the recipe and get results. This input can also be the integer "2" to run the recipe silently.

Outputs

• report

Reports, errors, warnings, etc.

• results

Raw result files (.ill) that contain illuminance matrices for each sensor at each hour of the simulation. These can be postprocessed using various components under the 4::Results sub-tab.

• DA

Daylight autonomy results in percent. DA is the percentage of occupied hours that each sensor recieves equal or more than the illuminance threshold. Each value is for a different sensor of the grid. These can be plugged into the "LB Spatial Heatmap" component along with meshes of the sensor grids to visualize results. These can also be connected to the "HB Spatial Daylight Autonomy" component to compute spatial daylight autonomy for each grid. Note that the resulting sDA is only compliant with LEED if dynamic blinds have been simulated using the methods in IES-LM-83-12.

• cDA

Continuous daylight autonomy results in percent. cDA is similar to DA except that values below the illuminance threshold can still count partially towards the final percentage. Each value is for a different sensor of the grid. These can be plugged into the "LB Spatial Heatmap" component along with meshes of the sensor grids to visualize results.

• UDI

Useful daylight illuminance results in percent. UDI is the percentage of occupied hours that illuminace falls between minimum and maximum thresholds. Each value is for a different sensor of the grid. These can be plugged into the "LB Spatial Heatmap" component along with meshes of the sensor grids to visualize results.

• UDI_low

Results for the percent of time that is below the lower threshold of useful daylight illuminance in percent. Each value is for a different sensor of the grid. These can be plugged into the "LB Spatial Heatmap" component along with meshes of the sensor grids to visualize results.

• UDI_up

Results for the percent of time that is above the upper threshold of useful daylight illuminance in percent. Each value is for a different sensor of the grid. These can be plugged into the "LB Spatial Heatmap" component along with meshes of the sensor grids to visualize results.

-

Run a quick view-based Radiance simulation to visualize the properties of Honeybee objects within Radiance.

Note that this simulation is always run on a single processor and will only show static Radiance properties (no dynamic Aperture or Shade properties). Accordingly, this component is only intended for quick checks of properties. For full customization of view-based simulations, the "HB Point-in-time View-based" recipe should be used.

Inputs

• hb_objs [Required]

  An array of honeybee Rooms, Faces, Apertures, Doors or Shades to be visualized in Radiance. This can also be an entire Model to be visualized.

• view

  An optional Honeybee-Radiance view to specify the view to render. If unspecified, the currently active Rhino viewport will be rendered.

• sky

  An optional Radiance sky from any of the sky components under the "Light Sources" tab. If unspecified, a uniform sky with 10000 lux will be used.

• adj_expos

  Boolean to note whether the exposure of the image should be adjusted to mimic the human visual response in the output. The goal of this process is to output an image that correlates more strongly with a person’s subjective impression of a scene rather than the absolute birghtness of the scene. (Default: True).

• metric

  Either an integer or the full name of a point-in-time metric to be computed by the recipe. (Default: luminance). Choose from the following:

  • 0 = illuminance

  • 1 = irradiance

  • 2 = luminance

  • 3 = radiance

• resolution

  An integer for the maximum dimension of each image in pixels (either width or height depending on the input view angle and type). (Default: 800).

• radiance_par

  Text for the radiance parameters to be used for ray tracing. (Default: -ab 2 -aa 0.25 -ad 512 -ar 16).

• run [Required]

  Set to "True" to run Radiance and get an image of the scene.

Outputs

• report

  Reports, errors, warnings, etc.

• hdr

  A High Dynamic Range (HDR) image of the scene. This can be plugged into the Ladybug "Image Viewer" component to preview the image. It can also be plugged into the "HB False Color" component to convert the image into a false color version. Lastly, it can be connected to the "HB HDR to GIF" component to get a GIF image that is more portable and easily previewed by different software. Pixel values are in the standard SI units of the requested input metric.

  • illuminance = lux (aka. lm/m2)

  • irradiance = W/m2

  • luminance = cd/m2 (aka. lm/m2-sr)

  • radiance = W/m2-sr

-

Get recommended Radiance parameters given a recipe type and a level of detail.

The original recommendation for the various Radiance paramters comes from this document.

Inputs

• recipe_type [Required]

  An integer or text for the type of recipe. Acceptable text inputs are either the full text of the recipe type (eg. point-in-time-grid) or the name of the Radiance command for which the parameters are being used (eg. rtrace). Choose from the following options.

  • 0 | rtrace | point-in-time-grid | daylight-factor

  • 1 | rpict | point-in-time-view

  • 2 | rfluxmtx | annual

• detail_level

  An integer or text for the level of detail/quality for which radiance parameters will be output. (Default: 0 for low). Choose from the following options.

  • 0 | low

  • 1 | medium

  • 2 | high

• additional_par

  Text to override the Radiance parameters as needed. Radiance's standard syntax must be followed (e.g. -ps 1 -lw 0.01).

Outputs

• rad_par

  Radiance parameters as a text string. These can be plugged into the radiancepar input of the various recipes.

- [source code]

Get the recommended ambient resoluation (-ar) needed to resolve details with a given dimension in model units.

This recommendation is derived from the overall dimensions of the Radince scene being simulated as well as the ambient accuracy (-aa) being used in the simulation.

The result from this component can be plugged directly into the additional_par_ of the "HB Radiance Parameter" component or into the radiance_par of any recipe components.

Inputs

• model [Required]

The Honeybee Model being used for Radiance simulation.

• detail_dim [Required]

A number in model units that represents the dimension of the smallest detail that must be resolved in the Radiance simulation.

• aa

An number for ambient accuracy (-aa) being used in the Radiance smiulation. This value should be matched between this component and the component into which the ouput ar is being input. (Default: 0.25 for low-resolution Radiance studies).

Outputs

• ar

The abmient resolution needed to resolve the detail_dim as a text string. These can be plugged into the additional_par of the "HB Radiance Parameter" component or the radiance_par_ input of the recipes.

• Annual Daylight Metrics

• Annual Glare Metrics

• Annual Sunlight Exposure

• Aperture Group Schedule

• Daylight Control Schedule

• Spatial Daylight Autonomy

• Annual Average Values

• Annual Cumulative Values

• Annual Peak Values

• Annual Results to Data

• Adjust HDR

• False Color

• Glare Postprocess

• HDR to GIF

• Extract HDR

• Model to Rad Folder

-

Calculate Annual Daylight Metrics from a result (.ill) files.

Inputs

• results [Required]

An list of annual Radiance result files from the "HB Annual Daylight" component (containing the .ill files and the sun-up-hours.txt). This can also be just the path to the folder containing these result files.

• dyn_sch

Optional dynamic Aperture Group Schedules from the "HB Aperture Group Schedule" component, which will be used to customize the behavior of any dyanmic aperture geometry in the output metrics. If unsupplied, all dynamic aperture groups will be in their default state in for the output metrics.

• occ_sch

An annual occupancy schedule as a Ladybug Data Collection or a HB-Energy schedule object. This can also be the identifier of a schedule in your HB-Energy schedule library. Any value in this schedule that is 0.1 or above will be considered occupied. If None, a schedule from 9AM to 5PM on weekdays will be used.

• threshold

Threshhold for daylight autonomy (DA) in lux (default: 300).

• min_max

A list for min, max illuminacne thresholds for useful daylight illuminance in lux. (Default: (100, 3000)).

• grid_filter

The name of a grid or a pattern to filter the grids. For instance, first_floor_* will simulate only the sensor grids that have an identifier that starts with first_floor_. By default all the grids will be processed.

Outputs

• report

Reports, errors, warnings, etc.

• DA

Daylight autonomy results in percent. DA is the percentage of occupied hours that each sensor recieves equal or more than the illuminance threshold. Each value is for a different sensor of the grid. These can be plugged into the "LB Spatial Heatmap" component along with meshes of the sensor grids to visualize results. These can also be connected to the "HB Spatial Daylight Autonomy" component to compute spatial daylight autonomy for each grid.

• cDA

Continuous daylight autonomy results in percent. cDA is similar to DA except that values below the illuminance threshold can still count partially towards the final percentage. Each value is for a different sensor of the grid. These can be plugged into the "LB Spatial Heatmap" component along with meshes of the sensor grids to visualize results.

• UDI

Useful daylight illuminance results in percent. UDI is the percentage of time that illuminace falls between minimum and maximum thresholds. Each value is for a different sensor of the grid. These can be plugged into the "LB Spatial Heatmap" component along with meshes of the sensor grids to visualize results.

• UDI_low

Results for the percent of time that is below the lower threshold of useful daylight illuminance in percent. Each value is for a different sensor of the grid. These can be plugged into the "LB Spatial Heatmap" component along with meshes of the sensor grids to visualize results.

• UDI_up

Results for the percent of time that is above the upper threshold of useful daylight illuminance in percent. Each value is for a different sensor of the grid. These can be plugged into the "LB Spatial Heatmap" component along with meshes of the sensor grids to visualize results.

- [source code]

Calculate Annual Glare Metrics from result (.dgp) files.

Glare Autonmy is a metric describing the percentage of occupied hours that each sensor is below the glare threshold.

Spatial Glare Autonomy is a metric describing the percentage of the sensor grid that is free glare according to the glare threshold and the target time. The sGA value is expressed as a percentage of the sensors in the analysis grid.

Inputs

• results [Required]

An list of annual Radiance result files from the "HB Imageless Annual Glare" component (containing the .dgp files and the sun-up-hours.txt). This can also be just the path to the folder containing these result files.

• occ_sch

An annual occupancy schedule as a Ladybug Data Collection or a HB-Energy schedule object. This can also be the identifier of a schedule in your HB-Energy schedule library. Any value in this schedule that is 0.1 or above will be considered occupied. If None, a schedule from 9AM to 5PM on weekdays will be used.

• glare_thresh

Threshold for glare autonomy (GA) in DGP (default: 0.4).

• grid_filter

The name of a grid or a pattern to filter the grids. For instance, first_floor_* will simulate only the sensor grids that have an identifier that starts with first_floor_. By default all the grids will be processed.

• target_time

A minimum threshold of occupied time (eg. 95% of the time), above which a given sensor passes and contributes to the spatial glare autonomy. (Default: 95%).

Outputs

• report

Reports, errors, warnings, etc.

• GA

Glare autonomy results in percent. GA is the percentage of occupied hours that each sensor is free of glare according to the glare threshold. Each value is for a different sensor of the grid. These can be plugged into the "LB Spatial Heatmap" component along with meshes of the sensor grids to visualize results.

• sGA

Spatial glare autonomy as a percentage of the sensors for each analysis grid that does not exceed the glare threshold for a specified fraction of occupied hours, ie. the target time.

• pass_fail

A data tree of zeros and ones, which indicate whether a given sensor passes the criteria for being free of glare (1) or fails the criteria (0). Being free of glare does not necessarily mean that the sensor is glare-free for all hours, but that it is glare-free for a minimum percentage of occupied hours defined by the target time. Each value is for a different sensor of the grid. These can be plugged into the "LB Spatial Heatmap" component along with meshes of the sensor grids to visualize results.

-

Calculate Annual Sunlight Exposure from a results folder.

Note: This component will only output a LEED compliant ASE if you've run the simulation with all operable shading devices retracted. If you are using results with operable shading devices, then this output is NOT LEED compliant.

Inputs

• results [Required]

An annual results folder containing direct illuminance results. This can be the output of the "HB Annual Daylight" component. This can also be just the path to the results folder.

• occ_sch

An annual occupancy schedule as a Ladybug Data Collection or a HB-Energy schedule object. This can also be the identifier of a schedule in your HB-Energy schedule library. Any value in this schedule that is 0.1 or above will be considered occupied. If None, a schedule from 9AM to 5PM on weekdays will be used.

• threshold

The threshold (lux) that determines if a sensor is overlit (default: 1000).

• target_hrs

The number of occupied hours that cannot receive higher illuminance than the direct threshold (default: 250).

• grid_filter

The name of a grid or a pattern to filter the grids. For instance, first_floor_* will simulate only the sensor grids that have an identifier that starts with first_floor_. By default all the grids will be processed.

Outputs

• report

Reports, errors, warnings, etc.

• ASE

Annual sunlight exposure as a percentage for each sensor grid.

• hrs_above

The number of hours above the threshold for each sensor point. These can be plugged into the "LB Spatial Heatmap" component along with meshes of the sensor grids to visualize results.

-

Create a Dynamic Aperture Group Schedule, which can be used to process any dynamic aperture geometry that was run in an annual simulation.

Inputs

• group_aps [Required]

Honeybee Apertures that are a part of the same dynamic group and will be assigned the same schedule for postprocessing. Typically, this is the output of the "HB Dynamic Aperture Group" component but it can also be the output of the "HB Get Dynamic Groups" component, which returns all of the dynamic groups on a particular Model.

• schedule [Required]

A list of 8760 integers refering to the index of the aperture group state to be used at each hour of the simulation. This can also be a single integer for a static state to be used for the entire period of the simulation or a pattern of integers that is less than 8760 in length and will be repeated until the 8760 is reached. Note that 0 refers to the first state, 1 refers to the second state, and so on. -1 can be used to completely discout the aperture from the simulation for a given hour.

Outputs

• dyn_sch

A dynamic schedule object for the input aperture group, which can be plugged into any of the Results components with a syn_sch input.

- [source code]

Generate electric lighting schedules from annual daylight results, which can be used to account for daylight controls in energy simulations.

Such controls will dim the lights in the energy simulation according to whether the illuminance values at the sensor locations are at a target illuminance setpoint.

In addition to benefiting from the accuracy of Radiance, using this component has several advantages over the "HB Apply Daylight Control" component under HB-Energy. Notably, it can account for setups with multiple illuminance sensors.

This component will generate one schedule per sensor grid in the simulation. Each grid should have sensors at the locations in space where daylight dimming sensors are located. Grids with one, two, or more sensors can be used to model setups where fractions of each room are controlled by different sensors. If the sensor grids are distributed over the entire floor of the rooms, the resulting schedules will be idealized, where light dimming has been optimized to supply the minimum illuminance setpoint everywhere in the room.

Inputs

• results [Required]

An list of annual Radiance result files from the "HB Annual Daylight" component (containing the .ill files and the sun-up-hours.txt). This can also be just the path to the folder containing these result files.

• dyn_sch

Optional dynamic Aperture Group Schedules from the "HB Aperture Group Schedule" component, which will be used to customize the behavior of any dyanmic aperture geometry in the output metrics. If unsupplied, all dynamic aperture groups will be in their default state in for the output metrics.

• base_schedule

A lighting schedule representing the usage of lights without any daylight controls. The values of this schedule will be multiplied by the hourly dimming fraction to yield the output lighting schedules. The format of this schedule can be a Ladybug Data Collection, a HB-Energy schedule object, or the identifier of a schedule in the HB-Energy schedule library. If None, a schedule from 9AM to 5PM on weekdays will be used.

• ill_setpoint

A number for the illuminance setpoint in lux beyond which electric lights are dimmed if there is sufficient daylight. Some common setpoints are listed below. (Default: 300 lux). 50 lux - Corridors and hallways. 150 lux - Computer work spaces (screens provide illumination). 300 lux - Paper work spaces (reading from surfaces that need illumination). 500 lux - Retail spaces or museums illuminating merchandise/artifacts. 1000 lux - Operating rooms and workshops where light is needed for safety.

• min_power_in

A number between 0 and 1 for the the lowest power the lighting system can dim down to, expressed as a fraction of maximum input power. (Default: 0.3).

• min_light_out

A number between 0 and 1 the lowest lighting output the lighting system can dim down to, expressed as a fraction of maximum light output. Note that setting this to 1 means lights aren't dimmed at all until the illuminance setpoint is reached. This can be used to approximate manual light-switching behavior when used in conjunction with the off_at_min_ output below. (Default: 0.2).

• off_at_min

Boolean to note whether lights should switch off completely when they get to the minimum power input. (Default: False).

Outputs

• schedules

Lighting control Recipe

- [source code]

Get average illuminance or irradiance values over an annual daylight or irradiance simulation.

The hoys input can also be used to filter the data for a particular time period or hour/timestep of the simulation.

Inputs

• results [Required]

An list of annual Radiance result files from either the "HB Annual Daylight" or the "HB Annual Irradiance" component (containing the .ill files and the sun-up-hours.txt). This can also be just the path to the folder containing these result files.

• dyn_sch

Optional dynamic Aperture Group Schedules from the "HB Aperture Group Schedule" component, which will be used to customize the behavior of any dyanmic aperture geometry in the output metrics. If unsupplied, all dynamic aperture groups will be in their default state in for the output metrics.

• hoys

An optional numbers or list of numbers to select the hours of the year (HOYs) for which results will be computed. These HOYs can be obtained from the "LB Calculate HOY" or the "LB Analysis Period" components. If None, all hours of the results will be used.

• median

Set to True to get the median values instead of the average. The median values can only be calculated for a results folder from the "HB Annual Daylight" component. (Default: False).

• grid_filter

The name of a grid or a pattern to filter the grids. For instance, first_floor_* will simulate only the sensor grids that have an identifier that starts with first_floor_. By default all the grids will be processed.

Outputs

• report

Reports, errors, warnings, etc.

• values

Average illuminance or irradiance valules for each sensor in lux or W/m2. Each value is for a different sensor of the grid. These can be plugged into the "LB Spatial Heatmap" component along with meshes of the sensor grids to visualize results.

- [source code]

Get cumulative radiation (or sum of illuminance) values over an annual irradiance or daylight simulation.

The hoys input can also be used to filter the data for a particular time period or hour/timestep of the simulation.

Inputs

• results [Required]

An list of annual Radiance result files from either the "HB Annual Daylight" or the "HB Annual Irradiance" component (containing the .ill files and the sun-up-hours.txt). This can also be just the path to the folder containing these result files.

• dyn_sch

Optional dynamic Aperture Group Schedules from the "HB Aperture Group Schedule" component, which will be used to customize the behavior of any dyanmic aperture geometry in the output metrics. If unsupplied, all dynamic aperture groups will be in their default state in for the output metrics.

• hoys

An optional numbers or list of numbers to select the hours of the year (HOYs) for which results will be computed. These HOYs can be obtained from the "LB Calculate HOY" or the "LB Analysis Period" components. If None, all hours of the results will be used.

• grid_filter

The name of a grid or a pattern to filter the grids. For instance, first_floor_* will simulate only the sensor grids that have an identifier that starts with first_floor_. By default all the grids will be processed.

Outputs

• report

Reports, errors, warnings, etc.

• values

In the case of an annual irradaince simulation, this is the cumulative radiation valules for each sensor in Wh/m2. For annual daylight, it is cumulative illuminance (lux-hours). These can be plugged into the "LB Spatial Heatmap" component along with meshes of the sensor grids to visualize results.

- [source code]

Calculate Spatial Daylight Autonomy (sDA) from lists of daylight autonomy values.

As per IES-LM-83-12 Spatial Daylight Autonomy (sDA) is a metric describing annual sufficiency of ambient daylight levels in interior environments. It is defined as the percent of an analysis area (the area where calcuations are performed -typically across an entire space) that meets a minimum daylight illuminance level for a specified fraction of the operating hours per year. The sDA value is expressed as a percentage of area.

Note: This component will only output a LEED compliant sDA if you've run the simulation with dynamic blinds and blind schedules as per the IES-LM-83-12 standard. If you are not using dynamic blinds, then this output is NOT LEED compliant.

Inputs

• DA [Required]

A data tree of daylight autonomy values output from the "HB Annual Dalyight" recipe or the "HB Annual Daylight Metrics" component. Note that, unless these DA values follow LM83 dynamic blinds setup, the resulting sDA is not LEED compliant.

• mesh

An optional list of Meshes that align with the _DA data tree above, which will be used to assign an area to each sensor. If no mesh is connected here, it will be assumed that each sensor represents an equal area to all of the others.

• target_time

A minimum threshold of occupied time (eg. 50% of the time), above which a given sensor passes and contributes to the spatial daylight autonomy. (Default: 50%).

Outputs

• report

Reports, errors, warnings, etc.

• sDA

Spatial daylight autonomy as percentage of area for each analysis grid.

• pass_fail

A data tree of zeros and ones, which indicate whether a given senor passes the criteria for being daylit (1) or fails the criteria (0). Each value is for a different sensor of the grid. These can be plugged into the "LB Spatial Heatmap" component along with meshes of the sensor grids to visualize results.

- [source code]

Import the hourly illuminance or irradiance results of an annual daylight or irradiance study to a list of data collections.

The resulting data collections can be visulized using the ladybug components or deconstructed for detailed analysis with native Grasshopper math components.

Inputs

• results [Required]

An list of annual Radiance result files from the "HB Annual Daylight" component (containing the .ill files and the sun-up-hours.txt). This can also be just the path to the folder containing these result files.

• dyn_sch

Optional dynamic Aperture Group Schedules from the "HB Aperture Group Schedule" component, which will be used to customize the behavior of any dyanmic aperture geometry in the output metrics. If unsupplied, all dynamic aperture groups will be in their default state in for the output metrics.

• sel_pts [Required]

A point or list of points, which will be used to filter the sensors for which data collections will be imported.

• all_pts [Required]

The data tree of all sensor points that were used in the simulation. This is required in order to look up the index of the _sel_pts in the results matrices.

• sel_vecs

An optional vector or list of vectors, which will be used to filter the sensors for which data collections will be imported. If there is an input here, the all_vecs_ must be connected.

• all_vecs

The data tree of all sensor directions that were used in the simulation. This is required in order to look up the index of the sel_vecs_ in the results matrices.

Outputs

• report

Reports, errors, warnings, etc.

• data

A list of hourly data collections containing illuminance or irradiance results. These can be visulized using the ladybug components or deconstructed for detailed analysis with native Grasshopper math components.

- [source code]

Adjust and format a High Dynamic Range (HDR) image file.

Possible adjustments include chaging the exposure of the image to mimic what would be seen by a human eye and adding an optional text label to the image.

Inputs

• hdr [Required]

  Path to a High Dynamic Range (HDR) image file.

• adj_expos

  Boolean to note whether the exposure of the image should be adjusted to mimic the human visual response in the output. The goal of this process is to output an image that correlates more strongly with a person’s subjective impression of a scene rather than the absolute birghtness of the scene. (Default: False).

• label

  Optional text label to be appended to the bottom of the image. This is useful when one has several images and would like to easily identify them while scrolling through them.

• label_hgt

  An integer for the height of the label text in pixels. (Default: 32).

Outputs

• hdr

  Path to the resulting adjusted HDR image file.

- [source code]

Convert a High Dynamic Range (HDR) image file into a Graphics Interchange Format (GIF) image file.

GIF files are much smaller than HDRs, they are more portable, and they can be previewed with many different types of software. However, they do not contain all of the information that an HDR image has.

Inputs

• hdr [Required]

  Path to a High Dynamic Range (HDR) image file.

Outputs

• gif

  Path to the resulting GIF file,

- [source code]

Perform glare post-processing on a hemisphical fisheye HDR image file.

Glare post-processing includes calcuating Daylight Glare Probability (DGP) as well as other glare indexes (DGI, UGR, VCP, CGI, UDP).

This component is using the evalglare function for glare calculations., which is developed by J. Wienold at Fraunhofer ISE. More information on evalglare can be found here: https://www.radiance-online.org/learning/documentation/manual-pages/pdfs/evalglare.pdf/view

For more information about the metrics used to evaluate glare, see here: http://web.mit.edu/tito_/www/Projects/Glare/GlareRecommendationsForPractice.html

Inputs

• hdr [Required]

  Path to a hemisphical fisheye High Dynamic Range (HDR) image file. This can be obtained from the "HB Point-In-Time View-Based" recipe component. Due to runtime reasons of the evalglare code, the input HDR image should be smaller than 1500 x 1500 pixels. The recommended size is 1000 x 1000 pixels, the minimum recommended size is 800 x 800 pixels.

• task_pos

  An optional task position as a 2D point or string formatted as "X, Y". The X and Y coordinates of this point must be numbers between 0 and 1 and correspond to fraction of the image width and height where the task position lies. If no task position is provided, the glare will be valuated for the entire scene of the image.

• task_angle

  An number between 0 and 180 for the task position opening angle in degrees. This angle indicates how widely the peripheral vision is engaged for the task. (Default: 30).

• hide_task

  Boolean to note whether the task area should be hidden in the output check_hdr.

Outputs

• DGP

  Daylight Glare Probability (DGP) as a number between 0 and 1. The DGP describes the fraction of persons disturbed by glare, where 0 is no one disturbed and 1 is everyone. Values lower than 0.2 are out of the range of the user assessment tests, where the program is based on and should be interpreted carefully.

• category

  Text for the category of glare discomfort. It will be one of the following.

  • Imperceptible Glare [0.35 > DGP]

  • Perceptible Glare [0.4 > DGP >= 0.35]

  • Disturbing Glare [0.45 > DGP >= 0.4]

  • Intolerable Glare [DGP >= 0.45]

• glare_indices

  A list of various glare indices ordered as follows.

  • Daylight Glare Index (DGI)

  • Unified Glare Rating (UGR)

  • Visual Comfort Probability (VCP)

  • CIE Glare Index (CGI)

  • Veiling Luminance (Lveil)

• check_hdr

  Path to a HDR image produced from the glare study. The image will use randomly-assigned colors to indicate different sources of glare in the image. It will also show a circular region for the task area unless hidetask has been set to True.

- [source code]

Interpolate or extrapolate a High Dynamic Range (HDR) image file from another HDR image file.

Recommended use is to extract 180 FOV (-vh 180 -vv 180) angular or hemispherical HDR images from a 360 FOV (-vh 360 -vv 360) angular HDR image. Alternatively, conversions between 180 FOV angular and hemispherical HDR images can be made.

Inputs

• view [Required]

A view to interpolate or extrapolate into a new HDR. The "HB View" component can be used to create an input view and it must have the same position as that use to make the _hdr.

• hdr [Required]

Path to a High Dynamic Range (HDR) image file from which to interpolate or extrapolate.

• resolution

An integer for the dimension of the output image in pixels. If extracting a 180 FOV angular or hemispherical HDR image from a 360 FOV HDR image, the default resolution is 1/3 of the resolution of _hdr. If converting between 180 FOV angular or hemispherical HDR images, the default resolution is that of _hdr.

Outputs

• hdr

Path to the resulting HDR image file.

-

Convert a High Dynamic Range (HDR) image file into a falsecolor version of itself.

Inputs

• hdr [Required]

Path to a High Dynamic Range (HDR) image file.

• max

A number to set the upper boundary of the legend. The default is dictated based on the legend_unit_.

• seg_count

An interger representing the number of steps between the high and low boundary of the legend. The default is set to 10 and any custom values input in here should always be greater than or equal to 2.

• legend_height

An integer for the height of the legend in pixels. Set to 0 to completely remove the legend from the output. (Default: 200).

• legend_width

An integer for the width of the legend in pixels. Set to 0 to completely remove the legend from the output. (Default: 100).

• legend_unit

Text for the unit of the legend. If unspecified, an attempt will be made to sense the metric from the input image file. Typical examples include lux, W/m2, cd/m2, w/sr-m2.

• conversion

Number for the conversion factor (aka. multiplier) for the results. The default is either 1 or 179 depending on whether the image is for radiance or irradiance to luminance or illuminance, respectively.

• contour_lines

Set to True ro render the image with colored contour lines.

• logarithmic

Number of decades to use with a logarithmic legend scale. Decades are the number of intervals of 10 below the maximum scale. If unspecified, a linear scale is used.

• extrema

Set to True to cause extrema points to be printed on the brightest and darkest pixels of the input picture.

• mask

A boolen to note whether pixels with a value of zero should be masked in black. (Default: False).

• color_palette

Optional interger or text to change the color palette. Choose from the following.

Outputs

• hdr

Path to the resulting falsecolor HDR file. This can be plugged into the Ladybug "Image Viewer" component to preview the image. It can also be plugged into the "HB HDR to GIF" component to get a GIF image that is more portable and easily previewed by different software.

- [source code]

Get peak irradiance or sum of illuminance values over an annual irradiance or daylight simulation.

The hoys input can also be used to filter the data for a particular time period or hour/timestep of the simulation.

Inputs

• results [Required]

An list of annual Radiance result files from either the "HB Annual Daylight" or the "HB Annual Irradiance" component (containing the .ill files and the sun-up-hours.txt). This can also be just the path to the folder containing these result files.

• dyn_sch

Optional dynamic Aperture Group Schedules from the "HB Aperture Group Schedule" component, which will be used to customize the behavior of any dyanmic aperture geometry in the output metrics. If unsupplied, all dynamic aperture groups will be in their default state in for the output metrics.

• hoys

An optional numbers or list of numbers to select the hours of the year (HOYs) for which results will be computed. These HOYs can be obtained from the "LB Calculate HOY" or the "LB Analysis Period" components. If None, all hours of the results will be used.

• grid_filter

The name of a grid or a pattern to filter the grids. For instance, first_floor_* will simulate only the sensor grids that have an identifier that starts with first_floor_. By default all the grids will be processed.

• coincident

Boolean to indicate whether output values represent the the peak value for each sensor throughout the entire analysis (False) or they represent the highest overall value across each sensor grid at a particular timestep (True). (Default: False).

Outputs

• report

Reports, errors, warnings, etc.

• hoys

An integer for each sesnor grid that represents the hour of the year at which the peak occurs. This will be None unless coincident_ is set to True.

• values

Peak illuminance or irradiance valules for each sensor in lux or W/m2. Each value is for a different sensor of the grid. These can be plugged into the "LB Spatial Heatmap" component along with meshes of the sensor grids to visualize results.

-

Write a Honeybee Model to a Radiance Model Folder.

This Radiance Model Folder is what is used to run various types of Radiance studies off of a consistent set of geometry and modifiers.

Inputs

• model [Required]

A honeybee model object possessing all geometry, radiance modifiers and simulation assets like Sensor Grids and Views.

• minimal

Boolean to note whether the radiance strings should be written in a minimal format (with spaces instead of line breaks). (Default: False).

• folder

Path to a folder to into which the Model Radiance Folder will be written. If unspecified, it will be written to a sub-folder within the default simulation folder.

• write [Required]

Set to True to write the Model to a Radiance folder.

Outputs

• report

Reports, errors, warnings, etc.

• folder

Path to the folder in which all of the files have been written.