API Reference

`Swift`([_dev])	Graphical backend using Swift
`SwiftElement`()	A basic super class for HTML elements which can be added to Swift
`Slider`([cb, min, max, step, value, label, ...])	Create a range-slider html element
`Button`(cb[, label, desc])	Create a Button html element
`Label`([label, compact, desc])	Create a Label html element
`Select`(cb[, label, options, value, desc])	Create a Select element, used to create a drop-down list.
`Checkbox`(cb[, label, options, checked, desc])	Create a checkbox element, used to create multi-selection list.
`Radio`(cb[, label, options, checked, desc])	Create a radio element, used to create single-selection list.

Swift

@author Jesse Haviland

class swift.Swift.Swift(_dev=False)[source]

Bases: object

Graphical backend using Swift

Swift is a web app built on three.js. It supports many 3D graphical primitives including meshes, boxes, ellipsoids and lines. It can render Collada objects in full color.

Examples

import roboticstoolbox as rtb

robot = rtb.models.DH.Panda()  # create a robot

pyplot = rtb.backends.Swift()   # create a Swift backend
pyplot.add(robot)              # add the robot to the backend
robot.q = robot.qz             # set the robot configuration
pyplot.step()                  # update the backend and graphical view

property rate: int

show()[source]

Print the current display list, for debugging.

env.show() prints every object currently added to the scene (shapes, assemblies/robots, and UI elements) with its id, a repr() of the object itself, and its name if one was given via name= at add time – an assembly/robot also lists its links, indented, with their geometry/collision shape counts. The pause/realtime-speed controls _add_controls() adds to every launch() aren’t user-added UI, so they’re excluded here too.

Any named object, or any object by its id, can also be retrieved directly with env[name] / env[id] – see __getitem__().

Return type:: None

launch(realtime=False, headless=None, rate=60, browser=None, axes=True, ground_opacity=1.0, ground_pattern=False, ground_pattern_width=1.0, lights=None, timeout=1, browser_timeout=5, **kwargs)[source]

Launch the Swift Simulator

env = launch(args) create a 3D scene in a running Swift instance as defined by args, and returns a reference to the backend.

Warning

The scene’s lights are fixed in world space and never move on their own – including in response to set_camera_pose(). Moving the camera far enough from its default position can leave every camera-facing surface in shadow, since the default lights are positioned specifically to match that default camera position. Use lights=/set_lights() to reposition them to match, if needed.

timeout and browser_timeout cover two independent, opposite-direction halves of the same disconnect – worth spelling out in full, since the two are easy to mix up:

Parameter	Who is waiting	For what
`timeout`	This Python process, inside `hold()`/`run()`	The browser tab to still be there
`browser_timeout`	The browser tab (JavaScript)	This Python process to still be alive

Concretely:

Close the browser tab – timeout (default 1 second) is how long hold()/run() keep polling before giving up, printing "Swift browser tab closed.", calling close(), and returning. Actual wall-clock latency is timeout plus up to ~1 second of polling granularity – about 2 seconds with the default.
Kill this Python process (or it crashes) – browser_timeout (default 5 seconds) is how long the browser tab waits before closing itself. Python can’t run any code to reconnect a dead process, so this side needs its own, independently-configured timer running entirely in the browser.

Neither side can observe the other’s half of a disconnect directly – the browser can’t poll a dead Python process, and a killed Python process can’t run any code at all – which is why two separate parameters exist rather than one. Either can be set to None for “wait forever” on that side. See Internals for the full mechanism (threads, sockets, exactly what “the browser is gone” means internally).

Parameters:

