ladybug.legend module¶

class ladybug.legend.Legend(values, legend_parameters=None)[source]¶

Bases: object

Ladybug legend used to get legend geometry, legend text, generate colors, etc.

Parameters

values – A List or Tuple of numerical values that will be used to generate the legend and colors.
legend_parameters – An Optional LegendParameter object to override default parameters of the legend.

Properties:

legend_parameters
values
value_colors
title
title_location
title_location_scene_2d
segment_text
segment_text_location
segment_text_location_scene_2d
segment_mesh
segment_mesh_scene_2d
color_range
segment_numbers
segment_colors
segment_length
is_min_default
is_max_default

Usage:

1.
data = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
legend = Legend(data, LegendParameters(segment_count=6))
print(legend.segment_text)
print(legend.segment_mesh)
print(legend.segment_colors)

>> ['0.00', '1.80', '3.60', '5.40', '7.20', '9.00']
>> Mesh3D (6 faces) (14 vertices)
>> ((R:75, G:107, B:169), (R:159, G:189, B:238), (R:224, G:229, B:145),
    (R:247, G:200, B:53), (R:234, G:113, B:0), (R:234, G:38, B:0))

2.
data = [100, 300, 500, 1000, 2000, 3000]
leg_colors = [Color(0, 0, 255), Color(0, 255, 0), Color(255, 0, 0)]
legend_par = LegendParametersCategorized([300, 2000], leg_colors)
legend_par.category_names = ['low', 'desired', 'too much']
legend_par.continuous_colors = False  # get data in only 3 colors
legend = Legend(data, legend_par)
print(legend.segment_text)
print(legend.segment_mesh)
print(legend.segment_colors)
print(legend.value_colors)
>> ['low', 'desired', 'too much']
>> Mesh3D (3 faces) (8 vertices)
>> ((R:0, G:0, B:255), (R:0, G:255, B:0), (R:255, G:0, B:0))
>> ((R:0, G:0, B:255), (R:0, G:255, B:0), (R:0, G:255, B:0),
    (R:0, G:255, B:0), (R:0, G:255, B:0), (R:255, G:0, B:0))

3.
data = [-0.5, 0, 0.5]
legend_par = LegendParameters(min=-1, max=1, segment_count=3)
legend_par.ordinal_dictionary = {-3: 'Cold', -2: 'Cool', -1: 'Slightly Cool',
                                 0: 'Neutral',
                                 1: 'Slightly Warm', 2: 'Warm', 3: 'Hot'}
legend = Legend(data, legend_par)
print(legend.segment_text)
print(legend.segment_mesh)
print(legend.segment_colors)
legend.legend_parameters.segment_count = 5
print(legend.segment_text)
legend.legend_parameters.min = -2
legend.legend_parameters.max = 2
print(legend.segment_text)
>> ['Slightly Cool', 'Neutral', 'Slightly Warm']
>> Mesh3D (3 faces) (8 vertices)
>> ((R:75, G:107, B:169), (R:249, G:235, B:89), (R:234, G:38, B:0))
>> ['Slightly Cool', '', 'Neutral', '', 'Slightly Warm']
>> ['Cool', 'Slightly Cool', 'Neutral', 'Slightly Warm', 'Warm']

ToString()[source]¶: Overwrite .NET ToString.

color_map_2d(width=800, height=600)[source]¶

A Matrix of color values for the legend.

This is useful for generating images of the colored 2D legend to be output into the plane of the screen.

Parameters

width – The screen width in pixels, which is needed to interpret dimensions specified in the percent of the screen. (Default: 800).
height – The screen height in pixels, which is needed to interpret dimensions specified in the percent of the screen. (Default: 600).

duplicate()[source]¶: Return a copy of the current legend.

classmethod from_dict(data)[source]¶

Create a legend from a dictionary.

Parameters: data – A python dictionary in the following format

{
"values": [0, 10],
"legend_parameters": None
}

static parse_dim_2d(dim_str, screen_dim)[source]¶

Parse a string for a 2D screen dimension into pixel width and height.

Parameters

