Classes for robot modeling, used by the simulation, planning and execution backends to exchange information.
The unit systems most commonly used in COMPAS FAB are meters and
radians; helpers like to_degrees and
to_radians convert between systems.
Classes¤
Action(
name: str,
start_state: RobotCellState | None = None,
trajectory: JointTrajectory | None = None,
post_state: RobotCellState | None = None,
description: str = "",
tags: list[str] | None = None,
attributes: dict[str, Any] | None = None,
)
A single action within an ActionChain.
An action is the atomic unit of a chain. It wraps a start_state (the cell
state the action begins from), an optional trajectory, an optional
post_state, and a free-form attributes bag (with tags as the default,
first-class attribute). It deliberately uses one class rather than a
planned/unplanned split:
- Has a trajectory → a planned action. The
post_stateis derived by applying the trajectory's last point tostart_state(the chain does this on append). - No trajectory → an unplanned action. For a discrete state change
(e.g. a tool attached/detached, a rigid body grasped/released) the
post_stateis supplied explicitly.
Using a single class means backtracking/undo just clears trajectory
instead of swapping class types. Branching is intentionally not
implemented yet, but nothing here forecloses it.
Construction is normally done through ActionChain.append_trajectory() and
ActionChain.append_state_change(), which take care of validation,
start-state threading and post-state derivation. Actions can also be built
standalone (e.g. by Grasshopper builder components) and threaded in later
with ActionChain.append_action(); in that case start_state stays None
until the action is appended to a chain.
Parameters:
-
name(str) –Unique identifier of the action within the chain.
-
start_state(RobotCellState | None, default:None) –Cell state the action begins from. Filled in by the chain on append when the action is built standalone.
-
trajectory(JointTrajectory | None, default:None) –The trajectory for a planned action.
Nonefor a state-change action. -
post_state(RobotCellState | None, default:None) –Cell state after the action has executed. For planned actions the chain derives this; for state-change actions it must be supplied.
-
description(str, default:'') –Free-form human description.
-
tags(list[str] | None, default:None) –Convenience accessor for
attributes["tags"], a list of strings driving differentiated downstream execution (e.g.approach,retract,linear,free). Stored inattributes. -
attributes(dict[str, Any] | None, default:None) –Free-form key-value metadata.
tagsis the default key; execution code is free to read any other key (e.g. an execution speed or blend mode).
Attributes:
-
is_trajectory(bool) –True when this action carries a trajectory (a planned action).
-
duration(float) –Trajectory duration in seconds, or
0.0for state-change actions. -
end_state(RobotCellState | None) –Alias of
post_state; the cell state once the action has executed.
ActionChain(
name: str,
start_state: RobotCellState,
robot_cell: RobotCell | None = None,
description: str = "",
)
A named, serializable sequence of trajectory and state-change actions.
A chain threads a single RobotCellState through a sequence of Action objects. The post-state of action N is the pre-state (start_state) of action N+1 — this end-state-equals-next-start-state invariant is exactly why it is a chain. Planned actions derive their post-state automatically (the trajectory's last point applied to the pre-state); state-change actions (e.g. gripper toggle, tool attach/detach) carry an explicit post-state.
The typical use case is pick-and-place: approach → contact → state-change (grasp) → retract → transfer → approach → contact → state-change (release) → retract. Each motion is planned separately and atomically; the chain is the higher-level assembly.
Iteration yields actions along the realized path. An action_by_name()
lookup is provided; index-based access is intentionally not exposed so that
future extensions (e.g. branching alternatives — deliberately deferred for
now) do not require an API break.
The name "chain" was chosen because it conveys the end-state-equals-next- start-state link between actions. Rejected alternatives: motion skeleton, template, motion plan, action sequence, action group.
Parameters:
-
name(str) –Chain identifier.
-
start_state(RobotCellState) –Cell state the chain starts from.
-
robot_cell(RobotCell | None, default:None) –When provided, a structural signature of the cell is stored so that loading the chain against a mismatched cell can fail loudly (see
verify_cell()). -
description(str, default:'') –Free-form human description of the chain.
Attributes:
-
end_state(RobotCellState) –Post-state of the last action, or
start_stateif the chain is empty. -
trajectories(list[JointTrajectory]) –The trajectories along the realized path, in order.
-
duration(float) –Sum of trajectory durations along the realized path, in seconds.
-
cell_signature(str | None) –Fingerprint of the bound cell, or
Noneif the chain was built without one.
Notes
On serialization the chain strips the embedded start_state from each
contained trajectory and from each action (both are derivable by re-threading
the chain) and omits the derived post_state of planned actions. Only
explicit state-change post-states are stored. On load the chain is re-threaded
so every action's start_state and every trajectory's mirrored start_state
are reconstructed identically.
Attributes¤
property
¤
Snapshot of the realized path. Returns a fresh list; mutating it does not affect the chain.
Methods:¤
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.
classmethod
¤
append_action(action: Action) -> ActionChain
Append a pre-built Action.
Dispatches to append_trajectory() or append_state_change() depending
on whether the action carries a trajectory. Convenient when actions are
constructed upstream (e.g. by Grasshopper builder components) and the
caller just needs to thread them in order. The action's attributes
(including tags) are preserved.
Raises:
-
ValueError–If
action.nameis already used, the trajectory references joints absent from the cell state, or a state-change action is missing itspost_state.
append_state_change(
name: str,
post_state: RobotCellState,
description: str = "",
tags: list[str] | None = None,
attributes: dict[str, Any] | None = None,
) -> ActionChain
Append a discrete state-change action (e.g. attach/detach tool, grasp/release).
The action's start_state is set to the current end_state; post_state
is the explicit state after the change.
Returns self to allow chaining.
Raises:
-
ValueError–If
nameis already used.
append_trajectory(
name: str,
trajectory: JointTrajectory,
description: str = "",
tags: list[str] | None = None,
attributes: dict[str, Any] | None = None,
) -> ActionChain
Append a planned (trajectory) action.
The action's start_state is set to the current end_state and mirrored
into trajectory.start_state. The post_state is derived from the
start-state with the trajectory's last point applied. The trajectory's
joint set must be a subset of the cell's configurable joints.
Returns self to allow chaining.
Raises:
-
ValueError–If
nameis already used, or the trajectory references joints absent from the cell state.
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.
classmethod
¤
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.
classmethod
¤
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.
iter_cell_states() -> Iterator[RobotCellState]
Yield a RobotCellState snapshot for every trajectory point and every state-change in the realized path.
Useful for frame-by-frame playback: pair with an index slider and a visualisation component to scrub through the entire chain (not just one trajectory). Each yielded state is a fresh copy; mutating it does not affect the chain.
Order: for a planned action, one snapshot per point in
action.trajectory.points, with the pre-action configuration merged
with the point's joint values (by name when joint_names are available,
otherwise the point is used directly). For a state-change action, one
snapshot — the explicit post_state.
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:
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.
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.
classmethod
¤
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–
verify_cell(robot_cell: RobotCell) -> None
Verify the chain was assembled against robot_cell.
Compares the cached cell signature against the given cell.
Raises:
-
ValueError–If the signatures differ. No-op when the chain was constructed without a bound cell.
A container for describing a bounding volume.
Parameters:
-
volume_type(int) –The type of bounding volume, one of
BoundingVolume.VOLUME_TYPES. -
volume(Box | Sphere | Mesh) –
Attributes:
-
volume_type–The type of bounding volume, one of
BoundingVolume.VOLUME_TYPES. -
volume–
Notes
BoundingVolume.BOX
Box bounding volume type.
BoundingVolume.SPHERE
Sphere bounding volume type.
BoundingVolume.MESH
Mesh bounding volume type.
BoundingVolume.VOLUME_TYPES
List of supported bounding volume types.
Methods:¤
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.
classmethod
¤
Construct an object of this type from the provided data.
Parameters:
-
data(dict) –The data dictionary.
Returns:
-
class:`compas.data.Data`–An instance of this object type if the data contained in the dict has the correct schema.
classmethod
¤
copy() -> BoundingVolume
Make a copy of this BoundingVolume.
Returns:
-
`BoundingVolume`–A copy.
classmethod
¤
from_box(box: Box) -> BoundingVolume
classmethod
¤
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.
classmethod
¤
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.
classmethod
¤
from_mesh(mesh: Mesh) -> BoundingVolume
classmethod
¤
from_sphere(sphere: Sphere) -> BoundingVolume
scale(scale_factor: float) -> None
Scale the volume uniformly.
Parameters:
-
scale_factor(float) –Scale factor to use in scaling operation.
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:
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.
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.
transform(transformation: Transformation) -> None
Transform the volume using a Transformation.
Parameters:
-
transformation(Transformation) –The transformation to apply on the
BoundingVolume.
classmethod
¤
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–
ConfigurationTarget(
target_configuration: Configuration,
tolerance_above: list[float] | None = None,
tolerance_below: list[float] | None = None,
name: str = "Configuration Target",
)
Represents a configuration target for the robot's end-effector motion planning.
The configuration target is a joint configuration of the robot's joints.
Given a ConfigurationTarget, the planner aims to find a path moving
the robot's joint positions to match with ConfigurationTarget.target_configuration.
ConfigurationTarget is suitable for targets whose joint configuration is known, such as a home position, or a repetitive position that has been calibrated in the actual robot cell, such as a tool changing position.
The number of joints in the target configuration should match the number of joints
in the robot's planning group. Otherwise the behavior of the backend planner may
be undefined. See tutorial targets for more details.
Attributes:
-
target_configuration–The target configuration. joint_names and joint_values must be specified. Defaults unit is radians for revolute and continuous joints, and meters for prismatic joints.
-
tolerance_above–Acceptable deviation above the targeted configurations. One for each joint. Always use positive values. Units must be in meters for prismatic joints and radians for revolute and continuous joints. If not specified, the default value from the planner is used.
-
tolerance_below–Acceptable deviation below the targeted configurations. One for each joint. Always use positive values. Units must be in meters for prismatic joints and radians for revolute and continuous joints. If not specified, the default value from the planner is used.
-
name–The human-readable name of the target. Defaults to 'Configuration Target'.
Methods:¤
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.
Check if two ConfigurationTarget objects are equal.
This function relies on the is_close function from the compas.tolerance module.
Hence, the numerical values of the geometry are compared with the globally defined tolerance.
Except where the target_configurations are compared with Configuration.is_close method.
classmethod
¤
Construct an object of this type from the provided data.
Parameters:
-
data(dict) –The data dictionary.
Returns:
-
class:`compas.data.Data`–An instance of this object type if the data contained in the dict has the correct schema.
classmethod
¤
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.
classmethod
¤
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.
classmethod
¤
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.
classmethod
¤
generate_default_tolerances(
configuration: Configuration, tolerance_prismatic: float, tolerance_revolute: float
) -> tuple[list[float], list[float]]
Generates tolerances values for the target configuration based on the joint types.
The parameters tolerance_prismatic and tolerance_revolute are used to generate the
list of values for tolerances_above, tolerances_below. The length of the list is equal to the
number of joints in the target configuration.
This function will not override the existing tolerance_above and tolerance_below values,
users should set the values explicitly.
Parameters:
-
tolerance_prismatic(float) –The default tolerance applied to prismatic joints. Defaults unit is meters.
-
tolerance_revolute(float) –The default tolerance applied to revolute and continuous joints. Defaults unit is radians.
Returns:
-
`tuple` of (`list` of `float`, `list` of `float`)–The tolerances_above and tolerances_below lists.
Examples:
>>> from compas_robots import Configuration
>>> from compas_fab.robots import ConfigurationTarget
>>> from compas_robots.model import Joint
>>> configuration = Configuration.from_revolute_values([0, 3.14, 0, 0, 3.14, 0])
>>> tolerance_prismatic = 0.001
>>> tolerance_revolute = math.radians(1)
>>> tolerances_above, tolerances_below = ConfigurationTarget.generate_default_tolerances(configuration, tolerance_prismatic, tolerance_revolute)
>>> target = ConfigurationTarget(configuration, tolerances_above, tolerances_below)
ConfigurationTarget does not contain any geometry with configurable units to normalize.
normalized_to_meters() -> Target
Returns a copy of the target where the target and tolerances are scaled to meters.
Notes
copy.deepcopy is used, normalize_to_meters is then called on the copy.
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:
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.
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.
classmethod
¤
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–
Base class for robot constraints.
Parameters:
-
constraint_type(int) –Constraint type, one of
Constraint.CONSTRAINT_TYPES. -
weight(float | None, default:1.0) –A weighting factor for this constraint. Denotes relative importance to other constraints. Closer to zero means less important. Defaults to
1.
Attributes:
-
constraint_type–Constraint type, one of
Constraint.CONSTRAINT_TYPES. -
weight–A weighting factor for this constraint. Denotes relative importance to other constraints. Closer to zero means less important.
Notes
Constraint.JOINT Joint constraint type. Constraint.POSITION Positional constraint type. Constraint.ORIENTATION Orientational constraint type. Constraint.CONSTRAINT_TYPES List of possible constraint types.
Methods:¤
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.
classmethod
¤
Construct an object of this type from the provided data.
Parameters:
-
data(dict) –The data dictionary.
Returns:
-
class:`compas.data.Data`–An instance of this object type if the data contained in the dict has the correct schema.
classmethod
¤
classmethod
¤
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.
classmethod
¤
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.
scaled(scale_factor: float) -> Constraint
Get a scaled copy of this Constraint.
Parameters:
-
scale_factor(float) –Scale factor used to scale the
Constraint.
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:
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.
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.
classmethod
¤
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–
ConstraintSetTarget(
constraint_set: list[Constraint], name: str = "Constraint Set Target"
)
Represents a list of Constraint as the target for motion planning.
Given a ConstraintSetTarget, the planner aims to find a path moving the robot's end-effector to satisfy ALL the constraints in the constraint set. Constraints can be very specific, for example defining value domains for each joint, such that the goal configuration is included, or defining a volume in space, to which a specific robot link (e.g. the end-effector) is required to move to.
This target cannot be translated into a single pose or configuration target except in trivial cases. Therefore the ending pose or configuration of the planned path can only be determined after performing the motion planning.
ConstraintSetTarget is suitable for advanced users who want to specify
custom constraints for the robot motion planning.
Different planner backends may support different types of Constraints.
See tutorial targets for more details.
ConstraintSetTarget is only supported by Free motion planning, Cartesian motion planning do not support this target type.
Attributes:
-
constraint_set–A list of constraints to be satisfied.
-
name–The human-readable name of the target. Defaults to 'Constraint Set Target'.
Methods:¤
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.
classmethod
¤
Construct an object of this type from the provided data.
Parameters:
-
data(dict) –The data dictionary.
Returns:
-
class:`compas.data.Data`–An instance of this object type if the data contained in the dict has the correct schema.
classmethod
¤
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.
classmethod
¤
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.
classmethod
¤
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.
ConstraintSetTarget does not contain any geometry with configurable units to normalize.
normalized_to_meters() -> Target
Returns a copy of the target where the target and tolerances are scaled to meters.
Notes
copy.deepcopy is used, normalize_to_meters is then called on the copy.
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:
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.
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.
classmethod
¤
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–
Calculates equally distributed vectors that deviate from the specified one by a maximal angle of max_alpha.
Parameters:
-
axis([`Vector`][compas.geometry.Vector]) –The axis about which to calculate vectors.
-
max_alpha(float) –The maximum angle in radians that a vector should deviate from the axis.
-
step(int) –The number of how often to divide
max_angle.
Yields:
-
list of [`Vector`][compas.geometry.Vector]–
Examples:
>>> generator = DeviationVectorsGenerator((0, 0, -1), math.radians(120), 1)
>>> [print(zaxis) for zaxis in generator]
Vector(x=0.000, y=0.000, z=-1.000)
Vector(x=-0.866, y=0.000, z=0.500)
Vector(x=0.433, y=0.750, z=0.500)
Vector(x=0.433, y=-0.750, z=0.500)
[None, None, None, None]
Duration is used to accurately describe the passage of time. It consists of seconds and nanoseconds, the total duration is the sum of the two values.
Parameters:
-
secs(int | float) –Integer representing number of seconds. If a float is passed, the integer portion is assigned to secs and the decimal portion of the secs variable is converted and added to nsecs.
-
nsecs(int) –Integer representing number of nanoseconds.
Attributes:
-
seconds(float) –Returns the total duration as floating-point seconds.
-
secs–Float representing number of seconds.
-
nsecs–Integer representing number of nanoseconds.
Examples:
>>> d = Duration(2, 5e8)
>>> d.seconds
2.5
>>> d = Duration(2.6, 0)
>>> d.seconds
2.6
>>> d = Duration(2.6, 5e8)
>>> d.secs
3
>>> d.nsecs
100000000
>>> d.seconds
3.1
Attributes¤
Methods:¤
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.
classmethod
¤
Construct an object of this type from the provided data.
Parameters:
-
data(dict) –The data dictionary.
Returns:
-
class:`compas.data.Data`–An instance of this object type if the data contained in the dict has the correct schema.
classmethod
¤
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.
classmethod
¤
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.
classmethod
¤
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.
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:
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.
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.
classmethod
¤
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–
FrameInterpolator(
start_frame: Frame,
end_frame: Frame,
max_step_distance: float = 0.01,
max_step_angle: float = 0.1,
min_step_distance: float = 0.0001,
min_step_angle: float = 0.0001,
)
Interpolate between two frames with bounded Cartesian and angular steps.
All the properties are read-only and are computed during initialization.
Parameters:
-
start_frame(Frame) –The start frame.
-
end_frame(Frame) –The end frame.
-
max_step_distance(float, default:0.01) –The maximum Cartesian distance between two consecutive interpolated frames, in the frames' own unit. Default is
0.01. -
max_step_angle(float, default:0.1) –The maximum angular distance (radians) between two consecutive interpolated frames. Default is
0.1. -
min_step_distance(float, default:0.0001) –The minimum Cartesian distance below which a segment can no longer be subdivided (see
check_if_subdivision_possible). Default is0.0001. -
min_step_angle(float, default:0.0001) –The minimum angular distance (radians) below which a segment can no longer be subdivided. Default is
0.0001.
Attributes¤
property
¤
regular_interpolation_steps: int
The number of interpolation steps based on max_step_distance and max_step_angle.
Returns:
-
int–The number of interpolation steps. Minimum is 1.
property
¤
total_angle: float
The total angle between the start and end frames.
Returns:
-
float–The total angle in radians between the start and end frames.
property
¤
total_distance: float
The total distance between the start and end frames.
Returns:
-
float–The total distance (original unit) between the start and end frames.
Methods:¤
Check if the addition of an extra t value between t1 and t2 is possible.
Two conditions are being checked:
- The distance between the two frames is greater than the
min_step_distance. - The angle between the two frames is greater than the
min_step_angle.
The subdivision is possible if any one of the two conditions is met.
Parameters:
Returns:
-
tuple–A tuple containing the following values:
delta_distance: (:obj:float) The distance between the two frames.delta_angle: (:obj:float) The angle between the two frames.subdivision_possible: (:obj:bool) True if the subdivision is possible
FrameTarget(
target_frame: Frame,
target_mode: TargetMode,
native_scale: float = 1.0,
tolerance_position: float | None = None,
tolerance_orientation: float | None = None,
name: str = "Frame Target",
)
Represents a fully constrained pose target for the robot's end-effector using a Frame.
When using a FrameTarget, the end-effector has no translational or rotational freedom. In another words, the pose of the end-effector is fully defined (constrained).
Given a FrameTarget, the planner aims to find a path moving
the robot's Tool0 Coordinate Frame (T0CF) to the specified FrameTarget.target_frame.
For robots with multiple end effector attachment points (such as the RFL Robot), the attachment point depends on the planning group selected in the planning request.
Attributes:
-
target_frame–The target frame.
-
target_mode–The target mode specifies which link or frame is referenced when specifying a target. See
TargetModefor more details. -
native_scale–The native scale factor of the target frames defined as
user_object_value * native_scale = meter_object_value. In another words,input_frame.scale(native_scale)will convert the input frame to meter units. For example, if the target is modeled in a millimeters environment,native_scaleshould be set to'0.001'. Default is'1.0'. -
tolerance_position–The tolerance for the position of the target point. Unit must be in meters, it is not affected by
native_scale. If not specified, the default value from the planner is used. -
tolerance_orientation–The tolerance for matching the target axis orientation. Unit must be in radians. If not specified, the default value from the planner is used.
-
name–The human-readable name of the target. Defaults to 'Frame Target'.
Methods:¤
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.
__eq__(other) -> bool
Check if two FrameTarget objects are equal.
This function relies on the is_close function from the compas.tolerance module.
Hence, the numerical values of the geometry are compared with the globally defined tolerance.
classmethod
¤
__from_data__(data: dict) -> FrameTarget
Construct a FrameTarget from a data dictionary.
Parameters:
-
data(dict) –The data dictionary.
Returns:
-
[`FrameTarget`][compas_fab.robots.FrameTarget]–The frame target.
classmethod
¤
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.
classmethod
¤
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.
classmethod
¤
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.
classmethod
¤
from_transformation(
transformation: Transformation,
target_mode: TargetMode,
native_scale: float = 1.0,
tolerance_position: float | None = None,
tolerance_orientation: float | None = None,
name: str = "Frame Target",
)
Creates a FrameTarget from a transformation matrix.
Parameters:
-
transformation(Transformation) –The transformation matrix.
-
target_mode(TargetMode) –The target mode specifies which link or frame is referenced when specifying a target. See
TargetModefor more details. -
native_scale(float, default:1.0) –The native scale factor of the target frames defined as
user_object_value * native_scale = meter_object_value. In another words,input_frame.scale(native_scale)will convert the input frame to meter units. For example, if the target is modeled in a millimeters environment,native_scaleshould be set to'0.001'. Default is'1.0'. -
tolerance_position(float | None, default:None) –The tolerance for the position of the target point. Unit must be in meters, it is not affected by
native_scale. If not specified, the default value from the planner is used. -
tolerance_orientation(float | None, default:None) –The tolerance for matching the target axis orientation. Unit must be in radians. If not specified, the default value from the planner is used.
-
name(str, default:'Frame Target') –The human-readable name of the target. Defaults to 'Frame Target'.
Returns:
-
`FrameTarget`–The frame target.
Convert the target into meter scale if native_scale is not 1.0.
Because all robots and planners in compas_fab use meters as the default unit of measure,
user targets that are created in other units (e.g. millimeters) will have a native_scale
factor such as 0.001 for millimeters.
This function convert the target_frame into meters scale.
native_scale is set to 1.0 after the conversion.
normalized_to_meters() -> Target
Returns a copy of the target where the target and tolerances are scaled to meters.
Notes
copy.deepcopy is used, normalize_to_meters is then called on the copy.
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:
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.
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.
classmethod
¤
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–
FrameWaypoints(
target_frames: list[Frame],
target_mode: TargetMode,
native_scale: float = 1.0,
tolerance_position: float | None = None,
tolerance_orientation: float | None = None,
name: str = "Frame Waypoints",
)
Represents a sequence of fully constrained pose target for the robot's end-effector using a Frame.
When using a FrameWaypoints, the end-effector has no translational or rotational freedom. In another words, the pose of the end-effector is fully defined (constrained).
The behavior of FrameWaypoints is similar to FrameTarget, but it represents a sequence of targets.
Attributes:
-
target_frames–The target frames.
-
target_mode–The target mode specifies which link or frame is referenced when specifying a target. See
TargetModefor more details. -
native_scale–The native scale factor of the target frames defined as
user_object_value * native_scale = meter_object_value. In another words,input_frame.scale(native_scale)will convert the input frame to meter unit. For example, if the target is modeled in a millimeters environment,native_scaleshould be set to'0.001'. Default is'1.0'. -
tolerance_position–The tolerance for the position of the target point. Unit must be in meters, it is not affected by
native_scale. If not specified, the default value from the planner is used. -
tolerance_orientation–The tolerance for matching the target axis orientation. Unit must be in radians. If not specified, the default value from the planner is used.
-
name–The human-readable name of the target. Defaults to 'Frame Waypoints'.
Methods:¤
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.
Check if two FrameWaypoints objects are equal.
This function relies on the is_close function from the compas.tolerance module.
Hence, the numerical values of the geometry are compared with the globally defined tolerance.
classmethod
¤
Construct an object of this type from the provided data.
Parameters:
-
data(dict) –The data dictionary.
Returns:
-
class:`compas.data.Data`–An instance of this object type if the data contained in the dict has the correct schema.
classmethod
¤
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.
classmethod
¤
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.
classmethod
¤
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.
classmethod
¤
from_transformations(
transformations: list[Transformation],
target_mode: TargetMode,
native_scale: float = 1.0,
tolerance_position: float | None = None,
tolerance_orientation: float | None = None,
name: str = "Frame Waypoints",
)
Creates a FrameWaypoints from a list of transformation matrices.
Parameters:
-
transformations(list[Transformation]) –The list of transformation matrices.
-
target_mode(TargetMode) –The target mode specifies which link or frame is referenced when specifying a target. See
TargetModefor more details. -
native_scale(float, default:1.0) –The native scale factor of the target frames defined as
user_object_value * native_scale = meter_object_value. In another words,input_frame.scale(native_scale)will convert the input frame to meter unit. For example, if the target is modeled in a millimeters environment,native_scaleshould be set to'0.001'. Default is'1.0'. -
tolerance_position(float | None, default:None) –The tolerance for the position of the target point. Unit must be in meters, it is not affected by
native_scale. If not specified, the default value from the planner is used. -
tolerance_orientation(float | None, default:None) –The tolerance for matching the target axis orientation. Unit must be in radians. If not specified, the default value from the planner is used.
-
name(str, default:'Frame Waypoints') –The human-readable name of the target. Defaults to 'Frame Target'.
Returns:
-
`FrameWaypoints`–The frame waypoints.
Convert the target into meter scale if native_scale is not 1.0.
Because all robots and planners in compas_fab use meters as the default unit of measure,
user targets that are created in other units (e.g. millimeters) will have a native_scale
factor such as 0.001 for millimeters.
This function convert the target_frame into meters scale.
native_scale is set to 1.0 after the conversion.
normalized_to_meters() -> Target
Returns a copy of the target where the target and tolerances are scaled to meters.
Notes
copy.deepcopy is used, normalize_to_meters is then called on the copy.
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:
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.
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.
classmethod
¤
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–
The moments of inertia represent the spatial distribution of mass in a rigid body.
It depends on the mass, size, and shape of a rigid body with units of [mass * m**2]. The moments of inertia can be expressed as the components of a symmetric positive-definite 3x3 matrix, with 3 diagonal elements, and 3 unique off-diagonal elements. Each inertia matrix is defined relative to a coordinate frame or set of axes.
Attributes:
-
inertia_tensor–A symmetric positive-definite 3x3 matrix: | ixx ixy ixz | | ixy iyy iyz | | ixz iyz izz | with [ixx, iyy, izz] as the principal moments of inertia and [ixy, ixz, iyz] as the products of inertia.
-
mass–The mass of the object in kg.
-
center_of_mass–The center of mass of the object in meters.
Examples:
>>> inertia = Inertia([[0] * 3] * 3, 1.0, Point(0.1, 3.1, 4.4))
>>> inertia
Inertia([[0, 0, 0], [0, 0, 0], [0, 0, 0]], 1.0, Point(x=0.1, y=3.1, z=4.4))
>>> inertia.principal_moments
[0, 0, 0]
Notes
Assuming uniform mass density, inertial data can be obtained using the free software MeshLab, referring to this great tutorial.
JointConstraint(
joint_name: str,
value: float,
tolerance_above: float | None = 0.0,
tolerance_below: float | None = 0.0,
weight: float | None = 1.0,
)
Constrains the value of a joint to be within a certain bound.
Parameters:
-
joint_name(str) –The name of the joint this constraint refers to.
-
value(float) –The targeted value for that joint.
-
tolerance_above(float | None, default:0.0) –Tolerance above the targeted joint value, in radians. Defaults to
0. -
tolerance_below(float | None, default:0.0) –Tolerance below the targeted joint value, in radians. Defaults to
0. -
weight(float | None, default:1.0) –A weighting factor for this constraint. Denotes relative importance to other constraints. Closer to zero means less important. Defaults to
1.
Attributes:
-
joint_name–The name of the joint this constraint refers to.
-
value–The targeted value for that joint.
-
tolerance_above–Tolerance above the targeted joint value, in radians.
-
tolerance_below–Tolerance below the targeted joint value, in radians.
-
weight–A weighting factor for this constraint. Denotes relative importance to other constraints. Closer to zero means less important.
Methods:¤
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.
classmethod
¤
Construct an object of this type from the provided data.
Parameters:
-
data(dict) –The data dictionary.
Returns:
-
class:`compas.data.Data`–An instance of this object type if the data contained in the dict has the correct schema.
classmethod
¤
copy() -> JointConstraint
Create a copy of this JointConstraint.
Returns:
-
`JointConstraint`–
classmethod
¤
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.
classmethod
¤
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.
classmethod
¤
joint_constraints_from_configuration(
configuration: Configuration,
tolerances_above: list[float],
tolerances_below: list[float],
) -> list[JointConstraint]
Create joint constraints for all joints of the configuration. One constraint is created for each joint.
Parameters:
-
configuration(Configuration) –The target configuration.
-
tolerances_above(list[float]) –The tolerances above the targeted configuration's joint value on each of the joints, defining the upper bound in radians to be achieved. If only one value is passed in the list, it will be used to create upper bounds for all joint constraints.
-
tolerances_below(list[float]) –The tolerances below the targeted configuration's joint value on each of the joints, defining the upper bound in radians to be achieved. If only one value is passed, it will be used to create lower bounds for all joint constraints.
Returns:
-
`list` of `JointConstraint`–
Raises:
-
`ValueError`–If the passed configuration does not have joint names.
-
`ValueError`–If the passed list of tolerance values have a different length than the configuration.
Notes
Make sure that you are using the correct tolerance units if your robot has different joint types defined.
scale(scale_factor: float) -> None
Scale (multiply) the constraint with a factor.
Parameters:
-
scale_factor(float) –Factor used to multiply the joint value and tolerance bounds with.
scaled(scale_factor: float) -> Constraint
Get a scaled copy of this Constraint.
Parameters:
-
scale_factor(float) –Scale factor used to scale the
Constraint.
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:
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.
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.
classmethod
¤
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–
JointTrajectory(
trajectory_points: list[JointTrajectoryPoint] | None = None,
joint_names: list[str] | None = None,
start_state: RobotCellState | None = None,
fraction: float | None = None,
attributes: dict[str, Any] | None = None,
)
Describes a joint trajectory as a list of trajectory points.
Parameters:
-
trajectory_points(list[JointTrajectoryPoint] | None, default:None) –List of points composing the trajectory.
-
joint_names(list[str] | None, default:None) –List of joint names of the trajectory.
-
start_state(RobotCellState | None, default:None) –The full robot cell state the planner was given (tools, rigid bodies, attached collision objects, robot configuration). When present, callers no longer have to thread the cell state separately through visualisation / replay code.
-
fraction(float | None, default:None) –Percentage of the requested trajectory that was calculated, e.g.
1means the full trajectory was found. -
attributes(dict[str, Any] | None, default:None) –Custom attributes of the trajectory.
Attributes:
-
points–List of points composing the trajectory.
-
start_configuration(Configuration | None) –Start configuration for the trajectory. Not a constructor parameter: assign via the property after construction to override. The getter returns the explicit override when set, otherwise
start_state.robot_configuration, otherwiseNone. -
data–The serialised trajectory.
Attributes¤
property
¤
time_from_start: float
Time from start of the last point — effectively the trajectory's total duration in seconds. Zero when empty.
Methods:¤
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.
classmethod
¤
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.
classmethod
¤
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.
classmethod
¤
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.
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:
to_frames_and_polyline(
robot_cell: RobotCell,
start_state: RobotCellState | None,
group=None,
target_mode: TargetMode = ROBOT,
)
Compute frames and a connecting polyline from a trajectory.
For each trajectory point, the helper substitutes the point's joint
values into a single working copy of start_state and runs local
forward kinematics via RobotCell.forward_kinematics_target_frame,
i.e. the URDF kinematic chain in-process, with no backend round trip.
A polyline through their origins is computed as well.
start_state may be None; in that case the trajectory's own
start_state (populated by the planner that produced it) is used.
target_mode selects which frame each point is reported at (the robot's
planner coordinate frame, the attached tool's TCF, or the workpiece);
defaults to TargetMode.ROBOT. Pass the mode of the planned target /
waypoints so the visualized path matches what was planned.
Returns (frames, polyline). polyline is None when there are
fewer than two points. Any failure along the way returns ([], None)
rather than raising.
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.
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.
classmethod
¤
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–
JointTrajectoryPoint(
joint_values: list[float] | None = None,
joint_types: list[int] | None = None,
velocities: list[float] | None = None,
accelerations: list[float] | None = None,
effort: list[float] | None = None,
time_from_start: Duration | None = None,
joint_names: list[str] | None = None,
)
Defines a point within a trajectory.
A trajectory point is a sub-class of Configuration extended with acceleration, effort and time-from-start information.
Trajectory points are defined either as joint_values + velocities and accelerations, or as joint_values + efforts.
Parameters:
-
joint_values(list[float] | None, default:None) –Joint values expressed in radians or meters, depending on the joint type.
-
joint_types(list[int] | None, default:None) –Joint types, e.g. a list of
Joint.REVOLUTEfor revolute joints. -
velocities(list[float] | None, default:None) –Velocity of each joint.
-
accelerations(list[float] | None, default:None) –Acceleration of each joint.
-
effort(list[float] | None, default:None) –Effort of each joint.
-
time_from_start(Duration | None, default:None) –Duration of the trajectory point counted from the start.
-
joint_names(list[str] | None, default:None) –Names of the joints, in the same order as
joint_values.
Attributes:
Attributes¤
property
¤
The serialised trajectory point.
Assigning a dict to this property replaces the current data; the getter and setter must always be used together.
property
¤
A dictionary of joint accelerations by joint name.
property
¤
has_joint_names: bool
Returns True when there is a joint name for every value.
property
writable
¤
Joint joint_types, e.g. a list of JointType.REVOLUTE for revolute joints.
property
writable
¤
Joint values expressed in radians or meters, depending on the respective type.
property
¤
Prismatic joint values in meters.
E.g. positions on the external axis system.
property
¤
A dictionary of joint velocities by joint name.
Methods:¤
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.
classmethod
¤
Raises an error if there is not a joint name for every value.
close_to(other: Configuration, tol: float = 0.001) -> bool
Returns True if the other Configuration's joint_values are within a certain range.
Parameters:
-
other(Configuration) –The configuration to compare to.
-
tol(float, default:0.001) –The tolerance under which we consider 2 floats the same. Defaults to 1e-3.
Returns:
-
bool–Trueif the otherConfiguration's joint_values are within a certain tolerance,Falseotherwise.
Examples:
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.
classmethod
¤
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.
classmethod
¤
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.
classmethod
¤
from_prismatic_and_revolute_values(
prismatic_values: list[float],
revolute_values: list[float],
joint_names: list[str] | None = None,
) -> Configuration
Construct a configuration from prismatic and revolute joint values.
Parameters:
-
prismatic_values(list[float]) –Positions on the external axis system in meters.
-
revolute_values(list[float]) –Joint values expressed in radians.
-
joint_names(list[str] | None, default:None) –List of joint names.
Returns:
-
Configuration–A newly created instance of configuration.
classmethod
¤
from_revolute_values(
values: list[float], joint_names: list[str] | None = None
) -> Configuration
Construct a configuration from revolute joint values in radians.
Parameters:
-
values(list[float]) –Joint values expressed in radians.
-
joint_names(list[str] | None, default:None) –List of joint names.
Returns:
-
Configuration–A newly created instance of configuration.
iter_differences(other: Configuration) -> Iterator[float]
Generator over the differences to another Configuration's joint_values.
If the joint type is revolute or continuous, the smaller difference
(+/- 2*\pi) is calculated.
Parameters:
-
other(Configuration) –The configuration to compare to.
Yields:
-
The next difference to the `Configuration`'s joint_values.–
Raises:
-
ValueError–If the configurations are not comparable.
Examples:
>>> from compas.geometry import allclose
>>> c1 = Configuration.from_revolute_values([1, 0, 3])
>>> c2 = Configuration.from_revolute_values([1, 2 * pi, 4])
>>> allclose(c1.iter_differences(c2), [0.0, 0.0, -1.0])
True
>>> c1 = Configuration.from_revolute_values([1, 0, 3])
>>> c2 = Configuration.from_revolute_values([1, -2 * pi - 0.2, 4])
>>> allclose(c1.iter_differences(c2), [0.0, 0.2, -1.0])
True
max_difference(other: Configuration) -> float
Returns the maximum difference to another Configuration's joint values.
Parameters:
-
other(Configuration) –The configuration to compare to.
Returns:
-
The maximum absolute difference.–
Examples:
merge(other: Configuration) -> None
Merge the configuration with another configuration in place along joint names. The other configuration takes precedence over this configuration in case a joint value is present in both.
Notes
Caution: joint_names may be rearranged.
Parameters:
-
other(Configuration) –The configuration to be merged.
Raises:
-
ValueError–If the configuration or the
otherconfiguration does not specify joint names for all joint values.
merged(other) -> JointTrajectoryPoint
Return a new point with self merged with other.
other takes precedence over self for any joint present in both.
Joint names in the returned point may be reordered.
Parameters:
-
other–The point to be merged.
Raises:
-
ValueError–If either point does not specify joint names for all joint values.
scale(scale_factor: float) -> None
Scales the joint positions of the current configuration.
Only scalable joints are scaled, i.e. planar and prismatic joints.
Parameters:
-
scale_factor(float) –Scale factor.
scaled(scale_factor: float) -> Configuration
Return a scaled copy of this configuration.
Only scalable joints are scaled, i.e. planar and prismatic joints.
Parameters:
-
scale_factor(float) –Scale factor
Returns:
-
A scaled copy of this configuration.–
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:
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.
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.
classmethod
¤
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–
OrientationConstraint(
link_name: str,
quaternion: list[float],
tolerances: list[float] = None,
weight: list[float] = 1.0,
)
Constrains a link to be within a certain orientation.
Parameters:
-
link_name(str) –The name of the link this constraint refers to.
-
quaternion(list[float]) –The desired orientation of the link specified by a quaternion in the order of
[w, x, y, z]. -
tolerances(list[float], default:None) –Error tolerances :math:
t_{i}for each of the frame's axes. If only one value is passed it will be used for all 3 axes. The respective bound to be achieved is :math:(a_{i} - t_{i}, a_{i} + t_{i}). Defaults to[0.01, 0.01, 0.01]. -
weight(list[float], default:1.0) –A weighting factor for this constraint. Denotes relative importance to other constraints. Closer to zero means less important. Defaults to
1.
Attributes:
-
link_name–The name of the link this constraint refers to.
-
quaternion–The desired orientation of the link specified by a quaternion in the order of
[w, x, y, z]. -
tolerances–Error tolerances :math:
t_{i}for each of the frame's axes. If only one value is passed it will be used for all 3 axes. The respective bound to be achieved is :math:(a_{i} - t_{i}, a_{i} + t_{i}). Defaults to[0.01, 0.01, 0.01]. -
weight–A weighting factor for this constraint. Denotes relative importance to other constraints. Closer to zero means less important. Defaults to
1.0.
Notes
The rotation tolerance for an axis is defined by the other vector component values for rotation around corresponding axis.
If you specify the tolerance vector with [0.01, 0.01, 6.3], it means
that the frame's x-axis and y-axis are allowed to rotate about the z-axis
by an angle of 6.3 radians, whereas the z-axis can only change 0.01.
Methods:¤
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.
classmethod
¤
Construct an object of this type from the provided data.
Parameters:
-
data(dict) –The data dictionary.
Returns:
-
class:`compas.data.Data`–An instance of this object type if the data contained in the dict has the correct schema.
classmethod
¤
copy() -> OrientationConstraint
Create a copy of this OrientationConstraint.
Returns:
-
`OrientationConstraint`–
classmethod
¤
from_frame(
pcf_frame: Frame,
tolerances_orientation: list[float],
link_name: str,
weight: float | None = 1.0,
) -> OrientationConstraint
Create an OrientationConstraint from a frame on the group's end-effector link.
Only the orientation of the frame is considered for the constraint, expressed
as a quaternion.
Parameters:
-
pcf_frame(Frame) –The Planner Coordinate Frame relative to the WCF.
-
tolerances_orientation(list[float]) –Error tolerances :math:
t_{i}for each of the frame's axes in radians. If only one value is passed in the list it will be uses for all 3 axes. -
link_name(str) –The name of the end-effector link. Necessary for creating the position constraint.
-
weight(float | None, default:1.0) –A weighting factor for this constraint. Denotes relative importance to other constraints. Closer to zero means less important. Defaults to
1.
Returns:
-
`OrientationConstraint`–
Raises:
-
`ValueError`–If tolerance axes given are not one or three values.
Notes
The rotation tolerance for an axis is defined by the other vector
component values for rotation around corresponding axis.
If you specify the tolerances_orientation vector with [0.01, 0.01, 6.3], it
means that the frame's x-axis and y-axis are allowed to rotate about the
z-axis by an angle of 6.3 radians, whereas the z-axis would only rotate
by 0.01.
classmethod
¤
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.
classmethod
¤
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.
scaled(scale_factor: float) -> Constraint
Get a scaled copy of this Constraint.
Parameters:
-
scale_factor(float) –Scale factor used to scale the
Constraint.
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:
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.
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.
transform(transformation: Transformation) -> None
classmethod
¤
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–
Generate vectors that are orthonormal to an axis.
Parameters:
-
axis([`Vector`][compas.geometry.Vector]) –The axis to which the vectors should be orthonormal to.
-
angle_step(float) –The angle in radians as the spacing between generated vectors.
Yields:
-
[`Vector`][compas.geometry.Vector]–The orthonormal vector.
Examples:
>>> generator = OrthonormalVectorsFromAxisGenerator((0, 0, 1), math.radians(120))
>>> [print(xaxis) for xaxis in generator]
Vector(x=0.000, y=-1.000, z=0.000)
Vector(x=0.866, y=0.500, z=0.000)
Vector(x=-0.866, y=0.500, z=0.000)
[None, None, None]
PointAxisInterpolator(
start_point_axis: tuple[Point, Vector],
end_point_axis: tuple[Point, Vector],
max_step_distance: float = 0.01,
max_step_angle: float = 0.1,
)
Interpolate between two point-axis pairs with bounded position/angle steps.
All the properties are read-only and are computed during initialization.
Parameters:
-
start_point_axis(tuple[Point, Vector]) –The start point-axis pair.
-
end_point_axis(tuple[Point, Vector]) –The end point-axis pair.
-
max_step_distance(float, default:0.01) –The maximum Cartesian distance between two consecutive interpolated points, in the points' own unit. Default is
0.01. -
max_step_angle(float, default:0.1) –The maximum angular distance (radians) between two consecutive interpolated axes. Default is
0.1.
Attributes¤
property
¤
regular_interpolation_steps: int
The number of interpolation steps based on max_step_distance and max_step_angle.
Returns:
-
int–The number of interpolation steps. Minimum is 1.
property
¤
total_angle: float
The total angle between the start and end axes.
Returns:
-
float–The total angle in radians between the start and end axes.
property
¤
total_distance: float
The total distance between the start and end points.
Returns:
-
float–The total distance (original unit) between the start and end points.
Methods:¤
PointAxisTarget(
target_point: Point,
target_z_axis: Vector,
target_mode: TargetMode,
native_scale: float = 1.0,
tolerance_position: float | None = None,
tolerance_orientation: float | None = None,
name: str = "Point-Axis Target",
)
Represents a point and axis target for the robot's end-effector motion planning.
This target allows one degree of rotational freedom, enabling the end-effector to rotate around the target axis. Given a PointAxisTarget, the planner seeks a path to move the robot's end-effector tool tip to the target point and align the tool tip's Z axis with the specified target axis.
PointAxisTarget is suitable for tasks like drilling, milling, and 3D printing,
where aligning the end-effector with a target axis is crucial,
but the orientation around the axis is not important.
Note that PointAxisTarget only represents a single target,
for a sequence of targets, consider using PointAxisWaypoints.
The user must define (1) the target point of which the tool tip will reach and (2) the target axis where the tool tip coordinate frame (TCF)'s Z axis can rotate around. The target point and axis are defined relative to the robot's world coordinate frame (WCF).
For robots with multiple end effector attachment points, the FCF depends on
the planning group setting in the planning request, as defined in an SRDF file or
RobotSemantics.
Attributes:
-
target_point–The target point defined relative to the world coordinate frame (WCF).
-
target_z_axis–The target axis is defined by the target_point and pointing towards this vector. A unitized vector is recommended. The tool tip coordinate frame (TCF)'s Z axis can rotate around this axis.
-
target_mode–The target mode specifies which link or frame is referenced when specifying a target. See
TargetModefor more details. -
native_scale–The native scale factor of the target frames defined as
user_object_value * native_scale = meter_object_value. In another words,input_point.scale(native_scale)will convert the input point to meter unit. For example, if the target is modeled in a millimeters environment,native_scaleshould be set to'0.001'. Default is'1.0'. -
tolerance_position–The tolerance for the position of the target point. Unit must be in meters, it is not affected by
native_scale. If not specified, the default value from the planner is used. -
tolerance_orientation–The tolerance for matching the target axis orientation. Unit must be in radians. If not specified, the default value from the planner is used.
-
name–The human-readable name of the target. Defaults to 'Point-Axis Target'.
Methods:¤
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.
Check if two PointAxisTarget objects are equal.
This function relies on the is_close function from the compas.tolerance module.
Hence, the numerical values of the geometry are compared with the globally defined tolerance.
classmethod
¤
__from_data__(data: dict) -> PointAxisTarget
Construct a PointAxisTarget from a data dictionary.
Parameters:
-
data(dict) –The data dictionary.
Returns:
-
[`PointAxisTarget`][compas_fab.robots.PointAxisTarget]–The point axis target.
classmethod
¤
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.
classmethod
¤
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.
classmethod
¤
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.
Convert the target into meter scale if native_scale is not 1.0.
Because all robots and planners in compas_fab use meters as the default unit of measure,
user targets that are created in other units (e.g. millimeters) will have a native_scale
factor such as 0.001 for millimeters.
This function convert the target_point into meters scale,
and the target_z_axis is unitized.
native_scale is set to 1.0 after the conversion.
normalized_to_meters() -> Target
Returns a copy of the target where the target and tolerances are scaled to meters.
Notes
copy.deepcopy is used, normalize_to_meters is then called on the copy.
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:
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.
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.
classmethod
¤
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–
PointAxisWaypoints(
target_points_and_axes: list[tuple[Point, Vector]],
target_mode: TargetMode,
native_scale: float = 1.0,
tolerance_position: float | None = None,
tolerance_orientation: float | None = None,
name: str = "Point-Axis Waypoints",
)
Represents a sequence of point and axis targets for the robot's end-effector motion planning.
PointAxisTarget is suitable for tasks like drawing, milling, and 3D printing, where aligning the end-effector with a target axis is crucial, but the orientation around the axis is not important.
The behavior of PointAxisWaypoints is similar to PointAxisTarget, but it represents a sequence of targets.
See PointAxisTarget for more details.
Attributes:
-
target_points_and_axes–The target points and axes. Both values are defined relative to the world coordinate frame (WCF). Unitized vectors are recommended for the target axes.
-
target_mode–The target mode specifies which link or frame is referenced when specifying a target. See
TargetModefor more details. -
native_scale–The native scale factor of the target points defined as
user_object_value * native_scale = meter_object_value. In another words,input_point.scale(native_scale)will convert the input point to meter unit. For example, if the target is modeled in a millimeters environment,native_scaleshould be set to'0.001'. Default is'1.0'. -
tolerance_position–The tolerance for the position of the target point. Unit must be in meters, it is not affected by
native_scale. If not specified, the default value from the planner is used. -
tolerance_orientation–The tolerance for matching the target axis orientation. Unit must be in radians. If not specified, the default value from the planner is used.
-
name–The human-readable name of the target. Defaults to 'Point-Axis Waypoints'.
Methods:¤
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.
Check if two PointAxisWaypoints objects are equal.
This function relies on the is_close function from the compas.tolerance module.
Hence, the numerical values of the geometry are compared with the globally defined tolerance.
classmethod
¤
Construct an object of this type from the provided data.
Parameters:
-
data(dict) –The data dictionary.
Returns:
-
class:`compas.data.Data`–An instance of this object type if the data contained in the dict has the correct schema.
classmethod
¤
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.
classmethod
¤
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.
classmethod
¤
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.
Convert the target into meter scale if native_scale is not 1.0.
Because all robots and planners in compas_fab use meters as the default unit of measure,
user targets that are created in other units (e.g. millimeters) will have a native_scale
factor such as 0.001 for millimeters.
This function convert the points in target_points_and_axes into meters scale,
vectors are unitized.
native_scale is set to 1.0 after the conversion.
normalized_to_meters() -> Target
Returns a copy of the target where the target and tolerances are scaled to meters.
Notes
copy.deepcopy is used, normalize_to_meters is then called on the copy.
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:
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.
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.
classmethod
¤
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–
PositionConstraint(
link_name: str, bounding_volume: BoundingVolume, weight: float | None = 1.0
)
Constrains a link to be within a certain bounding volume.
Parameters:
-
link_name(str) –The name of the link this constraint refers to.
-
bounding_volume(BoundingVolume) –The volume this constraint refers to.
-
weight(float | None, default:1.0) –A weighting factor for this constraint. Denotes relative importance to other constraints. Closer to zero means less important. Defaults to
1.
Attributes:
-
link_name–The name of the link this constraint refers to.
-
bounding_volume–The volume this constraint refers to.
-
weight–A weighting factor for this constraint. Denotes relative importance to other constraints. Closer to zero means less important.
Examples:
>>> from compas.geometry import Sphere
>>> from compas_fab.robots import PositionConstraint
>>> from compas_fab.robots import BoundingVolume
>>> bv = BoundingVolume.from_sphere(Sphere(0.5, point=[3, 4, 5]))
>>> pc = PositionConstraint("link_0", bv, weight=1.0)
Methods:¤
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.
classmethod
¤
Construct an object of this type from the provided data.
Parameters:
-
data(dict) –The data dictionary.
Returns:
-
class:`compas.data.Data`–An instance of this object type if the data contained in the dict has the correct schema.
classmethod
¤
copy() -> PositionConstraint
Create a copy of this PositionConstraint.
Returns:
-
`PositionConstraint`–
classmethod
¤
from_box(link_name: str, box: Box, weight: float | None = 1.0) -> PositionConstraint
Create a PositionConstraint from a Box.
Parameters:
-
link_name(str) –The name of the link this constraint refers to.
-
box(Box) –Box defining the bounding volume this constraint refers to.
-
weight(float | None, default:1.0) –A weighting factor for this constraint. Denotes relative importance to other constraints. Closer to zero means less important. Defaults to
1.
Returns:
-
`PositionConstraint`–
Examples:
classmethod
¤
from_frame(
pcf_frame: Frame,
tolerance_position: float,
link_name: str,
weight: float | None = 1.0,
) -> PositionConstraint
Create a PositionConstraint from a frame on the group's end-effector link.
Only the position of the frame is considered for the constraint.
Parameters:
-
pcf_frame(Frame) –The Planner Coordinate Frame relative to the WCF.
-
tolerance_position(float) –The allowed tolerance to the frame's position (defined in the robot's units).
-
link_name(str) –The name of the end-effector link. Necessary for creating the position constraint.
-
weight(float | None, default:1.0) –A weighting factor for this constraint. Denotes relative importance to other constraints. Closer to zero means less important. Defaults to
1.
Returns:
-
`PositionConstraint`–
See Also
PositionConstraint.from_box
PositionConstraint.from_mesh
PositionConstraint.from_sphere
classmethod
¤
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.
classmethod
¤
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.
classmethod
¤
from_mesh(link_name: str, mesh: Mesh, weight: float | None = 1.0) -> PositionConstraint
Create a PositionConstraint from a Mesh.
Parameters:
-
link_name(str) –The name of the link this constraint refers to.
-
mesh(Mesh) –Mesh defining the bounding volume this constraint refers to.
-
weight(float | None, default:1.0) –A weighting factor for this constraint. Denotes relative importance to other constraints. Closer to zero means less important. Defaults to
1.
Returns:
-
`PositionConstraint`–
Examples:
classmethod
¤
from_point(
link_name: str, point: Point, tolerance_position: float, weight: float | None = 1.0
) -> PositionConstraint
Create a PositionConstraint from a point.
Parameters:
-
link_name(str) –The name of the link this constraint refers to.
-
point(Point) –Point defining the bounding volume this constraint refers to.
-
tolerance_position(float) –The allowed tolerance to the point's position (defined in the robot's units).
-
weight(float | None, default:1.0) –A weighting factor for this constraint. Denotes relative importance to other constraints. Closer to zero means less important. Defaults to
1.
Returns:
-
`PositionConstraint`–
classmethod
¤
from_sphere(
link_name: str, sphere: Sphere, weight: float | None = 1.0
) -> PositionConstraint
Create a PositionConstraint from a Sphere.
Parameters:
-
link_name(str) –The name of the link this constraint refers to.
-
sphere(Sphere) –Sphere defining the bounding volume this constraint refers to.
-
weight(float | None, default:1.0) –A weighting factor for this constraint. Denotes relative importance to other constraints. Closer to zero means less important. Defaults to
1.
Returns:
-
`PositionConstraint`–
Examples:
scale(scale_factor: float) -> None
Scale the bounding_volume uniformly.
Parameters:
-
scale_factor(float) –Factor to scale constraining
bounding_volume.
scaled(scale_factor: float) -> Constraint
Get a scaled copy of this Constraint.
Parameters:
-
scale_factor(float) –Scale factor used to scale the
Constraint.
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:
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.
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.
transform(transformation: Transformation) -> None
classmethod
¤
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–
The ReachabilityMap describes the reachability of a robot.
The ReachabilityMap describes the reachability of a robot at certain frames, with valid IK solutions at these frames. The map only makes sense to be calculated with analytic inverse kinematic solvers, as they include all possible solutions to be found.
Attributes:
-
frames(list of list of [`Frame`][compas.geometry.Frame]) –The frames at which the IK solutions are calculated.
-
configurations(list of list of list of [`Configuration`][compas_robots.Configuration]) –The configurations at the frames.
-
score(list of int) –The number of solutions per frame list (2D)
-
points(list of [`Point`][compas.geometry.Point]) –The points per frame list (2D)
-
shape(tuple of int) –The shape of the frames array
Notes
See Also reuleaux
Attributes¤
Methods:¤
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.
classmethod
¤
calculate(
frame_generator: Generator,
planner: PlannerInterface,
robot_cell_state: RobotCellState,
target_mode: TargetMode,
ik_options: dict | None = None,
)
Calculates the reachability map for a robot cell.
The robot_cell must be set in the planner before calling this function by calling
planner.set_robot_cell(robot_cell)
Collision checking is only available if the planner supports it. For example, AnalyticalPyBulletPlanner supports collision checking while AnalyticalKinematicsPlanner does not.
If tools are attached to the robot, the robot cell must contain the tool and robot cell state must reflect this. The frame generator will generate frames for the Tool Coordinate Frame (TCF). If no tools are attached, the robot's Planner Coordinate Frame (PCF) is used.
Parameters:
-
frame_generator(Generator) –A 2D frame generator to yield
Frame. -
planner(PlannerInterface) –The planner backend for which inverse kinematics is being calculated. It only makes only sense to use AnalyticalPyBulletPlanner or AnalyticalKinematicsPlanner
-
robot_cell_state(RobotCellState) –The robot cell state for which the reachability map is calculated. The initial robot configuration is not important.
-
ik_options(dict | None, default:None) –Optional arguments to be passed on to the planner's inverse kinematics function.
-
target_mode(TargetMode) –The target mode for the targets generated by the frame generator.
Raises:
-
ValueError : If the frame_generator does not produce a 2D list of frames–
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.
classmethod
¤
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.
classmethod
¤
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.
Returns the reachable frames and configurations at a specific ik index.
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:
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.
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.
classmethod
¤
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–
RigidBody(
visual_meshes: list[Mesh] | Mesh,
collision_meshes: list[Mesh] | Mesh,
native_scale: float = 1.0,
name: str | None = None,
)
Represents a rigid body.
A rigid body can have different visual and collision meshes.
The native unit (in compas_fab and backends) for the meshes is meters 'native_scale=1.0'.
If the user created the rigid body in a different unit, the scale must be set such that the
mesh.scale(native_scale) will convert the mesh to meters.
For example, if the modeling environment is in millimeters, the scale should be set to 0.001.
Notes
The number of objects in the collision meshes does not have to be the same as the visual meshes. If the user wants to use the same mesh for both visualization and collision checking, place the meshes in visual_meshes and leave the collision_meshes empty.
Parameters:
-
visual_meshes(list[Mesh] | Mesh) –The visual meshes of the rigid body used for visualization purpose. They can be more detailed for realistic visualization without affecting planning performance. If left empty, the rigid body will not be visualized.
-
collision_meshes(list[Mesh] | Mesh) –The collision meshes of the rigid body used for collision checking. They should be less detailed (fewer polygons) for better planning performance. If
None, or an empty list is passed, no collision checking will be performed for the rigid body. -
native_scale(float, default:1.0) –The native scale factor of the meshes defined as
user_object_value * native_scale = meter_object_value. In another words,mesh.scale(native_scale)will convert the input mesh to meters. For example, if the modeling environment is in millimeters,native_scaleshould be set to'0.001'. Default is'1.0'. -
name(str | None, default:None) –
Attributes:
-
visual_meshes–A list of meshes for visualization purpose.
-
collision_meshes–A list of meshes for collision checking.
Notes
compas_fab do not support weight and inertia properties for rigid bodies.
Attributes¤
property
¤
The collision meshes of the rigid body in meters.
This function returns a list of new meshes, the original meshes are not modified.
property
¤
The visual meshes of the rigid body in meters.
This function returns a list of new meshes, the original meshes are not modified.
Methods:¤
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.
classmethod
¤
Construct an object of this type from the provided data.
Parameters:
-
data(dict) –The data dictionary.
Returns:
-
class:`compas.data.Data`–An instance of this object type if the data contained in the dict has the correct schema.
classmethod
¤
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.
classmethod
¤
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.
classmethod
¤
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.
classmethod
¤
Creates a RigidBody from a single mesh.
This function is a convenience function for creating a RigidBody from a single mesh. The mesh will be used for both visualization and collision checking.
Parameters:
-
mesh(Mesh) –The mesh of the rigid body.
-
native_scale(float, default:1.0) –The native scale of the rigid body. Default is 1.0.
-
name(str | None, default:None) –A human-readable identifier for the rigid body. Default is
None.
Returns:
-
[`RigidBody`][compas_fab.robots.RigidBody]–The rigid body.
Notes
If the user would like to use different meshes for visualization and collision checking,
consider using the constructor directly: RigidBody(visual_meshes, collision_meshes).
classmethod
¤
Creates a RigidBody from a list of meshes.
This function is a convenience function for creating a RigidBody from a list of meshes. The first mesh will be used for visualization and collision checking. The rest of the meshes will be used for visualization only.
Parameters:
-
meshes(list[Mesh]) –The meshes of the rigid body.
-
native_scale(float, default:1.0) –The native scale of the rigid body. Default is 1.0.
-
name(str | None, default:None) –A human-readable identifier for the rigid body. Default is
None.
Returns:
-
[`RigidBody`][compas_fab.robots.RigidBody]–The rigid body.
Notes
If the user would like to use different meshes for visualization and collision checking,
consider using the constructor directly: RigidBody(visual_meshes, collision_meshes).
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:
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.
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.
classmethod
¤
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–
Methods:¤
classmethod
¤
Create and return a floor as RigidBody, useful for simulating a floor.
The floor is square with a default size of 1m x 1m, centered around the
object origin and sitting clearance below Z=0 (default 1 cm).
The downward offset keeps the floor from registering a collision with the
robot's base link, which would otherwise make every configuration fail
collision checking. Note that a robot base's collision geometry often
dips a few millimetres below Z=0 (e.g. the UR5 base_link_inertia
reaches about -7 mm), so the clearance must exceed that, not just a
floating-point epsilon — hence the 1 cm default. Deep-skirted bases may
need a larger value; pass clearance=0 for a floor flush with Z=0.
The robot-agnostic alternative is to not offset at all and instead add the
base link to the floor's RigidBodyState touch_links (what the bundled
cells such as ur5_cone_tool do), which exempts the pair no matter how
far the base geometry extends.
The floor has only one visual mesh, and one collision mesh.
classmethod
¤
Create and return a target marker as RigidBody, useful for visualizing the target pose.
The target marker points out the X, Y, Z directions with its shape. It is fully contained within a cube in the positive octant of the target frame. The size of the cube is determined by the input size.
The marker has only one visual mesh, and no collision mesh.
RigidBodyState(
frame: Frame,
attached_to_link: str | None = None,
attached_to_tool: str | None = None,
touch_links: list[str] | None = None,
touch_bodies: list[str] | None = None,
attachment_frame: Frame | None = None,
is_hidden: bool = False,
)
Represents the state of a workpiece in a RobotCell.
Rigid bodies can be used to represent different types of objects in the robot cell:
- Workpieces that are attached to the tip of a tool
- Robotic backpacks or other accessories that are attached to links of the robot
- Workpieces or Static obstacles in the environment
- All of the above objects but are currently hidden
When representing a workpiece that is attached to a tool, the attached_to_tool attribute should be
set to the name of the tool. The attachment_frame attribute should be set to the grasp frame,
which represents the position of the workpiece relative to the tool coordinate frame (TCF).
When representing a collision geometry (such as robotic backpacks) that is attached to a link of the robot,
the attached_to_link attribute should be set. The attachment_frame attribute should be set to the relative position
of the rigid body to the base frame of the link.
The touch_links attribute should be set to the names of the robot links that are allowed
to collide with the object.
In either one of the two attached cases, the frame attribute should be set to 'None' as the actual frame
is determined automatically by the position of the attached link or tool.
Even if the attribute is not set to None, it will be disregarded.
When representing a stationary object in the environment, such as stationary workpiece or obstacles,
both attached_to_ attributes should be set to None. The frame attribute should be set to the base frame
of the object relative to the world coordinate frame.
If the stationary object touches the robot, the touch_links attribute should be set
to the names of the robot links that are allowed to collide with the object.
When representing a workpiece that is currently not in the scene, the is_hidden attribute should be set to True.
This will hide the object from collision checking and visualization.
Attributes:
-
frame–The base frame of the rigid body relative to the world coordinate frame.
-
attached_to_link–The name of the robot link to which the rigid body is attached.
Noneif not attached to a link. -
attached_to_tool–The id of the tool to which the rigid body is attached.
Noneif not attached to a tool. -
touch_links–The names of the robot links that are allowed to collide with the rigid body.
[]if the rigid body is not allowed to collide with any robot links. -
touch_bodies–The names of other rigid bodies (including tools) that are allowed to collide with the rigid body.
[]if the rigid body is not allowed to collide with any other rigid bodies. -
attachment_frame–The attachment (grasp) frame of the rigid body relative to (the base frame of) the attached link or (the tool tip frame of) the tool.
Noneif the rigid body is not attached to a link or a tool. -
is_hidden–Whether the rigid body is hidden in the scene. Collision checking will be turned off for hidden objects. Defaults to
False.
Parameters:
-
frame(Frame) –The base frame of the rigid body relative to the world coordinate frame.
-
attached_to_link(str | None, default:None) –The name of the robot link to which the rigid body is attached. Defaults to
None, meaning that the rigid body is not attached to a link. -
attached_to_tool(str | None, default:None) –The id of the tool to which the rigid body is attached. Defaults to
None, meaning that the rigid body is not attached to a tool. -
touch_links(list[str] | None, default:None) –The names of the robot links that are allowed to collide with the rigid body. Defaults to
[], meaning that the rigid body is not allowed to collide with any robot links. -
touch_bodies(list[str] | None, default:None) –The names of other rigid bodies (including tools) that are allowed to collide with the rigid body. Defaults to
[], meaning that the rigid body is not allowed to collide with any other rigid bodies. -
attachment_frame(Frame | None, default:None) –The attachment (grasp) frame of the rigid body relative to (the base frame of) the attached link or (the tool tip frame of) the tool. Defaults to
None, meaning that the rigid body is not attached to a link or a tool. -
is_hidden(bool, default:False) –Whether the rigid body is hidden in the scene. Collision checking will be turned off for hidden objects. Defaults to
False.
Methods:¤
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.
classmethod
¤
Construct an object of this type from the provided data.
Parameters:
-
data(dict) –The data dictionary.
Returns:
-
class:`compas.data.Data`–An instance of this object type if the data contained in the dict has the correct schema.
classmethod
¤
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.
classmethod
¤
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.
classmethod
¤
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.
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:
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.
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.
classmethod
¤
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–
RobotCell(
robot_model: RobotModel | None = None,
robot_semantics: RobotSemantics | None = None,
tool_models: dict[str, ToolModel] | None = None,
rigid_body_models: dict[str, RigidBody] | None = None,
)
Represents all objects in a robot cell. This include - One robot (and its semantics) - ToolModels (including attached tools, and tools that are statically placed in the environment) - RigidBodies (including attached rigid bodies, and rigid bodies that are statically placed in the environment)
Rigid bodies are objects can be used to represent: - Workpieces that are attached to the tip of a tool - Workpieces that are placed in the environment and are not attached - Robotic backpacks or other accessories that are attached to links of the robot - Static obstacles in the environment
Notes regarding scaling: All models in the RobotCell should be in meters. If user models are in millimeters, they should be scaled to meters before being added to the RobotCell.
Attributes:
-
robot_model–The robot model in the robot cell. Note that there can only be one robot in the robot cell. This is equivalent to the URDF in ROS MoveIt workflows.
-
robot_semantics–Semantics describing planning groups, disabled collisions, pre-defined poses etc. for the robot model. This is equivalent to the SRDF in ROS MoveIt workflows.
-
tool_models–The tools in the robot cell. The key is the unique identifier for the tool.
-
rigid_body_models–The rigid bodies in the robot cell. The key is the unique identifier for the rigid body.
-
root_name(str) –The name of the robot's root link.
-
main_group_name(str) –The name of the main planning group of the robot.
-
group_names(list[str]) –The names of all planning groups of the robot.
-
group_states(dict[str, dict]) –The group states of the robot. The first key is the group name, the second key is the group state name. At this level you get a joint dictionary. The third key is the joint name, and the value is the joint value.
-
tool_ids(list[str]) –The ids of the tools in the robot cell.
-
rigid_body_ids(list[str]) –The ids of the rigid bodies in the robot cell.
Attributes¤
property
¤
Returns the data dictionary that represents the RobotCell.
The RobotCell can be used as a data storage container in advanced use scenarios for serializing
a group of tools and environment models.
In this case, the robot_model and robot_semantics can be None.
However, the robot_model and robot_semantics are required for all the planning functions.
property
¤
property
¤
All group states of the robot, only available if semantics is set.
Returns:
-
`dict` of `dict` of `dict` of `float`–The first key is the group name, the second key is the group state name. At this level you get a joint dictionary. The third key is the joint name, and the value is the joint value.
Examples:
property
¤
main_group_name: str
Robot's main planning group, only available if semantics is set.
Returns:
-
`str`–
Methods:¤
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.
classmethod
¤
Construct a RobotCell from a data dictionary.
Parameters:
-
data(dict) –The data dictionary.
Returns:
-
[`RobotCell`][compas_fab.robots.RobotCell]–The robot cell.
classmethod
¤
assert_cell_state_match(robot_cell_state: RobotCellState) -> None
Assert that the number of tools and rigid bodies in the cell state match the number of tools and workpieces in the robot cell.
compute_attach_objects_frames(robot_cell_state: RobotCellState) -> RobotCellState
Compute the frames of the attached objects (tools and workpieces) from a robot cell state with robot configuration.
The frames of the attached objects (relative to WCF) are computed
using the forward kinematics function from the RobotModel.
Therefore, the function is available even without any backend planner.
A full robot configuration (containing all joints) must be present in the robot_cell_state input.
A new robot cell state is returned, where the attached objects have their frame attributes updated.
Parameters:
-
robot_cell_state(RobotCellState) –The state of the robot cell. The robot configuration must be set in the robot state.
Returns:
-
[`RobotCellState`][compas_fab.robots.RobotCellState]–A new robot cell state with the attached objects' frames updated.
configuration_to_full_configuration(
configuration: Configuration, full_configuration: Configuration | None = None
) -> Configuration
Create a new Configuration object from a given configuration and fill in the missing joints from a given full_configuration. The joint values in the configuration takes precedence over the full_configuration.
Parameters:
-
configuration(Configuration) –The configuration of the group. The attributes
joint_namesandjoint_typesmust be provided. -
full_configuration(Configuration | None, default:None) –The full configuration of the robot. If not provided, the full configuration is created using
zero_full_configuration.
Returns:
-
[`Configuration`][compas_robots.Configuration]–A new Configuration object with all the joints of the robot.
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.
default_cell_state() -> RobotCellState
Create a default robot cell state for the robot cell.
Equivalent to RobotCellState.from_robot_cell with the robot cell as input.
The robot's base frame will be assumed to be at worldXY frame. All tools will be assumed to be in their zero configuration and positioned at worldXY frame. All workpieces will be assumed to be in their base frame and not attached to any tool or link. All tools and workpieces are assumed to be visible in the scene (is_hidden=False).
Returns:
-
[`RobotCellState`][compas_fab.robots.RobotCellState]–The default robot cell state.
Return the link a tool attached at the group's end-effector will sit flush against.
Walks up the kinematic chain from the end-effector link, skipping every geometry-less mounting link, and returns the first link with visual or collision geometry — the one a tool attached at the EE inevitably overlaps. Geometry-less frame links are not included (MoveIt has no geometry to collide with for them, so listing them as touch links is meaningless).
This is a sensible default for the touch_links argument of
RobotCellState.set_tool_attached_to_group.
For robots where the end-effector link itself carries geometry
(e.g. Panda's panda_link8), the EE link is returned. For robots
that expose a chain of frame-only mounting links (e.g. UR5:
tool0 → flange → wrist_3_link), the walk steps past those
and returns just the first solid ancestor (wrist_3_link).
Parameters:
-
group(str | None, default:None) –Defaults to the cell's main planning group.
Returns:
-
list of str–A single-element list with the first link bearing geometry along the EE chain; or an empty list if no such link exists (degenerate).
Examples:
Check if the model's geometry has been loaded.
Raises:
-
`Exception`–If geometry has not been loaded.
Check if semantics is set.
Raises:
-
`Exception`–If
semanticsis not set.
fill_configuration_with_joint_names(
configuration: Configuration, group: str | None = None
) -> Configuration
Create a new configuration object from the given configuration and to fill in the joint_types and joint_names if they are missing.
- If the supplied configuration has joint_names and joint_types, a new configuration object with the same values is returned.
- If the supplied configuration is a full configuration (has all configurable joints of the robot),
the
groupinput has no effect. - If the supplied configuration is a group configuration (has only the joints of a specific group), the corresponding group name must be passed.
Returned Configuration is a new object and contain .joint_names attribute.
Parameters:
-
configuration(Configuration) –The configuration to fill with joint names and types.
-
group(str | None, default:None) –The name of the planning group. Defaults to None.
Returns:
-
[`Configuration`][compas_robots.Configuration]–The configuration with joint names and types.
forward_kinematics_target_frame(
robot_cell_state: RobotCellState,
target_mode: TargetMode,
group: str | None = None,
native_scale: float | None = None,
) -> Frame
Compute the target frame of the robot for the specified planning group and target mode.
. The Planner Coordinate Frame (PCF) relative to WCF is returned for TargetMode.ROBOT.¤
. The Tool Coordinate Frame (TCF) relative to WCF is returned for TargetMode.TOOL.¤
. The Object Coordinate Frame (OCF) relative to WCF is returned for TargetMode.WORKPIECE.¤
Forward kinematics function is provided by the RobotModel.
Therefore, the function is available even without any backend planner.
A full robot configuration (containing all joints) must be present in
the robot_cell_state input.
Parameters:
-
robot_cell_state(RobotCellState) –The state of the robot cell. The robot configuration must be set in the robot state.
-
target_mode(TargetMode) –The target mode of the frame. The target mode must be supported by the robot cell state.
-
group(str | None, default:None) –The name of the planning group. Defaults to the main planning group.
Returns:
-
[`Frame`][compas.geometry.Frame]–The target frame as interpreted by the target mode, relative to the World Coordinate Frame (WCF).
classmethod
¤
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.
classmethod
¤
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.
from_ocf_to_pcf(
robot_cell_state: RobotCellState, ocf_frames: list[Frame], workpiece_id: str
) -> list[Frame]
Converts a frame describing the object coordinate frame (OCF) relative to WCF to a frame describing the planner coordinate frame (PCF) (also T0CF) relative to WCF. The transformation goes from the workpiece's base frame, through the workpiece's attachment frame (in workpiece_state), to the tool's TCF.
This workpiece specified by the workpiece_id must be attached to a tool, and the tool must be attached to the robot in the robot cell state.
This is typically used by the planner at the beginning of the inverse kinematics calculation to convert the frame of the object (ocf) to the frame of the robot's flange (tool0).
Parameters:
-
robot_cell_state(RobotCellState) –The state of the robot cell.
-
ocf_frames(list[Frame]) –Object Coordinate Frames (OCF) relative to the World Coordinate Frame (WCF).
-
workpiece_id(str) –The id of a workpiece found in
client.robot_cell.rigid_body_models. The workpiece must be attached to a tool, and the tool must be attached to the robot.
Returns:
-
[`Frame`][compas.geometry.Frame]–Planner Coordinate Frames (PCF) (also T0CF) relative to the World Coordinate Frame (WCF).
Notes
This function works correctly even when there are multiple workpieces attached to the robot. Simply pass the correct workpiece_id to the function.
from_pcf_to_ocf(
robot_cell_state: RobotCellState, pcf_frames: list[Frame], workpiece_id: str
) -> list[Frame]
Converts a frame describing the planner coordinate frame (PCF) (also T0CF) relative to WCF to a frame describing the object coordinate frame (OCF) relative to WCF.
The transformation goes from the tool's attachment frame (in ToolState),
through the tool's .frame (in ToolModel),
through the workpiece's attachment frame (in workpiece_state),
arriving at the workpiece's base frame.
This workpiece specified by the workpiece_id must be attached to a tool, and the tool must be attached to the robot in the robot cell state.
Parameters:
-
robot_cell_state(RobotCellState) –The state of the robot cell.
-
pcf_frames(list[Frame]) –Planner Coordinate Frames (PCF) (also T0CF) relative to the World Coordinate Frame (WCF).
-
workpiece_id(str) –The id of a workpiece found in
client.robot_cell.rigid_body_models. The workpiece must be attached to a tool, and the tool must be attached to the robot.
Notes
This function works correctly even when there are multiple workpieces attached to the robot. Simply pass the correct workpiece_id to the function.
from_pcf_to_tcf(
robot_cell_state: RobotCellState, pcf_frames: list[Frame], tool_id: str
) -> list[Frame]
Converts a frame describing the planner coordinate frame (PCF) (also T0CF) relative to WCF to a frame describing the robot's tool coordinate frame (TCF) relative to WCF. The transformation goes through the tool's base frame, which differs from the PCF by the tool's current attachment_frame (in tool_state).
This tool specified by the tool_id must be attached to the robot in the robot cell state.
This is typically used by the planner at the end of the forward kinematics calculation to convert the frame of the robot's flange (tool0) to the frame of the robot's tool tip (tcf).
Parameters:
-
robot_cell_state(RobotCellState) –The state of the robot cell.
-
pcf_frames(list[Frame]) –Planner Coordinate Frames (PCF) (also T0CF) relative to the World Coordinate Frame (WCF).
-
tool_id(str) –The id of a tool found in
client.robot_cell.tool_models. The tool must be attached to the robot.
Returns:
-
[`Frame`][compas.geometry.Frame]–Tool Coordinate Frames (TCF) relative to the World Coordinate Frame (WCF).
from_tcf_to_pcf(
robot_cell_state: RobotCellState, tcf_frames: list[Frame], tool_id: str
) -> list[Frame]
Converts a frame describing the robot's tool coordinate frame (TCF) relative to WCF to a frame describing the planner coordinate frame (PCF), relative to WCF. The transformation goes through the tool's base frame, which differs from the PCF by the tool's current attachment_frame (in tool_state).
This tool specified by the tool_id must be attached to the robot in the robot cell state.
This function is typically used by the planner at the beginning of the inverse kinematics calculation to convert the frame of the robot's tool tip (tcf) to the frame of the robot's flange (tool0).
Parameters:
-
robot_cell_state(RobotCellState) –The state of the robot cell.
-
tcf_frames(list[Frame]) –Tool Coordinate Frames (TCF) relative to the World Coordinate Frame (WCF).
-
tool_id(str) –The id of a tool found in
client.robot_cell.tool_models. The tool must be attached to the robot.
Returns:
-
[`Frame`][compas.geometry.Frame]–Planner Coordinate Frames (PCF) (also T0CF) relative to the World Coordinate Frame (WCF).
classmethod
¤
from_urdf_and_srdf(
urdf_filename: str,
srdf_filename: str | None,
local_package_mesh_folder: str | None = None,
) -> RobotCell
Create a robot cell from URDF and SRDF files. Optionally, a local package mesh folder to load mesh geometry.
The new RobotCell will not have any tools or rigid bodies.
Parameters:
-
urdf_filename(str) –Path to the URDF file.
-
srdf_filename(str | None) –Path to the SRDF file to load semantics.
-
local_package_mesh_folder(str | None, default:None) –Path to the local package mesh folder. If the path is provided, the geometry of the robot is loaded from this folder. Default is
None, which means that the geometry is not loaded.
Returns:
-
[`RobotCell`][compas_fab.robots.RobotCell]–Newly created instance of the robot cell.
full_configuration_to_group_configuration(
full_configuration: Configuration, group: str
) -> Configuration
Filter a full configuration and return only the joints of the specified group.
Parameters:
-
full_configuration(Configuration) –A full configuration (with all configurable joints of the robot). Note that this object is not modified.
-
group(str) –The name of the planning group.
Returns:
-
[`Configuration`][compas_robots.Configuration]–A new configuration object with only the joints of the specified group.
Get all the names of all configurable joints of a planning group.
Similar to get_all_configurable_joints but returning joint names.
Returns:
-
`list` of `str`–
Get all configurable Joint of the robot.
Configurable joints are joints that can be controlled,
i.e., not Joint.FIXED, not mimicking another joint and not a passive joint.
See Joint.is_configurable for more details.
The result of this function is different from RobotModel.get_configurable_joints()
as this also filters out passive joints declared in the RobotSemantics.
Returns:
-
`list` of [`Joint`][compas_robots.model.Joint]–A list of configurable joints.
get_attached_rigid_bodies(robot_cell_state: RobotCellState, group: str) -> list[Mesh]
Returns the rigid bodies attached to the links of the robot as AttachedCollisionMesh.
This does not include the tool and the workpieces attached to the tools.
Use get_attached_tool and get_attached_workpieces to get those.
get_attached_tool(robot_cell_state: RobotCellState, group: str) -> ToolModel | None
Return the ToolModel of the tool attached to the group in the robot cell state.
There can only be a maximum of one tool attached to a planning group.
Parameters:
-
robot_cell_state(RobotCellState) –The state of the robot cell. The tool attachment information is stored in the tool_states attribute.
-
group(str) –The name of the planning group to which the tool is attached. This is not optional because the robot cell and and the state do not have knowledge of the main group name.
Returns:
-
[`ToolModel`][compas_robots.ToolModel]–The tool attached to the group in the robot cell state. None if no tool is attached.
get_attached_workpieces(
robot_cell_state: RobotCellState, group: str
) -> list[RigidBody]
Returns the workpiece attached to the tool attached to the group in the robot cell state.
There can be more than one workpiece attached to a tool.
Returns:
-
list of [`RigidBody`][compas_fab.robots.RigidBody]–The workpieces attached to the tool attached to the group in the robot cell state. Empty list if no workpiece is attached or no tool is attached.
Get the robot's base link.
Parameters:
-
group(str | None, default:None) –The name of the planning group. Defaults to the main planning group.
Returns:
-
[`Link`][compas_robots.Link]–
Examples:
Get all the names of configurable joints of a planning group.
Similar to get_configurable_joints but returning joint names.
Parameters:
-
group(str | None, default:None) –The name of the planning group. Defaults to the main planning group.
Returns:
-
`list` of `str`–
Notes
This function is different from RobotModel.get_configurable_joint_name(),
as this function filters only the joints of the specified group.
Get the configurable joint types.
Parameters:
-
group(str | None, default:None) –The name of the planning group. Defaults to the main planning group.
Returns:
-
`list` of [`Joint.SUPPORTED_TYPES`][compas_robots.Joint.SUPPORTED_TYPES]–
Notes
If semantics is set and no group is passed, it returns all
configurable joint types of all groups.
Examples:
Get all configurable Joint of a planning group.
Configurable joints are joints that can be controlled,
i.e., not Joint.FIXED, not mimicking another joint and not a passive joint.
See Joint.is_configurable for more details.
Important: Setting the group to None, does not return all configurable joints of the robot,
but that of the main planning group.
Parameters:
-
group(str | None, default:None) –The name of the planning group. Defaults to the main planning group.
Returns:
-
`list` of [`Joint`][compas_robots.model.Joint]–A list of configurable joints.
Notes
This function is different from RobotModel.get_configurable_joints(),
as this function filters only the joints of the specified group.
get_configuration_from_group_state(group: str, group_state_name: str) -> Configuration
Get the Configuration from a predefined group state.
Group states are predefined configurations of a planning group in the RobotSemantics.
Parameters:
Returns:
-
[`Configuration`][compas_robots.Configuration]–The configuration specified by the
group_state.
Get the robot's end effector link.
Parameters:
-
group(str | None, default:None) –The name of the planning group. Defaults to the main planning group.
Returns:
-
[`Link`][compas_robots.Link]–
Examples:
Get the name of the robot's end effector link.
Parameters:
-
group(str | None, default:None) –The name of the group. Defaults to the main planning group.
Returns:
-
`str`–
Examples:
Get the names of the group states of a planning group.
Parameters:
-
group(str) –The name of the planning group.
Returns:
-
`list` of `str`–
Examples:
Get the names of the links in the kinematic chain.
Parameters:
-
group(str | None, default:None) –The name of the planning group. Defaults to the main planning group.
Returns:
-
`list` of `str`–
Examples:
Get the names of the links with collision geometry.
Note that returned names does not imply that the link has collision geometry loaded.
Use ensure_geometry() to ensure that collision geometry is loaded.
Returns:
-
`list` of `str`–
Examples:
pcf_to_target_frames(
robot_cell_state: RobotCellState,
frame_or_frames: Frame | list[Frame],
target_mode: TargetMode,
group: str,
) -> Frame | list[Frame]
Converts a (or a list of) Planner Coordinate Frame (PCF) to the target frame according to the target mode.
For example, if the target mode is TargetMode.TOOL, the function will convert the PCF to the TCF.
If the target mode is TargetMode.WORKPIECE, the function will convert the PCF to the workpiece's OCF.
This function is the opposite of target_frames_to_pcf.
Parameters:
-
robot_cell_state(RobotCellState) –The state of the robot cell.
-
frame_or_frames(Frame | list[Frame]) –The PCF frame or frames to convert.
-
target_mode(TargetMode) –The target mode of the frame or frames.
-
group(str) –The planning group to check. Must be specified.
Returns:
-
[`Frame`][compas.geometry.Frame] or list of [`Frame`][compas.geometry.Frame]–Target Frame relative to the World Coordinate Frame (WCF). If the input is a single frame, the output will also be a single frame. If the input is a list of frames, the output will also be a list of frames.
random_configuration(group: str | None = None) -> Configuration
Get a random configuration for the specified planning group.
This is not a full configuration of the robot, if a full configuration is needed,
consider merging this configuration with the zero_full_configuration.
For example: robot_cell.zero_full_configuration().merged(robot_cell.random_configuration(group))
Parameters:
-
group(str | None, default:None) –The name of the planning group. Defaults to the main planning group.
Returns:
-
[`Configuration`][compas_robots.Configuration]–
Notes
No collision checking is involved, the configuration may be in collision.
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:
structural_signature() -> str
A stable fingerprint of the cell's structural identity.
Combines the robot model name with the sorted tool and rigid-body ids and
hashes them. Two cells with the same robot and the same set of tool/body
ids (by name) share a signature, regardless of object identity. Useful for
cheaply detecting whether a cell's set of registered models has changed —
e.g. to match an Action's start state to a
cell, or to decide whether a planning scene needs re-uploading.
t_pcf_ocf(robot_cell_state: RobotCellState, workpiece_id: str) -> Transformation
Returns the transformation from the PCF (Planner Coordinate Frame) to the OCF (Object Coordinate Frame).
Parameters:
-
workpiece_id(str) –The id of a workpiece found in
self.rigid_body_models. The workpiece must be attached to a tool, and the tool must be attached to the robot.
Returns:
-
[`Transformation`][compas.geometry.Transformation]–Transformation from the workpiece's OCF to PCF.
t_pcf_tbcf(robot_cell_state: RobotCellState, tool_id: str) -> Transformation
Returns the transformation from the PCF (Planner Coordinate Frame) to the TBCF (Tool Base Coordinate Frame).
Parameters:
-
tool_id(str) –The id of a tool found in
self.robot_cell.tool_models. The tool must be attached to the robot.
Returns:
-
[`Transformation`][compas.geometry.Transformation]–Transformation from the tool's TCF to TBCF.
t_pcf_tcf(robot_cell_state: RobotCellState, tool_id: str) -> Transformation
Returns the transformation from the PCF (Planner Coordinate Frame) to the TCF (Tool Coordinate Frame).
Parameters:
-
tool_id(str) –The id of a tool found in
self.robot_cell.tool_models. The tool must be attached to the robot.
Returns:
-
[`Transformation`][compas.geometry.Transformation]–Transformation from the tool's TCF to TBCF.
target_frames_to_pcf(
robot_cell_state: RobotCellState,
frame_or_frames: Frame | list[Frame],
target_mode: TargetMode,
group: str,
) -> Frame | list[Frame]
Converts a Frame or a list of Frames to the PCF (Planner Coordinate Frame) relative to WCF.
This function is intended to be used by the planner to convert target frames to PCF for planning.
The transformation is equivalent to from_tcf_to_pcf when the target mode is TargetMode.TOOL,
and equivalent to from_ocf_to_pcf when the target mode is TargetMode.WORKPIECE.
If the target mode is TargetMode.ROBOT, the input frames are unchanged.
Parameters:
-
robot_cell_state(RobotCellState) –The state of the robot cell.
-
frame_or_frames(Frame | list[Frame]) –The frame or frames to convert.
-
target_mode(TargetMode) –The target mode of the frame or frames.
-
group(str) –The planning group to check. Must be specified.
Returns:
-
[`Frame`][compas.geometry.Frame] or list of [`Frame`][compas.geometry.Frame]–Planner Coordinate Frame (PCF) relative to the World Coordinate Frame (WCF). If the input is a single frame, the output will also be a single frame. If the input is a list of frames, the output will also be a list of frames.
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.
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.
classmethod
¤
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–
zero_configuration(group: str | None = None) -> Configuration
Get the zero joint configuration for the specified planning group.
If the joint value 0.0 is outside of joint limits (joint.limit.upper, joint.limit.lower) then
(upper + lower) / 2 is used as joint value.
Parameters:
-
group(str | None, default:None) –The name of the planning group. Defaults to the main planning group.
Returns:
-
[`Configuration`][compas_robots.Configuration]–The zero configuration of a planning group.
Notes
The zero configuration is not necessarily the full configuration of the robot unless the planning group contains all the configurable joints of the robot.
Planning functions that requires a start_state (RobotCellState) as input
must contain a full configuration in RobotCellState.robot_configuration, consider
using the zero_full_configuration method to get a full configuration.
Examples:
zero_full_configuration() -> Configuration
Get the zero configuration (all configurable joints) of the robot.
Does not include passive joints or fixed joints.
If the joint value 0.0 is outside of joint limits (joint.limit.upper, joint.limit.lower) then
(upper + lower) / 2 is used as joint value.
Returns:
-
[`Configuration`][compas_robots.Configuration]–The zero configuration of the robot.
A collection of built-in robot cells that can be used for testing and demonstrations.
The RobotCell and RobotCellState
objects created by the factory methods can be used to write examples,
so that the example code can stay short.
The robot cells with only a robot name (e.g. 'ur5') contains only the robot model and semantics. Some robot cells contain also Tool(s) and Rigid Body(s). The Tool(s) are often loaded from the ToolLibrary. Other collision objects such as robot backpacks, floors, tables, workpieces, etc. may also be included depending on the specific robot cell.
All the robot cells constructors has a load_geometry parameter that can be used to
decide if the geometry for the robot and the tool(s) should be loaded or not.
In order to visualize the robot cell or to perform planning functions, the geometry must be loaded.
However, for some tests that may not require geometry, setting load_geometry to 'false'
can speed up the test. If in doubt, use the default value True.
The RobotCellState object contains a predefined state that match with the robot cell. The tool(s) and workpiece(s) may or may not be attached depending on the specific robot cell scenario. Users can simply modify the state to create different scenarios.
Examples:
>>> from compas_fab.robots import RobotCellLibrary
>>> robot_cell, robot_cell_state = RobotCellLibrary.ur5_cone_tool()
>>> robot_cell.robot_model.name
'ur5_robot'
Methods:¤
classmethod
¤
abb_irb120_3_58(load_geometry: bool = True) -> tuple[RobotCell, RobotCellState]
Returns a ABB irb120-3/58 robot.
The returned tuple contains a RobotCell (robot model + semantics) and
a matching default RobotCellState.
Parameters:
-
load_geometry(bool, default:True) –Default is
True, which means that the geometry is loaded.Falsecan be used to speed up the creation of the robot.
Returns:
-
tuple[[`RobotCell`][compas_fab.robots.RobotCell], [`RobotCellState`][compas_fab.robots.RobotCellState]]–Newly created robot cell and its default state.
classmethod
¤
abb_irb4600_40_255(load_geometry: bool = True) -> tuple[RobotCell, RobotCellState]
Returns a ABB irb4600-40/2.55 robot.
The returned tuple contains a RobotCell (robot model + semantics) and
a matching default RobotCellState.
Parameters:
-
load_geometry(bool, default:True) –Default is
True, which means that the geometry is loaded.Falsecan be used to speed up the creation of the robot.
Returns:
-
tuple[[`RobotCell`][compas_fab.robots.RobotCell], [`RobotCellState`][compas_fab.robots.RobotCellState]]–Newly created robot cell and its default state.
classmethod
¤
abb_irb4600_40_255_gripper_one_beam(
load_geometry: bool = True,
) -> tuple[RobotCell, RobotCellState]
Create and return the ABB irb4600-40-255 robot with a gripper tool attached. One beam (a RigidBody) is included and is attached to the gripper. A floor is also included.
See RobotCellLibrary.abb_irb4600_40_255 and
ToolLibrary.static_gripper
for details on the robot and tool.
Parameters:
-
load_geometry(bool, default:True) –Default is
True, which means that the robot and tool geometry are loaded.Falsecan be used to speed up the creation of the robot cell, but without geometry, the robot cell cannot be visualized and backend planners cannot perform collision checking during planning.
Returns:
-
tuple[[`RobotCell`][compas_fab.robots.RobotCell], [`RobotCellState`][compas_fab.robots.RobotCellState]]–Newly created instance of the robot cell and robot cell state.
classmethod
¤
abb_irb4600_40_255_printing_tool(
load_geometry: bool = True,
) -> tuple[RobotCell, RobotCellState]
Create and return the ABB irb4600-40-255 robot with a printing tool attached. A floor is also included.
See RobotCellLibrary.abb_irb4600_40_255
and ToolLibrary.printing_tool
for details on the robot and tool.
Parameters:
-
load_geometry(bool, default:True) –Default is
True, which means that the robot and tool geometry are loaded.Falsecan be used to speed up the creation of the robot cell, but without geometry, the robot cell cannot be visualized and backend planners cannot perform collision checking during planning.
Returns:
-
tuple[[`RobotCell`][compas_fab.robots.RobotCell], [`RobotCellState`][compas_fab.robots.RobotCellState]]–Newly created instance of the robot cell and robot cell state.
classmethod
¤
panda(load_geometry: bool = True) -> tuple[RobotCell, RobotCellState]
Returns a Panda robot.
The returned tuple contains a RobotCell (robot model + semantics) and
a matching default RobotCellState.
Parameters:
-
load_geometry(bool, default:True) –Default is
True, which means that the geometry is loaded.Falsecan be used to speed up the creation of the robot.
Returns:
-
tuple[[`RobotCell`][compas_fab.robots.RobotCell], [`RobotCellState`][compas_fab.robots.RobotCellState]]–Newly created robot cell and its default state.
classmethod
¤
rfl(load_geometry: bool = True) -> tuple[RobotCell, RobotCellState]
Create and return the RFL robot with 4 ABB irb 4600 and twin-gantry setup.
The returned tuple contains a RobotCell (robot model + semantics) and
a matching default RobotCellState.
Parameters:
-
load_geometry(bool, default:True) –Default is
True, which means that the geometry is loaded.Falsecan be used to speed up the creation of the robot.
Returns:
-
tuple[[`RobotCell`][compas_fab.robots.RobotCell], [`RobotCellState`][compas_fab.robots.RobotCellState]]–Newly created robot cell and its default state.
classmethod
¤
ur10e(load_geometry: bool = True) -> tuple[RobotCell, RobotCellState]
Returns a UR10e robot.
The returned tuple contains a RobotCell (robot model + semantics) and
a matching default RobotCellState.
Parameters:
-
load_geometry(bool, default:True) –Default is
True, which means that the geometry is loaded.Falsecan be used to speed up the creation of the robot.
Returns:
-
tuple[[`RobotCell`][compas_fab.robots.RobotCell], [`RobotCellState`][compas_fab.robots.RobotCellState]]–Newly created robot cell and its default state.
classmethod
¤
ur10e_gripper_one_beam(load_geometry: bool = True) -> tuple[RobotCell, RobotCellState]
Create and return the ur10e robot with a gripper tool attached. One beam (a RigidBody) is included and is attached to the gripper. A floor is also included.
See RobotCellLibrary.ur10e and ToolLibrary.static_gripper_small
for details on the robot and tool.
Parameters:
-
load_geometry(bool, default:True) –Default is
True, which means that the robot and tool geometry are loaded.Falsecan be used to speed up the creation of the robot cell, but without geometry, the robot cell cannot be visualized and backend planners cannot perform collision checking during planning.
Returns:
-
tuple[[`RobotCell`][compas_fab.robots.RobotCell], [`RobotCellState`][compas_fab.robots.RobotCellState]]–Newly created instance of the robot cell and robot cell state.
classmethod
¤
ur5(load_geometry: bool = True) -> tuple[RobotCell, RobotCellState]
Returns a UR5 robot.
The returned tuple contains a RobotCell (robot model + semantics) and
a matching default RobotCellState.
The main planning group of the robot is named 'manipulator'. The first and last link on the 'manipulator' group is named 'base_link' and 'tool0'.
Parameters:
-
load_geometry(bool, default:True) –Default is
True, which means that the geometry is loaded.Falsecan be used to speed up the creation of the robot.
Returns:
-
tuple[[`RobotCell`][compas_fab.robots.RobotCell], [`RobotCellState`][compas_fab.robots.RobotCellState]]–Newly created robot cell and its default state.
classmethod
¤
ur5_cone_tool(load_geometry: bool = True) -> tuple[RobotCell, RobotCellState]
Create and return the UR5 robot with a cone tool attached. A floor is also included.
See RobotCellLibrary.ur5 and ToolLibrary.cone
for details on the robot and tool.
Parameters:
-
load_geometry(bool, default:True) –Default is
True, which means that the robot and tool geometry are loaded.Falsecan be used to speed up the creation of the robot cell, but without geometry, the robot cell cannot be visualized and backend planners cannot perform collision checking during planning.
Returns:
-
tuple[[`RobotCell`][compas_fab.robots.RobotCell], [`RobotCellState`][compas_fab.robots.RobotCellState]]–Newly created instance of the robot cell and robot cell state.
classmethod
¤
ur5_gripper_one_beam(load_geometry: bool = True) -> tuple[RobotCell, RobotCellState]
Create and return the ur5 robot with a gripper tool attached. One beam (a RigidBody) is included and is attached to the gripper. A floor is also included.
See RobotCellLibrary.ur5 and ToolLibrary.static_gripper_small
for details on the robot and tool.
Parameters:
-
load_geometry(bool, default:True) –Default is
True, which means that the robot and tool geometry are loaded.Falsecan be used to speed up the creation of the robot cell, but without geometry, the robot cell cannot be visualized and backend planners cannot perform collision checking during planning.
Returns:
-
tuple[[`RobotCell`][compas_fab.robots.RobotCell], [`RobotCellState`][compas_fab.robots.RobotCellState]]–Newly created instance of the robot cell and robot cell state.
RobotCellState(
robot_base_frame: Frame | None = None,
robot_configuration: Configuration | None = None,
tool_states: dict[str, ToolState] | None = None,
rigid_body_states: dict[str, RigidBodyState] | None = None,
)
Represents the state of a robot cell.
This class should be used to represent the complete state of a robot cell, not a partial state. The list of tool_states and rigid_body_states should match the list of tools and workpieces in the RobotCell.
The only optional attribute is the robot configuration, which is not known before the motions are planned.
Methods:¤
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.
classmethod
¤
Construct an object of this type from the provided data.
Parameters:
-
data(dict) –The data dictionary.
Returns:
-
class:`compas.data.Data`–An instance of this object type if the data contained in the dict has the correct schema.
classmethod
¤
assert_target_mode_match(target_mode: TargetMode | None, group: str) -> None
Check if the current tool and workpiece attachment state support the specified TargetMode.
If the target_mode is None,
such as the cases for ConfigurationTarget and ConstraintSetTarget,
this function will not perform any checks.
This check is performed automatically by planning functions, it can also be called manually by the user to ensure that the robot cell state is correctly set up.
Checks are performed as follows:
- If target mode is
TargetMode.TOOL, the specified planning group must have a tool attached. - If target mode is
TargetMode.WORKPIECE, the specified planning group must have one and only one workpiece attached.
Parameters:
-
target_mode(TargetMode | None) –The target or waypoints to check.
-
group(str) –The planning group to check. Must be specified.
Raises:
-
[`TargetModeMismatchError`][compas_fab.backends.TargetModeMismatchError]–If the target mode is
TOOLand no tool is attached to the robot in the specified group. If the target mode isWORKPIECEand no (or more than one) workpiece is attached to the specified group. -
ValueError–If the planning group is not specified.
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.
classmethod
¤
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.
classmethod
¤
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.
classmethod
¤
from_robot_cell(
robot_cell: RobotCell, robot_configuration: Configuration | None = None
) -> RobotCellState
Creates a default RobotCellState from a RobotCell.
This function ensures that all the tools and workpieces in the robot cell are represented in the robot cell state. This function should be called after the robot cell is created and all objects are added to it.
The robot's base frame will be assumed to be at worldXY frame. All tools will be assumed to be in their zero configuration and positioned at worldXY frame. All workpieces will be assumed to be in their base frame and not attached to any tool or link. All tools and workpieces are assumed to be visible in the scene (is_hidden=False).
Parameters:
-
robot_cell(RobotCell) –The robot cell.
-
robot_configuration(Configuration | None, default:None) –The configuration of the robot. If the configuration is not provided, the robot's zero configuration will be used.
Returns the ids of the rigid bodies attached to links of the robot and to tools.
Returns:
-
List[str]–The ids of the rigid bodies attached to the robot.
Returns the id of the tool attached to the planning group.
There can only be a maximum of one tool attached to a planning group.
Returns:
-
str–The id of the tool attached to the planning group. None if no tool is attached.
Returns the id of the workpiece attached to the tool attached to the planning group.
Workpieces are rigid bodies that are attached to the tip of a tool. There can be more than one workpiece attached to a tool.
Returns:
-
List[str]–The ids of the workpieces attached to the tool attached to the planning group.
Returns the ids of the tools that are not attached to any planning group.
Returns:
-
List[str]–The ids of the tools that are not attached to any planning group.
set_rigid_body_attached_to_link(
rigid_body_id: str,
link_name: str,
attachment_frame: Frame | Transformation | None = None,
touch_links: list[str] | None = None,
) -> None
Sets the rigid body attached to the link of the robot.
Notes
There can be more than one rigid body attached to a link. A RigidBody cannot be attached to both a link and a tool.
Parameters:
-
rigid_body_id(str) –The id of the rigid body.
-
link_name(str) –The name of the link to which the rigid body is attached.
-
attachment_frame(Frame | Transformation | None, default:None) –The frame of the rigid body relative to the link. Defaults to None, which means that the rigid body is at the base of the link.
-
touch_links(list[str] | None, default:None) –The names of the robot links that are allowed to collide with the rigid body.
set_rigid_body_attached_to_tool(
rigid_body_id: str, tool_id: str, attachment_frame: Frame | None = None
)
Sets the rigid body attached to the tool.
Notes
There can be more than one rigid body attached to the tip of a tool. A RigidBody cannot be attached to both a link and a tool.
Parameters:
-
rigid_body_id(str) –The id of the rigid body.
-
tool_id(str) –The id of the tool to which the rigid body is attached.
-
attachment_frame(Frame | None, default:None) –The attachment (grasp) frame of the rigid body relative to the tool. Defaults to None, which means that the rigid body is at the tip of the tool.
set_tool_attached_to_group(
tool_id: str,
group: str,
attachment_frame: Frame | None = None,
touch_links: list[str] | None = None,
) -> None
Sets the tool attached to the planning group.
Any other tools that is attached to the specified planning group will be detached.
Notes
There can only be a maximum of one tool attached to a planning group.
Parameters:
-
tool_id(str) –The id of the tool.
-
group(str) –The name of the planning group to which the tool is attached.
-
attachment_frame(Frame | None, default:None) –The frame of the tool relative to the end frame of the planning group. Defaults to None, which means that the tool's frame coincides with the end frame of the planning group.
-
touch_links(list[str] | None, default:None) –The names of the robot links that are allowed to collide with the tool.
set_tool_detached(
tool_id: str, frame: Frame | None = None, touch_links: list[str] | None = None
) -> None
Sets the tool to be detached from the planning group.
Parameters:
-
tool_id(str) –The id of the tool.
-
frame(Frame | None, default:None) –The frame of the tool (relative to the world coordinate frame) after detaching. Defaults to None, which means that the tool's frame is not changed.
-
touch_links(list[str] | None, default:None) –The names of the robot links that are allowed to collide with the tool. Defaults to None, which means that the tool's touch links are reset to an empty list. If this behavior is not desired, consider modifying the tool_states directly or set the touch_links set explicitly.
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:
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.
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.
classmethod
¤
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–
RobotSemantics(
groups: dict[str, dict[str, list[str]]] | None = None,
main_group_name: str | None = None,
passive_joints: list[str] | None = None,
end_effectors: list[str] | None = None,
disabled_collisions: set[tuple[str, str]] | None = None,
group_states: dict[str, dict[str, dict[str, float]]] | None = None,
)
Represents semantic information of a robot.
The semantic model is based on the
Semantic Robot Description Format (SRDF).
Typically, the RobotSemantics objects are created from an SRDF file (using from_srdf_file)
or loaded as part of a RobotCell by a backend client
(e.g. RosClient.load_robot_cell).
Parameters:
-
groups(dict[str, dict[str, list[str]]] | None, default:None) –A nested dictionary defining planning groups. The dictionary structure is as follows:
- Level 1 keys are planning group names :
str. -
Level 2 contains only two keys:
linksis alistofstrcontaining link namesjointsis alistofstrcontaining joint names.
- Level 1 keys are planning group names :
-
main_group_name(str | None, default:None) –The name of the main group.
-
passive_joints(list[str] | None, default:None) –A list of passive joint names.
-
end_effectors(list[str] | None, default:None) –A list of end effector link names.
-
disabled_collisions(set[tuple[str, str]] | None, default:None) –A set of disabled collision pairs. The order is not important, i.e. the pair
('link1', 'link2')is the same as('link2', 'link1'). Only one pair is needed. -
group_states(dict[str, dict[str, dict[str, float]]] | None, default:None) –A nested dictionary defining named states for a particular group, in terms of joint values. This is useful to define states such as "home" or "folded arms" for the robot. The dictionary structure is as follows:
- Level 1 keys are planning group names :
str. - Level 2 keys are group state names :
str. - Level 3 keys are joint names
strand values are joint valuesfloat.
- Level 1 keys are planning group names :
Attributes:
-
group_names(list[str]) –Get the names of all planning groups.
-
unordered_disabled_collisions(set[frozenset]) –Get the disabled collision pairs as a set of frozensets.
Methods:¤
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.
classmethod
¤
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.
classmethod
¤
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.
classmethod
¤
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.
classmethod
¤
from_srdf_file(file: str, robot_model: RobotModel) -> RobotSemantics
Create an instance of semantics based on an SRDF file path or file-like object.
Parameters:
-
file(str) –The path to the SRDF file.
-
robot_model(RobotModel) –The robot model is needed when loading the semantics.
Examples:
>>> from compas_robots import RobotModel
>>> urdf_filename = compas_fab.get("robot_library/ur5_robot/urdf/robot_description.urdf")
>>> srdf_filename = compas_fab.get("robot_library/ur5_robot/robot_description_semantic.srdf")
>>> robot_model = RobotModel.from_urdf_file(urdf_filename)
>>> semantics = RobotSemantics.from_srdf_file(srdf_filename, robot_model)
>>> print(semantics.main_group_name)
manipulator
classmethod
¤
from_srdf_string(text: str, robot_model: RobotModel) -> RobotSemantics
Create an instance of semantics based on an SRDF string.
Parameters:
-
text(str) –The SRDF data as a string.
-
robot_model(RobotModel) –The robot model is needed when loading the semantics.
classmethod
¤
from_xml(xml: XML, robot_model: RobotModel) -> RobotSemantics
Create an instance of semantics based on an XML object.
Parameters:
-
xml(XML) –The XML object containing the SRDF data.
-
robot_model(RobotModel) –The robot model is needed when loading the semantics.
Get the name of the first link (base link) in a planning group.
Parameters:
-
group(str | None, default:None) –The name of the planning group. Defaults to the main planning group.
Returns:
-
`str`–The name of the base link.
Get the name of the last link (end effector link) in a planning group.
Parameters:
-
group(str | None, default:None) –The name of the planning group. Defaults to the main planning group.
Returns:
-
`str`–The name of the end effector link.
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:
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.
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.
classmethod
¤
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–
Target(
target_mode: TargetMode = None,
native_scale: float = 1.0,
name: str = "Generic Target",
)
Represents a kinematic target for motion planning.
The current implementation supports only static target constraints such as pose, configuration, and joint constraints. Dynamic targets such as velocity, acceleration, and jerk are not yet supported.
Targets are intended to be used for motion planning with a planning backend
by using the planner's plan_motion method.
Note that different backends support different types of targets.
Attributes:
-
name–A human-readable name for identifying the target.
-
target_mode–The target mode specifies which link or frame is referenced when specifying a target. This attribute is optional in this base class because some child classes (e.g: ConfigurationTarget) do not require it. See
TargetModefor more details. -
native_scale–The native scale factor of the target frames defined as
user_object_value * native_scale = meter_object_value. In another words,input_frame.scale(native_scale)will convert the input frame to meter units. For example, if the target is modeled in a millimeters environment,native_scaleshould be set to'0.001'. Default is'1.0'.
See Also
PointAxisTarget
FrameTarget
ConfigurationTarget
ConstraintSetTarget
Methods:¤
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.
classmethod
¤
Construct an object of this type from the provided data.
Parameters:
-
data(dict) –The data dictionary.
Returns:
-
class:`compas.data.Data`–An instance of this object type if the data contained in the dict has the correct schema.
classmethod
¤
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.
classmethod
¤
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.
classmethod
¤
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.
Convert the target into meter scale if native_scale is not 1.0.
Because all robots and planners in compas_fab use meters as the default unit of measure,
user targets that are created in other units (e.g. millimeters) will have a native_scale
factor such as 0.001 for millimeters.
This function convert the target and its tolerance into meters scale
and setting the native_scale attribute to 1.0.
Notes
This function will modify the target in place. It can only be called once because the target will be in meters scale after the first call.
normalized_to_meters() -> Target
Returns a copy of the target where the target and tolerances are scaled to meters.
Notes
copy.deepcopy is used, normalize_to_meters is then called on the copy.
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:
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.
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.
classmethod
¤
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–
Represents different matching mode for Targets and Waypoints.
Target modes represent which link or frame is referenced when specifying a target or waypoint.
For example, if a target's target_mode is TargetMode.TCF (Tool Coordinate Frame),
it means that the planner will try to move the robot, such that it's attached TCF
matches with the .frame specified in the Target or Waypoint.
Attributes:
-
ROBOT(str) –Refers to the PCF (Planner Coordinate Frame). The frame of the tip link of a planning group.
-
TOOL(str) –Refers to the TCF (Tool Coordinate Frame) of the tool attached to the robot. Typically this frame is at the tool tip of the tool. A tool must be attached to the robot to use this.
-
WORKPIECE(str) –Refers to the frame of the workpiece (
RigidBody) attached to the robot. There must be one and only one workpiece attached to the robot when using this mode.
Notes
The term workpiece refers to the RigidBody attached to a tool.
When using the WORKPIECE mode, the user must ensure that only one workpiece is attached to the robot.
Otherwise, it is not possible for compas_fab to determine which workpiece is being referred to.
If the user has multiple workpieces, they should use the TOOL mode instead.
A collection of built-in tools that can be used for testing and demonstration. The compas_robots.ToolModel objects created by the factory methods can be used to write examples, so that the example code can stay short.
Some of the tools are created programmatically, these usually contain simple shapes such as cones, boxes, etc. They are typically faster to load. Some of the tools are loaded from URDF, SRDF and local mesh files, similar to the robots. This is possible because ToolModel is a subclass of RobotModel and can be loaded in the same way. Some of these tools also have a different visual and collision mesh.
Some of the tools have a kinematic chain, which is used to represent shape-changing tools such as a gripper with jaws.
These are referred to kinematic tools in the compas_fab library.
The kinematic chain is represented similar to a RobotModel. The configuration of the kinematic chain can be described
in the context of a RobotCell using ToolState objects in RobotCellState.tool_states.
All the tools are modelled following ROS REP 199 recommendations, where the tool's base frame is attached to the link named 'flange' in the RobotModel. The 'flange' link frame must have its Positive X (x+) point away from the last link.
Note that this convention is present in many of Robots loaded from URDF files, but not all. Be aware that the 'flange' link is not necessary equal to the 'tool0' frame displayed on the robot controller, the orientation of the 'tool0' frame is robot-brand-dependent. The rationale of using a consistent 'flange' frame is that any tool can be attached to any robot interchangeably without additional rotations to align the tool model and the robot flange.
Examples:
Methods:¤
classmethod
¤
Create and return a cone as ToolModel, useful for simulating a drawing tool.
The cone points towards the positive X-axis of the tool frame. The tool has only one visual mesh, which is also used for collision mesh.
The tool TCF is located at the tip of the cone, it is a translation offset from T0CF by its length (default 0.1) along the X-axis of the T0CF. The tool name is 'cone'.
Parameters:
-
load_geometry(bool, default:True) –Default is
True, which means that the geometry is loaded.Falsecan be used to speed up the creation of the tool. -
radius(float, default:0.02) –Default is
0.02, which means that the radius of the cone is 2cm. -
length(float, default:0.1) –Default is
0.1, which means that the length of the cone is 10cm.
Returns:
-
[`ToolModel`][compas_fab.robots.ToolModel]–Newly created instance of the tool.
classmethod
¤
Create and return a kinematic gripper ToolModel, useful for simulating a gripper with jaws.
The gripper is 0.05m (5cm) thick from base to its gripping face.
The tool has a total of three links representing the gripper body 'body'
and the two jaws left_finger and right_finger.
The gripper has two movable fingers that are 0.1m (10cm) long.
The fingers can be moved by changing the tool's configuration.
They are represented by two joints 'left_finger_joint' and 'right_finger_joint' each with limits [0.0, 0.025].
The closed state has a position [0,0], and the fingers are 0.05m (5cm) apart.
The open state has a position [0.025, 0.025], and the fingers are 0.1m (10cm) apart.
The tool has the same visual and collision mesh. The tool's TCF is located at the tip of the gripper fingers, which is a translation offset from T0CF by +0.15 along the X-axis of the T0CF. The tool name is 'gripper'. Bar material can be held with the gripper if the long axis of the bar matches the Z axis of the TCF.
Parameters:
-
load_geometry(bool, default:True) –Default is
True, which means that the geometry is loaded.Falsecan be used to speed up the creation of the tool.
Returns:
-
[`ToolModel`][compas_fab.robots.ToolModel]–Newly created instance of the tool.
classmethod
¤
Create and return a printing tool as ToolModel, useful for simulating a 3D printing tool.
The Tool Frame is located at the tip of the tool,
equal to Frame([0.2, 0.0, 1.0], [1.0, 0.0, 0.0], [0.0, 1.0, 0.0]).
It has the same orientation as its base frame.
Its Z-axis points out of the printing nozzle into the material being printed.
Therefor, the printing targets should be defined with the Z-axis pointing towards the object being printed.
The tool name is 'printing_tool'.
Changing the tool_size parameter will scale the tool.
The default size is 1.0, corresponding to the tool tip being 1m away (Z-direction) from the base frame.
Parameters:
classmethod
¤
Create and return a static gripper ToolModel, useful for simulating a gripper.
The gripper is 0.1m (10cm) thick from base to its gripping face. The gripper has two jaws that have an opening width of 0.2m (20cm). The tool has three visual meshes representing the gripper body and the jaws. The visual mesh is also used for collision mesh. The tool TCF is located at the gripper face of the gripper, it is a translation offset from T0CF by +0.1 along the X-axis of the T0CF. The tool name is 'gripper'. Bar material can be held with the gripper with the long axis matching the Z axis of the TCF.
Parameters:
-
load_geometry(bool, default:True) –Default is
True, which means that the geometry is loaded.Falsecan be used to speed up the creation of the tool.
Returns:
-
[`ToolModel`][compas_fab.robots.ToolModel]–Newly created instance of the tool.
classmethod
¤
Create and return a static gripper ToolModel, useful for simulating a gripper.
The gripper is 0.05m (5cm) thick from base to its gripping face. The gripper has two jaws that have an opening width of 0.05m (5cm). The tool has three visual meshes representing the gripper body and the jaws. The visual mesh is also used for collision mesh. The tool TCF is located at the gripper face of the gripper, it is a translation offset from T0CF by +0.1 along the X-axis of the T0CF. The tool name is 'gripper'. Bar material can be held with the gripper with the long axis matching the Z axis of the TCF.
Parameters:
-
load_geometry(bool, default:True) –Default is
True, which means that the geometry is loaded.Falsecan be used to speed up the creation of the tool.
Returns:
-
[`ToolModel`][compas_fab.robots.ToolModel]–Newly created instance of the tool.
ToolState(
frame: Frame | Transformation,
attached_to_group: str | None = None,
touch_links: list[str] | None = None,
attachment_frame: Frame | Transformation | None = None,
configuration: Configuration | None = None,
is_hidden: bool = False,
)
Represents the state of a tool in a RobotCell.
When representing a tool that is attached to a robot, the attached_to_group
attributes should be set to the planning group name and the frame attribute
is set to 'None'.
Note that the tool's base frame is attached without any offset to the end of
that planning group, this behavior is fixed.
When representing a tool that is kinematic (a ToolModel with movable joints), the
configuration attribute should be set. Otherwise, if left at None, the tool's
configuration will be assumed to be at its zero configuration.
Note that the attachment location of workpieces (RigidBody) to the tool cannot
and will not be changed by the tool's configuration.
Attributes:
-
frame–The base frame of the tool relative to the world coordinate frame. If the tool is attached to a planning group, this frame can be set to None.' In that case, the planner or visualization tool will use the end frame of the planning group.
-
attached_to_group–The name of the robot planning group to which the tool is attached. Defaults to
None. -
attachment_frame–The frame of the tool relative to the frame of the attached link. Defaults to
None. -
touch_links–The names of the robot links that are allowed to collide with the tool.
-
configuration–The configuration of the tool if the tool is kinematic. Defaults to
None. -
is_hidden–Whether the tool is hidden in the scene. Collision checking will be turned off for hidden objects. Defaults to
False.
Methods:¤
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.
classmethod
¤
Construct an object of this type from the provided data.
Parameters:
-
data(dict) –The data dictionary.
Returns:
-
class:`compas.data.Data`–An instance of this object type if the data contained in the dict has the correct schema.
classmethod
¤
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.
classmethod
¤
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.
classmethod
¤
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.
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:
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.
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.
classmethod
¤
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–
Base trajectory class.
Attributes:
-
planning_time–Amount of time it took to complete the motion plan, in seconds. Defaults to
-1when the backend did not report it. -
attributes–Custom attributes of the trajectory.
Methods:¤
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.
classmethod
¤
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.
classmethod
¤
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.
classmethod
¤
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.
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:
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.
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.
classmethod
¤
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–
Waypoints(
target_mode: TargetMode = None,
native_scale: float = 1.0,
name: str = "Generic Waypoints",
)
Represents a sequence of kinematic target for motion planning.
Waypoints represent a sequence of targets the robot should pass through in the order they are defined.
This is in contrast to Target which represent only a single target.
The initial (starting) point should not be included in the waypoints list.
It is valid for a Waypoints object to have one target.
Waypoints are useful for tasks like painting, welding, or 3D printing, where the programmer wants to define the waypoints the robot should pass through.
Waypoints are intended to be used for motion planning with a planning backend by using the planner's plan_cartesian_motion method.
Note that different backends support different types of waypoints.
The method of interpolation between the waypoints is controlled by the motion planner backend.
Attributes:
-
target_mode–The target mode specifies which link or frame is referenced when specifying a target. See
TargetModefor more details. -
native_scale–The native scale factor of the waypoint targets defined as
user_object_value * native_scale = meter_object_value. In another words,input_frame.scale(native_scale)will convert the input frame to meter units. For example, if the target is modeled in a millimeters environment,native_scaleshould be set to'0.001'. Default is'1.0'. -
name–A human-readable name for identifying the target.
See Also
PointAxisWaypoints
FrameWaypoints
Methods:¤
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.
classmethod
¤
Construct an object of this type from the provided data.
Parameters:
-
data(dict) –The data dictionary.
Returns:
-
class:`compas.data.Data`–An instance of this object type if the data contained in the dict has the correct schema.
classmethod
¤
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.
classmethod
¤
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.
classmethod
¤
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.
Convert the target into meter scale if native_scale is not 1.0.
Because all robots and planners in compas_fab use meters as the default unit of measure,
user targets that are created in other units (e.g. millimeters) will have a native_scale
factor such as 0.001 for millimeters.
This function convert the target and its tolerance into meters scale
and setting the native_scale attribute to 1.0.
Notes
This function will modify the target in place. It can only be called once because the target will be in meters scale after the first call.
normalized_to_meters() -> Target
Returns a copy of the target where the target and tolerances are scaled to meters.
Notes
copy.deepcopy is used, normalize_to_meters is then called on the copy.
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:
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.
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.
classmethod
¤
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–
A wrench represents force in free space, separated into its linear (force) and angular (torque) parts.
Attributes:
-
force(Vector) –[Fx, Fy, Fz] force vector in Newtons
-
torque(Vector) –[Tx, Ty, Tz] moments vector in Newton-meters
Examples:
>>> from compas.geometry import Vector
>>> w = Wrench([1, 2, 3], [0.1, 0.2, 0.3])
>>> w = Wrench(Vector(1, 2, 3), Vector(0.1, 0.2, 0.3))
Attributes¤
property
¤
Methods:¤
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.
classmethod
¤
Construct an object of this type from the provided data.
Parameters:
-
data(dict) –The data dictionary.
Returns:
-
class:`compas.data.Data`–An instance of this object type if the data contained in the dict has the correct schema.
classmethod
¤
classmethod
¤
classmethod
¤
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.
classmethod
¤
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.
classmethod
¤
Removes the force and torque in effect of gravity from the wrench.
Parameters:
-
ft_sensor_frame(Frame) –The coordinate frame of the force torque sensor.
-
mass(float) –The mass of the object in kg.
-
center_of_mass(Point) –The center of mass of the object in meters.
Returns:
-
Wrench–The gravity compensated wrench.
Examples:
>>> mass, com = 10, [0, 0, 1]
>>> f = Frame([0, 0, 0], [1, 0, 0], [0, 1, 0])
>>> w = Wrench([0, 0, -98], [0, 0, 0])
>>> x = w.gravity_compensated(f, mass, com)
>>> print(x.force)
Vector(x=0.000, y=0.000, z=0.066)
>>> print(x.torque)
Vector(x=0.000, y=0.000, z=0.000)
>>> mass, com = 10, [1, 1, 1]
>>> f = Frame([0, 0, 0], [1, 0, 0], [0, 1, 0])
>>> w = Wrench([0, 0, -98], [-98, 98, 0])
>>> x = w.gravity_compensated(f, mass, com)
>>> print(x.force)
Vector(x=0.000, y=0.000, z=0.066)
>>> print(x.torque)
Vector(x=-88.193, y=88.193, z=0.000)
Notes
For more info, see [1]_.
References
.. [1] Vougioukas S., Bias Estimation and Gravity Compensation For Force-Torque Sensors, Available at: https://www.semanticscholar.org/paper/Bias-Estimation-and-Gravity-Compensation-For-Vougioukas/900c5de4ac54cf28df816584264fa0de71c4817f
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:
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.
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.
transform(transformation: Transformation) -> None
Transforms a Wrench with the transformation.
Parameters:
-
transformation(Transformation) –The transformation to transform the
Wrench.
Returns:
-
None–
Examples:
transformed(transformation: Transformation) -> Wrench
Returns a transformed copy of the Wrench.
Parameters:
-
transformation(Transformation) –The transformation to transform the
Wrench.
Returns:
-
Wrench–The transformed wrench.
Examples:
classmethod
¤
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–