RSDK-12226 — Update documentation and tutorials to deprecate GetImage (part 2)

docs/data-ai/ai/alert.md

@@ -133,10 +133,9 @@ Configure data capture on the `filtered-camera` resource to capture images of de
    Locate the `objectfilter-cam` panel.
 
    Click **Add method**.
-   Click the **Type** dropdown and select **ReadImage**.
+   Click the **Type** dropdown and select **GetImages**.
    Set the capture frequency to `0.2` images per second (equivalent to one image every 5 seconds).
    You can adjust the frequency to suit your use case.
-   Set the **MIME type** to `image/jpeg`.
 
 ## Configure a trigger on your machine
 

docs/data-ai/capture-data/advanced/advanced-data-capture-sync.md

@@ -130,7 +130,7 @@ Avoid configuring data capture to higher rates than your hardware can handle, as
 {{< tabs >}}
 {{% tab name="viam-server" %}}
 
-This example configuration captures data from the `ReadImage` method of a camera:
+This example configuration captures data from the `GetImages` method of a camera:
 
 ```json {class="line-numbers linkable-line-numbers"}
 {
@@ -166,10 +166,9 @@ This example configuration captures data from the `ReadImage` method of a camera
               {
                 "capture_frequency_hz": 0.333,
                 "disabled": false,
-                "method": "ReadImage",
+                "method": "GetImages",
                 "additional_params": {
-                  "reader_name": "cam1",
-                  "mime_type": "image/jpeg"
+                  "reader_name": "cam1"
                 }
               }
             ],
@@ -350,7 +349,7 @@ The following attributes are available for data capture configuration:
 | `method` | string | **Required** | Depends on the type of component or service. See [Supported components and services](/data-ai/capture-data/capture-sync/#click-to-see-resources-that-support-data-capture-and-cloud-sync). **Note:** For tabular data, Viam enforces a maximum size of 4MB for any single reading. |
 | `retention_policy` | object | Optional | Option to configure how long data collected by this component or service should remain stored in the Viam Cloud. You must set this in JSON mode. See the JSON example for a camera component. <br> **Options:** `"days": <int>`, `"binary_limit_gb": <int>`, `"tabular_limit_gb": <int>`. <br> Days are in UTC time. Setting a retention policy of 1 day means that data stored now will be deleted the following day **in UTC time**. You can set either or both of the size limit options; size is in gigabytes. The `retention_policy` does not affect logs. For information about logs, see [Logging](/operate/reference/viam-server/#logging). |
 | `recent_data_store` | object | Optional | Configure a rolling time frame of recent data to store in a [hot data store](/data-ai/data/hot-data-store/) for faster access. Example: `{ "stored_hours": 24 }` |
-| `additional_params` | object | Optional | Varies based on the method. For example, `ReadImage` requires a MIME type and `DoCommand` requires `docommand_input` with an object of the command object to pass to `DoCommand`. |
+| `additional_params` | object | Optional | Varies based on the method. For example, `DoCommand` requires `docommand_input` with an object of the command object to pass to `DoCommand`, and `GetImages` can optionally intake a `filter_source_names` list of strings to indicate which source names to return images from. |
 | `disabled` | boolean | Optional | Whether data capture is disabled. |
 
 {{< /expand >}}
@@ -372,7 +371,7 @@ Each capture method object contains the following fields:
 | Key | Type | Description |
 | --- | ---- | ----------- |
 | `name` | string | The name specifies the fully qualified name of the part. Example: `"rdk:component:sensor/spacesensor"`. |
-| `additional_params` | Object | Varies based on the method. For example, `ReadImage` requires a MIME type and `DoCommand` requires `docommand_input` with an object of the command object to pass to `DoCommand`. |
+| `additional_params` | Object | Varies based on the method. For example, `DoCommand` requires `docommand_input` with an object of the command object to pass to `DoCommand`, and `GetImages` can optionally intake a `filter_source_names` list of strings to indicate which source names to return images from. |
 | `disabled` | boolean | Whether data capture for the method is disabled. |
 | `method` | string | Depends on the type of component or service. See [Supported components and services](/data-ai/capture-data/capture-sync/#click-to-see-resources-that-support-data-capture-and-cloud-sync). **Note:** For tabular data, Viam enforces a maximum size of 4MB for any single reading. |
 | `capture_frequency_hz` | float | Frequency in hertz at which to capture data. For example, to capture a reading every 2 seconds, enter `0.5`. |
@@ -506,7 +505,7 @@ The following example of a configuration with a remote part captures data from t
 
 {{< expand "Click to view the JSON configuration for capturing data from a camera" >}}
 
-The following example of a configuration with a remote part captures data from the `ReadImage` method of a camera:
+The following example of a configuration with a remote part captures data from the `GetImages` method of a camera:
 
 ```json {class="line-numbers linkable-line-numbers"}
 {
@@ -537,9 +536,9 @@ The following example of a configuration with a remote part captures data from t
                 "capture_frequency_hz": 1,
                 "name": "rdk:component:camera/cam",
                 "disabled": false,
-                "method": "ReadImage",
+                "method": "GetImages",
                 "additional_params": {
-                  "mime_type": "image/jpeg",
+                  "filter_source_names": ["color"],
                   "reader_name": "cam1"
                 }
               }

