viam-sdk 0.45.2__py3-none-win_amd64.whl

viam/services/service_base.py

@@ -0,0 +1,78 @@
+import abc
+from logging import Logger
+from typing import TYPE_CHECKING, ClassVar, Mapping, Optional, cast
+
+from typing_extensions import Self
+
+from viam.logging import getLogger
+from viam.resource.base import ResourceBase
+from viam.utils import ValueTypes
+
+if TYPE_CHECKING:
+    from viam.resource.types import API
+    from viam.robot.client import RobotClient
+
+
+class ServiceBase(abc.ABC, ResourceBase):
+    """This class describes the base functionality required for a Viam Service.
+    All services must inherit from this class.
+    """
+
+    API: ClassVar["API"]
+
+    def __init__(self, name: str, *, logger: Optional[Logger] = None) -> None:
+        self.name = name
+        self.logger = logger if logger is not None else getLogger(f"{self.API}.{name}")
+
+    @classmethod
+    def from_robot(cls, robot: "RobotClient", name: str) -> Self:
+        """Get the service named ``name`` from the provided robot.
+
+        ::
+
+            async def connect() -> RobotClient:
+                # Replace "<API-KEY>" (including brackets) with your API key and "<API-KEY-ID>" with your API key ID
+                options = RobotClient.Options.with_api_key("<API-KEY>", "<API-KEY-ID>")
+                # Replace "<MACHINE-URL>" (included brackets) with your machine's connection URL or FQDN
+                return await RobotClient.at_address("<MACHINE-URL>", options)
+
+            async def main():
+                robot = await connect()
+
+                # Can be used with any resource, using the motion service as an example
+                motion = MotionClient.from_robot(robot=machine, name="builtin")
+
+                robot.close()
+
+        Args:
+            robot (RobotClient): The robot
+            name (str): The name of the service
+
+        Returns:
+            Self: The service, if it exists on the robot
+        """
+        service = robot.get_service(cls.get_resource_name(name))
+        return cast(cls, service)  # type: ignore
+
+    async def do_command(self, command: Mapping[str, ValueTypes], *, timeout: Optional[float] = None, **kwargs) -> Mapping[str, ValueTypes]:
+        """Send/receive arbitrary commands.
+
+        ::
+
+            service = SERVICE.from_robot(robot=machine, "builtin")  # replace SERVICE with the appropriate class
+
+            my_command = {
+              "cmnd": "dosomething",
+              "someparameter": 52
+            }
+
+            # Can be used with any resource, using the motion service as an example
+            await service.do_command(command=my_command)
+
+        Args:
+            command (Dict[str, ValueTypes]): The command to execute
+
+        Returns:
+            Dict[str, ValueTypes]: Result of the executed command
+        """
+        raise NotImplementedError()

viam/services/service_client_base.py

@@ -0,0 +1,46 @@
+import abc
+from typing import TYPE_CHECKING, ClassVar, Mapping, Optional
+
+from grpclib.client import Channel
+from typing_extensions import Self
+
+from viam.errors import ResourceNotFoundError
+from viam.proto.common import ResourceName
+from viam.resource.base import API, ResourceBase
+from viam.utils import ValueTypes
+
+if TYPE_CHECKING:
+    from viam.robot.client import RobotClient
+
+
+class ServiceClientBase(abc.ABC, ResourceBase):
+    """
+    Base service client.
+    All service clients must inherit from this class.
+    """
+
+    API: ClassVar[API]
+    channel: Channel
+
+    def __init__(self, name: str, channel: Channel):
+        self.name = name
+        self.channel = channel
+
+    @classmethod
+    def from_robot(cls, robot: "RobotClient", name: str = "builtin") -> Self:
+        """Get the service client named ``name`` from the provided robot.
+
+        Args:
+            robot (RobotClient): The robot
+            name (str): The name of the service client
+
+        Returns:
+            Self: The service client, if it exists on the robot
+        """
+        resource_name = ResourceName(namespace="rdk", type="service", subtype=cls.API.resource_subtype, name=name)
+        if resource_name not in robot.resource_names:
+            raise ResourceNotFoundError(resource_name.subtype, resource_name.name)
+        return cls(name, robot._channel)
+
+    async def do_command(self, command: Mapping[str, ValueTypes], *, timeout: Optional[float] = None, **kwargs) -> Mapping[str, ValueTypes]:
+        raise NotImplementedError()

