Skip to content

Latest commit

 

History

History
263 lines (178 loc) · 8.96 KB

robot_librarian.md

File metadata and controls

263 lines (178 loc) · 8.96 KB

Robot Librarian

A Robot Librarian is a robot records database.

Default Libraries

There is only one robot library: robots.json. You can define it explicitly, or not.

from tdw.librarian import RobotLibrarian

# These constructors will load the same records database.
lib = RobotLibrarian()
lib = RobotLibrarian(library="robots.json")

# Get the names of all records in the library.
for record in lib.records:
    print(record.name)

Command API

Send the add_robot command to add a robot to the scene or use the wrapper function Controller.get_add_robot():

from platform import system
from tdw.backend.platforms import SYSTEM_TO_S3
from tdw.controller import Controller
from tdw.tdw_utils import TDWUtils

if __name__ == "__main__":
    c = Controller(launch_build=False)
    c.start()
    
    commands = [TDWUtils.create_empty_room(12, 12)]
    
    # Add a robot to the scene.
    commands.append({"$type": "add_robot",
                     "id": 0,
                     "position": {"x": 1, "y": 0, "z": 0},
                     "rotation": 0,
                     "name": "ur3",
                     "url": f"https://tdw-public.s3.amazonaws.com/robots/{SYSTEM_TO_S3[system()]}/2020.2/ur3"})
    # This is identical to the `add_robot` command, but uses a simpler wrapper function.
    commands.append(c.get_add_robot(name="ur3",
                                    robot_id=1,
                                    position={"x": -1, "y": 0, "z": 0},
                                    rotation=0))
    c.communicate(commands)

RobotRecord API

A record of a robot asset bundle.

from tdw.librarian import RobotRecord

record = RobotRecord() # Creates a record with blank or default values.
from tdw.librarian import RobotRecord

record = RobotRecord(data=data) # Creates a record from JSON data.

Fields

Field Type Description
name str The name of the robot.
urls Dict[str, str] A dictionary of URLs or local filepaths of asset bundles per platform. See: RobotRecord.get_url()
source str The source URL of the robot model or .urdf file.
immovable bool If true, the base of the robot is immovable and can't change position once added to the scene.
targets dict A dictionary of "canonical" joint targets to set a pose such that none of the joints are intersecting with the floor, assuming that the robot's starting position is (0, 0, 0). Key = The name of the joint. Value = A dictionary: "type" is the type of joint ("revolute", "prismatic", "sphereical") and "target" is the target angle or position.
ik list A list of joint link chains that can be used for inverse kinematics (IK).

Functions

def get_url(self) -> str:

Returns the URL of the asset bundle for this platform. This is a wrapper for record.urls.

lib = RobotLibrarian()
record = lib.records[0]

print(record.get_url())

RobotLibrarian API

Fields

Field Type Description
library str The path to the records database file.
data dict The raw JSON dictionary loaded from the records database file.
description str A brief description of the library.
records List[RobotRecord] The list of robot records.

Static Functions

def create_library(description: str, path: str) -> None:

Create a new library JSON file.

RobotRecord.create_library("My library", path="path/to/new/library.json")
Parameter Type Description
description str A description of the library.
path str The absolute filepath to the .json records database file.
def get_library_filenames() -> List[str]:

Returns a list of the filenames of the libraries of this type in the tdw module.

filenames = RobotLibrarian.get_library_filenames()

print(filenames) # ['robots.json']
def get_default_library() -> List[str]:

Returns the filename of the default library (which is always the first element in the list returned by get_library_filenames().

default_library = RobotLibrarian.get_default_library()

print(default_library) # robots.json

Functions

def get_record(self, name: str) -> Optional[RobotRecord]:

Returns a record with the specified name. If that record can't be found, returns None.

lib = RobotLibrarian()
record = lib.get_record("ur3")

print(record.name) # ur3
Parameter Type Description
name str The name of the record.
def search_records(self, search: str) -> List[RobotRecord]:

Returns a list of records whose names include the search keyword.

lib = RobotLibrarian()
records = lib.search_records("ur3")

for record in records:
    print(record.name) # ur3
Parameter Type Description
search str The string to search for in the robot name.
def add_or_update_record(self, record: RobotRecord, overwrite: bool, write bool = True, quiet: bool = True) -> bool:

Add a new record or update an existing record.

record = define_record() # Provide your own code here.
lib = RobotLibrarian()

lib.add_or_update_record(record, False, write=True, quiet=False)
Parameter Type Description
record RobotRecord The new or modified record.
overwrite bool If True: If there is a record with the same name as this record, replace it with the new record and return True. Otherwise, return False.
If False: If there is a record with the same name as this record, don't add the robot, and suggest a new name.
write bool If true, write the library data to disk (overwriting the existing file).
quiet bool If true, don't print out messages to the console.
def remove_record(self, record: Union[str, RobotRecord], write: bool = True) -> bool:

Remove a record. Returns true if the record was removed.

record = define_record() # Provide your own code here.
lib = RobotLibrarian()

lib.remove_record(record) # Returns False.
lib = RobotLibrarian()

lib.remove_record("ur3") # Returns True.
Parameter Type Description
record RobotRecord or str The record or the name of the record.
write bool If true, write the library data to disk (overwriting the existing file).
def write(self, pretty=True) -> None:

Write the library data to disk (overwriting the existing file).

Parameter Type Description
pretty bool "Pretty print" the JSON data with line breaks and indentations.
def get_valid_record_name(self, name: str, overwrite: bool) -> Tuple[bool, str, List[str]]:

Generates a valid record name. Returns: true if the name is good as-is, the new name, and a list of problems with the old name.

lib = RobotLibrarian()

ok, name, problems = lib.get_valid_record_name("ur3", True)

print(ok) # True
print(name) # ur3
lib = RobotLibrarian()

ok, name, problems = lib.get_valid_record_name("ur3", False)

print(ok) # False
print(name) # ur3
print(problems) # ["A record named ur3 already exists, and we don't want to overwrite it."]
Parameter Type Description
name str The name of a record we'd like to add.
overwrite str If True: raise an exception if a record named name doesn't already exist.
If False: If the record exists, suggest a new name.