Skip to content

compas_fab.scene ¤

Classes¤

BaseRigidBodyObject ¤

BaseRigidBodyObject(
    draw_visual=True, draw_collision=False, native_scale=1.0, *args, **kwargs
)

Base class for representing a rigid body object in a CAD environment.

This class is automatically instantiated by the RobotCellObject when a RigidBody is present in the robot cell. However, it can also be used independently to draw a RigidBody in a CAD environment.

Parameters:

  • draw_visual (bool, default: True ) –

    If True, the visual meshes will be drawn. Default is True.

  • draw_collision (bool, default: False ) –

    If True, the collision meshes will be drawn. Default is False.

  • native_scale (float, default: 1.0 ) –

    The native scale factor to visualize the rigid body, in case the native CAD environment uses a different unit system other than meters. The native scale value should be set such that a meter_mesh.scale(1/native_scale) will create the correct mesh in the native unit system. For example, if the unit system of the visualization environment is millimeters, native_scale should be set to '0.001'. Default is 1.0.

Notes 
The initial parameters `draw_visual`, `draw_collision`, and `native_scale` cannot be changed after initialization.

Methods:¤

ToString ¤
ToString()

Converts the instance to a string.

This method exists for .NET compatibility. When using IronPython, the implicit string conversion that usually takes place in CPython will not kick-in, and in its place, IronPython will default to printing self.GetType().FullName or similar. Overriding the ToString method of .NET object class fixes that and makes Rhino/Grasshopper display proper string representations when the objects are printed or connected to a panel or other type of string output.

__jsondump__ ¤
__jsondump__(minimal=False)

Return the required information for serialization with the COMPAS JSON serializer.

Parameters:

  • minimal (bool, default: False ) –

    If True, exclude the GUID from the dump dict.

Returns:

__jsonload__ classmethod ¤
__jsonload__(data, guid=None, name=None)

Construct an object of this type from the provided data to support COMPAS JSON serialization.

Parameters:

  • data (dict) –

    The raw Python data representing the object.

  • guid (str, default: None ) –

    The GUID of the object.

  • name (str, default: None ) –

    The name of the object.

Returns:

add ¤
add(item, **kwargs)

Add a child item to the scene object.

Parameters:

  • item (:class:`compas.data.Data`) –

    The item to add.

  • **kwargs (dict, default: {} ) –

    Additional keyword arguments to create the scene object for the item.

Returns:

  • class:`compas.scene.SceneObject` –

    The scene object associated with the added item.

Raises:

  • ValueError –

    If the scene object does not have an associated scene node.

clear ¤
clear()

The main clearing method.

copy ¤
copy(cls=None, copy_guid=False)

Make an independent copy of the data object.

Parameters:

  • cls (Type[:class:`compas.data.Data`], default: None ) –

    The type of data object to return. Defaults to the type of the current data object.

  • copy_guid (bool, default: False ) –

    If True, the copy will have the same guid as the original.

Returns:

  • class:`compas.data.Data` –

    An independent copy of this object.

draw ¤
draw(rigid_body_state: RigidBodyState | None = None)

Draw the rigid body object in the respective CAD environment. It will return the native geometry objects that were created.

In Rhino, this method will create Rhino.Geometry.Mesh objects and add them to the Rhino document. In GHPython, this method will create Rhino.Geometry.Mesh objects and return them.

Parameters:

  • rigid_body_state (RigidBodyState | None, default: None ) –

    The rigid body state to draw.

Returns:

  • List[object] –

    A list of native geometry objects representing the visual and collision meshes of the rigid body.

from_json classmethod ¤
from_json(filepath)

Construct an object of this type from a JSON file.

Parameters:

  • filepath (str) –

    The path to the JSON file.

Returns:

  • class:`compas.data.Data` –

    An instance of this object type if the data contained in the file has the correct schema.

Raises:

  • TypeError –

    If the data in the file is not a :class:compas.data.Data.

from_jsonstring classmethod ¤
from_jsonstring(string)

Construct an object of this type from a JSON string.

Parameters:

  • string (str) –

    The JSON string.

Returns:

  • class:`compas.data.Data` –

    An instance of this object type if the data contained in the string has the correct schema.

Raises:

  • TypeError –

    If the data in the string is not a :class:compas.data.Data.

remove ¤
remove(node)

Remove a child node from this node.

Parameters:

  • node (:class:`compas.datastructures.TreeNode`) –

    The node to remove.

