0
# 3D Charts
1

2
Three-dimensional visualizations with advanced rendering capabilities including 3D coordinate systems, lighting effects, materials, and interactive camera controls. These charts leverage WebGL for high-performance 3D graphics in web browsers.
3

4
## Capabilities
5

6
### 3D Bar Charts
7

8
Three-dimensional bar charts for categorical data with depth and perspective.
9

10
```python { .api }
11
class Bar3D:
12
    def __init__(self, init_opts=None, render_opts=None):
13
        """
14
        Initialize a 3D bar chart.
15
        
16
        Args:
17
            init_opts (InitOpts, optional): Chart initialization options
18
            render_opts (RenderOpts, optional): Rendering options
19
        """
20

21
    def add(self, series_name, data, **kwargs):
22
        """
23
        Add 3D bar data.
24
        
25
        Args:
26
            series_name (str): Name of the data series
27
            data (list): List of [x, y, z] coordinate triplets
28
            xaxis3d_opts (Axis3DOpts, optional): X-axis configuration
29
            yaxis3d_opts (Axis3DOpts, optional): Y-axis configuration  
30
            zaxis3d_opts (Axis3DOpts, optional): Z-axis configuration
31
            grid3d_opts (Grid3DOpts, optional): 3D grid configuration
32
            
33
        Returns:
34
            Bar3D: Self for method chaining
35
        """
36
```
37

38
**Usage Example:**
39
```python
40
from pyecharts.charts import Bar3D
41
from pyecharts import options as opts
42
import random
43

44
data = []
45
for i in range(10):
46
    for j in range(10):
47
        data.append([i, j, random.randint(0, 100)])
48

49
bar3d = (
50
    Bar3D()
51
    .add("Data", data)
52
    .set_global_opts(title_opts=opts.TitleOpts(title="3D Bar Chart"))
53
)
54
```
55

56
### 3D Scatter Charts
57

58
Three-dimensional scatter plots for exploring relationships in three variables.
59

60
```python { .api }
61
class Scatter3D:
62
    def __init__(self, init_opts=None, render_opts=None):
63
        """
64
        Initialize a 3D scatter chart.
65
        
66
        Args:
67
            init_opts (InitOpts, optional): Chart initialization options
68
            render_opts (RenderOpts, optional): Rendering options
69
        """
70

71
    def add(self, series_name, data, **kwargs):
72
        """
73
        Add 3D scatter data.
74
        
75
        Args:
76
            series_name (str): Name of the data series
77
            data (list): List of [x, y, z] coordinate triplets or [x, y, z, value] quadruplets
78
            symbol (str, optional): Point symbol type
79
            symbol_size (int|list, optional): Point size
80
            itemstyle_opts (ItemStyleOpts, optional): Point styling
81
            xaxis3d_opts (Axis3DOpts, optional): X-axis configuration
82
            yaxis3d_opts (Axis3DOpts, optional): Y-axis configuration
83
            zaxis3d_opts (Axis3DOpts, optional): Z-axis configuration
84
            grid3d_opts (Grid3DOpts, optional): 3D grid configuration
85
            
86
        Returns:
87
            Scatter3D: Self for method chaining
88
        """
89
```
90

91
### 3D Line Charts
92

93
Three-dimensional line charts connecting points in 3D space.
94

95
```python { .api }
96
class Line3D:
97
    def __init__(self, init_opts=None, render_opts=None):
98
        """
99
        Initialize a 3D line chart.
100
        
101
        Args:
102
            init_opts (InitOpts, optional): Chart initialization options
103
            render_opts (RenderOpts, optional): Rendering options
104
        """
105

106
    def add(self, series_name, data, **kwargs):
107
        """
108
        Add 3D line data.
109
        
110
        Args:
111
            series_name (str): Name of the data series
112
            data (list): List of [x, y, z] coordinate triplets
113
            linestyle_opts (LineStyleOpts, optional): Line styling
114
            xaxis3d_opts (Axis3DOpts, optional): X-axis configuration
115
            yaxis3d_opts (Axis3DOpts, optional): Y-axis configuration
116
            zaxis3d_opts (Axis3DOpts, optional): Z-axis configuration
117
            grid3d_opts (Grid3DOpts, optional): 3D grid configuration
118
            
119
        Returns:
120
            Line3D: Self for method chaining
121
        """
122
```
123

124
### 3D Multi-Line Charts
125

126
Multiple line series in 3D space with animation effects.
127

