1 of 46

4 :: Extra

Color Range

Use this component to access a library of typical gradients useful throughout Ladybug. The output from this component should be plugged into the colors_ input of the "Legend Parameters" component.

For an image of each of the gardients in the library, check here: https://github.com/ladybug-tools/lbt-grasshopper/blob/master/gradients.png

Inputs

index

An index refering to one of the following possible gradients: 0 - Original Ladybug 1 - Nuanced Ladybug 2 - Multi-colored Ladybug 3 - Ecotect 4 - View Study 5 - Shadow Study 6 - Glare Study 7 - Annual Comfort 8 - Thermal Comfort 9 - Peak Load Balance 10 - Heat Sensation 11 - Cold Sensation 12 - Benefit/Harm 13 - Harm 14 - Benefit 15 - Shade Benefit/Harm 16 - Shade Harm 17 - Shade Benefit 18 - Energy Balance 19 - Energy Balance w/ Storage 20 - THERM 21 - Cloud Cover 22 - Black to White 23 - Blue, Green, Red 24 - Multicolored 2 25 - Multicolored 3 26 - OpenStudio Palette

Outputs

colors

A series of colors to be plugged into the "LB Legend Parameters" component.

FalseStartToggle

Generate Point Grid

- [source code]

Genrate a mesh with corresponding test points from a Rhino Brep (or Mesh).

The resulting mesh will be in a format that the "LB Spatial Heatmap" component will accept.

Inputs

geometry [Required]

Brep or Mesh from which to generate the points and grid.

grid_size [Required]

Number for the size of the test grid.

offset_dist

Number for the distance to move points from the surfaces of the input _geometry. Typically, this should be a small positive number to ensure points are not blocked by the mesh. (Default: 0).

quad_only

Boolean to note whether meshing should be done using Rhino's defaults (False), which fills the entire _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 input _geometry, an error will be raised.

Outputs

points

Test points at the center of each mesh face.

vectors

Vectors for the normal direction at each of the points.

face_areas

Area of each mesh face.

mesh

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

ImageViewer

- [source code]

Preview image files Please find the source code from: https://github.com/ladybug-tools/ladybug-grasshopper-dotnet

Inputs

imagePath

one or a list of image file path.

coordinates

A list of points for extracting colors from the source image.

scale

Set this image view port scale.

Outputs

imagePath

A new image marked with coordinates.

values

Color information or Radiance value that extracted from the input image. Radiance value only available on HDR image, and the unit is based on the Radiance study type. -Illuminance: lux -Luminance: cd/m2

GIF

Generates an animated gif image when there is a list of images.

Legend Parameters

- [source code]

Use this component to change the colors, numerical range, and/or number of divisions of any Ladybug legend along with the corresponding colored mesh that the legend refers to.

Any Ladybug component that outputs a colored mesh and a legend will have an input that can accept Legend Parameters from this component.

Inputs

min

A number to set the lower boundary of the legend. If None, the minimum of the values associated with the legend will be used.

max

A number to set the upper boundary of the legend. If None, the maximum of the values associated with the legend will be used.

seg_count

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

colors

An list of color objects. Default is Ladybug's original colorset.

continuous_leg

Boolean. If True, the colors along the legend will be in a continuous gradient. If False, they will be categorized in incremental groups according to the number_of_segments. Default is False for depicting discrete categories.

num_decimals

An optional integer to set the number of decimal places for the numbers in the legend text. Default is 2.

larger_smaller

Boolean noting whether to include larger than and smaller than (> and <) values after the upper and lower legend segment text. Default is False.

vert_or_horiz

Boolean. If True, the legend mesh and text points will be generated vertically. If False, they will genrate a horizontal legend. Default is True for a vertically-oriented legend.

base_plane

A Plane to note the starting point and orientation from where the legend will be genrated. The default is the world XY plane at origin (0, 0, 0).

seg_height

An optional number to set the height of each of the legend segments. Default is 1.

seg_width

An optional number to set the width of each of the legend segments. Default is 1 when legend is vertical. When horizontal, the default is (text_height * (number_decimal_places + 2)).

text_height

An optional number to set the size of the text in model units. Default is half of the segment_height.

font

An optional text string to specify the font to be used for the text. Examples include "Arial", "Times New Roman", "Courier" (all without quotations). Default is "Arial".

Outputs

leg_par

A legend parameter object that can be plugged into any of the Ladybug components with a legend.

Mesh Threshold Selector

Select a sub-region of a mesh using aligned values and conditional criteria.

This has multiple uses and can be applied to any study that outputs a list of results that are aligned with a mesh. For example, quantifying the daylit area from a daylight analysis, selecting the portion of a roof with enough solar radiation for photovoltaic panels, etc.

Inputs

values [Required]

A list of numbers that correspond to either the number of faces or vertices of the _mesh.

mesh [Required]

The mesh from which a sub-region will be selected. This is typically a colored mesh output from a study.

operator

A text string representing an operator for the the conditional statement. The default is greater than (>). This must be an operator in python and examples include the following:

pct_threshold

A number between 0 and 100 that represents the percentage of the mesh faces or vertices to be included in the resulting sub_mesh. (Default: 25%).

abs_threshold

An optional number that represents the absolute threshold above which a given mesh face or vertex is included in the resulting sub_mesh. An input here will override the percent threshold input above.

Outputs

report

Reports, errors, warnings, etc.

total_value

The sum of each value that meets the criteria multiplied by the corresponding mesh face area. This can generally be used to understand how much value is captured according to the conditional critera. For example, if the input _mesh is a radiation study, this is equal to the total radiation falling on the sub_mesh. This may or may not be meaningful depending on the units of the connected _values. This output will always be zero for cases where values correspond to mesh vertices and not faces.

total_area

The area of the sub_mesh that meets the criteria.

sub_mesh

A new mesh with the faces or vertices removed to reveal just the portion that satisfies the conditional criteria. By default, this is hidden to that just the outline appears in the geometry preview.

outline

A set of lines outlining the portion of the mesh that is above the threshold.

Preview VisualizationSet

- [source code]

Preview a VisualizationSet from any component with a vis_set output.

The VisualizationSet is often a much more detailed view of the geometry that the component typically generates and includes features like recommended line weights/types, display modes (eg. wireframe vs. shaded), transparency, and more.

Inputs

vis_set [Required]

VisualizationSet arguments from any Ladybug Tools component with a vis_set output. This can also be the path to a .vsf file that exists on this machine (these files are often written with the "LB Dump VisualizationSet" component). Lastly, this input can be a custom VisualizationSet that has been created with the Ladybug Tools SDK.

leg_par

Script variable VisSet

leg_par2d

Optional 2D LegendParameters from the "LB Legend Parameters 2D" component, which will be used to customize a legend in the plane of the screen so that it functions like a head-up display (HUD). If unspecified, the VisualizationSet will be rendered with 3D legends in the Rhino scene much like the other native Ladybug Tools components.

data_set

Optional text or an integer to select a specific data set from analysis geometries within the Visualization Set. Note that this input only has meaning for Visualization Sets that contain multiple data sets assigned to the same geometry. When using an integer, this will refer to the index of the data set to be visualized (starting with 0). When using text, this will refer to the name of the data type for the data set to be displayed.

Outputs

A VisualizationSet object that can be baked into the Rhino document by running "Bake" on this component or written to a standalone file using the "LB Dump VisualizationSet" component.

Spatial Heatmap

- [source code]

Color a mesh as a heatmap using values that align with the mesh faces or vertices.

Note that any brep can be converted to a gridded mesh that can be consumed by this component using the "LB Generate Point Grid" component.

Inputs

values [Required]

A list of numerical values with which to color the mesh. The number of values must match the number of faces or vertices in the mesh.

mesh [Required]

A Mesh object, with a number of faces or vertices that match the number of input values and will be colored with results.

offset_dom

Optional domain (or number for distance), which will be used to offset the mesh faces or verticesto according to the values. Higher values will be offset further.

legend_par

Optional legend parameters from the Ladybug 'Legend Parameters' component.

legend_title

A text string for Legend title. Typically, the units of the data are used here but the type of data might also be used. Default is an empty string.

global_title

A text string to label the entire mesh. It will be displayed in the lower left of the result mesh. Default is for no title.

Outputs

mesh

The input _mesh that has been colored with results.

legend

Geometry representing the legend for the mesh.

title

A text object for the global_title.

colors

The colors associated with each input value.

legend_par

The input legend parameters with defaults filled for unset properties.

vis_set

Script variable Heatmap

Capture View

- [source code]

Capture views of the Rhino scene and save them to your hard drive as as a .png files.

This is particularly useful when creating animations and one needs to automate the capturing of views. Note that images will likely have a Rhino world axes icon in the lower left of the image unless you go to Options > Grid > and uncheck "Show world axes icon".

Inputs

file_name [Required]

The file name, which the image will be saved as. Note that, for animations, each saved image should have a different name. Otherwise, the previous image will be overwritten by each successive image. Unique names for each animation frame can be achieved by using the animating slider to generate the file name.

folder

The folder into which the image file will be written. This should be a complete path to the folder. If None, the images will be written to one of the following default locations: Windows - C:/Users/[USERNAME]/ladybug_tools/resources/captured_views/ Mac - /Users/[USERNAME]/ladybug_tools/resources/captured_views/

viewport

Text for the Rhino viewport name which will be captured. This can also be a list of viewports in which case multiple views will be captured. If None, the default will be the active viewport (the last viewport in which you navigated). Acceptable inputs include: Perspective Top Bottom Left Right Front Back any view name that has been saved within the Rhino file

width

Integer for the width of the image to be captured in pixels. If None, the default is the width of the Rhino viewport currently on the screen.

height

Integer for the height of the image to be captured in pixels. If None, the default is the height of the Rhino viewport currently on the screen.

mode