dim_str – A string for a screen dimension. (eg. 12px, 5%).
screen_dim – The total screen dimension in pixels, which is needed to interpret dimensions specified in the percent of the screen.

segment_text_location_2d(width=800, height=600)[source]¶

A list of Point2D for the location of legend segment text in the 2D screen.

The Point2Ds are derived from the 2D properties of the legend parameters.

Parameters

width – The screen width in pixels, which is needed to interpret dimensions specified in the percent of the screen. (Default: 800).
height – The screen height in pixels, which is needed to interpret dimensions specified in the percent of the screen. (Default: 600).

title_location_2d(width=800, height=600)[source]¶

A Point2D for the location of the title.

The Point2D is derived from the 2D properties of the legend parameters.

Parameters

width – The screen width in pixels, which is needed to interpret dimensions specified in the percent of the screen. (Default: 800).
height – The screen height in pixels, which is needed to interpret dimensions specified in the percent of the screen. (Default: 600).

to_dict()[source]¶: Get legend as a dictionary.

property color_range¶: The color range associated with this legend.

property is_max_default¶

Boolean noting whether the max is default.

Useful when deciding whether to override the legend to properly display an ordinal dictionary.

property is_min_default¶

Boolean noting whether the min is default.

Useful when deciding whether to override the legend to properly display an ordinal dictionary.

property legend_parameters¶: The legend parameters assigned to this legend.

property segment_colors¶: A list of colors associated with the legend segments.

property segment_length¶: An integer for the number of segment lengths in the legend.

property segment_mesh¶: A Ladybug Mesh3D for the legend colors.

property segment_mesh_scene_2d¶

A Ladybug Mesh2D for the legend colors.

The Mesh2D is derived from the 3D plane and properties of the legend parameters.

property segment_numbers¶: Get a list of numbers along a linear scale from the min to max.

property segment_text¶: A list of text strings for the segment labels of the legend.

property segment_text_location¶: A list of Plane objects for the location of the legend segment text.

property segment_text_location_scene_2d¶

A list of Point2D for the location of the legend segment text.

The Point2Ds are derived from the 3D plane and properties of the legend parameters, making them useful for output into certain 2D interfaces.

property title¶: A text string for the title of the legend.

property title_location¶: A Plane for the location and orientation of the legend title.

property title_location_scene_2d¶

A Point2D for the location of the title.

The Point2D is derived from the 3D plane and properties of the legend parameters, making it useful for output to certain 2D interfaces.

property value_colors¶: A List of colors associated with the assigned values.

property values¶: The data set assigned to the legend.

class ladybug.legend.Legend2DParameters(origin_x=None, origin_y=None, segment_height=None, segment_width=None, text_height=None)[source]¶

Bases: object

Object to customize the properties of legends in the 2D plane of a screen.

Parameters

origin_x – A text string to note the X 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 X moving to the right). Text must be formatted as an integer followed by “px” (to denote the number of screen pixels) or a number followed by “%” (to denote the percentage of the screen). Examples include 10px, 5%. The default is set to make the legend clearly visible on the screen (10px).
origin_y – A text string 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). Text must be formatted as an integer followed by “px” (to denote the number of screen pixels) or a number followed by “%” (to denote the percentage of the screen). Examples include 10px, 5%. The default is set to make the legend clearly visible on the screen (50px).
segment_height – A text string to note the height for each of the legend segments. Text must be formatted as an integer followed by “px” (to denote the number of screen pixels) or a number followed by “%” (to denote the percentage of the screen). Examples include 10px, 5%. The default is set to make most legends readable (25px for horizontal and 36px for vertical).
segment_width – A text string to set the width for each of the legend segments. Text must be formatted as an integer followed by “px” (to denote the number of screen pixels) or a number followed by “%” (to denote the percentage of the screen). Examples include 10px, 5%. The default is set to make most legends readable (36px for horizontal and 25px for vertical).
text_height – A text string to set the height for the legend text. Text must be formatted as an integer followed by “px” (to denote the number of screen pixels) or a number followed by “%” (to denote the percentage of the screen). Examples include 10px, 5%. Default is 12px.