Returns:

  • None –
sha256 ¤
sha256(as_string=False)

Compute a hash of the data for comparison during version control using the sha256 algorithm.

Parameters:

  • as_string (bool, default: False ) –

    If True, return the digest in hexadecimal format rather than as bytes.

Returns:

Examples:

>>> from compas.datastructures import Mesh
>>> mesh = Mesh.from_obj(compas.get("faces.obj"))
>>> v1 = mesh.sha256()
>>> v2 = mesh.sha256()
>>> mesh.vertex_attribute(mesh.vertex_sample(1)[0], "z", 1)
>>> v3 = mesh.sha256()
>>> v1 == v2
True
>>> v2 == v3
False
to_json ¤
to_json(filepath, pretty=False, compact=False, minimal=False)

Convert an object to its native data representation and save it to a JSON file.

Parameters:

  • filepath (str) –

    The path to the JSON file.

  • pretty (bool, default: False ) –

    If True, format the output with newlines and indentation.

  • compact (bool, default: False ) –

    If True, format the output without any whitespace.

  • minimal (bool, default: False ) –

    If True, exclude the GUID from the JSON output.

to_jsonstring ¤
to_jsonstring(pretty=False, compact=False, minimal=False)

Convert an object to its native data representation and save it to a JSON string.

Parameters:

  • pretty (bool, default: False ) –

    If True, format the output with newlines and indentation.

  • compact (bool, default: False ) –

    If True, format the output without any whitespace.

  • minimal (bool, default: False ) –

    If True, exclude the GUID from the JSON output.

Returns:

  • str –

    The JSON string.

traverse ¤
traverse(strategy='depthfirst', order='preorder')

Traverse the tree from this node.

Parameters:

  • strategy ((depthfirst, breadthfirst), default: "depthfirst" ) –

    The traversal strategy.

  • order ((preorder, postorder), default: "preorder" ) –

    The traversal order. This parameter is only used for depth-first traversal.

Yields:

  • class:`compas.datastructures.TreeNode` –

    The next node in the traversal.

Raises:

  • ValueError –

    If the strategy is not "depthfirst" or "breadthfirst". If the order is not "preorder" or "postorder".

update ¤
update(rigid_body_state: RigidBodyState)

Update the rigid body object with the given rigid body state.

Parameters:

  • rigid_body_state (RigidBodyState) –

    The rigid body state to update the object.

Notes

Here we do not assume whether that the CAD-specific ._transform method will operate on the native geometry in place, or creating a new object. This is up to the CAD-specific implementation. The ._transform method should return the transformed geometry object, whether it is a new object or the same object.

validate_data classmethod ¤
validate_data(data)

Validate the data against the object's data schema.

The data is the raw data that can be used to construct an object of this type with the classmethod __from_data__.

Parameters:

  • data (Any) –

    The data for validation.

Returns:

  • Any –

BaseRobotCellObject ¤

BaseRobotCellObject(
    draw_visual=True, draw_collision=False, native_scale=1.0, *args, **kwargs
)

Base class for all robot cell objects.

The RobotCellObject is a container for all the objects that are part of a robot cell. It does not draw and update the native geometry itself, but delegates this to the respective SceneObject instances that are part of the robot cell.

The RobotCellObject and its constituent CAD-specific SceneObject instances provides caching of the native geometry whenever possible, so that the native geometry is only created once and then updated in place. This provides a performance improvement when the robot cell is drawn multiple times such as during interactive manipulation (e.g. in GHPython) or visualizing a trajectory as animation.

In order to take advantage of the the caching, users should reuse the RobotCellObject instance as long as the robot cell remain the same, and only update the robot cell state when needed.

If caching function is not desired, simply remove the native geometry and create a new instance of the RobotCellObject every time the robot cell is drawn.

Parameters:

  • draw_visual (bool, default: True ) –

    If True, the visual meshes will be drawn. Default is True.

  • draw_collision (bool, default: False ) –

    If True, the collision meshes will be drawn. Default is False.

  • native_scale (float, default: 1.0 ) –

    The native scale factor to visualize the meshes in the robot cell, in case the native CAD environment uses a different unit system other than meters. The native scale value should be set such that a meter_mesh.scale(1/native_scale) will create the mesh in the native unit system. For example, if the unit system of the visualization environment is millimeters, native_scale should be set to '0.001'. Default is 1.0.

Notes 
The initial parameters `draw_visual`, `draw_collision`, and `scale` cannot be changed after initialization.