Text for the display mode of the viewport to be captured.If None, the default will be the display mode of the active viewport (the last viewport in which you navigated). Acceptable inputs include: Wireframe Shaded Rendered Ghosted X-Ray Technical Artistic Pen

transparent

Boolean to note whether the captured .png file should have a transparent background. If None or False, the image will have the Rhino viewport background color.

capture [Required]

Set to "True" to capture the image of the Rhino viewport.

Outputs

file

The file path of the image taken with this component.

Legend 2D Parameters

- [source code]

Customize the properties of a screen-oreinted 2D legend displaying with the "LB Preview VisualizationSet" component.

Inputs

origin_x

An integer in pixels to note the X coordinate of the base point from where the 2D legend will be generated (assuming an origin in the upper-left corner of the screen with higher positive values of X moving to the right). Alternatively, this can be a text string ending in a % sign to denote the percentage of the screen where the X coordinate exists (eg. 5%). The default is set to make the legend clearly visible in the upper-left corner of the screen (10 pixels).

origin_y

An integer in pixels to note the Y coordinate of the base point from where the legend will be generated (assuming an origin in the upper-left corner of the screen with higher positive values of Y moving downward). Alternatively, this can be a text string ending in a % sign to denote the percentage of the screen where the X coordinate exists (eg. 5%). The default is set to make the legend clearly visible in the upper-left corner of the screen (50 pixels).

seg_height

A integer in pixels to note the height for each of the legend segments. Alternatively, this can be a text string ending in a % sign to denote the percentage of the screen (eg. 5%). The default is set to make most legends readable on standard resolution screens (25px for horizontal and 36px for vertical).

seg_width

An integer in pixels to set the width of each of the legend segments. Alternatively, this can be a text string ending in a % sign to denote the percentage of the screen (eg. 5%). The default is set to make most legends readable on standard resolution screens (36px for horizontal and 25px for vertical).

text_height

An integer in pixels to set the height for the legend text. Alternatively, this can be a text string ending in a % sign to denote the percentage of the screen (eg. 2%).

Outputs

leg_par2d

A legend parameter object that can be plugged into any of the Ladybug components with a legend.

Orient to Camera

- [source code]

Orient a series of geometries to the active viewport camera.

Inputs

geo [Required]

A series of geometries to be oriented to the camera of the active Rhino viewport.

position

A point to be used as the origin around which the the geometry will be oriented. If None, the lower left corner of the bounding box around the geometry will be used.

refresh

Connect a Grasshopper "button" component to refresh the orientation upon hitting the button. You can also connect a Grasshopper "Timer" component to update the view in real time as you navigate through the Rhino scene.

Outputs

geo

The input geometry that has been oriented to the camera of the active Rhino viewport.

Set View

Open a new viewport in Rhino that shows the parallel-projected view from the sun.

This is useful for understanding what parts of Rhino geometry are shaded at a particular hour of the day.

Inputs

direction [Required]

A vector for the direction that the viewport camera faces.

position

A point for the position of the vieport camera in 3D space. If no point is provided, the Rhino origin will be used (0, 0, 0).

look_around

Optional 2D point (aka. UV coordinates) to tilt the viewport camera off from from the input _direction. Values for UV coordinates must be between 0 and 1 and these correspond to a tilt of 90 degrees in either direction (with 0.5, 0.5 being centered on the _direction). Inputting a native Grasshopper Slider MD component will allow the most control of view offsetting.

width

An optional interger for the width (in pixels) of the Rhino viewport that will be generated.

height

An optional interger for the height (in pixels) of the Rhino viewport that will be generated.

lens_len

An optional number that sets the lens length of the viewport camera in mm. Typical values are around 20-50mm but wider angle views can be achieved by lowering this number to 10 or less. If unspecified, the lens length of the currently active Rhino viewport will be used.

mode

An optional text input for the display mode of the Rhino viewport that will be generated. For example: Wireframe, Shaded, Rendered, etc. If unspecified, the mode of the currenlty active Rhino viewport will be used

Outputs

report

The name of the viewport that was opened.

To IP

- [source code]

Convert a DataCollection to IP values.

Inputs

data_si [Required]

A DataCollection in SI units.

Outputs

data_ip

The DataCollection in IP units.

To SI

Convert a DataCollection to SI values.

Inputs

data_ip [Required]

A DataCollection in IP (or other) units.

Outputs

data_si

The DataCollection in SI units.

To Unit

Convert a DataCollection to the input _to_unit.

Inputs

data [Required]

A DataCollection to be converted to different units.

to_unit

Text representing the unit to convert the DataCollection to (eg. m2). Connect the _data and see the all_unit output for a list of all currently-supported units for a given collection. The default won't perform any unit conversion on the output data.

Outputs

all_unit

A list of all possible units that the input _data can be converted to.

data

The converted DataCollection.

Unit Converter

Convert a value or list of values from one unit to another.

Inputs

values [Required]

Values to be converted from one unit type to another.

from_u [Required]

Text indicating the units of the input _values (eg. 'C')

to_u [Required]

