Configuration¶

All configuration dataclasses for pib3.

Overview¶

Configuration is organized into specialized dataclasses:

Class	Purpose
`TrajectoryConfig`	Main config combining all others
`PaperConfig`	Drawing surface settings
`IKConfig`	Inverse kinematics solver
`ImageConfig`	Image processing
`RobotConfig`	Robot connection
`LowLatencyConfig`	Direct Tinkerforge motor control

TrajectoryConfig¶

Main configuration class that combines all settings.

TrajectoryConfig `dataclass` ¶

TrajectoryConfig(
    paper=PaperConfig(),
    ik=IKConfig(),
    image=ImageConfig(),
    point_density=0.01,
)

Full configuration for trajectory generation.

Combines paper, IK, and image settings with additional parameters.

Attributes:

Name	Type	Description
`paper`	`PaperConfig`	Paper/drawing surface configuration.
`ik`	`IKConfig`	Inverse kinematics solver configuration.
`image`	`ImageConfig`	Image processing configuration.
`point_density`	`float`	Interpolation density for smooth motion.

Usage¶

from pib3 import TrajectoryConfig, PaperConfig, IKConfig, ImageConfig

# Default configuration
config = TrajectoryConfig()

# Custom configuration
config = TrajectoryConfig(
    paper=PaperConfig(size=0.15, drawing_scale=0.9),
    ik=IKConfig(max_iterations=200),
    image=ImageConfig(threshold=100),
    point_density=0.005,
)

# Use with trajectory generation
import pib3
trajectory = pib3.generate_trajectory("image.png", config=config)

PaperConfig¶

Configuration for the drawing surface.

PaperConfig `dataclass` ¶

PaperConfig(
    start_x=None,
    size=0.1,
    height_z=None,
    center_y=None,
    drawing_scale=0.8,
    lift_height=0.03,
)

Configuration for the drawing surface (paper), in the robot TORSO frame.

Coordinates are in meters in the torso frame — the frame the DH base is defined in, and the frame IK targets use. Any field left as None is auto-placed by sketch_to_trajectory around a reachable anchor (so the paper centre is reachable by construction); override these on hardware to match the real drawing surface.

Attributes:

Name	Type	Description
`start_x`	`Optional[float]`	Paper near-edge X (torso frame, m). None → auto from anchor.
`size`	`float`	Paper width/height in meters (assumes square paper).
`height_z`	`Optional[float]`	Drawing-plane Z (torso frame, m). None → auto from anchor.
`center_y`	`Optional[float]`	Paper center Y (torso frame, m). None → auto from anchor.
`drawing_scale`	`float`	Scale factor for drawing within paper bounds (0.0-1.0).
`lift_height`	`float`	Pen-up distance in meters when moving between strokes.

Usage¶

from pib3 import PaperConfig

# Default paper
paper = PaperConfig()

# Large paper, higher table
paper = PaperConfig(
    size=0.20,       # 20cm x 20cm
    height_z=0.80,   # 80cm table height
    drawing_scale=0.85,
)

# Specific position
paper = PaperConfig(
    start_x=0.08,
    center_y=0.18,
    lift_height=0.02,
)

Parameter Guide¶

Parameter	Default	Range	Notes
`start_x`	0.10	0.05-0.20	Closer = easier reach
`size`	0.12	0.08-0.25	Limited by arm reach
`height_z`	0.74	0.60-0.85	Table height
`drawing_scale`	0.8	0.5-1.0	Margin within paper
`lift_height`	0.03	0.01-0.05	Pen lift distance

IKConfig¶

Configuration for the inverse kinematics solver.

IKConfig `dataclass` ¶

IKConfig(
    max_iterations=300,
    slimit=100,
    tolerance=0.002,
    arm="left",
    grip_style="index_finger",
)

Configuration for the inverse kinematics solver.

The solver is roboticstoolbox ikine_LM (Levenberg-Marquardt). Only max_iterations, slimit and tolerance affect it.

Attributes:

Name	Type	Description
`max_iterations`	`int`	Max iterations per IK search attempt (ikine_LM ilimit).
`slimit`	`int`	Number of search attempts with random restarts per point (ikine_LM slimit). Higher values find solutions for more poses at the cost of more compute on hard/unreachable targets.
`tolerance`	`float`	Position tolerance in meters.
`arm`	`str`	Which arm to use for drawing ("left" or "right").
`grip_style`	`Literal['index_finger', 'pencil_grip']`	Drawing grip style: - "index_finger": Use extended index finger as drawing tool (default). - "pencil_grip": Clenched fist holding a pencil, tip near pinky base.

Usage¶

from pib3 import IKConfig

# Default settings
ik = IKConfig()

# High accuracy
ik = IKConfig(
    max_iterations=300,
    tolerance=0.001,  # 1mm
)

# Solve more hard poses (more random restarts)
ik = IKConfig(slimit=200)

# Fast (less accurate)
ik = IKConfig(
    max_iterations=50,
    tolerance=0.005,  # 5mm
)

# Use right arm
ik = IKConfig(arm="right")

The solver is roboticstoolbox ikine_LM (Levenberg-Marquardt) on the expert-calibrated DH model. Only max_iterations, slimit and tolerance affect it.

Parameter Guide¶

Parameter	Default	Range	Notes
`max_iterations`	300	30-500	`ikine_LM` iterations per attempt
`slimit`	100	50-300	Random-restart attempts per point; higher solves more poses
`tolerance`	0.002	0.001-0.01	Position accuracy (meters)
`arm`	"left"	"left"/"right"	Which arm to use
`grip_style`	"index_finger"	"index_finger"/"pencil_grip"	Drawing tool

ImageConfig¶

Configuration for image processing and contour extraction.

ImageConfig `dataclass` ¶

ImageConfig(
    threshold=128,
    auto_foreground=True,
    simplify_tolerance=2.0,
    min_contour_length=10,
    min_contour_points=3,
    margin=0.05,
    optimize_path_order=True,
)

Configuration for image-to-sketch conversion.

Attributes:

Name	Type	Description
`threshold`	`int`	Black/white threshold (0-255).
`auto_foreground`	`bool`	Automatically detect minority pixels as foreground.
`simplify_tolerance`	`float`	Douglas-Peucker simplification tolerance in pixels.
`min_contour_length`	`int`	Minimum contour length in pixels.
`min_contour_points`	`int`	Minimum vertices after simplification.
`margin`	`float`	Margin/padding in normalized coordinates (0.0-1.0).
`optimize_path_order`	`bool`	Use TSP optimization to minimize pen-up travel.

Usage¶

from pib3 import ImageConfig

# Default settings
image = ImageConfig()

# For light pencil sketches
image = ImageConfig(
    threshold=200,
    simplify_tolerance=3.0,
)

# For detailed images
image = ImageConfig(
    simplify_tolerance=0.5,
    min_contour_length=5,
)

# Noisy images
image = ImageConfig(
    simplify_tolerance=4.0,
    min_contour_length=20,
    min_contour_points=5,
)

Parameter Guide¶

Parameter	Default	Range	Notes
`threshold`	128	0-255	Lower = more sensitive
`auto_foreground`	True	-	Auto-detect dark/light
`simplify_tolerance`	2.0	0.5-5.0	Higher = simpler
`min_contour_length`	10	5-50	Filter small contours
`min_contour_points`	3	3-10	Min vertices per stroke
`margin`	0.05	0-0.2	Border padding
`optimize_path_order`	True	-	Minimize pen travel

RobotConfig¶

Configuration for real robot connection.

RobotConfig `dataclass` ¶

RobotConfig(
    host="172.26.34.149",
    port=9090,
    timeout=5.0,
    low_latency=LowLatencyConfig(),
)

Configuration for real robot connection.

Attributes:

Name	Type	Description
`host`	`str`	Robot IP address.
`port`	`int`	Rosbridge websocket port.
`timeout`	`float`	Connection timeout in seconds.
`low_latency`	`LowLatencyConfig`	Advanced Tinkerforge motor control settings. Motor commands use Tinkerforge by default (enabled=True). Set enabled=False to use ROS for motor control instead.

Usage¶

from pib3 import RobotConfig
from pib3.backends import RealRobotBackend

# Default settings
config = RobotConfig()

# Custom connection
config = RobotConfig(
    host="192.168.1.100",
    port=9090,
    timeout=10.0,
)