Methods:¤

ToString ¤
ToString()

Converts the instance to a string.

This method exists for .NET compatibility. When using IronPython, the implicit string conversion that usually takes place in CPython will not kick-in, and in its place, IronPython will default to printing self.GetType().FullName or similar. Overriding the ToString method of .NET object class fixes that and makes Rhino/Grasshopper display proper string representations when the objects are printed or connected to a panel or other type of string output.

__jsondump__ ¤
__jsondump__(minimal=False)

Return the required information for serialization with the COMPAS JSON serializer.

Parameters:

  • minimal (bool, default: False ) –

    If True, exclude the GUID from the dump dict.

Returns:

__jsonload__ classmethod ¤
__jsonload__(data, guid=None, name=None)

Construct an object of this type from the provided data to support COMPAS JSON serialization.

Parameters:

  • data (dict) –

    The raw Python data representing the object.

  • guid (str, default: None ) –

    The GUID of the object.

  • name (str, default: None ) –

    The name of the object.

Returns:

add ¤
add(item, **kwargs)

Add a child item to the scene object.

Parameters:

  • item (:class:`compas.data.Data`) –

    The item to add.

  • **kwargs (dict, default: {} ) –

    Additional keyword arguments to create the scene object for the item.

Returns:

  • class:`compas.scene.SceneObject` –

    The scene object associated with the added item.

Raises:

  • ValueError –

    If the scene object does not have an associated scene node.

clear ¤
clear()

The main clearing method.

copy ¤
copy(cls=None, copy_guid=False)

Make an independent copy of the data object.

Parameters:

  • cls (Type[:class:`compas.data.Data`], default: None ) –

    The type of data object to return. Defaults to the type of the current data object.

  • copy_guid (bool, default: False ) –

    If True, the copy will have the same guid as the original.

Returns:

  • class:`compas.data.Data` –

    An independent copy of this object.

draw ¤
draw(robot_cell_state: RobotCellState | None = None)

Return all native geometry (in the CAD environment) belonging to the robot cell.

The geometry contains the robot model, rigid bodies, and tools.

Parameters:

  • robot_cell_state (RobotCellState | None, default: None ) –

    The state of the robot cell, containing the configuration of the robot and the state of the rigid bodies and tools.

Returns:

  • List[object] –

    A list of native geometry objects representing the robot cell in the CAD environment.

from_json classmethod ¤
from_json(filepath)

Construct an object of this type from a JSON file.

Parameters:

  • filepath (str) –

    The path to the JSON file.

Returns:

  • class:`compas.data.Data` –

    An instance of this object type if the data contained in the file has the correct schema.

Raises:

  • TypeError –

    If the data in the file is not a :class:compas.data.Data.

from_jsonstring classmethod ¤
from_jsonstring(string)

Construct an object of this type from a JSON string.

Parameters:

  • string (str) –

    The JSON string.

Returns:

  • class:`compas.data.Data` –

    An instance of this object type if the data contained in the string has the correct schema.

Raises:

  • TypeError –

    If the data in the string is not a :class:compas.data.Data.

remove ¤
remove(node)

Remove a child node from this node.

Parameters:

  • node (:class:`compas.datastructures.TreeNode`) –

    The node to remove.

Returns:

  • None –
sha256 ¤
sha256(as_string=False)

Compute a hash of the data for comparison during version control using the sha256 algorithm.

Parameters:

  • as_string (bool, default: False ) –

    If True, return the digest in hexadecimal format rather than as bytes.

Returns:

Examples:

>>> from compas.datastructures import Mesh
>>> mesh = Mesh.from_obj(compas.get("faces.obj"))
>>> v1 = mesh.sha256()
>>> v2 = mesh.sha256()
>>> mesh.vertex_attribute(mesh.vertex_sample(1)[0], "z", 1)
>>> v3 = mesh.sha256()
>>> v1 == v2
True
>>> v2 == v3
False
to_json ¤
to_json(filepath, pretty=False, compact=False, minimal=False)

Convert an object to its native data representation and save it to a JSON file.

Parameters:

  • filepath (str) –

    The path to the JSON file.

  • pretty (bool, default: False ) –

    If True, format the output with newlines and indentation.

  • compact (bool, default: False ) –

    If True, format the output without any whitespace.

  • minimal (bool, default: False ) –

    If True, exclude the GUID from the JSON output.

to_jsonstring ¤
to_jsonstring(pretty=False, compact=False, minimal=False)