Text indicating the units of the output values (eg. 'K')

Outputs

all_u

A text string indicating all possible units that can be plugged into _from_u and _to_u.

values

The converted numerical values.

Adaptive Comfort Parameters

Create a set of parameters that define the acceptable conditions of the Adaptive thermal comfort model.

These parameters can be plugged into any of the components that compute Adaptive thermal comfort.

Inputs

ashrae_or_en

A boolean to note whether to use the ASHRAE-55 neutral temperature function (True) or the european neutral function (False), which is consistent with both EN-15251 and EN-16798. Note that this input will also determine default values for many of the other properties of this object.

neutral_offset

The number of degrees Celcius from the neutral temperature where the input operative temperature is considered acceptable. The default is 2.5C when the neutral temperature function is ASHRAE-55 (consistent with 90% PPD) and 3C when the neutral temperature function is EN (consistent with comfort class II). For ASHRAE-55, the following neutral offsets apply.

For the EN standard, the following neutral offsets apply.

avgm_or_runmean

A boolean to note whether the prevailing outdoor temperature is computed from the average monthly temperature (True) or a weighted running mean of the last week (False). The default is True when the neutral temperature function is ASHRAE-55 and False when the neutral temperature function is EN.

discr_or_cont_vel

A boolean to note whether discrete categories should be used to assess the effect of elevated air speed (True) or whether a continuous function should be used (False). Note that continuous air speeds were only used in the older EN-15251 standard and are not a part of the more recent EN-16798 standard. When unassigned, this will be True for discrete air speeds.

cold_prevail_limit

A number indicating the prevailing outdoor temperature below which acceptable indoor operative temperatures flat line. The default is 10C, which is consistent with both ASHRAE-55 and EN-16798. However, 15C was used for the older EN-15251 standard. This number cannot be greater than 22C and cannot be less than 10C.

conditioning

A number between 0 and 1 that represents how "conditioned" vs. "free-running" the building is. 0 = free-running (completely passive with no air conditioning) 1 = conditioned (no operable windows and fully air conditioned) The default is 0 since both the ASHRAE-55 and the EN standards prohibit the use of adaptive comfort methods when a heating/cooling system is active. When set to a non-zero number, a neutral temperature function for heated/cooled operation derived from the SCATs database will be used. For more information on how adaptive comfort methods can be applied to conditioned buildings, see the neutral_temperature_conditioned function in the ladybug_comfort documentation.

Outputs

adapt_par

An Adaptive comfort parameter object that can be plugged into any of the components that compute Adaptive thermal comfort.

PMV Comfort Parameters

- [source code]

Create a set of parameters that define the acceptable conditions of the Predicted Mean Vote (PMV) thermal comfort model.

These parameters can be plugged into any of the components that compute PMV thermal comfort.

Inputs

ppd_thresh

A number between 5 and 100 that represents the upper threshold of PPD that is considered acceptable. Default is 10, which charcterizes most buildings in the ASHRAE-55 and EN-15251 standards.

hr_upper

A number between 0 and 1 indicating the upper limit of humidity ratio that is considered acceptable. Default is 1 for essentially no limit.

hr_lower

A number between 0 and 1 indicating the lower limit of humidity ratio considered acceptable. Default is 0 for essentially no limit.

still_air_thresh

The air speed threshold in m/s at which the standard effective temperature (SET) model will be used to correct for the cooling effect of elevated air speeds. Default is 0.1 m/s, which is the limit according to ASHRAE-55.

Outputs

pmv_par

A PMV comfort parameter object that can be plugged into any of the components that compute PMV thermal comfort.

Passive Strategies

- [source code]

Provides a list of passive thermal strategies to be plugged into the "LB PMV Polygon" component.

Solar Body Parameters

Create a set of parameters that define the characteristics of a human in relation to the sun that falls on them.

These parameters can be plugged into any of the components that estimate mean radiant temperature (MRT) deltas as a result of being in the sun.

Inputs

posture

A text string indicating the posture of the body. Letters must be lowercase. Default is "standing". Choose from the following:

sharp

A number between 0 and 180 representing the solar horizontal angle relative to front of person (SHARP). 0 signifies sun that is shining directly into the person's face and 180 signifies sun that is shining at the person's back. Default is 135, asuming that a person typically faces their side or back to the sun to avoid glare.

body_az

A number between 0 and 360 representing the direction that the human is facing in degrees (0=North, 90=East, 180=South, 270=West). Default is None, which will assume that the sharp input dictates the degrees the human is facing from the sun.

absorptivity

A number between 0 and 1 representing the average shortwave absorptivity of the body (including clothing and skin color). Typical clothing values - white: 0.2, khaki: 0.57, black: 0.88 Typical skin values - white: 0.57, brown: 0.65, black: 0.84 Default is 0.7 for average (brown) skin and medium clothing.

emissivity

A number between 0 and 1 representing the average longwave emissivity of the body. Default is 0.95, which is almost always the case except in rare situations of wearing metalic clothing.

Outputs