# Create backend from config
robot = RealRobotBackend.from_config(config)

LowLatencyConfig¶

Configuration for direct Tinkerforge motor control, bypassing ROS.

LowLatencyConfig `dataclass` ¶

LowLatencyConfig(
    enabled=True,
    tinkerforge_host=None,
    tinkerforge_port=4223,
    motor_mapping=None,
    sync_to_ros=True,
    command_timeout=0.5,
    use_robot_motor_config=True,
    api_port=5000,
)

Configuration for low-latency direct Tinkerforge motor control.

Bypasses ROS/rosbridge for motor commands, sending directly to Tinkerforge servo bricklets for reduced latency (~5-20ms vs ~100-200ms).

This is the default motor control mode. Servo bricklets are auto-discovered on connect. Use motor_control="ros" in the Robot constructor to use ROS-based motor control instead.

Attributes:

Name	Type	Description
`enabled`	`bool`	Enable low-latency mode for motor commands (default: True).
`tinkerforge_host`	`Optional[str]`	Tinkerforge brick daemon host (usually robot IP).
`tinkerforge_port`	`int`	Tinkerforge brick daemon port (default: 4223).
`motor_mapping`	`Optional[Dict[str, tuple]]`	Dict mapping motor names to (bricklet_uid, channel) tuples. If None, uses auto-discovery (recommended).
`sync_to_ros`	`bool`	If True, update local position cache after setting. This ensures get_joint() returns correct values after low-latency sets. Note: Does NOT publish to ROS topics (that would cause double commands).
`command_timeout`	`float`	Timeout for direct motor commands in seconds.
`use_robot_motor_config`	`bool`	Read the robot's own motor table from pib-api (`http://<host>:<api_port>/motor`) on connect. It gives the exact bricklet UID and pin of every motor, plus the `invert` flags and rotation ranges set in Cerebra, so direct control moves every joint exactly like the ROS path does. Falls back to bricklet auto-discovery when pib-api is unreachable.
`api_port`	`int`	Port of pib-api on the robot.

Usage¶

Direct Tinkerforge motor control is enabled by default (enabled=True) with auto-discovery (motor_mapping=None). Most users don't need to configure LowLatencyConfig directly -- just use Robot(host="...").

For advanced use cases:

from pib3 import LowLatencyConfig, RobotConfig
from pib3.backends import RealRobotBackend

# Custom Tinkerforge settings
config = RobotConfig(
    host="172.26.34.149",
    low_latency=LowLatencyConfig(
        tinkerforge_port=4224,  # Non-standard port
    ),
)

robot = RealRobotBackend.from_config(config)

To disable direct control and use ROS for motors:

from pib3 import Robot

robot = Robot(host="172.26.34.149", motor_mode="ros")

Parameter Guide¶

Parameter	Default	Description
`enabled`	`True`	Enable direct Tinkerforge control
`tinkerforge_host`	`None`	Daemon host (defaults to robot IP)
`tinkerforge_port`	`4223`	Daemon port
`motor_mapping`	`None`	Maps motor names to `(uid, channel)`. `None` = auto-discover.
`sync_to_ros`	`True`	Update local cache after commands
`command_timeout`	`0.5`	Command timeout in seconds

Performance¶

Mode	Latency	Use Case
Standard (ROS)	100-200ms	Trajectory playback
Low-latency	5-20ms	Real-time control

See the Low-Latency Tutorial for complete examples.

Configuration¶

Overview¶

TrajectoryConfig¶

TrajectoryConfig dataclass ¶

Usage¶

PaperConfig¶

PaperConfig dataclass ¶

Usage¶

Parameter Guide¶

IKConfig¶

IKConfig dataclass ¶

Usage¶

Parameter Guide¶

ImageConfig¶

ImageConfig dataclass ¶

Usage¶

Parameter Guide¶

RobotConfig¶

RobotConfig dataclass ¶

Usage¶

LowLatencyConfig¶

LowLatencyConfig dataclass ¶

Usage¶

Parameter Guide¶

Performance¶

TrajectoryConfig `dataclass` ¶

PaperConfig `dataclass` ¶

IKConfig `dataclass` ¶

ImageConfig `dataclass` ¶

RobotConfig `dataclass` ¶

LowLatencyConfig `dataclass` ¶