realtime (bool | float) – Force the simulator to display no faster than real time, note that it may still run slower due to complexity. True is 1x speed; a float (e.g. 0.5) sets a specific wall-clock-per-sim-time multiplier (slow motion below 1.0); False runs uncapped.
headless (bool | None) – Do not launch the graphical front-end of the simulator. Will still simulate the robot. Runs faster due to not needing to display anything. None (default) falls back to the SWIFT_HEADLESS environment variable (headless if set to any non-empty value), then False if that’s also unset – lets a test harness or CI environment force headless mode globally without every calling script having to pass headless=True itself.
rate (int) – The rate (Hz) at which the simulator will be run, defaults to 60Hz
browser (str | None) – browser to open in: one of ‘google-chrome’, ‘chrome’, ‘firefox’, ‘safari’, ‘opera’ or see for full list https://docs.python.org/3/library/webbrowser.html#webbrowser.open_new
axes (bool) – Show the world-frame axes helper at the origin, defaults to True
ground_opacity (float) – Opacity of the ground plane, from 0 (invisible) to 1 (opaque), defaults to 1
ground_pattern (bool | str) – Repeating pattern on the ground plane. False (default) is a plain flat floor. True or "@tile" is a built-in checkerboard; "@grid" is a built-in grid. Anything else is treated as an absolute path to an image file to tile as a texture – its tile height follows the image’s own aspect ratio (never distorted); see ground_pattern_width. Whenever a pattern is active, the ground plane recentres under the camera every frame (snapped to a whole tile, so the pattern never visibly shifts) so its edge is never reachable regardless of pan/zoom – skipped entirely for the plain flat floor, which has no visible edge to begin with.
ground_pattern_width (float) – x-extent of one tile, in metres. Only meaningful when ground_pattern is set, defaults to 1.
lights (list[Light] | None) – custom scene lights, replacing Swift’s default 3-light rig entirely – there is no way to add to the defaults, only replace them outright. None (default) keeps the default rig unchanged. See set_lights() to change lights again after launch.
timeout (float | None) – how long hold() keeps waiting, in seconds, after the browser tab disconnects before giving up and returning. None means wait indefinitely (the pre-2.1 behaviour), defaults to 1
browser_timeout (float | None) – how long the browser tab waits, in seconds, after losing its connection to this process before closing itself. None means never auto-close, defaults to 5. Independent of timeout – this fires browser-side, so it still applies if this process is killed outright rather than exiting through hold(). Only takes effect on a tab the browser considers script-opened; on a normally user-opened tab (the common case) window.close() is a silent no-op and the tab is left showing a “Disconnected” banner instead.

Return type:

None

step(dt=0.05, render=True)[source]

Update the graphical scene

Parameters:

dt (float) – time step in seconds, defaults to 0.05
render (bool) – render the change in Swift. If True, this updates the pose of the simulated robots and objects in Swift.

Return type:

None

env.step(args) triggers an update of the 3D scene in the Swift window referenced by env.

Note

Each robot in the scene is updated based on their control type (position, velocity, acceleration, or torque).
Upon acting, the other three of the four control types will be updated in the internal state of the robot object.
The control type is defined by the robot object, and not all robot objects support all control types.
Execution is blocked for the specified interval

Seealso:: run() for repeatedly calling this in a loop with disconnect-awareness built in, instead of hand-writing while True: env.step(dt).

reset()[source]

Reset the graphical scene

env.reset() triggers a reset of the 3D scene in the Swift window referenced by env. It is restored to the original state defined by launch().

Return type:: None

restart()[source]

Restart the graphics display

env.restart() triggers a restart of the Swift view referenced by env. It is closed and relaunched to the original state defined by launch().

Return type:: None

close(clear_cell=False)[source]

Close the graphics display

env.close() gracefully disconnectes from the Swift visualizer referenced by env.

Parameters:: clear_cell (bool) – if launched with browser="notebook", blank out the cell that rendered the iframe instead of leaving its last frame visible (the default – matches prior behaviour). No effect for any other browser= mode, or if the iframe’s cell was never displayed (e.g. still headless).
Return type:: None

add(ob, robot_alpha=1.0, collision_alpha=0.0, readonly=False, name=None)[source]

Add an object to the graphical scene

Deprecated since version 2.0: Kept for backward compatibility. Prefer the explicit add_shape(), add_ui(), add_assembly(), or add_robot() – one entry point per kind of thing, no type-checking required.

Parameters:

ob (Shape | SwiftElement | _rtb_types.Robot) – the object to add
robot_alpha (float) – Robot visual opacity. If 0, then the geometries are invisible, defaults to 1.0
collision_alpha (float) – Robot collision visual opacity. If 0, then the geometries defaults to 0.0
readonly (bool) – If true, swift will not modify any robot attributes, the robot is only being displayed, not simulated, defaults to False
name (str | None) – optional debug/display name, see show()

Return type:

int | AssemblyHandle | SwiftElement | None

Returns:

for a Shape, its object id within the visualizer; for a Robot, an AssemblyHandle owning that instance’s live joint state; for a SwiftElement, the element itself

add_shape(shape, callback=None, name=None)[source]

Add a single shape to the graphical scene

