Edit

World state store API

The world state store service API lets a client list, get, and stream the transforms a world state store service publishes. The 3D SCENE tab uses this API to render a machine’s custom visuals, and a custom visualizer you build can consume it the same way. To implement the service in a module, see Publish visuals from a module.

The world state store service supports the following methods:

Method Name	Description
`ListUUIDs`	List all world state transform UUIDs.
`GetTransform`	Get a world state transform by UUID.
`StreamTransformChanges`	Stream changes to world state transforms.
`DoCommand`	Execute model-specific commands that are not otherwise defined by the service API.
`GetStatus`	Get the current status of the world state store service as a map of key-value pairs describing its state.
`GetResourceName`	Get the ResourceName for this Resource with the given name.
`Close`	Safely shut down the resource and prevent further use.

API

ListUUIDs

List all world state transform UUIDs.

Parameters:

extra (Mapping[str, Any]) (optional): Extra options to pass to the underlying RPC call.
timeout (float) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

(List[bytes])

Example:

worldstatestore = WorldStateStoreClient.from_robot(robot=machine, name="builtin")

uuids = await worldstatestore.list_uuids()

For more information, see the Python SDK Docs.

Parameters:

ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
extra (map[string]interface{}): Extra options to pass to the underlying RPC call.

Returns:

([][]byte)
(error): An error, if one occurred.

Example:

// List the world state uuids of a WorldStateStore Service.
uuids, err := myWorldStateStoreService.ListUUIDs(ctx, nil)
if err != nil {
  logger.Fatal(err)
}
// Print out the world state
for _, uuid := range uuids {
  fmt.Printf("UUID: %v", uuid)
}

For more information, see the Go SDK Docs.

Parameters:

extra (None) (optional): Additional arguments to the method.
callOptions (CallOptions) (optional)

Returns:

(Promise<string[]>)

Example:

const worldStateStore = new VIAM.WorldStateStoreClient(machine, 'builtin');

// Get all transform UUIDs
const uuids = await worldStateStore.listUUIDs();

For more information, see the TypeScript SDK Docs.

GetTransform

Get a world state transform by UUID.

Parameters:

uuid (bytes) (required): The UUID of the transform to retrieve.
extra (Mapping[str, Any]) (optional): Extra options to pass to the underlying RPC call.
timeout (float) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

(viam.proto.common.Transform)

Example:

worldstatestore = WorldStateStoreClient.from_robot(robot=machine, name="builtin")

transform = await worldstatestore.get_transform(uuid=b"some-uuid")

For more information, see the Python SDK Docs.

Parameters:

ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
uuid ([]byte)
extra (map[string]interface{}): Extra options to pass to the underlying RPC call.

Returns:

(*commonpb.Transform)
(error): An error, if one occurred.

Example:

// Get the transform by uuid.
obj, err := myWorldStateStoreService.GetTransform(ctx, myUUID, nil)
if err != nil {
  logger.Fatal(err)
}
// Print out the transform.
fmt.Printf("Name: %v\nPose: %+v\nMetadata: %+v\nGeometry: %+v", obj.Name, obj.Pose, obj.Metadata, obj.Geometry)

For more information, see the Go SDK Docs.

Parameters:

uuid (string) (required): The UUID of the transform to retrieve.
extra (None) (optional): Additional arguments to the method.
callOptions (CallOptions) (optional)

Returns:

(Promise<TransformWithUUID>)

Example:

const worldStateStore = new VIAM.WorldStateStoreClient(machine, 'builtin');

// Get a specific transform by UUID
const transform = await worldStateStore.getTransform(uuid);

For more information, see the TypeScript SDK Docs.

StreamTransformChanges

Stream changes to world state transforms.

Parameters:

extra (Mapping[str, Any]) (optional): Extra options to pass to the underlying RPC call.
timeout (float) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

(AsyncGenerator[viam.proto.service.worldstatestore.StreamTransformChangesResponse, None])

Example:

worldstatestore = WorldStateStoreClient.from_robot(robot=machine, name="builtin")

async for change in worldstatestore.stream_transform_changes():
    print(f"Transform {change.transform.uuid} {change.change_type}")

Each change carries a change_type (one of TRANSFORM_CHANGE_TYPE_ADDED, TRANSFORM_CHANGE_TYPE_UPDATED, TRANSFORM_CHANGE_TYPE_REMOVED, or TRANSFORM_CHANGE_TYPE_UNSPECIFIED from viam.proto.service.worldstatestore) and an updated_fields field mask:

For TRANSFORM_CHANGE_TYPE_ADDED, updated_fields is empty; use the whole transform.
For TRANSFORM_CHANGE_TYPE_UPDATED, updated_fields.paths lists the field paths that changed, so you can apply a partial update instead of replacing the whole transform.
For TRANSFORM_CHANGE_TYPE_REMOVED, updated_fields.paths holds the transform’s UUID path.

For more information, see the Python SDK Docs.

Parameters:

ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
extra (map[string]interface{}): Extra options to pass to the underlying RPC call.

Returns:

(*TransformChangeStream)
(error): An error, if one occurred.

Example:

changes, err := myWorldStateStoreService.StreamTransformChanges(ctx, nil)
if err != nil {
  logger.Fatal(err)
}
for {
  change, err := changes.Next()
  if err == io.EOF {
    break
  }
  if err != nil {
    logger.Fatal(err)
  }
  fmt.Printf("Change: %v\n", change)
}

