0
# Rendering and Visualization
1

2
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.
3

4
## Capabilities
5

6
### Camera Image Rendering
7

8
```python { .api }
9
def getCameraImage(width, height, viewMatrix, projectionMatrix, shadow=1, lightDirection=None, lightColor=None, lightDistance=None, lightAmbientCoeff=None, lightDiffuseCoeff=None, lightSpecularCoeff=None, renderer=None, physicsClientId=0):
10
    """
11
    Render camera image from specified viewpoint.
12
    
13
    Args:
14
        width (int): Image width in pixels
15
        height (int): Image height in pixels  
16
        viewMatrix (list): 4x4 view matrix (16 elements)
17
        projectionMatrix (list): 4x4 projection matrix (16 elements)
18
        shadow (int, optional): Enable shadows (0/1). Defaults to 1.
19
        lightDirection (list, optional): Light direction [x, y, z]
20
        lightColor (list, optional): Light color [r, g, b]
21
        lightDistance (float, optional): Light distance
22
        lightAmbientCoeff (float, optional): Ambient light coefficient
23
        lightDiffuseCoeff (float, optional): Diffuse light coefficient
24
        lightSpecularCoeff (float, optional): Specular light coefficient
25
        renderer (int, optional): Renderer type (ER_BULLET_HARDWARE_OPENGL, ER_TINY_RENDERER)
26
        physicsClientId (int, optional): Physics client ID. Defaults to 0.
27
    
28
    Returns:
29
        tuple: (width, height, rgbPixels, depthPixels, segmentationMaskBuffer)
30
            - rgbPixels: RGB image as numpy array or list
31
            - depthPixels: Depth buffer as numpy array or list
32
            - segmentationMaskBuffer: Segmentation mask with object IDs
33
    """
34
```
35

36
### Camera Matrix Computation
37

38
```python { .api }
39
def computeViewMatrix(cameraEyePosition, cameraTargetPosition, cameraUpVector):
40
    """
41
    Compute view matrix for camera positioning.
42
    
43
    Args:
44
        cameraEyePosition (list): Camera position [x, y, z]
45
        cameraTargetPosition (list): Target position [x, y, z]
46
        cameraUpVector (list): Up vector [x, y, z]
47
    
48
    Returns:
49
        list: 4x4 view matrix (16 elements)
50
    """
51

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

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

58
def computeProjectionMatrixFOV(fov, aspect, nearVal, farVal):
59
    """Compute projection matrix from field of view."""
60
```
61

62
### Debug Visualization
63

