# Magnebot
Magnebot is a high-level robotics-like API for [TDW](https://github.com/threedworld-mit/tdw). The Magnebot can move around the scene and manipulate objects by picking them up with "magnets". The simulation is entirely driven by physics.
The Magnebot can be loaded into a [wide variety of scenes populated by interactable objects](https://github.com/alters-mit/magnebot/tree/main/doc/images/floorplans).
At a low level, the Magnebot is driven by robotics commands such as set_revolute_target, which will turn a revolute drive. The high-level API combines the low-level commands into "actions", such as `grasp(target_object)` or `move_by(distance)`.
The Magnebot API supports both single-agent and multi-agent simulations.
<img src="https://github.com/alters-mit/magnebot/raw/main/social.jpg" />
# Requirements
See [TDW requirements](https://github.com/threedworld-mit/tdw/blob/master/Documentation/lessons/setup/install.md).
# Installation
1. **`pip3 install magnebot`**
2. (Linux servers only): [Download the latest TDW build](https://github.com/threedworld-mit/tdw/releases/latest) and unzip it. For more information on setting up a TDW build on a server, [read this](https://github.com/threedworld-mit/tdw/blob/master/Documentation/lessons/setup/install.md). On a personal computer, the build will be downloaded and launched automatically.
#### Test if your installation was successful
1. Run this controller:
```python
from magnebot import MagnebotController
c = MagnebotController() # On a server, change this to MagnebotController(launch_build=False)
c.init_scene()
c.move_by(2)
print(c.magnebot.dynamic.transform.position)
c.end()
```
2. (Linux servers only): [Launch the TDW build.](https://github.com/threedworld-mit/tdw/blob/master/Documentation/lessons/core_concepts/launch_build.md) On a personal computer, the build will launch automatically.
#### Update an existing installation
1. `pip3 install tdw -U`
2. `pip3 install magnebot -U`
3. (Linux servers only): [Download the latest TDW build](https://github.com/threedworld-mit/tdw/releases/latest) and unzip it. On a personal computer, the build will automatically be upgraded the next time you create a TDW controller.
**If you are upgrading from Magnebot 1.3.2 or earlier, be aware that there are many changes to the API in Magnebot 2.0.0 and newer. [Read the changelog for more information.][https://github.com/alters-mit/magnebot/blob/main/doc/changelog.md]**
# Manual
## General
- [Changelog][https://github.com/alters-mit/magnebot/blob/main/doc/changelog.md]
- [Troubleshooting and debugging][https://github.com/alters-mit/magnebot/blob/main/doc/troubleshooting.md]
- [Performance benchmark][https://github.com/alters-mit/magnebot/blob/main/doc/benchmark.md]
## TDW Documentation
Before using Magnebot, we recommend you read TDW's documentation to familiarize yourself with some of the underlying concepts in this API:
- [Setup](https://github.com/threedworld-mit/tdw/blob/master/Documentation/lessons/setup/install.md)
- [Core Concepts](https://github.com/threedworld-mit/tdw/blob/master/Documentation/lessons/core_concepts/controller.md)
- [Objects and scenes](https://github.com/threedworld-mit/tdw/blob/master/Documentation/lessons/objects_and_scenes/overview.md)
- [Robots](https://github.com/threedworld-mit/tdw/blob/master/Documentation/lessons/robots/overview.md)
- [Multi-agent simulations](https://github.com/threedworld-mit/tdw/blob/master/Documentation/lessons/multi_agent/overview.md)
## `MagnebotController` (single-agent, high-level API)
The [`MagnebotController`][https://github.com/alters-mit/magnebot/blob/main/doc/api/magnebot_controller.md] offers a simplified API for single-agent simulations. Actions are non-interruptible; `self.move_by(2)` will simulate motion until the action ends (i.e. when the Magnebot has moved forward by 2 meters). This API mode has been optimized for ease of use and simulation speed.
- [Overview][https://github.com/alters-mit/magnebot/blob/main/doc/manual/magnebot_controller/overview.md]
- [Scene setup][https://github.com/alters-mit/magnebot/blob/main/doc/manual/magnebot_controller/scene_setup.md]
- [Output data][https://github.com/alters-mit/magnebot/blob/main/doc/manual/magnebot_controller/output_data.md]
- [Actions][https://github.com/alters-mit/magnebot/blob/main/doc/manual/magnebot_controller/actions.md]
- [Moving, turning, and collision detection][https://github.com/alters-mit/magnebot/blob/main/doc/manual/magnebot_controller/movement.md]
- [Arm articulation][https://github.com/alters-mit/magnebot/blob/main/doc/manual/magnebot_controller/arm_articulation.md]
- [Grasp action][https://github.com/alters-mit/magnebot/blob/main/doc/manual/magnebot_controller/grasp.md]
- [Camera rotation][https://github.com/alters-mit/magnebot/blob/main/doc/manual/magnebot_controller/camera_rotation.md]
- [Third-person cameras][https://github.com/alters-mit/magnebot/blob/main/doc/manual/magnebot_controller/third_person_camera.md]
- [Occupancy maps][https://github.com/alters-mit/magnebot/blob/main/doc/manual/magnebot_controller/occupancy_map.md]
## `Magnebot` (*n*-agent, lower-level API)
[`Magnebot`][https://github.com/alters-mit/magnebot/blob/main/doc/api/magnebot.md] is a TDW add-on that must be added to a TDW controller to be usable. `Magnebot` can be used in multi-agent simulations, but it requires a more extensive understanding of TDW than `MagnebotController`.
- [Overview][https://github.com/alters-mit/magnebot/blob/main/doc/manual/magnebot/overview.md]
- [Scene setup][https://github.com/alters-mit/magnebot/blob/main/doc/manual/magnebot/scene_setup.md]
- [Output data][https://github.com/alters-mit/magnebot/blob/main/doc/manual/magnebot/output_data.md]
- [Actions][https://github.com/alters-mit/magnebot/blob/main/doc/manual/magnebot/actions.md]
- [Moving, turning, and collision detection][https://github.com/alters-mit/magnebot/blob/main/doc/manual/magnebot/movement.md]
- [Arm articulation][https://github.com/alters-mit/magnebot/blob/main/doc/manual/magnebot/arm_articulation.md]
- [Grasp action][https://github.com/alters-mit/magnebot/blob/main/doc/manual/magnebot/grasp.md]
- [Camera][https://github.com/alters-mit/magnebot/blob/main/doc/manual/magnebot/camera.md]
- [Third-person cameras][https://github.com/alters-mit/magnebot/blob/main/doc/manual/magnebot/third_person_camera.md]
- [Occupancy maps][https://github.com/alters-mit/magnebot/blob/main/doc/manual/magnebot/occupancy_map.md]
- [Multi-agent simulations][https://github.com/alters-mit/magnebot/blob/main/doc/manual/magnebot/multi_agent.md]
## Actions
It is possible to define custom Magnebot actions by extending the [`Action`][https://github.com/alters-mit/magnebot/blob/main/doc/api/actions/action.md] class.
- [Overview][https://github.com/alters-mit/magnebot/blob/main/doc/manual/actions/overview.md]
- [Move and turn actions][https://github.com/alters-mit/magnebot/blob/main/doc/manual/actions/movement.md]
- [Arm articulation actions][https://github.com/alters-mit/magnebot/blob/main/doc/manual/actions/arm_articulation.md]
- [Inverse kinematics (IK) actions][https://github.com/alters-mit/magnebot/blob/main/doc/manual/actions/ik.md]
- [Camera actions][https://github.com/alters-mit/magnebot/blob/main/doc/manual/actions/camera.md]
***
# API
- [`MagnebotController`][https://github.com/alters-mit/magnebot/blob/main/doc/api/magnebot_controller.md]
- [`Magnebot`][https://github.com/alters-mit/magnebot/blob/main/doc/api/magnebot.md]
- [Other API documentation][https://github.com/alters-mit/magnebot/blob/main/doc/api]
***
# Examples
[Example controllers](https://github.com/alters-mit/magnebot/tree/main/controllers/examples) show actual examples for an actual use-case.
Other controllers in this repo:
- [Promo controllers](https://github.com/alters-mit/magnebot/tree/main/controllers/promos) are meant to be use to generate promo videos or images; they include low-level TDW commands that you won't need to ordinarily use.
- [Test controllers](https://github.com/alters-mit/magnebot/tree/main/controllers/tests) load the Magnebot into an empty room and test basic functionality.
***
# Higher-level APIs
The Magnebot API relies on the `tdw` Python module. Every action in this API uses combinations of low-level TDW commands and output data, typically across multiple simulation steps.
This API is designed to be used as-is or as the base for an API with higher-level actions, such as the [Transport Challenge](https://github.com/alters-mit/transport_challenge).
<img src="https://raw.githubusercontent.com/alters-mit/magnebot/main/doc/images/api_hierarchy.png" style="zoom:67%;" />
| API | Description |
| ------------------------------------------------------------ | ------------------------------------------------------------ |
| [Transport Challenge](https://github.com/alters-mit/transport_challenge) | Transport objects from room to room using containers as tools. |
| [Multimodal Challenge](https://github.com/alters-mit/multimodal_challenge) | Perceive objects in the scene using visual and audio input. |
Raw data
{
"_id": null,
"home_page": "https://github.com/alters-mit/magnebot",
"name": "magnebot",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "unity simulation tdw robotics",
"author": "Esther Alter",
"author_email": "alters@mit.edu",
"download_url": "https://files.pythonhosted.org/packages/53/aa/27dda02b23785c2f43b804ef678850dbf6150e93a78c484db0f96754e39b/magnebot-2.2.10.tar.gz",
"platform": null,
"description": "# Magnebot\r\n\r\nMagnebot is a high-level robotics-like API for [TDW](https://github.com/threedworld-mit/tdw). The Magnebot can move around the scene and manipulate objects by picking them up with \"magnets\". The simulation is entirely driven by physics.\r\n\r\nThe Magnebot can be loaded into a [wide variety of scenes populated by interactable objects](https://github.com/alters-mit/magnebot/tree/main/doc/images/floorplans). \r\n\r\nAt a low level, the Magnebot is driven by robotics commands such as set_revolute_target, which will turn a revolute drive. The high-level API combines the low-level commands into \"actions\", such as `grasp(target_object)` or `move_by(distance)`.\r\n\r\nThe Magnebot API supports both single-agent and multi-agent simulations.\r\n\r\n<img src=\"https://github.com/alters-mit/magnebot/raw/main/social.jpg\" />\r\n\r\n# Requirements\r\n\r\nSee [TDW requirements](https://github.com/threedworld-mit/tdw/blob/master/Documentation/lessons/setup/install.md).\r\n\r\n# Installation \r\n\r\n1. **`pip3 install magnebot`**\r\n2. (Linux servers only): [Download the latest TDW build](https://github.com/threedworld-mit/tdw/releases/latest) and unzip it. For more information on setting up a TDW build on a server, [read this](https://github.com/threedworld-mit/tdw/blob/master/Documentation/lessons/setup/install.md). On a personal computer, the build will be downloaded and launched automatically.\r\n\r\n#### Test if your installation was successful\r\n\r\n1. Run this controller:\r\n\r\n```python\r\nfrom magnebot import MagnebotController\r\n\r\nc = MagnebotController() # On a server, change this to MagnebotController(launch_build=False)\r\n\r\nc.init_scene()\r\nc.move_by(2)\r\nprint(c.magnebot.dynamic.transform.position)\r\nc.end()\r\n```\r\n\r\n2. (Linux servers only): [Launch the TDW build.](https://github.com/threedworld-mit/tdw/blob/master/Documentation/lessons/core_concepts/launch_build.md) On a personal computer, the build will launch automatically.\r\n\r\n#### Update an existing installation\r\n\r\n1. `pip3 install tdw -U`\r\n2. `pip3 install magnebot -U`\r\n3. (Linux servers only): [Download the latest TDW build](https://github.com/threedworld-mit/tdw/releases/latest) and unzip it. On a personal computer, the build will automatically be upgraded the next time you create a TDW controller.\r\n\r\n**If you are upgrading from Magnebot 1.3.2 or earlier, be aware that there are many changes to the API in Magnebot 2.0.0 and newer. [Read the changelog for more information.][https://github.com/alters-mit/magnebot/blob/main/doc/changelog.md]**\r\n\r\n# Manual\r\n\r\n## General\r\n\r\n- [Changelog][https://github.com/alters-mit/magnebot/blob/main/doc/changelog.md]\r\n- [Troubleshooting and debugging][https://github.com/alters-mit/magnebot/blob/main/doc/troubleshooting.md]\r\n- [Performance benchmark][https://github.com/alters-mit/magnebot/blob/main/doc/benchmark.md]\r\n\r\n## TDW Documentation\r\n\r\nBefore using Magnebot, we recommend you read TDW's documentation to familiarize yourself with some of the underlying concepts in this API:\r\n\r\n- [Setup](https://github.com/threedworld-mit/tdw/blob/master/Documentation/lessons/setup/install.md)\r\n- [Core Concepts](https://github.com/threedworld-mit/tdw/blob/master/Documentation/lessons/core_concepts/controller.md)\r\n- [Objects and scenes](https://github.com/threedworld-mit/tdw/blob/master/Documentation/lessons/objects_and_scenes/overview.md)\r\n- [Robots](https://github.com/threedworld-mit/tdw/blob/master/Documentation/lessons/robots/overview.md)\r\n- [Multi-agent simulations](https://github.com/threedworld-mit/tdw/blob/master/Documentation/lessons/multi_agent/overview.md)\r\n\r\n## `MagnebotController` (single-agent, high-level API)\r\n\r\nThe [`MagnebotController`][https://github.com/alters-mit/magnebot/blob/main/doc/api/magnebot_controller.md] offers a simplified API for single-agent simulations. Actions are non-interruptible; `self.move_by(2)` will simulate motion until the action ends (i.e. when the Magnebot has moved forward by 2 meters). This API mode has been optimized for ease of use and simulation speed.\r\n\r\n- [Overview][https://github.com/alters-mit/magnebot/blob/main/doc/manual/magnebot_controller/overview.md]\r\n- [Scene setup][https://github.com/alters-mit/magnebot/blob/main/doc/manual/magnebot_controller/scene_setup.md]\r\n- [Output data][https://github.com/alters-mit/magnebot/blob/main/doc/manual/magnebot_controller/output_data.md]\r\n- [Actions][https://github.com/alters-mit/magnebot/blob/main/doc/manual/magnebot_controller/actions.md]\r\n- [Moving, turning, and collision detection][https://github.com/alters-mit/magnebot/blob/main/doc/manual/magnebot_controller/movement.md]\r\n- [Arm articulation][https://github.com/alters-mit/magnebot/blob/main/doc/manual/magnebot_controller/arm_articulation.md]\r\n- [Grasp action][https://github.com/alters-mit/magnebot/blob/main/doc/manual/magnebot_controller/grasp.md]\r\n- [Camera rotation][https://github.com/alters-mit/magnebot/blob/main/doc/manual/magnebot_controller/camera_rotation.md]\r\n- [Third-person cameras][https://github.com/alters-mit/magnebot/blob/main/doc/manual/magnebot_controller/third_person_camera.md]\r\n- [Occupancy maps][https://github.com/alters-mit/magnebot/blob/main/doc/manual/magnebot_controller/occupancy_map.md]\r\n\r\n## `Magnebot` (*n*-agent, lower-level API)\r\n\r\n[`Magnebot`][https://github.com/alters-mit/magnebot/blob/main/doc/api/magnebot.md] is a TDW add-on that must be added to a TDW controller to be usable. `Magnebot` can be used in multi-agent simulations, but it requires a more extensive understanding of TDW than `MagnebotController`.\r\n\r\n- [Overview][https://github.com/alters-mit/magnebot/blob/main/doc/manual/magnebot/overview.md]\r\n- [Scene setup][https://github.com/alters-mit/magnebot/blob/main/doc/manual/magnebot/scene_setup.md]\r\n- [Output data][https://github.com/alters-mit/magnebot/blob/main/doc/manual/magnebot/output_data.md]\r\n- [Actions][https://github.com/alters-mit/magnebot/blob/main/doc/manual/magnebot/actions.md]\r\n- [Moving, turning, and collision detection][https://github.com/alters-mit/magnebot/blob/main/doc/manual/magnebot/movement.md]\r\n- [Arm articulation][https://github.com/alters-mit/magnebot/blob/main/doc/manual/magnebot/arm_articulation.md]\r\n- [Grasp action][https://github.com/alters-mit/magnebot/blob/main/doc/manual/magnebot/grasp.md]\r\n- [Camera][https://github.com/alters-mit/magnebot/blob/main/doc/manual/magnebot/camera.md]\r\n- [Third-person cameras][https://github.com/alters-mit/magnebot/blob/main/doc/manual/magnebot/third_person_camera.md]\r\n- [Occupancy maps][https://github.com/alters-mit/magnebot/blob/main/doc/manual/magnebot/occupancy_map.md]\r\n- [Multi-agent simulations][https://github.com/alters-mit/magnebot/blob/main/doc/manual/magnebot/multi_agent.md]\r\n\r\n## Actions\r\n\r\nIt is possible to define custom Magnebot actions by extending the [`Action`][https://github.com/alters-mit/magnebot/blob/main/doc/api/actions/action.md] class.\r\n\r\n- [Overview][https://github.com/alters-mit/magnebot/blob/main/doc/manual/actions/overview.md]\r\n- [Move and turn actions][https://github.com/alters-mit/magnebot/blob/main/doc/manual/actions/movement.md]\r\n- [Arm articulation actions][https://github.com/alters-mit/magnebot/blob/main/doc/manual/actions/arm_articulation.md]\r\n- [Inverse kinematics (IK) actions][https://github.com/alters-mit/magnebot/blob/main/doc/manual/actions/ik.md]\r\n- [Camera actions][https://github.com/alters-mit/magnebot/blob/main/doc/manual/actions/camera.md]\r\n\r\n***\r\n\r\n# API\r\n\r\n- [`MagnebotController`][https://github.com/alters-mit/magnebot/blob/main/doc/api/magnebot_controller.md]\r\n- [`Magnebot`][https://github.com/alters-mit/magnebot/blob/main/doc/api/magnebot.md]\r\n- [Other API documentation][https://github.com/alters-mit/magnebot/blob/main/doc/api]\r\n\r\n***\r\n\r\n# Examples\r\n\r\n[Example controllers](https://github.com/alters-mit/magnebot/tree/main/controllers/examples) show actual examples for an actual use-case.\r\n\r\nOther controllers in this repo:\r\n\r\n- [Promo controllers](https://github.com/alters-mit/magnebot/tree/main/controllers/promos) are meant to be use to generate promo videos or images; they include low-level TDW commands that you won't need to ordinarily use.\r\n- [Test controllers](https://github.com/alters-mit/magnebot/tree/main/controllers/tests) load the Magnebot into an empty room and test basic functionality.\r\n\r\n***\r\n\r\n# Higher-level APIs\r\n\r\nThe Magnebot API relies on the `tdw` Python module. Every action in this API uses combinations of low-level TDW commands and output data, typically across multiple simulation steps.\r\n\r\nThis API is designed to be used as-is or as the base for an API with higher-level actions, such as the [Transport Challenge](https://github.com/alters-mit/transport_challenge). \r\n\r\n<img src=\"https://raw.githubusercontent.com/alters-mit/magnebot/main/doc/images/api_hierarchy.png\" style=\"zoom:67%;\" />\r\n\r\n| API | Description |\r\n| ------------------------------------------------------------ | ------------------------------------------------------------ |\r\n| [Transport Challenge](https://github.com/alters-mit/transport_challenge) | Transport objects from room to room using containers as tools. |\r\n| [Multimodal Challenge](https://github.com/alters-mit/multimodal_challenge) | Perceive objects in the scene using visual and audio input. |\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "High-level API for the Magnebot in TDW.",
"version": "2.2.10",
"project_urls": {
"Homepage": "https://github.com/alters-mit/magnebot"
},
"split_keywords": [
"unity",
"simulation",
"tdw",
"robotics"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "53aa27dda02b23785c2f43b804ef678850dbf6150e93a78c484db0f96754e39b",
"md5": "235774632857d7ae93df498be906d40d",
"sha256": "af3dec282e4737038540ffeaa3f40b05065c660ee4e25e70b25e2830e1a97975"
},
"downloads": -1,
"filename": "magnebot-2.2.10.tar.gz",
"has_sig": false,
"md5_digest": "235774632857d7ae93df498be906d40d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 264945,
"upload_time": "2024-01-09T14:37:20",
"upload_time_iso_8601": "2024-01-09T14:37:20.421751Z",
"url": "https://files.pythonhosted.org/packages/53/aa/27dda02b23785c2f43b804ef678850dbf6150e93a78c484db0f96754e39b/magnebot-2.2.10.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-09 14:37:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "alters-mit",
"github_project": "magnebot",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "magnebot"
}
JSON