Parameters:

shape (Shape) – the shape to add
callback (Optional[Callable[[float, dict[str, object]], SE3]]) – optional per-step pose callback (t, values) -> SE3, called each env.step() instead of the default velocity/shape.v-driven update – see step()
name (str | None) – optional debug/display name, see show()

Return type:

int

Returns:

the shape’s object id within the visualizer

id = env.add_shape(shape) adds shape to the graphical environment and returns its id.

add_ui(element, name=None)[source]

Add a UI element (Slider, Button, …) to the graphical scene

Parameters:

element (SwiftElement) – the element to add
name (str | None) – optional name, collected into the values dict per-step callbacks receive – see step(). Only elements with a .value attribute (e.g. Slider, Select) contribute a value.

Return type:

SwiftElement

Returns:

the element itself

env.add_ui(element) adds element to the sidebar.

add_assembly(fk, parts, q0=None, callback=None, readonly=False, name=None)[source]

Add an assembly of parts driven by a pure forward-kinematics function

Parameters:

fk (Callable[[list | ndarray | tuple | set], list[SE3]]) – pure function mapping this assembly’s current q to one world-frame SE3 pose per entry in parts, in the same order
parts (list[Shape]) – the shapes making up this assembly, in the order fk returns poses for
q0 (list | ndarray | tuple | set | None) – initial configuration, defaults to an empty array (set handle.q before the first step() if fk needs one)
callback (Optional[Callable[[float, dict[str, object]], list | ndarray | tuple | set]]) – optional per-step callback (t, values) -> q, called each env.step() to compute the new q directly – see step()
readonly (bool) – if True, swift will not advance this assembly’s q itself, defaults to False
name (str | None) – optional debug/display name, see show()

Return type:

AssemblyHandle

Returns:

a handle owning this assembly’s live joint state

handle = env.add_assembly(fk, parts) adds parts to the graphical environment as one unit, positioned each step by fk(handle.q).

add_robot(robot, robot_alpha=1.0, collision_alpha=0.0, readonly=False, callback=None, name=None)[source]

Add an rtb.Robot to the graphical scene

Parameters:

robot (_rtb_types.Robot) – the robot to add
robot_alpha (float) – Robot visual opacity. If 0, then the geometries are invisible, defaults to 1.0
collision_alpha (float) – Robot collision visual opacity. If 0, then the geometries defaults to 0.0
readonly (bool) – If true, swift will not modify any robot attributes, the robot is only being displayed, not simulated, defaults to False
callback (Optional[Callable[[float, dict[str, object]], list | ndarray | tuple | set]]) – optional per-step callback (t, values) -> q, see add_assembly()
name (str | None) – optional debug/display name, see show()

Return type:

AssemblyHandle

Returns:

a handle owning this robot instance’s live joint state

handle = env.add_robot(robot) adds robot to the graphical environment and returns a handle. robot itself stays a plain kinematic model – drive it with handle.q/handle.qd (mutating robot.q/robot.qd directly still works, but is deprecated, see AssemblyHandle).

remove(id)[source]

Remove a robot/shape from the graphical scene

env.remove(robot) removes the robot from the graphical: environment.

Parameters:: id (int | AssemblyHandle | Shape | _rtb_types.ERobot) – the id of the object as returned by the add method, or the instance of the object
Return type:: None

hold(duration=None, timeout=None)[source]

Block for up to duration seconds (or indefinitely)

Meant to sit at the end of a script: once your simulation loop finishes, the script would otherwise exit immediately, killing this process and disconnecting the browser tab mid-view. hold() keeps this process (and so the tab) alive so you can keep looking at the final scene – for a fixed amount of time if duration is given, or until interrupted (^C) or the browser disconnects for longer than timeout otherwise.

duration is an unconditional cap – it elapses regardless of whether the browser is still connected, unlike timeout, which only ever starts counting after a disconnect. hold(5) reads as “hold for 5 seconds” and does exactly that; it will still return early if the browser goes away first.

Parameters:

duration (float | None) – seconds to hold for, regardless of connection state; None (default) holds indefinitely, bounded only by timeout/^C
timeout (float | None) – seconds to keep waiting after the browser disconnects before giving up and returning early; defaults to whatever launch() was given (itself 1 by default). None never gives up on a disconnect (still stops at duration, if given).

Return type:

None

run(duration=None, dt=0.05, timeout=None)[source]