sol_body_par

A solar body parameter object that can be plugged into any of the components that estimate mean radiant temperature (MRT) deltas as a result of being in the sun.

Dump Data

Dump any Ladybug data collections into a file. You can use "LB Load Data" component to load the data collections from the file back into Grasshopper.

Inputs

data [Required]

A list of Ladybug data collections to be written to a file.

format

Text or an integer to set the format of the output file. Choose from the options below. (Default: CSV).

name

A name for the file to which the data collections will be written. (Default: 'data').

folder

An optional directory into which the data collections will be written. The default is set to a user-specific simulation folder.

dump [Required]

Set to "True" to save the data collection to a file.

Outputs

report

Errors, warnings, etc.

data_file

The path of the file where the data collections are saved.

Load Data

- [source code]

Load Ladybug data collections from a CSV, JSON, or PKL file.

Inputs

data_file [Required]

A file path to a CSV, JSON or PKL file from which data collections will be loaded.

load [Required]

Set to "True" to load the data collections from the _data_file.

Outputs

report

Reports, errors, warnings, etc.

data

A list of honeybee objects that have been re-serialized from the input file.

Open Directory

- [source code]

Open a file's directory in Windows Explorer or Mac Finder. This is useful for understanding weather data or simulation files.

Inputs

file_path [Required]

Full path to a file or directory to be opened in Explorer/Finder.

Outputs

report

Reports, errors, warnings, etc.

Open File

- [source code]

Open a file in whatever program is associated with the file extension. This can be used to open simulation files in particular applications (eg. opening an OSM file in the OpenStudio Application).

Inputs

file_path [Required]

Full path to a file to be opened.

Outputs

report

Reports, errors, warnings, etc.

Compass

Create a compass sign that indicates the direction of North in the Rhino scene.

Inputs

north

A number between -360 and 360 for the counterclockwise difference between the North and the positive Y-axis in degrees. Counterclockwise means "90 is West and 270 is East". This can also be Vector for the direction to North. (Default: 0)

center

A point for the center position of the compass in the Rhino scene. (Default: (0, 0, 0) aka. the Rhino scene origin).

scale

A number to set the scale of the compass. The default is 1, which corresponds to a radius of 10 meters in the current Rhino model's unit system.

Outputs

compass

A set of circles, lines and text objects that mark the cardinal directions in the Rhino scene.

Magnetic to True North

- [source code]

Compute a True North angle and vector from Magnetic North at a given location.

This component uses then World Magnetic Model (WMM) developed and maintained by NOAA. https://www.ncei.noaa.gov/products/world-magnetic-model

Inputs

location [Required]

A ladybug Location that has been output from the "LB Import EPW" component or the "LB Construct Location" component. This is used to determine the difference between magnetic and true North.

mag_north [Required]

A number between -360 and 360 for the counterclockwise difference between Magnetic North and the positive Y-axis in degrees. Counterclockwise means "90 is West and 270 is East". This can also be Vector for the magnetic North direction.

year

A number for the year in which the Magnetic North was evaluated. Decimal values are accepted. This is needed as the location of Magnetic North has been moving at a rate of roughly 50 km/year for the past couple of decades. (Default: 2025).

cof_file

An optional path to a .COF file containing the coefficients that form the inputs for the World Magnetic Model (WMM). A new set of coefficients is published roughly every 5 years as the magnetic poles continue to move. If unspecified, coefficients will be taken from the most recent model. COF files with the most recent coefficients and historical values are available at:

Outputs

mag_declination

The magnetic declination in degrees. Magnetic declination is the difference between magnetic North and true North at a given location on the globe (expressed in terms of degrees).

true_north

A number between -360 and 360 for the True North angle in degrees.

true_north_vec

A vector for the True North direction. This can be plugged into any of the north_ inputs of the other LAdybug Tools components.

Activities Met List

- [source code]

Provides a list of available activites and outputs the metabolic rate of that activity for use in the Ladybug PMV comfort calculator.

Area Aggregate

- [source code]

Get a Data Collection that is aggregated by an area value.

Note that this component will raise a ValueError if the data type in the header of the data collection is not normalizable to yeild a useful type.

Inputs

data [Required]

A Data Collection to be aggregated by the input _area.

area [Required]

A number representing area by which all of the data is aggregated.

unit

Text for the units that the area value is in. Acceptable inputs include 'm2', 'ft2' and any other unit that is supported. (Default: m2).

Outputs

data

A Ladybug data collection object aggregated by the input area

Area Normalize

- [source code]

Get a Data Collection that is normalized by an area value.

Note that this component will raise a ValueError if the data type in the header of the data collection is not normalizable to yeild a useful type. Also note that a ZeroDivisionError will be raised if the input area is equal to 0.

Inputs

data [Required]

A Data Collection to be normalized by the input _area.

area [Required]

A number representing area by which all of the data is normalized.

unit

Text for the units that the area value is in. Acceptable inputs include 'm2', 'ft2' and any other unit that is supported. (Default: m2).

Outputs

