Telekinesis Agentic Skill Library

Appearance

Capture Depth Image ​

SUMMARY

Capture Depth Image acquires one depth frame from a 3D camera and returns it as a NumPy array of float values in metres. Pair it with a Rerun DepthImage colour map for instant visual inspection of distance information.

Available on: Intel RealSense, Zivid.

The Skill ​

python
depth_image = camera.capture_depth_image()

Example ​

Intel RealSense

Single depth image capture output

Zivid

Single depth image capture output

The Code ​

python
"""
Connect to a RealSense camera, capture a depth image, and disconnect.

Run from a terminal to avoid issues with Rerun's spawn mode.
"""
from loguru import logger
import rerun as rr

from telekinesis.medulla.cameras import realsense

def main():
    camera = realsense.RealSense(name="my_realsense_camera")

    try:
        rr.init("RealSense_Depth_Image_Example", spawn=True)
        camera.connect()

        depth_image = camera.capture_depth_image()

        rr.log(
            "Depth_Image_Capture", 
            rr.DepthImage(
                depth_image,
                meter=1.0, # values are already in metres
                colormap="turbo",
                depth_range=(0.0, 3.0) # 3 metres
            )
        )
    except Exception as e:
        logger.error(
            f"Unable to capture depth image. Caught exception: {type(e).__name__}: {e}"
        )
    finally:
        rr.disconnect()
        camera.disconnect()


if __name__ == "__main__":
    main()
python
"""
Connect to a Zivid camera, capture a depth image, and disconnect.

Run from a terminal to avoid issues with Rerun's spawn mode.
"""
from loguru import logger
import rerun as rr

from telekinesis.medulla.cameras import zivid

def main():
    camera = zivid.Zivid(name="my_zivid_camera")

    try:
        rr.init("Zivid_Depth_Image_Example", spawn=True)
        camera.connect()

        depth_image = camera.capture_depth_image()

        rr.log(
            "Depth_Image_Capture", 
            rr.DepthImage(
                depth_image,
                meter=1.0, # values are already in metres
                colormap="turbo",
                depth_range=(0.0, 3.0) # 3 metres
            )
        )
    except Exception as e:
        logger.error(
            f"Unable to capture depth image. Caught exception: {type(e).__name__}: {e}"
        )
    finally:
        rr.disconnect()
        camera.disconnect()

if __name__ == "__main__":
    main()

Running the Example ​

Change to the respective camera examples folder in telekinesis-examples and run

bash
python capture_depth_image.py

A Rerun viewer opens automatically. The depth image appears under Depth_Image_Capture with the turbo colour map applied.

Parameter Configuration ​

This method takes no parameters.

Returns ​

TypeDescription
Depth image (NumPy-backed)Depth map of shape (H, W), float32, values in metres. Pixels with no valid depth are NaN.

Raises ​

ExceptionCondition
RuntimeErrorCamera is not connected (RealSense, Zivid)
RuntimeErrorRealSense: the depth frame could not be retrieved from the pipeline
NotImplementedErrorCalled on IDS or Webcam — these are 2D-only cameras and do not implement depth capture

Where to Use the Skill ​

  • Reach and clearance checks — measure object-to-camera distances before grasp planning.
  • Workspace mapping — capture a one-shot depth snapshot of the robot cell.
  • Sanity checks during calibration — confirm depth alignment without running a continuous stream.