viam/services/slam/__init__.py

@@ -0,0 +1,17 @@
+from viam.proto.common import Pose
+from viam.proto.service.slam import MappingMode, SensorInfo
+from viam.resource.registry import Registry, ResourceRegistration
+
+from .client import SLAMClient
+from .service import SLAMRPCService
+from .slam import SLAM
+
+__all__ = [
+    "Pose",
+    "MappingMode",
+    "SensorInfo",
+    "SLAMClient",
+    "SLAM",
+]
+
+Registry.register_api(ResourceRegistration(SLAM, SLAMRPCService, lambda name, channel: SLAMClient(name, channel)))

viam/services/slam/client.py

@@ -0,0 +1,62 @@
+from typing import List, Mapping, Optional
+
+from grpclib.client import Channel
+
+from viam.proto.common import DoCommandRequest, DoCommandResponse
+from viam.proto.service.slam import (
+    GetInternalStateRequest,
+    GetInternalStateResponse,
+    GetPointCloudMapRequest,
+    GetPointCloudMapResponse,
+    GetPositionRequest,
+    GetPositionResponse,
+    GetPropertiesRequest,
+    SLAMServiceStub,
+)
+from viam.resource.rpc_client_base import ReconfigurableResourceRPCClientBase
+from viam.utils import ValueTypes, dict_to_struct, struct_to_dict
+
+from . import Pose
+from .slam import SLAM
+
+
+class SLAMClient(SLAM, ReconfigurableResourceRPCClientBase):
+    """
+    Connect to the SLAMService, which allows the robot to create a map of its surroundings and find its location in that map.
+    """
+
+    client: SLAMServiceStub
+
+    def __init__(self, name: str, channel: Channel):
+        self.channel = channel
+        self.client = SLAMServiceStub(channel)
+        super().__init__(name)
+
+    async def get_position(self, *, timeout: Optional[float] = None, **kwargs) -> Pose:
+        md = kwargs.get("metadata", self.Metadata()).proto
+        request = GetPositionRequest(name=self.name)
+        response: GetPositionResponse = await self.client.GetPosition(request, timeout=timeout, metadata=md)
+        return response.pose
+
+    async def get_point_cloud_map(self, return_edited_map: bool = False, *, timeout: Optional[float] = None, **kwargs) -> List[bytes]:
+        md = kwargs.get("metadata", self.Metadata()).proto
+        request = GetPointCloudMapRequest(name=self.name, return_edited_map=return_edited_map)
+        response: List[GetPointCloudMapResponse] = await self.client.GetPointCloudMap(request, timeout=timeout, metadata=md)
+        return [r.point_cloud_pcd_chunk for r in response]
+
+    async def get_internal_state(self, *, timeout: Optional[float] = None, **kwargs) -> List[bytes]:
+        md = kwargs.get("metadata", self.Metadata()).proto
+        request = GetInternalStateRequest(name=self.name)
+        response: List[GetInternalStateResponse] = await self.client.GetInternalState(request, timeout=timeout, metadata=md)
+        return [r.internal_state_chunk for r in response]
+
+    async def get_properties(self, *, timeout: Optional[float] = None, **kwargs) -> SLAM.Properties:
+        md = kwargs.get("metadata", self.Metadata()).proto
+        request = GetPropertiesRequest(name=self.name)
+        return await self.client.GetProperties(request, timeout=timeout, metadata=md)
+
+    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/slam/service.py