data

A Ladybug data collection object derived that is normalized by the input area.

Clothing List

Provides a list of clothing values based on selected apparel. Plug the output into a native Grasshopper Mass Addition component to get the total clothing level of the clothing ensemble.

Construct Matrix

- [source code]

Construct a Ladybug Matrix object from a Grasshopper Data Tree of values.

Inputs

values [Required]

A Grasshopper Data Tree of values to be merged into a matrix object.

Outputs

matrix

A Ladybug Matrix object encapsulating all of the input values.

Create Legend

- [source code]

Create a custom legend for any set of data or range. Creating a legend with this component allows for a bit more flexibility than what can be achieved by working with the legends automatically output from different studies.

Inputs

values [Required]

A list of numerical values or data collections that the legend refers to. This can also be the minimum and maximum numerical values of the data. The legend's maximum and minimum values will be set by the max and min of the data set.

base_plane

An optional plane or point to set the location of the legend. (Default: Rhino origin - (0, 0, 0))

title

A text string representing a legend title. Legends are usually titled with the units of the data.

legend_par

Optional legend parameters from the "LB Legend Parameters" component.

leg_par2d

Outputs

mesh

A colored mesh for the legend colors.

title_obj

A text object for the legend title.

label_objs

An array of text objects for the label text.

label_text

An array of text strings for the label text.

colors

An array of colors that align with the input _values. This can be used to color geometry that aligns with the values.

Deconstruct Matrix

Deconstruct a Ladybug Matrix object into a Grasshopper Data Tree of values.

Inputs

matrix [Required]

A Ladybug Matrix object such as the intersection matrices output from any of the ray-tracing components (eg. "LB Direct Sun Hours").

Outputs

values

The numerical values of the matrix as a Grasshopper Data Tree.

Deconstruct VisualizationSet

Deconstruct a Ladybug VisualizationSet into all of its constituent objects.

This includes Context Geometry, Analysis Geometry, and any data sets that are associated with the analysis geometry. The last one is particularly helpful for performing analysis in the data associated with a particular visualization.

Inputs

vis_set [Required]

Outputs

context

A list of geometry objects that constitute the context geometry of the VisualizationSet. When the VisualizationSet contains multiple context geometry instances, this will be a data tree with one branch for each context object.

analysis

A list of geometry objects that constitute the analysis geometry of the VisualizationSet. When the VisualizationSet contains multiple analysis geometry instances, this will be a data tree with one branch for each analysis object.

data

A list of numbers that constitue the data set associated with the analysis geometry. In the event of multiple data sets assigned to the same analysis geometry, this will be a data tree of numbers with one branch for each data set. In the event of multiple analysis geometries, this will be a nested data tree where the first number in the path matches the analysis geometry branch and the last number matches the data set number.

Dump VisualizationSet

Dump a Ladybug VisualiztionSet into a file.

The "LB Preview VisualizationSet" component can be used to visualize the content from the file back into Grasshopper.

Inputs

vis_set [Required]

A VisualizationSet object to be written to a file. This can also be VisualizationSet arguments from any Ladybug Tools component with a vis_set output.

format

Text or an integer to set the format of the output file. Choose from the options below. (Default: JSON).

name

A name for the file to which the VisualizationSet will be written. The default is derived from the identifier of the visualization set.

folder

An optional directory into which the VisualizationSet will be written. The default is set to a user-specific simulation folder.

dump [Required]

Set to "True" to save the VisualizationSet to a file.

Outputs

report

Errors, warnings, etc.

vs_file

The path of the file where the VisualisationSet is saved. The "LB Preview VisualizationSet" component can be used to visualize the content from the file back into Grasshopper.

Filter by Normal

Filter or select faces of geometry based on their orientation.

Inputs

north

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

geometry [Required]

Rhino Breps and/or Rhino Meshes which will be broken down into individual planar faces and filtered based on the direction they face.

orientation [Required]

Text for the direction that the geometry is facing. This can also be a number between 0 and 360 for the azimuth (clockwise horizontal degrees from North) that the geometry should face. Choose from the following:

up_angle

A number in degrees for the maximum declination angle from the positive Z Axis that is considerd up. This should be between 0 and 90 for the results to be practical. (Default: 30).

down_angle

A number in degrees for the maximum angle difference from the newative Z Axis that is considerd down. This should be between 0 and 90 for the results to be practical. (Default: 30).

horiz_angle

Angle in degrees for the horizontal deviation from _orientation that is still considered to face that orientation. This should be between 0 and 90 for the results to be practical. Note that this input has no effect when the input orientation is "Up" or "Down". (Default: 23).

Outputs

report

...

sel_geo

Selected faces of the input geometry that are facing the direction corresponding to the input criteria.

Legend Parameters Categorized

Use this component to change the colors, range, and display of any Ladybug legend along with the corresponding colored mesh that the legend refers to.

The legend parameters from this component have more limitations than the normal Legend Parameters. However, these legend parameters will do auto-categorization of data, binning values into groups based on custom ranges.

