ladybug_display.visualization module

class ladybug_display.visualization.AnalysisGeometry(identifier, geometry, data_sets, active_data=0, display_mode='Surface', hidden=False)

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

Overwrite .NET ToString.

add_data_set(data, insert_index=None)

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)

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)

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)

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)

Remove a data set from this AnalysisGeometry object.

Parameters:

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

rotate_xy(angle, origin)

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)

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

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.visualization.ContextGeometry(identifier, geometry, hidden=False)

Bases: _VisualizationBase

An object representing context geometry to display.

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 or ladybug-display objects that gives context to analysis geometry or other aspects of the visualization. Typically, these will display in wireframe around the geometry, though the properties of display geometry can be used to customize the visualization.

• 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

• hidden

• min_point

• max_point

• user_data

ToString()

Overwrite .NET ToString.

duplicate()

Get a copy of this object.

classmethod from_dict(data)

Create an ContextGeometry from a dictionary.

Parameters:

data – A python dictionary in the following format

{
"type": "ContextGeometry",
"identifier": "",  # unique object identifier
"geometry": [],  # list of ladybug-display geometry objects
"hidden": True  # boolean for whether the layer is hidden by default
}

static geometry_to_wireframe(geometry)

Convert a raw ladybug-geometry object into a wireframe ladybug-display object.

Parameters:

geometry – A raw ladybug-geometry object to be converted to a wireframe ladybug-display object.

move(moving_vec)

Move this ContextGeometry along a vector.

Parameters:

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

rotate_xy(angle, origin)

Rotate this ContextGeometry 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)

Scale this ContextGeometry 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()

Get ContextGeometry as a dictionary.

WIREFRAME_MAP = {<class 'ladybug_geometry.geometry2d.arc.Arc2D'>: (<class 'ladybug_display.geometry2d.arc.DisplayArc2D'>, None), <class 'ladybug_geometry.geometry2d.line.LineSegment2D'>: (<class 'ladybug_display.geometry2d.line.DisplayLineSegment2D'>, None), <class 'ladybug_geometry.geometry2d.mesh.Mesh2D'>: (<class 'ladybug_display.geometry2d.mesh.DisplayMesh2D'>, None, 'Wireframe'), <class 'ladybug_geometry.geometry2d.pointvector.Point2D'>: (<class 'ladybug_display.geometry2d.point.DisplayPoint2D'>, None), <class 'ladybug_geometry.geometry2d.pointvector.Vector2D'>: (<class 'ladybug_display.geometry2d.vector.DisplayVector2D'>, None), <class 'ladybug_geometry.geometry2d.polygon.Polygon2D'>: (<class 'ladybug_display.geometry2d.polygon.DisplayPolygon2D'>, None, 'Wireframe'), <class 'ladybug_geometry.geometry2d.polyline.Polyline2D'>: (<class 'ladybug_display.geometry2d.polyline.DisplayPolyline2D'>, None), <class 'ladybug_geometry.geometry2d.ray.Ray2D'>: (<class 'ladybug_display.geometry2d.ray.DisplayRay2D'>, None), <class 'ladybug_geometry.geometry3d.arc.Arc3D'>: (<class 'ladybug_display.geometry3d.arc.DisplayArc3D'>, None), <class 'ladybug_geometry.geometry3d.cone.Cone'>: (<class 'ladybug_display.geometry3d.cone.DisplayCone'>, None, 'Wireframe'), <class 'ladybug_geometry.geometry3d.cylinder.Cylinder'>: (<class 'ladybug_display.geometry3d.cylinder.DisplayCylinder'>, None, 'Wireframe'), <class 'ladybug_geometry.geometry3d.face.Face3D'>: (<class 'ladybug_display.geometry3d.face.DisplayFace3D'>, None, 'Wireframe'), <class 'ladybug_geometry.geometry3d.line.LineSegment3D'>: (<class 'ladybug_display.geometry3d.line.DisplayLineSegment3D'>, None), <class 'ladybug_geometry.geometry3d.mesh.Mesh3D'>: (<class 'ladybug_display.geometry3d.mesh.DisplayMesh3D'>, None, 'Wireframe'), <class 'ladybug_geometry.geometry3d.plane.Plane'>: (<class 'ladybug_display.geometry3d.plane.DisplayPlane'>, None), <class 'ladybug_geometry.geometry3d.pointvector.Point3D'>: (<class 'ladybug_display.geometry3d.point.DisplayPoint3D'>, None), <class 'ladybug_geometry.geometry3d.pointvector.Vector3D'>: (<class 'ladybug_display.geometry3d.vector.DisplayVector3D'>, None), <class 'ladybug_geometry.geometry3d.polyface.Polyface3D'>: (<class 'ladybug_display.geometry3d.polyface.DisplayPolyface3D'>, None, 'Wireframe'), <class 'ladybug_geometry.geometry3d.polyline.Polyline3D'>: (<class 'ladybug_display.geometry3d.polyline.DisplayPolyline3D'>, None), <class 'ladybug_geometry.geometry3d.ray.Ray3D'>: (<class 'ladybug_display.geometry3d.ray.DisplayRay3D'>, None), <class 'ladybug_geometry.geometry3d.sphere.Sphere'>: (<class 'ladybug_display.geometry3d.sphere.DisplaySphere'>, None, 'Wireframe')}

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 or set a tuple of ladybug_display geometry objects for context.

