0
# 3D Visualizations
1

2
Three-dimensional plotting capabilities including 3D scatter plots, surfaces, meshes, and volume rendering.
3

4
## Capabilities
5

6
### 3D Scatter Plots
7

8
Three-dimensional scatter plots for visualizing relationships between three variables.
9

10
```javascript { .api }
11
/**
12
 * 3D scatter plot trace configuration
13
 */
14
interface Scatter3DTrace {
15
  type: 'scatter3d';
16
  x: number[];
17
  y: number[];
18
  z: number[];
19
  mode?: 'markers' | 'lines' | 'markers+lines' | 'markers+lines+text' | 'text';
20
  name?: string;
21
  text?: string | string[];
22
  textposition?: string;
23
  marker?: {
24
    size?: number | number[];
25
    color?: string | string[] | number[];
26
    symbol?: string | string[];
27
    opacity?: number | number[];
28
    line?: {
29
      color?: string | string[];
30
      width?: number | number[];
31
    };
32
    colorscale?: string;
33
    showscale?: boolean;
34
    colorbar?: Partial<ColorBar>;
35
    cauto?: boolean;
36
    cmin?: number;
37
    cmax?: number;
38
  };
39
  line?: {
40
    color?: string | string[];
41
    width?: number;
42
    dash?: string;
43
  };
44
}
45
```
46

47
**Usage Examples:**
48

49
```javascript
50
// Basic 3D scatter plot
51
Plotly.newPlot('myDiv', [{
52
    x: [1, 2, 3, 4, 5],
53
    y: [1, 4, 2, 8, 5],
54
    z: [2, 1, 7, 3, 9],
55
    type: 'scatter3d',
56
    mode: 'markers',
57
    marker: {
58
        size: 8,
59
        color: 'red'
60
    }
61
}]);
62

63
// 3D line plot
64
Plotly.newPlot('myDiv', [{
65
    x: [1, 2, 3, 4, 5],
66
    y: [1, 4, 2, 8, 5], 
67
    z: [2, 1, 7, 3, 9],
68
    type: 'scatter3d',
69
    mode: 'lines+markers',
70
    line: {
71
        color: 'blue',
72
        width: 6
73
    },
74
    marker: {
75
        size: 4,
76
        color: 'red'
77
    }
78
}]);
79

80
// Colored 3D scatter plot
81
Plotly.newPlot('myDiv', [{
82
    x: [1, 2, 3, 4, 5],
83
    y: [1, 4, 2, 8, 5],
84
    z: [2, 1, 7, 3, 9],
85
    type: 'scatter3d',
86
    mode: 'markers',
87
    marker: {
88
        size: [10, 15, 20, 25, 30],
89
        color: [1, 2, 3, 4, 5],
90
        colorscale: 'Viridis',
91
        showscale: true,
92
        opacity: 0.8
93
    }
94
}]);
95
```
96

97
### 3D Surface Plots
98

99
Surface plots for visualizing functions of two variables.
100

101
```javascript { .api }
102
/**
103
 * 3D surface plot trace configuration
104
 */
105
interface SurfaceTrace {
106
  type: 'surface';
107
  z: number[][];
108
  x?: number[] | number[][];
109
  y?: number[] | number[][];
110
  surfacecolor?: number[][];
111
  colorscale?: string;
112
  showscale?: boolean;
113
  colorbar?: Partial<ColorBar>;
114
  opacity?: number;
115
  cauto?: boolean;
116
  cmin?: number;
117
  cmax?: number;
118
  contours?: {
119
    x?: Partial<SurfaceContour>;
120
    y?: Partial<SurfaceContour>;
121
    z?: Partial<SurfaceContour>;
122
  };
123
  hidesurface?: boolean;
124
  lighting?: Partial<SurfaceLighting>;
125
  lightposition?: {
126
    x?: number;
127
    y?: number;
128
    z?: number;
129
  };
130
}
131

132
interface SurfaceContour {
133
  show?: boolean;
134
  color?: string;
135
  width?: number;
136
  start?: number;
137
  end?: number;
138
  size?: number;
139
  project?: {
140
    x?: boolean;
141
    y?: boolean;
142
    z?: boolean;
143
  };
144
}
145

146
interface SurfaceLighting {
147
  ambient?: number;
148
  diffuse?: number;
149
  specular?: number;
150
  roughness?: number;
151
  fresnel?: number;
152
}
153
```
154

155
**Usage Examples:**
156