Properties:

origin_x
origin_y
segment_height
segment_width
text_height
is_default
is_origin_x_default
is_origin_y_default
is_segment_height_default
is_segment_width_default
is_text_height_default

ToString()[source]¶: Overwrite .NET ToString method.

duplicate()[source]¶: Return a copy of the current Legend2DParameters.

classmethod from_dict(data)[source]¶

Create Legend2DParameters from a dictionary.

Parameters: data – A python dictionary in the following format

{
"type": "Legend2DParameters",
"origin_x": "20px",
"origin_y": "20px",
"segment_height": "5%",
"segment_width": "2%",
"text_height": "3%"
}

to_dict()[source]¶: Get Legend2DParameters as a dictionary.

static valid_dim_string(dim_string, invalid_obj='Legend2DParameters', raise_exception=True)[source]¶

Check if a string is in a valid format for assigning 2D dimensions.

Parameters

dim_string – Text to check if it fits the format for 2D dimensions.
invalid_obj – An optional name of the object to be reported in the error message when raise_exception is True.
raise_exception – Boolean to note whether an exception should be raised if the dim_string is not in the correct format. Otherwise, this method will simply return True/False for whether the string meets the format.

VALID_DIM = re.compile('^\\d*px|\\d*%$|\\d*.\\d*%$')¶

property is_default¶: Boolean noting whether all properties are defaulted.

property is_origin_x_default¶: Boolean noting whether the origin X coordinate is defaulted.

property is_origin_y_default¶: Boolean noting whether the origin Y coordinate is defaulted.

property is_segment_height_default¶: Boolean noting whether the segment height is defaulted.

property is_segment_width_default¶: Boolean noting whether the segment width is defaulted.

property is_text_height_default¶: Boolean noting whether the text height is defaulted.

property origin_x¶

Get or set text to note the X coordinate from where the legend will be drawn.

The default is set to make the legend clearly visible on the screen (10px).

property origin_y¶

Get or set text to note the Y coordinate from where the legend will be drawn.

The default is set to make the legend clearly visible on the screen (50px).

property segment_height¶

Get or set the height for each of the legend segments.

The default is set to make most legends readable (25px for horizontal and 36px for vertical).

property segment_width¶

Get or set the width for each of the legend segments.

The default is set to make most legends readable (36px for horizontal and 25px for vertical).

property text_height¶: Get or set the height for the legend text.

class ladybug.legend.Legend3DParameters(base_plane=None, segment_height=None, segment_width=None, text_height=None)[source]¶

Bases: object

Object to customize the properties of legends in the 3D scene.

Parameters

base_plane – A Ladybug Plane object to note the starting point from where the legend will be generated. If None, the default is the world XY plane at origin (0, 0, 0) unless the legend is assigned to a specific geometry, in which case the origin is in the lower right corner of the geometry bounding box for vertical legends and the upper right corner for horizontal legends.
segment_height – A number to set the height for each of the legend segments. If None, the default is 1 unless the legend is assigned to a specific geometry, in which case it is automatically set to a value on an appropriate scale (some fraction of the bounding box around the geometry).
segment_width – A number to set the width for each of the legend segments. If None, the default is 1 unless the legend is assigned to a specific geometry, in which case it is automatically set to a value on an appropriate scale (some fraction of the bounding box around the geometry).
text_height – A number to set the height for the legend text. If None, the default is 1/3 of the segment_height.

Properties:

base_plane
segment_height
segment_width
text_height
is_default
is_base_plane_default
is_segment_height_default
is_segment_width_default
is_text_height_default

ToString()[source]¶: Overwrite .NET ToString method.

duplicate()[source]¶: Return a copy of the current Legend3DParameters.

classmethod from_dict(data)[source]¶

Create Legend3DParameters from a dictionary.

Parameters: data – A python dictionary in the following format

{
"type": "Legend3DParameters",
"base_plane": {"type": "Plane", "o": [11, 0, 0], "n": [0, 0, 1]},
"segment_height": 0.5,
"segment_width": 0.25,
"text_height": 0.25
}