128
```python { .api }
129
class Lines3D:
130
    def __init__(self, init_opts=None, render_opts=None):
131
        """
132
        Initialize a 3D multi-line chart.
133
        
134
        Args:
135
            init_opts (InitOpts, optional): Chart initialization options
136
            render_opts (RenderOpts, optional): Rendering options
137
        """
138

139
    def add(self, series_name, data, **kwargs):
140
        """
141
        Add 3D lines data.
142
        
143
        Args:
144
            series_name (str): Name of the data series
145
            data (list): List of [start_point, end_point] pairs where each point is [x, y, z]
146
            effect_opts (Lines3DEffectOpts, optional): Animation effects
147
            linestyle_opts (LineStyleOpts, optional): Line styling
148
            xaxis3d_opts (Axis3DOpts, optional): X-axis configuration
149
            yaxis3d_opts (Axis3DOpts, optional): Y-axis configuration
150
            zaxis3d_opts (Axis3DOpts, optional): Z-axis configuration
151
            grid3d_opts (Grid3DOpts, optional): 3D grid configuration
152
            
153
        Returns:
154
            Lines3D: Self for method chaining
155
        """
156
```
157

158
### 3D Surface Charts
159

160
Surface plots for visualizing functions of two variables or 3D terrain data.
161

162
```python { .api }
163
class Surface3D:
164
    def __init__(self, init_opts=None, render_opts=None):
165
        """
166
        Initialize a 3D surface chart.
167
        
168
        Args:
169
            init_opts (InitOpts, optional): Chart initialization options
170
            render_opts (RenderOpts, optional): Rendering options
171
        """
172

173
    def add(self, series_name, data, **kwargs):
174
        """
175
        Add 3D surface data.
176
        
177
        Args:
178
            series_name (str): Name of the data series
179
            data (list): 2D array of z-values or list of [x, y, z] triplets
180
            is_parametric (bool, optional): Whether data is parametric
181
            wire_frame (dict, optional): Wireframe styling
182
            itemstyle_opts (ItemStyleOpts, optional): Surface styling
183
            xaxis3d_opts (Axis3DOpts, optional): X-axis configuration
184
            yaxis3d_opts (Axis3DOpts, optional): Y-axis configuration
185
            zaxis3d_opts (Axis3DOpts, optional): Z-axis configuration
186
            grid3d_opts (Grid3DOpts, optional): 3D grid configuration
187
            
188
        Returns:
189
            Surface3D: Self for method chaining
190
        """
191
```
192

193
### 3D Geographic Maps
194

195
Three-dimensional geographic visualizations with elevation and depth.
196

197
```python { .api }
198
class Map3D:
199
    def __init__(self, init_opts=None, render_opts=None):
200
        """
201
        Initialize a 3D map chart.
202
        
203
        Args:
204
            init_opts (InitOpts, optional): Chart initialization options
205
            render_opts (RenderOpts, optional): Rendering options
206
        """
207

208
    def add(self, series_name, data_pair, **kwargs):
209
        """
210
        Add 3D map data.
211
        
212
        Args:
213
            series_name (str): Name of the data series
214
            data_pair (list): List of [region_name, value] pairs
215
            maptype (str): Map type identifier
216
            itemstyle_opts (ItemStyleOpts, optional): Region styling
217
            label_opts (Map3DLabelOpts, optional): Label configuration
218
            emphasis_opts (Emphasis3DOpts, optional): Hover effects
219
            light_opts (Map3DLightOpts, optional): Lighting configuration
220
            viewcontrol_opts (Map3DViewControlOpts, optional): Camera controls
221
            posteffect_opts (Map3DPostEffectOpts, optional): Post-processing effects
222
            
223
        Returns:
224
            Map3D: Self for method chaining
225
        """
226
```
227

228
### 3D Globe Visualizations
229

230
Interactive globe representations for global geographic data.
231

232
```python { .api }
233
class MapGlobe:
234
    def __init__(self, init_opts=None, render_opts=None):
235
        """
236
        Initialize a 3D globe chart.
237
        
238
        Args:
239
            init_opts (InitOpts, optional): Chart initialization options
240
            render_opts (RenderOpts, optional): Rendering options
241
        """
242

243
    def add(self, series_name, data_pair, **kwargs):
244
        """
245
        Add globe data.
246
        
247
        Args:
248
            series_name (str): Name of the data series
249
            data_pair (list): List of [location_name, value] pairs
250
            maptype (str): Map type ("world" for global)
251
            is_roam (bool, optional): Enable globe rotation
252
            
253
        Returns:
254
            MapGlobe: Self for method chaining
255
        """
256
```
257