Repeatedly call step() until duration (sim-time seconds) has elapsed, stopping early if the browser disconnects for longer than timeout – the same disconnect-timeout hold() uses, and defaulting to the same launch()’s timeout= value.

env.run() is the loop most scripts would otherwise hand-write as while True: env.step(dt); time.sleep(dt) at the end of a script, with hold()’s disconnect-awareness built in instead of looping forever after the browser is long gone.

Parameters:

duration (float | None) – sim-time seconds to run for; None runs until disconnected (or forever, if timeout is also None)
dt (float) – time step passed to each step() call, defaults to 0.05
timeout (float | None) – seconds to keep running after the browser disconnects before giving up and returning; defaults to whatever launch() was given (itself 1 by default). None never gives up on a disconnect (still stops at duration, if given).

Seealso:

step() for a single manual update, if you need finer control than a bounded/unbounded loop gives you.

Return type:

None

start_recording(file_name, framerate, format='webm')[source]

Start recording the canvas in the Swift simulator

Parameters:

file_name (str) – The file name for which the video will be saved as
framerate (float) – The framerate of the video - to be timed correctly, this should equalt 1 / dt where dt is the time supplied to the step function
format (Literal['webm', 'gif', 'png', 'jpg']) – This is the format of the video, one of ‘webm’, ‘gif’, ‘png’, or ‘jpg’

Return type:

None

env.start_recording(file_name) starts recording the simulation: scene and will save it as file_name once env.start_recording(file_name) is called

stop_recording()[source]

Start recording the canvas in the Swift simulator. This is optional as the video will be automatically saved when the python script exits

Return type:: None

env.stop_recording() stops the recording of the simulation, can: only be called after env.start_recording(file_name)

screenshot(file_name='swift_snap')[source]

Save a screenshot of the current Swift frame as a png file

Parameters:: file_name (str) – The file name for which the screenshot will be saved as
Return type:: None

env.screenshot(file_name) saves a screenshot and downloads it as file_name

process_events(events)[source]

Process the event queue from Swift, this invokes the callback functions from custom elements added to the page. If using custom elements (for example add_slider), use this function in your event loop to process updates from Swift.

Return type:: None

set_camera_pose(position, look_at)[source]

Swift.set_camera_pose(position, look_at) will set the camera position and orientation of the camera within the swift scene. The camera is located at location and is oriented to look at a point in space defined by look_at. Note that the camera is oriented with the positive z-axis.

Warning

The scene’s lights do not move with the camera – they’re fixed in world space, positioned to match the default camera position set at launch. Moving the camera far enough away with this method can leave every camera-facing surface in shadow. Use set_lights() to reposition them to match, if needed.

Parameters:

position (list | ndarray | tuple | set) – The desired position of the camera
look_at (list | ndarray | tuple | set) – A point in the scene in which the camera will look at

Return type:

None

set_lights(lights)[source]

Replace the scene’s current lights.

env.set_lights(lights) replaces every light currently in the scene – including Swift’s own default rig, if it’s still active – with lights. There is no way to add or remove a single light individually; the whole rig is always replaced as one unit. Call again with the same lights given to launch() to restore them after temporarily using something else.

Parameters:: lights (list[Light]) – the new set of lights, replacing every light currently in the scene
Return type:: None

UI elements

class swift.Elements.SwiftElement[source]

Bases: ABC

A basic super class for HTML elements which can be added to Swift

abstractmethod to_dict()[source]

Outputs the element in dictionary form

Return type:: dict[str, object]

abstractmethod update()[source]

Update state of element to reflect what’s going on in the front-end

Return type:: None

class swift.Elements.Slider(cb=None, min=0, max=100, step=1, value=0, label='', unit='', precision=3, desc=None)[source]

Bases: SwiftElement

Create a range-slider html element

Parameters:

cb (Optional[Callable[[float], None]]) – A callback function which is executed when the value of the slider changes. The callback should accept one argument which represents the new value of the slider. Optional – if not given, the slider has no per-element callback, which is the common case for a named slider read via env.values in a shape/assembly callback instead.
min (float) – the minimum value of the slider, optional
max (float) – the maximum value of the slider, optional
step (float) – the step size of the slider, optional
label (str) – caption shown next to the slider, optional
desc (str | None) – deprecated alias for label
unit (str) – add a unit to the slider value, optional
precision (int) – number of decimal places shown for the current value and the min/max range labels next to the slider – e.g. precision=3 shows 2.478, not 2.48 (that would be 3 significant figures instead, a different, narrower value this parameter does not control). Optional, defaults to 3. Purely a display rounding – the underlying value (what a callback or env.values actually receives) always keeps full float precision, e.g. whatever a step()-side computation produced.

