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

  • min_point_with_legend

  • max_point_with_legend

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

static legend_3d_to_svg(legend)[source]

Translate a 3D Legend geometry into an SVG.

Parameters:

legend – A Ladybug Legend object to be converted to SVG.

Returns:

A list of SVG elements in the following order.

  • legend_mesh – A colored mesh for the legend.

  • legend_title – A text object for the legend title.

  • legend_text – Text objects for the rest of the legend text.

static legend_text_objects(legend)[source]

Get DisplayText3D objects that correspond with a 3D legend.

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.

project_2d(plane)[source]

“Project this AnalysisGeometry into a plane to get it in the plane’s 2D system.

This is useful as a pre-step before converting to SVG to get the geometry from a certain view.

Parameters:

plane – The Plane into which the AnalysisGeometry will be projected.

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.

to_svg(width=800, height=600, interactive=False, render_3d_legend=False, render_2d_legend=False, default_leg_pos=None)[source]

Get this AnalysisGeometry as an editable SVG object.

Casting the SVG object to string will give the file contents of a SVG.

Note that it is expected that the AnalysisGeometry has been scaled to fit in the specified width and height dimensions and it exists within the lower-right quadrant of the world coordinate system (Quadrant 4) in oder to be translated correctly into the XY coordinate system of the screen.

Parameters:

  • width – The screen width in pixels.

  • height – The screen height in pixels.

  • interactive – A boolean to note whether this AnalysisGeometry should be rendered with interactive hover effects (True) or they should be rendered as static (False). If hover effects are included, then colored SVG objects will be highlighted with a thick black border when hovered over and hover text will appear with the value associated with the geometry. (Default: False).

  • render_3d_legend – Boolean to note whether a 3D version of the legend for any AnalysisGeometry should be included in the SVG (following the 3D dimensions specified in the LegendParameters).

  • render_2d_legend – Boolean to note whether a 2D version of the legend for any AnalysisGeometry should be included in the SVG (following the 2D dimensions specified in the LegendParameters).

  • default_leg_pos – An optional tuple of 3 numbers that can be used to customize the default legend positions such that they are not on top of one another when multiple AnalysisGeometries exist in a VisualizationSet. (Default: None).

HOVER_STYLE = '.a_geo:hover {stroke:black;stroke_width:1;opacity:0.5;}'
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 max_point_with_legend

A Point3D for the maximum around all geometry, including 3D legends.

property min_point

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

property min_point_with_legend

A Point3D for the minimum around all geometry, including 3D legends.

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.

static legend_2d_to_svg(legend, width=800, height=600)[source]

Translate a 2D Legend geometry into an SVG.

Parameters:

  • legend – A Ladybug Legend object to be converted to SVG.

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

Returns:

A list of SVG elements in the following order.

  • legend_mesh – A colored mesh for the legend.

  • legend_title – A text object for the legend title.

  • legend_text – Text objects for the rest of the legend text.

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)