viam-sdk 0.3.0__py3-none-linux_armv6l.whl → 0.66.0__py3-none-linux_armv6l.whl

viam/services/vision/vision.py

@@ -0,0 +1,317 @@
+import abc
+import sys
+from typing import Final, List, Mapping, Optional
+
+from viam.media.video import ViamImage
+from viam.proto.common import PointCloudObject
+from viam.proto.service.vision import Classification, Detection, GetPropertiesResponse
+from viam.resource.types import API, RESOURCE_NAMESPACE_RDK, RESOURCE_TYPE_SERVICE
+from viam.utils import ValueTypes
+
+from ..service_base import ServiceBase
+
+if sys.version_info >= (3, 10):
+    from typing import TypeAlias
+else:
+    from typing_extensions import TypeAlias
+
+
+class CaptureAllResult:
+    """
+    CaptureAllResult represents the collection of things that you have requested from the
+    CaptureAllFromCamera method. This is used most often for visualization purposes, since normally,
+    returning the image on every call to a classifier/detector/etc would be costly and unnecessary.
+    The default result for each field is None rather than the empty list to distinguish between
+    "there was no request for the classifier/detector to return a result" vs.
+    "the classifier/detector was requested, but there were no results".
+    """
+
+    def __init__(
+        self,
+        image: Optional[ViamImage] = None,
+        classifications: Optional[List[Classification]] = None,
+        detections: Optional[List[Detection]] = None,
+        objects: Optional[List[PointCloudObject]] = None,
+        extra: Optional[Mapping[str, ValueTypes]] = None,
+    ):
+        """
+        Args:
+            image (ViamImage|None): The image from the GetImages request of the camera, if it was requested.
+            classifications (List[Classification]|None): The classifications from GetClassifications, if it was requested.
+            detections (List[Detection]|None): The detections from GetDetections, if it was requested.
+            objects (List[PointCloudObject]|None): the object point clouds from GetObjectPointClouds, if it was requested.
+            extra (dict): A catch all structure, usually for metadata, that a module writer might want to return. Default empty.
+
+        Returns:
+            None
+        """
+        self.image = image
+        self.classifications = classifications
+        self.detections = detections
+        self.objects = objects
+        self.extra = extra
+
+
+class Vision(ServiceBase):
+    """
+    Vision represents a Vision service.
+
+    This acts as an abstract base class for any drivers representing specific
+    vision implementations. This cannot be used on its own. If the ``__init__()`` function is
+    overridden, it must call the ``super().__init__()`` function.
+
+    For more information, see `Computer Vision service <https://docs.viam.com/dev/reference/apis/services/vision/>`_.
+    """
+
+    API: Final = API(  # pyright: ignore [reportIncompatibleVariableOverride]
+        RESOURCE_NAMESPACE_RDK, RESOURCE_TYPE_SERVICE, "vision"
+    )
+
+    Properties: "TypeAlias" = GetPropertiesResponse
+    """
+    Properties is a class that states what features are supported on the associated vision service.
+    Currently, these are the following properties:
+    - classifications_supported (bool): GetClassifications and GetClassificationsFromCamera are implemented.
+    - detections_supported (bool): GetDetections and GetDetectionsFromCamera are implemented.
+    - object_point_clouds_supported (bool): GetObjectPointClouds is implemented.
+    """
+
+    @abc.abstractmethod
+    async def capture_all_from_camera(
+        self,
+        camera_name: str,
+        return_image: bool = False,
+        return_classifications: bool = False,
+        return_detections: bool = False,
+        return_object_point_clouds: bool = False,
+        *,
+        extra: Optional[Mapping[str, ValueTypes]] = None,
+        timeout: Optional[float] = None,
+    ) -> CaptureAllResult:
+        """Get the next image, detections, classifications, and objects all together,
+        given a camera name. Used for visualization.
+
+        ::
+
+            my_detector = VisionClient.from_robot(machine, "my_detector")
+
+            # Get the captured data for a camera
+            result = await my_detector.capture_all_from_camera(
+                "my_camera",
+                return_image=True,
+                return_detections=True,
+            )
+            image = result.image
+            detections = result.detections
+
+        Args:
+            camera_name (str): The name of the camera to use for detection
+            return_image (bool): Ask the vision service to return the camera's latest image
+            return_classifications (bool): Ask the vision service to return its latest classifications
+            return_detections (bool): Ask the vision service to return its latest detections
+            return_object_point_clouds (bool): Ask the vision service to return its latest 3D segmentations
+
+        Returns:
+            vision.CaptureAllResult: A class that stores all potential returns from the vision service.
+            It can  return the image from the camera along with its associated detections, classifications,
+            and objects, as well as any extra info the model may provide.
+
+        For more information, see `Computer Vision service <https://docs.viam.com/dev/reference/apis/services/vision/#captureallfromcamera>`_.
+        """
+        ...
+
+    @abc.abstractmethod
+    async def get_detections_from_camera(
+        self,
+        camera_name: str,
+        *,
+        extra: Optional[Mapping[str, ValueTypes]] = None,
+        timeout: Optional[float] = None,
+    ) -> List[Detection]:
+        """Get a list of detections in the next image given a camera and a detector
+
+        ::
+
+            my_detector = VisionClient.from_robot(robot=machine, "my_detector")
+
+            # Get detections for the next image from the specified camera
+            detections = await my_detector.get_detections_from_camera("my_camera")
+
+        Args:
+            camera_name (str): The name of the camera to use for detection
+
+        Raises:
+            ViamError: Raised if given an image without a specified width and height
+
+        Returns:
+            List[viam.proto.service.vision.Detection]: A list of 2D bounding boxes, their labels, and the
+            confidence score of the labels, around the found objects in the next 2D image
+            from the given camera, with the given detector applied to it.
+
+        For more information, see `Computer Vision service <https://docs.viam.com/dev/reference/apis/services/vision/#getdetectionsfromcamera>`_.
+        """
+        ...
+
+    @abc.abstractmethod
+    async def get_detections(
+        self,
+        image: ViamImage,
+        *,
+        extra: Optional[Mapping[str, ValueTypes]] = None,
+        timeout: Optional[float] = None,
+    ) -> List[Detection]:
+        """Get a list of detections in the given image using the specified detector
+
+        ::
+
+            my_camera = Camera.from_robot(robot=machine, "my_camera")
+            my_detector = VisionClient.from_robot(robot=machine, "my_detector")
+
+            # Get an image from the camera
+            images, _ = await my_camera.get_images()
+            img = images[0]
+
+            # Get detections for that image
+            detections = await my_detector.get_detections(img)
+
+        Args:
+            image (ViamImage): The image to get detections for
+
+        Raises:
+            ViamError: Raised if given an image without a specified width and height
+
+        Returns:
+            List[viam.proto.service.vision.Detection]: A list of 2D bounding boxes, their labels, and the
+            confidence score of the labels, around the found objects in the next 2D image
+            from the given camera, with the given detector applied to it.
+
+        For more information, see `Computer Vision service <https://docs.viam.com/dev/reference/apis/services/vision/#getdetections>`_.
+        """
+        ...
+
+    @abc.abstractmethod
+    async def get_classifications_from_camera(
+        self,
+        camera_name: str,
+        count: int,
+        *,
+        extra: Optional[Mapping[str, ValueTypes]] = None,
+        timeout: Optional[float] = None,
+    ) -> List[Classification]:
+        """Get a list of classifications in the next image given a camera and a classifier
+
+        ::
+
+            my_classifier = VisionClient.from_robot(robot=machine, "my_classifier")
+
+            # Get the 2 classifications with the highest confidence scores for the next image from the camera
+            classifications = await my_classifier.get_classifications_from_camera(
+                "my_camera", 2)
+
+        Args:
+            camera_name (str): The name of the camera to use for detection
+            count (int): The number of classifications desired
+
+        returns:
+            List[viam.proto.service.vision.Classification]: The list of Classifications
+
+        For more information, see `Computer Vision service <https://docs.viam.com/dev/reference/apis/services/vision/#getclassificationsfromcamera>`_.
+        """
+        ...
+
+    @abc.abstractmethod
+    async def get_classifications(
+        self,
+        image: ViamImage,
+        count: int,
+        *,
+        extra: Optional[Mapping[str, ValueTypes]] = None,
+        timeout: Optional[float] = None,
+    ) -> List[Classification]:
+        """Get a list of classifications in the given image using the specified classifier
+
+        ::
+
+            my_camera = Camera.from_robot(robot=machine, "my_camera")
+            my_classifier = VisionClient.from_robot(robot=machine, "my_classifier")
+
+            # Get an image from the camera
+            images, _ = await my_camera.get_images()
+            img = images[0]
+
+            # Get the 2 classifications with the highest confidence scores for the image
+            classifications = await my_classifier.get_classifications(img, 2)
+
+        Args:
+            image (ViamImage): The image to get detections for
+            count (int): The number of classifications desired
+
+        Returns:
+            List[viam.proto.service.vision.Classification]: The list of Classifications
+
+        For more information, see `Computer Vision service <https://docs.viam.com/dev/reference/apis/services/vision/#getclassifications>`_.
+        """
+        ...
+
+    @abc.abstractmethod
+    async def get_object_point_clouds(
+        self,
+        camera_name: str,
+        *,
+        extra: Optional[Mapping[str, ValueTypes]] = None,
+        timeout: Optional[float] = None,
+    ) -> List[PointCloudObject]:
+        """
+        Returns a list of the 3D point cloud objects and associated metadata in the latest
+        picture obtained from the specified 3D camera (using the specified segmenter).
+
+        To deserialize the returned information into a numpy array, use the Open3D library.
+
+        ::
+
+            import numpy as np
+            import open3d as o3d
+
+            my_segmenter = VisionClient.from_robot(robot=machine, "my_segmenter")
+            # Get the objects from the camera output
+            objects = await my_segmenter.get_object_point_clouds("my_camera")
+            # write the first object point cloud into a temporary file
+            with open("/tmp/pointcloud_data.pcd", "wb") as f:
+                f.write(objects[0].point_cloud)
+            pcd = o3d.io.read_point_cloud("/tmp/pointcloud_data.pcd")
+            points = np.asarray(pcd.points)
+
+        Args:
+            camera_name (str): The name of the camera
+
+        Returns:
+            List[viam.proto.common.PointCloudObject]: The pointcloud objects with metadata
+
+        For more information, see `Computer Vision service <https://docs.viam.com/dev/reference/apis/services/vision/#getobjectpointclouds>`_.
+        """
+        ...
+
+    @abc.abstractmethod
+    async def get_properties(
+        self,
+        *,
+        extra: Optional[Mapping[str, ValueTypes]] = None,
+        timeout: Optional[float] = None,
+    ) -> Properties:
+        """
+        Get info about what vision methods the vision service provides. Currently returns boolean values that
+        state whether the service implements the classification, detection, and/or 3D object segmentation methods.
+
+        ::
+
+            my_detector = VisionClient.from_robot(robot=machine, "my_detector")
+            properties = await my_detector.get_properties()
+            detections_supported = properties.detections_supported
+            classifications_supported = properties.classifications_supported
+
+        Returns:
+            Properties: The properties of the vision service
+
+        For more information, see `Computer Vision service <https://docs.viam.com/dev/reference/apis/services/vision/#getproperties>`_.
+        """
+        ...