to_dict()[source]¶: Get Legend3DParameters as a dictionary.

property base_plane¶: Get or set a Ladybug Point3D for the base point of the legend.

property is_base_plane_default¶: Boolean noting whether the base plane is defaulted.

property is_default¶: Boolean noting whether all properties are defaulted.

property is_segment_height_default¶: Boolean noting whether the segment height is defaulted.

property is_segment_width_default¶: Boolean noting whether the segment width is defaulted.

property is_text_height_default¶: Boolean noting whether the text height is defaulted.

property segment_height¶

Get or set the height for each of the legend segments.

The default is 1 unless the legend is assigned to a specific geometry, in which case it is automatically set to a value on an appropriate scale (some fraction of the bounding box around the geometry).

property segment_width¶

Get or set the width for each of the legend segments.

Default is 1 when legend is vertical. When horizontal, the default is text_height * (max_number_of_digits + 2) where max_number_of_digits is the number of digits displaying in the legend parameter max.

property text_height¶

Get or set the height for the legend text.

Default is 1/3 of the segment_height.

class ladybug.legend.LegendParameters(min=None, max=None, segment_count=None, colors=None, title=None, base_plane=None)[source]¶

Bases: object

Ladybug legend parameters used to customize legends.

All properties of LegendParameters are set-able (except the is_property_default ones).

Parameters

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.
segment_count – An integer 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.
title – 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.
base_plane – A Ladybug Plane object to note the starting point from where the legend will be generated. The default is the world XY plane at origin (0, 0, 0).

Properties:

min
max
segment_count
colors
continuous_legend
title
ordinal_dictionary
decimal_count
include_larger_smaller
vertical
font
user_data
properties_3d
base_plane
segment_height
segment_width
text_height
properties_2d
origin_x
origin_y
segment_height_2d
segment_width_2d
text_height_2d
is_segment_count_default
are_colors_default
is_title_default
is_base_plane_default
is_segment_height_default
is_segment_width_default
is_text_height_default
is_origin_x_default
is_origin_y_default
is_segment_height_2d_default
is_segment_width_2d_default
is_text_height_2d_default

Usage:

lp = LegendParameters(min=0, max=100, segment_count=6)
lp.vertical = False
lp.segment_width = 5

ToString()[source]¶: Overwrite .NET ToString method.

colors_by_set(colorset_name)[source]¶

Set the colors of this object using the name of a Colorset.

This will also add the name of the color set to this LegendParameter’s user_data.

Parameters: colorset_name – The name of a Colorset to dictate the colors of this legend parameter object (eg. ecotect) (eg. benefit_harm). See the the ladybug Colorset object for a complete list of color sets.

duplicate()[source]¶: Return a copy of the current legend parameters.

classmethod from_dict(data)[source]¶

Create LegendParameters from a dictionary.

Parameters: data – A python dictionary in the following format

{
"type": "LegendParameters",
"min": -3,
"max": 3,
"segment_count": 7
}

to_dict()[source]¶: Get legend parameters as a dictionary.

property are_colors_default¶: Boolean noting whether the colors are defaulted.

property base_plane¶: Get or set a Plane for the base point and orientation of the 3D legend.

property colors¶: Get or set the colors defining the legend.

property continuous_legend¶

Boolean noting whether legend is drawn as a gradient or discrete segments.

If True, the legend mesh will be drawn vertex-by-vertex resulting in a continuous gradient instead of discrete segments. If False, the mesh will be generated with one face for each of the segment_count. Default: False for depicting discrete categories.

property decimal_count¶

Get or set an integer for the number of decimal places in the legend text.

Default is 2. Note that this input has no bearing on the resulting legend text when an ordinal_dictionary is present.

property font¶

Get or set the font for the legend text.

Examples include “Arial”, “Times New Roman”, “Courier”. Note that this parameter may not have an effect on certain interfaces that have limited access to fonts. Default is “Arial”.

property include_larger_smaller¶: Boolean noting whether > and < should be included in legend segment text.

property is_base_plane_default¶: Boolean noting whether the base plane in 3D space is defaulted.