Inputs

domain [Required]

A list of one or more numbers noting the bondaries of the data categories. For example, [100, 2000] creates three categories of (<100, 100-2000, >2000). Values must always be ordered from lowest to highest.

colors [Required]

An list of color objects with a length equal to the number of items in the domain + 1. These are used to color each of the categories of data.

categories

An optional list of text strings with a length equal to the colors. These will be used to name each of the categories in the legend. If None, the legend text will simply mark the numerical ranges of the categories. (Default: None).

continuous_cols

Boolean noting whether colors generated are continuous or discrete. If True, the colors generated from the corresponding legend will be in a continuous gradient. If False, they will be categorized in incremental groups according to the segment_count.

continuous_leg

num_decimals

An optional integer to set the number of decimal places for the numbers in the legend text. Default is 2.

larger_smaller

Boolean noting whether to include larger than and smaller than (> and <) values after the upper and lower legend segment text. Default is False.

vert_or_horiz

Boolean. If True, the legend mesh and text points will be generated vertically. If False, they will genrate a horizontal legend. Default is True for a vertically-oriented legend.

base_plane

A Plane to note the starting point and orientation from where the legend will be genrated. The default is the world XY plane at origin (0, 0, 0).

seg_height

An optional number to set the height of each of the legend segments. Default is 1.

seg_width

An optional number to set the width of each of the legend segments. Default is 1 when legend is vertical. When horizontal, the default is (text_height * (number_decimal_places + 2)).

text_height

An optional number to set the size of the text in model units. Default is half of the segment_height.

font

An optional text string to specify the font to be used for the text. Examples include "Arial", "Times New Roman", "Courier" (all without quotations). Default is "Arial".

Outputs

leg_par

A legend parameter object that can be plugged into any of the Ladybug components with a legend.

Mesh to Hatch

- [source code]

Bake a clored mesh into the Rhino scene as a group of colored hatches.

This is useful when exporting ladybug graphics from Rhino to vector-based programs like Inkscape or Illustrator since hatches are exported from Rhino as colored-filled polygons.

Inputs

mesh [Required]

A colored mesh (or list of colored meshes) to be baked into the Rhino scene as groups of colored hatches.

layer

Text for the layer name on which the hatch will be added. If unspecified, it will be baked onto the currently active layer.

run [Required]

Set to 'True' to bake the mesh into the scene as hatches.

Outputs

report

Reports, errors, warnings ...

PET Body Parameters

Create a set of parameters that define the body characteristics for the PET model.

These parameters can be plugged into any of the components that compute PET thermal comfort.

Inputs

age

The age of the human subject in years. (Default: 36 years for middle age of the average worldwide life expectancy).

sex

A value between 0 and 1 to indicate the sex of the human subject, which influences the computation of basal metabolism. 0 indicates male. 1 indicates female and any number in between denotes a weighted average between the two. (Default: 0.5).

height

The height of the human subject in meters. Average male height is around 1.75m while average female height is 1.55m. (Default: 1.65m for a worldwide average between male and female height).

body_mass

The body mass of the human subject in kilograms. (Default: 62 kg for the worldwide average adult human body mass).

posture

A text string indicating the posture of the body. Letters must be lowercase. Default is "standing". Choose from the following:

humid_acclim

A boolean to note whether the human subject is acclimated to a humid/tropical climate (True) or is acclimated to a temperate climate (False). When True, the categories developed by Lin and Matzarakis (2008) will be used to assess comfort instead of the original categories developed by Matzarakis and Mayer (1996).

Outputs

pet_par

A PET comfort parameter object that can be plugged into any of the components that compute PET thermal comfort.

Passive Strategy Parameters

- [source code]

Adjust the assumptions of the passive strategies that can be overalid on the Psychrometric Chart using the "LB PMV Polygon" component. The default assumptions of each of the strategies are as follows:

Thermal Mass + Night Vent - The polygon represents the conditions under which shaded, night-flushed thermal mass can keep occupants cool. By default, this polygon assumes that temperatures can get as high as 12 C above the max temperature of the comfort polygon as long temperatures 8 hours before the hot hour are 3.0 C lower than the max temperture of the comfort polygon. This parameter component can be used to adjust these two temperature values and the number of hours that the building keeps its "coolth".

Occupant Use of Fans - This polygon is made by assuming that an air speed of 1.0 m/s is the maximum speed tolerable before papers start blowing around and conditions become annoying to occupants. The polygon is determined by running a PMV model with this fan air speed and the PMV inputs of the warmest comfort conditions. This parameter component can be used to adjust this maximum acceptable air speed.

Capture Internal Heat - The polygon is made by assuming a minimum building balance point of 12.8 C and any conditions that are warmer than that will keep occupants comfortable (up to the comfort polygon). It is assumed that, above this building balance temperature, the building is free-running and occupants are able to open windows as they wish to keep conditions from overshooting the comfort polygon. Note that the default balance temperature of 12.8 C is fairly low and assumes a significant amount of internal heat from people, equipment. etc. Or the building as a well-insulated envelope to ensure what internal heat there is can leave the building slowly. This parameter component can be used to adjust the balance temperature.

