Python API

Hand-written reference for the Python modules of the flexivpdk package. Generated message and stub modules are described in Services and Messages.

flexiv.pdk

flexiv.pdk.__version__: Package version string, for example "1.0.0".

class flexiv.pdk.Client(target: str = 'localhost:50052')

Main entry point. Creates an insecure gRPC channel to target and exposes one lazily created service client per gRPC service. Each service client has a stub attribute, the generated gRPC stub.

Usable as a context manager; the channel is closed on exit.

channel: grpc.Channel: The underlying channel.

check_version() → tuple[bool, str]: Ask the server whether this client works with it: same major and minor version. Returns (compatible, message); message says why not, or gives the server version. Returns (False, message) when the server cannot be reached; message says why.

close() → None: Close the channel.

property workcell

property config

property frame

property scene_event

property collision

property system

property system_config

property system_state

property kinematics

property point_to_point_path

property surface_finish

property mesh_operation

property camera

property reconstruction

property version

property log: Service clients. See API Overview for the service each one wraps.

property license: flexiv.pdk.client.LicenseServiceClient: License service client, with a helper for installing license files.

class flexiv.pdk.client.LicenseServiceClient

Returned by flexiv.pdk.Client.license. Not exported from flexiv.pdk; import it from flexiv.pdk.client if you need the type.

stub: LicenseServiceStub.

install_file(path, file_name: str = '')

Install the .lic file Flexiv sent back. Takes effect immediately.

The file is read on this machine and its contents sent over gRPC, so the server may run on another host or in a container.

Parameters:

path – Path to the .lic file.
file_name – Name to save it as on the server. Defaults to the file’s own name, or the license id where that name is not plain (only A-Z a-z 0-9 - _ .).

Returns:

SaveResponse. Check status.code; an unverifiable license is reported there, not raised.

Raises:

OSError – The file cannot be read.
ValueError – The file is empty.

flexiv.pdk.watch

Consume server-streaming (“watch”) RPCs with automatic reconnection. See Watching Scene Events.

flexiv.pdk.watch.Executor: Callable[[Callable[[], None]], None]: given fn, runs fn() on the thread of your choice. The Python form of C++ watch::Executor.

class flexiv.pdk.watch.Options(executor=None, reconnect=True, backoff_initial_s=0.5, backoff_max_s=10.0, backoff_factor=2.0, max_retries=-1)

Dataclass controlling delivery and reconnection.

Parameters:

executor – Callable[[Callable[[], None]], None] that runs a callback on the thread of your choice. None delivers on the watch’s background thread.
reconnect – Reconnect when the stream ends or fails, including when the server cancels it.
backoff_initial_s – First reconnect delay, in seconds.
backoff_max_s – Maximum reconnect delay.
backoff_factor – Multiplier applied after each failed attempt. The delay resets after an event is received.
max_retries – Maximum consecutive reconnects; -1 for unlimited.

flexiv.pdk.watch.watch(open_stream, options=None) → Iterator

Blocking generator that yields stream events and reconnects with backoff. Stop by breaking out of the loop or closing the generator; either cancels the live call. Options.executor is ignored.

Parameters:: open_stream – Zero-argument callable that opens the stream, for example lambda: client.scene_event.stub.WatchSceneEvents(request). Called again on every reconnect.

class flexiv.pdk.watch.Subscriber

Opens watch RPCs as background subscriptions. Usable as a context manager (calls stop_all() on exit).

subscribe(open_stream, on_event, options=None) → Subscription: Start a background subscription. on_event is called with each event. Keep the returned Subscription and close it to stop.

subscribe_rpc(stub_method, request, on_event, options=None) → Subscription: Shorthand for subscribe(lambda: stub_method(request), on_event, options).

stop_all() → None: Close every subscription created by this subscriber.

class flexiv.pdk.watch.Subscription(open_stream, on_event, options=None)

Handle to an active watch. The constructor starts the stream at once on a daemon thread named pdk-watch; Subscriber.subscribe() calls it for you. Usable as a context manager.

property active: bool: True while the watch is running.

close(timeout=None) → None: Stop the stream and join the worker thread. Idempotent and safe from any thread; when called from inside the callback, the join is skipped.

Exceptions raised by a callback are logged on the flexiv.pdk.watch logger and the stream continues.

flexiv.pdk.spatial

flexiv.pdk.spatial.to_numpy(message) → numpy.ndarray

Vector3 → [x, y, z]; Quaternion → [w, x, y, z]; SE3Pose → 4×4 homogeneous matrix; JointWaypoint → (position, velocity); a repeated double field, list or tuple → 1-D float64 array. Raises TypeError for anything else.

An all-zero (unset) Quaternion, alone or in an SE3Pose, reads as the identity rotation. The server may not treat it so; always set w=1 in messages you send.

flexiv.pdk.spatial.to_proto(value, target=None): target is Vector3 ([x, y, z]), Quaternion ([w, x, y, z] or a Rotation), SE3Pose (4×4), JointWaypoint (a (position, velocity) pair) or list (repeated double). It may be omitted only for a 4×4 matrix or a Rotation. Raises TypeError for a missing or unknown target, and ValueError for the wrong shape. See Math Conversions.

flexiv.pdk.physics

flexiv.pdk.physics.to_numpy(message) → numpy.ndarray: Inertia → its symmetric 3×3 inertia tensor. Raises TypeError for anything else.

flexiv.pdk.physics.to_proto(value, target=None): A 3×3 matrix → Inertia, from the upper triangle. target may be Inertia or omitted. Raises ValueError for another shape. See Math Conversions.

flexiv.pdk.license.license_file

Helpers behind flexiv.pdk.client.LicenseServiceClient.install_file().

flexiv.pdk.license.license_file.read_license_file(path) → str: Read a license file (raw or base64 form) and return the base64 text for SaveRequest.license.

flexiv.pdk.license.license_file.license_text(raw: bytes) → str: Return base64 for either form of license file. Whitespace in base64 input is ignored; already-encoded input is passed through.

flexiv.pdk.license.license_file.server_file_name(path) → str: The file’s own name if the server accepts it as a plain name, otherwise "" (the server then names the file after the license id).

Command-line entry point

pdk-scene is the console script flexiv.pdk.cli.main:pdk_scene. See The pdk-scene Command-Line Tool.