DOCS-1876: Add examples for ML and vision services (#547)

Author: skyleilani

src/viam/services/mlmodel/mlmodel.py

@@ -26,6 +26,17 @@ class MLModel(ServiceBase):
     async def infer(self, input_tensors: Dict[str, NDArray], *, timeout: Optional[float]) -> Dict[str, NDArray]:
         """Take an already ordered input tensor as an array, make an inference on the model, and return an output tensor map.
 
+        ::
+
+            import numpy as np
+
+            my_mlmodel = MLModelClient.from_robot(robot=robot, name="my_mlmodel_service")
+
+            nd_array = np.array([1, 2, 3], dtype=np.float64)
+            input_tensors = {"0": nd_array}
+
+            output_tensors = await my_mlmodel.infer(input_tensors)
+
         Args:
             input_tensors (Dict[str, NDArray]): A dictionary of input flat tensors as specified in the metadata
 
@@ -38,6 +49,12 @@ async def infer(self, input_tensors: Dict[str, NDArray], *, timeout: Optional[fl
     async def metadata(self, *, timeout: Optional[float]) -> Metadata:
         """Get the metadata (such as name, type, expected tensor/array shape, inputs, and outputs) associated with the ML model.
 
+        ::
+
+            my_mlmodel = MLModelClient.from_robot(robot=robot, name="my_mlmodel_service")
+
+            metadata = await my_mlmodel.metadata()
+
         Returns:
             Metadata: The metadata
         """

src/viam/services/vision/vision.py

@@ -34,6 +34,16 @@ async def get_detections_from_camera(
     ) -> List[Detection]:
         """Get a list of detections in the next image given a camera and a detector
 
+        ::
+
+            camera_name = "cam1"
+
+            # Grab the detector you configured on your machine
+            my_detector = VisionClient.from_robot(robot, "my_detector")
+
+            # Get detections from the next image from the camera
+            detections = await my_detector.get_detections_from_camera(camera_name)
+
         Args:
             camera_name (str): The name of the camera to use for detection
 
@@ -54,6 +64,20 @@ async def get_detections(
     ) -> List[Detection]:
         """Get a list of detections in the given image using the specified detector
 
+        ::
+
+            # Grab camera from the machine
+            cam1 = Camera.from_robot(robot, "cam1")
+
+            # Get the detector you configured on your machine
+            my_detector = VisionClient.from_robot(robot, "my_detector")
+
+            # Get an image from the camera
+            img = await cam1.get_image()
+
+            # Get detections from that image
+            detections = await my_detector.get_detections(img)
+
         Args:
             image (Image): The image to get detections from
 
@@ -75,6 +99,17 @@ async def get_classifications_from_camera(
     ) -> List[Classification]:
         """Get a list of classifications in the next image given a camera and a classifier
 
+        ::
+
+            camera_name = "cam1"
+
+            # Grab the classifier you configured on your machine
+            my_classifier = VisionClient.from_robot(robot, "my_classifier")
+
+            # Get the 2 classifications with the highest confidence scores from the next image from the camera
+            classifications = await my_classifier.get_classifications_from_camera(
+                camera_name, 2)
+
         Args:
             camera_name (str): The name of the camera to use for detection
             count (int): The number of classifications desired
@@ -95,6 +130,20 @@ async def get_classifications(
     ) -> List[Classification]:
         """Get a list of classifications in the given image using the specified classifier
 
+        ::
+
+            # Grab camera from the machine
+            cam1 = Camera.from_robot(robot, "cam1")
+
+            # Get the classifier you configured on your machine
+            my_classifier = VisionClient.from_robot(robot, "my_classifier")
+
+            # Get an image from the camera
+            img = await cam1.get_image()
+
+            # Get the 2 classifications with the highest confidence scores
+            classifications = await my_classifier.get_classifications(img, 2)
+
         Args:
             image (Image): The image to get detections from
             count (int): The number of classifications desired
@@ -117,16 +166,21 @@ async def get_object_point_clouds(
         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
 
-            object_point_clouds = await vision.get_object_point_clouds(camera_name, segmenter_name)
-
+            # Grab the 3D camera from the machine
+            cam1 = Camera.from_robot(robot, "cam1")
+            # Grab the object segmenter you configured on your machine
+            my_segmenter = VisionClient.from_robot(robot, "my_segmenter")
+            # Get the objects from the camera output
+            objects = await my_segmenter.get_object_point_clouds(cam1)
             # write the first object point cloud into a temporary file
             with open("/tmp/pointcloud_data.pcd", "wb") as f:
-                f.write(object_point_clouds[0].point_cloud)
+                f.write(objects[0].point_cloud)
             pcd = o3d.io.read_point_cloud("/tmp/pointcloud_data.pcd")
             points = np.asarray(pcd.points)