property cb: Callable[[float], None]

property min: float

property max: float

property step: float

property value: float

property label: str

property desc: str

property unit: str

property precision: int

to_dict()[source]

Outputs the element in dictionary form

Return type:: dict[str, object]

update(e)[source]

Update state of element to reflect what’s going on in the front-end

Return type:: None

class swift.Elements.Label(label='', compact=False, desc=None)[source]

Bases: SwiftElement

Create a Label html element

Parameters:

label (str) – the text of the label, optional
desc (str | None) – deprecated alias for label
compact (bool) – use a tighter margin/font-size than the default (sized for an occasional standalone heading) – for several Labels stacked close together, e.g. a multi-line live readout, rather than a one-off title. Purely a display style, applied as an inline override in the browser – doesn’t affect any other Label instance, and the class-wide default is unchanged. Optional, defaults to False.

property label: str

property desc: str

to_dict()[source]

Outputs the element in dictionary form

Return type:: dict[str, object]

update(_)[source]

Update state of element to reflect what’s going on in the front-end

Return type:: None

class swift.Elements.Button(cb, label='', desc=None)[source]

Bases: SwiftElement

Create a Button html element

Parameters:

cb (Callable[[Any], None]) – A callback function which is executed when the button is clicked. The callback should accept one argument which can be disregarded
label (str) – text written on the button, optional
desc (str | None) – deprecated alias for label

property cb: Callable[[Any], None]

property label: str

property desc: str

to_dict()[source]

Outputs the element in dictionary form

Return type:: dict[str, object]

update(_)[source]

Update state of element to reflect what’s going on in the front-end

Return type:: None

class swift.Elements.Select(cb, label='', options=[], value=0, desc=None)[source]

Bases: SwiftElement

Create a Select element, used to create a drop-down list.

Parameters:

cb (Callable[[int], None]) – A callback function which is executed when the value select box changes. The callback should accept one argument which represents the index of the new value
label (str) – caption shown next to the select box, optional
desc (str | None) – deprecated alias for label
options (list[str]) – represent the options inside the select box, optional
value (int) – the index of the initial selection of the select box, optional

property cb: Callable[[int], None]

property label: str

property desc: str

property options: list[str]

property value: int

to_dict()[source]

Outputs the element in dictionary form

Return type:: dict[str, object]

update(e)[source]

Update state of element to reflect what’s going on in the front-end

Return type:: None

class swift.Elements.Checkbox(cb, label='', options=[], checked=[], desc=None)[source]

Bases: SwiftElement

Create a checkbox element, used to create multi-selection list.

Parameters:

cb (Callable[[list[bool]], None]) – A callback function which is executed when a box is checked. The callback should accept one argument which represents a List of bool representing the checked state of each box
label (str) – caption shown next to the checkboxes, optional
desc (str | None) – deprecated alias for label
options (list[str]) – represents the checkboxes, optional
checked (list[bool]) – a List represented boxes initially checked

property cb: Callable[[list[bool]], None]

property label: str

property desc: str

property options: list[str]

property checked: list[bool]

to_dict()[source]

Outputs the element in dictionary form

Return type:: dict[str, object]

update(e)[source]

Update state of element to reflect what’s going on in the front-end

Return type:: None

class swift.Elements.Radio(cb, label='', options=[], checked=[], desc=None)[source]

Bases: SwiftElement

Create a radio element, used to create single-selection list.

Parameters:

cb (Callable[[int], None]) – A callback function which is executed when a radio is checked. The callback should accept one argument which represents a index corresponding to the checked radio button
label (str) – caption shown next to the radio buttons, optional
desc (str | None) – deprecated alias for label
options (list[str]) – represents the radio buttons, optional
checked (int | list[bool]) – the initial radio button checked, optional

property cb: Callable[[int], None]

property label: str

property desc: str

property options: list[str]

property checked: list[bool]

to_dict()[source]

Outputs the element in dictionary form

Return type:: dict[str, object]

update(e)[source]

Update state of element to reflect what’s going on in the front-end

Return type:: None