@@ -0,0 +1,75 @@
+from grpclib.server import Stream
+
+from viam.proto.common import DoCommandRequest, DoCommandResponse
+from viam.proto.service.slam import (
+    GetInternalStateRequest,
+    GetInternalStateResponse,
+    GetPointCloudMapRequest,
+    GetPointCloudMapResponse,
+    GetPositionRequest,
+    GetPositionResponse,
+    GetPropertiesRequest,
+    GetPropertiesResponse,
+    SLAMServiceBase,
+)
+from viam.resource.rpc_service_base import ResourceRPCServiceBase
+from viam.utils import dict_to_struct, struct_to_dict
+
+from .slam import SLAM
+
+
+class SLAMRPCService(SLAMServiceBase, ResourceRPCServiceBase):
+    """
+    gRPC Service for a SLAM service
+    """
+
+    RESOURCE_TYPE = SLAM
+
+    async def GetInternalState(self, stream: Stream[GetInternalStateRequest, GetInternalStateResponse]) -> None:
+        request = await stream.recv_message()
+        assert request is not None
+        name = request.name
+        slam = self.get_resource(name)
+        timeout = stream.deadline.time_remaining() if stream.deadline else None
+        chunks = await slam.get_internal_state(timeout=timeout)
+        for chunk in chunks:
+            response = GetInternalStateResponse(internal_state_chunk=chunk)
+            await stream.send_message(response)
+
+    async def GetPointCloudMap(self, stream: Stream[GetPointCloudMapRequest, GetPointCloudMapResponse]) -> None:
+        request = await stream.recv_message()
+        assert request is not None
+        name = request.name
+        slam = self.get_resource(name)
+        timeout = stream.deadline.time_remaining() if stream.deadline else None
+        chunks = await slam.get_point_cloud_map(return_edited_map=request.return_edited_map, timeout=timeout)
+        for chunk in chunks:
+            response = GetPointCloudMapResponse(point_cloud_pcd_chunk=chunk)
+            await stream.send_message(response)
+
+    async def GetPosition(self, stream: Stream[GetPositionRequest, GetPositionResponse]) -> None:
+        request = await stream.recv_message()
+        assert request is not None
+        name = request.name
+        slam = self.get_resource(name)
+        timeout = stream.deadline.time_remaining() if stream.deadline else None
+        position = await slam.get_position(timeout=timeout)
+        response = GetPositionResponse(pose=position)
+        await stream.send_message(response)
+
+    async def GetProperties(self, stream: Stream[GetPropertiesRequest, GetPropertiesResponse]) -> None:
+        request = await stream.recv_message()
+        assert request is not None
+        slam = self.get_resource(request.name)
+        timeout = stream.deadline.time_remaining() if stream.deadline else None
+        properties = await slam.get_properties(timeout=timeout)
+        await stream.send_message(properties)
+
+    async def DoCommand(self, stream: Stream[DoCommandRequest, DoCommandResponse]) -> None:
+        request = await stream.recv_message()
+        assert request is not None
+        slam = self.get_resource(request.name)
+        timeout = stream.deadline.time_remaining() if stream.deadline else None
+        result = await slam.do_command(command=struct_to_dict(request.command), timeout=timeout, metadata=stream.metadata)
+        response = DoCommandResponse(result=dict_to_struct(result))
+        await stream.send_message(response)

viam/services/slam/slam.py

@@ -0,0 +1,111 @@
+import abc
+import sys
+from typing import Final, List, Optional
+
+from viam.proto.service.slam import GetPropertiesResponse
+from viam.resource.types import API, RESOURCE_NAMESPACE_RDK, RESOURCE_TYPE_SERVICE
+
+from ..service_base import ServiceBase
+from . import Pose
+
+if sys.version_info >= (3, 10):
+    from typing import TypeAlias
+else:
+    from typing_extensions import TypeAlias
+
+
+class SLAM(ServiceBase):
+    """
+    SLAM represents a SLAM service.
+
+    This acts as an abstract base class for any drivers representing specific
+    arm 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 `SLAM service <https://docs.viam.com/dev/reference/apis/services/slam/>`_.
+    """
+
+    API: Final = API(RESOURCE_NAMESPACE_RDK, RESOURCE_TYPE_SERVICE, "slam")  # pyright: ignore [reportIncompatibleVariableOverride]
+
+    Properties: "TypeAlias" = GetPropertiesResponse
+
+    @abc.abstractmethod
+    async def get_internal_state(self, *, timeout: Optional[float]) -> List[bytes]:
+        """
+        Get the internal state of the SLAM algorithm required to continue mapping/localization.
+
+        ::
+
+            slam = SLAMClient.from_robot(robot=machine, name="my_slam_service")
+
+            # Get the internal state of the SLAM algorithm required to continue mapping/localization.
+            internal_state = await slam.get_internal_state()
+
+        Returns:
+            List[GetInternalStateResponse]: Chunks of the internal state of the SLAM algorithm
+
+        For more information, see `SLAM service <https://docs.viam.com/dev/reference/apis/services/slam/#getinternalstate>`_.
+        """
+        ...
+
+    @abc.abstractmethod
+    async def get_point_cloud_map(self, return_edited_map: bool = False, *, timeout: Optional[float]) -> List[bytes]:
+        """
+        Get the point cloud map.
+
+        ::
+
+            slam_svc = SLAMClient.from_robot(robot=machine, name="my_slam_service")
+
+            # Get the point cloud map in standard PCD format.
+            pcd_map = await slam_svc.get_point_cloud_map()
+
+        Args:
+            return_edited_map (bool): signal to the SLAM service to return an edited map, if the map package contains one and if
+                the SLAM service supports the feature
+
+        Returns:
+            List[GetPointCloudMapResponse]: Complete pointcloud in standard PCD format. Chunks of the PointCloud, concatenating all
+            GetPointCloudMapResponse.point_cloud_pcd_chunk values.
+
+        For more information, see `SLAM service <https://docs.viam.com/dev/reference/apis/services/slam/#getpointcloudmap>`_.
+        """
+        ...
+
+    @abc.abstractmethod
+    async def get_position(self, *, timeout: Optional[float]) -> Pose:
+        """
+        Get current position of the specified component in the SLAM Map.
+
+        ::
+
+            slam_svc = SLAMClient.from_robot(robot=machine, name="my_slam_service")
+
+            # Get the current position of the specified source component in the SLAM map as a Pose.
+            pose = await slam.get_position()
+
+        Returns:
+            Pose: The current position of the specified component
+
+        For more information, see `SLAM service <https://docs.viam.com/dev/reference/apis/services/slam/#getposition>`_.
+        """
+        ...
+
+    @abc.abstractmethod
+    async def get_properties(self, *, timeout: Optional[float]) -> Properties:
+        """
+        Get information regarding the current SLAM session.
+
+        ::
+
+            slam_svc = SLAMClient.from_robot(robot=machine, name="my_slam_service")
+
+            # Get the properties of your current SLAM session.
+            slam_properties = await slam_svc.get_properties()
+
+        Returns:
+            Properties: The properties of SLAM
+
+        For more information, see `SLAM service <https://docs.viam.com/dev/reference/apis/services/slam/#getproperties>`_.
+        """
+        ...