64
```python { .api }
65
def addUserDebugLine(lineFromXYZ, lineToXYZ, lineColorRGB=None, lineWidth=1, lifeTime=0, parentObjectUniqueId=-1, parentLinkIndex=-1, replaceItemUniqueId=-1, physicsClientId=0):
66
    """
67
    Add debug line visualization.
68
    
69
    Args:
70
        lineFromXYZ (list): Start point [x, y, z]
71
        lineToXYZ (list): End point [x, y, z]
72
        lineColorRGB (list, optional): RGB color [r, g, b] (0-1 range)
73
        lineWidth (float, optional): Line width. Defaults to 1.
74
        lifeTime (float, optional): Display duration in seconds, 0 for permanent
75
        parentObjectUniqueId (int, optional): Parent object ID
76
        parentLinkIndex (int, optional): Parent link index
77
        replaceItemUniqueId (int, optional): Replace existing item ID
78
        physicsClientId (int, optional): Physics client ID
79
    
80
    Returns:
81
        int: Debug item unique ID
82
    """
83

84
def addUserDebugText(text, textPosition, textColorRGB=None, textSize=1, lifeTime=0, textOrientation=None, parentObjectUniqueId=-1, parentLinkIndex=-1, replaceItemUniqueId=-1, physicsClientId=0):
85
    """
86
    Add debug text visualization.
87
    
88
    Args:
89
        text (str): Text to display
90
        textPosition (list): Text position [x, y, z]
91
        textColorRGB (list, optional): RGB color [r, g, b] (0-1 range)
92
        textSize (float, optional): Text size. Defaults to 1.
93
        lifeTime (float, optional): Display duration in seconds, 0 for permanent
94
        textOrientation (list, optional): Text orientation quaternion [x, y, z, w]
95
        parentObjectUniqueId (int, optional): Parent object ID
96
        parentLinkIndex (int, optional): Parent link index
97
        replaceItemUniqueId (int, optional): Replace existing item ID
98
        physicsClientId (int, optional): Physics client ID
99
    
100
    Returns:
101
        int: Debug item unique ID
102
    """
103

104
def addUserDebugPoints(pointPositions, pointColors, pointSizes, lifeTime=0, pointColorRGB=None, parentObjectUniqueId=-1, parentLinkIndex=-1, replaceItemUniqueId=-1, physicsClientId=0):
105
    """
106
    Add debug point cloud visualization.
107
    
108
    Args:
109
        pointPositions (list): List of point positions [[x, y, z], ...]
110
        pointColors (list): List of point colors [[r, g, b], ...]
111
        pointSizes (list): List of point sizes [size1, size2, ...]
112
        lifeTime (float, optional): Display duration in seconds, 0 for permanent
113
        pointColorRGB (list, optional): Default color for all points [r, g, b]
114
        parentObjectUniqueId (int, optional): Parent object ID
115
        parentLinkIndex (int, optional): Parent link index
116
        replaceItemUniqueId (int, optional): Replace existing item ID
117
        physicsClientId (int, optional): Physics client ID
118
    
119
    Returns:
120
        int: Debug item unique ID
121
    """
122

123
def addUserDebugParameter(paramName, rangeMin, rangeMax, startValue):
124
    """
125
    Add debug GUI parameter slider.
126
    
127
    Args:
128
        paramName (str): Parameter name displayed in GUI
129
        rangeMin (float): Minimum value
130
        rangeMax (float): Maximum value
131
        startValue (float): Initial value
132
    
133
    Returns:
134
        int: Parameter unique ID
135
    """
136

137
def readUserDebugParameter(itemUniqueId, physicsClientId=0):
138
    """
139
    Read current value of debug parameter.
140
    
141
    Args:
142
        itemUniqueId (int): Parameter unique ID
143
        physicsClientId (int, optional): Physics client ID
144
    
145
    Returns:
146
        float: Current parameter value
147
    """
148

149
def removeUserDebugItem(itemUniqueId, physicsClientId=0):
150
    """
151
    Remove debug visualization item.
152
    
153
    Args:
154
        itemUniqueId (int): Debug item unique ID
155
        physicsClientId (int, optional): Physics client ID
156
    """
157

158
def removeAllUserDebugItems(physicsClientId=0):
159
    """
160
    Remove all debug visualization items.
161
    
162
    Args:
163
        physicsClientId (int, optional): Physics client ID
164
    """
165
```
166

167
### Visual Configuration
168

169
```python { .api }
170
def configureDebugVisualizer(flag, enable, physicsClientId=0):
171
    """
172
    Configure debug visualizer settings.
173
    
174
    Args:
175
        flag (int): Visualizer flag (COV_ENABLE_GUI, COV_ENABLE_SHADOWS, etc.)
176
        enable (int): Enable (1) or disable (0)
177
        physicsClientId (int, optional): Physics client ID
178
    """
179

180
def resetDebugVisualizerCamera(cameraDistance, cameraYaw, cameraPitch, cameraTargetPosition, physicsClientId=0):
181
    """
182
    Reset debug visualizer camera position.
183
    
184
    Args:
185
        cameraDistance (float): Distance from target
186
        cameraYaw (float): Yaw angle in degrees
187
        cameraPitch (float): Pitch angle in degrees  
188
        cameraTargetPosition (list): Target position [x, y, z]
189
        physicsClientId (int, optional): Physics client ID
190
    """
191

192
def getDebugVisualizerCamera(physicsClientId=0):
193
    """
194
    Get debug visualizer camera parameters.
195
    
196
    Args:
197
        physicsClientId (int, optional): Physics client ID
198
    
199
    Returns:
200
        tuple: (width, height, viewMatrix, projectionMatrix, cameraUp, cameraForward,
201
                horizontal, vertical, yaw, pitch, dist, target)
202
    """
203

204
def setDebugObjectColor(objectUniqueId, linkIndex, objectDebugColorRGB, physicsClientId=0):
205
    """
206
    Set debug color for object or link.
207
    
208
    Args:
209
        objectUniqueId (int): Object unique ID
210
        linkIndex (int): Link index (-1 for base)
211
        objectDebugColorRGB (list): RGB color [r, g, b] (0-1 range)
212
        physicsClientId (int, optional): Physics client ID
213
    """
214
```
215

216
### Texture and Visual Appearance
217