258
### 3D Network Graphs
259

260
Three-dimensional network visualizations with advanced force-directed layouts.
261

262
```python { .api }
263
class GraphGL:
264
    def __init__(self, init_opts=None, render_opts=None):
265
        """
266
        Initialize a 3D graph chart.
267
        
268
        Args:
269
            init_opts (InitOpts, optional): Chart initialization options
270
            render_opts (RenderOpts, optional): Rendering options
271
        """
272

273
    def add(self, series_name, nodes, links, **kwargs):
274
        """
275
        Add 3D graph data.
276
        
277
        Args:
278
            series_name (str): Name of the data series
279
            nodes (list): List of GraphGLNode objects or node dictionaries
280
            links (list): List of GraphGLLink objects or link dictionaries
281
            layout (str, optional): Layout algorithm ("force", "circular", "none")
282
            force_atlas2_opts (GraphGLForceAtlas2Opts, optional): Force layout options
283
            itemstyle_opts (ItemStyleOpts, optional): Node styling
284
            linestyle_opts (LineStyleOpts, optional): Edge styling
285
            
286
        Returns:
287
            GraphGL: Self for method chaining
288
        """
289
```
290

291
## 3D Configuration Options
292

293
### 3D Coordinate System
294

295
```python { .api }
296
class Axis3DOpts:
297
    def __init__(self, **kwargs):
298
        """
299
        3D axis configuration.
300
        
301
        Args:
302
            type_ (str): Axis type ("value", "category", "time", "log")
303
            name (str): Axis name
304
            min_ (numeric): Minimum value
305
            max_ (numeric): Maximum value
306
            data (list): Category data for category axes
307
            axislabel_opts (LabelOpts): Axis label styling
308
            axisline_opts (AxisLineOpts): Axis line styling
309
            axistick_opts (AxisTickOpts): Axis tick styling
310
            splitline_opts (SplitLineOpts): Grid line styling
311
        """
312

313
class Grid3DOpts:
314
    def __init__(self, **kwargs):
315
        """
316
        3D grid configuration.
317
        
318
        Args:
319
            width (int): Grid width
320
            height (int): Grid height  
321
            depth (int): Grid depth
322
            is_rotate (bool): Enable auto-rotation
323
            rotate_speed (int): Rotation speed
324
            rotate_sensitivity (int): Mouse rotation sensitivity
325
            zoom_sensitivity (int): Zoom sensitivity
326
            pan_sensitivity (int): Pan sensitivity
327
            distance (int): Camera distance
328
            alpha (int): Horizontal rotation angle
329
            beta (int): Vertical rotation angle
330
            center (list): Grid center position [x, y, z]
331
            box_width (int): 3D box width
332
            box_height (int): 3D box height
333
            box_depth (int): 3D box depth
334
        """
335
```
336

337
### 3D Lighting and Materials
338

339
```python { .api }
340
class Map3DLightOpts:
341
    def __init__(self, **kwargs):
342
        """
343
        3D lighting configuration.
344
        
345
        Args:
346
            main_color (str): Main light color
347
            main_intensity (float): Main light intensity
348
            main_shadow (bool): Enable main light shadows
349
            main_shadow_quality (str): Shadow quality ("low", "medium", "high", "ultra")
350
            main_beta (int): Main light elevation angle
351
            ambient_color (str): Ambient light color
352
            ambient_intensity (float): Ambient light intensity
353
        """
354

355
class Map3DColorMaterialOpts:
356
    def __init__(self, **kwargs):
357
        """3D color material options."""
358

359
class Map3DLambertMaterialOpts:
360
    def __init__(self, **kwargs):
361
        """3D Lambert material options for matte surfaces."""
362

363
class Map3DRealisticMaterialOpts:
364
    def __init__(self, **kwargs):
365
        """3D realistic material options with reflectance and roughness."""
366
```
367

368
### 3D View Controls
369

