ladybug_display.analysis module

Class for representing geometry colored with data according to legend parameters.

class ladybug_display.analysis.AnalysisGeometry(identifier, geometry, data_sets, active_data=0, display_mode='Surface', hidden=False)[source]

Bases: _VisualizationBase

An object where geometry is colored with data.

Multiple data sets for different metrics can correspond to the same geometry.

Parameters:

  • identifier – Text string for a unique object ID. Must be less than 100 characters and not contain spaces or special characters.

  • geometry – A list of ladybug-geometry objects that is aligned with the values in the input data_sets. The length of this list should usually be equal to the total number of values in each data_set, indicating that each geometry gets a single color. Alternatively, if all of the geometry objects are meshes, the number of values in the data can be equal to the total number of faces across the meshes or the total number of vertices across the meshes.

  • data_sets – A list of VisualizationData objects representing the data sets that are associated with the input geometry.

  • active_data – An integer to denote which of the input data_sets should be displayed by default. (Default: 0).

  • display_mode –

    Text to indicate the display mode (surface, wireframe, etc.). Choose from the following. (Default: Surface).

    • Surface

    • SurfaceWithEdges

    • Wireframe

    • Points

  • hidden – A boolean to note whether the geometry is hidden by default and must be un-hidden to be visible in the 3D scene. (Default: False).

Properties:

  • identifier

  • display_name

  • geometry

  • data_sets

  • active_data

  • display_mode

  • hidden

  • min_point

  • max_point

  • matching_method

  • user_data

ToString()[source]

Overwrite .NET ToString.

add_data_set(data, insert_index=None)[source]

Add a data set to this AnalysisGeometry object.

Parameters:

  • data – A VisualizationData object to be added to this AnalysisGeometry.

  • insert_index – An integer for the index at which the data should be inserted. If None, the data will be appended to the end. (Default: None).

duplicate()

Get a copy of this object.

classmethod from_dict(data)[source]

Create an AnalysisGeometry from a dictionary.

Parameters:

data – A python dictionary in the following format

{
"type": "AnalysisGeometry",
"identifier": "",  # unique object identifier
"geometry": [],  # list of geometry objects
"data_sets": [],  # list of data sets associated with the geometry
"active_data": 0,  # integer for the index of the active data set
"display_mode": "Surface",  # text for the display mode of the data
"hidden": True  # boolean for whether the layer is hidden by default
}
graphic_container(data_index=None, min_point=None, max_point=None)[source]

Get a Ladybug GraphicContainer object, which can be used to draw legends.

Parameters:

  • data_index – Integer for the index of the data set for which a GraphicContainer will be returned. If None, the active_data set will be used. (Default: None).

  • min_point – An optional Point3D to denote the minimum bounding box for the graphic container. If None, this object’s own min_point will be used, which corresponds to the bounding box around the geometry. (Default: None).

  • max_point – An optional Point3D to denote the maximum bounding box for the graphic container. If None, this object’s own max_point will be used, which corresponds to the bounding box around the geometry. (Default: None).

move(moving_vec)[source]

Move this AnalysisGeometry along a vector.

Parameters:

moving_vec – A ladybug_geometry Vector3D with the direction and distance to move the AnalysisGeometry.

remove_data_set(data_index)[source]

Remove a data set from this AnalysisGeometry object.

Parameters:

data_index – An integer for the data index to be removed.

rotate_xy(angle, origin)[source]

Rotate this AnalysisGeometry counterclockwise in the world XY plane.

Parameters:

  • angle – An angle in degrees.

  • origin – A ladybug_geometry Point3D for the origin around which the object will be rotated.

scale(factor, origin=None)[source]

Scale this AnalysisGeometry by a factor from an origin point.

Parameters:

  • factor – A number representing how much the object should be scaled.

  • origin – A ladybug_geometry Point3D representing the origin from which to scale. If None, it will be scaled from the World origin (0, 0, 0).

to_dict()[source]

Get AnalysisGeometry as a dictionary.

T_FORMABLE_2D = (<class 'ladybug_geometry.geometry2d.pointvector.Point2D'>, <class 'ladybug_geometry.geometry2d.ray.Ray2D'>, <class 'ladybug_geometry.geometry2d.line.LineSegment2D'>, <class 'ladybug_geometry.geometry2d.polyline.Polyline2D'>, <class 'ladybug_geometry.geometry2d.arc.Arc2D'>, <class 'ladybug_geometry.geometry2d.polygon.Polygon2D'>, <class 'ladybug_geometry.geometry2d.mesh.Mesh2D'>)
property active_data

Get or set an integer for the index of data set that is actively displaying.

property data_sets

Get a tuple of VisualizationData assigned to the AnalysisGeometry.

property display_mode

Get or set text to indicate the display mode.

property display_name

Get or set text for the object name without any character restrictions.

This is typically used to set the layer of the object in the interface that renders the VisualizationSet. A :: in the display_name can be used to denote sub-layers following a convention of ParentLayer::SubLayer.

If not set, the display_name will be equal to the object identifier.

property full_id

Get a string with both the object display_name and identifier.

This is formatted as display_name[identifier].

This is useful in error messages to give users an easy means of finding invalid objects within models. If there is no display_name assigned, only the identifier will be returned.

property geometry

Get a tuple of geometry objects assigned to this AnalysisGeometry.

property hidden

Get or set a boolean for whether the geometry is hidden by default.

property identifier

Get or set a text string for the unique object identifier.

