tessl/pypi-pybullet

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

—

Pending

Overview

Eval results

Files

Object Loading and Creation

Name: tessl/pypi-pybullet
Author: tessl

Functions for loading robots, objects, and environments from various file formats (URDF, SDF, MJCF), as well as creating collision and visual shapes programmatically. These functions form the foundation for building simulation environments and populating them with objects.

Capabilities

URDF Loading

Load robots and objects from Unified Robot Description Format (URDF) files with extensive configuration options.

def loadURDF(fileName, basePosition=None, baseOrientation=None, useMaximalCoordinates=0, useFixedBase=0, flags=0, globalScaling=1.0, physicsClientId=0):
    """
    Load multibody from URDF file.
    
    Args:
        fileName (str): Path to URDF file (relative to search path or absolute)
        basePosition (list, optional): Initial position [x, y, z]. Defaults to [0, 0, 0].
        baseOrientation (list, optional): Initial orientation as quaternion [x, y, z, w]. 
                                        Defaults to [0, 0, 0, 1].
        useMaximalCoordinates (int, optional): Use maximal coordinates (0=multibody, 1=rigid body). 
                                             Defaults to 0.
        useFixedBase (int, optional): Fix base to world (1) or allow movement (0). Defaults to 0.
        flags (int, optional): Bitwise combination of URDF loading flags. Defaults to 0.
        globalScaling (float, optional): Global scaling factor for all dimensions. Defaults to 1.0.
        physicsClientId (int, optional): Physics client ID. Defaults to 0.
    
    Returns:
        int: Unique body ID for the loaded object
    
    Raises:
        Exception: If file not found or parsing fails
    """

def loadSDF(fileName, useMaximalCoordinates=0, globalScaling=1.0, physicsClientId=0):
    """
    Load objects from Simulation Description Format (SDF) file.
    
    Args:
        fileName (str): Path to SDF file
        useMaximalCoordinates (int, optional): Use maximal coordinates. Defaults to 0.
        globalScaling (float, optional): Global scaling factor. Defaults to 1.0.
        physicsClientId (int, optional): Physics client ID. Defaults to 0.
    
    Returns:
        list: List of unique body IDs for all loaded objects
    """

def loadMJCF(fileName, flags=0, physicsClientId=0):
    """
    Load objects from MuJoCo XML format (MJCF) file.
    
    Args:
        fileName (str): Path to MJCF file
        flags (int, optional): Loading flags. Defaults to 0.
        physicsClientId (int, optional): Physics client ID. Defaults to 0.
    
    Returns:
        list: List of unique body IDs for all loaded objects
    """

def loadBullet(fileName, physicsClientId=0):
    """
    Load world state from .bullet file (PyBullet's binary format).
    
    Args:
        fileName (str): Path to .bullet file
        physicsClientId (int, optional): Physics client ID. Defaults to 0.
    
    Returns:
        list: List of unique body IDs for all loaded objects
    """

Soft Body Loading

def loadSoftBody(fileName, basePosition=None, baseOrientation=None, scale=1.0, mass=1.0, useNeoHookean=0, useBendingSprings=1, useMassSpring=1, springElasticStiffness=0.45, springDampingStiffness=0.1, springDampingAllDirections=1, useSelfCollision=1, frictionCoeff=0.5, useFaceContact=1, physicsClientId=0):
    """
    Load soft body from OBJ mesh file.
    
    Args:
        fileName (str): Path to OBJ file containing triangle mesh
        basePosition (list, optional): Initial position [x, y, z]. Defaults to [0, 0, 0].
        baseOrientation (list, optional): Initial orientation quaternion. Defaults to [0, 0, 0, 1].
        scale (float, optional): Scaling factor for mesh. Defaults to 1.0.
        mass (float, optional): Total mass of soft body. Defaults to 1.0.
        useNeoHookean (int, optional): Use Neo-Hookean material model. Defaults to 0.
        useBendingSprings (int, optional): Add bending springs. Defaults to 1.
        useMassSpring (int, optional): Use mass-spring model. Defaults to 1.
        springElasticStiffness (float, optional): Elastic stiffness. Defaults to 0.45.
        springDampingStiffness (float, optional): Damping stiffness. Defaults to 0.1.
        springDampingAllDirections (int, optional): Apply damping in all directions. Defaults to 1.
        useSelfCollision (int, optional): Enable self collision. Defaults to 1.
        frictionCoeff (float, optional): Friction coefficient. Defaults to 0.5.
        useFaceContact (int, optional): Use face-based contact. Defaults to 1.
        physicsClientId (int, optional): Physics client ID. Defaults to 0.
    
    Returns:
        int: Unique body ID for the soft body
    """

