or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

advanced-mode.mdcontext-device.mdframes.mdindex.mdlogging.mdoptions.mdpipeline.mdpointclouds.mdprocessing.mdrecording.mdsensors.md
tile.json

tessl/pypi-pyrealsense2

Python bindings for Intel RealSense SDK 2.0 providing access to depth and color cameras for computer vision applications.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/pyrealsense2@2.56.x

To install, run

npx @tessl/cli install tessl/pypi-pyrealsense2@2.56.0

index.mddocs/

PyRealSense2

Python bindings for Intel RealSense SDK 2.0, providing comprehensive access to Intel RealSense depth and color cameras. Enables computer vision, robotics, and augmented reality applications with depth sensing, 3D perception, and real-time camera streaming capabilities.

Package Information

  • Package Name: pyrealsense2
  • Language: Python
  • Installation: pip install pyrealsense2
  • Minimum Python: 3.9+
  • License: Apache 2.0

Core Imports

import pyrealsense2 as rs

Basic Usage

import pyrealsense2 as rs
import numpy as np

# Create pipeline and configure streams
pipeline = rs.pipeline()
config = rs.config()
config.enable_stream(rs.stream.depth, 640, 480, rs.format.z16, 30)
config.enable_stream(rs.stream.color, 640, 480, rs.format.bgr8, 30)

# Start streaming
pipeline.start(config)

