From 8b2b1e3aaea68a1974a3b0b21e8bacfe77402872 Mon Sep 17 00:00:00 2001 From: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> Date: Fri, 12 Sep 2025 10:34:31 +0200 Subject: [PATCH] DOCS-4335: Add world state store --- .github/workflows/parse_go.py | 3 + .github/workflows/parse_python.py | 2 + .github/workflows/parse_typescript.py | 3 +- .github/workflows/sdk_protos_map.csv | 8 + .github/workflows/update_sdk_methods.py | 7 +- .../apis/services/world-state-store.md | 23 ++ .../apis/generated/world_state_store-table.md | 9 + .../apis/generated/world_state_store.md | 309 ++++++++++++++++++ .../protos/world_state_store.DoCommand.md | 4 + .../protos/world_state_store.GetOperation.md | 3 + .../world_state_store.GetResourceName.md | 1 + .../protos/world_state_store.GetTransform.md | 1 + .../protos/world_state_store.ListUUIDs.md | 1 + ...orld_state_store.StreamTransformChanges.md | 1 + .../protos/world_state_store.close.md | 1 + 15 files changed, 374 insertions(+), 2 deletions(-) create mode 100644 docs/dev/reference/apis/services/world-state-store.md create mode 100644 static/include/services/apis/generated/world_state_store-table.md create mode 100644 static/include/services/apis/generated/world_state_store.md create mode 100644 static/include/services/apis/overrides/protos/world_state_store.DoCommand.md create mode 100644 static/include/services/apis/overrides/protos/world_state_store.GetOperation.md create mode 100644 static/include/services/apis/overrides/protos/world_state_store.GetResourceName.md create mode 100644 static/include/services/apis/overrides/protos/world_state_store.GetTransform.md create mode 100644 static/include/services/apis/overrides/protos/world_state_store.ListUUIDs.md create mode 100644 static/include/services/apis/overrides/protos/world_state_store.StreamTransformChanges.md create mode 100644 static/include/services/apis/overrides/protos/world_state_store.close.md diff --git a/.github/workflows/parse_go.py b/.github/workflows/parse_go.py index 73dddae8e2..5fe82732c7 100755 --- a/.github/workflows/parse_go.py +++ b/.github/workflows/parse_go.py @@ -113,6 +113,9 @@ def parse(self, type, viam_resources): for resource in viam_resources: + if resource == "world_state_store": + print(f'Skipping Resource: {resource}') + continue ## Determine URL form for Go depending on type (like 'component'): if type in ("component", "service") and resource in go_resource_overrides: url = f"{self.scrape_url}/go.viam.com/rdk/{type}s/{go_resource_overrides[resource]}" diff --git a/.github/workflows/parse_python.py b/.github/workflows/parse_python.py index 716d6f2961..9b0de13d4b 100755 --- a/.github/workflows/parse_python.py +++ b/.github/workflows/parse_python.py @@ -141,6 +141,8 @@ def parse(self, type, viam_resources): ## Determine URL form for Python depending on type (like 'component'): if type in ("component", "service") and resource in python_resource_overrides: url = f"{self.scrape_url}/autoapi/viam/{type}s/{python_resource_overrides[resource]}/client/index.html" + elif resource == "world_state_store": + url = f"{self.scrape_url}/autoapi/viam/services/worldstatestore/index.html" elif type in ("component", "service"): url = f"{self.scrape_url}/autoapi/viam/{type}s/{resource}/client/index.html" elif type == "app" and resource in python_resource_overrides: diff --git a/.github/workflows/parse_typescript.py b/.github/workflows/parse_typescript.py index b08f20f182..1823093c09 100755 --- a/.github/workflows/parse_typescript.py +++ b/.github/workflows/parse_typescript.py @@ -15,7 +15,8 @@ "dataset": "Data", "data_sync": "Data", "data_manager": "DataManager", - "mltraining": "MlTraining" + "mltraining": "MlTraining", + "world_state_store": "WorldStateStore" } ## Ignore these specific APIs if they error, are deprecated, etc: diff --git a/.github/workflows/sdk_protos_map.csv b/.github/workflows/sdk_protos_map.csv index b663bbc9d5..c373d4e842 100644 --- a/.github/workflows/sdk_protos_map.csv +++ b/.github/workflows/sdk_protos_map.csv @@ -319,6 +319,14 @@ vision,GetResourceName,,get_resource_name,Name,getResourceName,name vision,GetProperties,,get_properties,GetProperties,properties,getProperties vision,Close,,close,Close,, +## World State Store +world_state_store,listUUIDs,,list_uuids,,,listUUIDs +world_state_store,GetTransform,,get_transform,,,getTransform +world_state_store,StreamTransformChanges,,stream_transform_changes,,,streamTransformChanges +world_state_store,DoCommand,,do_command,,,doCommand +world_state_store,GetResourceName,,get_resource_name,,,name +world_state_store,Close,,close,,, + ## App app,GetUserIDByEmail,,get_user_id_by_email,GetUserIDByEmail,,getUserIDByEmail app,CreateOrganization,,create_organization,CreateOrganization,,createOrganization diff --git a/.github/workflows/update_sdk_methods.py b/.github/workflows/update_sdk_methods.py index 5aae568e7c..be7e48d23b 100755 --- a/.github/workflows/update_sdk_methods.py +++ b/.github/workflows/update_sdk_methods.py @@ -23,7 +23,7 @@ ## at runtime if desired: components = ["arm", "base", "board", "button", "camera", "encoder", "gantry", "generic_component", "gripper", "input_controller", "motor", "movement_sensor", "power_sensor", "sensor", "servo", "switch"] -services = ["base_remote_control", "data_manager", "discovery", "generic_service", "mlmodel", "motion", "navigation", "slam", "vision"] +services = ["base_remote_control", "data_manager", "discovery", "generic_service", "mlmodel", "motion", "navigation", "slam", "vision", "world_state_store"] app_apis = ["app", "billing", "data", "dataset", "data_sync", "mltraining"] robot_apis = ["robot"] @@ -323,6 +323,11 @@ "url": "https://raw.githubusercontent.com/viamrobotics/api/main/app/mltraining/v1/ml_training_grpc.pb.go", "name": "MLTrainingServiceClient", "methods": [] + }, + "world_state_store": { + "url": "https://raw.githubusercontent.com/viamrobotics/api/main/service/worldstatestore/v1/world_state_store_grpc.pb.go", + "name": "WorldStateStoreServiceClient", + "methods": [] } } diff --git a/docs/dev/reference/apis/services/world-state-store.md b/docs/dev/reference/apis/services/world-state-store.md new file mode 100644 index 0000000000..637a1d467d --- /dev/null +++ b/docs/dev/reference/apis/services/world-state-store.md @@ -0,0 +1,23 @@ +--- +title: "World state store API" +linkTitle: "World state store" +weight: 70 +type: "docs" +tags: ["world_state_store", "services"] +description: "Retrieve a list of world objects." +icon: true +images: ["/icons/components/generic.svg"] +date: "2025-09-12" +# updated: "" # When the content was last entirely checked +--- + +The world state store service API allows you to retrieve a list of world objects. +You can use this list to create custom visualizers to render spatial data related to a machine on the machine's **VISUALIZE** tab. + +The world state store service supports the following methods: + +{{< readfile "/static/include/services/apis/generated/world_state_store-table.md" >}} + +## API + +{{< readfile "/static/include/services/apis/generated/world_state_store.md" >}} diff --git a/static/include/services/apis/generated/world_state_store-table.md b/static/include/services/apis/generated/world_state_store-table.md new file mode 100644 index 0000000000..7d18aae23e --- /dev/null +++ b/static/include/services/apis/generated/world_state_store-table.md @@ -0,0 +1,9 @@ + +| Method Name | Description | +| ----------- | ----------- | +| [`listUUIDs`](/dev/reference/apis/services/vision/#close) | List all world state transform UUIDs. | +| [`GetTransform`](/dev/reference/apis/services/vision/#close) | Get a world state transform by UUID. | +| [`StreamTransformChanges`](/dev/reference/apis/services/vision/#close) | Stream changes to world state transforms. | +| [`DoCommand`](/dev/reference/apis/services/vision/#close) | Execute model-specific commands that are not otherwise defined by the service API. | +| [`GetResourceName`](/dev/reference/apis/services/vision/#close) | Get the ResourceName for this Resource with the given name. | +| [`Close`](/dev/reference/apis/services/vision/#close) | Safely shut down the resource and prevent further use. | diff --git a/static/include/services/apis/generated/world_state_store.md b/static/include/services/apis/generated/world_state_store.md new file mode 100644 index 0000000000..5902ce9c8e --- /dev/null +++ b/static/include/services/apis/generated/world_state_store.md @@ -0,0 +1,309 @@ +### listUUIDs + +List all world state transform UUIDs. + +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- `extra` (Mapping[[str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str), Any]) (optional): Extra options to pass to the underlying RPC call. +- `timeout` ([float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (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](https://docs.python.org/3/library/stdtypes.html#bytes-objects)]) + +**Example:** + +```python {class="line-numbers linkable-line-numbers"} +worldstatestore = WorldStateStoreClient.from_robot(robot=machine, name="builtin") + +uuids = await worldstatestore.list_uuids() +``` + +For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/services/worldstatestore/index.html#viam.services.worldstatestore.WorldStateStore.list_uuids). + +{{% /tab %}} +{{% tab name="TypeScript" %}} + +**Parameters:** + +- `extra` (None) (optional): Additional arguments to the method. +- `callOptions` (CallOptions) (optional) + +**Returns:** + +- (Promise) + +**Example:** + +```ts {class="line-numbers linkable-line-numbers"} +const worldStateStore = new VIAM.WorldStateStoreClient( + machine, + 'builtin' +); + +// Get all transform UUIDs +const uuids = await worldStateStore.listUUIDs(); +``` + +For more information, see the [TypeScript SDK Docs](https://ts.viam.dev/classes/WorldStateStoreClient.html#listuuids). + +{{% /tab %}} +{{< /tabs >}} + +### GetTransform + +Get a world state transform by UUID. + +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- `uuid` ([bytes](https://docs.python.org/3/library/stdtypes.html#bytes-objects)) (required): The UUID of the transform to retrieve. +- `extra` (Mapping[[str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str), Any]) (optional): Extra options to pass to the underlying RPC call. +- `timeout` ([float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (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](https://python.viam.dev/autoapi/viam/proto/common/index.html#viam.proto.common.Transform)) + +**Example:** + +```python {class="line-numbers linkable-line-numbers"} +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](https://python.viam.dev/autoapi/viam/services/worldstatestore/index.html#viam.services.worldstatestore.WorldStateStore.get_transform). + +{{% /tab %}} +{{% tab name="TypeScript" %}} + +**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](https://ts.viam.dev/interfaces/TransformWithUUID-1.html)>) + +**Example:** + +```ts {class="line-numbers linkable-line-numbers"} +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](https://ts.viam.dev/classes/WorldStateStoreClient.html#gettransform). + +{{% /tab %}} +{{< /tabs >}} + +### StreamTransformChanges + +Stream changes to world state transforms. + +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- `extra` (Mapping[[str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str), Any]) (optional): Extra options to pass to the underlying RPC call. +- `timeout` ([float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (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]](https://python.viam.dev/autoapi/viam/proto/service/worldstatestore/index.html#viam.proto.service.worldstatestore.StreamTransformChangesResponse)) + +**Example:** + +```python {class="line-numbers linkable-line-numbers"} +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}") +``` + +For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/services/worldstatestore/index.html#viam.services.worldstatestore.WorldStateStore.stream_transform_changes). + +{{% /tab %}} +{{% tab name="TypeScript" %}} + +**Parameters:** + +- `extra` (None) (optional): Additional arguments to the method. +- `callOptions` (CallOptions) (optional) + +**Returns:** + +- (AsyncGenerator<[TransformChangeEvent](https://ts.viam.dev/types/TransformChangeEvent.html), void>) + +**Example:** + +```ts {class="line-numbers linkable-line-numbers"} +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 + ); +} +``` + +For more information, see the [TypeScript SDK Docs](https://ts.viam.dev/classes/WorldStateStoreClient.html#streamtransformchanges). + +{{% /tab %}} +{{< /tabs >}} + +### 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`](/dev/reference/sdks/docommand/). + +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- `command` (Mapping[[str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str), ValueTypes]) (required): The command to execute. +- `timeout` ([float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (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](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str), viam.utils.ValueTypes]) + +**Example:** + +```python {class="line-numbers linkable-line-numbers"} +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](https://python.viam.dev/autoapi/viam/services/worldstatestore/index.html#viam.services.worldstatestore.WorldStateStore.do_command). + +{{% /tab %}} +{{% tab name="TypeScript" %}} + +**Parameters:** + +- `command` ([Struct](https://ts.viam.dev/classes/Struct.html)) (required): The command to execute. +- `callOptions` (CallOptions) (optional) + +**Returns:** + +- (Promise<[JsonValue](https://ts.viam.dev/types/JsonValue.html)>) + +**Example:** + +```ts {class="line-numbers linkable-line-numbers"} +import { Struct } from '@viamrobotics/sdk'; + +const result = await resource.doCommand( + Struct.fromJson({ + myCommand: { key: 'value' }, + }) +); +``` + +For more information, see the [TypeScript SDK Docs](https://ts.viam.dev/classes/WorldStateStoreClient.html#docommand). + +{{% /tab %}} +{{< /tabs >}} + +### GetResourceName + +Get the ResourceName for this Resource with the given name. + +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- `name` ([str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): The name of the Resource. + +**Returns:** + +- ([viam.proto.common.ResourceName](https://python.viam.dev/autoapi/viam/proto/common/index.html#viam.proto.common.ResourceName)): The ResourceName of this Resource. + +**Example:** + +```python {class="line-numbers linkable-line-numbers"} +my_world_state_store_svc_name = WorldStateStoreClient.get_resource_name("my_world_state_store_svc") +``` + +For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/services/worldstatestore/index.html#viam.services.worldstatestore.WorldStateStore.get_resource_name). + +{{% /tab %}} +{{% tab name="TypeScript" %}} + +**Parameters:** + +- None. + +**Returns:** + +- (string): The name of the resource. + +**Example:** + +```ts {class="line-numbers linkable-line-numbers"} +world_state_store.name +``` + +For more information, see the [TypeScript SDK Docs](https://ts.viam.dev/classes/WorldStateStoreClient.html#name). + +{{% /tab %}} +{{< /tabs >}} + +### Close + +Safely shut down the resource and prevent further use. + +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- None. + +**Returns:** + +- None. + +**Example:** + +```python {class="line-numbers linkable-line-numbers"} +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](https://python.viam.dev/autoapi/viam/services/worldstatestore/index.html#viam.services.worldstatestore.WorldStateStore.close). + +{{% /tab %}} +{{< /tabs >}} diff --git a/static/include/services/apis/overrides/protos/world_state_store.DoCommand.md b/static/include/services/apis/overrides/protos/world_state_store.DoCommand.md new file mode 100644 index 0000000000..90eddcf335 --- /dev/null +++ b/static/include/services/apis/overrides/protos/world_state_store.DoCommand.md @@ -0,0 +1,4 @@ +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`](/dev/reference/sdks/docommand/). diff --git a/static/include/services/apis/overrides/protos/world_state_store.GetOperation.md b/static/include/services/apis/overrides/protos/world_state_store.GetOperation.md new file mode 100644 index 0000000000..91e02c0e49 --- /dev/null +++ b/static/include/services/apis/overrides/protos/world_state_store.GetOperation.md @@ -0,0 +1,3 @@ +Get the Operation associated with the currently running function. + +When writing custom resources, you should get the Operation by calling this function and check to see if it’s cancelled. If the Operation is cancelled, then you can perform any necessary operations such as, for example, terminating long running tasks or cleaning up connections. diff --git a/static/include/services/apis/overrides/protos/world_state_store.GetResourceName.md b/static/include/services/apis/overrides/protos/world_state_store.GetResourceName.md new file mode 100644 index 0000000000..1e9e736f6e --- /dev/null +++ b/static/include/services/apis/overrides/protos/world_state_store.GetResourceName.md @@ -0,0 +1 @@ +Get the ResourceName for this Resource with the given name. diff --git a/static/include/services/apis/overrides/protos/world_state_store.GetTransform.md b/static/include/services/apis/overrides/protos/world_state_store.GetTransform.md new file mode 100644 index 0000000000..213d06b599 --- /dev/null +++ b/static/include/services/apis/overrides/protos/world_state_store.GetTransform.md @@ -0,0 +1 @@ +Get a world state transform by UUID. diff --git a/static/include/services/apis/overrides/protos/world_state_store.ListUUIDs.md b/static/include/services/apis/overrides/protos/world_state_store.ListUUIDs.md new file mode 100644 index 0000000000..679c53de17 --- /dev/null +++ b/static/include/services/apis/overrides/protos/world_state_store.ListUUIDs.md @@ -0,0 +1 @@ +List all world state transform UUIDs. diff --git a/static/include/services/apis/overrides/protos/world_state_store.StreamTransformChanges.md b/static/include/services/apis/overrides/protos/world_state_store.StreamTransformChanges.md new file mode 100644 index 0000000000..7cda52e1cd --- /dev/null +++ b/static/include/services/apis/overrides/protos/world_state_store.StreamTransformChanges.md @@ -0,0 +1 @@ +Stream changes to world state transforms. diff --git a/static/include/services/apis/overrides/protos/world_state_store.close.md b/static/include/services/apis/overrides/protos/world_state_store.close.md new file mode 100644 index 0000000000..7d7da2dbf3 --- /dev/null +++ b/static/include/services/apis/overrides/protos/world_state_store.close.md @@ -0,0 +1 @@ +Safely shut down the resource and prevent further use.