Skip to content

Latest commit

 

History

History
102 lines (75 loc) · 3.87 KB

index.md

File metadata and controls

102 lines (75 loc) · 3.87 KB

API documentation for this tool

Documentation for PySpaceMouse is generated by MkDoxy.

Examples

More examples can be found in Examples page.

Module pyspacemouse

The module-level API is as follows:

open(callback=None, button_callback=None, button_callback_arr=None, set_nonblocking_loop=True, device=None)
    Open a 3D space navigator device. Makes this device the current active device, which enables the module-level read() and close()
    calls. For multiple devices, use the read() and close() calls on the returned object instead, and don't use the module-level calls.

    Parameters:
        callback: If callback is provided, it is called on each HID update with a copy of the current state namedtuple
        dof_callback: If dof_callback is provided, it is called only on DOF state changes with the argument (state).
        button_callback: If button_callback is provided, it is called on each button push, with the arguments (state_tuple, button_state)
        device: name of device to open, as a string like "SpaceNavigator". Must be one of the values in `supported_devices`.
                If `None`, chooses the first supported device found.
    Returns:
        Device object if the device was opened successfully
        None if the device could not be opened

read()              Return a namedtuple giving the current device state (t,x,y,z,roll,pitch,yaw,button)
close()             Close the connection to the current device, if it is open
list_devices()      Return a list of supported devices found, or an empty list if none found

open() returns a DeviceSpec object. If you have multiple 3Dconnexion devices, you can use the object-oriented API to access them individually. Each object has the following API, which functions exactly as the above API, but on a per-device basis:

dev.open()          Opens the connection (this is always called by the module-level open command,
                    so you should not need to use it unless you have called close())
dev.read()          Return the state of the device as namedtuple [t,x,y,z,roll,pitch,yaw,button]
dev.close()         Close this device

There are also attributes:

dev.connected       True if the device is connected, False otherwise
dev.state           Convenience property which returns the same value as read()

State objects

State objects returned from read() have 7 attributes: [t,x,y,z,roll,pitch,yaw,button].

  • t: timestamp in seconds since the script started.
  • x,y,z: translations in the range [-1.0, 1.0]
  • roll, pitch, yaw: rotations in the range [-1.0, 1.0].
  • buttons: list of button states (0 or 1), in order specified in the device specifier

Custom Device Configuration

You can customize axis mappings without modifying the TOML configuration by using the helper functions:

create_device_info()

Create a completely custom device configuration:

custom = pyspacemouse.create_device_info(
    name="MyDevice",
    vendor_id=0x256F,
    product_id=0xC635,
    mappings={
        "x": (1, 1, 2, 1),      # (channel, byte1, byte2, scale)
        "y": (1, 3, 4, -1),     # Inverted
        "z": (1, 5, 6, -1),
        "pitch": (2, 1, 2, -1),
        "roll": (2, 3, 4, -1),
        "yaw": (2, 5, 6, 1),
    },
    buttons={"LEFT": (3, 1, 0), "RIGHT": (3, 1, 1)},
)

modify_device_info()

Modify an existing device spec (e.g., to invert axes):

specs = pyspacemouse.get_device_specs()
base = specs["SpaceNavigator"]

# Invert Y and Z for ROS conventions
ros_spec = pyspacemouse.modify_device_info(
    base,
    name="SpaceNavigator (ROS)",
    invert_axes=["y", "z", "roll", "yaw"],
)

Using Custom Specs

Pass the custom spec to open() or open_by_path():

with pyspacemouse.open(device_spec=ros_spec) as device:
    state = device.read()