Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
-
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.
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).
schedules
Lighting control Recipe
-
Create a Dynamic Aperture Group Schedule, which can be used to process any dynamic aperture geometry that was run in an annual simulation.
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.
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.
-
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.
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.
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.
-
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.
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%).
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.
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.
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.
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.
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.
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).
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.
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.
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.
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.
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.
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.
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.
Calculate Annual Daylight Metrics from a result (.ill) files.
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.
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.
-
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).
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.
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.
-
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.
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).
hdr
Path to the resulting adjusted HDR image file.
-
Convert a High Dynamic Range (HDR) image file into a falsecolor version of itself.
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.
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.
-
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.
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.
hdr
Path to the resulting HDR image file.
-
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.
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%).
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.
-
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.
hdr [Required]
Path to a High Dynamic Range (HDR) image file.
gif
Path to the resulting GIF file,
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:
For more information about the metrics used to evaluate glare, see here:
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.
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.
report
Reports, errors, warnings, etc.
folder
Path to the folder in which all of the files have been written.