docs/data-ai/capture-data/capture-sync.md

@@ -70,13 +70,11 @@ For more information, see [How sync works](/data-ai/capture-data/advanced/how-sy
    {{< alert title="Camera capture methods" color="note" >}}
    Camera components provide two similar, but distinct capture methods:
 
-   - **GetImages** (recommended): Returns one image for each camera sensor as a JPEG (for color sensors) or point cloud (for depth sensors).
-   - **ReadImage**: Returns a single image in the specified MIME type, if the camera component supports that MIME type.
-     Prefer GetImages unless your use case requires a specific MIME type other than JPEG.
+   - **GetImages**: Returns an image per camera sensor for 3D cameras (for example, "color" as JPEG for RGB sensors, "depth" as a depth map for depth sensors), or a single image for webcams, RTSP cameras etc.
 
    {{< /alert >}}
 
-1. Set the capture **Frequency** in hertz, for example to `0.2` with `ReadImage` on a camera to capture an image every 5 seconds.
+1. Set the capture **Frequency** in hertz, for example to `0.2` with `GetImages` on a camera to capture an image every 5 seconds.
 1. **Save** your config.
 
 You can add multiple methods with different capture frequencies.

docs/data-ai/capture-data/conditional-sync.md

@@ -306,7 +306,7 @@ You have now configured sync to happen during a specific time slot.
 
 To test your setup, [configure a webcam](/operate/reference/components/camera/webcam/) or another component and [enable data capture on the component](/data-ai/capture-data/capture-sync/#configure-data-capture-and-sync-for-individual-resources).
 Make sure to physically connect any hardware parts to the computer controlling your machine.
-For a camera component, use the `ReadImage` method.
+For a camera component, use the `GetImages` method.
 The data manager will now capture data.
 Go to the [**CONTROL** tab](/manage/troubleshoot/teleoperate/default-interface/#web-ui).
 You should see the sensor.

docs/dev/reference/glossary/api-namespace-triplet.md

@@ -19,5 +19,5 @@ Each resource implements one and only one API.
 
 For example:
 
-- The API of the built-in component [camera](/operate/reference/components/camera/) is `rdk:component:camera`, which exposes methods such as `GetImage()`.
+- The API of the built-in component [camera](/operate/reference/components/camera/) is `rdk:component:camera`, which exposes methods such as `GetImages()`.
 - The API of the built-in service [vision](/operate/reference/services/vision/) is `rdk:service:vision`, which exposes methods such as `GetDetectionsFromCamera()`.

docs/manage/software/scheduled-jobs.md

@@ -110,7 +110,7 @@ Each job targets a specific resource on your machine and calls a designated comp
       "name": "daily-camera-capture",
       "schedule": "0 8 * * *",
       "resource": "camera1",
-      "method": "GetImage"
+      "method": "GetImages"
     },
     {
       "name": "periodic-sync",

docs/operate/modules/support-hardware/_index.md

@@ -152,8 +152,7 @@ See [Run control logic](/operate/modules/control-logic/) for more information.
 **Example module:** To choose the Viam [APIs](/dev/reference/apis/#component-apis) that make sense for your module, think about the functionality you want to implement.
 You need a way to return an image and you need a way to return a number.
 
-If you look at the [camera API](/dev/reference/apis/components/camera/), you can see the `GetImage` method, which returns an image.
-That will work for the image.
+If you look at the [camera API](/dev/reference/apis/components/camera/), you can see the `GetImages` method, which returns images from the camera.
 
 The camera API also has a few other methods.
 You do not need to fully implement all the methods of an API.

docs/operate/reference/components/camera/fake.md

@@ -57,7 +57,7 @@ The following attributes are available for `fake` cameras:
 | `width` | int | Optional | The width of the image in pixels. The maximum width is 10000. <br> Default: `1280` |
 | `height` | int | Optional | The height of the image in pixels. The maximum height is 10000. <br> Default: `720` |
 | `animated` | bool | Optional | If you want the camera stream visible on the **CONTROL** tab to be animated. <br> Default: `False` |
-| `rtp_passthrough` | bool | Optional | If true, `GetImage` will ignore width, height, and animated config params. Default: `False`. |
+| `rtp_passthrough` | bool | Optional | If true, `GetImages` will ignore width, height, and animated config params. Default: `False`. |
 | `model` | bool | Optional  | If true, provides `IntrinsicParams` and `DistortionParams` for the camera. Default: `False`. |
 
 ## View the camera stream

docs/tutorials/configure/pet-photographer.md

@@ -281,22 +281,29 @@ Now that you've included the required utility function and safeguard, your compl
 {{% tab name="Python"%}}
 
 ```python {class="line-numbers linkable-line-numbers"}
-async def get_image(
+async def get_images(
   self,
-  mime_type: str = "",
   *,
+  filter_source_names: Optional[Sequence[str]] = None,
   extra: Optional[Dict[str, Any]] = None,
   timeout: Optional[float] = None,
   **kwargs
-  ) -> Image.Image:
+  ) -> Tuple[Sequence[NamedImage], ResponseMetadata]:
     """Filters the output of the underlying camera"""
-    img = await self.actual_cam.get_image()
+    images, metadata = await self.actual_cam.get_images(
+        filter_source_names=filter_source_names,
+        extra=extra,
+        timeout=timeout,
+        **kwargs
+    )
     if from_dm_from_extra(extra):
-        detections = await self.vision_service.get_detections(img)
+        from viam.media.utils.pil import viam_to_pil_image
+        img_pil = viam_to_pil_image(images[0])
+        detections = await self.vision_service.get_detections(img_pil)
         if len(detections) == 0:
             raise NoCaptureToStoreError()
 
-    return img
+    return images, metadata
 ```
 
 If the data management service is the caller, the filter function requests detections from the vision service and returns the image if the specified color is detected.
@@ -365,6 +372,7 @@ from PIL import Image
 from viam.errors import NoCaptureToStoreError
 from viam.services.vision import Vision
 from viam.utils import from_dm_from_extra
+from viam.media.utils.pil import viam_to_pil_image
 
 
 class ColorFilterCam(
@@ -454,33 +462,31 @@ class ColorFilterCam(
         """Returns details about the camera"""
         return await self.actual_cam.get_properties()
 
-    async def get_image(
+    async def get_images(
               self,
-              mime_type: str = "",
               *,
+              filter_source_names: Optional[Sequence[str]] = None,
               extra: Optional[Dict[str, Any]] = None,
               timeout: Optional[float] = None,
               **kwargs
-    ) -> Image.Image:
+    ) -> Tuple[
+         List[NamedImage],
+         ResponseMetadata
+         ]:
         """Filters the output of the underlying camera"""
-        img = await self.actual_cam.get_image()
+        images, metadata = await self.actual_cam.get_images(
+            filter_source_names=filter_source_names,
+            extra=extra,
+            timeout=timeout,
+            **kwargs
+        )
         if from_dm_from_extra(extra):
-            detections = await self.vision_service.get_detections(img)
+            img_pil = viam_to_pil_image(images[0])
+            detections = await self.vision_service.get_detections(img_pil)
             if len(detections) == 0:
                 raise NoCaptureToStoreError()
 
-        return img
-
-    async def get_images(
-              self,
-              *,
-              timeout: Optional[float] = None,
-              **kwargs
-    ) -> Tuple[
-         List[NamedImage],
-         ResponseMetadata
-         ]:
-        raise NotImplementedError
+        return images, metadata
 
     async def get_point_cloud(
               self,
@@ -973,7 +979,7 @@ To add data capture for the color filter camera:
 
 1. Click **Add method** in the **Data capture** section of your color filter camera component.
 
-2. Toggle the **Method** dropdown menu, select **ReadImage**, and set the **Frequency** of the capture to `0.1`, which will configure the data management service to capture images from your camera once every 10 seconds.
+2. Toggle the **Method** dropdown menu, select **GetImages** (**ReadImage** is deprecated), and set the **Frequency** of the capture to `0.1`, which will configure the data management service to capture images from your camera once every 10 seconds.
 
 3. Click the **MIME type** dropdown and select `image/jpeg`.
 

docs/tutorials/projects/helmet.md

@@ -214,7 +214,7 @@ Configure data capture on the `objectfilter` camera to capture images of people
    Locate the `objectfilter-cam` panel.
 
 3. Click **Add method**.
-   Click the **Type** dropdown and select **ReadImage**.
+   Click the **Type** dropdown and select **GetImages**.
    Set the capture frequency to `0.2` images per second (equivalent to one image every 5 seconds).
    You can always change the frequency to suit your use case.
    Set the **MIME type** to `image/jpeg`.

static/include/app/apis/generated/data.md

@@ -30,7 +30,7 @@ tabular_data = await data_client.get_latest_tabular_data(
     part_id="77ae3145-7b91-123a-a234-e567cdca8910",
     resource_name="camera-1",
     resource_api="rdk:component:camera",
-    method_name="GetImage",
+    method_name="GetImages",
     additional_params={"docommand_input": {"test": "test"}}
 )
 

static/include/app/apis/generated/data_sync.md

@@ -82,7 +82,7 @@ const binaryDataId = await dataClient.binaryDataCaptureUpload(
   '123abc45-1234-5678-90ab-cdef12345678',
   'rdk:component:camera',
   'my-camera',
-  'ReadImage',
+  'GetImages',
   '.jpg',
   [new Date('2025-03-19'), new Date('2025-03-19')]
 );
@@ -133,7 +133,7 @@ _viam = await Viam.withApiKey(
      ".png",
      componentType: "rdk:component:camera",
      componentName: "camera-1",
-     methodName: "ReadImage",
+     methodName: "GetImages",
      dataRequestTimes: dataRequestTimes);
 
    print('Successfully uploaded binary data with binaryDataId: $binaryDataId');

static/include/components/apis/generated/camera.md

@@ -1,6 +1,7 @@
 ### GetImage
 
-_Deprecated_.
+_Deprecated. Use [`GetImages`](#getimages) instead._
+
 Return an image from the camera.
 You can request a specific MIME type but the returned MIME type is not guaranteed.
 If the server does not know how to return the specified MIME type, the server returns the image in another format instead.
@@ -183,15 +184,12 @@ For more information, see the [Flutter SDK Docs](https://flutter.viam.dev/viam_s
 ### GetImages
 
 {{% alert title="Usage" color="note" %}}
-Intended specifically for use with cameras that support simultaneous depth and color image streams, like the [Intel RealSense](https://app.viam.com/module/viam/realsense) or the [Luxonis OAK-D](https://app.viam.com/module/viam/oak-d).
-If your camera does not have multiple imagers, this method will work without capturing multiple images simultaneously.
-
 You can use the [`rgb-d-overlay` module](https://app.viam.com/module/viam/rgb-d-overlay) to view and compare the camera streams returned by this method.
 See the [module readme](https://github.com/viam-labs/rgb-d-overlay) for further instructions.
 {{% /alert %}}
 
-Get simultaneous images from different imagers, along with associated metadata.
-The multiple images returned from `GetImages()` do not represent a time series of images.
+`GetImages` is used for getting simultaneous images from different imagers from 3D cameras along with associated metadata, and single images from non-3D cameras, for example webcams, RTSP cameras, etc. in the image list in the response.
+Multiple images returned from `GetImages()` do not represent a time series of images.
 
 {{< tabs >}}
 {{% tab name="Python" %}}

static/include/components/apis/overrides/methods/python.camera.get_image.after.md

@@ -1,3 +1,5 @@
+_Deprecated. Use [`get_images`](#get_images) instead._
+
 If the `mime_type` of your image is `image/vnd.viam.dep`, pass the returned image data to the Viam Python SDK's [`ViamImage.bytes_to_depth_array()`](https://python.viam.dev/autoapi/viam/media/video/index.html#viam.media.video.ViamImage.bytes_to_depth_array) method to decode the raw image data to a standard 2D image representation.
 
 For example:

static/include/components/apis/overrides/protos/camera.GetImages.md

@@ -1,10 +1,8 @@
 {{% alert title="Usage" color="note" %}}
-Intended specifically for use with cameras that support simultaneous depth and color image streams, like the [Intel RealSense](https://app.viam.com/module/viam/realsense) or the [Luxonis OAK-D](https://app.viam.com/module/viam/oak-d).
-If your camera does not have multiple imagers, this method will work without capturing multiple images simultaneously.
 
 You can use the [`rgb-d-overlay` module](https://app.viam.com/module/viam/rgb-d-overlay) to view and compare the camera streams returned by this method.
 See the [module readme](https://github.com/viam-labs/rgb-d-overlay) for further instructions.
 {{% /alert %}}
 
-Get simultaneous images from different imagers, along with associated metadata.
-The multiple images returned from `GetImages()` do not represent a time series of images.
+`GetImages` is used for getting simultaneous images from different imagers from 3D cameras along with associated metadata, and single images from non-3D cameras, for example webcams, RTSP cameras, etc. in the image list in the response.
+Multiple images returned from `GetImages()` do not represent a time series of images.

static/include/data/capture-supported.md

@@ -8,7 +8,7 @@
 | [Base](/operate/reference/components/base/)                       | `Position`, `DoCommand` |
 | [Board](/operate/reference/components/board/)                     | `Analogs`, `Gpios`, `DoCommand` |
 | [Button](/operate/reference/components/button/)                   | `DoCommand` |
-| [Camera](/operate/reference/components/camera/)                   | `GetImages`, `ReadImage`, `NextPointCloud`, `DoCommand` |
+| [Camera](/operate/reference/components/camera/)                   | `GetImages`, `ReadImage` (deprecated), `NextPointCloud`, `DoCommand` |
 | [Encoder](/operate/reference/components/encoder/)                 | `TicksCount`, `DoCommand` |
 | [Gantry](/operate/reference/components/gantry/)                   | `Lengths`, `Position`, `DoCommand` |
 | [Gripper](/operate/reference/components/gripper/)                 | `DoCommand` |