Each TransformChange carries a ChangeType (one of pb.TransformChangeType_TRANSFORM_CHANGE_TYPE_ADDED, _UPDATED, _REMOVED, or _UNSPECIFIED) and an UpdatedFields []string:

For an added transform, UpdatedFields is empty; use the whole transform.
For an updated transform, UpdatedFields lists the field paths that changed, so you can apply a partial update instead of replacing the whole transform.
For a removed transform, UpdatedFields holds the transform’s UUID path.

StreamTransformChanges returns a *TransformChangeStream, not a channel: call Next() repeatedly until it returns io.EOF, as shown above.

For more information, see the Go SDK Docs.

Parameters:

extra (None) (optional): Additional arguments to the method.
callOptions (CallOptions) (optional)

Returns:

(AsyncGenerator<TransformChangeEvent, void>)

Example:

const worldStateStore = new VIAM.WorldStateStoreClient(machine, 'builtin');

// Stream transform changes
const stream = worldStateStore.streamTransformChanges();
for await (const change of stream) {
  console.log('Transform change:', change.changeType, change.transform);
}

Each change carries a changeType (one of TransformChangeType.ADDED, .UPDATED, .REMOVED, or .UNSPECIFIED) and an updatedFields field mask:

For ADDED, updatedFields is undefined; use the whole transform.
For UPDATED, updatedFields.paths lists the field paths that changed, so you can apply a partial update instead of replacing the whole transform.
For REMOVED, updatedFields.paths holds the transform’s UUID path.

For more information, see the TypeScript SDK Docs.

DoCommand

Execute model-specific commands that are not otherwise defined by the service API. Most models do not implement DoCommand. Any available model-specific commands should be covered in the model’s documentation. If you are implementing your own vision service and want to add features that have no corresponding built-in API method, you can implement them with DoCommand.

Parameters:

command (Mapping[str, ValueTypes]) (required): The command to execute.
timeout (float) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

(Mapping[str, viam.utils.ValueTypes])

Example:

my_world_state_store_svc = World_State_StoreClient.from_robot(robot=machine, "my_world_state_store_svc")

my_command = {
  "cmnd": "dosomething",
  "someparameter": 52
}

await my_world_state_store_svc.do_command(command=my_command)

For more information, see the Python SDK Docs.

Parameters:

ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
cmd (map[string]interface{}): The command to execute.

Returns:

(map[string]interface{}): The command response.
(error): An error, if one occurred.

Example:

myWorldStateStoreSvc, err := worldstatestore.FromProvider(machine, "my_world_state_store_svc")

command := map[string]interface{}{"cmd": "test", "data1": 500}
result, err := myWorldStateStoreSvc.DoCommand(context.Background(), command)

For more information, see the Go SDK Docs.

Parameters:

command (Struct) (required): The command to execute. Accepts either a Struct or a plain object, which will be converted automatically.
callOptions (CallOptions) (optional)

Returns:

(Promise<JsonValue>)

Example:

// Plain object (recommended)
const result = await resource.doCommand({
  myCommand: { key: 'value' },
});

// Struct (still supported)
import { Struct } from '@viamrobotics/sdk';

const result = await resource.doCommand(Struct.fromJson({ myCommand: { key: 'value' } }));

For more information, see the TypeScript SDK Docs.

GetStatus

Get the current status of the world state store service as a map of key-value pairs describing its state.

Parameters:

timeout (float) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

(Mapping[str, viam.utils.ValueTypes]): : The status of the service.

Example:

status = await service.get_status()

For more information, see the Python SDK Docs.

Parameters:

ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.

Returns:

(map[string]interface{})
(error): An error, if one occurred.

Example:

myWorldStateStoreSvc, err := worldstatestore.FromProvider(machine, "my_world_state_store_svc")

status, err := myWorldStateStoreSvc.Status(context.Background())

For more information, see the Go SDK Docs.

Parameters:

callOptions (CallOptions) (optional)

Returns:

(Promise<JsonValue>)

For more information, see the TypeScript SDK Docs.

GetResourceName

Get the ResourceName for this Resource with the given name.

Parameters:

name (str) (required): The name of the Resource.

Returns:

(viam.proto.common.ResourceName): : The ResourceName of this Resource.

Example:

my_world_state_store_svc_name = WorldStateStoreClient.get_resource_name("my_world_state_store_svc")

For more information, see the Python SDK Docs.

Parameters:

None.

Returns:

(Name)

Example:

myWorldStateStoreSvc, err := worldstatestore.FromProvider(machine, "my_world_state_store_svc")

err = myWorldStateStoreSvc.Name()

For more information, see the Go SDK Docs.

Parameters:

None.

Returns:

(string): The name of the resource.

Example:

world_state_store.name

For more information, see the TypeScript SDK Docs.

Close

Safely shut down the resource and prevent further use.

Python
Go

Parameters:

None.

Returns:

None.

Example:

my_world_state_store_svc = World_State_StoreClient.from_robot(robot=machine, name="my_world_state_store_svc")
await my_world_state_store_svc.close()

For more information, see the Python SDK Docs.

Parameters:

ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.

Returns:

(error): An error, if one occurred.

Example:

myWorldStateStoreSvc, err := worldstatestore.FromProvider(machine, "my_world_state_store_svc")

err = myWorldStateStoreSvc.Close(context.Background())

For more information, see the Go SDK Docs.

Was this page helpful?

Glad to hear it! If you have any other feedback please let us know:

We're sorry about that. To help us improve, please tell us what we can do better:

Thank you!