Passive Solar Heating - The polygon represents the conditions under which sun-exposed thermal mass can keep occupants warm in winter. By default, this polygon assumes that temperatures can get as high as 12 C above the max temperature of the comfort polygon as long temperatures 8 hours before the hot hour are 3.0 C lower than the max temperture of the comfort polygon. This parameter component can be used to adjust these two temperature values and the number of hours that the building keeps its "coolth".

Inputs

day_above_comf

A number in degrees Celsius representing the maximum daily temperature above the comfort range which can still be counted in the "Mass + Night Vent" polygon. (Default: 12 C).

night_below_comf

A number in degrees Celsius representing the minimum temperature below the maximum comfort polygon temperature that the outdoor temperature must drop at night in order to count towards the "Mass + Night Vent" polygon. (Default: 3C).

fan_air_speed

The air speed around the occupants that the fans create in m/s. This is used to create the "Occupant Use of Fans" polygon. Note that values above 1 m/s tend to blow papers off desks. (Default: 1.0 m/3)

balance_temp

The balance temperature of the building in Celsius when accounting for all internal heat. This is used to create the "Capture Internal Heat" polygon. This value must be greater or equal to 5 C (balance temperatures below 10 C are exceedingly rare) and it should be less than the coldest temperature of the merged comfort polygon in order to be meaningful. (Default: 12.8 C)

solar_heat_cap

A number representing the amount of outdoor solar flux (W/m2) that is needed to raise the temperature of the theoretical building by 1 degree Celsius. The lower this number, the more efficiently the space is able to absorb passive solar heat. The default assumes a relatively small passively solar heated zone without much mass. A higher number will be required the larger the space is and the more mass that it has. (Default: 50 W/m2)

time_constant

A number that represents the amount of time in hours that a therortical building can passively maintain its temperature. This is used to determine how many hours a space can maintain a cool temperature after night flushing for the "Mass + Night Vent" polygon. It is also used to determine how many hours a space can store solar radiation for the "Passive Solar Heating" polygon. The default assumes a relatively well-isulated building with a thermal mass typical of most contemporary buildings. Higher mass buildings will be able to support a longer time constant. (Default: 8 hours).

Outputs

strategy_par

Passive strategy parameters that can be plugged into the "LB PMV Polygon" to adjust the assumptions of the passive strategy polygons.

Screen Oriented Text

- [source code]

Generate screen-oriented text that displays in the Rhino scene as a head-up display (HUD).

This is useful when there are certain summary results or information that should always be displayed on-screen.

Inputs

text [Required]

Text string to be displayed in the plane of the screen.

leg_par2d

Optional 2D LegendParameters from the "LB Legend Parameters 2D" component, which will be used to customize a text in the plane of the screen. Note that only the text_height, origin_x and origin_y inputs of this component affect the placement of the text.

font

An optional text string to specify the font to be used for the text. Examples include "Arial", "Times New Roman", "Courier" (all without quotations). Default is "Arial".

color

An optional color to set the color of the text. If unspecified, it will be black.

Outputs

SortByLayers

- [source code]

Sort and group Rhino objects by layers. Please find the source code from: https://github.com/ladybug-tools/ladybug-grasshopper-dotnet

Inputs

A list of Rhino objects that associated with sortable layers

Optional object list to sort synchronously

Outputs

Sorted objects by layers

Synchronously sorted objects

Grouped layer names

Time Aggregate

Convert a DataCollection of point-in-time values to its time-aggregated equivalent.

For example, if the collection has a Power data type in W, this method will return a collection with an Energy data type in kWh.

Inputs

data [Required]

A houry, sub-hourly or daily data collection that can be aggregated over time to yield data of a different metric. (eg. a data collection of Power values in W).

Outputs

data_aggr

The data collection aggregated over time. (eg. a data collection of Energy values in kWh).

Time Rate of Change

- [source code]

Convert a DataCollection of time-aggregated values to time rate of change units.

For example, if the collection has an Energy data type in kWh, this method will return a collection with an Power data type in W.

Inputs

data [Required]

A houry, sub-hourly or daily data collection that can converted to a time rate of change metric. (eg. a data collection of Energy values in kWh).

Outputs

data_rate

The data collection converted to time rate of changevalues. (eg. a data collection of Energy values in kWh).

UTCI Comfort Parameters

Create a set of parameters that define the acceptable conditions of the Universal Thermal Climate Index (UTCI) comfort model.

These parameters can be plugged into any of the components that compute UTCI comfort.

Inputs

cold_thresh

Temperature in Celsius below which the UTCI represents cold stress. (Default: 9C).

heat_thresh

A number between 0 and 1 indicating the upper limit of humidity ratio that is considered acceptable. Default is 1 for essentially no limit.

Outputs

utci_par

A UTCI comfort parameter object that can be plugged into any of the components that compute UTCI thermal comfort.