370
```python { .api }
371
class Map3DViewControlOpts:
372
    def __init__(self, **kwargs):
373
        """
374
        3D view control configuration.
375
        
376
        Args:
377
            projection (str): Projection type ("perspective", "orthographic")
378
            auto_rotate (bool): Enable auto-rotation
379
            auto_rotate_direction (str): Rotation direction ("cw", "ccw")
380
            auto_rotate_speed (int): Rotation speed
381
            damping (float): Damping factor for smooth interaction
382
            roam (bool): Enable mouse interaction
383
            rotate_sensitivity (int): Rotation sensitivity
384
            zoom_sensitivity (int): Zoom sensitivity
385
            pan_sensitivity (int): Pan sensitivity
386
            pan_mouse_button (str): Mouse button for panning
387
            rotate_mouse_button (str): Mouse button for rotation
388
            distance (int): Camera distance
389
            min_distance (int): Minimum camera distance
390
            max_distance (int): Maximum camera distance
391
            orthographic_size (int): Orthographic view size
392
            max_orthographic_size (int): Maximum orthographic size
393
            min_orthographic_size (int): Minimum orthographic size
394
            alpha (int): Horizontal rotation angle
395
            beta (int): Vertical rotation angle
396
            center (list): View center [x, y, z]
397
            min_alpha (int): Minimum alpha angle
398
            max_alpha (int): Maximum alpha angle
399
            min_beta (int): Minimum beta angle
400
            max_beta (int): Maximum beta angle
401
        """
402
```
403

404
### 3D Post-Processing Effects
405

406
```python { .api }
407
class Map3DPostEffectOpts:
408
    def __init__(self, **kwargs):
409
        """
410
        3D post-processing effects.
411
        
412
        Args:
413
            is_enable (bool): Enable post-processing
414
            bloom_enable (bool): Enable bloom effect
415
            bloom_intensity (float): Bloom intensity
416
            depth_of_field_enable (bool): Enable depth of field
417
            depth_of_field_focal_distance (float): Focal distance
418
            depth_of_field_focal_range (float): Focal range
419
            depth_of_field_f_stop (float): F-stop value
420
            depth_of_field_blur_radius (int): Blur radius
421
            screen_space_ambient_occlusion_enable (bool): Enable SSAO
422
            screen_space_ambient_occlusion_quality (str): SSAO quality
423
            screen_space_ambient_occlusion_radius (float): SSAO radius
424
            screen_space_ambient_occlusion_intensity (float): SSAO intensity
425
            screen_space_reflection_enable (bool): Enable screen space reflections
426
            screen_space_reflection_quality (str): SSR quality
427
            screen_space_reflection_max_roughness (float): Maximum roughness for reflections
428
            temporal_super_sampling_enable (bool): Enable temporal super sampling
429
        """
430
```
431

432
## 3D Data Types
433

434
```python { .api }
435
class GraphGLNode:
436
    def __init__(self, **kwargs):
437
        """
438
        3D graph node.
439
        
440
        Args:
441
            id (str): Node identifier
442
            name (str): Node display name
443
            value (list): 3D position [x, y, z]
444
            category (str): Node category
445
            symbol (str): Node symbol
446
            symbol_size (int): Node size
447
            itemstyle_opts (ItemStyleOpts): Node styling
448
        """
449

450
class GraphGLLink:
451
    def __init__(self, **kwargs):
452
        """
453
        3D graph edge/link.
454
        
455
        Args:
456
            source (str): Source node ID
457
            target (str): Target node ID
458
            value (numeric): Link weight/value
459
            linestyle_opts (LineStyleOpts): Link styling
460
        """
461

462
class GraphGLForceAtlas2Opts:
463
    def __init__(self, **kwargs):
464
        """
465
        3D force-directed layout configuration.
466
        
467
        Args:
468
            gpu (bool): Use GPU acceleration
469
            steps (int): Number of simulation steps
470
            stop_threshold (float): Stop threshold
471
            bar_nes_theta (float): Barnes-Hut theta parameter
472
            repulsion_by_degree (bool): Repulsion based on node degree
473
            lin_log_mode (bool): Use lin-log mode
474
            gravity (float): Gravity strength
475
            scaling_ratio (float): Scaling ratio
476
            strong_gravity_mode (bool): Strong gravity mode
477
            gravity_center (list): Gravity center [x, y, z]
478
        """
479

480
class Lines3DEffectOpts:
481
    def __init__(self, **kwargs):
482
        """
483
        3D line animation effects.
484
        
485
        Args:
486
            is_show (bool): Show effects
487
            period (int): Animation period
488
            delay (int): Animation delay
489
            constant_speed (int): Constant animation speed
490
            symbol (str): Effect symbol
491
            symbol_size (int): Effect symbol size
492
            color (str): Effect color
493
            opacity (float): Effect opacity
494
            trail_length (float): Trail length ratio
495
        """
496
```