157
```javascript
158
// Generate surface data
159
function generateSurfaceData() {
160
    const size = 20;
161
    const x = [];
162
    const y = [];
163
    const z = [];
164
    
165
    for (let i = 0; i < size; i++) {
166
        z[i] = [];
167
        for (let j = 0; j < size; j++) {
168
            const xVal = -5 + (10 * i) / (size - 1);
169
            const yVal = -5 + (10 * j) / (size - 1);
170
            z[i][j] = Math.sin(Math.sqrt(xVal * xVal + yVal * yVal));
171
            
172
            if (i === 0) y.push(yVal);
173
        }
174
        x.push(-5 + (10 * i) / (size - 1));
175
    }
176
    
177
    return { x, y, z };
178
}
179

180
// Basic surface plot
181
const surfaceData = generateSurfaceData();
182
Plotly.newPlot('myDiv', [{
183
    type: 'surface',
184
    x: surfaceData.x,
185
    y: surfaceData.y,
186
    z: surfaceData.z,
187
    colorscale: 'Viridis'
188
}]);
189

190
// Surface with contours
191
Plotly.newPlot('myDiv', [{
192
    type: 'surface',
193
    z: surfaceData.z,
194
    colorscale: 'Blues',
195
    contours: {
196
        z: {
197
            show: true,
198
            usecolormap: true,
199
            highlightcolor: '#42f462',
200
            project: { z: true }
201
        }
202
    }
203
}]);
204

205
// Surface with custom lighting
206
Plotly.newPlot('myDiv', [{
207
    type: 'surface',
208
    z: surfaceData.z,
209
    colorscale: 'Portland',
210
    lighting: {
211
        ambient: 0.4,
212
        diffuse: 0.8,
213
        specular: 2.0,
214
        roughness: 0.1,
215
        fresnel: 0.2
216
    },
217
    lightposition: {
218
        x: 100,
219
        y: 200,
220
        z: 0
221
    }
222
}]);
223
```
224

225
### 3D Mesh Plots
226

227
3D mesh plots for visualizing irregular 3D surfaces and geometries.
228

229
```javascript { .api }
230
/**
231
 * 3D mesh plot trace configuration
232
 */
233
interface Mesh3DTrace {
234
  type: 'mesh3d';
235
  x: number[];
236
  y: number[];
237
  z: number[];
238
  i?: number[];
239
  j?: number[];
240
  k?: number[];
241
  intensity?: number[];
242
  color?: string;
243
  colorscale?: string;
244
  showscale?: boolean;
245
  colorbar?: Partial<ColorBar>;
246
  opacity?: number;
247
  alphahull?: number;
248
  delaunayaxis?: 'x' | 'y' | 'z';
249
  facecolor?: string[];
250
  flatshading?: boolean;
251
  lighting?: Partial<MeshLighting>;
252
  lightposition?: {
253
    x?: number;
254
    y?: number;
255
    z?: number;
256
  };
257
}
258

259
interface MeshLighting {
260
  ambient?: number;
261
  diffuse?: number;
262
  specular?: number;
263
  roughness?: number;
264
  fresnel?: number;
265
  vertexnormalsepsilon?: number;
266
  facenormalsepsilon?: number;
267
}
268
```
269

270
**Usage Examples:**
271

272
```javascript
273
// Basic mesh plot (convex hull)
274
const meshData = {
275
    x: [0, 1, 2, 0, 1, 2, 0, 1, 2],
276
    y: [0, 0, 0, 1, 1, 1, 2, 2, 2],
277
    z: [0, 0, 0, 1, 1, 1, 0, 0, 0]
278
};
279

280
Plotly.newPlot('myDiv', [{
281
    type: 'mesh3d',
282
    x: meshData.x,
283
    y: meshData.y,
284
    z: meshData.z,
285
    color: 'lightblue',
286
    opacity: 0.7
287
}]);
288

289
// Mesh with explicit triangulation
290
Plotly.newPlot('myDiv', [{
291
    type: 'mesh3d',
292
    x: [0, 1, 0, 0],
293
    y: [0, 0, 1, 0],
294
    z: [0, 0, 0, 1],
295
    i: [0, 0, 0, 1],
296
    j: [1, 2, 3, 2],
297
    k: [2, 3, 1, 3],
298
    intensity: [0, 0.25, 0.5, 1],
299
    colorscale: 'Rainbow',
300
    showscale: true
301
}]);
302

303
// Colored mesh with intensity
304
Plotly.newPlot('myDiv', [{
305
    type: 'mesh3d',
306
    x: meshData.x,
307
    y: meshData.y,
308
    z: meshData.z,
309
    intensity: [0, 1, 2, 0, 1, 2, 0, 1, 2],
310
    colorscale: 'Viridis',
311
    showscale: true,
312
    opacity: 0.8
313
}]);
314
```
315

316
### Volume Plots
317

318
Volume rendering for 3D scalar field visualization.
319

