From 4b98abdcfeff213aa6a53ea29597c15cae0d6598 Mon Sep 17 00:00:00 2001 From: andf-viam <132301587+andf-viam@users.noreply.github.com> Date: Fri, 12 Jul 2024 05:40:12 -0400 Subject: [PATCH] DOCS-2349: Add CaptureAllFromCamera API (#3126) --- .github/workflows/sdk_protos_map.csv | 1 + .../services/apis/generated/vision-table.md | 1 + .../include/services/apis/generated/vision.md | 60 +++++++++++++++++++ ....CaptureAllFromCamera.VisCapture.return.md | 2 + ....vision.CaptureAllFromCamera.cameraName.md | 1 + .../go.vision.CaptureAllFromCamera.opts.md | 1 + .../protos/vision.CaptureAllFromCamera.md | 2 + 7 files changed, 68 insertions(+) create mode 100644 static/include/services/apis/overrides/methods/go.vision.CaptureAllFromCamera.VisCapture.return.md create mode 100644 static/include/services/apis/overrides/methods/go.vision.CaptureAllFromCamera.cameraName.md create mode 100644 static/include/services/apis/overrides/methods/go.vision.CaptureAllFromCamera.opts.md create mode 100644 static/include/services/apis/overrides/protos/vision.CaptureAllFromCamera.md diff --git a/.github/workflows/sdk_protos_map.csv b/.github/workflows/sdk_protos_map.csv index 7eef51997f..0567887f02 100644 --- a/.github/workflows/sdk_protos_map.csv +++ b/.github/workflows/sdk_protos_map.csv @@ -292,6 +292,7 @@ vision,GetDetections,get_detections,Detections,detections vision,GetClassificationsFromCamera,get_classifications_from_camera,ClassificationsFromCamera,classificationsFromCamera vision,GetClassifications,get_classifications,Classifications,classifications vision,GetObjectPointClouds,get_object_point_clouds,GetObjectPointClouds,objectPointClouds +vision,CaptureAllFromCamera,capture_all_from_camera,CaptureAllFromCamera, ## HACK: No proto for these (and/or inherited in Go SDK), manually mapping: vision,Reconfigure,,Reconfigure, vision,DoCommand,do_command,DoCommand,doCommand diff --git a/static/include/services/apis/generated/vision-table.md b/static/include/services/apis/generated/vision-table.md index 05f88b7c28..c7499a694c 100644 --- a/static/include/services/apis/generated/vision-table.md +++ b/static/include/services/apis/generated/vision-table.md @@ -6,6 +6,7 @@ | [`GetClassificationsFromCamera`](/services/vision/#getclassificationsfromcamera) | Get a list of classifications from the next image from a specified camera using a configured classifier. | | [`GetClassifications`](/services/vision/#getclassifications) | Get a list of classifications from a given image using a configured classifier. | | [`GetObjectPointClouds`](/services/vision/#getobjectpointclouds) | Get a list of 3D point cloud objects and associated metadata in the latest picture from a 3D camera (using a specified segmenter). | +| [`CaptureAllFromCamera`](/services/vision/#captureallfromcamera) | Get the next image, detections, classifications, and objects all together, given a camera name. | | [`Reconfigure`](/services/vision/#reconfigure) | Reconfigure this resource. | | [`DoCommand`](/services/vision/#docommand) | Execute model-specific commands that are not otherwise defined by the service API. | | [`FromRobot`](/services/vision/#fromrobot) | Get the resource from the provided robot with the given name. | diff --git a/static/include/services/apis/generated/vision.md b/static/include/services/apis/generated/vision.md index c3c5648872..63083c7a83 100644 --- a/static/include/services/apis/generated/vision.md +++ b/static/include/services/apis/generated/vision.md @@ -468,6 +468,66 @@ For more information, see the [Flutter SDK Docs](https://flutter.viam.dev/viam_s {{% /tab %}} {{< /tabs >}} +### CaptureAllFromCamera + +Get the next image, detections, classifications, and objects all together, given a camera name. +Used for visualization. + +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- `camera_name` ([str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): The name of the camera to use for detection. +- `return_image` ([bool](https://docs.python.org/3/library/stdtypes.html#boolean-type-bool)) (required): Ask the vision service to return the camera’s latest image. +- `return_classifications` ([bool](https://docs.python.org/3/library/stdtypes.html#boolean-type-bool)) (required): Ask the vision service to return its latest classifications. +- `return_detections` ([bool](https://docs.python.org/3/library/stdtypes.html#boolean-type-bool)) (required): Ask the vision service to return its latest detections. +- `return_object_point_clouds` ([bool](https://docs.python.org/3/library/stdtypes.html#boolean-type-bool)) (required): Ask the vision service to return its latest 3D segmentations. +- `extra` (Mapping[[str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str), Any]) (optional): Extra options to pass to the underlying RPC call. +- `timeout` ([float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call. + +**Returns:** + +- ([viam.services.vision.vision.CaptureAllResult](https://python.viam.dev/autoapi/viam/services/vision/vision/index.html#viam.services.vision.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. + +**Example:** + +```python {class="line-numbers linkable-line-numbers"} +camera_name = "cam1" + +# Grab the detector you configured on your machine +my_detector = VisionClient.from_robot(robot, "my_detector") + +# capture all from the next image from the camera +result = await my_detector.capture_all_from_camera( + camera_name, + return_image=True, + return_detections=True, +) +``` + +For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/services/vision/client/index.html#viam.services.vision.client.VisionClient.capture_all_from_camera). + +{{% /tab %}} +{{% tab name="Go" %}} + +**Parameters:** + +- `ctx` [(Context)](https://pkg.go.dev/context#Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries. +- `cameraName` [(string)](https://pkg.go.dev/builtin#string): The name of the camera to use for detection. +- `opts` [(viscapture.CaptureOptions)](https://pkg.go.dev/go.viam.com/rdk/vision/viscapture#CaptureOptions): Additional options to provide if desired. +- `extra` [(map[string]interface{})](https://go.dev/blog/maps): Extra options to pass to the underlying RPC call. + +**Returns:** + +- [(viscapture.VisCapture)](https://pkg.go.dev/go.viam.com/rdk/vision/viscapture#VisCapture): 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. +- [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred. + +For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/services/vision#Service). + +{{% /tab %}} +{{< /tabs >}} + ### Reconfigure Reconfigure this resource. diff --git a/static/include/services/apis/overrides/methods/go.vision.CaptureAllFromCamera.VisCapture.return.md b/static/include/services/apis/overrides/methods/go.vision.CaptureAllFromCamera.VisCapture.return.md new file mode 100644 index 0000000000..92edf1e50e --- /dev/null +++ b/static/include/services/apis/overrides/methods/go.vision.CaptureAllFromCamera.VisCapture.return.md @@ -0,0 +1,2 @@ +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. diff --git a/static/include/services/apis/overrides/methods/go.vision.CaptureAllFromCamera.cameraName.md b/static/include/services/apis/overrides/methods/go.vision.CaptureAllFromCamera.cameraName.md new file mode 100644 index 0000000000..004ea13f7e --- /dev/null +++ b/static/include/services/apis/overrides/methods/go.vision.CaptureAllFromCamera.cameraName.md @@ -0,0 +1 @@ +The name of the camera to use for detection. diff --git a/static/include/services/apis/overrides/methods/go.vision.CaptureAllFromCamera.opts.md b/static/include/services/apis/overrides/methods/go.vision.CaptureAllFromCamera.opts.md new file mode 100644 index 0000000000..e20b8fcdbc --- /dev/null +++ b/static/include/services/apis/overrides/methods/go.vision.CaptureAllFromCamera.opts.md @@ -0,0 +1 @@ +Additional options to provide if desired. diff --git a/static/include/services/apis/overrides/protos/vision.CaptureAllFromCamera.md b/static/include/services/apis/overrides/protos/vision.CaptureAllFromCamera.md new file mode 100644 index 0000000000..7836fcc645 --- /dev/null +++ b/static/include/services/apis/overrides/protos/vision.CaptureAllFromCamera.md @@ -0,0 +1,2 @@ +Get the next image, detections, classifications, and objects all together, given a camera name. +Used for visualization.