tessl/pypi-pybullet

Official Python Interface for the Bullet Physics SDK specialized for Robotics Simulation and Reinforcement Learning

—

Pending

Overview

Eval results

Files

Rendering and Visualization

Name: tessl/pypi-pybullet
Author: tessl

Camera control, image rendering, and debug visualization tools for simulation analysis, data collection, and development. Essential for computer vision applications, data generation, and simulation debugging.

Capabilities

Camera Image Rendering

def getCameraImage(width, height, viewMatrix, projectionMatrix, shadow=1, lightDirection=None, lightColor=None, lightDistance=None, lightAmbientCoeff=None, lightDiffuseCoeff=None, lightSpecularCoeff=None, renderer=None, physicsClientId=0):
    """
    Render camera image from specified viewpoint.
    
    Args:
        width (int): Image width in pixels
        height (int): Image height in pixels  
        viewMatrix (list): 4x4 view matrix (16 elements)
        projectionMatrix (list): 4x4 projection matrix (16 elements)
        shadow (int, optional): Enable shadows (0/1). Defaults to 1.
        lightDirection (list, optional): Light direction [x, y, z]
        lightColor (list, optional): Light color [r, g, b]
        lightDistance (float, optional): Light distance
        lightAmbientCoeff (float, optional): Ambient light coefficient
        lightDiffuseCoeff (float, optional): Diffuse light coefficient
        lightSpecularCoeff (float, optional): Specular light coefficient
        renderer (int, optional): Renderer type (ER_BULLET_HARDWARE_OPENGL, ER_TINY_RENDERER)
        physicsClientId (int, optional): Physics client ID. Defaults to 0.
    
    Returns:
        tuple: (width, height, rgbPixels, depthPixels, segmentationMaskBuffer)
            - rgbPixels: RGB image as numpy array or list
            - depthPixels: Depth buffer as numpy array or list
            - segmentationMaskBuffer: Segmentation mask with object IDs
    """

Camera Matrix Computation

def computeViewMatrix(cameraEyePosition, cameraTargetPosition, cameraUpVector):
    """
    Compute view matrix for camera positioning.
    
    Args:
        cameraEyePosition (list): Camera position [x, y, z]
        cameraTargetPosition (list): Target position [x, y, z]
        cameraUpVector (list): Up vector [x, y, z]
    
    Returns:
        list: 4x4 view matrix (16 elements)
    """

def computeViewMatrixFromYawPitchRoll(cameraTargetPosition, distance, yaw, pitch, roll, upAxisIndex):
    """Compute view matrix from yaw-pitch-roll angles."""

def computeProjectionMatrix(left, right, bottom, top, nearVal, farVal):
    """Compute projection matrix from frustum parameters."""

def computeProjectionMatrixFOV(fov, aspect, nearVal, farVal):
    """Compute projection matrix from field of view."""

Debug Visualization

def addUserDebugLine(lineFromXYZ, lineToXYZ, lineColorRGB=None, lineWidth=1, lifeTime=0, parentObjectUniqueId=-1, parentLinkIndex=-1, replaceItemUniqueId=-1, physicsClientId=0):
    """
    Add debug line visualization.
    
    Args:
        lineFromXYZ (list): Start point [x, y, z]
        lineToXYZ (list): End point [x, y, z]
        lineColorRGB (list, optional): RGB color [r, g, b] (0-1 range)
        lineWidth (float, optional): Line width. Defaults to 1.
        lifeTime (float, optional): Display duration in seconds, 0 for permanent
        parentObjectUniqueId (int, optional): Parent object ID
        parentLinkIndex (int, optional): Parent link index
        replaceItemUniqueId (int, optional): Replace existing item ID
        physicsClientId (int, optional): Physics client ID
    
    Returns:
        int: Debug item unique ID
    """

def addUserDebugText(text, textPosition, textColorRGB=None, textSize=1, lifeTime=0, textOrientation=None, parentObjectUniqueId=-1, parentLinkIndex=-1, replaceItemUniqueId=-1, physicsClientId=0):
    """
    Add debug text visualization.
    
    Args:
        text (str): Text to display
        textPosition (list): Text position [x, y, z]
        textColorRGB (list, optional): RGB color [r, g, b] (0-1 range)
        textSize (float, optional): Text size. Defaults to 1.
        lifeTime (float, optional): Display duration in seconds, 0 for permanent
        textOrientation (list, optional): Text orientation quaternion [x, y, z, w]
        parentObjectUniqueId (int, optional): Parent object ID
        parentLinkIndex (int, optional): Parent link index
        replaceItemUniqueId (int, optional): Replace existing item ID
        physicsClientId (int, optional): Physics client ID
    
    Returns:
        int: Debug item unique ID
    """

