Configure a Webcam

webcam is the general camera model. If the camera drivers are among those in this mediadevices repository. the camera will work with the webcam model.

On the COMPONENTS subtab, navigate to the Create Component menu. Enter a name for your camera, select the type camera, and select the webcam model.

Creation of webcam camera in the Viam app config builder.

Fill in the attributes for your webcam view. If you click on the Video Path field while your robot is live, a drop down will autopopulate with identified camera paths.

Configuration of a webcam camera in the Viam app config builder.
{
    "name": "<camera_name>",
    "type": "camera",
    "model" : "webcam",
    "attributes": {
        "intrinsic_parameters": {
            "width_px": <integer>,
            "height_px": <integer>,
            "fx": <float64>,
            "fy": <float64>,
            "ppx": <float64>,
            "ppy": <float64>
        },
        "distortion_parameters": {
            "rk1": <float64>,
            "rk2": <float64>,
            "rk3": <float64>,
            "tp1": <float64>,
            "tp2": <float64>
        },
        "debug": <boolean>,
        "format": <string>,
        "video_path": <string>,
        "width_px": <integer>,
        "height_px": <integer>
    }
}

The following attributes are available for webcams:

NameInclusionDescription
intrinsic_parametersOptionalThe intrinsic parameters of the camera used to do 2D <-> 3D projections:
  • width_px: The expected width of the aligned image in pixels.
  • height_px: The expected height of the aligned image in pixels.
  • fx: The image center x point.
  • fy: The image center y point.
  • ppx: The image focal x.
  • ppy: The image focal y.
distortion_parametersOptionalModified 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.
debugOptionalEnables the debug outputs from the camera if true. Defaults to false.
formatOptionalThe camera image format, used with video_path to find camera.
video_pathOptionalThe path to the webcam. Often video0. If you don’t provide a video path, it defaults to the first valid video path it finds.
width_pxOptionalThe camera image width in pixels, used with video_path to find camera with this resolution. Defaults to the closest possible value to closest to 480.
height_pxOptionalThe camera image height in pixels, used with video_path to find camera with this resolution. Defaults to the closest possible value to closest to 640.

View the camera stream

Once your camera is connected, go to the CONTROL tab, and click on the camera’s dropdown menu. Toggle “View Camera”. If everything is configured correctly, you will see the live video feed from your camera.

Example Camera view inside Viam app

Troubleshooting

video0 does not work

If you’re working on a linux machine, run v4l2-ctl --list-devices in your terminal to see available video paths.

No visible live video feed

If you’re working on a linux machine, ssh into it, then restart viam-server by running:

sudo systemctl restart viam-server

If this doesn’t work, you can reboot your machine by running:

sudo reboot

If video0 does not work for you, you can find another potential video_path by typing the following in your terminal:

v4l2-ctl --list-devices

The output for a webcam looks like this, in which case video1 might be the correct path to use for video_path:

C270 HD WEBCAM (usb-0000:01:00.0-1.2):
 /dev/video0
 /dev/video1
 /dev/media4

CSI Camera not working on a Raspberry Pi

If you are using a CSI camera on a Raspberry Pi, you need to enable legacy mode.

Timeout errors on a Raspberry Pi

If you are getting “timeout” errors from GRPC when adding a webcam model on a Raspberry Pi, make sure the webcam port is enabled on the Pi (common if you are using a fresh Pi right out of the box):

sudo raspi-config
Interface Options -> Camera -> Enable Camera
Restart the Pi

Next Steps