Shape Creation

Create collision and visual shapes programmatically for custom objects.

def createCollisionShape(shapeType, radius=0.5, halfExtents=None, height=1.0, fileName=None, meshScale=None, planeNormal=None, flags=0, physicsClientId=0):
    """
    Create collision shape.
    
    Args:
        shapeType (int): Shape type constant (p.GEOM_SPHERE, p.GEOM_BOX, etc.)
        radius (float, optional): Radius for sphere, cylinder, capsule. Defaults to 0.5.
        halfExtents (list, optional): Half extents [x, y, z] for box. Required for p.GEOM_BOX.
        height (float, optional): Height for cylinder, capsule. Defaults to 1.0.
        fileName (str, optional): Mesh file path for p.GEOM_MESH. Required for mesh shapes.
        meshScale (list, optional): Mesh scaling [x, y, z]. Defaults to [1, 1, 1].
        planeNormal (list, optional): Plane normal [x, y, z] for p.GEOM_PLANE. Defaults to [0, 0, 1].
        flags (int, optional): Shape creation flags. Defaults to 0.
        physicsClientId (int, optional): Physics client ID. Defaults to 0.
    
    Returns:
        int: Collision shape unique ID
    """

def createCollisionShapeArray(shapeTypes, radii=None, halfExtents=None, heights=None, fileNames=None, meshScales=None, planeNormals=None, flags=None, physicsClientId=0):
    """
    Create array of collision shapes efficiently.
    
    Args:
        shapeTypes (list): List of shape type constants
        radii (list, optional): List of radii for spherical shapes
        halfExtents (list, optional): List of half extents for box shapes
        heights (list, optional): List of heights for cylindrical shapes
        fileNames (list, optional): List of mesh file paths
        meshScales (list, optional): List of mesh scales
        planeNormals (list, optional): List of plane normals
        flags (list, optional): List of shape flags
        physicsClientId (int, optional): Physics client ID. Defaults to 0.
    
    Returns:
        list: List of collision shape unique IDs
    """

def createVisualShape(shapeType, radius=0.5, halfExtents=None, height=1.0, fileName=None, meshScale=None, planeNormal=None, rgbaColor=None, specularColor=None, physicsClientId=0):
    """
    Create visual shape for rendering.
    
    Args:
        shapeType (int): Shape type constant
        radius (float, optional): Radius for spherical shapes. Defaults to 0.5.
        halfExtents (list, optional): Half extents for box shapes
        height (float, optional): Height for cylindrical shapes. Defaults to 1.0.
        fileName (str, optional): Mesh file path for visual meshes
        meshScale (list, optional): Mesh scaling factors. Defaults to [1, 1, 1].
        planeNormal (list, optional): Plane normal for plane shapes
        rgbaColor (list, optional): RGBA color [r, g, b, a]. Values 0-1.
        specularColor (list, optional): Specular color [r, g, b]. Values 0-1.
        physicsClientId (int, optional): Physics client ID. Defaults to 0.
    
    Returns:
        int: Visual shape unique ID
    """

def createVisualShapeArray(shapeTypes, radii=None, halfExtents=None, heights=None, fileNames=None, meshScales=None, planeNormals=None, rgbaColors=None, specularColors=None, physicsClientId=0):
    """
    Create array of visual shapes efficiently.
    
    Returns:
        list: List of visual shape unique IDs
    """

Multi-Body Creation

Assemble complex objects from collision shapes, visual shapes, and link hierarchy.

