Edit

Transform a Camera

Use the transform model to apply transformations to input source images. The transformations are applied in the order they are written in the pipeline.

Config Builder
JSON Template

Navigate to the CONFIGURE tab of your machine’s page in the Viam app. Click the + icon next to your machine part in the left-hand menu and select Component. Select the camera type, then select the transform model. Enter a name or use the suggested name for your camera and click Create.

Configuration of an transform view in the Viam app config builder.

Click the {} (Switch to Advanced) button in the top right of the component panel to edit the component’s attributes directly with JSON. Copy and paste the following attribute template into the attributes field. Then remove and fill in the attributes as applicable to your camera, according to the table below.

Attributes template
Attributes example

{
  "source" : "<your-camera-name>",
  "pipeline": [
    { "type": "<transformation-type>", "attributes": { ... } },
  ],
  "intrinsic_parameters": {
    "width_px": <int>,
    "height_px": <int>,
    "fx": <float>,
    "fy": <float>,
    "ppx": <float>,
    "ppy": <float>
  },
  "distortion_parameters": {
  "rk1": <float>,
    "rk2": <float>,
    "rk3": <float>,
    "tp1": <float>,
    "tp2": <float>
  }
}

{
  "source": "my-webcam",
  "pipeline": [
    { "type": "rotate", "attributes": {} },
    { "type": "resize", "attributes": { "width_px": 200, "height_px": 100 } }
  ]
}

{
  "name": "<your-camera-name>",
  "model": "transform",
  "type": "camera",
  "namespace": "rdk",
  "attributes" : {
    "source" : "<your-source-camera-name>",
    "pipeline": [
      { "type": "<transformation-type>", "attributes": { ... } },
    ],
    "intrinsic_parameters": {
      "width_px": <int>,
      "height_px": <int>,
      "fx": <float>,
      "fy": <float>,
      "ppx": <float>,
      "ppy": <float>
    },
    "distortion_parameters": {
      "rk1": <float>,
      "rk2": <float>,
      "rk3": <float>,
      "tp1": <float>,
      "tp2": <float>
    }
  }
}

The following attributes are available for transform views:

Name	Type	Required?	Description
`source`	string	Required	`name` of the camera to transform.
`pipeline`	array	Required	Specify an array of transformation objects.
`intrinsic_parameters`	object	Optional	The intrinsic parameters of the camera used to do 2D <-> 3D projections: `width_px`: The expected width of the aligned image in pixels. Value must be >= 0. `height_px`: The expected height of the aligned image in pixels. Value must be >= 0. `fx`: The image center x point. `fy`: The image center y point. `ppx`: The image focal x. `ppy`: The image focal y.
`distortion_parameters`	object	Optional	Modified Brown-Conrady parameters used to correct for distortions caused by the shape of the camera lens: `rk1`: The radial distortion x. `rk2`: The radial distortion y. `rk3`: The radial distortion z. `tp1`: The tangential distortion x. `tp2`: The tangential distortion y.

The following are the transformation objects available for the pipeline:

Classifications

Classifications overlay text from the GetClassifications method of the vision service onto the image.

{
  "source": "<your-source-camera-name>",
  "pipeline": [
    {
      "type": "classifications",
      "attributes": {
        "classifier_name": "<name>",
        "confidence_threshold": <float>,
        "max_classifications": <int>,
        "valid_labels": [ "<label>" ]
      }
    }
  ]
}

Attributes:

classifier_name: The name of the classifier in the vision service.
confidence_threshold: The threshold above which to display classifications.
max_classifications: Optional. The maximum number of classifications to display on the camera stream at any given time. Default: 1.
valid_labels: Optional. An array of labels that you to see detections for on the camera stream. If not specified, all labels from the classifier are used.

Crop

The Crop transform crops takes an image and crops it to a rectangular area specified by two points: the top left point ((x_min, y_min)) and the bottom right point ((x_max, y_max)).

{
  "source": "<your-source-camera-name>",
  "pipeline": [
    {
      "type": "crop",
      "attributes": {
        "x_min_px": <int>,
        "y_min_px": <int>,
        "x_max_px": <int>,
        "y_max_px": <int>,
        "overlay_crop_box": <bool>
      }
    }
  ]
}