def addUserDebugPoints(pointPositions, pointColors, pointSizes, lifeTime=0, pointColorRGB=None, parentObjectUniqueId=-1, parentLinkIndex=-1, replaceItemUniqueId=-1, physicsClientId=0):
    """
    Add debug point cloud visualization.
    
    Args:
        pointPositions (list): List of point positions [[x, y, z], ...]
        pointColors (list): List of point colors [[r, g, b], ...]
        pointSizes (list): List of point sizes [size1, size2, ...]
        lifeTime (float, optional): Display duration in seconds, 0 for permanent
        pointColorRGB (list, optional): Default color for all points [r, g, b]
        parentObjectUniqueId (int, optional): Parent object ID
        parentLinkIndex (int, optional): Parent link index
        replaceItemUniqueId (int, optional): Replace existing item ID
        physicsClientId (int, optional): Physics client ID
    
    Returns:
        int: Debug item unique ID
    """

def addUserDebugParameter(paramName, rangeMin, rangeMax, startValue):
    """
    Add debug GUI parameter slider.
    
    Args:
        paramName (str): Parameter name displayed in GUI
        rangeMin (float): Minimum value
        rangeMax (float): Maximum value
        startValue (float): Initial value
    
    Returns:
        int: Parameter unique ID
    """

def readUserDebugParameter(itemUniqueId, physicsClientId=0):
    """
    Read current value of debug parameter.
    
    Args:
        itemUniqueId (int): Parameter unique ID
        physicsClientId (int, optional): Physics client ID
    
    Returns:
        float: Current parameter value
    """

def removeUserDebugItem(itemUniqueId, physicsClientId=0):
    """
    Remove debug visualization item.
    
    Args:
        itemUniqueId (int): Debug item unique ID
        physicsClientId (int, optional): Physics client ID
    """

def removeAllUserDebugItems(physicsClientId=0):
    """
    Remove all debug visualization items.
    
    Args:
        physicsClientId (int, optional): Physics client ID
    """

Visual Configuration

def configureDebugVisualizer(flag, enable, physicsClientId=0):
    """
    Configure debug visualizer settings.
    
    Args:
        flag (int): Visualizer flag (COV_ENABLE_GUI, COV_ENABLE_SHADOWS, etc.)
        enable (int): Enable (1) or disable (0)
        physicsClientId (int, optional): Physics client ID
    """

def resetDebugVisualizerCamera(cameraDistance, cameraYaw, cameraPitch, cameraTargetPosition, physicsClientId=0):
    """
    Reset debug visualizer camera position.
    
    Args:
        cameraDistance (float): Distance from target
        cameraYaw (float): Yaw angle in degrees
        cameraPitch (float): Pitch angle in degrees  
        cameraTargetPosition (list): Target position [x, y, z]
        physicsClientId (int, optional): Physics client ID
    """

def getDebugVisualizerCamera(physicsClientId=0):
    """
    Get debug visualizer camera parameters.
    
    Args:
        physicsClientId (int, optional): Physics client ID
    
    Returns:
        tuple: (width, height, viewMatrix, projectionMatrix, cameraUp, cameraForward,
                horizontal, vertical, yaw, pitch, dist, target)
    """

def setDebugObjectColor(objectUniqueId, linkIndex, objectDebugColorRGB, physicsClientId=0):
    """
    Set debug color for object or link.
    
    Args:
        objectUniqueId (int): Object unique ID
        linkIndex (int): Link index (-1 for base)
        objectDebugColorRGB (list): RGB color [r, g, b] (0-1 range)
        physicsClientId (int, optional): Physics client ID
    """

Texture and Visual Appearance

def loadTexture(textureFilename):
    """
    Load texture from file.
    
    Args:
        textureFilename (str): Path to texture image file
    
    Returns:
        int: Texture unique ID
    """

def changeTexture(textureUniqueId, pixels, width, height):
    """
    Update texture with new pixel data.
    
    Args:
        textureUniqueId (int): Texture unique ID
        pixels (list): Pixel data (RGB format)
        width (int): Texture width
        height (int): Texture height
    """

def changeVisualShape(objectUniqueId, linkIndex, shapeIndex=-1, **kwargs):
    """
    Change visual properties of object or link.
    
    Args:
        objectUniqueId (int): Object unique ID
        linkIndex (int): Link index (-1 for base)
        shapeIndex (int, optional): Shape index
        textureUniqueId (int, optional): New texture ID
        rgbaColor (list, optional): RGBA color [r, g, b, a]
        specularColor (list, optional): Specular color [r, g, b]
        physicsClientId (int, optional): Physics client ID
    """