viam/services/worldstatestore/__init__.py

@@ -0,0 +1,18 @@
+from viam.proto.service.worldstatestore import StreamTransformChangesResponse, TransformChangeType
+from viam.resource.registry import Registry, ResourceRegistration
+
+from .client import WorldStateStoreClient
+from .service import WorldStateStoreService
+from .worldstatestore import WorldStateStore
+
+__all__ = [
+    "WorldStateStore",
+    "WorldStateStoreClient",
+    "WorldStateStoreService",
+    "StreamTransformChangesResponse",
+    "TransformChangeType",
+]
+
+Registry.register_api(
+    ResourceRegistration(WorldStateStore, WorldStateStoreService, lambda name, channel: WorldStateStoreClient(name, channel))
+)

viam/services/worldstatestore/client.py

@@ -0,0 +1,94 @@
+from typing import Any, AsyncGenerator, List, Mapping, Optional
+
+from grpclib.client import Channel
+
+from viam.proto.common import DoCommandRequest, DoCommandResponse, Transform
+from viam.proto.service.worldstatestore import (
+    GetTransformRequest,
+    GetTransformResponse,
+    ListUUIDsRequest,
+    ListUUIDsResponse,
+    StreamTransformChangesRequest,
+    StreamTransformChangesResponse,
+    WorldStateStoreServiceStub,
+)
+from viam.resource.rpc_client_base import ReconfigurableResourceRPCClientBase
+from viam.utils import ValueTypes, dict_to_struct, struct_to_dict
+
+from .worldstatestore import WorldStateStore
+
+
+class WorldStateStoreClient(WorldStateStore, ReconfigurableResourceRPCClientBase):
+    """
+    gRPC client for the WorldStateStore service.
+    """
+
+    client: WorldStateStoreServiceStub
+
+    def __init__(self, name: str, channel: Channel):
+        self.channel = channel
+        self.client = WorldStateStoreServiceStub(channel)
+        super().__init__(name)
+
+    async def list_uuids(
+        self,
+        *,
+        extra: Optional[Mapping[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ) -> List[bytes]:
+        md = kwargs.get("metadata", self.Metadata()).proto
+        request = ListUUIDsRequest(
+            name=self.name,
+            extra=dict_to_struct(extra),
+        )
+        response: ListUUIDsResponse = await self.client.ListUUIDs(request, timeout=timeout, metadata=md)
+        return list(response.uuids)
+
+    async def get_transform(
+        self,
+        uuid: bytes,
+        *,
+        extra: Optional[Mapping[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ) -> "Transform":
+        md = kwargs.get("metadata", self.Metadata()).proto
+        request = GetTransformRequest(
+            name=self.name,
+            uuid=uuid,
+            extra=dict_to_struct(extra),
+        )
+        response: GetTransformResponse = await self.client.GetTransform(request, timeout=timeout, metadata=md)
+        return response.transform
+
+    async def stream_transform_changes(
+        self,
+        *,
+        extra: Optional[Mapping[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ) -> AsyncGenerator[StreamTransformChangesResponse, None]:
+        md = kwargs.get("metadata", self.Metadata()).proto
+        request = StreamTransformChangesRequest(
+            name=self.name,
+            extra=dict_to_struct(extra),
+        )
+        responses = await self.client.StreamTransformChanges(request, timeout=timeout, metadata=md)
+        for response in responses:
+            yield response
+
+    async def do_command(
+        self,
+        command: Mapping[str, ValueTypes],
+        *,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ) -> Mapping[str, ValueTypes]:
+        md = kwargs.get("metadata", self.Metadata()).proto
+        request = DoCommandRequest(
+            name=self.name,
+            command=dict_to_struct(command),
+        )
+        response: DoCommandResponse = await self.client.DoCommand(request, timeout=timeout, metadata=md)
+        return struct_to_dict(response.result)

viam/services/worldstatestore/service.py

@@ -0,0 +1,55 @@
+from grpclib.server import Stream
+
+from viam.proto.common import DoCommandRequest, DoCommandResponse
+from viam.proto.service.worldstatestore import (
+    GetTransformRequest,
+    GetTransformResponse,
+    ListUUIDsRequest,
+    ListUUIDsResponse,
+    StreamTransformChangesRequest,
+    StreamTransformChangesResponse,
+    UnimplementedWorldStateStoreServiceBase,
+)
+from viam.resource.rpc_service_base import ResourceRPCServiceBase
+from viam.utils import dict_to_struct, struct_to_dict
+
+from .worldstatestore import WorldStateStore
+
+
+class WorldStateStoreService(UnimplementedWorldStateStoreServiceBase, ResourceRPCServiceBase[WorldStateStore]):
+    RESOURCE_TYPE = WorldStateStore
+
+    async def ListUUIDs(self, stream: Stream[ListUUIDsRequest, ListUUIDsResponse]) -> None:
+        request = await stream.recv_message()
+        assert request is not None
+        service = self.get_resource(request.name)
+        timeout = stream.deadline.time_remaining() if stream.deadline else None
+        uuids = await service.list_uuids(extra=struct_to_dict(request.extra), timeout=timeout)
+        await stream.send_message(ListUUIDsResponse(uuids=uuids))
+
+    async def GetTransform(self, stream: Stream[GetTransformRequest, GetTransformResponse]) -> None:
+        request = await stream.recv_message()
+        assert request is not None
+        service = self.get_resource(request.name)
+        timeout = stream.deadline.time_remaining() if stream.deadline else None
+        transform = await service.get_transform(uuid=request.uuid, extra=struct_to_dict(request.extra), timeout=timeout)
+        await stream.send_message(GetTransformResponse(transform=transform))
+
+    async def StreamTransformChanges(
+        self,
+        stream: Stream[StreamTransformChangesRequest, StreamTransformChangesResponse],
+    ) -> None:
+        request = await stream.recv_message()
+        assert request is not None
+        service = self.get_resource(request.name)
+        timeout = stream.deadline.time_remaining() if stream.deadline else None
+        async for change in service.stream_transform_changes(extra=struct_to_dict(request.extra), timeout=timeout):
+            await stream.send_message(change)
+
+    async def DoCommand(self, stream: Stream[DoCommandRequest, DoCommandResponse]) -> None:
+        request = await stream.recv_message()
+        assert request is not None
+        worldstatestore = self.get_resource(request.name)
+        timeout = stream.deadline.time_remaining() if stream.deadline else None
+        result = await worldstatestore.do_command(struct_to_dict(request.command), timeout=timeout)
+        await stream.send_message(DoCommandResponse(result=dict_to_struct(result)))

viam/services/worldstatestore/worldstatestore.py

@@ -0,0 +1,90 @@
+import abc
+from typing import Any, AsyncGenerator, Final, List, Mapping, Optional
+
+from viam.proto.common import Transform
+from viam.proto.service.worldstatestore import (
+    StreamTransformChangesResponse,
+)
+from viam.resource.types import API, RESOURCE_NAMESPACE_RDK, RESOURCE_TYPE_SERVICE
+
+from ..service_base import ServiceBase
+
+
+class WorldStateStore(ServiceBase):
+    """WorldStateStore is a Viam service that manages world state transforms.
+
+    The WorldStateStore service provides functionality to store, retrieve, and stream
+    changes to world state transforms, which represent the pose of objects in different
+    reference frames. This functionality can be used to create custom visualizations of the world state.
+
+    For more information, see `WorldStateStore service <https://docs.viam.com/dev/reference/apis/services/world-state-store/>`_.
+    """
+
+    API: Final = API(  # pyright: ignore [reportIncompatibleVariableOverride]
+        RESOURCE_NAMESPACE_RDK, RESOURCE_TYPE_SERVICE, "world_state_store"
+    )
+
+    @abc.abstractmethod
+    async def list_uuids(
+        self,
+        *,
+        extra: Optional[Mapping[str, Any]] = None,
+        timeout: Optional[float] = None,
+    ) -> List[bytes]:
+        """List all world state transform UUIDs.
+
+        ::
+
+            worldstatestore = WorldStateStoreClient.from_robot(robot=machine, name="builtin")
+
+            uuids = await worldstatestore.list_uuids()
+
+        Returns:
+            List[bytes]: A list of transform UUIDs
+        """
+        ...
+
+    @abc.abstractmethod
+    async def get_transform(
+        self,
+        uuid: bytes,
+        *,
+        extra: Optional[Mapping[str, Any]] = None,
+        timeout: Optional[float] = None,
+    ) -> Transform:
+        """Get a world state transform by UUID.
+
+        ::
+
+            worldstatestore = WorldStateStoreClient.from_robot(robot=machine, name="builtin")
+
+            transform = await worldstatestore.get_transform(uuid=b"some-uuid")
+
+        Args:
+            uuid (bytes): The UUID of the transform to retrieve
+
+        Returns:
+            Transform: The requested transform
+        """
+        ...
+
+    @abc.abstractmethod
+    async def stream_transform_changes(
+        self,
+        *,
+        extra: Optional[Mapping[str, Any]] = None,
+        timeout: Optional[float] = None,
+    ) -> AsyncGenerator[StreamTransformChangesResponse, None]:
+        """Stream changes to world state transforms.
+
+        ::
+
+            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}")
+
+        Returns:
+            AsyncGenerator[StreamTransformChangesResponse, None]: A stream of transform changes
+        """
+        ...