If you have a 100 x 200 image, and you want to crop to a box between the points (30, 40) and (60,80), the following would suffice:

{
  "source": "<your-source-camera-name>",
  "pipeline": [
    {
      "type": "crop",
      "attributes": {
        "x_min_px": 30,
        "y_min_px": 40,
        "x_max_px": 60,
        "y_max_px": 80,
        "overlay_crop_box": false
      }
    }
  ]
}

If you have a 100 x 200 image, and you want to crop to a box between the points (30, 40) and (60,80), the following would suffice:

{
  "source": "<your-source-camera-name>",
  "pipeline": [
    {
      "type": "crop",
      "attributes": {
        "x_min_px": 0.3,
        "y_min_px": 0.2,
        "x_max_px": 0.6,
        "y_max_px": 0.4,
        "overlay_crop_box": false
      }
    }
  ]
}

Attributes:

x_min_px: The x coordinate or the relative proportion of the top left point of the rectangular area to crop the image to.
y_min_px: The y coordinate or the relative proportion of the top left point of the rectangular area to crop the image to.
x_max_px: The x coordinate or the relative proportion of the bottom right point of the rectangular area to crop the image to.
y_max_px: The y coordinate or the relative proportion of the bottom right point of the rectangular area to crop the image to.
overlay_crop_box: Set to true to not actually carry out the crop, but instead overlay the cropping box on the original image and visualize where the crop would be applied.

Detections

The Detections transform takes the input image and overlays the detections from a given detector configured within the vision service.

{
  "source": "<your-source-camera-name>",
  "pipeline": [
    {
      "type": "detections",
      "attributes": {
        "detector_name": string,
        "confidence_threshold": <float>,
        "valid_labels": ["<label>"]
      }
    }
  ]
}

Attributes:

detector_name: The name of the detector configured in the vision service.
confidence_threshold: Specify to only display detections above the specified threshold (decimal between 0 and 1).
valid_labels: Optional. An array of labels that you to see detections for on the camera stream. If not specified, all labels from the classifier are used.

Resize

The Resize transform resizes the image to the specified height and width.

{
  "source": "<your-source-camera-name>",
  "pipeline": [
    {
      "type": "resize",
      "attributes": {
        "width_px": <int>,
        "height_px": <int>
      }
    }
  ]
}

Attributes:

width_px: Specify the expected width for the aligned image. Value must be >= 0.
height_px: Specify the expected width for the aligned image. Value must be >= 0.

Rotate

The Rotate transformation rotates the image by the angle specified in angle_deg. Default: 180 degrees. This feature is useful for when the camera is installed upside down or sideways on your machine.

{
  "source": "<your-source-camera-name>",
  "pipeline": [
    {
      "type": "rotate",
      "attributes": {
        "angle_degs": <float>
      }
    }
  ]
}

Attributes:

angle_deg: Rotate the image by a specific angle in degrees.

View the camera stream

Once your camera is configured and connected, expand the TEST panel on the CONFIGURE or CONTROL tabs. If everything is configured correctly, you will see the live feed from your camera.

Troubleshooting

If your camera is not working as expected, follow these steps:

Check your machine logs on the LOGS tab to check for errors.
Review this camera model’s documentation to ensure you have configured all required attributes.
Click on the TEST panel on the CONFIGURE or CONTROL tab and test if you can use the camera there.

If none of these steps work, reach out to us on the Community Discord and we will be happy to help.

Common errors

Failed to find the best driver that fits the constraints

When working with a camera component, depending on the camera, you may need to explicitly provide some camera-specific configuration parameters.

Solution: Check the specifications for your camera, and manually provide configuration parameters such as width and height to the camera component configuration page on the Viam app. On the CONFIGURE page, find your camera, then fill in your camera’s specific configuration either using the Show more button to show the relevant configuration options, or the {} (Switch to Advanced) button in the top right of the component panel to enter these attributes manually. Provide at least the width and height values to start.

Next steps

For more configuration and usage info, see:

Was this page helpful?

Glad to hear it! If you have any other feedback please let us know:

We're sorry about that. To help us improve, please tell us what we can do better:

Thank you!