# Overview
`geometry.py` provides primitives for dealing with scene and robot geometry.
## Main Concepts
### Geometrical types
* `Pose`: The 6D position and orientation of a body. Construction methods:
```python
Pose(position=[x, y, z], quaternion=[w, i, j, k])
Pose.from_hmat(homogeneous_matrix)
Pose.from_poseuler(poseuler=[x,y,z, p,r,w], ordering="XYZ")
```
* `Wrench` and `WrenchStamped` 6D force-torque.
* `Twist` and `TwistStamped` 6D velocity.
* `Accel` and `AccelStamped` 6D acceleration.
For debugging and visualization, `Pose` and `PoseStamped` objects can be
constructed with a `name` parameter.
### Frames and Stamped types
All quantities here come in plain and 'Stamped' varieties. A stamped quantity
(E.g. `TwistStamped`) is always defined as a plain type (E.g. `Twist`) with
respect to a `frame`. A `frame` is something that can be evaluated
to a world-pose -- either a `PoseStamped` or a `Grounding`. A grounding is
optional (i.e. can use None to indicate world-frame). This library supports
different grounding back-ends, e.g. mujoco-elements or observation-dicts.
For example, the pose of a plug in a robot gripper could be expressed as a
`PoseStamped` with a combination of the `Pose` of the gripper in world frame
and the pose of the plug with respect to the gripper.
A frame for a stamped quantity can be:
* Another stamped quantity,
* A "grounding" (a user chosen type).
* A user supplied `Physics` instance must be able to provide the world
`Pose` of a grounding. The library defined `MujocoPhysics` does this
for `mjcf.Element` instances.
* `None`, in which case, world frame is assumed.
Therefore in the above example, the first quantity might come from a mujoco
model (possibly synchronized with the real world), and the second quantity
might be known a priori or estimated by vision.
```python
gripper_in_world = PoseStamped(pose=None, frame=synced_gripper_mjcf_body)
plug_in_gripper = Pose(...) # From vision pose model.
plug_pose = PoseStamped(plug_in_gripper, frame=gripper_in_world)
```
(A more realistic example would have the pose of the plug in the *camera* frame
then either having the camera in the kinematic tree of the robot (attached to
the robot) or having it and the robot in world frame)
Then the pose of the *plug* in the *world* frame can be calculated as:
```python
plug_in_world: Pose = plug_pose.get_world_pose()
```
### Immutability
All types in `geometry.py` are immutable. You can create modified copies of
existing values with the `replace` and `with_*` methods. `replace` is similar in
spirit to `collections.namedtuple._replace`, these methods return new objects.
### PoseStamped
This is the stamped version of a Pose.
* Its frame hierarchy can be flattened with `to_world`, which returns a
`PoseStamped` in world frame.
* The `Pose` relative to another frame is returned from `get_relative_pose`.
* The `Pose` relative to the world frame is returned from `get_world_pose`.
So, in the case of a gripper in camera frame which is not attached to the robot,
we could `to_world()` either the gripper or plug `PoseStamped`, giving a new
frame and then calculate thier relative pose (plug relative to robot) with
`get_relative_pose`.
### HybridPoseStamped
A `PoseStamped` where the position or orientation can be overriden. This is
useful to express the idea of (for example) the position of the gripper with
world orientation to allow for more intuitive operator control of the gripper.
Raw data
{
"_id": null,
"home_page": "https://github.com/deepmind/dm_robotics/tree/main/py/geometry",
"name": "dm-robotics-geometry",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.7",
"maintainer_email": null,
"keywords": null,
"author": "DeepMind",
"author_email": null,
"download_url": null,
"platform": null,
"description": "# Overview\n\n`geometry.py` provides primitives for dealing with scene and robot geometry.\n\n## Main Concepts\n\n### Geometrical types\n\n* `Pose`: The 6D position and orientation of a body. Construction methods:\n\n ```python\n Pose(position=[x, y, z], quaternion=[w, i, j, k])\n Pose.from_hmat(homogeneous_matrix)\n Pose.from_poseuler(poseuler=[x,y,z, p,r,w], ordering=\"XYZ\")\n ```\n* `Wrench` and `WrenchStamped` 6D force-torque.\n* `Twist` and `TwistStamped` 6D velocity.\n* `Accel` and `AccelStamped` 6D acceleration.\n\nFor debugging and visualization, `Pose` and `PoseStamped` objects can be\nconstructed with a `name` parameter.\n\n### Frames and Stamped types\n\nAll quantities here come in plain and 'Stamped' varieties. A stamped quantity\n(E.g. `TwistStamped`) is always defined as a plain type (E.g. `Twist`) with\nrespect to a `frame`. A `frame` is something that can be evaluated\nto a world-pose -- either a `PoseStamped` or a `Grounding`. A grounding is \noptional (i.e. can use None to indicate world-frame). This library supports\ndifferent grounding back-ends, e.g. mujoco-elements or observation-dicts.\n\nFor example, the pose of a plug in a robot gripper could be expressed as a\n`PoseStamped` with a combination of the `Pose` of the gripper in world frame\nand the pose of the plug with respect to the gripper.\n\nA frame for a stamped quantity can be:\n\n* Another stamped quantity,\n* A \"grounding\" (a user chosen type).\n * A user supplied `Physics` instance must be able to provide the world\n `Pose` of a grounding. The library defined `MujocoPhysics` does this\n for `mjcf.Element` instances.\n* `None`, in which case, world frame is assumed.\n\nTherefore in the above example, the first quantity might come from a mujoco\nmodel (possibly synchronized with the real world), and the second quantity\nmight be known a priori or estimated by vision.\n\n```python\ngripper_in_world = PoseStamped(pose=None, frame=synced_gripper_mjcf_body)\nplug_in_gripper = Pose(...) # From vision pose model.\nplug_pose = PoseStamped(plug_in_gripper, frame=gripper_in_world)\n```\n\n(A more realistic example would have the pose of the plug in the *camera* frame\nthen either having the camera in the kinematic tree of the robot (attached to\nthe robot) or having it and the robot in world frame)\n\nThen the pose of the *plug* in the *world* frame can be calculated as:\n\n```python\nplug_in_world: Pose = plug_pose.get_world_pose()\n```\n\n### Immutability\n\nAll types in `geometry.py` are immutable. You can create modified copies of\nexisting values with the `replace` and `with_*` methods. `replace` is similar in\nspirit to `collections.namedtuple._replace`, these methods return new objects.\n\n### PoseStamped\n\nThis is the stamped version of a Pose.\n\n* Its frame hierarchy can be flattened with `to_world`, which returns a\n `PoseStamped` in world frame.\n* The `Pose` relative to another frame is returned from `get_relative_pose`.\n* The `Pose` relative to the world frame is returned from `get_world_pose`.\n\nSo, in the case of a gripper in camera frame which is not attached to the robot,\nwe could `to_world()` either the gripper or plug `PoseStamped`, giving a new\nframe and then calculate thier relative pose (plug relative to robot) with\n`get_relative_pose`.\n\n### HybridPoseStamped\n\nA `PoseStamped` where the position or orientation can be overriden. This is\nuseful to express the idea of (for example) the position of the gripper with\nworld orientation to allow for more intuitive operator control of the gripper.\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "This library provides primitives for dealing with scene and robot geometry",
"version": "0.8.1",
"project_urls": {
"Homepage": "https://github.com/deepmind/dm_robotics/tree/main/py/geometry"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a09402f79421131ddc3e83f157a766b7e4abd2cbf21078aa520a46dafbb433d6",
"md5": "fe4b32b74b2a5408d12af15fcebb5aef",
"sha256": "b764ded6528c62f757f404a9142c7e064282261b48933ba3f09bc9382dc7f106"
},
"downloads": -1,
"filename": "dm_robotics_geometry-0.8.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fe4b32b74b2a5408d12af15fcebb5aef",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.7",
"size": 29377,
"upload_time": "2024-06-20T10:34:08",
"upload_time_iso_8601": "2024-06-20T10:34:08.280541Z",
"url": "https://files.pythonhosted.org/packages/a0/94/02f79421131ddc3e83f157a766b7e4abd2cbf21078aa520a46dafbb433d6/dm_robotics_geometry-0.8.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-20 10:34:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "deepmind",
"github_project": "dm_robotics",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "dm-robotics-geometry"
}
JSON