320
```javascript { .api }
321
/**
322
 * Volume plot trace configuration
323
 */
324
interface VolumeTrace {
325
  type: 'volume';
326
  x?: number[];
327
  y?: number[];
328
  z?: number[];
329
  value: number[][][];
330
  isomin?: number;
331
  isomax?: number;
332
  opacity?: number | number[];
333
  opacityscale?: string | number[][];
334
  colorscale?: string;
335
  showscale?: boolean;
336
  colorbar?: Partial<ColorBar>;
337
  caps?: {
338
    x?: Partial<VolumeCap>;
339
    y?: Partial<VolumeCap>;
340
    z?: Partial<VolumeCap>;
341
  };
342
  slices?: {
343
    x?: Partial<VolumeSlice>;
344
    y?: Partial<VolumeSlice>;
345
    z?: Partial<VolumeSlice>;
346
  };
347
  surface?: Partial<VolumeSurface>;
348
  spaceframe?: Partial<VolumeSpaceframe>;
349
}
350

351
interface VolumeCap {
352
  show?: boolean;
353
  fill?: number;
354
}
355

356
interface VolumeSlice {
357
  show?: boolean;
358
  locations?: number[];
359
  fill?: number;
360
}
361

362
interface VolumeSurface {
363
  show?: boolean;
364
  count?: number;
365
  fill?: number;
366
  pattern?: 'all' | 'odd' | 'even';
367
}
368

369
interface VolumeSpaceframe {
370
  show?: boolean;
371
  fill?: number;
372
}
373
```
374

375
**Usage Examples:**
376

377
```javascript
378
// Generate volume data
379
function generateVolumeData() {
380
    const size = 20;
381
    const value = [];
382
    
383
    for (let i = 0; i < size; i++) {
384
        value[i] = [];
385
        for (let j = 0; j < size; j++) {
386
            value[i][j] = [];
387
            for (let k = 0; k < size; k++) {
388
                const x = (i - size/2) / 5;
389
                const y = (j - size/2) / 5;
390
                const z = (k - size/2) / 5;
391
                value[i][j][k] = x*x + y*y + z*z;
392
            }
393
        }
394
    }
395
    
396
    return value;
397
}
398

399
// Basic volume plot
400
const volumeData = generateVolumeData();
401
Plotly.newPlot('myDiv', [{
402
    type: 'volume',
403
    value: volumeData,
404
    isomin: 0.1,
405
    isomax: 2.0,
406
    opacity: 0.1,
407
    surface: {
408
        show: true,
409
        count: 17
410
    }
411
}]);
412

413
// Volume with slices
414
Plotly.newPlot('myDiv', [{
415
    type: 'volume',
416
    value: volumeData,
417
    colorscale: 'Hot',
418
    slices: {
419
        z: {
420
            show: true,
421
            locations: [0.1, 0.5, 0.9]
422
        }
423
    },
424
    caps: {
425
        x: { show: false },
426
        y: { show: false },
427
        z: { show: false }
428
    }
429
}]);
430
```
431

432
### Isosurface Plots
433

434
Isosurface plots for visualizing constant-value surfaces in 3D scalar fields.
435

436
```javascript { .api }
437
/**
438
 * Isosurface plot trace configuration
439
 */
440
interface IsosurfaceTrace {
441
  type: 'isosurface';
442
  x?: number[];
443
  y?: number[];
444
  z?: number[];
445
  value: number[][][];
446
  isomin?: number;
447
  isomax?: number;
448
  surface?: Partial<IsosurfaceSurface>;
449
  caps?: Partial<IsosurfaceCaps>;
450
  colorscale?: string;
451
  showscale?: boolean;
452
  colorbar?: Partial<ColorBar>;
453
}
454

455
interface IsosurfaceSurface {
456
  show?: boolean;
457
  count?: number;
458
  fill?: number;
459
  pattern?: 'all' | 'odd' | 'even';
460
}
461

462
interface IsosurfaceCaps {
463
  x?: Partial<IsosurfaceCap>;
464
  y?: Partial<IsosurfaceCap>;
465
  z?: Partial<IsosurfaceCap>;
466
}
467

468
interface IsosurfaceCap {
469
  show?: boolean;
470
  fill?: number;
471
}
472
```
473

474
**Usage Examples:**
475

476
```javascript
477
// Basic isosurface
478
Plotly.newPlot('myDiv', [{
479
    type: 'isosurface',
480
    value: volumeData,
481
    isomin: 0.5,
482
    isomax: 1.5,
483
    surface: {
484
        show: true,
485
        count: 5
486
    },
487
    colorscale: 'Blues'
488
}]);
489
```
490

491
### 3D Layout Configuration
492