Convert an object to its native data representation and save it to a JSON string.

Parameters:

  • pretty (bool, default: False ) –

    If True, format the output with newlines and indentation.

  • compact (bool, default: False ) –

    If True, format the output without any whitespace.

  • minimal (bool, default: False ) –

    If True, exclude the GUID from the JSON output.

Returns:

  • str –

    The JSON string.

traverse ¤
traverse(strategy='depthfirst', order='preorder')

Traverse the tree from this node.

Parameters:

  • strategy ((depthfirst, breadthfirst), default: "depthfirst" ) –

    The traversal strategy.

  • order ((preorder, postorder), default: "preorder" ) –

    The traversal order. This parameter is only used for depth-first traversal.

Yields:

  • class:`compas.datastructures.TreeNode` –

    The next node in the traversal.

Raises:

  • ValueError –

    If the strategy is not "depthfirst" or "breadthfirst". If the order is not "preorder" or "postorder".

update ¤
update(robot_cell_state: RobotCellState)

Update the robot cell object with the given robot cell state.

validate_data classmethod ¤
validate_data(data)

Validate the data against the object's data schema.

The data is the raw data that can be used to construct an object of this type with the classmethod __from_data__.

Parameters:

  • data (Any) –

    The data for validation.

Returns:

  • Any –

BaseRobotModelObject ¤

BaseRobotModelObject(
    draw_visual: bool = True,
    draw_collision: bool = False,
    native_scale: float = 1.0,
    *args,
    **kwargs,
)

Base class for compas_fab-special RobotModelObjects

This class is a SceneObject that represents a robot model. It is used to draw the robot model in the respective CAD environment.

Parameters:

  • draw_visual (bool, default: True ) –

    Draw the visual meshes of the robot model. Default is True.

  • draw_collision (bool, default: False ) –

    Draw the collision meshes of the robot model. Default is False. It is possible to turn on both draw_visual and draw_collision, however both set of meshes will be returned as a combined list in the draw() method. Consider creating two separate RobotModelObjects if you want to draw the visual and collision meshes separately

  • native_scale (float, default: 1.0 ) –

    The native scale factor to visualize the robot model, in case the native CAD environment uses a different unit system other than meters. The native scale value should be set such that a meter_mesh.scale(1/native_scale) will create the mesh in the native unit system. For example, if the unit system of the visualization environment is millimeters, native_scale should be set to '0.001'. Default is 1.0.

Notes 
The initial parameters `draw_visual`, `draw_collision`, and `scale` cannot be changed after initialization.

Attributes¤

robot_model property ¤
robot_model: RobotModel

The robot model this object is associated with.

Methods:¤

ToString ¤
ToString()

Converts the instance to a string.

This method exists for .NET compatibility. When using IronPython, the implicit string conversion that usually takes place in CPython will not kick-in, and in its place, IronPython will default to printing self.GetType().FullName or similar. Overriding the ToString method of .NET object class fixes that and makes Rhino/Grasshopper display proper string representations when the objects are printed or connected to a panel or other type of string output.

__jsondump__ ¤
__jsondump__(minimal=False)

Return the required information for serialization with the COMPAS JSON serializer.

Parameters:

  • minimal (bool, default: False ) –

    If True, exclude the GUID from the dump dict.

Returns:

__jsonload__ classmethod ¤
__jsonload__(data, guid=None, name=None)

Construct an object of this type from the provided data to support COMPAS JSON serialization.

Parameters:

  • data (dict) –

    The raw Python data representing the object.

  • guid (str, default: None ) –

    The GUID of the object.

  • name (str, default: None ) –

    The name of the object.

Returns:

add ¤
add(item, **kwargs)

Add a child item to the scene object.

Parameters:

  • item (:class:`compas.data.Data`) –

    The item to add.

  • **kwargs (dict, default: {} ) –

    Additional keyword arguments to create the scene object for the item.

Returns:

  • class:`compas.scene.SceneObject` –

    The scene object associated with the added item.

Raises:

  • ValueError –

    If the scene object does not have an associated scene node.

clear ¤
clear()

The main clearing method.

copy ¤
copy(cls=None, copy_guid=False)

Make an independent copy of the data object.

Parameters:

  • cls (Type[:class:`compas.data.Data`], default: None ) –

    The type of data object to return. Defaults to the type of the current data object.

  • copy_guid (bool, default: False ) –

    If True, the copy will have the same guid as the original.