218
```python { .api }
219
def loadTexture(textureFilename):
220
    """
221
    Load texture from file.
222
    
223
    Args:
224
        textureFilename (str): Path to texture image file
225
    
226
    Returns:
227
        int: Texture unique ID
228
    """
229

230
def changeTexture(textureUniqueId, pixels, width, height):
231
    """
232
    Update texture with new pixel data.
233
    
234
    Args:
235
        textureUniqueId (int): Texture unique ID
236
        pixels (list): Pixel data (RGB format)
237
        width (int): Texture width
238
        height (int): Texture height
239
    """
240

241
def changeVisualShape(objectUniqueId, linkIndex, shapeIndex=-1, **kwargs):
242
    """
243
    Change visual properties of object or link.
244
    
245
    Args:
246
        objectUniqueId (int): Object unique ID
247
        linkIndex (int): Link index (-1 for base)
248
        shapeIndex (int, optional): Shape index
249
        textureUniqueId (int, optional): New texture ID
250
        rgbaColor (list, optional): RGBA color [r, g, b, a]
251
        specularColor (list, optional): Specular color [r, g, b]
252
        physicsClientId (int, optional): Physics client ID
253
    """
254

255
def getVisualShapeData(objectUniqueId, physicsClientId=0):
256
    """
257
    Get visual shape data for object.
258
    
259
    Args:
260
        objectUniqueId (int): Object unique ID
261
        physicsClientId (int, optional): Physics client ID
262
    
263
    Returns:
264
        list: Visual shape information for each link
265
    """
266

267
def resetVisualShapeData(objectUniqueId, physicsClientId=0):
268
    """
269
    Reset visual shape data to original.
270
    
271
    Args:
272
        objectUniqueId (int): Object unique ID
273
        physicsClientId (int, optional): Physics client ID
274
    """
275
```
276

277
## Usage Examples
278

279
### Basic Camera Rendering
280

281
```python
282
import pybullet as p
283
import numpy as np
284

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

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

294
# Compute camera matrices
295
view_matrix = p.computeViewMatrix(
296
    cameraEyePosition=[2, 2, 2],
297
    cameraTargetPosition=[0, 0, 0],
298
    cameraUpVector=[0, 0, 1]
299
)
300

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

303
# Render image
304
_, _, rgb_img, depth_img, seg_img = p.getCameraImage(
305
    width, height, view_matrix, proj_matrix
306
)
307

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

313
print(f"RGB image shape: {rgb_img.shape}")
314
print(f"Depth image shape: {depth_img.shape}")
315
```
316

317
### Debug Visualization
318

319
```python
320
import pybullet as p
321
import time
322

323
p.connect(p.GUI)
324
p.loadURDF("plane.urdf")
325

326
# Add debug lines
327
line_id = p.addUserDebugLine(
328
    lineFromXYZ=[0, 0, 0],
329
    lineToXYZ=[1, 1, 1],
330
    lineColorRGB=[1, 0, 0],  # Red
331
    lineWidth=3,
332
    lifeTime=0  # Permanent
333
)
334

335
# Add debug text
336
text_id = p.addUserDebugText(
337
    text="Origin",
338
    textPosition=[0, 0, 0.5],
339
    textColorRGB=[0, 1, 0],  # Green
340
    textSize=1.5
341
)
342

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

348
points_id = p.addUserDebugPoints(
349
    pointPositions=points,
350
    pointColors=colors,
351
    pointSizes=sizes
352
)
353

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

357
# Interactive loop
358
for i in range(1000):
359
    force_value = p.readUserDebugParameter(slider_id)
360
    p.stepSimulation()
361
    time.sleep(1./240.)
362

363
# Cleanup
364
p.removeUserDebugItem(line_id)
365
p.removeAllUserDebugItems()
366
```
367

368
### Camera Control
369

370
```python
371
import pybullet as p
372

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

377
# Configure visualizer
378
p.configureDebugVisualizer(p.COV_ENABLE_GUI, 1)  # Enable GUI
379
p.configureDebugVisualizer(p.COV_ENABLE_SHADOWS, 1)  # Enable shadows
380
p.configureDebugVisualizer(p.COV_ENABLE_WIREFRAME, 0)  # Disable wireframe
381

382
# Reset camera position
383
p.resetDebugVisualizerCamera(
384
    cameraDistance=3.0,
385
    cameraYaw=45,
386
    cameraPitch=-30,
387
    cameraTargetPosition=[0, 0, 0]
388
)
389

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

395
# Set object debug color
396
p.setDebugObjectColor(robot_id, -1, [1, 0, 0])  # Red base
397
p.setDebugObjectColor(robot_id, 0, [0, 1, 0])   # Green first link
398
```
399

400
### Texture Management
401

402
```python
403
import pybullet as p
404

405
p.connect(p.GUI)
406

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

411
# Change visual appearance
412
p.changeVisualShape(
413
    objectUniqueId=cube_id,
414
    linkIndex=-1,
415
    textureUniqueId=texture_id,
416
    rgbaColor=[1, 1, 1, 1]  # White tint
417
)
418

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

424
# Reset to original appearance
425
p.resetVisualShapeData(cube_id)
426
```