def createMultiBody(baseMass, baseCollisionShapeIndex, baseVisualShapeIndex=-1, basePosition=None, baseOrientation=None, baseInertialFramePosition=None, baseInertialFrameOrientation=None, linkMasses=None, linkCollisionShapeIndices=None, linkVisualShapeIndices=None, linkPositions=None, linkOrientations=None, linkInertialFramePositions=None, linkInertialFrameOrientations=None, linkParentIndices=None, linkJointTypes=None, linkJointAxis=None, physicsClientId=0):
    """
    Create multibody from collision and visual shape components.
    
    Args:
        baseMass (float): Mass of base link
        baseCollisionShapeIndex (int): Collision shape ID for base (-1 for none)
        baseVisualShapeIndex (int, optional): Visual shape ID for base. Defaults to -1.
        basePosition (list, optional): Base position [x, y, z]. Defaults to [0, 0, 0].
        baseOrientation (list, optional): Base orientation quaternion. Defaults to [0, 0, 0, 1].
        baseInertialFramePosition (list, optional): Inertial frame position offset
        baseInertialFrameOrientation (list, optional): Inertial frame orientation offset
        linkMasses (list, optional): List of link masses
        linkCollisionShapeIndices (list, optional): List of collision shape IDs for links
        linkVisualShapeIndices (list, optional): List of visual shape IDs for links
        linkPositions (list, optional): List of link positions relative to parent
        linkOrientations (list, optional): List of link orientations relative to parent
        linkInertialFramePositions (list, optional): List of inertial frame positions
        linkInertialFrameOrientations (list, optional): List of inertial frame orientations
        linkParentIndices (list, optional): List of parent link indices
        linkJointTypes (list, optional): List of joint type constants
        linkJointAxis (list, optional): List of joint axes
        physicsClientId (int, optional): Physics client ID. Defaults to 0.
    
    Returns:
        int: Unique body ID for created multibody
    """

Object Removal

def removeBody(bodyUniqueId, physicsClientId=0):
    """
    Remove body from simulation.
    
    Args:
        bodyUniqueId (int): Body unique ID to remove
        physicsClientId (int, optional): Physics client ID. Defaults to 0.
    """

def removeCollisionShape(collisionShapeId, physicsClientId=0):
    """
    Remove collision shape (if not used by any body).
    
    Args:
        collisionShapeId (int): Collision shape ID to remove
        physicsClientId (int, optional): Physics client ID. Defaults to 0.
    """

URDF Loading Flags

Use these flags with loadURDF() to control loading behavior:

# Inertia and dynamics
p.URDF_USE_INERTIA_FROM_FILE          # Use inertia tensor from URDF file
p.URDF_USE_IMPLICIT_CYLINDER          # Use implicit cylinder for collision

# Collision and physics
p.URDF_USE_SELF_COLLISION             # Enable self-collision detection
p.URDF_USE_SELF_COLLISION_EXCLUDE_PARENT      # Self collision but exclude parent links
p.URDF_USE_SELF_COLLISION_EXCLUDE_ALL_PARENTS # Self collision but exclude all parent links

# Visual and materials
p.URDF_USE_MATERIAL_COLORS_FROM_MTL   # Use colors from MTL material files
p.URDF_USE_MATERIAL_TRANSPARANCY_FROM_MTL     # Use transparency from MTL files

# Performance optimizations
p.URDF_MERGE_FIXED_LINKS             # Merge fixed joints for better performance
p.URDF_ENABLE_CACHED_GRAPHICS_SHAPES # Cache graphics shapes for reuse
p.URDF_ENABLE_SLEEPING               # Enable object sleeping for inactive bodies

# Behavior control
p.URDF_MAINTAIN_LINK_ORDER           # Preserve link order from URDF
p.URDF_IGNORE_VISUAL_SHAPES          # Skip loading visual shapes
p.URDF_IGNORE_COLLISION_SHAPES       # Skip loading collision shapes
p.URDF_PRINT_URDF_INFO              # Print URDF parsing information

# Advanced features
p.URDF_GLOBAL_VELOCITIES_MB          # Use global velocities for multibody
p.URDF_INITIALIZE_SAT_FEATURES       # Initialize SAT collision features
p.URDF_ENABLE_WAKEUP                 # Enable automatic wakeup for sleeping bodies

Usage Examples

Basic Object Loading

import pybullet as p
import pybullet_data

p.connect(p.GUI)
p.setAdditionalSearchPath(pybullet_data.getDataPath())

# Load ground plane
planeId = p.loadURDF("plane.urdf")

# Load robot at specific position and orientation
startPos = [0, 0, 1]
startOrientation = p.getQuaternionFromEuler([0, 0, 0])
robotId = p.loadURDF("r2d2.urdf", startPos, startOrientation)

# Load with specific flags for performance
robotId2 = p.loadURDF("pr2_gripper.urdf", 
                      basePosition=[2, 0, 1],
                      flags=p.URDF_MERGE_FIXED_LINKS | p.URDF_USE_INERTIA_FROM_FILE)

Creating Custom Primitives

import pybullet as p

p.connect(p.GUI)