property is_origin_x_default¶: Boolean noting whether the X coordinate in 2D is defaulted.

property is_origin_y_default¶: Boolean noting whether the Y coordinate in 2D is defaulted.

property is_segment_count_default¶: Boolean noting whether the number of segments is defaulted.

property is_segment_height_2d_default¶: Boolean noting whether the segment height in 2D is defaulted.

property is_segment_height_default¶: Boolean noting whether the segment height in 3D space is defaulted.

property is_segment_width_2d_default¶: Boolean noting whether the segment width in 2D is defaulted.

property is_segment_width_default¶: Boolean noting whether the segment width in 3D space is defaulted.

property is_text_height_2d_default¶: Boolean noting whether the text height in 3D space is defaulted.

property is_text_height_default¶: Boolean noting whether the text height in 3D space is defaulted.

property is_title_default¶: Boolean noting whether the title is defaulted.

property max¶: Get or set legend maximum.

property min¶: Get or set legend minimum.

property ordinal_dictionary¶

Get or set an optional dictionary that maps values to text categories.

If None, numerical values will be used for the legend segments. If not, text categories will be used and the legend will be ordinal. Note that, if the number of items in the dictionary are less than the segment_count, some segments won’t receive any label. Examples for possible dictionaries include: {-1: ‘Cold’, 0: ‘Neutral’, 1: ‘Hot’} {0: ‘False’, 1: ‘True’}

property origin_x¶: Get or set text for the X coordinate from where the 2D legend will be drawn.

property origin_y¶: Get or set text for the Y coordinate from where the 2D legend will be drawn.

property properties_2d¶: Get or set a Legend2DParameters for the properties of 2D legends.

property properties_3d¶: Get or set a Legend3DParameters for the properties of 3D legends.

property segment_count¶: Get or set the number of segments in the legend.

property segment_height¶: Get or set the height for each of the legend segments in 3D space.

property segment_height_2d¶: Get or set the height for each of the legend segments in 2D space.

property segment_width¶: Get or set the width for each of the legend segments in 3D space.

property segment_width_2d¶: Get or set the width for each of the legend segments in 2D space.

property text_height¶: Get or set the height for the legend text in 3D space.

property text_height_2d¶: Get or set the height for the legend text in 2D space.

property title¶: Get or set the text for the title of the legend.

property user_data¶: Get or set an optional dictionary for additional meta data for this object. This will be None until it has been set. All keys and values of this dictionary should be of a standard Python type to ensure correct serialization of the object to/from JSON (eg. str, float, int, list, dict)

property vertical¶

Boolean noting whether legend is vertical (True) or horizontal (False).

Default: True for a vertically-oriented legend.

class ladybug.legend.LegendParametersCategorized(domain, colors, category_names=None, title=None, base_plane=None)[source]¶

Bases: LegendParameters

Ladybug legend parameters used to customize legends.

These legend parameters have more limitations than the base LegendParameters class. However, these legend parameters will do auto-categorization of data, binning values into groups based on custom ranges.

Parameters

domain – A list of one or more numbers noting the boundaries 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 – 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.
category_names – 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).
title – 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.
base_plane – A Ladybug Plane object to note the starting point from where the legend will be generated. The default is the world XY plane at origin (0, 0, 0).

Properties:

domain
colors
category_names
continuous_colors
continuous_legend
title
ordinal_dictionary
decimal_count
include_larger_smaller
vertical
font
user_data
properties_3d
base_plane
segment_height
segment_width
text_height
properties_2d
origin_x
origin_y
segment_height_2d
segment_width_2d
text_height_2d
min
max
segment_count
is_title_default
is_base_plane_default
is_segment_height_default
is_segment_width_default
is_text_height_default

ToString()¶: Overwrite .NET ToString method.

colors_by_set(colorset_name)¶

Set the colors of this object using the name of a Colorset.

This will also add the name of the color set to this LegendParameter’s user_data.

Parameters: colorset_name – The name of a Colorset to dictate the colors of this legend parameter object (eg. ecotect) (eg. benefit_harm). See the the ladybug Colorset object for a complete list of color sets.