def getVisualShapeData(objectUniqueId, physicsClientId=0):
    """
    Get visual shape data for object.
    
    Args:
        objectUniqueId (int): Object unique ID
        physicsClientId (int, optional): Physics client ID
    
    Returns:
        list: Visual shape information for each link
    """

def resetVisualShapeData(objectUniqueId, physicsClientId=0):
    """
    Reset visual shape data to original.
    
    Args:
        objectUniqueId (int): Object unique ID
        physicsClientId (int, optional): Physics client ID
    """

Usage Examples

Basic Camera Rendering

import pybullet as p
import numpy as np

# Connect and setup scene
p.connect(p.GUI)
p.loadURDF("plane.urdf")
cube_id = p.loadURDF("cube_small.urdf", [0, 0, 1])

# Camera parameters
width, height = 640, 480
fov, aspect, near, far = 60, width/height, 0.01, 100

# Compute camera matrices
view_matrix = p.computeViewMatrix(
    cameraEyePosition=[2, 2, 2],
    cameraTargetPosition=[0, 0, 0],
    cameraUpVector=[0, 0, 1]
)

proj_matrix = p.computeProjectionMatrixFOV(fov, aspect, near, far)

# Render image
_, _, rgb_img, depth_img, seg_img = p.getCameraImage(
    width, height, view_matrix, proj_matrix
)

# Process images
if isinstance(rgb_img, list):  # Convert to numpy if needed
    rgb_img = np.array(rgb_img).reshape(height, width, 4)[:, :, :3]
    depth_img = np.array(depth_img).reshape(height, width)

print(f"RGB image shape: {rgb_img.shape}")
print(f"Depth image shape: {depth_img.shape}")

Debug Visualization

import pybullet as p
import time

p.connect(p.GUI)
p.loadURDF("plane.urdf")

# Add debug lines
line_id = p.addUserDebugLine(
    lineFromXYZ=[0, 0, 0],
    lineToXYZ=[1, 1, 1],
    lineColorRGB=[1, 0, 0],  # Red
    lineWidth=3,
    lifeTime=0  # Permanent
)

# Add debug text
text_id = p.addUserDebugText(
    text="Origin",
    textPosition=[0, 0, 0.5],
    textColorRGB=[0, 1, 0],  # Green
    textSize=1.5
)

# Add point cloud
points = [[i*0.1, 0, 0.1] for i in range(10)]
colors = [[i/10, 0, 1-i/10] for i in range(10)]
sizes = [0.05] * 10

points_id = p.addUserDebugPoints(
    pointPositions=points,
    pointColors=colors,
    pointSizes=sizes
)

# Add GUI parameter slider
slider_id = p.addUserDebugParameter("Force", 0, 100, 50)

# Interactive loop
for i in range(1000):
    force_value = p.readUserDebugParameter(slider_id)
    p.stepSimulation()
    time.sleep(1./240.)

# Cleanup
p.removeUserDebugItem(line_id)
p.removeAllUserDebugItems()

Camera Control

import pybullet as p

p.connect(p.GUI)
p.loadURDF("plane.urdf")
robot_id = p.loadURDF("r2d2.urdf", [0, 0, 1])

# Configure visualizer
p.configureDebugVisualizer(p.COV_ENABLE_GUI, 1)  # Enable GUI
p.configureDebugVisualizer(p.COV_ENABLE_SHADOWS, 1)  # Enable shadows
p.configureDebugVisualizer(p.COV_ENABLE_WIREFRAME, 0)  # Disable wireframe

# Reset camera position
p.resetDebugVisualizerCamera(
    cameraDistance=3.0,
    cameraYaw=45,
    cameraPitch=-30,
    cameraTargetPosition=[0, 0, 0]
)

# Get current camera info
camera_info = p.getDebugVisualizerCamera()
print(f"Camera distance: {camera_info[10]}")
print(f"Camera target: {camera_info[11]}")

# Set object debug color
p.setDebugObjectColor(robot_id, -1, [1, 0, 0])  # Red base
p.setDebugObjectColor(robot_id, 0, [0, 1, 0])   # Green first link

Texture Management

import pybullet as p

p.connect(p.GUI)

# Load and apply texture
texture_id = p.loadTexture("texture.png")
cube_id = p.loadURDF("cube_small.urdf", [0, 0, 1])

# Change visual appearance
p.changeVisualShape(
    objectUniqueId=cube_id,
    linkIndex=-1,
    textureUniqueId=texture_id,
    rgbaColor=[1, 1, 1, 1]  # White tint
)

# Get visual shape data
visual_data = p.getVisualShapeData(cube_id)
for shape in visual_data:
    print(f"Link {shape[1]}: texture_id={shape[4]}, color={shape[7]}")

# Reset to original appearance
p.resetVisualShapeData(cube_id)

Install with Tessl CLI