493
Layout options specific to 3D scenes.
494

495
```javascript { .api }
496
/**
497
 * 3D scene configuration
498
 */
499
interface Scene {
500
  bgcolor?: string;
501
  camera?: Partial<Camera>;
502
  domain?: {
503
    x?: [number, number];
504
    y?: [number, number];
505
  };
506
  aspectmode?: 'auto' | 'cube' | 'data' | 'manual';
507
  aspectratio?: {
508
    x?: number;
509
    y?: number;
510
    z?: number;
511
  };
512
  xaxis?: Partial<Scene3DAxis>;
513
  yaxis?: Partial<Scene3DAxis>;
514
  zaxis?: Partial<Scene3DAxis>;
515
  dragmode?: 'orbit' | 'turntable' | 'zoom' | 'pan' | false;
516
  hovermode?: 'closest' | false;
517
  annotations?: Partial<Scene3DAnnotation>[];
518
}
519

520
interface Camera {
521
  up?: { x?: number; y?: number; z?: number; };
522
  center?: { x?: number; y?: number; z?: number; };
523
  eye?: { x?: number; y?: number; z?: number; };
524
  projection?: {
525
    type?: 'perspective' | 'orthographic';
526
  };
527
}
528

529
interface Scene3DAxis {
530
  title?: string | Partial<AxisTitle>;
531
  type?: 'linear' | 'log' | 'date' | 'category';
532
  range?: [number, number];
533
  autorange?: boolean | 'reversed';
534
  showgrid?: boolean;
535
  gridcolor?: string;
536
  gridwidth?: number;
537
  showline?: boolean;
538
  linecolor?: string;
539
  linewidth?: number;
540
  showspikes?: boolean;
541
  spikecolor?: string;
542
  spikesides?: boolean;
543
  spikethickness?: number;
544
  showbackground?: boolean;
545
  backgroundcolor?: string;
546
  showaxeslabels?: boolean;
547
  color?: string;
548
  tickmode?: 'linear' | 'array';
549
  nticks?: number;
550
  tick0?: number;
551
  dtick?: number;
552
  tickvals?: number[];
553
  ticktext?: string[];
554
  ticks?: '' | 'outside' | 'inside';
555
  mirror?: boolean | 'ticks' | 'all' | 'allticks';
556
  ticklen?: number;
557
  tickwidth?: number;
558
  tickcolor?: string;
559
  tickfont?: Partial<Font>;
560
  tickangle?: number;
561
  tickformat?: string;
562
  exponentformat?: 'none' | 'e' | 'E' | 'power' | 'SI' | 'B';
563
  showexponent?: 'all' | 'first' | 'last' | 'none';
564
  zeroline?: boolean;
565
  zerolinecolor?: string;
566
  zerolinewidth?: number;
567
}
568
```
569

570
**Usage Examples:**
571

572
```javascript
573
// 3D plot with custom scene configuration
574
Plotly.newPlot('myDiv', [{
575
    type: 'scatter3d',
576
    x: [1, 2, 3, 4, 5],
577
    y: [1, 4, 2, 8, 5],
578
    z: [2, 1, 7, 3, 9],
579
    mode: 'markers'
580
}], {
581
    scene: {
582
        bgcolor: 'black',
583
        xaxis: {
584
            title: 'X Axis',
585
            color: 'white',
586
            gridcolor: 'gray'
587
        },
588
        yaxis: {
589
            title: 'Y Axis',
590
            color: 'white',
591
            gridcolor: 'gray'
592
        },
593
        zaxis: {
594
            title: 'Z Axis',
595
            color: 'white',
596
            gridcolor: 'gray'
597
        },
598
        camera: {
599
            eye: { x: 1.5, y: 1.5, z: 1.5 }
600
        },
601
        aspectmode: 'cube'
602
    }
603
});
604

605
// Multiple 3D scenes
606
Plotly.newPlot('myDiv', [
607
    {
608
        type: 'scatter3d',
609
        x: [1, 2, 3],
610
        y: [1, 2, 3],
611
        z: [1, 2, 3],
612
        scene: 'scene'
613
    },
614
    {
615
        type: 'scatter3d',
616
        x: [4, 5, 6],
617
        y: [4, 5, 6],
618
        z: [4, 5, 6],
619
        scene: 'scene2'
620
    }
621
], {
622
    scene: {
623
        domain: { x: [0, 0.5], y: [0, 1] },
624
        camera: { eye: { x: 2, y: 2, z: 2 } }
625
    },
626
    scene2: {
627
        domain: { x: [0.5, 1], y: [0, 1] },
628
        camera: { eye: { x: -2, y: -2, z: 2 } }
629
    }
630
});
631
```