0
# Vedo
1

2
A comprehensive Python library for scientific visualization and analysis of 3D objects, meshes, volumes, and point clouds built on top of VTK (Visualization Toolkit). Vedo provides an intuitive, high-level interface for creating interactive 3D visualizations, processing geometric data, and performing scientific analysis tasks with extensive support for various file formats, advanced rendering features, and seamless integration into Jupyter notebooks.
3

4
## Package Information
5

6
- **Package Name**: vedo
7
- **Language**: Python
8
- **Installation**: `pip install vedo`
9
- **Dependencies**: vtk, numpy, typing-extensions, Pygments
10

11
## Core Imports
12

13
```python
14
import vedo
15
```
16

17
Common import patterns:
18

19
```python
20
# Import specific classes and functions
21
from vedo import Mesh, Points, Volume, Plotter, show
22

23
# Import plotting functions
24
from vedo import plot, histogram
25

26
# Import shape generation functions  
27
from vedo import Sphere, Box, Line, Text3D
28

29
# Import utilities
30
from vedo import load, save, printc
31
```
32

33
## Basic Usage
34

35
```python
36
import vedo
37
from vedo import Sphere, Box, Plotter, show
38

39
# Create 3D objects
40
sphere = Sphere(pos=(0, 0, 0), r=1.0, c='red')
41
box = Box(pos=(2, 0, 0), length=1.5, width=1.0, height=0.8, c='blue')
42

43
# Simple visualization
44
show(sphere, box, title="Basic 3D Scene")
45

46
# Advanced plotting with Plotter
47
plt = Plotter(title="Interactive Scene")
48
plt.add(sphere)
49
plt.add(box)
50
plt.show()
51

52
# Load and visualize 3D files
53
mesh = vedo.load("model.stl")
54
mesh.color('green').alpha(0.8)
55
show(mesh)
56

57
# Point cloud analysis
58
points = vedo.Points([[0,0,0], [1,1,1], [2,0,1]], c='orange')
59
fitted_plane = vedo.fit_plane(points)
60
show(points, fitted_plane)
61
```
62

63
## Architecture
64

65
Vedo's architecture is built around VTK with intuitive Python interfaces:
66

67
- **Core Objects**: Mesh, Points, Volume, Image classes for different data types
68
- **Visual System**: CommonVisual base classes providing rendering and styling capabilities  
69
- **Plotter**: Central rendering engine managing scenes, cameras, and user interaction
70
- **Algorithms**: Extensive collection of geometric processing and analysis functions
71
- **I/O System**: Comprehensive file format support for import/export operations
72

73
The design provides both high-level convenience functions and low-level VTK access, enabling everything from quick data visualization to complex scientific applications.
74

75
## Capabilities
76

77
### Core Data Objects
78

79
Primary classes for representing and manipulating 3D data including meshes, point clouds, volumetric data, and 2D images. These objects provide the foundation for all visualization and analysis operations.
80

81
```python { .api }
82
class Mesh(MeshVisual, Points):
83
    def __init__(self, inputobj=None, c="gold", alpha=1): ...
84

85
class Points(PointsVisual, PointAlgorithms):
86
    def __init__(self, inputobj=None, r=4, c="red", alpha=1): ...
87

88
class Volume(VolumeAlgorithms, VolumeVisual):
89
    def __init__(self, inputobj=None, c="RdYlBu_r", alpha=(0.0, 0.0, 0.2, 0.4, 0.8, 1.0)): ...
90

91
class Image(ImageVisual):
92
    def __init__(self, obj=None, channels=3): ...
93
```
94

95
[Core Objects](./core-objects.md)
96

97
### Shape Generation
98

99
Comprehensive library of 3D shape primitives, geometric constructions, and procedural generation tools. Includes basic shapes, curves, splines, text rendering, and complex geometric forms.
100

101
```python { .api }
102
class Sphere:
103
    def __init__(self, pos=(0, 0, 0), r=1, res=24, quads=False, c="red", alpha=1): ...
104

105
class Box:
106
    def __init__(self, pos=(0, 0, 0), length=1, width=1, height=1, c="gold", alpha=1): ...
107

108
class Line:
109
    def __init__(self, p0, p1=None, res=1, lw=1, c="red", alpha=1): ...
110

111
class Text3D:
112
    def __init__(self, txt, pos=(0, 0, 0), s=1, font="", hspacing=1.15, vspacing=2.15, depth=0, italic=False, justify="bottom-left", c="black", alpha=1): ...
113
```
114

115
[Shape Generation](./shape-generation.md)
116

117
### Plotting and Visualization
118

119
Main visualization system including the Plotter class for scene management, matplotlib-style pyplot interface, and specialized plotting functions for scientific data visualization.
120

