0
# File I/O Operations
1

2
Comprehensive file format support for loading and saving 3D data, with functions for various mesh formats, volumetric data, images, and specialized scientific data formats. Vedo provides extensive I/O capabilities for integrating with existing workflows and data pipelines.
3

4
## Capabilities
5

6
### Loading 3D Data
7

8
Primary functions for loading various 3D file formats and data sources.
9

10
```python { .api }
11
def load(filename, unpack=True, force=False):
12
    """
13
    Load 3D objects from various file formats.
14
    
15
    Supported formats: STL, OBJ, PLY, VTK, VTP, VTU, VTS, VTI, XML, 
16
    3DS, X3D, COLLADA, OFF, NRRD, DICOM, TIF, PNG, JPG, BMP, and more.
17
    
18
    Parameters:
19
    - filename: str or list
20
        File path(s) to load
21
    - unpack: bool, default True
22
        If False, return list even for single file
23
    - force: bool, default False
24
        Force reload even if already cached
25
        
26
    Returns:
27
    Mesh, Points, Volume, Image, or list: Loaded object(s)
28
    """
29

30
def read(filename, unpack=True, force=False):
31
    """
32
    Alias for load() function.
33
    
34
    Parameters:
35
    - filename: str or list
36
        File path(s) to load
37
    - unpack: bool, default True
38
        If False, return list even for single file
39
    - force: bool, default False
40
        Force reload even if already cached
41
        
42
    Returns:
43
    Mesh, Points, Volume, Image, or list: Loaded object(s)
44
    """
45

46
def download(url, filename=None, force=False, verbose=True):
47
    """
48
    Download files from URLs.
49
    
50
    Parameters:
51
    - url: str
52
        URL to download from
53
    - filename: str, optional
54
        Local filename to save to
55
    - force: bool, default False
56
        Force re-download if file exists
57
    - verbose: bool, default True
58
        Print download progress
59
        
60
    Returns:
61
    str: Path to downloaded file
62
    """
63

64
def gunzip(filename):
65
    """
66
    Decompress gzipped files.
67
    
68
    Parameters:
69
    - filename: str
70
        Path to gzipped file
71
        
72
    Returns:
73
    str: Path to decompressed file
74
    """
75
```
76

77
### Saving 3D Data
78

79
Functions for exporting vedo objects to various file formats.
80

81
```python { .api }
82
def save(obj, filename, binary=True):
83
    """
84
    Save vedo objects to files.
85
    
86
    Supported formats: STL, OBJ, PLY, VTK, VTP, VTU, X3D, 
87
    COLLADA, OFF, and more based on file extension.
88
    
89
    Parameters:
90
    - obj: vedo object
91
        Object to save (Mesh, Points, Volume, etc.)
92
    - filename: str
93
        Output file path with extension
94
    - binary: bool, default True
95
        Use binary format when available
96
        
97
    Returns:
98
    str: Path to saved file
99
    """
100

101
def write(obj, filename, binary=True):
102
    """
103
    Alias for save() function.
104
    
105
    Parameters:
106
    - obj: vedo object
107
        Object to save
108
    - filename: str
109
        Output file path
110
    - binary: bool, default True
111
        Use binary format when available
112
        
113
    Returns:
114
    str: Path to saved file
115
    """
116
```
117

118
### Specialized Data Loading
119

120
Functions for loading specific data types and formats.
121

122
```python { .api }
123
def loadStructuredPoints(filename):
124
    """
125
    Load VTK structured points data.
126
    
127
    Parameters:
128
    - filename: str
129
        Path to structured points file
130
        
131
    Returns:
132
    Volume: Loaded volume object
133
    """
134

135
def loadStructuredGrid(filename):
136
    """
137
    Load VTK structured grid data.
138
    
139
    Parameters:
140
    - filename: str
141
        Path to structured grid file
142
        
143
    Returns:
144
    StructuredGrid: Loaded grid object
145
    """
146
```
147

148
### Window and Screenshot Operations
149

150
Functions for capturing and managing visualization windows.
151

152
```python { .api }
153
def screenshot(filename="screenshot.png", scale=1, asarray=False):
154
    """
155
    Capture screenshot of current visualization.
156
    
157
    Parameters:
158
    - filename: str, default "screenshot.png"
159
        Output image filename
160
    - scale: int, default 1
161
        Image scaling factor for resolution
162
    - asarray: bool, default False
163
        Return numpy array instead of saving file
164
        
165
    Returns:
166
    str or numpy.ndarray: Filename or image array
167
    """
168

169
def export_window(filename, binary=False):
170
    """
171
    Export entire rendering window state.
172
    
173
    Parameters:
174
    - filename: str
175
        Output file path
176
    - binary: bool, default False
177
        Use binary format
178
        
179
    Returns:
180
    str: Path to exported file
181
    """
182

183
def import_window(filename):
184
    """
185
    Import rendering window state from file.
186
    
187
    Parameters:
188
    - filename: str
189
        Path to window state file
190
        
191
    Returns:
192
    Plotter: Restored plotter instance
193
    """
194
```
195

196
### Video Generation
197

198
Class for creating animations and video sequences.
199

