# Camera API

The camera API allows you to give commands to your [camera components](https://docs.viam.com/reference/components/camera/) for getting images or point clouds.

The API for camera components allows you to:

- Request single images in 2D color, or display z-depth.
- Request a point cloud. Each 3D point cloud image consists of a set of coordinates (x,y,z) representing depth in mm.

The camera component supports the following methods:

| Method Name | Description |
| --- | --- |
| [`GetImages`](https://docs.viam.com/reference/apis/components/camera/#getimages) | `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. |
| [`GetPointCloud`](https://docs.viam.com/reference/apis/components/camera/#getpointcloud) | Get a point cloud from the camera as bytes with a MIME type describing the structure of the data. |
| [`GetProperties`](https://docs.viam.com/reference/apis/components/camera/#getproperties) | Get the camera intrinsic parameters and camera distortion, as well as whether the camera supports returning point clouds. |
| [`DoCommand`](https://docs.viam.com/reference/apis/components/camera/#docommand) | Execute model-specific commands that are not otherwise defined by the component API. |
| [`GetGeometries`](https://docs.viam.com/reference/apis/components/camera/#getgeometries) | Get all the geometries associated with the camera in its current configuration, in the frame of the camera. |
| [`GetResourceName`](https://docs.viam.com/reference/apis/components/camera/#getresourcename) | Get the `ResourceName` for this camera. |
| [`Close`](https://docs.viam.com/reference/apis/components/camera/#close) | Safely shut down the resource and prevent further use. |

## API

### GetImages

#### Usage

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.

`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.

- [Python](https://docs.viam.com/reference/apis/components/camera/#tabset-referenceapiscomponentscamera-1-0)
- [Go](https://docs.viam.com/reference/apis/components/camera/#tabset-referenceapiscomponentscamera-1-1)
- [TypeScript](https://docs.viam.com/reference/apis/components/camera/#tabset-referenceapiscomponentscamera-1-2)
- [Flutter](https://docs.viam.com/reference/apis/components/camera/#tabset-referenceapiscomponentscamera-1-3)

**Parameters:**

- `filter_source_names` (Sequence\[ [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)\]) (optional): The filter\_source\_names parameter can be used to filter only the images from the specified source names. When unspecified, all images are returned.
- `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:**

- (Tuple\[Sequence\[ [video.NamedImage](https://python.viam.dev/autoapi/viam/media/video/index.html#viam.media.video.NamedImage)\], [common.ResponseMetadata](https://python.viam.dev/autoapi/viam/gen/common/v1/common_pb2/index.html#viam.gen.common.v1.common_pb2.ResponseMetadata)\]): : A tuple containing two values; the first \[0\] a list of images returned from the camera system, and the second \[1\] the metadata associated with this response.

**Example:**

```python

```

For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/camera/client/index.html#viam.components.camera.client.CameraClient.get_images).

**Parameters:**

- `ctx` [(Context)](https://pkg.go.dev/context#Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
- `filterSourceNames` [\[string\]](https://pkg.go.dev/builtin#string)
- `extra` [(map\[string\]interface{})](https://go.dev/blog/maps): Extra options to pass to the underlying RPC call.

**Returns:**

- [\[NamedImage\]](https://pkg.go.dev/go.viam.com/rdk/components/camera#NamedImage): The list of images returned from the camera system, with the name of the imager associated with the image.
- [(resource.ResponseMetadata)](https://pkg.go.dev/go.viam.com/rdk/resource#ResponseMetadata): The metadata, which holds the timestamp of when the data was captured.
- [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred.

**Example:**

```go

```

For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/components/camera#ImagesSource).

**Parameters:**

- `filterSourceNames` (string) (optional): A list of source names to filter the images by. If empty or undefined, all images will be returned.
- `extra` (None) (optional): Extra parameters to pass to the camera.
- `callOptions` (CallOptions) (optional)

**Returns:**

- (Promise< { images: { image: Uint8Array; mimeType: string; sourceName: string }\[\]; metadata: ResponseMetadata; }, >)

**Example:**

```ts

```

For more information, see the [TypeScript SDK Docs](https://ts.viam.dev/classes/CameraClient.html#getimages).

**Parameters:**

- `filterSourceNames` [List](https://api.flutter.dev/flutter/dart-core/List-class.html)< [String](https://api.flutter.dev/flutter/dart-core/String-class.html)>? (optional)
- `extra` [Map](https://api.flutter.dev/flutter/dart-core/Map-class.html)< [String](https://api.flutter.dev/flutter/dart-core/String-class.html), dynamic>? (optional)

**Returns:**

- [Future](https://api.flutter.dev/flutter/dart-async/Future-class.html)< [GetImagesResult](https://flutter.viam.dev/viam_sdk/GetImagesResult-class.html) >

**Example:**

```dart

```

For more information, see the [Flutter SDK Docs](https://flutter.viam.dev/viam_sdk/Camera/getImages.html).

### GetPointCloud

Get a point cloud from the camera as bytes with a MIME type describing the structure of the data. The consumer of this call should decode the bytes into the format suggested by the MIME type.

- [Python](https://docs.viam.com/reference/apis/components/camera/#tabset-referenceapiscomponentscamera-2-0)
- [Go](https://docs.viam.com/reference/apis/components/camera/#tabset-referenceapiscomponentscamera-2-1)
- [TypeScript](https://docs.viam.com/reference/apis/components/camera/#tabset-referenceapiscomponentscamera-2-2)
- [Flutter](https://docs.viam.com/reference/apis/components/camera/#tabset-referenceapiscomponentscamera-2-3)

**Parameters:**

- `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:**

- (Tuple\[ [bytes](https://docs.python.org/3/library/stdtypes.html#bytes-objects), [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)\]): : A tuple containing two values; the first \[0\] the pointcloud data, and the second \[1\] the mimetype of the pointcloud (for example, PCD).

**Example:**

```python

```

For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/camera/client/index.html#viam.components.camera.client.CameraClient.get_point_cloud).

**Parameters:**

- `ctx` [(Context)](https://pkg.go.dev/context#Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
- `extra` [(map\[string\]interface{})](https://go.dev/blog/maps): Extra options to pass to the underlying RPC call.

**Returns:**

- [(pointcloud.PointCloud)](https://pkg.go.dev/go.viam.com/rdk/pointcloud#PointCloud): A general purpose container of points. It does not dictate whether or not the cloud is sparse or dense.
- [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred.

**Example:**

```go

```

For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/components/camera#PointCloudSource).

**Parameters:**

- `extra` (None) (optional)
- `callOptions` (CallOptions) (optional)

**Returns:**

- (Promise)

**Example:**

```ts

```

For more information, see the [TypeScript SDK Docs](https://ts.viam.dev/classes/CameraClient.html#getpointcloud).

**Parameters:**

- `extra` [Map](https://api.flutter.dev/flutter/dart-core/Map-class.html) < [String](https://api.flutter.dev/flutter/dart-core/String-class.html), dynamic>? (optional)

**Returns:**

- [Future](https://api.flutter.dev/flutter/dart-async/Future-class.html) < [ViamImage](https://flutter.viam.dev/viam_sdk/ViamImage-class.html) >

**Example:**

```dart

```

For more information, see the [Flutter SDK Docs](https://flutter.viam.dev/viam_sdk/Camera/pointCloud.html).

### GetProperties

Get the camera intrinsic parameters and camera distortion, as well as whether the camera supports returning point clouds.

- [Python](https://docs.viam.com/reference/apis/components/camera/#tabset-referenceapiscomponentscamera-3-0)
- [Go](https://docs.viam.com/reference/apis/components/camera/#tabset-referenceapiscomponentscamera-3-1)
- [TypeScript](https://docs.viam.com/reference/apis/components/camera/#tabset-referenceapiscomponentscamera-3-2)
- [Flutter](https://docs.viam.com/reference/apis/components/camera/#tabset-referenceapiscomponentscamera-3-3)

**Parameters:**

- `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.components.camera.Camera.Properties](https://python.viam.dev/autoapi/viam/components/camera/index.html#viam.components.camera.Camera.Properties)): : The properties of the camera, including intrinsic parameters, distortion parameters, supported mime types, and optionally extrinsic parameters (position relative to a reference frame).

**Example:**

```python

```

For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/camera/client/index.html#viam.components.camera.client.CameraClient.get_properties).

**Parameters:**

- `ctx` [(Context)](https://pkg.go.dev/context#Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.

**Returns:**

- [(Properties)](https://pkg.go.dev/go.viam.com/rdk/components/camera#Properties): Properties of the particular implementation of a camera.
- [(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/components/camera#Camera).

**Parameters:**

- `callOptions` (CallOptions) (optional)

**Returns:**

- (Promise< [cameraApi](https://ts.viam.dev/modules/cameraApi.html). [GetPropertiesResponse](https://ts.viam.dev/classes/cameraApi.GetPropertiesResponse.html) >)

**Example:**

```ts

```

For more information, see the [TypeScript SDK Docs](https://ts.viam.dev/classes/CameraClient.html#getproperties).

**Parameters:**

- None.

**Returns:**

- [Future](https://api.flutter.dev/flutter/dart-async/Future-class.html) < [CameraProperties](https://flutter.viam.dev/viam_sdk/CameraProperties.html) >

**Example:**

```dart

```

For more information, see the [Flutter SDK Docs](https://flutter.viam.dev/viam_sdk/Camera/properties.html).

### DoCommand

Execute model-specific commands that are not otherwise defined by the component API. Most models do not implement `DoCommand`. Any available model-specific commands should be covered in the model’s documentation. If you are implementing your own camera and want to add features that have no corresponding built-in API method, you can implement them with [`DoCommand`](https://docs.viam.com/reference/sdks/docommand/).

- [Python](https://docs.viam.com/reference/apis/components/camera/#tabset-referenceapiscomponentscamera-4-0)
- [Go](https://docs.viam.com/reference/apis/components/camera/#tabset-referenceapiscomponentscamera-4-1)
- [TypeScript](https://docs.viam.com/reference/apis/components/camera/#tabset-referenceapiscomponentscamera-4-2)
- [Flutter](https://docs.viam.com/reference/apis/components/camera/#tabset-referenceapiscomponentscamera-4-3)

**Parameters:**

- `command` (Mapping\[ [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str), ValueTypes\]) (required): The command to execute.
- `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:**

- (Mapping\[ [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str), viam.utils.ValueTypes\]): : Result of the executed command.

**Raises:**

- (NotImplementedError): Raised if the Resource does not support arbitrary commands.

**Example:**

```python

```

For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/camera/client/index.html#viam.components.camera.client.CameraClient.do_command).

**Parameters:**

- `ctx` [(Context)](https://pkg.go.dev/context#Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
- `cmd` [(map\[string\]interface{})](https://go.dev/blog/maps): The command to execute.

**Returns:**

- [(map\[string\]interface{})](https://pkg.go.dev/builtin#string): The command response.
- [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred.

**Example:**

```go

```

For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/resource#Resource).

**Parameters:**

- `command` ( [Struct](https://ts.viam.dev/classes/Struct.html)) (required): The command to execute. Accepts either a [Struct](https://ts.viam.dev/classes/Struct.html) or a plain object, which will be converted automatically.
- `callOptions` (CallOptions) (optional)

**Returns:**

- (Promise< [JsonValue](https://ts.viam.dev/types/JsonValue.html) >)

**Example:**

```ts

```

For more information, see the [TypeScript SDK Docs](https://ts.viam.dev/classes/CameraClient.html#docommand).

**Parameters:**

- `command` [Map](https://api.flutter.dev/flutter/dart-core/Map-class.html) < [String](https://api.flutter.dev/flutter/dart-core/String-class.html), dynamic> (required)

**Returns:**

- [Future](https://api.flutter.dev/flutter/dart-async/Future-class.html) < [Map](https://api.flutter.dev/flutter/dart-core/Map-class.html) < [String](https://api.flutter.dev/flutter/dart-core/String-class.html), dynamic>>

**Example:**

```dart

```

For more information, see the [Flutter SDK Docs](https://flutter.viam.dev/viam_sdk/Resource/doCommand.html).

### GetGeometries

Get all the geometries associated with the camera in its current configuration, in the [frame](https://docs.viam.com/reference/services/frame-system/) of the camera. The [motion](https://docs.viam.com/reference/services/motion/) and [navigation](https://docs.viam.com/reference/services/navigation/) services use the relative position of inherent geometries to configured geometries representing obstacles for collision detection and obstacle avoidance while motion planning.

- [Python](https://docs.viam.com/reference/apis/components/camera/#tabset-referenceapiscomponentscamera-5-0)
- [Go](https://docs.viam.com/reference/apis/components/camera/#tabset-referenceapiscomponentscamera-5-1)
- [TypeScript](https://docs.viam.com/reference/apis/components/camera/#tabset-referenceapiscomponentscamera-5-2)

**Parameters:**

**Returns:**

- ( [Sequence\[viam.proto.common.Geometry\]](https://python.viam.dev/autoapi/viam/proto/common/index.html#viam.proto.common.Geometry)): : The geometries associated with the Component.

**Example:**

```python

```

For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/camera/client/index.html#viam.components.camera.client.CameraClient.get_geometries).

**Parameters:**

**Returns:**

- [\[spatialmath.Geometry\]](https://pkg.go.dev/go.viam.com/rdk/spatialmath#Geometry): The geometries associated with this resource, in any order.
- [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred.

**Example:**

```go

```

For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/resource#Shaped).

**Parameters:**

- `extra` (None) (optional)
- `callOptions` (CallOptions) (optional)

**Returns:**

- (Promise< [commonApi](https://ts.viam.dev/modules/commonApi.html). [Geometry](https://ts.viam.dev/classes/commonApi.Geometry.html)\[\]> )

For more information, see the [TypeScript SDK Docs](https://ts.viam.dev/classes/CameraClient.html#getgeometries).

### GetResourceName

Get the `ResourceName` for this camera.

- [Python](https://docs.viam.com/reference/apis/components/camera/#tabset-referenceapiscomponentscamera-6-0)
- [Go](https://docs.viam.com/reference/apis/components/camera/#tabset-referenceapiscomponentscamera-6-1)
- [TypeScript](https://docs.viam.com/reference/apis/components/camera/#tabset-referenceapiscomponentscamera-6-2)
- [Flutter](https://docs.viam.com/reference/apis/components/camera/#tabset-referenceapiscomponentscamera-6-3)

**Parameters:**

- `name` ( [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): The name of the Resource.

**Returns:**

- ( [viam.proto.common.ResourceName](https://python.viam.dev/autoapi/viam/proto/common/index.html#viam.proto.common.ResourceName)): : The ResourceName of this Resource.

**Example:**

```python

```

For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/camera/client/index.html#viam.components.camera.client.CameraClient.get_resource_name).

**Parameters:**

- None.

**Returns:**

- [(Name)](https://pkg.go.dev/go.viam.com/rdk@v0.89.0/resource#Name)

**Example:**

```go

```

For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/resource#Resource).

**Parameters:**

- None.

**Returns:**

- (string): The name of the resource.

**Example:**

```ts

```

For more information, see the [TypeScript SDK Docs](https://ts.viam.dev/classes/CameraClient.html#name).

**Parameters:**

- `name` [String](https://api.flutter.dev/flutter/dart-core/String-class.html) (required)

**Returns:**

- [ResourceName](https://flutter.viam.dev/viam_sdk/ResourceName-class.html)

**Example:**

```dart

```

For more information, see the [Flutter SDK Docs](https://flutter.viam.dev/viam_sdk/Camera/getResourceName.html).

### Close

Safely shut down the resource and prevent further use.

- [Python](https://docs.viam.com/reference/apis/components/camera/#tabset-referenceapiscomponentscamera-7-0)
- [Go](https://docs.viam.com/reference/apis/components/camera/#tabset-referenceapiscomponentscamera-7-1)

**Parameters:**

- None.

**Returns:**

- None.

**Example:**

```python

```

For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/camera/client/index.html#viam.components.camera.client.CameraClient.close).

**Parameters:**

- `ctx` [(Context)](https://pkg.go.dev/context#Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.

**Returns:**

- [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred.

**Example:**

```go

```

For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/resource#Resource).