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.

Navigate to the Config tab of your robot’s page in the Viam app. Click on the Components subtab and click Create component. Select the camera type, then select the webcam model. Enter a name for your camera and click Create.

Configuration of a webcam camera in the Viam app config builder.

Edit and fill in the attributes as applicable. If you click on the Video Path field while your robot is live, a drop down autopopulates with identified camera paths.

{
    "name": "<your-camera-name>",
    "type": "camera",
    "model" : "webcam",
    "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>
        },
        "debug": <boolean>,
        "format": <string>,
        "video_path": "<your-video-path>",
        "width_px": <int>,
        "height_px": <int>,
        "frame_rate": <float>
    }
}

{
  "name": "my_cam",
  "type": "camera",
  "model": "webcam",
  "attributes": {
    "video_path": "video0"
  }
}

The following attributes are available for webcam cameras:

NameTypeInclusionDescription
video_pathstringOptionalThe ID of or the path to the webcam. If you don’t provide a video_path, it defaults to the first valid video path it finds. Using the ID of a webcam is more consistent than the path.
formatstringOptionalThe camera image format, used with video_path to find the camera.
width_pxintOptionalThe camera image width in pixels, used with video_path to find a camera with this resolution.
Default: Closest possible value to 480
height_pxintOptionalThe camera image height in pixels, used with video_path to find a camera with this resolution.
Default: Closest possible value to 640
frame_ratefloatOptionalThe camera capture frequency as frames per second, used with video_path to find a camera with this throughput.
Default: Closest possible value to 30.0
intrinsic_parametersobjectOptionalThe 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_parametersobjectOptionalModified 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.
debugbooleanOptionalEnables the debug outputs from the camera if true.
Default: false

View the camera stream

Once your camera is configured and connected, go to the Control tab, and click on the camera’s dropdown menu. Then toggle the camera or the Point Cloud Data view to ON. If everything is configured correctly, you will see the live video feed from your camera. You can change the refresh frequency as needed to change bandwidth.

Example Camera view inside Viam app

Troubleshooting

Find the video_path

To list available video_paths use the following command:

ls /dev/v4l/by-id/

To find the paths of all connected video devices, run the following command:

v4l2-ctl --list-devices

The id listed by ls /dev/v4l/by-id/ is a more consistent way to refer to the webcam.

system_profiler SPCameraDataType

The Unique ID displayed for each camera is the video_path.

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

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.

High CPU usage

Each camera stream you add uses CPU on the device it is connected to and there is therefore a practical limit to the numbeof camera streams your device can simultaneously support. You can limit the CPU usage by reducing the image resolution.

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

To enable the webcam port on a Raspberry Pi, run the following command:

sudo raspi-config

Then, select: Interface Options -> Camera -> Enable Camera.

Restart the Pi to complete the configuration.

Next Steps

Calibrate a Camera

Calibrate a camera and extract the intrinsic and distortion parameters.

transform

Instructions for transforming a camera.

Vision
Vision

The vision service enables your smart machine to use its on-board cameras to intelligently see and interpret the world around it.



Have questions, or want to meet other people working on robots? Join our Community Discord.