Telekinesis Agentic Skill Library

Appearance

Capture Single Depth Frame ​

SUMMARY

Capture Single Depth Frame 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.

The Skill ​

python
depth_image = camera.capture_single_depth_frame()

Example ​

Single depth image capture output

The Code ​

python
"""
Connect to a RealSense camera, capture a single depth frame, 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")
    try:
        rr.init("RealSense_Capture_Example", spawn=True)
        camera.connect()

        depth_image = camera.capture_single_depth_frame()

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


if __name__ == "__main__":
    main()

The Explanation of the Code ​

After connect has initialised the RealSense pipeline, capture_single_depth_frame activates the depth stream, retrieves one frame, and returns a NumPy array of float values already converted to metres.

python
depth_image = camera.capture_single_depth_frame()

rr.DepthImage renders the raw depth array as a false-colour image in Rerun:

  • meter=1.0 tells Rerun the values are already in metres so no unit conversion is applied.
  • colormap="turbo" maps close distances to blue and far distances to red.
  • depth_range=(0.0, 3.0) clamps the colour scale to the 0–3 metre range, so objects outside that band are clipped rather than compressing the palette.
python
rr.log(
    "Single_Depth_Image_Capture",
    rr.DepthImage(depth_image, meter=1.0, colormap="turbo", depth_range=(0.0, 3.0)),
)

The disconnect call lives in a finally block so the RealSense pipeline and USB resources are released regardless of whether the capture succeeded.

Running the Example ​

bash
python capture_depth_image_example.py

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

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.