Virtual Field state

Scene, arm, and asset payloads published by the runtime.

These types correspond to the asset-publishing flow described in docs/virtual_field/dual_arm_assets.md and the scene-state communication schema.

class virtual_field.core.state.Transform(translation=<factory>, rotation_xyzw=<factory>)

Rigid pose in world space for wire protocol and rendering.

translation is [x, y, z]. rotation_xyzw is a unit quaternion [x, y, z, w] (scalar-last), matching common VR/controller conventions.

class virtual_field.core.state.Twist(linear=<factory>, angular=<factory>)

Linear and angular velocity in world space.

This mirrors the velocity fields carried by XR controller samples and arm commands.

Attributes:

linear

Linear velocity vector [vx, vy, vz].

angular

Angular velocity vector [wx, wy, wz].

to_dict()

Serialize to a JSON-compatible dictionary.

Return type:

dict[str, Any]

classmethod from_dict(data)

Deserialize from JSON-compatible data.

Return type:

Twist

class virtual_field.core.state.ArmState(arm_id, owner_user_id, base, tip, centerline, radii, element_lengths=<factory>, directors=<factory>, contact_points=<factory>)

Renderable state for one simulated or pass-through arm.

This is the primary arm payload published in SceneState.arms and described in the Publishing Arm State and Assets guide.

Attributes:

arm_id

Stable identifier for the arm.

owner_user_id

User that owns this arm, or None when no owner is associated.

base

Base pose of the arm in world space.

tip

Tip pose of the arm in world space.

centerline

Polyline points describing the arm centerline from base to tip.

radii

Per-element or per-segment radii used by the client arm renderer.

element_lengths

Optional per-segment lengths. Useful for some client render modes.

directors

Optional row-wise 3x3 orientation frames along the arm.

contact_points

Optional world-space points for contact or debug visualization.

to_dict()

Serialize to a JSON-compatible dictionary.

Return type:

dict[str, Any]

classmethod from_dict(data)

Deserialize from JSON-compatible data.

Return type:

ArmState

class virtual_field.core.state.MeshEntity(mesh_id, owner_id, asset_uri, translation=<factory>, rotation_xyzw=<factory>, scale=<factory>, visible=True, static_asset=False)

Mesh instance published alongside the arm state.

Mesh entities are used for generated scenery, obstacles, props, or other user-owned assets that should be rendered by the client.

Attributes:

mesh_id

Stable mesh identifier.

owner_id

User that owns the mesh entity.

asset_uri

URI pointing to the mesh asset, often a GLTF data URI.

translation

World-space translation.

rotation_xyzw

World-space quaternion rotation in [x, y, z, w] order.

scale

Non-uniform scale vector.

visible

Whether the client should render the mesh.

static_asset

If true, the server may omit asset_uri on subsequent scene_state payloads once each client has received the full mesh once (large scenery).

to_client_dict(*, include_asset_uri=True)

Serialize for WebSocket payloads.

Return type:

dict[str, Any]

Parameters:

include_asset_uri

When false, asset_uri is omitted so static scenery is not resent.

to_dict()

Serialize to a JSON-compatible dictionary.

Return type:

dict[str, Any]

classmethod from_dict(data)

Deserialize from JSON-compatible data.

Return type:

MeshEntity

class virtual_field.core.state.OverlayPointsEntity(overlay_id, owner_id, points=<factory>, point_size=0.008, visible=True)

Point-cloud style overlay payload for lightweight debug visuals.

This entity type is useful for contact-point trails or other transient point markers that do not warrant a mesh.

Attributes:

overlay_id

Stable overlay identifier.

owner_id

User that owns the overlay.

points

World-space points to render.

point_size

Rendered point radius/size in world units.

visible

Whether the client should render the overlay.

to_dict()

Serialize to a JSON-compatible dictionary.

Return type:

dict[str, Any]

classmethod from_dict(data)

Deserialize from JSON-compatible data.

Return type:

OverlayPointsEntity

class virtual_field.core.state.SphereEntity(sphere_id, owner_id, translation, radius, color_rgb=<factory>, visible=True)

Simple sphere primitive published as part of the scene state.

This is used for dynamic spheres such as the Cathy-throw target objects.

Attributes:

sphere_id

Stable sphere identifier.

owner_id

User that owns the sphere.

translation

World-space sphere center.

radius

Sphere radius in world units.

color_rgb

Display color as [r, g, b] values.

visible

Whether the client should render the sphere.

to_dict()

Serialize to a JSON-compatible dictionary.

Return type:

dict[str, Any]

classmethod from_dict(data)

Deserialize from JSON-compatible data.

Return type:

SphereEntity

class virtual_field.core.state.SceneState(timestamp, arms, scenery=<factory>, user_arms=<factory>, meshes=<factory>, overlay_points=<factory>, spheres=<factory>, haptics=<factory>)

Full scene snapshot published from Python to the WebXR client.

This payload combines arm state with optional scenery and user-owned assets and is the core update object described in the communication and asset publishing guides.

Attributes:

timestamp

Scene time in seconds.

arms

Mapping from arm_id to ArmState.

scenery

Named world transforms for extra fixed scene anchors.

user_arms

Mapping from user_id to the arm ids currently owned by that user.

meshes

Mesh instances keyed by mesh_id.

overlay_points

Point overlays keyed by overlay_id.

spheres

Sphere primitives keyed by sphere_id.

to_dict()

Serialize to a JSON-compatible dictionary.

Return type:

dict[str, Any]

to_dict_for_client(sent_static_mesh_asset_ids)

Serialize like to_dict(), but omit repeated asset_uri for static meshes.

Updates sent_static_mesh_asset_ids in place: after a full send of a static mesh, its mesh_id is added; ids are dropped when the mesh disappears.

Return type:

dict[str, Any]

classmethod from_dict(data)

Deserialize from JSON-compatible data.

Return type:

SceneState