duplicate()¶: Return a copy of the current legend parameters.

classmethod from_dict(data)[source]¶

Create LegendParametersCategorized from a dictionary.

Parameters: data – A python dictionary in the following format

{
"type": "LegendParametersCategorized",
"domain": [100, 2000],
"colors": [{'r': 0, 'g': 0, 'b': 0},
           {'r': 0, 'g': 0, 'b': 100},
           {'r': 255, 'g': 0, 'b': 0}],
"category_names": ["low", "desired", "high"]
}

to_dict()[source]¶: Get legend parameters categorized as a dictionary.

property are_colors_default¶: Boolean noting whether the colors are defaulted.

property base_plane¶: Get or set a Plane for the base point and orientation of the 3D legend.

property category_names¶: Get or set a list of text for the names of the categories.

property colors¶: Get or set the colors defining the legend.

property continuous_colors¶

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. (Default: False).

property continuous_legend¶

Boolean noting whether legend is drawn as a gradient or discrete segments.

property decimal_count¶

Get or set an integer for the number of decimal places in the legend text.

Default is 2. Note that this input has no bearing on the resulting legend text when an ordinal_dictionary is present.

property domain¶: Get or set a list of numbers noting the boundaries of the data categories.

property font¶

Get or set the font for the legend text.

Examples include “Arial”, “Times New Roman”, “Courier”. Note that this parameter may not have an effect on certain interfaces that have limited access to fonts. Default is “Arial”.

property include_larger_smaller¶: Boolean noting whether > and < should be included in legend segment text.

property is_base_plane_default¶: Boolean noting whether the base plane in 3D space is defaulted.

property is_origin_x_default¶: Boolean noting whether the X coordinate in 2D is defaulted.

property is_origin_y_default¶: Boolean noting whether the Y coordinate in 2D is defaulted.

property is_segment_count_default¶: Boolean noting whether the number of segments is defaulted.

property is_segment_height_2d_default¶: Boolean noting whether the segment height in 2D is defaulted.

property is_segment_height_default¶: Boolean noting whether the segment height in 3D space is defaulted.

property is_segment_width_2d_default¶: Boolean noting whether the segment width in 2D is defaulted.

property is_segment_width_default¶: Boolean noting whether the segment width in 3D space is defaulted.

property is_text_height_2d_default¶: Boolean noting whether the text height in 3D space is defaulted.

property is_text_height_default¶: Boolean noting whether the text height in 3D space is defaulted.

property is_title_default¶: Boolean noting whether the title is defaulted.

property max¶: Get legend maximum. This is derived from the domain.

property min¶: Get legend minimum. This is derived from the domain.

property ordinal_dictionary¶: Always None for a LegendParametersCategorized.

property origin_x¶: Get or set text for the X coordinate from where the 2D legend will be drawn.

property origin_y¶: Get or set text for the Y coordinate from where the 2D legend will be drawn.

property properties_2d¶: Get or set a Legend2DParameters for the properties of 2D legends.

property properties_3d¶: Get or set a Legend3DParameters for the properties of 3D legends.

property segment_count¶

Get the number of segments in the legend.

This is always equal to one more than the length of the domain.

property segment_height¶: Get or set the height for each of the legend segments in 3D space.

property segment_height_2d¶: Get or set the height for each of the legend segments in 2D space.

property segment_width¶: Get or set the width for each of the legend segments in 3D space.

property segment_width_2d¶: Get or set the width for each of the legend segments in 2D space.

property text_height¶: Get or set the height for the legend text in 3D space.

property text_height_2d¶: Get or set the height for the legend text in 2D space.

property title¶: Get or set the text for the title of the legend.

property user_data¶: Get or set an optional dictionary for additional meta data for this object. This will be None until it has been set. All keys and values of this dictionary should be of a standard Python type to ensure correct serialization of the object to/from JSON (eg. str, float, int, list, dict)

property vertical¶

Boolean noting whether legend is vertical (True) or horizontal (False).

Default: True for a vertically-oriented legend.