0
# Data Processing and Filtering
1
2
PyVista provides comprehensive mesh processing and filtering capabilities through mixin classes that extend dataset functionality with geometric operations, topological modifications, and data transformations.
3
4
## Capabilities
5
6
### Geometric Operations
7
8
#### Clipping
9
10
Removes portions of meshes using planes or implicit functions.
11
12
```python { .api }
13
def clip(self, normal='x', origin=None, invert=False, value=0.0, inplace=False) -> 'DataSet':
14
"""
15
Clip dataset with a plane or scalar value.
16
17
Parameters:
18
normal (str or tuple): Clipping plane normal ('x', 'y', 'z') or vector
19
origin (tuple): Point on clipping plane
20
invert (bool): Invert clipping direction
21
value (float): Scalar value for clipping
22
inplace (bool): Modify dataset in place
23
24
Returns:
25
DataSet: Clipped dataset
26
"""
27
28
def clip_box(self, bounds, invert=False, factor=0.35, inplace=False) -> 'DataSet':
29
"""
30
Clip dataset with a box.
31
32
Parameters:
33
bounds (tuple): Bounding box (xmin, xmax, ymin, ymax, zmin, zmax)
34
invert (bool): Keep region outside box
35
factor (float): Implicit function factor
36
inplace (bool): Modify dataset in place
37
38
Returns:
39
DataSet: Clipped dataset
40
"""
41
42
def clip_scalar(self, scalars=None, invert=False, value=0.0, both=False,
43
inplace=False) -> 'DataSet':
44
"""
45
Clip dataset by scalar values.
46
47
Parameters:
48
scalars (str): Name of scalar array to use
49
invert (bool): Invert clipping direction
50
value (float): Clipping threshold value
51
both (bool): Return both clipped parts
52
inplace (bool): Modify dataset in place
53
54
Returns:
55
DataSet: Clipped dataset
56
"""
57
```
58
59
#### Slicing
60
61
Creates cross-sections through datasets.
62
63
```python { .api }
64
def slice(self, normal='x', origin=None, generate_triangles=False,
65
contour=False, inplace=False) -> PolyData:
66
"""
67
Slice dataset with a plane.
68
69
Parameters:
70
normal (str or tuple): Plane normal direction
71
origin (tuple): Point on plane
72
generate_triangles (bool): Triangulate slice
73
contour (bool): Generate contour lines
74
inplace (bool): Modify dataset in place
75
76
Returns:
77
PolyData: Sliced surface
78
"""
79
80
def slice_orthogonal(self, x=None, y=None, z=None, generate_triangles=False,
81
contour=False) -> MultiBlock:
82
"""
83
Create orthogonal slices through dataset.
84
85
Parameters:
86
x (float): X-coordinate for YZ slice
87
y (float): Y-coordinate for XZ slice
88
z (float): Z-coordinate for XY slice
89
generate_triangles (bool): Triangulate slices
90
contour (bool): Generate contour lines
91
92
Returns:
93
MultiBlock: Collection of slices
94
"""
95
96
def slice_along_axis(self, n=5, axis='x', tolerance=None,
97
generate_triangles=False) -> MultiBlock:
98
"""
99
Create multiple parallel slices along an axis.
100
101
Parameters:
102
n (int): Number of slices
103
axis (str): Axis direction ('x', 'y', 'z')
104
tolerance (float): Slicing tolerance
105
generate_triangles (bool): Triangulate slices
106
107
Returns:
108
MultiBlock: Collection of slices
109
"""
110
```
111
112
#### Thresholding
113
114
Extracts regions based on scalar values.
115
116
```python { .api }
117
def threshold(self, value=None, scalars=None, invert=False, continuous=False,
118
preference='cell', all_scalars=False, component_mode='selected',
119
component=0, method='upper', inplace=False) -> UnstructuredGrid:
120
"""
121
Extract cells/points with scalar values above/below threshold.
122
123
Parameters:
124
value (float or tuple): Threshold value(s)
125
scalars (str): Name of scalar array
126
invert (bool): Invert threshold logic
127
continuous (bool): Use continuous thresholding
128
preference (str): Data association ('cell' or 'point')
129
all_scalars (bool): Threshold all scalar arrays
130
component_mode (str): Component selection mode
131
component (int): Component number for vector data
132
method (str): Threshold method ('upper', 'lower', 'between')
133
inplace (bool): Modify dataset in place
134
135
Returns:
136
UnstructuredGrid: Thresholded dataset
137
"""
138
139
def threshold_percent(self, percent=0.5, scalars=None, invert=False,
140
continuous=False, preference='cell',
141
inplace=False) -> UnstructuredGrid:
142
"""
143
Threshold by percentage of scalar range.
144
145
Parameters:
146
percent (float): Percentage of range (0.0 to 1.0)
147
scalars (str): Name of scalar array
148
invert (bool): Invert threshold logic
149
continuous (bool): Use continuous thresholding
150
preference (str): Data association
151
inplace (bool): Modify dataset in place
152
153
Returns:
154
UnstructuredGrid: Thresholded dataset
155
"""
156
```
157
158
#### Contouring
159
160
Generates isosurfaces and contour lines.
161
162
```python { .api }
163
def contour(self, isosurfaces=10, scalars=None, compute_normals=False,
164
compute_gradients=False, compute_scalars=True, rng=None,
165
preference='point', method='contour', locator=None,
166
progress_bar=False) -> PolyData:
167
"""
168
Generate isosurfaces/contours from scalar data.
169
170
Parameters:
171
isosurfaces (int or list): Number or list of isovalues
172
scalars (str): Name of scalar array
173
compute_normals (bool): Compute surface normals
174
compute_gradients (bool): Compute gradients
175
compute_scalars (bool): Compute scalars on output
176
rng (tuple): Value range for isosurfaces
177
preference (str): Data association
178
method (str): Contouring method
179
locator (object): Point locator for acceleration
180
progress_bar (bool): Show progress bar
181
182
Returns:
183
PolyData: Contoured surface
184
"""
185
186
def contour_banded(self, n_contours=10, scalars=None, compute_normals=False,
187
rng=None, preference='point') -> PolyData:
188
"""
189
Generate banded contours with filled regions.
190
191
Parameters:
192
n_contours (int): Number of contour bands
193
scalars (str): Name of scalar array
194
compute_normals (bool): Compute surface normals
195
rng (tuple): Value range
196
preference (str): Data association
197
198
Returns:
199
PolyData: Banded contour surface
200
"""
201
```
202
203
### Surface Processing
204
205
#### Smoothing
206
207
Reduces mesh roughness through various smoothing algorithms.
208
209
```python { .api }
210
def smooth(self, n_iter=20, relaxation_factor=0.01, feature_angle=45.0,
211
edge_angle=15.0, boundary_smoothing=True, feature_smoothing=False,
212
normalize_coordinates=False, inplace=False) -> PolyData:
213
"""
214
Smooth mesh using Laplacian smoothing.
215
216
Parameters:
217
n_iter (int): Number of smoothing iterations
218
relaxation_factor (float): Relaxation factor (0.0 to 1.0)
219
feature_angle (float): Feature edge angle threshold
220
edge_angle (float): Edge angle threshold
221
boundary_smoothing (bool): Smooth boundary edges
222
feature_smoothing (bool): Smooth feature edges
223
normalize_coordinates (bool): Normalize coordinates
224
inplace (bool): Modify mesh in place
225
226
Returns:
227
PolyData: Smoothed mesh
228
"""
229
230
def smooth_taubin(self, n_iter=20, pass_band=0.1, normalize_coordinates=False,
231
inplace=False) -> PolyData:
232
"""
233
Smooth mesh using Taubin algorithm.
234
235
Parameters:
236
n_iter (int): Number of iterations
237
pass_band (float): Pass band value
238
normalize_coordinates (bool): Normalize coordinates
239
inplace (bool): Modify mesh in place
240
241
Returns:
242
PolyData: Smoothed mesh
243
"""
244
```
245
246
#### Decimation
247
248
Reduces mesh complexity by removing vertices and faces.
249
250
```python { .api }
251
def decimate(self, target_reduction=0.5, volume_preservation=False,
252
attribute_error=False, split_boundary=False, preserve_topology=True,
253
inplace=False, progress_bar=False) -> PolyData:
254
"""
255
Reduce mesh complexity through decimation.
256
257
Parameters:
258
target_reduction (float): Fraction of triangles to remove (0.0 to 1.0)
259
volume_preservation (bool): Preserve volume during decimation
260
attribute_error (bool): Use attribute error metric
261
split_boundary (bool): Allow boundary edge splitting
262
preserve_topology (bool): Maintain mesh topology
263
inplace (bool): Modify mesh in place
264
progress_bar (bool): Show progress bar
265
266
Returns:
267
PolyData: Decimated mesh
268
"""
269
270
def decimate_pro(self, target_reduction=0.9, feature_angle=45.0,
271
split_angle=75.0, splitting=True, preserve_topology=False,
272
inplace=False, progress_bar=False) -> PolyData:
273
"""
274
Advanced decimation with more control options.
275
276
Parameters:
277
target_reduction (float): Fraction of triangles to remove
278
feature_angle (float): Feature angle for edge classification
279
split_angle (float): Edge splitting angle
280
splitting (bool): Enable edge splitting
281
preserve_topology (bool): Maintain topology
282
inplace (bool): Modify mesh in place
283
progress_bar (bool): Show progress bar
284
285
Returns:
286
PolyData: Decimated mesh
287
"""
288
```
289
290
#### Subdivision
291
292
Increases mesh resolution through subdivision schemes.
293
294
```python { .api }
295
def subdivide(self, nsub=1, subfilter='linear', inplace=False) -> PolyData:
296
"""
297
Subdivide mesh to increase resolution.
298
299
Parameters:
300
nsub (int): Number of subdivision levels
301
subfilter (str): Subdivision algorithm ('linear', 'butterfly', 'loop')
302
inplace (bool): Modify mesh in place
303
304
Returns:
305
PolyData: Subdivided mesh
306
"""
307
308
def subdivide_adaptive(self, max_tri_area=1.0, max_n_tris=None,
309
max_n_passes=1, inplace=False) -> PolyData:
310
"""
311
Adaptive subdivision based on triangle area.
312
313
Parameters:
314
max_tri_area (float): Maximum triangle area
315
max_n_tris (int): Maximum number of triangles
316
max_n_passes (int): Maximum subdivision passes
317
inplace (bool): Modify mesh in place
318
319
Returns:
320
PolyData: Adaptively subdivided mesh
321
"""
322
```
323
324
### Geometric Transformations
325
326
#### Scaling and Translation
327
328
Basic geometric transformations.
329
330
```python { .api }
331
def scale(self, xyz, transform_all_input_vectors=False, inplace=False) -> 'DataSet':
332
"""
333
Scale dataset coordinates.
334
335
Parameters:
336
xyz (float or tuple): Scale factor(s) for x, y, z axes
337
transform_all_input_vectors (bool): Scale vector data
338
inplace (bool): Modify dataset in place
339
340
Returns:
341
DataSet: Scaled dataset
342
"""
343
344
def translate(self, xyz, transform_all_input_vectors=False,
345
inplace=False) -> 'DataSet':
346
"""
347
Translate dataset coordinates.
348
349
Parameters:
350
xyz (tuple): Translation vector (dx, dy, dz)
351
transform_all_input_vectors (bool): Translate vector data
352
inplace (bool): Modify dataset in place
353
354
Returns:
355
DataSet: Translated dataset
356
"""
357
358
def rotate_x(self, angle, point=(0.0, 0.0, 0.0), transform_all_input_vectors=False,
359
inplace=False) -> 'DataSet':
360
"""Rotate around X-axis by specified angle in degrees."""
361
362
def rotate_y(self, angle, point=(0.0, 0.0, 0.0), transform_all_input_vectors=False,
363
inplace=False) -> 'DataSet':
364
"""Rotate around Y-axis by specified angle in degrees."""
365
366
def rotate_z(self, angle, point=(0.0, 0.0, 0.0), transform_all_input_vectors=False,
367
inplace=False) -> 'DataSet':
368
"""Rotate around Z-axis by specified angle in degrees."""
369
```
370
371
#### Matrix Transformations
372
373
Apply arbitrary transformation matrices.
374
375
```python { .api }
376
def transform(self, trans, transform_all_input_vectors=False,
377
inplace=False) -> 'DataSet':
378
"""
379
Apply 4x4 transformation matrix.
380
381
Parameters:
382
trans (array-like): 4x4 transformation matrix
383
transform_all_input_vectors (bool): Transform vector data
384
inplace (bool): Modify dataset in place
385
386
Returns:
387
DataSet: Transformed dataset
388
"""
389
390
def reflect(self, normal, point=None, transform_all_input_vectors=False,
391
inplace=False) -> 'DataSet':
392
"""
393
Reflect dataset across a plane.
394
395
Parameters:
396
normal (tuple): Plane normal vector
397
point (tuple): Point on reflection plane
398
transform_all_input_vectors (bool): Reflect vector data
399
inplace (bool): Modify dataset in place
400
401
Returns:
402
DataSet: Reflected dataset
403
"""
404
```
405
406
### Boolean Operations
407
408
Combine meshes using boolean set operations.
409
410
```python { .api }
411
def boolean_union(self, mesh, tolerance=1e-5, inplace=False) -> PolyData:
412
"""
413
Compute boolean union with another mesh.
414
415
Parameters:
416
mesh (PolyData): Second mesh for operation
417
tolerance (float): Numerical tolerance
418
inplace (bool): Modify mesh in place
419
420
Returns:
421
PolyData: Union result
422
"""
423
424
def boolean_difference(self, mesh, tolerance=1e-5, inplace=False) -> PolyData:
425
"""
426
Compute boolean difference with another mesh.
427
428
Parameters:
429
mesh (PolyData): Mesh to subtract
430
tolerance (float): Numerical tolerance
431
inplace (bool): Modify mesh in place
432
433
Returns:
434
PolyData: Difference result
435
"""
436
437
def boolean_intersection(self, mesh, tolerance=1e-5, inplace=False) -> PolyData:
438
"""
439
Compute boolean intersection with another mesh.
440
441
Parameters:
442
mesh (PolyData): Second mesh for operation
443
tolerance (float): Numerical tolerance
444
inplace (bool): Modify mesh in place
445
446
Returns:
447
PolyData: Intersection result
448
"""
449
```
450
451
### Mesh Quality and Repair
452
453
#### Cleaning and Repair
454
455
Fix common mesh problems.
456
457
```python { .api }
458
def clean(self, point_merging=True, tolerance=None, lines_to_points=True,
459
polys_to_lines=True, strips_to_polys=True, inplace=False,
460
absolute=True) -> 'DataSet':
461
"""
462
Clean mesh by merging duplicate points and removing degenerate cells.
463
464
Parameters:
465
point_merging (bool): Merge duplicate points
466
tolerance (float): Point merging tolerance
467
lines_to_points (bool): Convert degenerate lines to points
468
polys_to_lines (bool): Convert degenerate polygons to lines
469
strips_to_polys (bool): Convert triangle strips to polygons
470
inplace (bool): Modify mesh in place
471
absolute (bool): Use absolute tolerance
472
473
Returns:
474
DataSet: Cleaned mesh
475
"""
476
477
def fill_holes(self, hole_size, inplace=False, progress_bar=False) -> PolyData:
478
"""
479
Fill holes in mesh surface.
480
481
Parameters:
482
hole_size (float): Maximum hole size to fill
483
inplace (bool): Modify mesh in place
484
progress_bar (bool): Show progress bar
485
486
Returns:
487
PolyData: Mesh with filled holes
488
"""
489
490
def remove_duplicate_cells(self, inplace=False) -> 'DataSet':
491
"""
492
Remove duplicate cells from mesh.
493
494
Parameters:
495
inplace (bool): Modify mesh in place
496
497
Returns:
498
DataSet: Mesh without duplicate cells
499
"""
500
```
501
502
#### Quality Metrics
503
504
Compute mesh quality measures.
505
506
```python { .api }
507
def compute_cell_quality(self, quality_measure='scaled_jacobian',
508
progress_bar=False) -> 'DataSet':
509
"""
510
Compute cell quality metrics.
511
512
Parameters:
513
quality_measure (str): Quality metric to compute
514
progress_bar (bool): Show progress bar
515
516
Returns:
517
DataSet: Mesh with quality data
518
"""
519
```
520
521
### Coordinate Transformations
522
523
Transform between coordinate systems.
524
525
```python { .api }
526
def cartesian_to_spherical(x, y, z):
527
"""
528
Convert Cartesian coordinates to spherical coordinates.
529
530
Parameters:
531
x (array-like): X coordinates
532
y (array-like): Y coordinates
533
z (array-like): Z coordinates
534
535
Returns:
536
tuple: (radius, theta, phi) spherical coordinates
537
"""
538
539
def spherical_to_cartesian(r, theta, phi):
540
"""
541
Convert spherical coordinates to Cartesian coordinates.
542
543
Parameters:
544
r (array-like): Radial distance
545
theta (array-like): Azimuthal angle
546
phi (array-like): Polar angle
547
548
Returns:
549
tuple: (x, y, z) Cartesian coordinates
550
"""
551
552
def transform_vectors_sph_to_cart(theta, phi, r, u, v, w):
553
"""
554
Transform vectors from spherical to Cartesian coordinates.
555
556
Parameters:
557
theta (array-like): Azimuthal angles
558
phi (array-like): Polar angles
559
r (array-like): Radial distances
560
u (array-like): Radial components
561
v (array-like): Theta components
562
w (array-like): Phi components
563
564
Returns:
565
tuple: (x, y, z) vector components in Cartesian coordinates
566
"""
567
```
568
569
### Grid and Mesh Operations
570
571
Utilities for creating and manipulating grids.
572
573
```python { .api }
574
def create_grid(dataset, dimensions):
575
"""
576
Create structured grid from dataset.
577
578
Parameters:
579
dataset (DataSet): Input dataset
580
dimensions (tuple): Grid dimensions
581
582
Returns:
583
StructuredGrid: Structured grid
584
"""
585
586
def grid_from_sph_coords(theta, phi, r):
587
"""
588
Create grid from spherical coordinates.
589
590
Parameters:
591
theta (array-like): Azimuthal coordinates
592
phi (array-like): Polar coordinates
593
r (array-like): Radial coordinates
594
595
Returns:
596
StructuredGrid: Grid in spherical coordinates
597
"""
598
599
def merge(datasets, merge_points=True, tolerance=None, main_has_priority=True):
600
"""
601
Merge multiple datasets into single dataset.
602
603
Parameters:
604
datasets (list): List of datasets to merge
605
merge_points (bool): Merge coincident points
606
tolerance (float): Point merging tolerance
607
main_has_priority (bool): Main dataset has priority
608
609
Returns:
610
UnstructuredGrid: Merged dataset
611
"""
612
613
def sample_function(function, bounds=(-1, 1, -1, 1, -1, 1), dims=(50, 50, 50),
614
compute_gradients=False, scalars_name='scalars',
615
generate_vertex_normals=True):
616
"""
617
Sample a function over a regular grid.
618
619
Parameters:
620
function (callable): Function to sample f(x, y, z)
621
bounds (tuple): Sampling bounds (xmin, xmax, ymin, ymax, zmin, zmax)
622
dims (tuple): Grid dimensions (nx, ny, nz)
623
compute_gradients (bool): Compute gradient vectors
624
scalars_name (str): Name for scalar array
625
generate_vertex_normals (bool): Generate vertex normals
626
627
Returns:
628
ImageData: Sampled function data
629
"""
630
631
def voxelize_volume(mesh, density, check_surface=True, progress_bar=False):
632
"""
633
Voxelize the volume of a surface mesh.
634
635
Parameters:
636
mesh (PolyData): Surface mesh to voxelize
637
density (float): Voxel density
638
check_surface (bool): Check surface closure
639
progress_bar (bool): Show progress bar
640
641
Returns:
642
ImageData: Voxelized volume
643
"""
644
```
645
646
### Special Functions
647
648
Specialized data generation functions.
649
650
```python { .api }
651
def perlin_noise(amplitude=1.0, freq=(1, 1, 1), phase=(0, 0, 0)):
652
"""
653
Generate Perlin noise function.
654
655
Parameters:
656
amplitude (float): Noise amplitude
657
freq (tuple): Frequency in each direction
658
phase (tuple): Phase offset in each direction
659
660
Returns:
661
callable: Perlin noise function f(x, y, z)
662
"""
663
```
664
665
### Extrusion and Sweeping
666
667
Create 3D objects from 2D profiles.
668
669
```python { .api }
670
def extrude(self, vector, capping=True, inplace=False,
671
progress_bar=False) -> PolyData:
672
"""
673
Extrude mesh along vector direction.
674
675
Parameters:
676
vector (tuple): Extrusion direction and distance
677
capping (bool): Cap extruded ends
678
inplace (bool): Modify mesh in place
679
progress_bar (bool): Show progress bar
680
681
Returns:
682
PolyData: Extruded mesh
683
"""
684
685
def extrude_rotate(self, resolution=30, translation=0.0, dradius=0.0,
686
angle=360.0, capping=True, inplace=False) -> PolyData:
687
"""
688
Extrude by rotation around axis.
689
690
Parameters:
691
resolution (int): Number of rotation steps
692
translation (float): Translation along axis
693
dradius (float): Change in radius
694
angle (float): Rotation angle in degrees
695
capping (bool): Cap ends
696
inplace (bool): Modify mesh in place
697
698
Returns:
699
PolyData: Rotationally extruded mesh
700
"""
701
```
702
703
## Usage Examples
704
705
### Basic clipping and slicing
706
707
```python
708
import pyvista as pv
709
710
# Load example mesh
711
mesh = pv.examples.load_airplane()
712
713
# Clip with plane
714
clipped = mesh.clip(normal='x', origin=(0, 0, 0))
715
716
# Create multiple slices
717
slices = mesh.slice_orthogonal(x=0, y=0, z=0)
718
719
# Plot results
720
plotter = pv.Plotter(shape=(1, 2))
721
plotter.subplot(0, 0)
722
plotter.add_mesh(clipped, show_edges=True)
723
plotter.add_title("Clipped Mesh")
724
plotter.subplot(0, 1)
725
plotter.add_mesh(slices, show_edges=True)
726
plotter.add_title("Orthogonal Slices")
727
plotter.show()
728
```
729
730
### Surface processing workflow
731
732
```python
733
import pyvista as pv
734
735
# Load noisy mesh
736
mesh = pv.examples.download_bunny()
737
738
# Processing pipeline
739
smoothed = mesh.smooth(n_iter=50, relaxation_factor=0.1)
740
decimated = smoothed.decimate(target_reduction=0.7)
741
subdivided = decimated.subdivide(nsub=1)
742
743
# Compare results
744
plotter = pv.Plotter(shape=(2, 2))
745
plotter.subplot(0, 0)
746
plotter.add_mesh(mesh, show_edges=True)
747
plotter.add_title("Original")
748
plotter.subplot(0, 1)
749
plotter.add_mesh(smoothed, show_edges=True)
750
plotter.add_title("Smoothed")
751
plotter.subplot(1, 0)
752
plotter.add_mesh(decimated, show_edges=True)
753
plotter.add_title("Decimated")
754
plotter.subplot(1, 1)
755
plotter.add_mesh(subdivided, show_edges=True)
756
plotter.add_title("Subdivided")
757
plotter.show()
758
```