Voxel Perception

The voxel perception utilities allow clients to sample sparse volumetric data around a specified region, which is useful for reinforcement learning and planning workloads.

Key Functions

• query_voxel: Capture a voxel buffer around a transform with configurable resolution and extents.

API References

tongsim.connection.grpc.unary_api.UnaryAPI.query_voxel async staticmethod

query_voxel(
    conn: GrpcConnection,
    transform: Transform,
    voxel_num_x: int,
    voxel_num_y: int,
    voxel_num_z: int,
    box_extent: Vector3,
    actors_to_ignore: list[str] | None = None,
    timeout: float = 5.0,
) -> bytes

Query voxel occupancy around a transform and return the raw buffer.

Parameters:

Name	Type	Description	Default
transform	Transform	World transform at the center of the volume.	required
voxel_num_x	int	Number of samples along the X axis.	required
voxel_num_y	int	Number of samples along the Y axis.	required
voxel_num_z	int	Number of samples along the Z axis.	required
box_extent	Vector3	Half-extent of the query box in world units.	required
actors_to_ignore	list[str] | None	Optional actor IDs excluded from sampling.	None
timeout	float	RPC timeout in seconds.	5.0

Returns:

Name	Type	Description
bytes	bytes	Serialized voxel data provided by the service.

Source code in src/tongsim/connection/grpc/unary_api.py

@staticmethod
@safe_async_rpc(default=None)
async def query_voxel(
    conn: GrpcConnection,
    transform: Transform,
    voxel_num_x: int,
    voxel_num_y: int,
    voxel_num_z: int,
    box_extent: Vector3,
    actors_to_ignore: list[str] | None = None,
    timeout: float = 5.0,
) -> bytes:
    """
    Query voxel occupancy around a transform and return the raw buffer.

    Args:
        transform (Transform): World transform at the center of the volume.
        voxel_num_x (int): Number of samples along the X axis.
        voxel_num_y (int): Number of samples along the Y axis.
        voxel_num_z (int): Number of samples along the Z axis.
        box_extent (Vector3): Half-extent of the query box in world units.
        actors_to_ignore (list[str] | None): Optional actor IDs excluded from sampling.
        timeout (float): RPC timeout in seconds.

    Returns:
        bytes: Serialized voxel data provided by the service.
    """
    if actors_to_ignore is None:
        actors_to_ignore = []

    stub = conn.get_stub(VoxelServiceStub)
    req = QueryVoxelRequest(
        transform=sdk_to_proto(transform),
        voxel_num_x=voxel_num_x,
        voxel_num_y=voxel_num_y,
        voxel_num_z=voxel_num_z,
        extent=sdk_to_proto(box_extent),
        ActorsToIgnore=[_to_object_id(actor_id) for actor_id in actors_to_ignore],
    )
    resp: Voxel = await stub.QueryVoxel(req, timeout=2.0)
    return resp.voxel_buffer