This identifier remains constant as the object is mutated, copied, and serialized to different formats.

property matching_method

Get text for the method by which the data is matched to the geometry.

This will be one of the following.

  • geometries - One value is assigned for each geometry

  • faces - One value is assigned per each face of the Mesh

  • vertices - One value is assigned per each vertex of the Mesh

property max_point

A Point3D for the maximum bounding box vertex around all of the geometry.

property min_point

A Point3D for the minimum bounding box vertex around all of the geometry.

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)

class ladybug_display.analysis.VisualizationData(values, legend_parameters=None, data_type=None, unit=None)[source]

Bases: VisualizationMetaData

Represents a data set for visualization with legend parameters and data type.

Parameters:

  • values – A list of numerical values that will be used to generate the visualization colors.

  • legend_parameters – An Optional LegendParameters object to override default parameters of the legend. None indicates that default legend parameters will be used. (Default: None).

  • data_type – Optional DataType from the ladybug datatype subpackage (ie. Temperature()) , which will be used to assign default legend properties. If None, the legend associated with this object will contain no units unless a unit below is specified. (Default: None).

  • unit – Optional text string for the units of the values. (ie. “C”). If None or empty, the default units of the data_type will be used. If no data type is specified in this case, this will simply be an empty string. (Default: None).

Properties:

  • values

  • legend_parameters

  • legend

  • data_type

  • unit

  • value_colors

  • user_data

ToString()[source]

Overwrite .NET ToString.

convert_to_ip(convert_min_max=False)[source]

Convert the VisualizationData to IP units.

Note that the VisualizationData must have a data_type and unit assigned to it in order for this method to run successfully and not raise an exception.

Parameters:

convert_min_max – Boolean to note whether the min and max of the LegendParameters should also have their units converted, which may or may not be desirable depending on when this min and max was originally set. (Default: False).

convert_to_si(convert_min_max=False)[source]

Convert the VisualizationData to SI units.

Note that the VisualizationData must have a data_type and unit assigned to it in order for this method to run successfully and not raise an exception.

Parameters:

convert_min_max – Boolean to note whether the min and max of the LegendParameters should also have their units converted, which may or may not be desirable depending on when this min and max was originally set. (Default: False).

convert_to_unit(unit, convert_min_max=False)[source]

Convert the VisualizationData to the input unit.

Note that the VisualizationData must have a data_type and unit assigned to it in order for this method to run successfully and not raise an exception.

Parameters:

  • unit – Text indicating the units to which the value should be converted (eg. ‘kWh/m2’). See ladybug.datatype.UNITS for a dictionary containing all acceptable units for each data type.

  • convert_min_max – Boolean to note whether the min and max of the LegendParameters should also have their units converted, which may or may not be desirable depending on when this min and max was originally set. (Default: False).

duplicate()[source]

Get a copy of this object.

classmethod from_dict(data)[source]

Create VisualizationData from a dictionary.

Parameters:

data – A python dictionary in the following format

{
"type": "VisualizationData",
"values": [0, 10],
"legend_parameters": {},  # optional LegendParameter specification
"data_type": {},  # optional DataType object
"unit": "C"  # optional text for the units
}
graphic_container(min_point, max_point)[source]

Get a Ladybug GraphicContainer object, which can be used to a draw legend.

Parameters:

  • min_point – An optional Point3D to denote the minimum bounding box for the graphic container.

  • max_point – An optional Point3D to denote the maximum bounding box for the graphic container.

to_dict()[source]

Get visualization data as a dictionary.

to_svg(width=800, height=600)[source]

Get the legend of the visualization data as an editable SVG object.

Casting this SVG object to string will give the file contents of a SVG. The legend will be rendered using the properties2d of the LegendParameters, which is suitable for exporting the legend as a standalone graphic.

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

property data_type

Get the data_type input to this object (if it exists).

property legend

Get the legend assigned to this data set.

property legend_parameters

Get the legend parameters assigned to this data set.

property unit

Get the unit input to this object (if it exists).

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 value_colors

Get a List of colors associated with the assigned values.

property values

Get the values assigned to the data set.

class ladybug_display.analysis.VisualizationMetaData(legend_parameters=None, data_type=None, unit=None)[source]

Bases: object

Represents the metadata for visualization with legend parameters and data type.

Parameters:

  • legend_parameters – An Optional LegendParameters object to override default parameters of the legend. None indicates that default legend parameters will be used. (Default: None).

  • data_type – Optional DataType from the ladybug datatype subpackage (ie. Temperature()) , which will be used to assign default legend properties. If None, the legend associated with this object will contain no units unless a unit below is specified. (Default: None).

  • unit – Optional text string for the units of the values. (ie. “C”). If None or empty, the default units of the data_type will be used. If no data type is specified in this case, this will simply be an empty string. (Default: None).

Properties:

  • legend_parameters

  • data_type

  • unit

  • user_data

ToString()[source]

Overwrite .NET ToString.

classmethod from_dict(data)[source]

Create VisualizationMetaData from a dictionary.

Parameters:

data – A python dictionary in the following format

{
"type": "VisualizationMetaData",
"legend_parameters": {},  # optional LegendParameter specification
"data_type": {},  # optional DataType object
"unit": "C"  # optional text for the units
}
to_dict()[source]

Get visualization data as a dictionary.

property data_type

Get the data_type input to this object (if it exists).

property legend_parameters

Get the legend parameters assigned to this data set.

property unit

Get the unit input to this object (if it exists).

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)