# Create collision shapes
sphereCol = p.createCollisionShape(p.GEOM_SPHERE, radius=0.5)
boxCol = p.createCollisionShape(p.GEOM_BOX, halfExtents=[0.5, 0.5, 0.5])
cylinderCol = p.createCollisionShape(p.GEOM_CYLINDER, radius=0.3, height=1.0)

# Create visual shapes with colors
sphereVis = p.createVisualShape(p.GEOM_SPHERE, radius=0.5, rgbaColor=[1, 0, 0, 1])
boxVis = p.createVisualShape(p.GEOM_BOX, halfExtents=[0.5, 0.5, 0.5], rgbaColor=[0, 1, 0, 1])
cylinderVis = p.createVisualShape(p.GEOM_CYLINDER, radius=0.3, height=1.0, rgbaColor=[0, 0, 1, 1])

# Create multibodies
sphereId = p.createMultiBody(baseMass=1.0, 
                            baseCollisionShapeIndex=sphereCol,
                            baseVisualShapeIndex=sphereVis,
                            basePosition=[0, 0, 2])

boxId = p.createMultiBody(baseMass=1.0,
                         baseCollisionShapeIndex=boxCol,
                         baseVisualShapeIndex=boxVis,
                         basePosition=[2, 0, 2])

cylinderId = p.createMultiBody(baseMass=1.0,
                              baseCollisionShapeIndex=cylinderCol,
                              baseVisualShapeIndex=cylinderVis,
                              basePosition=[-2, 0, 2])

Loading Mesh Objects

import pybullet as p

p.connect(p.GUI)

# Create collision shape from mesh file
meshCol = p.createCollisionShape(p.GEOM_MESH, 
                                fileName="path/to/mesh.obj",
                                meshScale=[1, 1, 1])

# Create visual shape from same or different mesh
meshVis = p.createVisualShape(p.GEOM_MESH,
                             fileName="path/to/visual_mesh.obj",
                             meshScale=[1, 1, 1],
                             rgbaColor=[0.5, 0.5, 0.5, 1])

# Create object from mesh
meshId = p.createMultiBody(baseMass=0,  # Static object
                          baseCollisionShapeIndex=meshCol,
                          baseVisualShapeIndex=meshVis,
                          basePosition=[0, 0, 0])

Complex Multi-Link Object

import pybullet as p

p.connect(p.GUI)

# Create shapes for base and links
baseCol = p.createCollisionShape(p.GEOM_BOX, halfExtents=[0.5, 0.5, 0.1])
linkCol = p.createCollisionShape(p.GEOM_CYLINDER, radius=0.1, height=0.5)

baseVis = p.createVisualShape(p.GEOM_BOX, halfExtents=[0.5, 0.5, 0.1], rgbaColor=[0.2, 0.2, 0.8, 1])
linkVis = p.createVisualShape(p.GEOM_CYLINDER, radius=0.1, height=0.5, rgbaColor=[0.8, 0.2, 0.2, 1])

# Create 2-link object
multiBodyId = p.createMultiBody(
    baseMass=1.0,
    baseCollisionShapeIndex=baseCol,
    baseVisualShapeIndex=baseVis,
    basePosition=[0, 0, 1],
    linkMasses=[0.5, 0.5],
    linkCollisionShapeIndices=[linkCol, linkCol],
    linkVisualShapeIndices=[linkVis, linkVis],
    linkPositions=[[0, 0, 0.3], [0, 0, 0.6]],
    linkOrientations=[[0, 0, 0, 1], [0, 0, 0, 1]],
    linkParentIndices=[0, 1],
    linkJointTypes=[p.JOINT_REVOLUTE, p.JOINT_REVOLUTE],
    linkJointAxis=[[1, 0, 0], [1, 0, 0]]
)

Soft Body Creation

import pybullet as p

p.connect(p.GUI)

# Load soft body from mesh
softBodyId = p.loadSoftBody("path/to/cloth.obj",
                           basePosition=[0, 0, 2],
                           mass=1.0,
                           useNeoHookean=1,
                           springElasticStiffness=0.45,
                           springDampingStiffness=0.1,
                           useSelfCollision=1,
                           frictionCoeff=0.5)

Best Practices

Use appropriate loading flags - p.URDF_MERGE_FIXED_LINKS for better performance
Set search paths - Use p.setAdditionalSearchPath() for asset directories
Batch shape creation - Use createCollisionShapeArray() for multiple similar shapes
Consider memory usage - Remove unused bodies and shapes to free memory
Validate file paths - Check file existence before loading to handle errors gracefully
Use global scaling - Scale objects uniformly rather than modifying source files