121
```python { .api }
122
class Plotter:
123
    def __init__(self, shape=(1, 1), N=None, pos=(0, 0), size="auto", screensize="auto", title="vedo", bg="white", bg2=None, axes=None): ...
124

125
def show(*objects, **kwargs): ...
126

127
def plot(*args, **kwargs): ...
128
def histogram(*args, **kwargs): ...
129
def fit(points, deg=1, niter=1000, nstd=3): ...
130
```
131

132
[Plotting and Visualization](./plotting-visualization.md)
133

134
### File I/O Operations
135

136
Comprehensive file format support for loading and saving 3D data, with functions for various mesh formats, volumetric data, images, and specialized scientific data formats.
137

138
```python { .api }
139
def load(filename, unpack=True, force=False): ...
140
def save(obj, filename, binary=True): ...
141
def download(url, filename=None, force=False, verbose=True): ...
142
def screenshot(filename="screenshot.png", scale=1, asarray=False): ...
143
```
144

145
[File I/O Operations](./file-io.md)
146

147
### Colors and Visual Properties
148

149
Color management system including color conversion functions, colormap application, palette generation, and visual styling utilities for enhancing 3D visualizations.
150

151
```python { .api }
152
def get_color(rgb=None, hsv=None): ...
153
def color_map(value, name="jet", vmin=None, vmax=None): ...
154
def build_palette(color1, color2, n, hsv=True): ...
155
def printc(*strings, c=None, bc=None, bold=False, italic=False, blink=False, underline=False, strike=False, dim=False, invert=False, box="", end="\\n", flush=False): ...
156
```
157

158
[Colors and Visual Properties](./colors-visual.md)
159

160
### Transformations and Geometry
161

162
Geometric transformation utilities, coordinate system conversions, and spatial analysis functions for manipulating and analyzing 3D data.
163

164
```python { .api }
165
class LinearTransform:
166
    def __init__(self, T): ...
167

168
def cart2spher(x, y, z): ...
169
def spher2cart(rho, theta, phi): ...
170
def fit_plane(points, signed=False): ...
171
def fit_sphere(coords): ...
172
```
173

174
[Transformations and Geometry](./transformations-geometry.md)
175

176
### User Interface Components
177

178
Interactive widgets and UI elements including sliders, buttons, scalar bars, legends, and measurement tools for creating interactive 3D applications.
179

180
```python { .api }
181
class Slider2D:
182
    def __init__(self, func, xmin, xmax, value=None, pos=4, title="", font="Calco", titleSize=1, c=None, alpha=1, showValue=True, delayed=False, **options): ...
183

184
class ScalarBar:
185
    def __init__(self, obj, title="", pos=(0.775, 0.05), titleYOffset=15, titleFontSize=12, size=(None, None), nlabels=None, c=None, horizontal=False, useAlpha=True): ...
186

187
class Light:
188
    def __init__(self, pos, focalPoint=(0, 0, 0), deg=180, c="white", intensity=1): ...
189
```
190

191
[User Interface Components](./ui-components.md)
192

193
### Analysis and Algorithms
194

195
Advanced algorithms for geometric analysis, point cloud processing, mesh operations, and scientific computations including fitting, clustering, and morphological operations.
196

197
```python { .api }
198
def merge(*meshs, flag=False): ...
199
def pca_ellipse(points, pvalue=0.673, res=60): ...
200
def procrustes_alignment(sources, rigid=False): ...
201

202
class ProgressBar:
203
    def __init__(self, start, stop, step=1, c="red", title="", width=24, char="█", bg="", logFile=None, delay=-1, ETA=True): ...
204
```
205

206
[Analysis and Algorithms](./analysis-algorithms.md)
207

208
### Specialized Applications
209

210
Ready-to-use applications for common scientific visualization tasks including volume slicing, isosurface browsing, interactive drawing, animation creation, and morphing between 3D objects.
211

212
```python { .api }
213
class Slicer3DPlotter(Plotter):
214
    def __init__(self, volume, cmaps=("gist_ncar_r", "hot_r", "bone"), clamp=True, show_histo=True): ...
215

216
class IsosurfaceBrowser(Plotter):
217
    def __init__(self, volume, isovalue=None, c="gold", alpha=1.0, cmap="hot"): ...
218

219
class FreeHandCutPlotter(Plotter):
220
    def __init__(self, obj, splined=True, font="", alpha=1.0): ...
221

222
class AnimationPlayer(Plotter):
223
    def __init__(self, sequence, fps=24, loop=True, show_controls=True): ...
224
```
225

226
[Specialized Applications](./applications.md)
227

228
## Types
229

230
```python { .api }
231
# Core type aliases
232
from typing import Union, List, Tuple, Optional, Any
233
import numpy as np
234

235
# Common type patterns used throughout vedo
236
ColorLike = Union[str, Tuple[float, float, float], List[float]]
237
PointLike = Union[List[float], Tuple[float, float, float], np.ndarray]
238
MeshLike = Union[str, "Mesh", "Points", "vtk.vtkPolyData", "vtk.vtkActor"]
239
```