try:
    while True:
        # Wait for coherent frames
        frames = pipeline.wait_for_frames()
        depth_frame = frames.get_depth_frame()
        color_frame = frames.get_color_frame()
        
        if not depth_frame or not color_frame:
            continue
            
        # Convert to numpy arrays for processing
        depth_image = np.asanyarray(depth_frame.get_data())
        color_image = np.asanyarray(color_frame.get_data())
        
        # Get distance at center pixel
        width = depth_frame.get_width()
        height = depth_frame.get_height()
        center_distance = depth_frame.get_distance(width // 2, height // 2)
        print(f"Distance at center: {center_distance:.2f} meters")
        
finally:
    pipeline.stop()

Architecture

PyRealSense2 provides both high-level and low-level APIs:

  • Pipeline API: Simplified interface for common use cases with automatic configuration
  • Context & Device API: Fine-grained device discovery and control
  • Sensor API: Direct sensor access for advanced configuration
  • Frame Processing: Rich ecosystem of filters and processing blocks
  • 3D Processing: Point cloud generation and coordinate transformations

The library integrates seamlessly with NumPy through Python's buffer protocol, enabling zero-copy data access for efficient processing with computer vision libraries like OpenCV and scientific computing frameworks.

Capabilities

Core Pipeline API

High-level streaming interface that simplifies camera configuration and frame capture. Automatically handles device selection, stream synchronization, and provides coherent framesets for easy processing.

class pipeline:
    def __init__(context=None): ...
    def start() -> pipeline_profile: ...
    def start(config) -> pipeline_profile: ...
    def stop(): ...
    def wait_for_frames(timeout_ms=5000) -> frameset: ...
    
class config:
    def enable_stream(stream_type, width, height, format, framerate): ...
    def enable_device(serial_number): ...
    def disable_all_streams(): ...

Pipeline API

Context & Device Management

Device discovery, enumeration, and management capabilities. Provides fine-grained control over connected RealSense devices with support for hotplug detection and device-specific features.

class context:
    def query_devices() -> device_list: ...
    def set_devices_changed_callback(callback): ...
    
class device:
    def query_sensors() -> list[sensor]: ...
    def get_info(camera_info) -> str: ...
    def hardware_reset(): ...

Context & Device Management

Sensors & Streaming

Low-level sensor control for advanced applications requiring precise stream configuration, custom frame processing, or multi-device synchronization.

class sensor:
    def get_stream_profiles() -> list[stream_profile]: ...
    def open(profile): ...
    def start(callback): ...
    def stop(): ...
    
class depth_sensor(sensor):
    def get_depth_scale() -> float: ...

Sensors & Streaming

Frame Handling

Frame data access and manipulation with support for depth, color, infrared, and motion data. Provides buffer protocol integration for NumPy compatibility and metadata access.

class frame:
    def get_data() -> BufData: ...
    def get_timestamp() -> float: ...
    def get_frame_number() -> int: ...
    
class depth_frame(video_frame):
    def get_distance(x, y) -> float: ...
    def get_units() -> float: ...
    
class frameset(frame):
    def get_depth_frame() -> depth_frame: ...
    def get_color_frame() -> video_frame: ...

Frame Handling

Processing & Filters

Real-time frame processing with built-in filters for noise reduction, alignment, colorization, and format conversion. Supports custom processing blocks and filter chaining.

class align(filter):
    def __init__(align_to_stream): ...
    
class colorizer(filter):
    def __init__(color_scheme=0): ...
    def colorize(depth_frame) -> video_frame: ...
    
class temporal_filter(filter):
    def __init__(smooth_alpha=0.4, smooth_delta=20.0, persistence_control=3): ...

Processing & Filters

3D Data & Point Clouds

3D processing capabilities including point cloud generation, coordinate transformations, and spatial analysis. Supports various output formats and texture mapping.

class pointcloud(filter):
    def calculate(depth_frame) -> points: ...
    def map_to(texture_frame): ...
    
class points(frame):
    def get_vertices() -> BufData: ...
    def export_to_ply(filename, texture_frame): ...
    
# Utility functions
def rs2_project_point_to_pixel(intrinsics, point_3d) -> pixel_2d: ...
def rs2_deproject_pixel_to_point(intrinsics, pixel_2d, depth) -> point_3d: ...

3D Data & Point Clouds

Configuration & Options

Device option management with support for camera parameters, processing settings, and hardware features. Provides range validation and real-time adjustment capabilities.

class options:
    def get_option(option) -> float: ...
    def set_option(option, value): ...
    def get_option_range(option) -> option_range: ...
    def supports(option) -> bool: ...

Configuration & Options

Recording & Playback

Session recording and playback functionality for development, testing, and data analysis. Supports compression and provides full control over playback timing.

class recorder(device):
    def __init__(filename, device, enable_compression=False): ...
    def pause(): ...
    def resume(): ...
    
class playback(device):
    def seek(time_ns): ...
    def set_real_time(real_time): ...
    def get_duration() -> int: ...

Recording & Playback

Advanced Mode API

Fine-grained control over RS400 series camera parameters including depth processing, color controls, and advanced calibration features. Enables deep customization for specialized applications.

class rs400_advanced_mode:
    def toggle_advanced_mode(enable): ...
    def is_enabled() -> bool: ...
    def serialize_json() -> str: ...
    def load_json(json_content): ...
    
    def get_depth_control() -> STDepthControlGroup: ...
    def set_depth_control(group): ...
    def get_rsm() -> STRsm: ...
    def set_rsm(rsm): ...

Advanced Mode API

Logging & Diagnostics

Global logging functions for debugging and diagnostics. Provides flexible logging output to console, files, or custom callbacks with comprehensive message processing capabilities.

def log_to_console(min_severity): ...
def log_to_file(min_severity, file_path): ...
def log_to_callback(min_severity, callback_function): ...
def enable_rolling_log_file(severity, file_path, max_size): ...
def reset_logger(): ...
def log(severity, message): ...

class log_message:
    def get_severity() -> log_severity: ...
    def get_message() -> str: ...
    def get_filename() -> str: ...
    def get_line_number() -> int: ...

# Version information
rs.__version__        # API version string
rs.__full_version__   # Full version string

Logging & Diagnostics

Error Handling

PyRealSense2 operations may raise exceptions of type rs.error. Common error scenarios include:

  • Device disconnection during streaming
  • Invalid stream configuration parameters
  • Hardware failures or timeouts
  • File I/O errors during recording/playback
try:
    pipeline.start(config)
except rs.error as e:
    print(f"RealSense error: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")

Integration Notes

  • NumPy: All frames support buffer protocol for zero-copy numpy array creation
  • OpenCV: Direct compatibility with OpenCV image processing functions
  • Threading: Frame callbacks execute on separate threads, requiring proper synchronization
  • Memory: Frames are reference-counted; call frame.keep() to extend lifetime if needed