200
```python { .api }
201
class Video:
202
    """
203
    Create video sequences from vedo visualizations.
204
    
205
    Parameters:
206
    - name: str, default "movie.mp4"
207
        Output video filename
208
    - fps: int, default 24
209
        Frames per second
210
    - duration: float, optional
211
        Total video duration in seconds
212
    - backend: str, default "ffmpeg"
213
        Video encoding backend
214
    """
215
    def __init__(self, name="movie.mp4", fps=24, duration=None, backend="ffmpeg"): ...
216
    
217
    def add_frame(self):
218
        """Add current visualization as video frame."""
219
    
220
    def pause(self, pause=0):
221
        """
222
        Add pause/delay in video.
223
        
224
        Parameters:
225
        - pause: float, default 0
226
            Pause duration in seconds
227
        """
228
    
229
    def close(self):
230
        """Finalize and save video file."""
231
```
232

233
### Format-Specific Information
234

235
Details about supported file formats and their capabilities.
236

237
```python { .api }
238
# Supported input formats (load/read):
239
MESH_FORMATS = [
240
    ".stl",      # Stereolithography
241
    ".obj",      # Wavefront OBJ  
242
    ".ply",      # Polygon File Format
243
    ".vtk",      # VTK Legacy
244
    ".vtp",      # VTK PolyData
245
    ".vtu",      # VTK Unstructured Grid
246
    ".vts",      # VTK Structured Grid
247
    ".vti",      # VTK Image Data
248
    ".xml",      # VTK XML formats
249
    ".3ds",      # 3D Studio
250
    ".x3d",      # X3D
251
    ".dae",      # COLLADA
252
    ".off",      # Object File Format
253
    ".facet"     # Facet format
254
]
255

256
VOLUME_FORMATS = [
257
    ".nrrd",     # Nearly Raw Raster Data
258
    ".nii",      # NIfTI
259
    ".mhd",      # MetaImage
260
    ".vti",      # VTK Image Data
261
    ".tif",      # TIFF stacks
262
    ".dcm"       # DICOM
263
]
264

265
IMAGE_FORMATS = [
266
    ".png",      # Portable Network Graphics
267
    ".jpg",      # JPEG
268
    ".jpeg",     # JPEG
269
    ".bmp",      # Bitmap
270
    ".tif",      # TIFF
271
    ".tiff"      # TIFF
272
]
273

274
# Supported output formats (save/write):
275
OUTPUT_FORMATS = [
276
    ".stl",      # Stereolithography (binary/ASCII)
277
    ".obj",      # Wavefront OBJ
278
    ".ply",      # Polygon File Format (binary/ASCII)
279
    ".vtk",      # VTK Legacy (binary/ASCII)  
280
    ".vtp",      # VTK PolyData XML
281
    ".vtu",      # VTK Unstructured Grid XML
282
    ".x3d",      # X3D
283
    ".dae",      # COLLADA
284
    ".off",      # Object File Format
285
    ".png",      # Images (screenshots)
286
    ".jpg",      # Images (screenshots)
287
    ".pdf",      # Vector graphics (2D plots)
288
    ".svg",      # Vector graphics (2D plots)
289
    ".eps"       # Vector graphics (2D plots)
290
]
291
```
292

293
## Usage Examples
294

295
```python
296
import vedo
297
import numpy as np
298

299
# Load various 3D file formats
300
mesh = vedo.load("model.stl")
301
points = vedo.load("pointcloud.ply")
302
volume = vedo.load("ct_scan.nrrd")
303

304
# Load multiple files at once
305
objects = vedo.load(["file1.obj", "file2.stl", "file3.ply"])
306

307
# Download data from URL
308
vedo.download("https://example.com/data.vtk", "local_data.vtk")
309
downloaded_mesh = vedo.load("local_data.vtk")
310

311
# Save objects in different formats
312
vedo.save(mesh, "output.obj")          # Wavefront OBJ
313
vedo.save(mesh, "output.ply")          # PLY format
314
vedo.save(points, "points.vtk")        # VTK legacy
315
vedo.save(volume, "volume.vti")        # VTK image data
316

317
# Create and save complex scenes
318
sphere = vedo.Sphere(c='red')
319
box = vedo.Box(c='blue')
320
combined = vedo.merge(sphere, box)
321
vedo.save(combined, "scene.stl", binary=True)
322

323
# Screenshot and video creation
324
vedo.show(mesh, title="3D Model")
325
vedo.screenshot("model_view.png", scale=2)  # High-res screenshot
326

327
# Create animation video
328
video = vedo.Video("rotation.mp4", fps=30)
329
for i in range(360):
330
    mesh.rotate_z(1)  # Rotate 1 degree
331
    vedo.show(mesh, interactive=False)
332
    video.add_frame()
333
video.close()
334

335
# Advanced I/O with format specification
336
# Load structured data
337
grid = vedo.loadStructuredGrid("simulation.vts")
338
structured_vol = vedo.loadStructuredPoints("field.vti")
339

340
# Export rendering window state
341
vedo.show(mesh, box, sphere)
342
vedo.export_window("scene_state.vtk")
343

344
# Later restore the complete scene
345
restored_plotter = vedo.import_window("scene_state.vtk")
346

347
# Handle compressed files
348
vedo.gunzip("compressed_model.stl.gz")
349
uncompressed_mesh = vedo.load("compressed_model.stl")
350

351
# Batch processing example
352
import glob
353
stl_files = glob.glob("*.stl")
354
meshes = []
355
for filename in stl_files:
356
    mesh = vedo.load(filename)
357
    mesh.color('random')  # Random colors
358
    meshes.append(mesh)
359
    
360
# Save combined result
361
combined_mesh = vedo.merge(*meshes)
362
vedo.save(combined_mesh, "combined_models.ply")
363
```