viam/services/vision/__init__.py

@@ -0,0 +1,15 @@
+from viam.resource.registry import Registry, ResourceRegistration
+from viam.services.vision.service import VisionRPCService
+
+from .client import Classification, Detection, VisionClient
+from .vision import CaptureAllResult, Vision
+
+__all__ = [
+    "CaptureAllResult",
+    "Classification",
+    "Detection",
+    "VisionClient",
+    "Vision",
+]
+
+Registry.register_api(ResourceRegistration(Vision, VisionRPCService, lambda name, channel: VisionClient(name, channel)))

viam/services/vision/client.py

@@ -0,0 +1,206 @@
+from typing import Any, List, Mapping, Optional
+
+from grpclib.client import Channel
+
+from viam.errors import ViamError
+from viam.media.video import CameraMimeType, ViamImage
+from viam.proto.common import DoCommandRequest, DoCommandResponse, PointCloudObject
+from viam.proto.service.vision import (
+    CaptureAllFromCameraRequest,
+    CaptureAllFromCameraResponse,
+    Classification,
+    Detection,
+    GetClassificationsFromCameraRequest,
+    GetClassificationsFromCameraResponse,
+    GetClassificationsRequest,
+    GetClassificationsResponse,
+    GetDetectionsFromCameraRequest,
+    GetDetectionsFromCameraResponse,
+    GetDetectionsRequest,
+    GetDetectionsResponse,
+    GetObjectPointCloudsRequest,
+    GetObjectPointCloudsResponse,
+    GetPropertiesRequest,
+    GetPropertiesResponse,
+    VisionServiceStub,
+)
+from viam.resource.rpc_client_base import ReconfigurableResourceRPCClientBase
+from viam.utils import ValueTypes, dict_to_struct, struct_to_dict
+
+from .vision import CaptureAllResult, Vision
+
+
+class VisionClient(Vision, ReconfigurableResourceRPCClientBase):
+    """
+    Connect to the Vision service, which allows you to access various computer vision algorithms
+    (like detection, segmentation, tracking, etc) that usually only require a camera or image input.
+    """
+
+    client: VisionServiceStub
+
+    def __init__(self, name: str, channel: Channel):
+        super().__init__(name)
+        self.channel = channel
+        self.client = VisionServiceStub(channel)
+
+    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, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ) -> CaptureAllResult:
+        md = kwargs.get("metadata", self.Metadata()).proto
+        request = CaptureAllFromCameraRequest(
+            name=self.name,
+            camera_name=camera_name,
+            return_image=return_image,
+            return_classifications=return_classifications,
+            return_detections=return_detections,
+            return_object_point_clouds=return_object_point_clouds,
+            extra=dict_to_struct(extra),
+        )
+        response: CaptureAllFromCameraResponse = await self.client.CaptureAllFromCamera(request, timeout=timeout, metadata=md)
+        result = CaptureAllResult()
+        result.extra = struct_to_dict(response.extra)
+        if return_image:
+            mime_type = CameraMimeType.from_proto(response.image.format)
+            img = ViamImage(response.image.image, mime_type)
+            result.image = img
+        if return_classifications:
+            result.classifications = list(response.classifications)
+        if return_detections:
+            result.detections = list(response.detections)
+        if return_object_point_clouds:
+            result.objects = list(response.objects)
+        return result
+
+    async def get_detections_from_camera(
+        self,
+        camera_name: str,
+        *,
+        extra: Optional[Mapping[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ) -> List[Detection]:
+        md = kwargs.get("metadata", self.Metadata()).proto
+        request = GetDetectionsFromCameraRequest(name=self.name, camera_name=camera_name, extra=dict_to_struct(extra))
+        response: GetDetectionsFromCameraResponse = await self.client.GetDetectionsFromCamera(request, timeout=timeout, metadata=md)
+        return list(response.detections)
+
+    async def get_detections(
+        self,
+        image: ViamImage,
+        *,
+        extra: Optional[Mapping[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ) -> List[Detection]:
+        md = kwargs.get("metadata", self.Metadata()).proto
+        mime_type = CameraMimeType.JPEG
+
+        if image.width is None or image.height is None:
+            raise ViamError(f"image {image} needs to have a specified width and height")
+        else:
+            request = GetDetectionsRequest(
+                name=self.name,
+                image=image.data,
+                width=image.width,
+                height=image.height,
+                mime_type=mime_type,
+                extra=dict_to_struct(extra),
+            )
+        response: GetDetectionsResponse = await self.client.GetDetections(request, timeout=timeout, metadata=md)
+        return list(response.detections)
+
+    async def get_classifications_from_camera(
+        self,
+        camera_name: str,
+        count: int,
+        *,
+        extra: Optional[Mapping[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ) -> List[Classification]:
+        md = kwargs.get("metadata", self.Metadata()).proto
+        request = GetClassificationsFromCameraRequest(name=self.name, camera_name=camera_name, n=count, extra=dict_to_struct(extra))
+        response: GetClassificationsFromCameraResponse = await self.client.GetClassificationsFromCamera(
+            request, timeout=timeout, metadata=md
+        )
+        return list(response.classifications)
+
+    async def get_classifications(
+        self,
+        image: ViamImage,
+        count: int,
+        *,
+        extra: Optional[Mapping[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ) -> List[Classification]:
+        md = kwargs.get("metadata", self.Metadata()).proto
+
+        mime_type = CameraMimeType.JPEG
+        if image.width is None or image.height is None:
+            raise ViamError(f"image {image} needs to have a specified width and height")
+        request = GetClassificationsRequest(
+            name=self.name,
+            image=image.data,
+            width=image.width,
+            height=image.height,
+            mime_type=mime_type,
+            n=count,
+            extra=dict_to_struct(extra),
+        )
+        response: GetClassificationsResponse = await self.client.GetClassifications(request, timeout=timeout, metadata=md)
+        return list(response.classifications)
+
+    async def get_object_point_clouds(
+        self,
+        camera_name: str,
+        *,
+        extra: Optional[Mapping[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ) -> List[PointCloudObject]:
+        md = kwargs.get("metadata", self.Metadata()).proto
+        request = GetObjectPointCloudsRequest(
+            name=self.name,
+            camera_name=camera_name,
+            mime_type=CameraMimeType.PCD,
+            extra=dict_to_struct(extra),
+        )
+        response: GetObjectPointCloudsResponse = await self.client.GetObjectPointClouds(request, timeout=timeout, metadata=md)
+        return list(response.objects)
+
+    async def get_properties(
+        self,
+        *,
+        extra: Optional[Mapping[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ) -> Vision.Properties:
+        md = kwargs.get("metadata", self.Metadata()).proto
+        request = GetPropertiesRequest(
+            name=self.name,
+            extra=dict_to_struct(extra),
+        )
+        response: GetPropertiesResponse = await self.client.GetProperties(request, timeout=timeout, metadata=md)
+        return 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)