Returns:

  • class:`compas.data.Data` –

    An independent copy of this object.

draw ¤
draw(
    robot_configuration: Configuration | None = None, base_frame: Frame | None = None
) -> list[object]

Draw the robot model object in the respective CAD environment.

This function conforms to SceneObject.draw() Interface and will return the native geometry objects that were created.

  • In the Rhino context where the geometry had been placed in the Rhino document, the native geometry handles are still returned.
  • In the GHPython context, the native geometry is returned as a list of Rhino.Geometry.Mesh objects, which can be used as a GHComponent output.
from_json classmethod ¤
from_json(filepath)

Construct an object of this type from a JSON file.

Parameters:

  • filepath (str) –

    The path to the JSON file.

Returns:

  • class:`compas.data.Data` –

    An instance of this object type if the data contained in the file has the correct schema.

Raises:

  • TypeError –

    If the data in the file is not a :class:compas.data.Data.

from_jsonstring classmethod ¤
from_jsonstring(string)

Construct an object of this type from a JSON string.

Parameters:

  • string (str) –

    The JSON string.

Returns:

  • class:`compas.data.Data` –

    An instance of this object type if the data contained in the string has the correct schema.

Raises:

  • TypeError –

    If the data in the string is not a :class:compas.data.Data.

remove ¤
remove(node)

Remove a child node from this node.

Parameters:

  • node (:class:`compas.datastructures.TreeNode`) –

    The node to remove.

Returns:

  • None –
sha256 ¤
sha256(as_string=False)

Compute a hash of the data for comparison during version control using the sha256 algorithm.

Parameters:

  • as_string (bool, default: False ) –

    If True, return the digest in hexadecimal format rather than as bytes.

Returns:

Examples:

>>> from compas.datastructures import Mesh
>>> mesh = Mesh.from_obj(compas.get("faces.obj"))
>>> v1 = mesh.sha256()
>>> v2 = mesh.sha256()
>>> mesh.vertex_attribute(mesh.vertex_sample(1)[0], "z", 1)
>>> v3 = mesh.sha256()
>>> v1 == v2
True
>>> v2 == v3
False
to_json ¤
to_json(filepath, pretty=False, compact=False, minimal=False)

Convert an object to its native data representation and save it to a JSON file.

Parameters:

  • filepath (str) –

    The path to the JSON file.

  • pretty (bool, default: False ) –

    If True, format the output with newlines and indentation.

  • compact (bool, default: False ) –

    If True, format the output without any whitespace.

  • minimal (bool, default: False ) –

    If True, exclude the GUID from the JSON output.

to_jsonstring ¤
to_jsonstring(pretty=False, compact=False, minimal=False)

Convert an object to its native data representation and save it to a JSON string.

Parameters:

  • pretty (bool, default: False ) –

    If True, format the output with newlines and indentation.

  • compact (bool, default: False ) –

    If True, format the output without any whitespace.

  • minimal (bool, default: False ) –

    If True, exclude the GUID from the JSON output.

Returns:

  • str –

    The JSON string.

traverse ¤
traverse(strategy='depthfirst', order='preorder')

Traverse the tree from this node.

Parameters:

  • strategy ((depthfirst, breadthfirst), default: "depthfirst" ) –

    The traversal strategy.

  • order ((preorder, postorder), default: "preorder" ) –

    The traversal order. This parameter is only used for depth-first traversal.

Yields:

  • class:`compas.datastructures.TreeNode` –

    The next node in the traversal.

Raises:

  • ValueError –

    If the strategy is not "depthfirst" or "breadthfirst". If the order is not "preorder" or "postorder".

update ¤
update(
    robot_configuration: Configuration | None = None, base_frame: Frame | None = None
)

Updates the native geometry of the robot model according to the given robot configuration and base frame.

Parameters:

  • robot_configuration (Configuration | None, default: None ) –

    The robot configuration to update the robot model. This is only optional for robot models that do not have any configurable joints.

  • base_frame (Frame | None, default: None ) –

    The frame of the RobotCoordinateFrame relative to the WorldCoordinateFrame. Default is World XY frame at origin.

Returns:

  • None –
Notes

It is possible to call this method before the draw method.

validate_data classmethod ¤
validate_data(data)

Validate the data against the object's data schema.

The data is the raw data that can be used to construct an object of this type with the classmethod __from_data__.

Parameters:

  • data (Any) –

    The data for validation.

Returns:

  • Any –