Debian Codegraph @

pyvista/core/utilities/parametric_objects.py

raw
1 """Module managing parametric objects."""
2
3 from __future__ import annotations
4
5 from collections.abc import Sequence
6 from math import pi
7 from typing import TYPE_CHECKING
8 from typing import Literal
9 from typing import get_args
10
11 import numpy as np
12
13 import pyvista as pv
14 from pyvista import _vtk
15 from pyvista._deprecate_positional_args import _deprecate_positional_args
16 from pyvista.core import _validation
17
18 from .geometric_sources import translate
19 from .helpers import wrap
20
21 if TYPE_CHECKING:
22 from pyvista import PolyData
23 from pyvista.core._typing_core import MatrixLike
24 from pyvista.core._typing_core import VectorLike
25
26 _ParametrizeByOptions = Literal['length', 'index']
27 _BoundaryConstraintOptions = Literal['finite_difference', 'clamped', 'second', 'scaled_second']
28
29
30 def Spline(
31 points: VectorLike[float] | MatrixLike[float],
32 n_points: int | None = None,
33 *,
34 closed: bool = False,
35 parametrize_by: _ParametrizeByOptions = 'length',
36 boundary_constraints: _BoundaryConstraintOptions
37 | tuple[_BoundaryConstraintOptions, _BoundaryConstraintOptions] = 'clamped',
38 boundary_values: float | tuple[float | None, float | None] | None = None,
39 **kwargs,
40 ) -> PolyData:
41 """Create a spline from points.
42
43 Parameters
44 ----------
45 points : numpy.ndarray
46 Array of points to build a spline out of. Array must be 3D and
47 directionally ordered.
48
49 n_points : int, optional
50 Number of points to interpolate along the points array. Defaults to
51 ``points.shape[0]``.
52
53 closed : bool, default: False
54 Close the spline if ``True`` (both ends are joined). Not closed by default.
55
56 parametrize_by : str, default: 'length'
57 Parametrize spline by ``'length'`` or by point ``'index'``.
58
59 boundary_constraints : str | Sequence[str], optional, default: 'clamped'
60 Derivative constraint type at both boundaries of the spline.
61 Can be set by a single string or a sequence of length 2 (one for each left/right end).
62 Each value must be one of:
63
64 - ``'finite_difference'``: The first derivative at the left(right) most point is determined
65 from the line defined from the first(last) two points.
66 - ``'clamped'``: Default: the first derivative at the left(right) most point is set to
67 Left(Right) ``boundary_values``. (Default)
68 - ``'second'``: The second derivative at the left(right) most point is set to
69 Left(Right) ``boundary_values``.
70 - ``'scaled_second'``: The second derivative at left(right) most points is
71 Left(Right) ``boundary_values`` times second derivative at first interior point.
72
73 boundary_values : float | Sequence[float | None], optional
74 Values of derivative at both ends of the spline used by the ``boundary_constraints`` type.
75 Can be set a single float, or a sequence of floats or None (one value for each left/right
76 end). If a single value is provided, the same value is used for both ends.
77 Value must be None for each end with boundary constraint type ``'finite_difference'``.
78
79 **kwargs : dict, optional
80 See :func:`surface_from_para` for additional keyword arguments.
81
82 Returns
83 -------
84 pyvista.PolyData
85 Line mesh of spline.
86
87 See Also
88 --------
89 :ref:`create_spline_example`
90 :ref:`distance_along_spline_example`
91
92 Examples
93 --------
94 Construct a spline.
95
96 >>> import numpy as np
97 >>> import pyvista as pv
98 >>> theta = np.linspace(-4 * np.pi, 4 * np.pi, 100)
99 >>> z = np.linspace(-2, 2, 100)
100 >>> r = z**2 + 1
101 >>> x = r * np.sin(theta)
102 >>> y = r * np.cos(theta)
103 >>> points = np.column_stack((x, y, z))
104 >>> spline = pv.Spline(points, 1000)
105 >>> spline.plot(
106 ... render_lines_as_tubes=True,
107 ... line_width=10,
108 ... show_scalar_bar=False,
109 ... )
110
111 """
112
113 # Validate inputs
114 def check_constraint(value: str, name: str) -> None:
115 _validation.check_contains(
116 get_args(_BoundaryConstraintOptions), must_contain=value, name=name
117 )
118
119 points_ = _validation.validate_arrayNx3(points, name='points')
120 _validation.check_contains(
121 get_args(_ParametrizeByOptions), must_contain=parametrize_by, name='parametrize_by'
122 )
123
124 # Ensure we have valid constraint, value pairs
125 name = 'boundary_constraints'
126 _validation.check_instance(boundary_constraints, Sequence, name=name)
127 if isinstance(boundary_constraints, str):
128 check_constraint(boundary_constraints, name=name)
129 constraints_pair = (boundary_constraints, boundary_constraints)
130 else:
131 _validation.check_length(boundary_constraints, exact_length=2, name=name)
132 check_constraint(boundary_constraints[0], name=name)
133 check_constraint(boundary_constraints[1], name=name)
134 constraints_pair = boundary_constraints
135
136 if boundary_values is None:
137 values_list: list[float | None]
138 values_list = [None if c == 'finite_difference' else 0.0 for c in constraints_pair]
139 values_pair: Sequence[float | None] = values_list
140 else:
141 name = 'boundary_values'
142 allowed_types = float, int, type(None)
143 _validation.check_instance(boundary_values, (Sequence, *allowed_types), name=name)
144 if isinstance(boundary_values, Sequence):
145 _validation.check_length(boundary_values, exact_length=2, name=name)
146 for val in boundary_values:
147 _validation.check_instance(val, allowed_types, name=name)
148 values_pair = boundary_values
149 else:
150 values_pair = (boundary_values, boundary_values)
151
152 spline_function = _vtk.vtkParametricSpline()
153 spline_function.SetPoints(pv.vtk_points(points_, deep=False))
154
155 if closed:
156 spline_function.ClosedOn()
157 else:
158 spline_function.ClosedOff()
159
160 if parametrize_by == 'length':
161 spline_function.ParameterizeByLengthOn()
162 else:
163 spline_function.ParameterizeByLengthOff()
164
165 _boundary_types_dict = {
166 'finite_difference': 0,
167 'clamped': 1,
168 'second': 2,
169 'scaled_second': 3,
170 }
171 for left_right, constraint, value in zip(
172 ('Left', 'Right'), constraints_pair, values_pair, strict=True
173 ):
174 method = f'Set{left_right}Constraint'
175 getattr(spline_function, method)(_boundary_types_dict[constraint])
176
177 if value is not None:
178 if constraint == 'finite_difference':
179 msg = f'finite difference boundary value must be None, got {value}'
180 raise ValueError(msg)
181 method = f'Set{left_right}Value'
182 getattr(spline_function, method)(value)
183
184 # get interpolation density
185 u_res = n_points
186 if u_res is None:
187 u_res = points_.shape[0]
188 u_res -= 1
189 spline = surface_from_para(spline_function, u_res=u_res, **kwargs)
190 return spline.compute_arc_length()
191
192
193 @_deprecate_positional_args(allowed=['points'])
194 def KochanekSpline( # noqa: PLR0917
195 points: VectorLike[float] | MatrixLike[float],
196 tension: VectorLike[float] | None = None,
197 bias: VectorLike[float] | None = None,
198 continuity: VectorLike[float] | None = None,
199 n_points: int | None = None,
200 ) -> PolyData:
201 """Create a Kochanek spline from points.
202
203 Parameters
204 ----------
205 points : array_like[float]
206 Array of points to build a Kochanek spline out of. Array must
207 be 3D and directionally ordered.
208
209 tension : sequence[float], default: [0.0, 0.0, 0.0]
210 Changes the length of the tangent vector.
211
212 bias : sequence[float], default: [0.0, 0.0, 0.0]
213 Primarily changes the direction of the tangent vector.
214
215 continuity : sequence[float], default: [0.0, 0.0, 0.0]
216 Changes the sharpness in change between tangents.
217
218 n_points : int, optional
219 Number of points on the spline. Defaults to ``points.shape[0]``.
220
221 Returns
222 -------
223 pyvista.PolyData
224 Kochanek spline.
225
226 Examples
227 --------
228 Construct a Kochanek spline.
229
230 >>> import numpy as np
231 >>> import pyvista as pv
232 >>> theta = np.linspace(-4 * np.pi, 4 * np.pi, 100)
233 >>> z = np.linspace(-2, 2, 100)
234 >>> r = z**2 + 1
235 >>> x = r * np.sin(theta)
236 >>> y = r * np.cos(theta)
237 >>> points = np.column_stack((x, y, z))
238 >>> kochanek_spline = pv.KochanekSpline(points, n_points=6)
239 >>> kochanek_spline.plot(line_width=4, color='k')
240
241 See :ref:`create_kochanek_spline_example` for an additional example.
242
243 """
244 if tension is None:
245 tension = np.array([0.0, 0.0, 0.0])
246 tension_ = _validation.validate_arrayN(tension, must_be_in_range=[-1.0, 1.0], name='tension')
247
248 if bias is None:
249 bias = np.array([0.0, 0.0, 0.0])
250 bias_ = _validation.validate_arrayN(bias, must_be_in_range=[-1.0, 1.0], name='bias')
251
252 if continuity is None:
253 continuity = np.array([0.0, 0.0, 0.0])
254 continuity_ = _validation.validate_arrayN(
255 continuity, must_be_in_range=[-1.0, 1.0], name='continuity'
256 )
257
258 points_ = _validation.validate_arrayNx3(points, name='points')
259 spline_function = _vtk.vtkParametricSpline()
260 spline_function.SetPoints(pv.vtk_points(points_, deep=False))
261
262 # set Kochanek spline for each direction
263 xspline = _vtk.vtkKochanekSpline()
264 yspline = _vtk.vtkKochanekSpline()
265 zspline = _vtk.vtkKochanekSpline()
266 xspline.SetDefaultBias(bias_[0])
267 yspline.SetDefaultBias(bias_[1])
268 zspline.SetDefaultBias(bias_[2])
269 xspline.SetDefaultTension(tension_[0])
270 yspline.SetDefaultTension(tension_[1])
271 zspline.SetDefaultTension(tension_[2])
272 xspline.SetDefaultContinuity(continuity_[0])
273 yspline.SetDefaultContinuity(continuity_[1])
274 zspline.SetDefaultContinuity(continuity_[2])
275 spline_function.SetXSpline(xspline)
276 spline_function.SetYSpline(yspline)
277 spline_function.SetZSpline(zspline)
278
279 # get interpolation density
280 u_res = n_points
281 if u_res is None:
282 u_res = points_.shape[0]
283
284 u_res -= 1
285 spline = surface_from_para(spline_function, u_res=u_res)
286 return spline.compute_arc_length()
287
288
289 def ParametricBohemianDome(
290 a: float | None = None,
291 b: float | None = None,
292 c: float | None = None,
293 **kwargs,
294 ) -> PolyData:
295 """Generate a Bohemian dome surface.
296
297 Parameters
298 ----------
299 a : float, default: 0.5
300 Bohemian dome surface parameter a.
301
302 b : float, default: 1.5
303 Bohemian dome surface parameter b.
304
305 c : float, default: 1.0
306 Bohemian dome surface parameter c.
307
308 **kwargs : dict, optional
309 See :func:`surface_from_para` for additional keyword arguments.
310
311 Returns
312 -------
313 pyvista.PolyData
314 ParametricBohemianDome surface.
315
316 Examples
317 --------
318 Create a ParametricBohemianDome mesh.
319
320 >>> import pyvista as pv
321 >>> mesh = pv.ParametricBohemianDome()
322 >>> mesh.plot(color='w', smooth_shading=True)
323
324 """
325 parametric_function = _vtk.vtkParametricBohemianDome()
326 if a is not None:
327 parametric_function.SetA(a)
328 if b is not None:
329 parametric_function.SetB(b)
330 if c is not None:
331 parametric_function.SetC(c)
332
333 center = kwargs.pop('center', [0.0, 0.0, 0.0])
334 direction = kwargs.pop('direction', [1.0, 0.0, 0.0])
335 kwargs.setdefault('clean', True)
336 surf = surface_from_para(parametric_function, **kwargs)
337 translate(surf, center, direction)
338 return surf
339
340
341 def ParametricBour(**kwargs) -> PolyData:
342 """Generate Bour's minimal surface.
343
344 Parameters
345 ----------
346 **kwargs : dict, optional
347 See :func:`surface_from_para` for additional keyword arguments.
348
349 Returns
350 -------
351 pyvista.PolyData
352 ParametricBour surface.
353
354 Examples
355 --------
356 Create a ParametricBour mesh.
357
358 >>> import pyvista as pv
359 >>> mesh = pv.ParametricBour()
360 >>> mesh.plot(color='w', smooth_shading=True)
361
362 """
363 parametric_function = _vtk.vtkParametricBour()
364
365 center = kwargs.pop('center', [0.0, 0.0, 0.0])
366 direction = kwargs.pop('direction', [1.0, 0.0, 0.0])
367 surf = surface_from_para(parametric_function, **kwargs)
368
369 translate(surf, center, direction)
370
371 return surf
372
373
374 def ParametricBoy(zscale: float | None = None, **kwargs) -> PolyData:
375 """Generate Boy's surface.
376
377 This is a model of the projective plane without singularities. It
378 was found by Werner Boy on assignment from David Hilbert.
379
380 For further information about this surface, please consult the
381 technical description "Parametric surfaces" in the
382 "VTK Technical Documents" section in the VTK.org web pages.
383
384 Parameters
385 ----------
386 zscale : float, optional
387 The scale factor for the z-coordinate.
388
389 **kwargs : dict, optional
390 See :func:`surface_from_para` for additional keyword arguments.
391
392 Returns
393 -------
394 pyvista.PolyData
395 ParametricBoy surface.
396
397 Examples
398 --------
399 Create a ParametricBoy mesh.
400
401 >>> import pyvista as pv
402 >>> mesh = pv.ParametricBoy()
403 >>> mesh.plot(color='w', smooth_shading=True)
404
405 """
406 parametric_function = _vtk.vtkParametricBoy()
407 if zscale is not None:
408 parametric_function.SetZScale(zscale)
409
410 center = kwargs.pop('center', [0.0, 0.0, 0.0])
411 direction = kwargs.pop('direction', [1.0, 0.0, 0.0])
412 kwargs.setdefault('clean', True)
413 surf = surface_from_para(parametric_function, **kwargs)
414 translate(surf, center, direction)
415 return surf
416
417
418 def ParametricCatalanMinimal(**kwargs) -> PolyData:
419 """Generate Catalan's minimal surface.
420
421 ParametricCatalanMinimal generates Catalan's minimal surface
422 parametrically. This minimal surface contains the cycloid as a
423 geodesic.
424
425 Parameters
426 ----------
427 **kwargs : dict, optional
428 See :func:`surface_from_para` for additional keyword arguments.
429
430 Returns
431 -------
432 pyvista.PolyData
433 ParametricCatalanMinimal surface.
434
435 Examples
436 --------
437 Create a ParametricCatalanMinimal mesh.
438
439 >>> import pyvista as pv
440 >>> mesh = pv.ParametricCatalanMinimal()
441 >>> mesh.plot(color='w', smooth_shading=True)
442
443 """
444 parametric_function = _vtk.vtkParametricCatalanMinimal()
445
446 center = kwargs.pop('center', [0.0, 0.0, 0.0])
447 direction = kwargs.pop('direction', [1.0, 0.0, 0.0])
448 surf = surface_from_para(parametric_function, **kwargs)
449
450 translate(surf, center, direction)
451
452 return surf
453
454
455 def ParametricConicSpiral( # noqa: PLR0917
456 a: float | None = None,
457 b: float | None = None,
458 c: float | None = None,
459 n: float | None = None,
460 **kwargs,
461 ) -> PolyData:
462 """Generate conic spiral surfaces that resemble sea-shells.
463
464 ParametricConicSpiral generates conic spiral surfaces. These can
465 resemble sea shells, or may look like a torus "eating" its own
466 tail.
467
468 Parameters
469 ----------
470 a : float, default: 0.2
471 The scale factor.
472
473 b : float, default: 1
474 The A function coefficient.
475 See the definition in Parametric surfaces referred to above.
476
477 c : float, default: 0.1
478 The B function coefficient.
479 See the definition in Parametric surfaces referred to above.
480
481 n : float, default: 2
482 The C function coefficient.
483 See the definition in Parametric surfaces referred to above.
484
485 **kwargs : dict, optional
486 See :func:`surface_from_para` for additional keyword arguments.
487
488 Returns
489 -------
490 pyvista.PolyData
491 ParametricConicSpiral surface.
492
493 Examples
494 --------
495 Create a ParametricConicSpiral mesh.
496
497 >>> import pyvista as pv
498 >>> mesh = pv.ParametricConicSpiral()
499 >>> mesh.plot(color='w', smooth_shading=True)
500
501 """
502 parametric_function = _vtk.vtkParametricConicSpiral()
503 if a is not None:
504 parametric_function.SetA(a)
505
506 if b is not None:
507 parametric_function.SetB(b)
508
509 if c is not None:
510 parametric_function.SetC(c)
511
512 if n is not None:
513 parametric_function.SetN(n)
514
515 center = kwargs.pop('center', [0.0, 0.0, 0.0])
516 direction = kwargs.pop('direction', [1.0, 0.0, 0.0])
517 surf = surface_from_para(parametric_function, **kwargs)
518
519 translate(surf, center, direction)
520
521 return surf
522
523
524 def ParametricCrossCap(**kwargs) -> PolyData:
525 """Generate a cross-cap.
526
527 ParametricCrossCap generates a cross-cap which is a non-orientable
528 self-intersecting single-sided surface. This is one possible
529 image of a projective plane in three-space.
530
531 Parameters
532 ----------
533 **kwargs : dict, optional
534 See :func:`surface_from_para` for additional keyword arguments.
535
536 Returns
537 -------
538 pyvista.PolyData
539 ParametricCrossCap surface.
540
541 Examples
542 --------
543 Create a ParametricCrossCap mesh.
544
545 >>> import pyvista as pv
546 >>> mesh = pv.ParametricCrossCap()
547 >>> mesh.plot(color='w', smooth_shading=True)
548
549 """
550 parametric_function = _vtk.vtkParametricCrossCap()
551
552 center = kwargs.pop('center', [0.0, 0.0, 0.0])
553 direction = kwargs.pop('direction', [1.0, 0.0, 0.0])
554 surf = surface_from_para(parametric_function, **kwargs)
555
556 translate(surf, center, direction)
557
558 return surf
559
560
561 def ParametricDini(a: float | None = None, b: float | None = None, **kwargs) -> PolyData:
562 """Generate Dini's surface.
563
564 ParametricDini generates Dini's surface. Dini's surface is a
565 surface that possesses constant negative Gaussian curvature
566
567 Parameters
568 ----------
569 a : float, default: 1.0
570 The scale factor. See the definition in Parametric surfaces
571 referred to above.
572
573 b : float, default: 0.2
574 The scale factor. See the definition in Parametric surfaces
575 referred to above.
576
577 **kwargs : dict, optional
578 See :func:`surface_from_para` for additional keyword arguments.
579
580 Returns
581 -------
582 pyvista.PolyData
583 ParametricDini surface.
584
585 Examples
586 --------
587 Create a ParametricDini mesh.
588
589 >>> import pyvista as pv
590 >>> mesh = pv.ParametricDini()
591 >>> mesh.plot(color='w', smooth_shading=True)
592
593 """
594 parametric_function = _vtk.vtkParametricDini()
595 if a is not None:
596 parametric_function.SetA(a)
597
598 if b is not None:
599 parametric_function.SetB(b)
600
601 center = kwargs.pop('center', [0.0, 0.0, 0.0])
602 direction = kwargs.pop('direction', [1.0, 0.0, 0.0])
603 surf = surface_from_para(parametric_function, **kwargs)
604
605 translate(surf, center, direction)
606
607 return surf
608
609
610 def ParametricEllipsoid(
611 xradius: float | None = None,
612 yradius: float | None = None,
613 zradius: float | None = None,
614 **kwargs,
615 ) -> PolyData:
616 """Generate an ellipsoid.
617
618 ParametricEllipsoid generates an ellipsoid. If all the radii are
619 the same, we have a sphere. An oblate spheroid occurs if RadiusX
620 = RadiusY > RadiusZ. Here the Z-axis forms the symmetry axis. To
621 a first approximation, this is the shape of the earth. A prolate
622 spheroid occurs if RadiusX = RadiusY < RadiusZ.
623
624 Parameters
625 ----------
626 xradius : float, default: 1.0
627 The scaling factor for the x-axis.
628
629 yradius : float, default: 1.0
630 The scaling factor for the y-axis.
631
632 zradius : float, default: 1.0
633 The scaling factor for the z-axis.
634
635 **kwargs : dict, optional
636 See :func:`surface_from_para` and :func:`parametric_keywords`
637 for additional keyword arguments.
638
639 Returns
640 -------
641 pyvista.PolyData
642 ParametricEllipsoid surface.
643
644 Examples
645 --------
646 Create a ParametricEllipsoid mesh.
647
648 >>> import pyvista as pv
649 >>> mesh = pv.ParametricEllipsoid()
650 >>> mesh.plot(color='w', smooth_shading=True)
651
652 """
653 parametric_function = _vtk.vtkParametricEllipsoid()
654 parametric_keywords(
655 parametric_function,
656 min_u=kwargs.pop('min_u', 0),
657 max_u=kwargs.pop('max_u', 2 * pi),
658 min_v=kwargs.pop('min_v', 0.0),
659 max_v=kwargs.pop('max_v', pi),
660 join_u=kwargs.pop('join_u', False),
661 join_v=kwargs.pop('join_v', False),
662 twist_u=kwargs.pop('twist_u', False),
663 twist_v=kwargs.pop('twist_v', False),
664 clockwise=kwargs.pop('clockwise', True),
665 )
666
667 if xradius is not None:
668 parametric_function.SetXRadius(xradius)
669
670 if yradius is not None:
671 parametric_function.SetYRadius(yradius)
672
673 if zradius is not None:
674 parametric_function.SetZRadius(zradius)
675
676 center = kwargs.pop('center', [0.0, 0.0, 0.0])
677 direction = kwargs.pop('direction', [1.0, 0.0, 0.0])
678 kwargs.setdefault('clean', True)
679 surf = surface_from_para(parametric_function, **kwargs)
680 translate(surf, center, direction)
681 return surf
682
683
684 def ParametricEnneper(**kwargs) -> PolyData:
685 """Generate Enneper's surface.
686
687 ParametricEnneper generates Enneper's surface. Enneper's surface
688 is a self-intersecting minimal surface possessing constant
689 negative Gaussian curvature.
690
691 Parameters
692 ----------
693 **kwargs : dict, optional
694 See :func:`surface_from_para` for additional keyword arguments.
695
696 Returns
697 -------
698 pyvista.PolyData
699 ParametricEnneper surface.
700
701 Examples
702 --------
703 Create a ParametricEnneper mesh.
704
705 >>> import pyvista as pv
706 >>> mesh = pv.ParametricEnneper()
707 >>> mesh.plot(color='w', smooth_shading=True)
708
709 """
710 parametric_function = _vtk.vtkParametricEnneper()
711
712 center = kwargs.pop('center', [0.0, 0.0, 0.0])
713 direction = kwargs.pop('direction', [1.0, 0.0, 0.0])
714 surf = surface_from_para(parametric_function, **kwargs)
715
716 translate(surf, center, direction)
717
718 return surf
719
720
721 def ParametricFigure8Klein(radius: float | None = None, **kwargs) -> PolyData:
722 """Generate a figure-8 Klein bottle.
723
724 ParametricFigure8Klein generates a figure-8 Klein bottle. A Klein
725 bottle is a closed surface with no interior and only one surface.
726 It is unrealisable in 3 dimensions without intersecting surfaces.
727
728 Parameters
729 ----------
730 radius : float, default: 1.0
731 The radius of the bottle.
732
733 **kwargs : dict, optional
734 See :func:`surface_from_para` for additional keyword arguments.
735
736 Returns
737 -------
738 pyvista.PolyData
739 ParametricFigure8Klein surface.
740
741 Examples
742 --------
743 Create a ParametricFigure8Klein mesh.
744
745 >>> import pyvista as pv
746 >>> mesh = pv.ParametricFigure8Klein()
747 >>> mesh.plot(color='w', smooth_shading=True)
748
749 """
750 parametric_function = _vtk.vtkParametricFigure8Klein()
751 if radius is not None:
752 parametric_function.SetRadius(radius)
753
754 center = kwargs.pop('center', [0.0, 0.0, 0.0])
755 direction = kwargs.pop('direction', [1.0, 0.0, 0.0])
756 kwargs.setdefault('clean', True)
757 surf = surface_from_para(parametric_function, **kwargs)
758 translate(surf, center, direction)
759 return surf
760
761
762 def ParametricHenneberg(**kwargs) -> PolyData:
763 """Generate Henneberg's minimal surface.
764
765 Parameters
766 ----------
767 **kwargs : dict, optional
768 See :func:`surface_from_para` for additional keyword arguments.
769
770 Returns
771 -------
772 pyvista.PolyData
773 ParametricHenneberg surface.
774
775 Examples
776 --------
777 Create a ParametricHenneberg mesh.
778
779 >>> import pyvista as pv
780 >>> mesh = pv.ParametricHenneberg()
781 >>> mesh.plot(color='w', smooth_shading=True)
782
783 """
784 parametric_function = _vtk.vtkParametricHenneberg()
785
786 center = kwargs.pop('center', [0.0, 0.0, 0.0])
787 direction = kwargs.pop('direction', [1.0, 0.0, 0.0])
788 surf = surface_from_para(parametric_function, **kwargs)
789
790 translate(surf, center, direction)
791
792 return surf
793
794
795 def ParametricKlein(**kwargs) -> PolyData:
796 """Generate a "classical" representation of a Klein bottle.
797
798 ParametricKlein generates a "classical" representation of a Klein
799 bottle. A Klein bottle is a closed surface with no interior and only one
800 surface. It is unrealisable in 3 dimensions without intersecting
801 surfaces.
802
803 Parameters
804 ----------
805 **kwargs : dict, optional
806 See :func:`surface_from_para` for additional keyword arguments.
807
808 Returns
809 -------
810 pyvista.PolyData
811 ParametricKlein surface.
812
813 Examples
814 --------
815 Create a ParametricKlein mesh.
816
817 >>> import pyvista as pv
818 >>> mesh = pv.ParametricKlein()
819 >>> mesh.plot(color='w', smooth_shading=True)
820
821 """
822 parametric_function = _vtk.vtkParametricKlein()
823
824 center = kwargs.pop('center', [0.0, 0.0, 0.0])
825 direction = kwargs.pop('direction', [1.0, 0.0, 0.0])
826 kwargs.setdefault('clean', True)
827 surf = surface_from_para(parametric_function, **kwargs)
828 translate(surf, center, direction)
829 return surf
830
831
832 def ParametricKuen(deltav0: float | None = None, **kwargs) -> PolyData:
833 """Generate Kuens' surface.
834
835 ParametricKuen generates Kuens' surface. This surface has a constant
836 negative Gaussian curvature.
837
838 Parameters
839 ----------
840 deltav0 : float, default: 0.05
841 The value to use when ``V == 0``.
842 This has the best appearance with the default settings.
843 Setting it to a value less than 0.05 extrapolates the surface
844 towards a pole in the -z direction.
845 Setting it to 0 retains the pole whose z-value is -inf.
846
847 **kwargs : dict, optional
848 See :func:`surface_from_para` for additional keyword arguments.
849
850 Returns
851 -------
852 pyvista.PolyData
853 ParametricKuen surface.
854
855 Examples
856 --------
857 Create a ParametricKuen mesh.
858
859 >>> import pyvista as pv
860 >>> mesh = pv.ParametricKuen()
861 >>> mesh.plot(color='w', smooth_shading=True)
862
863 """
864 parametric_function = _vtk.vtkParametricKuen()
865 if deltav0 is not None:
866 parametric_function.SetDeltaV0(deltav0)
867
868 center = kwargs.pop('center', [0.0, 0.0, 0.0])
869 direction = kwargs.pop('direction', [1.0, 0.0, 0.0])
870 kwargs.setdefault('clean', True)
871 surf = surface_from_para(parametric_function, **kwargs)
872 translate(surf, center, direction)
873 return surf
874
875
876 def ParametricMobius(radius: float | None = None, **kwargs) -> PolyData:
877 """Generate a Mobius strip.
878
879 Parameters
880 ----------
881 radius : float, default: 1.0
882 The radius of the Mobius strip.
883
884 **kwargs : dict, optional
885 See :func:`surface_from_para` for additional keyword arguments.
886
887 Returns
888 -------
889 pyvista.PolyData
890 ParametricMobius surface.
891
892 Examples
893 --------
894 Create a ParametricMobius mesh.
895
896 >>> import pyvista as pv
897 >>> mesh = pv.ParametricMobius()
898 >>> mesh.plot(color='w', smooth_shading=True)
899
900 """
901 parametric_function = _vtk.vtkParametricMobius()
902 if radius is not None:
903 parametric_function.SetRadius(radius)
904
905 center = kwargs.pop('center', [0.0, 0.0, 0.0])
906 direction = kwargs.pop('direction', [1.0, 0.0, 0.0])
907 surf = surface_from_para(parametric_function, **kwargs)
908 translate(surf, center, direction)
909 return surf
910
911
912 def ParametricPluckerConoid(n: int | None = None, **kwargs) -> PolyData:
913 """Generate Plucker's conoid surface.
914
915 ParametricPluckerConoid generates Plucker's conoid surface
916 parametrically. Plucker's conoid is a ruled surface, named after
917 Julius Plucker. It is possible to set the number of folds in this
918 class via the parameter 'n'.
919
920 Parameters
921 ----------
922 n : int, optional
923 This is the number of folds in the conoid.
924
925 **kwargs : dict, optional
926 See :func:`surface_from_para` for additional keyword arguments.
927
928 Returns
929 -------
930 pyvista.PolyData
931 ParametricPluckerConoid surface.
932
933 Examples
934 --------
935 Create a ParametricPluckerConoid mesh.
936
937 >>> import pyvista as pv
938 >>> mesh = pv.ParametricPluckerConoid()
939 >>> mesh.plot(color='w', smooth_shading=True)
940
941 """
942 parametric_function = _vtk.vtkParametricPluckerConoid()
943 if n is not None:
944 parametric_function.SetN(n)
945
946 center = kwargs.pop('center', [0.0, 0.0, 0.0])
947 direction = kwargs.pop('direction', [1.0, 0.0, 0.0])
948 surf = surface_from_para(parametric_function, **kwargs)
949
950 translate(surf, center, direction)
951
952 return surf
953
954
955 def ParametricPseudosphere(**kwargs) -> PolyData:
956 """Generate a pseudosphere.
957
958 ParametricPseudosphere generates a parametric pseudosphere. The
959 pseudosphere is generated as a surface of revolution of the
960 tractrix about it's asymptote, and is a surface of constant
961 negative Gaussian curvature.
962
963 Parameters
964 ----------
965 **kwargs : dict, optional
966 See :func:`surface_from_para` for additional keyword arguments.
967
968 Returns
969 -------
970 pyvista.PolyData
971 ParametricPseudosphere surface.
972
973 Examples
974 --------
975 Create a ParametricPseudosphere mesh.
976
977 >>> import pyvista as pv
978 >>> mesh = pv.ParametricPseudosphere()
979 >>> mesh.plot(color='w', smooth_shading=True)
980
981 """
982 parametric_function = _vtk.vtkParametricPseudosphere()
983
984 center = kwargs.pop('center', [0.0, 0.0, 0.0])
985 direction = kwargs.pop('direction', [1.0, 0.0, 0.0])
986 kwargs.setdefault('clean', True)
987 surf = surface_from_para(parametric_function, **kwargs)
988 translate(surf, center, direction)
989 return surf
990
991
992 @_deprecate_positional_args
993 def ParametricRandomHills( # noqa: PLR0917
994 number_of_hills: int | None = None,
995 hill_x_variance: float | None = None,
996 hill_y_variance: float | None = None,
997 hill_amplitude: float | None = None,
998 random_seed: int | None = None,
999 x_variance_scale_factor: float | None = None,
1000 y_variance_scale_factor: float | None = None,
1001 amplitude_scale_factor: float | None = None,
1002 **kwargs,
1003 ) -> PolyData:
1004 """Generate a surface covered with randomly placed hills.
1005
1006 ParametricRandomHills generates a surface covered with randomly
1007 placed hills. Hills will vary in shape and height since the
1008 presence of nearby hills will contribute to the shape and height
1009 of a given hill. An option is provided for placing hills on a
1010 regular grid on the surface. In this case the hills will all have
1011 the same shape and height.
1012
1013 Parameters
1014 ----------
1015 number_of_hills : int, default: 30
1016 The number of hills.
1017
1018 hill_x_variance : float, default: 2.5
1019 The hill variance in the x-direction.
1020
1021 hill_y_variance : float, default: 2.5
1022 The hill variance in the y-direction.
1023
1024 hill_amplitude : float, default: 2
1025 The hill amplitude (height).
1026
1027 random_seed : int, default: 1
1028 The Seed for the random number generator,
1029 a value of 1 will initialize the random number generator,
1030 a negative value will initialize it with the system time.
1031
1032 x_variance_scale_factor : float, default: 13
1033 The scaling factor for the variance in the x-direction.
1034
1035 y_variance_scale_factor : float, default: 13
1036 The scaling factor for the variance in the y-direction.
1037
1038 amplitude_scale_factor : float, default: 13
1039 The scaling factor for the amplitude.
1040
1041 **kwargs : dict, optional
1042 See :func:`surface_from_para` for additional keyword arguments.
1043
1044 Returns
1045 -------
1046 pyvista.PolyData
1047 ParametricRandomHills surface.
1048
1049 Examples
1050 --------
1051 Create a ParametricRandomHills mesh.
1052
1053 >>> import pyvista as pv
1054 >>> mesh = pv.ParametricRandomHills()
1055 >>> mesh.plot(color='w', smooth_shading=True)
1056
1057 """
1058 parametric_function = _vtk.vtkParametricRandomHills()
1059 if number_of_hills is not None:
1060 parametric_function.SetNumberOfHills(number_of_hills)
1061
1062 if hill_x_variance is not None:
1063 parametric_function.SetHillXVariance(hill_x_variance)
1064
1065 if hill_y_variance is not None:
1066 parametric_function.SetHillYVariance(hill_y_variance)
1067
1068 if hill_amplitude is not None:
1069 parametric_function.SetHillAmplitude(hill_amplitude)
1070
1071 if random_seed is not None:
1072 parametric_function.SetRandomSeed(random_seed)
1073
1074 if x_variance_scale_factor is not None:
1075 parametric_function.SetXVarianceScaleFactor(x_variance_scale_factor)
1076
1077 if y_variance_scale_factor is not None:
1078 parametric_function.SetYVarianceScaleFactor(y_variance_scale_factor)
1079
1080 if amplitude_scale_factor is not None:
1081 parametric_function.SetAmplitudeScaleFactor(amplitude_scale_factor)
1082
1083 center = kwargs.pop('center', [0.0, 0.0, 0.0])
1084 direction = kwargs.pop('direction', [1.0, 0.0, 0.0])
1085 surf = surface_from_para(parametric_function, **kwargs)
1086
1087 translate(surf, center, direction)
1088
1089 return surf
1090
1091
1092 def ParametricRoman(radius: float | None = None, **kwargs) -> PolyData:
1093 """Generate Steiner's Roman Surface.
1094
1095 Parameters
1096 ----------
1097 radius : float, default: 1
1098 The radius.
1099
1100 **kwargs : dict, optional
1101 See :func:`surface_from_para` for additional keyword arguments.
1102
1103 Returns
1104 -------
1105 pyvista.PolyData
1106 ParametricRoman surface.
1107
1108 Examples
1109 --------
1110 Create a ParametricRoman mesh.
1111
1112 >>> import pyvista as pv
1113 >>> mesh = pv.ParametricRoman()
1114 >>> mesh.plot(color='w', smooth_shading=True)
1115
1116 """
1117 parametric_function = _vtk.vtkParametricRoman()
1118 if radius is not None:
1119 parametric_function.SetRadius(radius)
1120
1121 center = kwargs.pop('center', [0.0, 0.0, 0.0])
1122 direction = kwargs.pop('direction', [1.0, 0.0, 0.0])
1123 surf = surface_from_para(parametric_function, **kwargs)
1124
1125 translate(surf, center, direction)
1126
1127 return surf
1128
1129
1130 @_deprecate_positional_args(allowed=['xradius', 'yradius', 'zradius'])
1131 def ParametricSuperEllipsoid( # noqa: PLR0917
1132 xradius: float | None = None,
1133 yradius: float | None = None,
1134 zradius: float | None = None,
1135 n1: float | None = None,
1136 n2: float | None = None,
1137 **kwargs,
1138 ) -> PolyData:
1139 """Generate a superellipsoid.
1140
1141 ParametricSuperEllipsoid generates a superellipsoid. A superellipsoid
1142 is a versatile primitive that is controlled by two parameters n1 and
1143 n2. As special cases it can represent a sphere, square box, and closed
1144 cylindrical can.
1145
1146 Parameters
1147 ----------
1148 xradius : float, default: 1
1149 The scaling factor for the x-axis.
1150
1151 yradius : float, default: 1
1152 The scaling factor for the y-axis.
1153
1154 zradius : float, default: 1
1155 The scaling factor for the z-axis.
1156
1157 n1 : float, default: 1
1158 The "squareness" parameter in the z-axis.
1159
1160 n2 : float, default: 1
1161 The "squareness" parameter in the x-y plane.
1162
1163 **kwargs : dict, optional
1164 See :func:`surface_from_para` for additional keyword arguments.
1165
1166 Returns
1167 -------
1168 pyvista.PolyData
1169 ParametricSuperEllipsoid surface.
1170
1171 See Also
1172 --------
1173 pyvista.ParametricSuperToroid :
1174 Toroidal equivalent of ParametricSuperEllipsoid.
1175 pyvista.Superquadric :
1176 Geometric object with additional parameters.
1177
1178 Examples
1179 --------
1180 Create a ParametricSuperEllipsoid surface that looks like a box
1181 with smooth edges.
1182
1183 >>> import pyvista as pv
1184 >>> mesh = pv.ParametricSuperEllipsoid(n1=0.02, n2=0.02)
1185 >>> mesh.plot(color='w', smooth_shading=True)
1186
1187 Create one that looks like a spinning top.
1188
1189 >>> mesh = pv.ParametricSuperEllipsoid(n1=4, n2=0.5)
1190 >>> mesh.plot(color='w', smooth_shading=True, cpos='xz')
1191
1192 """
1193 parametric_function = _vtk.vtkParametricSuperEllipsoid()
1194 if xradius is not None:
1195 parametric_function.SetXRadius(xradius)
1196
1197 if yradius is not None:
1198 parametric_function.SetYRadius(yradius)
1199
1200 if zradius is not None:
1201 parametric_function.SetZRadius(zradius)
1202
1203 if n1 is not None:
1204 parametric_function.SetN1(n1)
1205
1206 if n2 is not None:
1207 parametric_function.SetN2(n2)
1208
1209 center = kwargs.pop('center', [0.0, 0.0, 0.0])
1210 direction = kwargs.pop('direction', [1.0, 0.0, 0.0])
1211 surf = surface_from_para(parametric_function, **kwargs)
1212
1213 translate(surf, center, direction)
1214
1215 return surf
1216
1217
1218 @_deprecate_positional_args
1219 def ParametricSuperToroid( # noqa: PLR0917
1220 ringradius: float | None = None,
1221 crosssectionradius: float | None = None,
1222 xradius: float | None = None,
1223 yradius: float | None = None,
1224 zradius: float | None = None,
1225 n1: float | None = None,
1226 n2: float | None = None,
1227 **kwargs,
1228 ) -> PolyData:
1229 """Generate a supertoroid.
1230
1231 ParametricSuperToroid generates a supertoroid. Essentially a
1232 supertoroid is a torus with the sine and cosine terms raised to a power.
1233 A supertoroid is a versatile primitive that is controlled by four
1234 parameters r0, r1, n1 and n2. r0, r1 determine the type of torus whilst
1235 the value of n1 determines the shape of the torus ring and n2 determines
1236 the shape of the cross section of the ring. It is the different values of
1237 these powers which give rise to a family of 3D shapes that are all
1238 basically toroidal in shape.
1239
1240 Parameters
1241 ----------
1242 ringradius : float, default: 1
1243 The radius from the center to the middle of the ring of the
1244 supertoroid.
1245
1246 crosssectionradius : float, default: 0.5
1247 The radius of the cross section of ring of the supertoroid.
1248
1249 xradius : float, default: 1
1250 The scaling factor for the x-axis.
1251
1252 yradius : float, default: 1
1253 The scaling factor for the y-axis.
1254
1255 zradius : float, default: 1
1256 The scaling factor for the z-axis.
1257
1258 n1 : float, default: 1
1259 The shape of the torus ring.
1260
1261 n2 : float, default: 1
1262 The shape of the cross section of the ring.
1263
1264 **kwargs : dict, optional
1265 See :func:`surface_from_para` for additional keyword arguments.
1266
1267 Returns
1268 -------
1269 pyvista.PolyData
1270 ParametricSuperToroid surface.
1271
1272 See Also
1273 --------
1274 pyvista.ParametricSuperEllipsoid :
1275 Ellipsoidal equivalent of ParametricSuperToroid.
1276 pyvista.Superquadric :
1277 Geometric object with additional parameters.
1278
1279 Examples
1280 --------
1281 Create a ParametricSuperToroid mesh.
1282
1283 >>> import pyvista as pv
1284 >>> mesh = pv.ParametricSuperToroid(n1=2, n2=0.3)
1285 >>> mesh.plot(color='w', smooth_shading=True)
1286
1287 """
1288 parametric_function = _vtk.vtkParametricSuperToroid()
1289 if ringradius is not None:
1290 parametric_function.SetRingRadius(ringradius)
1291
1292 if crosssectionradius is not None:
1293 parametric_function.SetCrossSectionRadius(crosssectionradius)
1294
1295 if xradius is not None:
1296 parametric_function.SetXRadius(xradius)
1297
1298 if yradius is not None:
1299 parametric_function.SetYRadius(yradius)
1300
1301 if zradius is not None:
1302 parametric_function.SetZRadius(zradius)
1303
1304 if n1 is not None:
1305 parametric_function.SetN1(n1)
1306
1307 if n2 is not None:
1308 parametric_function.SetN2(n2)
1309
1310 center = kwargs.pop('center', [0.0, 0.0, 0.0])
1311 direction = kwargs.pop('direction', [1.0, 0.0, 0.0])
1312 kwargs.setdefault('clean', True)
1313 surf = surface_from_para(parametric_function, **kwargs)
1314 translate(surf, center, direction)
1315 return surf
1316
1317
1318 def ParametricTorus(
1319 ringradius: float | None = None, crosssectionradius: float | None = None, **kwargs
1320 ) -> PolyData:
1321 """Generate a torus.
1322
1323 Parameters
1324 ----------
1325 ringradius : float, default: 1.0
1326 The radius from the center to the middle of the ring of the
1327 torus.
1328
1329 crosssectionradius : float, default: 0.5
1330 The radius of the cross section of ring of the torus.
1331
1332 **kwargs : dict, optional
1333 See :func:`surface_from_para` for additional keyword arguments.
1334
1335 Returns
1336 -------
1337 pyvista.PolyData
1338 ParametricTorus surface.
1339
1340 Examples
1341 --------
1342 Create a ParametricTorus mesh.
1343
1344 >>> import pyvista as pv
1345 >>> mesh = pv.ParametricTorus()
1346 >>> mesh.plot(color='w', smooth_shading=True)
1347
1348 """
1349 parametric_function = _vtk.vtkParametricTorus()
1350 if ringradius is not None:
1351 parametric_function.SetRingRadius(ringradius)
1352
1353 if crosssectionradius is not None:
1354 parametric_function.SetCrossSectionRadius(crosssectionradius)
1355
1356 center = kwargs.pop('center', [0.0, 0.0, 0.0])
1357 direction = kwargs.pop('direction', [1.0, 0.0, 0.0])
1358 kwargs.setdefault('clean', True)
1359 surf = surface_from_para(parametric_function, **kwargs)
1360 translate(surf, center, direction)
1361 return surf
1362
1363
1364 @_deprecate_positional_args(allowed=['parametric_function'])
1365 def parametric_keywords( # noqa: PLR0917
1366 parametric_function: _vtk.vtkParametricFunction,
1367 min_u: float = 0.0,
1368 max_u: float = 2 * pi,
1369 min_v: float = 0.0,
1370 max_v: float = 2 * pi,
1371 join_u: bool = False, # noqa: FBT001, FBT002
1372 join_v: bool = False, # noqa: FBT001, FBT002
1373 twist_u: bool = False, # noqa: FBT001, FBT002
1374 twist_v: bool = False, # noqa: FBT001, FBT002
1375 clockwise: bool = True, # noqa: FBT001, FBT002
1376 ) -> None:
1377 """Apply keyword arguments to a parametric function.
1378
1379 Parameters
1380 ----------
1381 parametric_function : :vtk:`vtkParametricFunction`
1382 Parametric function to generate mesh from.
1383
1384 min_u : float, optional
1385 The minimum u-value.
1386
1387 max_u : float, optional
1388 The maximum u-value.
1389
1390 min_v : float, optional
1391 The minimum v-value.
1392
1393 max_v : float, optional
1394 The maximum v-value.
1395
1396 join_u : bool, optional
1397 Joins the first triangle strip to the last one with a twist in
1398 the u direction.
1399
1400 join_v : bool, optional
1401 Joins the first triangle strip to the last one with a twist in
1402 the v direction.
1403
1404 twist_u : bool, optional
1405 Joins the first triangle strip to the last one with a twist in
1406 the u direction.
1407
1408 twist_v : bool, optional
1409 Joins the first triangle strip to the last one with a twist in
1410 the v direction.
1411
1412 clockwise : bool, optional
1413 Determines the ordering of the vertices forming the triangle
1414 strips.
1415
1416 """
1417 parametric_function.SetMinimumU(min_u)
1418 parametric_function.SetMaximumU(max_u)
1419 parametric_function.SetMinimumV(min_v)
1420 parametric_function.SetMaximumV(max_v)
1421 parametric_function.SetJoinU(join_u)
1422 parametric_function.SetJoinV(join_v)
1423 parametric_function.SetTwistU(twist_u)
1424 parametric_function.SetTwistV(twist_v)
1425 parametric_function.SetClockwiseOrdering(clockwise)
1426
1427
1428 @_deprecate_positional_args(allowed=['parametric_function'])
1429 def surface_from_para( # noqa: PLR0917
1430 parametric_function: _vtk.vtkParametricFunction,
1431 u_res: int = 100,
1432 v_res: int = 100,
1433 w_res: int = 100,
1434 clean: bool = False, # noqa: FBT001, FBT002
1435 texture_coordinates: bool = False, # noqa: FBT001, FBT002
1436 ) -> PolyData:
1437 """Construct a mesh from a parametric function.
1438
1439 Parameters
1440 ----------
1441 parametric_function : :vtk:`vtkParametricFunction`
1442 Parametric function to generate mesh from.
1443
1444 u_res : int, default: 100
1445 Resolution in the u direction.
1446
1447 v_res : int, default: 100
1448 Resolution in the v direction.
1449
1450 w_res : int, default: 100
1451 Resolution in the w direction.
1452
1453 clean : bool, default: False
1454 Clean and merge duplicate points to avoid "creases" when
1455 plotting with smooth shading.
1456
1457 texture_coordinates : bool, default: False
1458 The generation of texture coordinates.
1459 This is off by default. Note that this is only applicable
1460 to parametric surfaces whose parametric dimension is 2.
1461 Note that texturing may fail in some cases.
1462
1463 Returns
1464 -------
1465 pyvista.PolyData
1466 Surface from the parametric function.
1467
1468 """
1469 # convert to a mesh
1470 para_source = _vtk.vtkParametricFunctionSource()
1471 para_source.SetParametricFunction(parametric_function)
1472 para_source.SetUResolution(u_res)
1473 para_source.SetVResolution(v_res)
1474 para_source.SetWResolution(w_res)
1475 para_source.SetGenerateTextureCoordinates(texture_coordinates)
1476 para_source.Update()
1477 surf = wrap(para_source.GetOutput())
1478 if clean:
1479 surf = surf.clean(
1480 tolerance=1e-7, # determined experimentally
1481 absolute=False,
1482 lines_to_points=False,
1483 polys_to_lines=False,
1484 strips_to_polys=False,
1485 )
1486 return surf