magnebot 2.2.10

High-level API for the Magnebot in TDW.

Magnebot

Magnebot is a high-level robotics-like API for 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.

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.

Requirements

See TDW requirements.

Installation

1. pip3 install magnebot
2. (Linux servers only): Download the latest TDW build and unzip it. For more information on setting up a TDW build on a server, read this. On a personal computer, the build will be downloaded and launched automatically.

Test if your installation was successful

1. Run this controller:

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. 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 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
• Core Concepts
• Objects and scenes
• Robots
• Multi-agent simulations

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 show actual examples for an actual use-case.

Other controllers in this repo:

• Promo controllers 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 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.

API	Description
Transport Challenge	Transport objects from room to room using containers as tools.
Multimodal Challenge	Perceive objects in the scene using visual and audio input.