When setting this property, it is also acceptable to include raw ladybug_geometry objects in the list and they will automatically be converted into a wireframe representation as a ladybug-display object.

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 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.visualization.VisualizationData(values, legend_parameters=None, data_type=None, unit=None)

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

Overwrite .NET ToString.

convert_to_ip(convert_min_max=False)

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)

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)

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

Get a copy of this object.

classmethod from_dict(data)

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)

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

Get visualization data as a dictionary.

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.visualization.VisualizationMetaData(legend_parameters=None, data_type=None, unit=None)

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

Overwrite .NET ToString.

classmethod from_dict(data)

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

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)

class ladybug_display.visualization.VisualizationSet(identifier, geometry, units=None)

Bases: _VisualizationBase

A visualization set containing analysis and context geometry to be visualized.

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 AnalysisGeometry and ContextGeometry objects to display in the visualization. Each geometry object will typically be translated to its own layer within the interface that renders the VisualizationSet.

• units –

  Text for the units system in which the visualization geometry exists. If None, the geometry will always be assumed to be in the current units system of the display interface. (Default: None). Choose from the following:

  • Meters

  • Millimeters

  • Feet

  • Inches

  • Centimeters

Properties:

• identifier

• display_name

• geometry

• min_point

• max_point

• units

• user_data

ToString()

Overwrite .NET ToString.

add_geometry(geometry, insert_index=None)

Add a ContextGeometry or AnalysisGeometry object to this VisualizationSet.

Parameters:

• geometry – A ContextGeometry or AnalysisGeometry object to be added to this VisualizationSet.

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

add_vis_set(vis_set)

Add all geometry objects of another VisualizationSet to this one.

Parameters:

vis_set – A VisualizationData object to be added to this AnalysisGeometry.

check_duplicate_identifiers(raise_exception=True, detailed=False)

Check that there are no duplicate geometry object identifiers in the set.

Parameters:

• raise_exception – Boolean to note whether a ValueError should be raised if duplicate identifiers are found. (Default: True).

• detailed – Boolean for whether the returned object is a detailed list of dicts with error info or a string with a message. (Default: False).

Returns:

A string with the message or a list with a dictionary if detailed is True.

convert_to_units(units)

Convert all of the geometry in this VisualizationSet to certain units.

This involves scaling the geometry and changing the VisualizationSet’s units property.

Parameters:

units –

Text for the units to which the VisualizationSet geometry should be converted. Choose from the following:

• Meters

• Millimeters

• Feet

• Inches

• Centimeters

duplicate()

Get a copy of this object.

classmethod from_dict(data)

Create an VisualizationSet from a dictionary.

Parameters:

data – A python dictionary in the following format

{
"type": "VisualizationSet",
"identifier": "",  # unique object identifier
"geometry": []  # list of AnalysisGeometry and ContextGeometry objects
}

classmethod from_file(vis_set_file)

Initialize a VisualizationSet from a JSON or pkl file, auto-sensing the type.

Parameters:

VisualizationSet – Path to either a VisualizationSet JSON or pkl file.

classmethod from_json(json_file)

Initialize a VisualizationSet from a JSON file.

Parameters:

json_file – Path to VisualizationSet JSON file.

classmethod from_pkl(pkl_file)

Initialize a Model from a pkl file.

Parameters:

pkl_file – Path to pkl file.

classmethod from_single_analysis_geo(identifier, geometry, values, legend_parameters=None, data_type=None, unit=None)

Create an VisualizationSet from a raw geometry object and a list of values.

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

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

graphic_container(geo_index=0, data_index=None, min_point=None, max_point=None)

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

Parameters:

• geo_index – Integer for the index of the geometry for which a GraphicContainer will be returned. Note that this index must refer to an analysis geometry in order to produce a valid graphic container. (Default: 0).

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

Move this VisualizationSet along a vector.

Parameters:

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

remove_geometry(geo_index)

Remove a geometry object from this VisualizationSet.

Parameters:

geo_index – An integer for the geometry index to be removed.

rotate_xy(angle, origin)

Rotate this VisualizationSet 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)

Scale this VisualizationSet 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()

Get VisualizationSet as a dictionary.

to_json(name, folder, indent=None)

Write VisualizationSet to JSON.

Parameters:

• name – A text string for the name of the JSON file.

• folder – A text string for the directory where the JSON will be written.

• indent – A positive integer to set the indentation used in the resulting JSON file. (Default: None).

to_pkl(name, folder)

Write VisualizationSet to compressed pickle file (pkl).

Parameters:

• name – A text string for the name of the pickle file.

• folder – A text string for the directory where the pickle file will be written.

UNITS = ('Meters', 'Millimeters', 'Feet', 'Inches', 'Centimeters')

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 or set a tuple of AnalysisGeometry and ContextGeometry objects.

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 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 units

Get or set Text for the units system in which the geometry 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)