Debian Codegraph @

pyvista/core/utilities/reader.py

raw
1 """Fine-grained control of reading data files."""
2
3 from __future__ import annotations
4
5 from abc import ABC
6 from abc import abstractmethod
7 from dataclasses import dataclass
8 import enum
9 import json
10 import os
11 from pathlib import Path
12 from typing import TYPE_CHECKING
13 from typing import Any
14 from typing import ClassVar
15 from typing import Generic
16 from typing import Literal
17 from typing import TypeVar
18 from typing import cast
19 from typing import get_args
20 import weakref
21 from xml.etree import ElementTree as ET
22
23 import numpy as np
24
25 import pyvista as pv
26 from pyvista import _vtk
27 from pyvista._deprecate_positional_args import _deprecate_positional_args
28 from pyvista._warn_external import warn_external
29 from pyvista.core._vtk_utilities import VersionInfo
30 from pyvista.core.errors import InvalidMeshWarning
31
32 from ._frd import _FRDParser
33 from .fileio import _FileIOBase
34 from .fileio import _get_ext_force
35 from .fileio import _lazy_vtk_import
36 from .fileio import _process_filename
37 from .helpers import wrap
38 from .misc import _NoNewAttrMixin
39 from .misc import abstract_class
40
41 if TYPE_CHECKING:
42 from collections.abc import Callable
43
44 # These are referenced as string forward references in ``BaseReader``
45 # generic parameterization on subclasses (e.g. ``BaseReader['PolyData']``)
46 # and in the ``_T_Output_co`` TypeVar bound. Static type checkers
47 # (mypy, pyright) resolve those strings against this module's namespace,
48 # so the imports are required at type-check time even though Ruff
49 # cannot see the reference inside a string literal.
50 from pyvista import DataObject
51 from pyvista import DataSet # noqa: F401
52 from pyvista import ImageData # noqa: F401
53 from pyvista import MultiBlock # noqa: F401
54 from pyvista import PartitionedDataSet # noqa: F401
55 from pyvista import PolyData # noqa: F401
56 from pyvista import RectilinearGrid # noqa: F401
57 from pyvista import StructuredGrid # noqa: F401
58 from pyvista import UnstructuredGrid # noqa: F401
59
60 from ._frd import _FRDData
61
62 HDF_HELP = 'https://docs.vtk.org/en/latest/vtk_file_formats/index.html#vtkhdf'
63 CLASS_READERS: dict[str, type[BaseReader[Any]]] = {}
64
65 # Covariant TypeVar for :class:`BaseReader`'s output type. Covariant is
66 # correct because ``BaseReader`` only *produces* values of ``T_Output``
67 # (via :meth:`BaseReader.read`); it never accepts them as input.
68 _T_Output_co = TypeVar('_T_Output_co', bound='DataObject', covariant=True)
69
70 _mesh_types = Literal[
71 'UnstructuredGrid',
72 'ImageData',
73 'PolyData',
74 'MultiBlock',
75 'RectilinearGrid',
76 'StructuredGrid',
77 'PointSet',
78 'PartitionedDataSet',
79 ]
80 _legacy_dataset_types = Literal[ # no PointSet
81 'UnstructuredGrid',
82 'ImageData',
83 'PolyData',
84 'RectilinearGrid',
85 'StructuredGrid',
86 ]
87
88
89 def get_reader(filename, force_ext=None):
90 """Get a reader for fine-grained control of reading data files.
91
92 Supported file types and Readers:
93
94 .. include:: /api/readers/readers_table.rst
95
96 Parameters
97 ----------
98 filename : str, Path
99 The string path to the file to read.
100
101 force_ext : str, optional
102 An extension to force a specific reader to be chosen.
103
104 Returns
105 -------
106 pyvista.BaseReader
107 A subclass of :class:`pyvista.BaseReader` is returned based on file type.
108
109 Examples
110 --------
111 >>> import pyvista as pv
112 >>> from pyvista import examples
113 >>> from pathlib import Path
114 >>> filename = examples.download_human(load=False)
115 >>> Path(filename).name
116 'Human.vtp'
117 >>> reader = pv.get_reader(filename)
118 >>> reader
119 XMLPolyDataReader('...Human.vtp')
120 >>> mesh = reader.read()
121 >>> mesh
122 PolyData ...
123 >>> mesh.plot(color='lightblue')
124
125 """
126 ext = _get_ext_force(filename, force_ext)
127
128 try:
129 Reader = CLASS_READERS[ext]
130 except KeyError:
131 if Path(filename).is_dir():
132 if len(files := os.listdir(filename)) > 0 and all( # noqa: PTH208
133 Path(f).suffix == '.dcm' for f in files
134 ):
135 Reader = DICOMReader
136 else:
137 msg = (
138 f'`pyvista.get_reader` does not support reading from directory:\n\t{filename}'
139 )
140 raise ValueError(msg)
141 else:
142 msg = f'`pyvista.get_reader` does not support a file with the {ext} extension'
143 raise ValueError(msg)
144
145 return Reader(filename)
146
147
148 class BaseVTKReader(ABC):
149 """Simulate a VTK reader."""
150
151 def __init__(self: BaseVTKReader) -> None:
152 self._data_object: pv.DataObject | None = None
153 self._observers: list[int | Callable[[Any], Any]] = []
154
155 def SetFileName(self, filename) -> None:
156 """Set file name."""
157 self._filename = filename
158
159 @abstractmethod
160 def UpdateInformation(self):
161 """Update Information from file."""
162
163 def AddObserver(self, event_type, callback) -> None:
164 """Add Observer that can be triggered during Update."""
165 self._observers.append([event_type, callback]) # type: ignore[arg-type]
166
167 def RemoveObservers(self, *args) -> None: # noqa: ARG002
168 """Remove Observer."""
169 self._observers = []
170
171 def GetProgress(self):
172 """GetProgress."""
173 return 0.0 if self._data_object is None else 1.0
174
175 def UpdateObservers(self, event_type) -> None:
176 """Call matching observer."""
177 for event_type_allowed, observer in self._observers: # type: ignore[misc]
178 if event_type_allowed == event_type:
179 observer(self, event_type)
180
181 @abstractmethod
182 def Update(self):
183 """Update Reader from file and store data internally.
184
185 Set self._data_object.
186 """
187
188 def GetOutputDataObject(self, *args): # noqa: ARG002
189 """Return stored data."""
190 return self._data_object
191
192
193 @abstract_class
194 class BaseReader(_FileIOBase, Generic[_T_Output_co]):
195 """The Base Reader class.
196
197 The base functionality includes reading data from a file,
198 and allowing access to the underlying vtk reader. See
199 :func:`pyvista.get_reader` for an example using
200 a built-in subclass.
201
202 Subclasses parameterize ``BaseReader`` with the concrete
203 :class:`~pyvista.DataObject` subclass they produce, e.g.
204 :class:`XMLPolyDataReader` is declared as
205 ``class XMLPolyDataReader(BaseReader[PolyData], ...)`` so
206 :meth:`read` returns :class:`~pyvista.PolyData` under static analysis
207 without each subclass needing its own ``read`` override.
208
209 Parameters
210 ----------
211 path : str, Path
212 Path of the file to read.
213
214 """
215
216 _class_reader: Any = None
217
218 # Override on subclasses whose VTK reader can emit more than one
219 # concrete :class:`~pyvista.DataObject` subclass. The ``BaseReader[X]``
220 # generic parameter on such a class is the narrowest common supertype
221 # the VTK format allows (e.g. ``BaseReader['DataSet']``), so docs and
222 # tests that need the exact list consult this attribute.
223 _output_types: ClassVar[tuple[_mesh_types, ...] | None] = None
224
225 def __init__(self, path) -> None:
226 """Initialize Reader by setting path."""
227 if cls := self._vtk_class:
228 self._reader = cls()
229 else:
230 # edge case where some class customization is needed on instantiation
231 self._reader = self._class_reader()
232 self._filename: str | None = None
233 self._progress_bar = False
234 self._progress_msg = None
235 self.__directory = None
236 self._set_defaults()
237 self.path = str(path)
238 self._set_defaults_post()
239
240 def __repr__(self) -> str:
241 """Representation of a Reader object."""
242 return f"{self.__class__.__name__}('{self.path}')"
243
244 @classmethod
245 def _get_extension_mappings(cls) -> list[dict[str, type]]:
246 return [CLASS_READERS]
247
248 def show_progress(self, msg=None) -> None:
249 """Show a progress bar when loading the file.
250
251 Parameters
252 ----------
253 msg : str, optional
254 Progress bar message. Defaults to ``"Reading <file base name>"``.
255
256 Examples
257 --------
258 >>> import pyvista as pv
259 >>> from pyvista import examples
260 >>> filename = examples.download_cavity(load=False)
261 >>> reader = pv.OpenFOAMReader(filename)
262 >>> reader.show_progress()
263
264 """
265 self._progress_bar = True
266 if msg is None:
267 msg = f'Reading {Path(self.path).name}'
268 self._progress_msg = msg
269
270 def hide_progress(self) -> None:
271 """Hide the progress bar when loading the file.
272
273 Examples
274 --------
275 >>> import pyvista as pv
276 >>> from pyvista import examples
277 >>> filename = examples.download_cavity(load=False)
278 >>> reader = pv.OpenFOAMReader(filename)
279 >>> reader.hide_progress()
280
281 """
282 self._progress_bar = False
283
284 @property
285 def reader(self):
286 """Return the vtk Reader object.
287
288 Returns
289 -------
290 pyvista.BaseReader
291 An instance of the Reader object.
292
293 """
294 if self._reader is None: # pragma: no cover
295 raise NotImplementedError
296 return self._reader
297
298 @property
299 def path(self) -> str:
300 """Return or set the filename or directory of the reader.
301
302 Examples
303 --------
304 >>> import pyvista as pv
305 >>> from pyvista import examples
306 >>> filename = examples.download_human(load=False)
307 >>> reader = pv.XMLPolyDataReader(filename)
308 >>> reader.path # doctest:+SKIP
309 '/home/user/.local/share/pyvista/examples/Human.vtp'
310
311 """
312 if self._filename is not None:
313 return self._filename
314 return self.__directory # type: ignore[return-value]
315
316 @path.setter
317 def path(self, path: str | Path):
318 if Path(path).is_dir():
319 self._set_directory(path)
320 elif Path(path).is_file():
321 self._set_filename(path)
322 else:
323 msg = f"Path '{path}' is invalid or does not exist."
324 raise FileNotFoundError(msg)
325
326 def _set_directory(self, directory) -> None:
327 """Set directory and update reader."""
328 self._filename = None
329 self.__directory = directory
330 self.reader.SetDirectoryName(directory)
331 self._update_information()
332
333 def _set_filename(self, filename) -> None:
334 """Set filename and update reader."""
335 # Private method since changing file type requires a
336 # different subclass.
337 self.__directory = None
338 self._filename = filename
339 self.reader.SetFileName(filename)
340 self._update_information()
341
342 def read(self, *, validate: bool | None = None) -> _T_Output_co: # numpydoc ignore=RT01
343 """Read data in file.
344
345 Parameters
346 ----------
347 validate : bool, optional
348 Forwarded to :func:`pyvista.wrap` as the ``validate`` keyword.
349 When ``True``, perform a cheap array-length sanity check on the
350 read dataset and emit a :class:`~pyvista.InvalidMeshWarning` on a
351 mismatch. When ``False``, skip the check entirely. When ``None``
352 (the default), honor
353 :attr:`pyvista.core.config.Config.validate_on_wrap`.
354
355 .. versionadded:: 0.48
356
357 Returns
358 -------
359 pyvista.DataObject
360 PyVista dataset. The concrete subclass is determined by the
361 specific ``*Reader`` used; for example,
362 :class:`~pyvista.XMLUnstructuredGridReader` produces an
363 :class:`~pyvista.UnstructuredGrid`.
364
365 """
366 from pyvista.core.filters import _update_alg # avoid circular import # noqa: PLC0415
367
368 _update_alg(self.reader, progress_bar=self._progress_bar, message=self._progress_msg)
369 data = wrap(self.reader.GetOutputDataObject(0), validate=validate)
370 if data is None: # pragma: no cover
371 msg = 'File reader failed to read and/or produced no output.'
372 raise RuntimeError(msg)
373 data._post_file_load_processing()
374
375 # check for any pyvista metadata
376 data._restore_metadata()
377 return cast('_T_Output_co', data)
378
379 def _update_information(self) -> None:
380 self.reader.UpdateInformation()
381
382 def _set_defaults(self) -> None:
383 """Set defaults on reader, if needed."""
384
385 def _set_defaults_post(self) -> None:
386 """Set defaults on reader post setting file, if needed."""
387
388
389 class PointCellDataSelection(_NoNewAttrMixin):
390 """Mixin for readers that support data array selections.
391
392 Examples
393 --------
394 >>> import pyvista as pv
395 >>> from pyvista import examples
396 >>> from pathlib import Path
397 >>> filename = examples.download_backward_facing_step(load=False)
398 >>> Path(filename).name
399 'foam_case_0_0_0_0.case'
400 >>> reader = pv.get_reader(filename)
401 >>> reader
402 EnSightReader('.../foam_case_0_0_0_0.case')
403 >>> reader.cell_array_names
404 ['v2', 'nut', 'k', 'nuTilda', 'p', 'omega', 'f', 'epsilon', 'U']
405 >>> reader.point_array_names
406 []
407 >>> reader.all_cell_arrays_status # doctest: +NORMALIZE_WHITESPACE
408 {'v2': True, 'nut': True, 'k': True, 'nuTilda': True, 'p': True,
409 'omega': True, 'f': True, 'epsilon': True, 'U': True}
410 >>> reader.disable_all_cell_arrays()
411 >>> reader.enable_cell_array('U')
412 >>> mesh = reader.read() # MultiBlock mesh
413 >>> mesh[0].array_names
414 ['U']
415
416 """
417
418 @property
419 def number_point_arrays(self):
420 """Return the number of point arrays.
421
422 Returns
423 -------
424 int
425 Number of point arrays.
426
427 """
428 return self.reader.GetNumberOfPointArrays() # type: ignore[attr-defined]
429
430 @property
431 def point_array_names(self):
432 """Return the list of all point array names.
433
434 Returns
435 -------
436 list[str]
437 List of all point array names.
438
439 """
440 return [self.reader.GetPointArrayName(i) for i in range(self.number_point_arrays)] # type: ignore[attr-defined]
441
442 def enable_point_array(self, name) -> None:
443 """Enable point array with name.
444
445 Parameters
446 ----------
447 name : str
448 Point array name.
449
450 """
451 self.reader.SetPointArrayStatus(name, 1) # type: ignore[attr-defined]
452
453 def disable_point_array(self, name) -> None:
454 """Disable point array with name.
455
456 Parameters
457 ----------
458 name : str
459 Point array name.
460
461 """
462 self.reader.SetPointArrayStatus(name, 0) # type: ignore[attr-defined]
463
464 def point_array_status(self, name):
465 """Get status of point array with name.
466
467 Parameters
468 ----------
469 name : str
470 Point array name.
471
472 Returns
473 -------
474 bool
475 Whether reading the cell array is enabled.
476
477 """
478 return bool(self.reader.GetPointArrayStatus(name)) # type: ignore[attr-defined]
479
480 def enable_all_point_arrays(self) -> None:
481 """Enable all point arrays."""
482 for name in self.point_array_names:
483 self.enable_point_array(name)
484
485 def disable_all_point_arrays(self) -> None:
486 """Disable all point arrays."""
487 for name in self.point_array_names:
488 self.disable_point_array(name)
489
490 @property
491 def all_point_arrays_status(self):
492 """Return the status of all point arrays.
493
494 Returns
495 -------
496 dict[str, bool]
497 Status of all point arrays.
498
499 """
500 return {name: self.point_array_status(name) for name in self.point_array_names}
501
502 @property
503 def number_cell_arrays(self):
504 """Return the number of cell arrays.
505
506 Returns
507 -------
508 int
509 Number of cell arrays.
510
511 """
512 return self.reader.GetNumberOfCellArrays() # type: ignore[attr-defined]
513
514 @property
515 def cell_array_names(self):
516 """Return the list of all cell array names.
517
518 Returns
519 -------
520 list[str]
521 List of all cell array names.
522
523 """
524 return [self.reader.GetCellArrayName(i) for i in range(self.number_cell_arrays)] # type: ignore[attr-defined]
525
526 def enable_cell_array(self, name) -> None:
527 """Enable cell array with name.
528
529 Parameters
530 ----------
531 name : str
532 Cell array name.
533
534 """
535 self.reader.SetCellArrayStatus(name, 1) # type: ignore[attr-defined]
536
537 def disable_cell_array(self, name) -> None:
538 """Disable cell array with name.
539
540 Parameters
541 ----------
542 name : str
543 Cell array name.
544
545 """
546 self.reader.SetCellArrayStatus(name, 0) # type: ignore[attr-defined]
547
548 def cell_array_status(self, name):
549 """Get status of cell array with name.
550
551 Parameters
552 ----------
553 name : str
554 Cell array name.
555
556 Returns
557 -------
558 bool
559 Whether reading the cell array is enabled.
560
561 """
562 return bool(self.reader.GetCellArrayStatus(name)) # type: ignore[attr-defined]
563
564 def enable_all_cell_arrays(self) -> None:
565 """Enable all cell arrays."""
566 for name in self.cell_array_names:
567 self.enable_cell_array(name)
568
569 def disable_all_cell_arrays(self) -> None:
570 """Disable all cell arrays."""
571 for name in self.cell_array_names:
572 self.disable_cell_array(name)
573
574 @property
575 def all_cell_arrays_status(self):
576 """Return the status of all cell arrays.
577
578 Returns
579 -------
580 dict[str, bool]
581 Name and if the cell array is available.
582
583 """
584 return {name: self.cell_array_status(name) for name in self.cell_array_names}
585
586
587 class TimeReader(ABC):
588 """Abstract class for readers supporting time."""
589
590 @property
591 @abstractmethod
592 def number_time_points(self):
593 """Return number of time points or iterations available to read.
594
595 Returns
596 -------
597 int
598
599 """
600
601 @abstractmethod
602 def time_point_value(self, time_point):
603 """Value of time point or iteration by index.
604
605 Parameters
606 ----------
607 time_point : int
608 Time point index.
609
610 Returns
611 -------
612 float
613
614 """
615
616 @property
617 def time_values(self):
618 """All time or iteration values.
619
620 Returns
621 -------
622 list[float]
623
624 """
625 return [self.time_point_value(idx) for idx in range(self.number_time_points)]
626
627 @property
628 @abstractmethod
629 def active_time_value(self):
630 """Active time or iteration value.
631
632 Returns
633 -------
634 float
635
636 """
637
638 @abstractmethod
639 def set_active_time_value(self, time_value):
640 """Set active time or iteration value.
641
642 Parameters
643 ----------
644 time_value : float
645 Time or iteration value to set as active.
646
647 """
648
649 @abstractmethod
650 def set_active_time_point(self, time_point):
651 """Set active time or iteration by index.
652
653 Parameters
654 ----------
655 time_point : int
656 Time or iteration point index for setting active time.
657
658 """
659
660
661 class XMLImageDataReader(BaseReader['ImageData'], PointCellDataSelection):
662 """XML Image Data Reader for .vti files.
663
664 Wraps :vtk:`vtkXMLImageDataReader`.
665
666 """
667
668 _vtk_module_name = 'vtkIOXML'
669 _vtk_class_name = 'vtkXMLImageDataReader'
670
671
672 class XMLPImageDataReader(BaseReader['ImageData'], PointCellDataSelection):
673 """Parallel XML Image Data Reader for .pvti files.
674
675 Wraps :vtk:`vtkXMLPImageDataReader`.
676
677 """
678
679 _vtk_module_name = 'vtkIOXML'
680 _vtk_class_name = 'vtkXMLPImageDataReader'
681
682
683 class XMLRectilinearGridReader(BaseReader['RectilinearGrid'], PointCellDataSelection):
684 """XML RectilinearGrid Reader for .vtr files.
685
686 Wraps :vtk:`vtkXMLRectilinearGridReader`.
687
688 Examples
689 --------
690 >>> import pyvista as pv
691 >>> from pyvista import examples
692 >>> from pathlib import Path
693 >>> filename = examples.download_rectilinear_grid(load=False)
694 >>> Path(filename).name
695 'RectilinearGrid.vtr'
696 >>> reader = pv.get_reader(filename)
697 >>> mesh = reader.read()
698 >>> sliced_mesh = mesh.slice('y')
699 >>> sliced_mesh.plot(
700 ... scalars='Void Volume Fraction',
701 ... cpos='xz',
702 ... show_scalar_bar=False,
703 ... )
704
705 """
706
707 _vtk_module_name = 'vtkIOXML'
708 _vtk_class_name = 'vtkXMLRectilinearGridReader'
709
710
711 class XMLPRectilinearGridReader(BaseReader['RectilinearGrid'], PointCellDataSelection):
712 """Parallel XML RectilinearGrid Reader for .pvtr files.
713
714 Wraps :vtk:`vtkXMLPRectilinearGridReader`.
715
716 """
717
718 _vtk_module_name = 'vtkIOXML'
719 _vtk_class_name = 'vtkXMLPRectilinearGridReader'
720
721
722 class XMLUnstructuredGridReader(BaseReader['UnstructuredGrid'], PointCellDataSelection):
723 """XML UnstructuredGrid Reader for .vtu files.
724
725 Wraps :vtk:`vtkXMLUnstructuredGridReader`.
726
727 Examples
728 --------
729 >>> import pyvista as pv
730 >>> from pyvista import examples
731 >>> from pathlib import Path
732 >>> filename = examples.download_notch_displacement(load=False)
733 >>> Path(filename).name
734 'notch_disp.vtu'
735 >>> reader = pv.get_reader(filename)
736 >>> mesh = reader.read()
737 >>> mesh.plot(
738 ... scalars='Nodal Displacement',
739 ... component=0,
740 ... cpos='xy',
741 ... show_scalar_bar=False,
742 ... )
743
744 """
745
746 _vtk_module_name = 'vtkIOXML'
747 _vtk_class_name = 'vtkXMLUnstructuredGridReader'
748
749
750 class XMLPUnstructuredGridReader(BaseReader['UnstructuredGrid'], PointCellDataSelection):
751 """Parallel XML UnstructuredGrid Reader for .pvtu files.
752
753 Wraps :vtk:`vtkXMLPUnstructuredGridReader`.
754
755 """
756
757 _vtk_module_name = 'vtkIOXML'
758 _vtk_class_name = 'vtkXMLPUnstructuredGridReader'
759
760
761 class XMLPolyDataReader(BaseReader['PolyData'], PointCellDataSelection):
762 """XML PolyData Reader for .vtp files.
763
764 Wraps :vtk:`vtkXMLPolyDataReader`.
765
766 Examples
767 --------
768 >>> import pyvista as pv
769 >>> from pyvista import examples
770 >>> from pathlib import Path
771 >>> filename = examples.download_cow_head(load=False)
772 >>> Path(filename).name
773 'cowHead.vtp'
774 >>> reader = pv.get_reader(filename)
775 >>> mesh = reader.read()
776 >>> cpos = pv.CameraPosition(
777 ... position=(12, 3.5, -4.5), focal_point=(4.5, 1.6, 0), viewup=(0, 1, 0.3)
778 ... )
779 >>> mesh.plot(
780 ... cpos=cpos,
781 ... clim=[0, 100],
782 ... show_scalar_bar=False,
783 ... )
784
785 """
786
787 _vtk_module_name = 'vtkIOXML'
788 _vtk_class_name = 'vtkXMLPolyDataReader'
789
790
791 class XMLStructuredGridReader(BaseReader['StructuredGrid'], PointCellDataSelection):
792 """XML StructuredGrid Reader for .vts files.
793
794 Wraps :vtk:`vtkXMLStructuredGridReader`.
795
796 Examples
797 --------
798 >>> import pyvista as pv
799 >>> from pyvista import examples
800 >>> from pathlib import Path
801 >>> filename = examples.download_structured_grid(load=False)
802 >>> Path(filename).name
803 'StructuredGrid.vts'
804 >>> reader = pv.get_reader(filename)
805 >>> mesh = reader.read()
806 >>> mesh.plot(style='wireframe', line_width=4, show_scalar_bar=False)
807
808 """
809
810 _vtk_module_name = 'vtkIOXML'
811 _vtk_class_name = 'vtkXMLStructuredGridReader'
812
813
814 class XMLMultiBlockDataReader(BaseReader['MultiBlock'], PointCellDataSelection):
815 """XML MultiBlock Data Reader for .vtm or .vtmb files.
816
817 Wraps :vtk:`vtkXMLMultiBlockDataReader`.
818
819 """
820
821 _vtk_module_name = 'vtkIOXML'
822 _vtk_class_name = 'vtkXMLMultiBlockDataReader'
823
824
825 class EnSightReader(BaseReader['MultiBlock'], PointCellDataSelection, TimeReader):
826 """EnSight Reader for .case files.
827
828 Wraps :vtk:`vtkGenericEnSightReader`.
829
830 Examples
831 --------
832 >>> import pyvista as pv
833 >>> from pyvista import examples
834 >>> from pathlib import Path
835 >>> filename = examples.download_cylinder_crossflow(load=False)
836 >>> Path(filename).name
837 'cylinder_Re35.case'
838 >>> reader = pv.get_reader(filename)
839 >>> mesh = reader.read()
840 >>> mesh.plot(
841 ... scalars='velocity',
842 ... component=1,
843 ... clim=[-20, 20],
844 ... cpos='xy',
845 ... cmap='RdBu',
846 ... show_scalar_bar=False,
847 ... )
848
849 """
850
851 _vtk_module_name = 'vtkIOEnSight'
852 _vtk_class_name = 'vtkGenericEnSightReader'
853
854 def _set_filename(self, filename) -> None:
855 """Set filename and update reader."""
856 # Private method since changing file type requires a
857 # different subclass.
858 self._filename = filename
859 self.reader.SetCaseFileName(filename)
860 self._update_information()
861 self._active_time_set = 0
862
863 @property
864 def number_time_points(self): # noqa: D102
865 item = self.reader.GetTimeSets().GetItem(self.active_time_set)
866 if item is None:
867 return 0
868 return (
869 item.GetSize()
870 if pv.vtk_version_info < (9, 6, 99) # < (9, 7, 0)
871 else item.GetCapacity()
872 )
873
874 def time_point_value(self, time_point): # noqa: D102
875 return self.reader.GetTimeSets().GetItem(self.active_time_set).GetValue(time_point)
876
877 @property
878 def active_time_value(self): # noqa: D102
879 return self.reader.GetTimeValue()
880
881 def set_active_time_value(self, time_value): # noqa: D102
882 if time_value not in self.time_values:
883 msg = f'Not a valid time {time_value} from available time values: {self.time_values}'
884 raise ValueError(msg)
885 self.reader.SetTimeValue(time_value)
886
887 def set_active_time_point(self, time_point) -> None: # noqa: D102
888 self.reader.SetTimeValue(self.time_point_value(time_point))
889
890 @property
891 def active_time_set(self) -> int:
892 """Return the index of the active time set of the reader.
893
894 Returns
895 -------
896 int
897 Index of the active time set.
898
899 """
900 return self._active_time_set
901
902 def set_active_time_set(self, time_set):
903 """Set the active time set by index.
904
905 Parameters
906 ----------
907 time_set : int
908 Index of the desired time set.
909
910 Raises
911 ------
912 IndexError
913 If the desired time set does not exist.
914
915 """
916 number_time_sets = self.reader.GetTimeSets().GetNumberOfItems()
917 if time_set in range(number_time_sets):
918 self._active_time_set = time_set
919 else:
920 msg = f'Time set index {time_set} not in {range(number_time_sets)}'
921 raise IndexError(msg)
922
923
924 class OpenFOAMReader(BaseReader['MultiBlock'], PointCellDataSelection, TimeReader):
925 """OpenFOAM Reader for .foam files.
926
927 By default, pyvista enables all patch arrays. This is a deviation
928 from the vtk default.
929
930 Wraps :vtk:`vtkOpenFOAMReader`.
931
932 """
933
934 _vtk_module_name = 'vtkIOGeometry'
935 _vtk_class_name = 'vtkOpenFOAMReader'
936
937 def _set_defaults_post(self) -> None:
938 self.enable_all_patch_arrays()
939
940 @property
941 def number_time_points(self): # noqa: D102
942 return self.reader.GetTimeValues().GetNumberOfValues()
943
944 def time_point_value(self, time_point): # noqa: D102
945 return self.reader.GetTimeValues().GetValue(time_point)
946
947 @property
948 def active_time_value(self): # noqa: D102
949 try:
950 value = self.reader.GetTimeValue()
951 except AttributeError as err: # pragma: no cover
952 msg = 'Inspecting active time value only supported for vtk versions >9.1.0'
953 raise AttributeError(msg) from err
954 return value
955
956 def set_active_time_value(self, time_value): # noqa: D102
957 if time_value not in self.time_values:
958 msg = f'Not a valid time {time_value} from available time values: {self.time_values}'
959 raise ValueError(msg)
960 self.reader.UpdateTimeStep(time_value)
961
962 def set_active_time_point(self, time_point) -> None: # noqa: D102
963 self.reader.UpdateTimeStep(self.time_point_value(time_point))
964
965 @property
966 def decompose_polyhedra(self):
967 """Whether polyhedra are to be decomposed when read.
968
969 .. warning::
970 Support for polyhedral decomposition has been deprecated
971 deprecated in VTK 9.3 and has been removed prior to VTK 9.4
972
973 Returns
974 -------
975 bool
976 If ``True``, decompose polyhedra into tetrahedra and pyramids.
977
978 """
979 return bool(self.reader.GetDecomposePolyhedra())
980
981 @decompose_polyhedra.setter
982 def decompose_polyhedra(self, value) -> None:
983 self.reader.SetDecomposePolyhedra(value)
984
985 @property
986 def skip_zero_time(self):
987 """Indicate whether or not to ignore the '/0' time directory.
988
989 Returns
990 -------
991 bool
992 If ``True``, ignore the '/0' time directory.
993
994 Examples
995 --------
996 >>> import pyvista as pv
997 >>> from pyvista import examples
998 >>> filename = examples.download_cavity(load=False)
999 >>> reader = pv.OpenFOAMReader(filename)
1000 >>> reader.skip_zero_time = False
1001 >>> reader.skip_zero_time
1002 False
1003
1004 """
1005 return bool(self.reader.GetSkipZeroTime())
1006
1007 @skip_zero_time.setter
1008 def skip_zero_time(self, value) -> None:
1009 self.reader.SetSkipZeroTime(value)
1010 self._update_information()
1011 self.reader.SetRefresh()
1012
1013 @property
1014 def cell_to_point_creation(self):
1015 """Whether cell data is translated to point data when read.
1016
1017 Returns
1018 -------
1019 bool
1020 If ``True``, translate cell data to point data.
1021
1022 Warnings
1023 --------
1024 When ``True``, cell and point data arrays will have
1025 duplicate names.
1026
1027 Examples
1028 --------
1029 >>> import pyvista as pv
1030 >>> from pyvista import examples
1031 >>> filename = examples.download_cavity(load=False)
1032 >>> reader = pv.OpenFOAMReader(filename)
1033 >>> reader.cell_to_point_creation = False
1034 >>> reader.cell_to_point_creation
1035 False
1036
1037 """
1038 return bool(self.reader.GetCreateCellToPoint())
1039
1040 @cell_to_point_creation.setter
1041 def cell_to_point_creation(self, value) -> None:
1042 self.reader.SetCreateCellToPoint(value)
1043
1044 @property
1045 def number_patch_arrays(self):
1046 """Return number of patch arrays in dataset.
1047
1048 Returns
1049 -------
1050 int
1051
1052 Examples
1053 --------
1054 >>> import pyvista as pv
1055 >>> from pyvista import examples
1056 >>> filename = examples.download_cavity(load=False)
1057 >>> reader = pv.OpenFOAMReader(filename)
1058 >>> reader.number_patch_arrays
1059 4
1060
1061 """
1062 return self.reader.GetNumberOfPatchArrays()
1063
1064 @property
1065 def patch_array_names(self):
1066 """Names of patch arrays in a list.
1067
1068 Returns
1069 -------
1070 list[str]
1071
1072 Examples
1073 --------
1074 >>> import pyvista as pv
1075 >>> from pyvista import examples
1076 >>> filename = examples.download_cavity(load=False)
1077 >>> reader = pv.OpenFOAMReader(filename)
1078 >>> reader.patch_array_names
1079 ['internalMesh', 'patch/movingWall', 'patch/fixedWalls', 'patch/frontAndBack']
1080
1081 """
1082 return [self.reader.GetPatchArrayName(i) for i in range(self.number_patch_arrays)]
1083
1084 def enable_patch_array(self, name) -> None:
1085 """Enable reading of patch array.
1086
1087 Parameters
1088 ----------
1089 name : str
1090 Which patch array to enable.
1091
1092 Examples
1093 --------
1094 >>> import pyvista as pv
1095 >>> from pyvista import examples
1096 >>> filename = examples.download_cavity(load=False)
1097 >>> reader = pv.OpenFOAMReader(filename)
1098 >>> reader.enable_patch_array('patch/movingWall')
1099 >>> reader.patch_array_status('patch/movingWall')
1100 True
1101
1102 """
1103 self.reader.SetPatchArrayStatus(name, 1)
1104
1105 def disable_patch_array(self, name) -> None:
1106 """Disable reading of patch array.
1107
1108 Parameters
1109 ----------
1110 name : str
1111 Which patch array to disable.
1112
1113 Examples
1114 --------
1115 >>> import pyvista as pv
1116 >>> from pyvista import examples
1117 >>> filename = examples.download_cavity(load=False)
1118 >>> reader = pv.OpenFOAMReader(filename)
1119 >>> reader.disable_patch_array('internalMesh')
1120 >>> reader.patch_array_status('internalMesh')
1121 False
1122
1123 """
1124 self.reader.SetPatchArrayStatus(name, 0)
1125
1126 def patch_array_status(self, name):
1127 """Return status of reading patch array.
1128
1129 Parameters
1130 ----------
1131 name : str
1132 Which patch array to report status.
1133
1134 Returns
1135 -------
1136 bool
1137 Whether the patch with the given name is to be read.
1138
1139 Examples
1140 --------
1141 >>> import pyvista as pv
1142 >>> from pyvista import examples
1143 >>> filename = examples.download_cavity(load=False)
1144 >>> reader = pv.OpenFOAMReader(filename)
1145 >>> reader.enable_patch_array('patch/movingWall')
1146 >>> reader.patch_array_status('patch/movingWall')
1147 True
1148
1149 """
1150 return bool(self.reader.GetPatchArrayStatus(name))
1151
1152 def enable_all_patch_arrays(self) -> None:
1153 """Enable reading of all patch arrays.
1154
1155 Examples
1156 --------
1157 >>> import pyvista as pv
1158 >>> from pyvista import examples
1159 >>> filename = examples.download_cavity(load=False)
1160 >>> reader = pv.OpenFOAMReader(filename)
1161 >>> reader.enable_all_patch_arrays()
1162 >>> assert reader.patch_array_status('patch/movingWall')
1163 >>> assert reader.patch_array_status('patch/fixedWalls')
1164
1165 """
1166 self.reader.EnableAllPatchArrays()
1167
1168 def disable_all_patch_arrays(self) -> None:
1169 """Disable reading of all patch arrays.
1170
1171 Examples
1172 --------
1173 >>> import pyvista as pv
1174 >>> from pyvista import examples
1175 >>> filename = examples.download_cavity(load=False)
1176 >>> reader = pv.OpenFOAMReader(filename)
1177 >>> reader.disable_all_patch_arrays()
1178 >>> assert not reader.patch_array_status('patch.movingWall')
1179 >>> assert not reader.patch_array_status('internalMesh')
1180
1181 """
1182 self.reader.DisableAllPatchArrays()
1183
1184 @property
1185 def all_patch_arrays_status(self):
1186 """Status of reading all patch arrays.
1187
1188 Returns
1189 -------
1190 dict[str, bool]
1191 dict key is the patch name and the value is whether it will be read.
1192
1193 Examples
1194 --------
1195 >>> import pyvista as pv
1196 >>> from pyvista import examples
1197 >>> filename = examples.download_cavity(load=False)
1198 >>> reader = pv.OpenFOAMReader(filename)
1199 >>> reader.all_patch_arrays_status # doctest: +NORMALIZE_WHITESPACE
1200 {'internalMesh': True, 'patch/movingWall': True, 'patch/fixedWalls': True,
1201 'patch/frontAndBack': True}
1202
1203 """
1204 return {name: self.patch_array_status(name) for name in self.patch_array_names}
1205
1206
1207 class POpenFOAMReader(OpenFOAMReader):
1208 """Parallel OpenFOAM Reader for .foam files.
1209
1210 Wraps :vtk:`vtkPOpenFOAMReader`.
1211
1212 Can read parallel-decomposed mesh information and time dependent data.
1213 This reader can be used for serial generated data,
1214 parallel reconstructed data, and decomposed data.
1215 """
1216
1217 _vtk_module_name = 'vtkIOParallel'
1218 _vtk_class_name = 'vtkPOpenFOAMReader'
1219
1220 @property
1221 def case_type(self):
1222 """Indicate whether decomposed mesh or reconstructed mesh should be read.
1223
1224 Returns
1225 -------
1226 str
1227 If ``'reconstructed'``, reconstructed mesh should be read.
1228 If ``'decomposed'``, decomposed mesh should be read.
1229
1230 Raises
1231 ------
1232 ValueError
1233 If the value is not in ['reconstructed', 'decomposed']
1234
1235 Examples
1236 --------
1237 >>> import pyvista as pv
1238 >>> from pyvista import examples
1239 >>> filename = examples.download_cavity(load=False)
1240 >>> reader = pv.POpenFOAMReader(filename)
1241 >>> reader.case_type = 'reconstructed'
1242 >>> reader.case_type
1243 'reconstructed'
1244
1245 """
1246 return 'reconstructed' if self.reader.GetCaseType() else 'decomposed'
1247
1248 @case_type.setter
1249 def case_type(self, value):
1250 if value == 'reconstructed':
1251 self.reader.SetCaseType(1)
1252 elif value == 'decomposed':
1253 self.reader.SetCaseType(0)
1254 else:
1255 msg = f"Unknown case type '{value}'."
1256 raise ValueError(msg)
1257
1258 self._update_information()
1259
1260
1261 class PLYReader(BaseReader['PolyData']):
1262 """PLY Reader for reading .ply files.
1263
1264 Wraps :vtk:`vtkPLYReader`.
1265
1266 Examples
1267 --------
1268 >>> import pyvista as pv
1269 >>> from pyvista import examples
1270 >>> from pathlib import Path
1271 >>> filename = examples.download_lobster(load=False)
1272 >>> Path(filename).name
1273 'lobster.ply'
1274 >>> reader = pv.get_reader(filename)
1275 >>> mesh = reader.read()
1276 >>> mesh.plot()
1277
1278 """
1279
1280 _vtk_module_name = 'vtkIOPLY'
1281 _vtk_class_name = 'vtkPLYReader'
1282
1283
1284 class OBJReader(BaseReader['PolyData']):
1285 """OBJ Reader for reading .obj files.
1286
1287 Wraps :vtk:`vtkOBJReader`.
1288
1289 Examples
1290 --------
1291 >>> import pyvista as pv
1292 >>> from pyvista import examples
1293 >>> from pathlib import Path
1294 >>> filename = examples.download_trumpet(load=False)
1295 >>> Path(filename).name
1296 'trumpet.obj'
1297 >>> reader = pv.get_reader(filename)
1298 >>> mesh = reader.read()
1299 >>> mesh.plot(cpos='yz', show_scalar_bar=False)
1300
1301 """
1302
1303 _vtk_module_name = 'vtkIOGeometry'
1304 _vtk_class_name = 'vtkOBJReader'
1305
1306
1307 class STLReader(BaseReader['PolyData']):
1308 """STL Reader for .stl files.
1309
1310 Wraps :vtk:`vtkSTLReader`.
1311
1312 Examples
1313 --------
1314 >>> import pyvista as pv
1315 >>> from pyvista import examples
1316 >>> from pathlib import Path
1317 >>> filename = examples.download_cad_model(load=False)
1318 >>> Path(filename).name
1319 '42400-IDGH.stl'
1320 >>> reader = pv.get_reader(filename)
1321 >>> mesh = reader.read()
1322 >>> mesh.plot()
1323
1324 """
1325
1326 _vtk_module_name = 'vtkIOGeometry'
1327 _vtk_class_name = 'vtkSTLReader'
1328
1329
1330 class TecplotReader(BaseReader['MultiBlock']):
1331 """Tecplot Reader for ascii .dat files.
1332
1333 Wraps :vtk:`vtkTecplotReader`.
1334
1335 Examples
1336 --------
1337 >>> import pyvista as pv
1338 >>> from pyvista import examples
1339 >>> filename = examples.download_tecplot_ascii(load=False)
1340 >>> reader = pv.get_reader(filename)
1341 >>> mesh = reader.read()
1342 >>> mesh[0].plot()
1343
1344 """
1345
1346 _vtk_module_name = 'vtkIOGeometry'
1347 _vtk_class_name = 'vtkTecplotReader'
1348
1349
1350 class VTKDataSetReader(BaseReader['DataSet']):
1351 """VTK Data Set Reader for .vtk files.
1352
1353 Wraps :vtk:`vtkDataSetReader`.
1354
1355 Notes
1356 -----
1357 This reader calls ``ReadAllScalarsOn``, ``ReadAllColorScalarsOn``,
1358 ``ReadAllNormalsOn``, ``ReadAllTCoordsOn``, ``ReadAllVectorsOn``,
1359 and ``ReadAllFieldsOn`` on the underlying :vtk:`vtkDataSetReader`.
1360
1361 Examples
1362 --------
1363 >>> import pyvista as pv
1364 >>> from pyvista import examples
1365 >>> from pathlib import Path
1366 >>> filename = examples.download_brain(load=False)
1367 >>> Path(filename).name
1368 'brain.vtk'
1369 >>> reader = pv.get_reader(filename)
1370 >>> mesh = reader.read()
1371 >>> sliced_mesh = mesh.slice('x')
1372 >>> sliced_mesh.plot(cpos='yz', show_scalar_bar=False)
1373
1374 """
1375
1376 _vtk_module_name = 'vtkIOLegacy'
1377 _vtk_class_name = 'vtkDataSetReader'
1378 _output_types = get_args(_legacy_dataset_types)
1379
1380 def _set_defaults_post(self) -> None:
1381 self.reader.ReadAllScalarsOn()
1382 self.reader.ReadAllColorScalarsOn()
1383 self.reader.ReadAllNormalsOn()
1384 self.reader.ReadAllTCoordsOn()
1385 self.reader.ReadAllVectorsOn()
1386 self.reader.ReadAllFieldsOn()
1387 self.reader.ReadAllTensorsOn()
1388
1389
1390 class VTKPDataSetReader(BaseReader['DataSet']):
1391 """Parallel VTK Data Set Reader for .pvtk files.
1392
1393 Wraps :vtk:`vtkPDataSetReader`.
1394
1395 """
1396
1397 _vtk_module_name = 'vtkIOParallel'
1398 _vtk_class_name = 'vtkPDataSetReader'
1399 _output_types = get_args(_legacy_dataset_types)
1400
1401
1402 class BYUReader(BaseReader['PolyData']):
1403 """BYU Reader for .g files.
1404
1405 Wraps :vtk:`vtkBYUReader`.
1406
1407 Examples
1408 --------
1409 >>> import pyvista as pv
1410 >>> from pyvista import examples
1411 >>> from pathlib import Path
1412 >>> filename = examples.download_teapot(load=False)
1413 >>> Path(filename).name
1414 'teapot.g'
1415 >>> reader = pv.get_reader(filename)
1416 >>> mesh = reader.read()
1417 >>> mesh.plot(cpos='xy', show_scalar_bar=False)
1418
1419 """
1420
1421 _vtk_module_name = 'vtkIOGeometry'
1422 _vtk_class_name = 'vtkBYUReader'
1423
1424
1425 class FacetReader(BaseReader['PolyData']):
1426 """Facet Reader for .facet files.
1427
1428 Wraps :vtk:`vtkFacetReader`.
1429
1430 Examples
1431 --------
1432 >>> import pyvista as pv
1433 >>> from pyvista import examples
1434 >>> from pathlib import Path
1435 >>> filename = examples.download_clown(load=False)
1436 >>> Path(filename).name
1437 'clown.facet'
1438 >>> reader = pv.get_reader(filename)
1439 >>> mesh = reader.read()
1440 >>> mesh.plot(color='red')
1441
1442 """
1443
1444 _vtk_module_name = 'vtkFiltersHybrid'
1445 _vtk_class_name = 'vtkFacetReader'
1446
1447
1448 class Plot3DMetaReader(BaseReader['MultiBlock']):
1449 """Plot3DMeta Reader for .p3d files.
1450
1451 Wraps :vtk:`vtkPlot3DMetaReader`.
1452
1453 """
1454
1455 _vtk_module_name = 'vtkIOParallel'
1456 _vtk_class_name = 'vtkPlot3DMetaReader'
1457
1458
1459 class Plot3DFunctionEnum(enum.IntEnum):
1460 """An enumeration for the functions used in :class:`MultiBlockPlot3DReader`."""
1461
1462 DENSITY = 100
1463 PRESSURE = 110
1464 PRESSURE_COEFFICIENT = 111
1465 MACH = 112
1466 SPEED_OF_SOUND = 113
1467 TEMPERATURE = 120
1468 ENTHALPY = 130
1469 INTERNAL_ENERGY = 140
1470 KINETIC_ENERGY = 144
1471 VELOCITY_MAGNITUDE = 153
1472 STAGNATION_ENERGY = 163
1473 ENTROPY = 170
1474 SWIRL = 184
1475 VELOCITY = 200
1476 VORTICITY = 201
1477 MOMENTUM = 202
1478 PRESSURE_GRADIENT = 210
1479 STRAIN_RATE = 212
1480 VORTICITY_MAGNITUDE = 211
1481
1482
1483 class MultiBlockPlot3DReader(BaseReader['MultiBlock']):
1484 """MultiBlock Plot3D Reader.
1485
1486 Wraps :vtk:`vtkMultiBlockPLOT3DReader`.
1487
1488 The methods :meth:`add_function()` and :meth:`remove_function()` accept values from
1489 :class:`Plot3DFunctionEnum`. For convenience, the values of that enumeration are available as
1490 class variables, as shown below.
1491
1492 - ``MultiBlockPlot3DReader.DENSITY = Plot3DFunctionEnum.DENSITY``
1493 - ``MultiBlockPlot3DReader.PRESSURE = Plot3DFunctionEnum.PRESSURE``
1494 - ``MultiBlockPlot3DReader.PRESSURE_COEFFICIENT = Plot3DFunctionEnum.PRESSURE_COEFFICIENT``
1495 - ``MultiBlockPlot3DReader.MACH = Plot3DFunctionEnum.MACH``
1496 - ``MultiBlockPlot3DReader.SPEED_OF_SOUND = Plot3DFunctionEnum.SPEED_OF_SOUND``
1497 - ``MultiBlockPlot3DReader.TEMPERATURE = Plot3DFunctionEnum.TEMPERATURE``
1498 - ``MultiBlockPlot3DReader.ENTHALPY = Plot3DFunctionEnum.ENTHALPY``
1499 - ``MultiBlockPlot3DReader.INTERNAL_ENERGY = Plot3DFunctionEnum.INTERNAL_ENERGY``
1500 - ``MultiBlockPlot3DReader.KINETIC_ENERGY = Plot3DFunctionEnum.KINETIC_ENERGY``
1501 - ``MultiBlockPlot3DReader.VELOCITY_MAGNITUDE = Plot3DFunctionEnum.VELOCITY_MAGNITUDE``
1502 - ``MultiBlockPlot3DReader.STAGNATION_ENERGY = Plot3DFunctionEnum.STAGNATION_ENERGY``
1503 - ``MultiBlockPlot3DReader.ENTROPY = Plot3DFunctionEnum.ENTROPY``
1504 - ``MultiBlockPlot3DReader.SWIRL = Plot3DFunctionEnum.SWIRL``
1505 - ``MultiBlockPlot3DReader.VELOCITY = Plot3DFunctionEnum.VELOCITY``
1506 - ``MultiBlockPlot3DReader.VORTICITY = Plot3DFunctionEnum.VORTICITY``
1507 - ``MultiBlockPlot3DReader.MOMENTUM = Plot3DFunctionEnum.MOMENTUM``
1508 - ``MultiBlockPlot3DReader.PRESSURE_GRADIENT = Plot3DFunctionEnum.PRESSURE_GRADIENT``
1509 - ``MultiBlockPlot3DReader.STRAIN_RATE = Plot3DFunctionEnum.STRAIN_RATE``
1510 - ``MultiBlockPlot3DReader.VORTICITY_MAGNITUDE = Plot3DFunctionEnum.VORTICITY_MAGNITUDE``
1511 """
1512
1513 _vtk_module_name = 'vtkIOParallel'
1514 _vtk_class_name = 'vtkMultiBlockPLOT3DReader'
1515
1516 # pull in function name enum values as class constants
1517 DENSITY = Plot3DFunctionEnum.DENSITY
1518 PRESSURE = Plot3DFunctionEnum.PRESSURE
1519 PRESSURE_COEFFICIENT = Plot3DFunctionEnum.PRESSURE_COEFFICIENT
1520 MACH = Plot3DFunctionEnum.MACH
1521 SPEED_OF_SOUND = Plot3DFunctionEnum.SPEED_OF_SOUND
1522 TEMPERATURE = Plot3DFunctionEnum.TEMPERATURE
1523 ENTHALPY = Plot3DFunctionEnum.ENTHALPY
1524 INTERNAL_ENERGY = Plot3DFunctionEnum.INTERNAL_ENERGY
1525 KINETIC_ENERGY = Plot3DFunctionEnum.KINETIC_ENERGY
1526 VELOCITY_MAGNITUDE = Plot3DFunctionEnum.VELOCITY_MAGNITUDE
1527 STAGNATION_ENERGY = Plot3DFunctionEnum.STAGNATION_ENERGY
1528 ENTROPY = Plot3DFunctionEnum.ENTROPY
1529 SWIRL = Plot3DFunctionEnum.SWIRL
1530 VELOCITY = Plot3DFunctionEnum.VELOCITY
1531 VORTICITY = Plot3DFunctionEnum.VORTICITY
1532 MOMENTUM = Plot3DFunctionEnum.MOMENTUM
1533 PRESSURE_GRADIENT = Plot3DFunctionEnum.PRESSURE_GRADIENT
1534 STRAIN_RATE = Plot3DFunctionEnum.STRAIN_RATE
1535 VORTICITY_MAGNITUDE = Plot3DFunctionEnum.VORTICITY_MAGNITUDE
1536
1537 def _set_defaults(self) -> None:
1538 self.auto_detect_format = True
1539
1540 def add_q_files(self, files) -> None:
1541 """Add q file(s).
1542
1543 Parameters
1544 ----------
1545 files : str | sequence[str]
1546 Solution file or files to add.
1547
1548 """
1549 # files may be a list or a single filename
1550 if files and isinstance(files, (str, Path)):
1551 files = [files]
1552 files = [_process_filename(f) for f in files]
1553
1554 # AddFileName supports reading multiple q files
1555 for q_filename in files:
1556 self.reader.AddFileName(q_filename)
1557
1558 @property
1559 def auto_detect_format(self):
1560 """Whether to try to automatically detect format such as byte order, etc."""
1561 return bool(self.reader.GetAutoDetectFormat())
1562
1563 @auto_detect_format.setter
1564 def auto_detect_format(self, value) -> None:
1565 self.reader.SetAutoDetectFormat(value)
1566
1567 def add_function(self, value: int | Plot3DFunctionEnum) -> None:
1568 """Specify additional functions to compute.
1569
1570 The available functions are enumerated in :class:`Plot3DFunctionEnum`. The members of this
1571 enumeration are most easily accessed by their aliases as class variables.
1572
1573 Multiple functions may be requested by calling this method multiple times.
1574
1575 Parameters
1576 ----------
1577 value : int | Plot3DFunctionEnum
1578 The function to add.
1579
1580 Examples
1581 --------
1582 >>> import pyvista as pv
1583 >>> from pyvista import examples
1584 >>> filename = examples.download_file('multi-bin.xyz')
1585 >>> reader = pv.reader.MultiBlockPlot3DReader(filename)
1586 >>> reader.add_function(112) # add a function by its integer value
1587 >>> reader.add_function(
1588 ... reader.PRESSURE_COEFFICIENT
1589 ... ) # add a function by enumeration via class variable alias
1590
1591 """
1592 if isinstance(value, enum.Enum):
1593 value = value.value
1594 self.reader.AddFunction(value)
1595
1596 def remove_function(self, value: int | Plot3DFunctionEnum) -> None:
1597 """Remove one function from list of functions to compute.
1598
1599 For details on the types of accepted values, see :meth:``add_function``.
1600
1601 Parameters
1602 ----------
1603 value : int | Plot3DFunctionEnum
1604 The function to remove.
1605
1606 """
1607 if isinstance(value, enum.Enum):
1608 value = value.value
1609 self.reader.RemoveFunction(value)
1610
1611 def remove_all_functions(self) -> None:
1612 """Remove all functions from list of functions to compute."""
1613 self.reader.RemoveAllFunctions()
1614
1615 @property
1616 def preserve_intermediate_functions(self):
1617 """When ``True`` (default), intermediate computed quantities will be preserved.
1618
1619 For example, if ``VelocityMagnitude`` is enabled, but not ``Velocity``, the reader still
1620 needs to compute ``Velocity``. If `preserve_intermediate_functions` is ``False``, then the
1621 output will not have ``Velocity`` array, only the requested ``VelocityMagnitude``.
1622
1623 This is useful to avoid using up memory for arrays that are not relevant for the analysis.
1624 """
1625 return self.reader.GetPreserveIntermediateFunctions()
1626
1627 @preserve_intermediate_functions.setter
1628 def preserve_intermediate_functions(self, val) -> None:
1629 self.reader.SetPreserveIntermediateFunctions(val)
1630
1631 @property
1632 def gamma(self):
1633 """Ratio of specific heats."""
1634 return self.reader.GetGamma()
1635
1636 @gamma.setter
1637 def gamma(self, val) -> None:
1638 self.reader.SetGamma(val)
1639
1640 @property
1641 def r_gas_constant(self):
1642 """Gas constant."""
1643 return self.reader.GetR()
1644
1645 @r_gas_constant.setter
1646 def r_gas_constant(self, val) -> None:
1647 self.reader.SetR(val)
1648
1649
1650 class CGNSReader(BaseReader['MultiBlock'], PointCellDataSelection):
1651 """CGNS Reader for .cgns files.
1652
1653 Creates a multi-block dataset and reads unstructured grids and structured
1654 meshes from binary files stored in CGNS file format, with data stored at
1655 the nodes, cells or faces.
1656
1657 By default, all point and cell arrays are loaded as well as the boundary
1658 patch. This varies from VTK's defaults. For more details, see
1659 :vtk:`vtkCGNSReader`.
1660
1661 Examples
1662 --------
1663 Load a CGNS file. All arrays are loaded by default.
1664
1665 >>> import pyvista as pv
1666 >>> from pyvista import examples
1667 >>> filename = examples.download_cgns_multi(load=False)
1668 >>> reader = pv.CGNSReader(filename)
1669 >>> reader.load_boundary_patch = False
1670 >>> ds = reader.read()
1671 >>> ds[0][0].cell_data
1672 pyvista DataSetAttributes
1673 Association : CELL
1674 Active Scalars : None
1675 Active Vectors : Momentum
1676 Active Texture : None
1677 Active Normals : None
1678 Contains arrays :
1679 Density float64 (2928,)
1680 Momentum float64 (2928, 3) VECTORS
1681 EnergyStagnationDensity float64 (2928,)
1682 ViscosityEddy float64 (2928,)
1683 TurbulentDistance float64 (2928,)
1684 TurbulentSANuTilde float64 (2928,)
1685
1686 """
1687
1688 _vtk_module_name = 'vtkIOCGNSReader'
1689 _vtk_class_name = 'vtkCGNSReader'
1690
1691 def _set_defaults_post(self) -> None:
1692 self.enable_all_point_arrays()
1693 self.enable_all_cell_arrays()
1694 self.load_boundary_patch = True
1695
1696 @property
1697 def distribute_blocks(self) -> bool:
1698 """Distribute each block in each zone across ranks.
1699
1700 To make the reader disregard the piece request and read all blocks in the
1701 zone, set this to ``False``. The default is ``True``.
1702
1703 Returns
1704 -------
1705 bool
1706 If ``True``, distribute each block in each zone across ranks.
1707
1708 Examples
1709 --------
1710 Disable distributing blocks.
1711
1712 >>> import pyvista as pv
1713 >>> from pyvista import examples
1714 >>> filename = examples.download_cgns_multi(load=False)
1715 >>> reader = pv.CGNSReader(filename)
1716 >>> reader.distribute_blocks = False
1717 >>> reader.distribute_blocks
1718 False
1719
1720 """
1721 return bool(self._reader.GetDistributeBlocks())
1722
1723 @distribute_blocks.setter
1724 def distribute_blocks(self, value: str) -> None:
1725 self._reader.SetDistributeBlocks(value)
1726
1727 def base_array_status(self, name: str) -> bool:
1728 """Get status of base array with name.
1729
1730 Parameters
1731 ----------
1732 name : str
1733 Base array name.
1734
1735 Returns
1736 -------
1737 bool
1738 Whether reading the base array is enabled.
1739
1740 """
1741 return bool(self.reader.GetBaseArrayStatus(name))
1742
1743 @property
1744 def base_array_names(self):
1745 """Return the list of all base array names.
1746
1747 Returns
1748 -------
1749 list[int]
1750
1751 """
1752 return [self.reader.GetBaseArrayName(i) for i in range(self.number_base_arrays)]
1753
1754 @property
1755 def number_base_arrays(self) -> int:
1756 """Return the number of base arrays.
1757
1758 Returns
1759 -------
1760 int
1761
1762 """
1763 return self.reader.GetNumberOfBaseArrays()
1764
1765 def enable_all_bases(self) -> None:
1766 """Enable reading all bases.
1767
1768 By default only the 0th base is read.
1769
1770 Examples
1771 --------
1772 Read all bases.
1773
1774 >>> import pyvista as pv
1775 >>> from pyvista import examples
1776 >>> filename = examples.download_cgns_multi(load=False)
1777 >>> reader = pv.CGNSReader(filename)
1778 >>> reader.enable_all_bases()
1779
1780 """
1781 self._reader.EnableAllBases()
1782
1783 def disable_all_bases(self) -> None:
1784 """Disable reading all bases.
1785
1786 By default only the 0th base is read.
1787
1788 Examples
1789 --------
1790 Disable reading all bases.
1791
1792 >>> import pyvista as pv
1793 >>> from pyvista import examples
1794 >>> filename = examples.download_cgns_multi(load=False)
1795 >>> reader = pv.CGNSReader(filename)
1796 >>> reader.disable_all_bases()
1797
1798 """
1799 self._reader.DisableAllBases()
1800
1801 def family_array_status(self, name) -> bool:
1802 """Get status of family array with name.
1803
1804 Parameters
1805 ----------
1806 name : str
1807 Family array name.
1808
1809 Returns
1810 -------
1811 bool
1812 Whether reading the family array is enabled.
1813
1814 """
1815 return bool(self.reader.GetFamilyArrayStatus(name))
1816
1817 @property
1818 def family_array_names(self) -> list[str]:
1819 """Return the list of all family array names.
1820
1821 Returns
1822 -------
1823 list[str]
1824
1825 """
1826 return [self.reader.GetFamilyArrayName(i) for i in range(self.number_family_arrays)]
1827
1828 @property
1829 def number_family_arrays(self) -> int:
1830 """Return the number of face arrays.
1831
1832 Returns
1833 -------
1834 int
1835
1836 """
1837 return self.reader.GetNumberOfFamilyArrays()
1838
1839 def enable_all_families(self) -> None:
1840 """Enable reading all families.
1841
1842 By default only the 0th family is read.
1843
1844 Examples
1845 --------
1846 Read all bases.
1847
1848 >>> import pyvista as pv
1849 >>> from pyvista import examples
1850 >>> filename = examples.download_cgns_multi(load=False)
1851 >>> reader = pv.CGNSReader(filename)
1852 >>> reader.enable_all_families()
1853
1854 """
1855 self._reader.EnableAllFamilies()
1856
1857 def disable_all_families(self) -> None:
1858 """Disable reading all families.
1859
1860 Examples
1861 --------
1862 Disable reading all bases.
1863
1864 >>> import pyvista as pv
1865 >>> from pyvista import examples
1866 >>> filename = examples.download_cgns_multi(load=False)
1867 >>> reader = pv.CGNSReader(filename)
1868 >>> reader.disable_all_families()
1869
1870 """
1871 self._reader.DisableAllFamilies()
1872
1873 @property
1874 def unsteady_pattern(self) -> bool:
1875 """Return or set using an unsteady pattern.
1876
1877 When set to ``True`` (default is ``False``), the reader will try to
1878 determine FlowSolution_t nodes to read with a pattern
1879 matching This can be useful for unsteady solutions when
1880 FlowSolutionPointers are not reliable.
1881
1882 Examples
1883 --------
1884 Set reading the unsteady pattern to ``True``.
1885
1886 >>> import pyvista as pv
1887 >>> from pyvista import examples
1888 >>> filename = examples.download_cgns_multi(load=False)
1889 >>> reader = pv.CGNSReader(filename)
1890 >>> reader.unsteady_pattern = True
1891 >>> reader.unsteady_pattern
1892 True
1893
1894 """
1895 return self._reader.GetUseUnsteadyPattern()
1896
1897 @unsteady_pattern.setter
1898 def unsteady_pattern(self, enabled: bool) -> None:
1899 self._reader.SetUseUnsteadyPattern(bool(enabled))
1900
1901 @property
1902 def vector_3d(self) -> bool:
1903 """Return or set adding an empty dimension to vectors in case of 2D solutions.
1904
1905 Examples
1906 --------
1907 Set adding an empty physical dimension to vectors to ``True``.
1908
1909 >>> import pyvista as pv
1910 >>> from pyvista import examples
1911 >>> filename = examples.download_cgns_multi(load=False)
1912 >>> reader = pv.CGNSReader(filename)
1913 >>> reader.vector_3d = True
1914 >>> reader.vector_3d
1915 True
1916
1917 """
1918 return self._reader.GetUse3DVector()
1919
1920 @vector_3d.setter
1921 def vector_3d(self, enabled: bool) -> None:
1922 self._reader.SetUse3DVector(bool(enabled))
1923
1924 @property
1925 def load_boundary_patch(self) -> bool:
1926 """Return or set loading boundary patches.
1927
1928 Notes
1929 -----
1930 VTK default is ``False``, but PyVista uses ``True``.
1931
1932 Examples
1933 --------
1934 Enable loading boundary patches .
1935
1936 >>> import pyvista as pv
1937 >>> from pyvista import examples
1938 >>> filename = examples.download_cgns_multi(load=False)
1939 >>> reader = pv.CGNSReader(filename)
1940 >>> reader.load_boundary_patch = True
1941 >>> reader.load_boundary_patch
1942 True
1943
1944 """
1945 return self._reader.GetLoadBndPatch()
1946
1947 @load_boundary_patch.setter
1948 def load_boundary_patch(self, enabled: bool) -> None:
1949 self._reader.SetLoadBndPatch(bool(enabled))
1950
1951
1952 class BinaryMarchingCubesReader(BaseReader['PolyData']):
1953 """BinaryMarchingCubes Reader for .tri files.
1954
1955 Wraps :vtk:`vtkMCubesReader`.
1956
1957 Examples
1958 --------
1959 >>> import pyvista as pv
1960 >>> from pyvista import examples
1961 >>> from pathlib import Path
1962 >>> filename = examples.download_pine_roots(load=False)
1963 >>> Path(filename).name
1964 'pine_root.tri'
1965 >>> reader = pv.get_reader(filename)
1966 >>> mesh = reader.read()
1967 >>> mesh.plot(color='brown')
1968
1969 """
1970
1971 _vtk_module_name = 'vtkIOGeometry'
1972 _vtk_class_name = 'vtkMCubesReader'
1973
1974
1975 @dataclass(order=True)
1976 class PVDDataSet(_NoNewAttrMixin):
1977 """Class for storing dataset info from PVD file."""
1978
1979 time: float
1980 part: int
1981 path: str
1982 group: str
1983
1984
1985 class _PVDReader(BaseVTKReader):
1986 """Simulate a VTK reader for PVD files."""
1987
1988 def __init__(self) -> None:
1989 super().__init__()
1990 self._directory: str | None = None
1991 self._datasets: list[PVDDataSet] | None = None
1992 self._active_datasets: list[PVDDataSet] | None = None
1993 self._time_values: list[float] | None = None
1994
1995 def SetFileName(self, filename) -> None:
1996 """Set filename and update reader."""
1997 self._filename = str(filename)
1998 self._directory = str(Path(filename).parent)
1999
2000 def UpdateInformation(self):
2001 """Parse PVD file."""
2002 if self._filename is None:
2003 msg = 'Filename must be set'
2004 raise ValueError(msg)
2005 tree = ET.parse(self._filename)
2006 root = tree.getroot()
2007 dataset_elements = root[0].findall('DataSet')
2008 datasets: list[PVDDataSet] = []
2009 for element in dataset_elements:
2010 element_attrib = element.attrib
2011 datasets.append(
2012 PVDDataSet(
2013 float(element_attrib.get('timestep', 0)),
2014 int(element_attrib.get('part', 0)),
2015 element_attrib['file'],
2016 element_attrib.get('group'), # type: ignore[arg-type]
2017 ),
2018 )
2019
2020 self._datasets = sorted(datasets)
2021 self._time_values = sorted({dataset.time for dataset in self._datasets})
2022 self._time_mapping: dict[float, list[PVDDataSet]] = {
2023 time: [] for time in self._time_values
2024 }
2025 for dataset in self._datasets:
2026 self._time_mapping[dataset.time].append(dataset)
2027 self._SetActiveTime(self._time_values[0])
2028
2029 def Update(self) -> None:
2030 """Read data and store it."""
2031 self._data_object = pv.MultiBlock([reader.read() for reader in self._active_readers])
2032
2033 def _SetActiveTime(self, time_value) -> None:
2034 """Set active time."""
2035 self._active_datasets = self._time_mapping[time_value]
2036 self._active_readers = [
2037 get_reader(Path(self._directory) / dataset.path) # type: ignore[arg-type]
2038 for dataset in self._active_datasets
2039 ]
2040
2041
2042 class PVDReader(BaseReader['MultiBlock'], TimeReader):
2043 """PVD Reader for .pvd files.
2044
2045 Examples
2046 --------
2047 >>> import pyvista as pv
2048 >>> from pyvista import examples
2049 >>> from pathlib import Path
2050 >>> filename = examples.download_wavy(load=False)
2051 >>> Path(filename).name
2052 'wavy.pvd'
2053 >>> reader = pv.get_reader(filename)
2054 >>> reader.time_values
2055 [0.0, 1.0, 2.0, 3.0, ... 12.0, 13.0, 14.0]
2056 >>> reader.set_active_time_point(5)
2057 >>> reader.active_time_value
2058 5.0
2059 >>> mesh = reader.read()[0] # MultiBlock mesh with only 1 block
2060 >>> mesh.plot(scalars='z')
2061
2062 """
2063
2064 _class_reader = _PVDReader
2065
2066 @property
2067 def active_readers(self):
2068 """Return the active readers.
2069
2070 Returns
2071 -------
2072 list[pyvista.BaseReader]
2073
2074 """
2075 return self.reader._active_readers
2076
2077 @property
2078 def datasets(self):
2079 """Return all datasets.
2080
2081 Returns
2082 -------
2083 list[pyvista.PVDDataSet]
2084
2085 """
2086 return self.reader._datasets
2087
2088 @property
2089 def active_datasets(self):
2090 """Return all active datasets.
2091
2092 Returns
2093 -------
2094 list[pyvista.PVDDataSet]
2095
2096 """
2097 return self.reader._active_datasets
2098
2099 @property
2100 def time_values(self): # noqa: D102
2101 return self.reader._time_values
2102
2103 @property
2104 def number_time_points(self): # noqa: D102
2105 return len(self.reader._time_values)
2106
2107 def time_point_value(self, time_point): # noqa: D102
2108 return self.reader._time_values[time_point]
2109
2110 @property
2111 def active_time_value(self): # noqa: D102
2112 # all active datasets have the same time
2113 return self.reader._active_datasets[0].time
2114
2115 def set_active_time_value(self, time_value) -> None: # noqa: D102
2116 self.reader._SetActiveTime(time_value)
2117
2118 def set_active_time_point(self, time_point) -> None: # noqa: D102
2119 self.set_active_time_value(self.time_values[time_point])
2120
2121
2122 class Nek5000Reader(BaseReader['UnstructuredGrid'], PointCellDataSelection, TimeReader):
2123 """Class for reading .nek5000 files produced by Nek5000 and NekRS.
2124
2125 Wraps :vtk:`vtkNek5000Reader`.
2126
2127 .. versionadded:: 0.45.0
2128
2129 .. note::
2130 This reader requires vtk version >=9.3.0.
2131
2132 Examples
2133 --------
2134 >>> import pyvista as pv
2135 >>> from pyvista import examples
2136 >>> filename = examples.download_nek5000(load=False)
2137 >>> reader = pv.get_reader(filename)
2138 >>> mesh = reader.read()
2139 >>> mesh.plot(scalars='Velocity', cpos='xy')
2140
2141 """
2142
2143 _vtk_module_name = 'vtkIOParallel'
2144 _vtk_class_name = 'vtkNek5000Reader'
2145
2146 def __init__(self, path):
2147 # nek5000 reader requires vtk >= 9.3
2148 if pv.vtk_version_info < (9, 3):
2149 msg = 'Nek5000Reader is only available for vtk>=9.3'
2150 raise pv.VTKVersionError(msg)
2151
2152 super().__init__(path)
2153
2154 def _set_defaults_post(self) -> None:
2155 self.set_active_time_point(0)
2156
2157 def enable_merge_points(self):
2158 """Enable merging coincident GLL points from different spectral elements on read."""
2159 self.reader.CleanGridOn()
2160
2161 def disable_merge_points(self):
2162 """Disable merging coincident GLL points from different spectral elements on read."""
2163 self.reader.CleanGridOff()
2164
2165 def enable_spectral_element_ids(self):
2166 """Enable spectral element IDs to be shown as cell data."""
2167 self.reader.SpectralElementIdsOn()
2168
2169 def disable_spectral_element_ids(self):
2170 """Disable spectral element IDs to be shown as cell data."""
2171 self.reader.SpectralElementIdsOff()
2172
2173 @property
2174 def number_time_points(self):
2175 """Return number of time points or iterations available to read.
2176
2177 Returns
2178 -------
2179 int
2180
2181 """
2182 return self.reader.GetNumberOfTimeSteps()
2183
2184 @property
2185 def time_values(self):
2186 """All time or iteration values.
2187
2188 Returns
2189 -------
2190 list[float]
2191
2192 """
2193 vtkStreaming = _lazy_vtk_import(
2194 'vtkCommonExecutionModel', 'vtkStreamingDemandDrivenPipeline'
2195 )()
2196 key = vtkStreaming.TIME_STEPS()
2197
2198 vtkinfo = self.reader.GetOutputInformation(0)
2199 return [vtkinfo.Get(key, i) for i in range(self.number_time_points)]
2200
2201 def time_point_value(self, time_point):
2202 """Value of time point or iteration by index.
2203
2204 Parameters
2205 ----------
2206 time_point : int
2207 Time point index.
2208
2209 Returns
2210 -------
2211 float
2212
2213 """
2214 return self.time_values[time_point]
2215
2216 @property
2217 def active_time_value(self):
2218 """Active time or iteration value.
2219
2220 Returns
2221 -------
2222 float
2223
2224 """
2225 vtkStreaming = _lazy_vtk_import(
2226 'vtkCommonExecutionModel', 'vtkStreamingDemandDrivenPipeline'
2227 )()
2228 key = vtkStreaming.UPDATE_TIME_STEP()
2229 vtkinfo = self.reader.GetOutputInformation(0)
2230 return vtkinfo.Get(key)
2231
2232 @property
2233 def active_time_point(self):
2234 """Active time point.
2235
2236 Returns
2237 -------
2238 int
2239
2240 """
2241 return self.time_values.index(self.active_time_value)
2242
2243 def set_active_time_value(self, time_value):
2244 """Set active time or iteration value.
2245
2246 Parameters
2247 ----------
2248 time_value : float
2249 Time or iteration value to set as active.
2250
2251 """
2252 vtkStreaming = _lazy_vtk_import(
2253 'vtkCommonExecutionModel', 'vtkStreamingDemandDrivenPipeline'
2254 )()
2255 key = vtkStreaming.UPDATE_TIME_STEP()
2256 vtkinfo = self.reader.GetOutputInformation(0)
2257 vtkinfo.Set(key, time_value)
2258
2259 def set_active_time_point(self, time_point):
2260 """Set active time or iteration by index.
2261
2262 Parameters
2263 ----------
2264 time_point : int
2265 Time or iteration point index for setting active time.
2266
2267 """
2268 if time_point < 0 or time_point >= self.number_time_points:
2269 msg = f'Time point ({time_point}) out of range [0, {self.number_time_points - 1}]'
2270 raise ValueError(msg)
2271
2272 self.set_active_time_value(self.time_values[time_point])
2273
2274 _cell_attr_err_msg = 'Nek5000 data does not contain cell arrays, this method cannot be used'
2275
2276 @property
2277 def number_cell_arrays(self): # noqa: D102
2278 raise AttributeError(self._cell_attr_err_msg)
2279
2280 @property
2281 def cell_array_names(self): # noqa: D102
2282 raise AttributeError(self._cell_attr_err_msg)
2283
2284 def enable_cell_array(self, name) -> None: # noqa: ARG002, D102
2285 raise AttributeError(self._cell_attr_err_msg)
2286
2287 def disable_cell_array(self, name) -> None: # noqa: ARG002, D102
2288 raise AttributeError(self._cell_attr_err_msg)
2289
2290 def cell_array_status(self, name): # noqa: ARG002, D102
2291 raise AttributeError(self._cell_attr_err_msg)
2292
2293 def enable_all_cell_arrays(self) -> None: # noqa: D102
2294 raise AttributeError(self._cell_attr_err_msg)
2295
2296 def disable_all_cell_arrays(self) -> None: # noqa: D102
2297 raise AttributeError(self._cell_attr_err_msg)
2298
2299
2300 class DICOMReader(BaseReader['ImageData']):
2301 """DICOM Reader for reading ``.dcm`` files.
2302
2303 Wraps :vtk:`vtkDICOMImageReader`.
2304
2305 This reader reads a single file or a path containing a several ``.dcm``
2306 files (DICOM stack).
2307
2308 Parameters
2309 ----------
2310 path : str
2311 Path to the single DICOM (``.dcm``) file to be opened or the directory
2312 containing a stack of DICOM files.
2313
2314 Examples
2315 --------
2316 Read a DICOM stack.
2317
2318 >>> import pyvista as pv
2319 >>> from pyvista import examples
2320 >>> path = examples.download_dicom_stack(load=False)
2321 >>> reader = pv.DICOMReader(path)
2322 >>> dataset = reader.read()
2323 >>> dataset.plot(volume=True, zoom=3, show_scalar_bar=False)
2324
2325 .. note::
2326
2327 The example dataset is the CPTAC-SAR collection from The Cancer
2328 Imaging Archive, distributed under CC BY 3.0 and subject to the
2329 TCIA Data Usage Policy. See
2330 :func:`~pyvista.examples.downloads.download_dicom_stack` for the
2331 required attribution and usage terms.
2332
2333 """
2334
2335 _vtk_module_name = 'vtkIOImage'
2336 _vtk_class_name = 'vtkDICOMImageReader'
2337
2338
2339 class BMPReader(BaseReader['ImageData']):
2340 """BMP Reader for .bmp files.
2341
2342 Wraps :vtk:`vtkBMPReader`.
2343
2344 Examples
2345 --------
2346 >>> import pyvista as pv
2347 >>> from pyvista import examples
2348 >>> from pathlib import Path
2349 >>> filename = examples.download_masonry_texture(load=False)
2350 >>> Path(filename).name
2351 'masonry.bmp'
2352 >>> reader = pv.get_reader(filename)
2353 >>> mesh = reader.read()
2354 >>> mesh.plot()
2355
2356 """
2357
2358 _vtk_module_name = 'vtkIOImage'
2359 _vtk_class_name = 'vtkBMPReader'
2360
2361
2362 class DEMReader(BaseReader['ImageData']):
2363 """DEM Reader for .dem files.
2364
2365 Wraps :vtk:`vtkDEMReader`.
2366
2367 Examples
2368 --------
2369 >>> import pyvista as pv
2370 >>> from pyvista import examples
2371 >>> from pathlib import Path
2372 >>> filename = examples.download_st_helens(load=False)
2373 >>> Path(filename).name
2374 'SainteHelens.dem'
2375 >>> reader = pv.get_reader(filename)
2376 >>> mesh = reader.read()
2377 >>> mesh.plot()
2378
2379 """
2380
2381 _vtk_module_name = 'vtkIOImage'
2382 _vtk_class_name = 'vtkDEMReader'
2383
2384
2385 class JPEGReader(BaseReader['ImageData']):
2386 """JPEG Reader for .jpeg and .jpg files.
2387
2388 Wraps :vtk:`vtkJPEGReader`.
2389
2390 Examples
2391 --------
2392 >>> import pyvista as pv
2393 >>> from pyvista import examples
2394 >>> from pathlib import Path
2395 >>> filename = examples.download_bird(load=False)
2396 >>> Path(filename).name
2397 'Pileated.jpg'
2398 >>> reader = pv.get_reader(filename)
2399 >>> mesh = reader.read()
2400 >>> mesh.plot()
2401
2402 """
2403
2404 _vtk_module_name = 'vtkIOImage'
2405 _vtk_class_name = 'vtkJPEGReader'
2406
2407
2408 class MetaImageReader(BaseReader['ImageData']):
2409 """Meta Image Reader for .mha and .mhd files.
2410
2411 Wraps :vtk:`vtkMetaImageReader`.
2412
2413 Examples
2414 --------
2415 >>> import pyvista as pv
2416 >>> from pyvista import examples
2417 >>> from pathlib import Path
2418 >>> filename = examples.download_chest(load=False)
2419 >>> Path(filename).name
2420 'ChestCT-SHORT.mha'
2421 >>> reader = pv.get_reader(filename)
2422 >>> mesh = reader.read()
2423 >>> mesh.plot()
2424
2425 """
2426
2427 _vtk_module_name = 'vtkIOImage'
2428 _vtk_class_name = 'vtkMetaImageReader'
2429
2430
2431 class NIFTIReader(BaseReader['ImageData']):
2432 """NIFTI Reader for .nii and .nii.gz files.
2433
2434 Wraps :vtk:`vtkNIFTIImageReader`.
2435
2436 Examples
2437 --------
2438 >>> import pyvista as pv
2439 >>> from pyvista import examples
2440 >>> from pathlib import Path
2441 >>> filename = examples.download_brain_atlas_with_sides(load=False)
2442 >>> Path(filename).name
2443 'avg152T1_RL_nifti.nii.gz'
2444 >>> reader = pv.get_reader(filename)
2445 >>> mesh = reader.read()
2446 >>> mesh.plot()
2447
2448 """
2449
2450 _vtk_module_name = 'vtkIOImage'
2451 _vtk_class_name = 'vtkNIFTIImageReader'
2452
2453
2454 class NRRDReader(BaseReader['ImageData']):
2455 """NRRDReader for .nrrd and .nhdr files.
2456
2457 Wraps :vtk:`vtkNrrdReader`.
2458
2459 Examples
2460 --------
2461 >>> import pyvista as pv
2462 >>> from pyvista import examples
2463 >>> from pathlib import Path
2464 >>> filename = examples.download_beach(load=False)
2465 >>> Path(filename).name
2466 'beach.nrrd'
2467 >>> reader = pv.get_reader(filename)
2468 >>> mesh = reader.read()
2469 >>> mesh.plot()
2470
2471 """
2472
2473 _vtk_module_name = 'vtkIOImage'
2474 _vtk_class_name = 'vtkNrrdReader'
2475
2476
2477 class PNGReader(BaseReader['ImageData']):
2478 """PNGReader for .png files.
2479
2480 Wraps :vtk:`vtkPNGReader`.
2481
2482 Examples
2483 --------
2484 >>> import pyvista as pv
2485 >>> from pyvista import examples
2486 >>> from pathlib import Path
2487 >>> filename = examples.download_vtk_logo(load=False)
2488 >>> Path(filename).name
2489 'vtk.png'
2490 >>> reader = pv.get_reader(filename)
2491 >>> mesh = reader.read()
2492 >>> mesh.plot()
2493
2494 """
2495
2496 _vtk_module_name = 'vtkIOImage'
2497 _vtk_class_name = 'vtkPNGReader'
2498
2499
2500 class PNMReader(BaseReader['ImageData']):
2501 """PNMReader for .pnm files.
2502
2503 Wraps :vtk:`vtkPNMReader`.
2504
2505 Examples
2506 --------
2507 >>> import pyvista as pv
2508 >>> from pyvista import examples
2509 >>> from pathlib import Path
2510 >>> filename = examples.download_gourds_pnm(load=False)
2511 >>> Path(filename).name
2512 'Gourds.pnm'
2513 >>> reader = pv.get_reader(filename)
2514 >>> mesh = reader.read()
2515 >>> mesh.plot()
2516
2517 """
2518
2519 _vtk_module_name = 'vtkIOImage'
2520 _vtk_class_name = 'vtkPNMReader'
2521
2522
2523 class SLCReader(BaseReader['ImageData']):
2524 """SLCReader for .slc files.
2525
2526 Wraps :vtk:`vtkSLCReader`.
2527
2528 Examples
2529 --------
2530 >>> import pyvista as pv
2531 >>> from pyvista import examples
2532 >>> from pathlib import Path
2533 >>> filename = examples.download_knee_full(load=False)
2534 >>> Path(filename).name
2535 'vw_knee.slc'
2536 >>> reader = pv.get_reader(filename)
2537 >>> mesh = reader.read()
2538 >>> mesh.plot()
2539
2540 """
2541
2542 _vtk_module_name = 'vtkIOImage'
2543 _vtk_class_name = 'vtkSLCReader'
2544
2545
2546 class TIFFReader(BaseReader['ImageData']):
2547 """TIFFReader for .tif and .tiff files.
2548
2549 Wraps :vtk:`vtkTIFFReader`.
2550
2551 Examples
2552 --------
2553 .. pyvista-plot::
2554 :force_static:
2555
2556 >>> import pyvista as pv
2557 >>> from pyvista import examples
2558 >>> from pathlib import Path
2559 >>> filename = examples.download_crater_imagery(load=False)
2560 >>> Path(filename).name
2561 'BJ34_GeoTifv1-04_crater_clip.tif'
2562 >>> reader = pv.get_reader(filename)
2563 >>> mesh = reader.read()
2564 >>> mesh.plot()
2565
2566 """
2567
2568 _vtk_module_name = 'vtkIOImage'
2569 _vtk_class_name = 'vtkTIFFReader'
2570
2571 def _set_defaults_post(self) -> None:
2572 """Set defaults on reader post setting file, if needed."""
2573 # Fix bug with default TIFF orientation https://gitlab.kitware.com/vtk/vtk/-/issues/19587
2574 ORIENTATION_BOTLEFT = 4
2575 self.reader.SetOrientationType(ORIENTATION_BOTLEFT)
2576
2577
2578 class HDRReader(BaseReader['ImageData']):
2579 """HDRReader for .hdr files.
2580
2581 Wraps :vtk:`vtkHDRReader`.
2582
2583 Examples
2584 --------
2585 >>> import pyvista as pv
2586 >>> from pyvista import examples
2587 >>> from pathlib import Path
2588 >>> filename = examples.download_parched_canal_4k(load=False)
2589 >>> Path(filename).name
2590 'parched_canal_4k.hdr'
2591 >>> reader = pv.get_reader(filename)
2592 >>> mesh = reader.read()
2593 >>> mesh
2594 ImageData (...)
2595 N Cells: 8382465
2596 N Points: 8388608
2597 X Bounds: 0.000e+00, 4.095e+03
2598 Y Bounds: 0.000e+00, 2.047e+03
2599 Z Bounds: 0.000e+00, 0.000e+00
2600 Dimensions: 4096, 2048, 1
2601 Spacing: 1.000e+00, 1.000e+00, 1.000e+00
2602 N Arrays: 1
2603
2604 """
2605
2606 _vtk_module_name = 'vtkIOImage'
2607 _vtk_class_name = 'vtkHDRReader'
2608
2609
2610 class PTSReader(BaseReader['PolyData']):
2611 """PTSReader for .pts files.
2612
2613 Wraps :vtk:`vtkPTSReader`.
2614
2615 """
2616
2617 _vtk_module_name = 'vtkIOGeometry'
2618 _vtk_class_name = 'vtkPTSReader'
2619
2620
2621 class AVSucdReader(BaseReader['UnstructuredGrid']):
2622 """AVSucdReader for .inp files.
2623
2624 Wraps :vtk:`vtkAVSucdReader`.
2625
2626 Examples
2627 --------
2628 >>> import pyvista as pv
2629 >>> from pyvista import examples
2630 >>> from pathlib import Path
2631 >>> filename = examples.download_cells_nd(load=False)
2632 >>> Path(filename).name
2633 'cellsnd.ascii.inp'
2634 >>> reader = pv.get_reader(filename)
2635 >>> mesh = reader.read()
2636 >>> mesh.plot(cpos='xy')
2637
2638 """
2639
2640 _vtk_module_name = 'vtkIOGeometry'
2641 _vtk_class_name = 'vtkAVSucdReader'
2642
2643
2644 class HDFReader(BaseReader['DataObject']):
2645 """HDFReader for .hdf files.
2646
2647 Wraps :vtk:`vtkHDFReader`.
2648
2649 Examples
2650 --------
2651 >>> import pyvista as pv
2652 >>> from pyvista import examples
2653 >>> from pathlib import Path
2654 >>> filename = examples.download_can_crushed_hdf(load=False)
2655 >>> Path(filename).name
2656 'can-vtu.hdf'
2657 >>> reader = pv.get_reader(filename)
2658 >>> mesh = reader.read()
2659 >>> mesh.plot()
2660
2661 """
2662
2663 _vtk_module_name = 'vtkIOHDF'
2664 _vtk_class_name = 'vtkHDFReader'
2665 _output_types = (
2666 'ImageData',
2667 'PolyData',
2668 'UnstructuredGrid',
2669 'PartitionedDataSet',
2670 'MultiBlock',
2671 )
2672
2673
2674 class GLTFReader(BaseReader['MultiBlock']):
2675 """GLTFeader for .gltf and .glb files.
2676
2677 Wraps :vtk:`vtkGLTFReader`.
2678
2679 """
2680
2681 _vtk_module_name = 'vtkIOGeometry'
2682 _vtk_class_name = 'vtkGLTFReader'
2683
2684
2685 class FluentReader(BaseReader['UnstructuredGrid']):
2686 """FluentReader for .cas files.
2687
2688 Wraps :vtk:`vtkFLUENTReader`.
2689
2690 """
2691
2692 _vtk_module_name = 'vtkIOGeometry'
2693 _vtk_class_name = 'vtkFLUENTReader'
2694
2695
2696 class MFIXReader(BaseReader['UnstructuredGrid']):
2697 """MFIXReader for .res files.
2698
2699 Wraps :vtk:`vtkMFIXReader`.
2700
2701 """
2702
2703 _vtk_module_name = 'vtkIOGeometry'
2704 _vtk_class_name = 'vtkMFIXReader'
2705
2706
2707 class SegYReader(BaseReader['DataSet']):
2708 """SegYReader for .sgy and .segy files.
2709
2710 Wraps :vtk:`vtkSegYReader`.
2711
2712 """
2713
2714 _vtk_module_name = 'vtkIOSegY'
2715 _vtk_class_name = 'vtkSegYReader'
2716 _output_types = ('StructuredGrid', 'ImageData')
2717
2718
2719 class _GIFReader(BaseVTKReader):
2720 """Simulate a VTK reader for GIF files."""
2721
2722 def __init__(self) -> None:
2723 super().__init__()
2724 self._n_frames = 0
2725 self._current_frame = 0
2726
2727 def UpdateInformation(self) -> None:
2728 """Update Information from file."""
2729
2730 def GetProgress(self):
2731 return self._current_frame / self._n_frames
2732
2733 def Update(self) -> None:
2734 """Read the GIF and store internally to `_data_object`."""
2735 from PIL import Image # noqa: PLC0415
2736 from PIL import ImageSequence # noqa: PLC0415
2737 from PIL import __version__ as pillow_version # noqa: PLC0415
2738
2739 PILLOW_VERSION_INFO = VersionInfo(
2740 major=int(pillow_version.split('.')[0]),
2741 minor=int(pillow_version.split('.')[1]),
2742 micro=int(pillow_version.split('.')[2]),
2743 )
2744
2745 img = Image.open(self._filename)
2746 self._data_object = pv.ImageData(dimensions=(img.size[0], img.size[1], 1))
2747
2748 # load each frame to the grid (RGB since gifs do not support transparency
2749 self._n_frames = img.n_frames # type: ignore[attr-defined]
2750 pillow_get_data = (
2751 Image.Image.get_flattened_data
2752 if PILLOW_VERSION_INFO >= (12, 1)
2753 else Image.Image.getdata
2754 )
2755 for i, frame in enumerate(ImageSequence.Iterator(img)):
2756 self._current_frame = i
2757 data = np.array(pillow_get_data(frame.convert('RGB')), dtype=np.uint8)
2758 self._data_object.point_data.set_array(data, f'frame{i}')
2759 self.UpdateObservers(6)
2760
2761 if 'frame0' in self._data_object.point_data:
2762 self._data_object.point_data.active_scalars_name = 'frame0'
2763
2764 img.close()
2765
2766
2767 class GIFReader(BaseReader['ImageData']):
2768 """GIFReader for .gif files.
2769
2770 Parameters
2771 ----------
2772 path : str
2773 Path of the GIF to read.
2774
2775 Examples
2776 --------
2777 >>> import pyvista as pv
2778 >>> from pyvista import examples
2779 >>> from pathlib import Path
2780 >>> filename = examples.download_gif_simple(load=False)
2781 >>> Path(filename).name
2782 'sample.gif'
2783 >>> reader = pv.get_reader(filename)
2784 >>> mesh = reader.read()
2785 >>> mesh.plot(rgba=True, zoom='tight', border=True, border_width=2)
2786
2787 """
2788
2789 _class_reader = _GIFReader
2790
2791
2792 class XdmfReader(BaseReader['DataObject'], PointCellDataSelection, TimeReader):
2793 """XdmfReader for .xdmf files.
2794
2795 Wraps :vtk:`vtkXdmfReader`.
2796
2797 Parameters
2798 ----------
2799 path : str
2800 Path of the XDMF file to read.
2801
2802 Examples
2803 --------
2804 >>> import pyvista as pv
2805 >>> from pyvista import examples
2806 >>> from pathlib import Path
2807 >>> filename = examples.download_meshio_xdmf(load=False)
2808 >>> reader = pv.get_reader(filename)
2809 >>> Path(filename).name
2810 'out.xdmf'
2811 >>> mesh = reader.read()
2812 >>> mesh.plot()
2813
2814 """
2815
2816 _vtk_module_name = 'vtkIOXdmf2'
2817 _vtk_class_name = 'vtkXdmfReader'
2818 _output_types = ('MultiBlock', 'UnstructuredGrid', 'StructuredGrid', 'RectilinearGrid')
2819
2820 @property
2821 def number_grids(self):
2822 """Return the number of grids that can be read by the reader.
2823
2824 Returns
2825 -------
2826 int
2827 The number of grids to be read.
2828
2829 """
2830 return self.reader.GetNumberOfGrids()
2831
2832 def set_active_time_value(self, time_value): # noqa: D102
2833 if time_value not in self.time_values:
2834 msg = f'Not a valid time {time_value} from available time values: {self.time_values}'
2835 raise ValueError(msg)
2836 self._active_time_value = time_value
2837 self.reader.UpdateTimeStep(time_value)
2838
2839 @property
2840 def number_time_points(self): # noqa: D102
2841 return len(self.time_values)
2842
2843 def time_point_value(self, time_point): # noqa: D102
2844 return self.time_values[time_point]
2845
2846 @property
2847 def time_values(self): # noqa: D102
2848 info = self.reader.GetOutputInformation(0)
2849 return list(info.Get(_vtk.vtkCompositeDataPipeline.TIME_STEPS()))
2850
2851 @property
2852 def active_time_value(self): # noqa: D102
2853 return self._active_time_value
2854
2855 def set_active_time_point(self, time_point) -> None: # noqa: D102
2856 self.set_active_time_value(self.time_values[time_point])
2857
2858 def _set_defaults_post(self) -> None:
2859 self._active_time_value = self.time_values[0]
2860 self.set_active_time_value(self._active_time_value)
2861
2862
2863 class XMLPartitionedDataSetReader(BaseReader['PartitionedDataSet']):
2864 """XML PartitionedDataSet Reader for reading .vtpd files.
2865
2866 Wraps :vtk:`vtkXMLPartitionedDataSetReader`.
2867
2868 Examples
2869 --------
2870 >>> import pyvista as pv
2871 >>> partitions = pv.PartitionedDataSet(
2872 ... [
2873 ... pv.Wavelet(extent=(0, 10, 0, 10, 0, 5)),
2874 ... pv.Wavelet(extent=(0, 10, 0, 10, 5, 10)),
2875 ... ]
2876 ... )
2877 >>> partitions.save('my_partitions.vtpd')
2878 >>> _ = pv.read('my_partitions.vtpd')
2879
2880 """
2881
2882 _vtk_module_name = 'vtkIOXML'
2883 _vtk_class_name = 'vtkXMLPartitionedDataSetReader'
2884
2885
2886 class FLUENTCFFReader(BaseReader['MultiBlock']):
2887 """FLUENTCFFReader for .h5 files.
2888
2889 Wraps :vtk:`vtkFLUENTCFFReader`.
2890
2891 Examples
2892 --------
2893 >>> import pyvista as pv
2894 >>> from pyvista import examples
2895 >>> filename = examples.download_room_cff(load=False)
2896 >>> reader = pv.get_reader(filename)
2897 >>> blocks = reader.read()
2898 >>> mesh = blocks[0]
2899 >>> mesh.plot(cpos='xy', scalars='SV_T')
2900
2901 """
2902
2903 _vtk_module_name = 'vtkIOFLUENTCFF'
2904 _vtk_class_name = 'vtkFLUENTCFFReader'
2905
2906
2907 class GambitReader(BaseReader['UnstructuredGrid']):
2908 """GambitReader for .neu files.
2909
2910 Wraps :vtk:`vtkGAMBITReader`.
2911
2912 .. versionadded:: 0.44.0
2913
2914 Examples
2915 --------
2916 >>> import pyvista as pv
2917 >>> from pyvista import examples
2918 >>> filename = examples.download_prism(load=False)
2919 >>> reader = pv.get_reader(filename)
2920 >>> mesh = reader.read()
2921 >>> mesh.plot()
2922
2923 """
2924
2925 _vtk_module_name = 'vtkIOGeometry'
2926 _vtk_class_name = 'vtkGAMBITReader'
2927
2928
2929 class GaussianCubeReader(BaseReader['DataSet']):
2930 """GaussianCubeReader for .cube files.
2931
2932 Wraps :vtk:`vtkGaussianCubeReader`.
2933
2934 Examples
2935 --------
2936 >>> import pyvista as pv
2937 >>> from pyvista import examples
2938 >>> from pathlib import Path
2939
2940 >>> filename = examples.download_m4_total_density(load=False)
2941 >>> Path(filename).name
2942 'm4_TotalDensity.cube'
2943
2944 """
2945
2946 _vtk_module_name = 'vtkIOChemistry'
2947 _vtk_class_name = 'vtkGaussianCubeReader'
2948 _output_types = ('ImageData', 'PolyData')
2949
2950 @_deprecate_positional_args
2951 def read(
2952 self,
2953 grid: bool = True, # noqa: FBT001, FBT002
2954 *,
2955 validate: bool | None = None,
2956 ) -> pv.DataSet:
2957 """Read the file and return the output.
2958
2959 Parameters
2960 ----------
2961 grid : bool, default: False
2962 Output as a grid if ``True``, otherwise return the polydata.
2963
2964 validate : bool, optional
2965 Forwarded to :func:`pyvista.wrap`. See :meth:`BaseReader.read`.
2966
2967 .. versionadded:: 0.48
2968
2969 Returns
2970 -------
2971 pyvista.DataSet
2972 PyVista dataset read from the file.
2973
2974 """
2975 from pyvista.core.filters import _update_alg # avoid circular import # noqa: PLC0415
2976
2977 _update_alg(self.reader, progress_bar=self._progress_bar, message=self._progress_msg)
2978 data = (
2979 wrap(self.reader.GetGridOutput(), validate=validate)
2980 if grid
2981 else wrap(self.reader.GetOutputDataObject(0), validate=validate)
2982 )
2983 if data is None: # pragma: no cover
2984 msg = 'File reader failed to read and/or produced no output.'
2985 raise RuntimeError(msg)
2986 data._post_file_load_processing()
2987
2988 # check for any pyvista metadata
2989 data._restore_metadata()
2990 return data
2991
2992 @property
2993 def hb_scale(self) -> float:
2994 """Get the scaling factor to compute bonds with hydrogen atoms.
2995
2996 Returns
2997 -------
2998 float
2999 The scaling factor to compute bonds with hydrogen atoms.
3000
3001 """
3002 return self.reader.GetHBScale()
3003
3004 @hb_scale.setter
3005 def hb_scale(self, hb_scale: float) -> None:
3006 """Set the scaling factor to compute bonds with hydrogen atoms.
3007
3008 Parameters
3009 ----------
3010 hb_scale : float
3011 The scaling factor to compute bonds with hydrogen atoms.
3012
3013 """
3014 self.reader.SetHBScale(hb_scale)
3015
3016 @property
3017 def b_scale(self) -> float:
3018 """Get the scaling factor to compute bonds between non-hydrogen atoms.
3019
3020 Returns
3021 -------
3022 float
3023 The scaling factor to compute bonds between non-hydrogen atoms.
3024
3025 """
3026 return self.reader.GetBScale()
3027
3028 @b_scale.setter
3029 def b_scale(self, b_scale: float) -> None:
3030 """Set the scaling factor to compute bonds between non-hydrogen atoms.
3031
3032 Parameters
3033 ----------
3034 b_scale : float
3035 The scaling factor to compute bonds between non-hydrogen atoms.
3036
3037 """
3038 self.reader.SetBScale(b_scale)
3039
3040
3041 class MINCImageReader(BaseReader['ImageData']):
3042 """MINCImageReader for .mnc files.
3043
3044 Wraps :vtk:`vtkMINCImageReader`.
3045
3046 .. versionadded:: 0.44.0
3047
3048 Examples
3049 --------
3050 >>> import pyvista as pv
3051 >>> from pyvista import examples
3052 >>> filename = examples.download_t3_grid_0(load=False)
3053 >>> reader = pv.get_reader(filename)
3054 >>> mesh = reader.read()
3055 >>> mesh.plot()
3056
3057 """
3058
3059 _vtk_module_name = 'vtkIOMINC'
3060 _vtk_class_name = 'vtkMINCImageReader'
3061
3062
3063 class PDBReader(BaseReader['PolyData']):
3064 """PDBReader for .pdb files.
3065
3066 Wraps :vtk:`vtkPDBReader`.
3067
3068 .. versionadded:: 0.44.0
3069
3070 Examples
3071 --------
3072 >>> import pyvista as pv
3073 >>> from pyvista import examples
3074 >>> from pathlib import Path
3075 >>> filename = examples.download_caffeine(load=False)
3076 >>> Path(filename).name
3077 'caffeine.pdb'
3078
3079 """
3080
3081 _vtk_module_name = 'vtkIOChemistry'
3082 _vtk_class_name = 'vtkPDBReader'
3083
3084
3085 class GESignaReader(BaseReader['ImageData']):
3086 """GESignaReader for .MR files.
3087
3088 Wraps :vtk:`vtkGESignaReader`.
3089
3090 .. versionadded:: 0.44.0
3091
3092 Examples
3093 --------
3094 >>> import pyvista as pv
3095 >>> from pyvista import examples
3096 >>> filename = examples.download_e07733s002i009(load=False)
3097 >>> reader = pv.get_reader(filename)
3098 >>> mesh = reader.read()
3099 >>> mesh.plot()
3100
3101 """
3102
3103 _vtk_module_name = 'vtkIOImage'
3104 _vtk_class_name = 'vtkGESignaReader'
3105
3106
3107 class ParticleReader(BaseReader['PolyData']):
3108 """ParticleReader for .raw files.
3109
3110 Wraps :vtk:`vtkParticleReader`.
3111
3112 .. versionadded:: 0.44.0
3113
3114 Warnings
3115 --------
3116 If the byte order is not set correctly,
3117 the reader will fail to read the file.
3118
3119 Examples
3120 --------
3121 >>> import pyvista as pv
3122 >>> from pyvista import examples
3123 >>> from pathlib import Path
3124 >>> filename = examples.download_particles(load=False)
3125 >>> reader = pv.get_reader(filename)
3126 >>> reader.endian = 'BigEndian'
3127 >>> Path(filename).name
3128 'Particles.raw'
3129 >>> mesh = reader.read()
3130 >>> mesh.plot()
3131
3132 """
3133
3134 _vtk_module_name = 'vtkIOGeometry'
3135 _vtk_class_name = 'vtkParticleReader'
3136
3137 @property
3138 def endian(self) -> str:
3139 """Get the byte order of the data.
3140
3141 Returns
3142 -------
3143 str
3144 The byte order of the data. 'BigEndian' or 'LittleEndian'.
3145
3146 """
3147 return self.reader.GetDataByteOrderAsString()
3148
3149 @endian.setter
3150 def endian(self, endian: str):
3151 """Set the byte order of the data.
3152
3153 Parameters
3154 ----------
3155 endian : str
3156 The byte order of the data. 'BigEndian' or 'LittleEndian'.
3157
3158 """
3159 if endian == 'BigEndian':
3160 self.reader.SetDataByteOrderToBigEndian()
3161 elif endian == 'LittleEndian':
3162 self.reader.SetDataByteOrderToLittleEndian()
3163 else:
3164 msg = f'Invalid endian: {endian}.'
3165 raise ValueError(msg)
3166 self.reader.Update()
3167
3168
3169 class ProStarReader(BaseReader['UnstructuredGrid']):
3170 """ProStarReader for .vrt files.
3171
3172 Wraps :vtk:`vtkProStarReader`.
3173
3174 Reads geometry in proSTAR (STARCD) file format.
3175
3176 .. versionadded:: 0.44.0
3177
3178 Examples
3179 --------
3180 >>> import pyvista as pv
3181 >>> from pyvista import examples
3182 >>> filename = examples.download_prostar(load=False)
3183 >>> reader = pv.get_reader(filename)
3184 >>> mesh = reader.read()
3185 >>> mesh.plot()
3186
3187 """
3188
3189 _vtk_module_name = 'vtkIOGeometry'
3190 _vtk_class_name = 'vtkProStarReader'
3191
3192
3193 class ExodusIIReader(BaseReader['MultiBlock'], PointCellDataSelection, TimeReader):
3194 """ExodusIIReader for .e and .exo files.
3195
3196 Reads Exodus II files. Wraps :vtk:`vtkExodusIIReader`.
3197
3198 .. versionadded:: 0.45.0
3199
3200 Examples
3201 --------
3202 >>> import pyvista as pv
3203 >>> from pyvista import examples
3204 >>> filename = examples.download_mug(load=False)
3205 >>> reader = pv.get_reader(filename)
3206 >>> mesh = reader.read()
3207 >>> mesh.plot()
3208
3209 """
3210
3211 _vtk_module_name = 'vtkIOExodus'
3212 _vtk_class_name = 'vtkExodusIIReader'
3213
3214 def _set_defaults_post(self):
3215 self._element_blocks = ExodusIIBlockSet(self, self._reader.ELEM_BLOCK)
3216 self._face_blocks = ExodusIIBlockSet(self, self._reader.FACE_BLOCK)
3217 self._edge_blocks = ExodusIIBlockSet(self, self._reader.EDGE_BLOCK)
3218
3219 self._elem_sets = ExodusIIBlockSet(self, self._reader.ELEM_SET)
3220 self._face_sets = ExodusIIBlockSet(self, self._reader.FACE_SET)
3221 self._side_sets = ExodusIIBlockSet(self, self._reader.SIDE_SET)
3222 self._node_sets = ExodusIIBlockSet(self, self._reader.NODE_SET)
3223
3224 self.enable_all_cell_arrays()
3225 self.enable_all_point_arrays()
3226
3227 def read_global(self) -> pv.Table:
3228 """Read enabled global data.
3229
3230 Returns
3231 -------
3232 Table
3233 Global data from Exodus II file
3234
3235 """
3236 global_extractor = _lazy_vtk_import(
3237 'vtkFiltersExtraction', 'vtkExtractExodusGlobalTemporalVariables'
3238 )()
3239
3240 global_extractor.SetInputConnection(self.reader.GetOutputPort())
3241 global_extractor.Update()
3242
3243 return wrap(global_extractor.GetOutputDataObject(0))
3244
3245 @property
3246 def element_blocks(self):
3247 """Returns an ExodusIIBlockSet object for the element blocks.
3248
3249 Returns
3250 -------
3251 ExodusIIBlockSet
3252 Convenience object for accessing information about the element blocks.
3253
3254 """
3255 return self._element_blocks
3256
3257 @property
3258 def face_blocks(self):
3259 """Returns an ExodusIIBlockSet object for the face blocks.
3260
3261 Returns
3262 -------
3263 ExodusIIBlockSet
3264 Convenience object for accessing information about the face blocks.
3265
3266 """
3267 return self._face_blocks
3268
3269 @property
3270 def edge_blocks(self):
3271 """Returns an ExodusIIBlockSet object for the edge blocks.
3272
3273 Returns
3274 -------
3275 ExodusIIBlockSet
3276 Convenience object for accessing information about the edge blocks.
3277
3278 """
3279 return self._edge_blocks
3280
3281 @property
3282 def side_sets(self):
3283 """Returns an ExodusIIBlockSet object for the side sets.
3284
3285 Returns
3286 -------
3287 ExodusIIBlockSet
3288 Convenience object for accessing information about the side sets.
3289
3290 """
3291 return self._side_sets
3292
3293 @property
3294 def node_sets(self):
3295 """Returns an ExodusIIBlockSet object for the node sets.
3296
3297 Returns
3298 -------
3299 ExodusIIBlockSet
3300 Convenience object for accessing information about the node sets.
3301
3302 """
3303 return self._node_sets
3304
3305 @property
3306 def element_sets(self):
3307 """Returns an ExodusIIBlockSet object for the element sets.
3308
3309 Returns
3310 -------
3311 ExodusIIBlockSet
3312 Convenience object for accessing information about the element sets.
3313
3314 """
3315 return self._elem_sets
3316
3317 @property
3318 def face_sets(self):
3319 """Returns an ExodusIIBlockSet object for the face sets.
3320
3321 Returns
3322 -------
3323 ExodusIIBlockSet
3324 Convenience object for accessing information about the face sets.
3325
3326 """
3327 return self._face_sets
3328
3329 @property
3330 def number_time_points(self):
3331 """Return number of time points or iterations available to read.
3332
3333 Returns
3334 -------
3335 int
3336
3337 """
3338 return self.reader.GetNumberOfTimeSteps()
3339
3340 def enable_displacements(self, displacement_magnitude=1.0):
3341 """Nodal positions are 'displaced' by the standard exodus displacement vector.
3342
3343 Parameters
3344 ----------
3345 displacement_magnitude : float, optional
3346 Magnitude of displacement, default 1.0.
3347
3348 """
3349 self.reader.SetApplyDisplacements(True)
3350 self.reader.SetDisplacementMagnitude(displacement_magnitude)
3351
3352 def disable_displacements(self):
3353 """Nodal positions are not 'displaced'."""
3354 self.reader.SetApplyDisplacements(False)
3355
3356 @property
3357 def number_point_arrays(self):
3358 """Return the number of point arrays.
3359
3360 Returns
3361 -------
3362 int
3363 Number of point arrays.
3364
3365 """
3366 return self.reader.GetNumberOfPointResultArrays()
3367
3368 @property
3369 def point_array_names(self):
3370 """Return the list of all point array names.
3371
3372 Returns
3373 -------
3374 list[str]
3375 List of all point array names.
3376
3377 """
3378 return [self.reader.GetPointResultArrayName(i) for i in range(self.number_point_arrays)]
3379
3380 def enable_point_array(self, name):
3381 """Enable point array with name.
3382
3383 Parameters
3384 ----------
3385 name : str
3386 Point array name.
3387
3388 """
3389 self.reader.SetPointResultArrayStatus(name, 1)
3390
3391 def disable_point_array(self, name):
3392 """Disable point array with name.
3393
3394 Parameters
3395 ----------
3396 name : str
3397 Point array name.
3398
3399 """
3400 self.reader.SetPointResultArrayStatus(name, 0)
3401
3402 def point_array_status(self, name):
3403 """Get status of point array with name.
3404
3405 Parameters
3406 ----------
3407 name : str
3408 Point array name.
3409
3410 Returns
3411 -------
3412 bool
3413 Whether reading the cell array is enabled.
3414
3415 """
3416 return bool(self.reader.GetPointResultArrayStatus(name))
3417
3418 @property
3419 def number_cell_arrays(self):
3420 """Return the number of point arrays.
3421
3422 Returns
3423 -------
3424 int
3425 Number of point arrays.
3426
3427 """
3428 return self.reader.GetNumberOfElementResultArrays()
3429
3430 @property
3431 def cell_array_names(self):
3432 """Return the list of all cell array names.
3433
3434 Returns
3435 -------
3436 list[str]
3437 List of all cell array names.
3438
3439 """
3440 return [self.reader.GetElementResultArrayName(i) for i in range(self.number_cell_arrays)]
3441
3442 def enable_cell_array(self, name):
3443 """Enable cell array with name.
3444
3445 Parameters
3446 ----------
3447 name : str
3448 Cell array name.
3449
3450 """
3451 self.reader.SetElementResultArrayStatus(name, 1)
3452
3453 def disable_cell_array(self, name):
3454 """Disable cell array with name.
3455
3456 Parameters
3457 ----------
3458 name : str
3459 Cell array name.
3460
3461 """
3462 self.reader.SetElementResultArrayStatus(name, 0)
3463
3464 def cell_array_status(self, name):
3465 """Get status of cell array with name.
3466
3467 Parameters
3468 ----------
3469 name : str
3470 Cell array name.
3471
3472 Returns
3473 -------
3474 bool
3475 Whether reading the cell array is enabled.
3476
3477 """
3478 return bool(self.reader.GetElementResultArrayStatus(name))
3479
3480 @property
3481 def number_global_arrays(self):
3482 """Return the number of point arrays.
3483
3484 Returns
3485 -------
3486 int
3487 Number of point arrays.
3488
3489 """
3490 return self.reader.GetNumberOfGlobalResultArrays()
3491
3492 @property
3493 def global_array_names(self):
3494 """Return the list of all global array names.
3495
3496 Returns
3497 -------
3498 list[str]
3499 List of all global array names.
3500
3501 """
3502 return [self.reader.GetGlobalResultArrayName(i) for i in range(self.number_cell_arrays)]
3503
3504 def enable_global_array(self, name):
3505 """Enable global array with name.
3506
3507 Parameters
3508 ----------
3509 name : str
3510 global array name.
3511
3512 """
3513 self.reader.SetGlobalResultArrayStatus(name, 1)
3514
3515 def disable_global_array(self, name):
3516 """Disable global array with name.
3517
3518 Parameters
3519 ----------
3520 name : str
3521 global array name.
3522
3523 """
3524 self.reader.SetGlobalResultArrayStatus(name, 0)
3525
3526 def global_array_status(self, name):
3527 """Get status of global array with name.
3528
3529 Parameters
3530 ----------
3531 name : str
3532 global array name.
3533
3534 Returns
3535 -------
3536 bool
3537 Whether reading the global array is enabled.
3538
3539 """
3540 return bool(self.reader.GetGlobalResultArrayStatus(name))
3541
3542 def enable_all_global_arrays(self) -> None:
3543 """Enable all global arrays."""
3544 for name in self.global_array_names:
3545 self.enable_global_array(name)
3546
3547 def disable_all_global_arrays(self) -> None:
3548 """Disable all global arrays."""
3549 for name in self.global_array_names:
3550 self.disable_global_array(name)
3551
3552 @property
3553 def time_values(self):
3554 """All time or iteration values.
3555
3556 Returns
3557 -------
3558 list[float]
3559
3560 """
3561 vtkStreaming = _lazy_vtk_import(
3562 'vtkCommonExecutionModel', 'vtkStreamingDemandDrivenPipeline'
3563 )()
3564 key = vtkStreaming.TIME_STEPS()
3565 vtkinfo = self.reader.GetOutputInformation(0)
3566 return [vtkinfo.Get(key, i) for i in range(self.number_time_points)]
3567
3568 def time_point_value(self, time_point):
3569 """Value of time point or iteration by index.
3570
3571 Parameters
3572 ----------
3573 time_point : int
3574 Time point index.
3575
3576 Returns
3577 -------
3578 float
3579
3580 """
3581 return self.time_values[time_point]
3582
3583 @property
3584 def active_time_value(self):
3585 """Active time or iteration value.
3586
3587 Returns
3588 -------
3589 float
3590
3591 """
3592 return self.time_values[self.reader.GetTimeStep()]
3593
3594 def set_active_time_value(self, time_value):
3595 """Set active time or iteration value.
3596
3597 Parameters
3598 ----------
3599 time_value : float
3600 Time or iteration value to set as active.
3601
3602 """
3603 try:
3604 index = self.time_values.index(time_value)
3605 except ValueError:
3606 msg = f'Time {time_value} not present. Available times are {self.time_values}'
3607 raise ValueError(msg) from None
3608
3609 self.set_active_time_point(index)
3610
3611 def set_active_time_point(self, time_point):
3612 """Set active time or iteration by index.
3613
3614 Parameters
3615 ----------
3616 time_point : int
3617 Time or iteration point index for setting active time.
3618
3619 """
3620 self.reader.SetTimeStep(time_point)
3621
3622
3623 class _FRDReader(BaseVTKReader):
3624 """VTK-style reader for CalculiX FRD files using FRDParser."""
3625
3626 def __init__(self) -> None:
3627 super().__init__()
3628 self._frd_data: _FRDData | None = None
3629 self._time_steps: list[float] = []
3630 self._active_time_point: int = 0
3631
3632 def UpdateInformation(self) -> None:
3633 parser = _FRDParser(self._filename)
3634 self._frd_data = parser.parse()
3635
3636 MAX_N_LINES = 3
3637
3638 def _warn_invalid(invalid_elements, desc):
3639 n = len(invalid_elements)
3640 s = 's' if n > 1 else ''
3641 msg = f'{n} cell{s} with {desc}:'
3642 for elem in invalid_elements[:MAX_N_LINES]:
3643 msg += '\n ' + str(elem)
3644
3645 warn_external(msg, InvalidMeshWarning)
3646
3647 if invalid_elements := self._frd_data._has_too_many_points:
3648 _warn_invalid(invalid_elements, 'too many points detected')
3649
3650 if invalid_elements := self._frd_data._has_too_few_points:
3651 _warn_invalid(invalid_elements, 'too few points detected. These elements are skipped')
3652
3653 if invalid_elements := self._frd_data._has_unsupported_element:
3654 _warn_invalid(
3655 invalid_elements, 'unknown element type encountered. These elements are skipped.'
3656 )
3657
3658 self._time_steps = sorted(self._frd_data.results_by_step.keys())
3659
3660 def Update(self) -> None:
3661 """Construct the mesh for the currently active time step."""
3662 if self._frd_data is None:
3663 return
3664 step_time = self._time_steps[self._active_time_point] if self._time_steps else None
3665 step_data = (
3666 self._frd_data.results_by_step.get(step_time, {}) if step_time is not None else {}
3667 )
3668 self._data_object = _FRDParser._build_grid(self._frd_data, step_data)
3669
3670
3671 class FRDReader(BaseReader['UnstructuredGrid'], TimeReader):
3672 """Reader for CalculiX FRD ASCII result files (``.frd``).
3673
3674 Supported element types include: HE8, PE6, PE15, TE4, HE20, TE10, TR3, TR6, QU4, QU8, BE2, BE3.
3675
3676 For datasets containing 6-component tensors (e.g. STRESS or STRAIN), this reader automatically
3677 pre-computes and appends the following derived scalar arrays to the output mesh:
3678
3679 - ``<NAME>_Mises``: equivalent von Mises magnitude.
3680 - ``<NAME>_sgMises``: signed von Mises magnitude.
3681 - ``<NAME>_PS1``, ``_PS2``, ``_PS3``: principal components.
3682
3683 .. versionadded:: 0.48
3684
3685 Examples
3686 --------
3687 >>> import pyvista as pv
3688 >>> from pyvista import examples
3689 >>> from pathlib import Path
3690 >>> filename = examples.download_frd(load=False)
3691 >>> Path(filename).name
3692 'mesh.frd'
3693 >>> reader = pv.get_reader(filename)
3694 >>> mesh = reader.read()
3695 >>> mesh.plot()
3696
3697 """
3698
3699 _class_reader = _FRDReader
3700
3701 @property
3702 def number_time_points(self) -> int:
3703 """Return the total number of time points."""
3704 return len(self.reader._time_steps)
3705
3706 def time_point_value(self, time_point: int) -> float:
3707 """Return the time value associated with the given time point."""
3708 return self.reader._time_steps[time_point]
3709
3710 @property
3711 def time_values(self) -> list[float]:
3712 """Return the list of available time values."""
3713 return list(self.reader._time_steps)
3714
3715 def set_active_time_point(self, time_point: int) -> None:
3716 """Set the active time point."""
3717 n = self.number_time_points
3718 if not 0 <= time_point < n:
3719 msg = f'time_point {time_point} is out of range (file has {n} time point(s)).'
3720 raise IndexError(msg)
3721 self.reader._active_time_point = time_point
3722
3723 def set_active_time_value(self, time_value: float) -> None:
3724 """Set the active time value."""
3725 steps = self.reader._time_steps
3726 if not steps:
3727 msg = 'No time steps found in the FRD file.'
3728 raise RuntimeError(msg)
3729
3730 # Changed logic - exact match is required
3731 if time_value not in steps:
3732 msg = f'Not a valid time {time_value} from available time values: {steps}'
3733 raise ValueError(msg)
3734
3735 self.reader._active_time_point = steps.index(time_value)
3736
3737 @property
3738 def active_time_value(self) -> float:
3739 """Return the active time value."""
3740 steps = self.reader._time_steps
3741 if not steps:
3742 return 0.0
3743 return steps[self.reader._active_time_point]
3744
3745 @active_time_value.setter
3746 def active_time_value(self, value: float) -> None:
3747 """Set the active time value."""
3748 self.set_active_time_value(value)
3749
3750
3751 class ExodusIIBlockSet(_NoNewAttrMixin):
3752 """Class for enabling and disabling blocks, sets, and block/set arrays in Exodus II files."""
3753
3754 def __init__(self, exodus_reader: ExodusIIReader, object_type):
3755 if not exodus_reader.reader.GetObjectTypeName(object_type):
3756 msg = 'object_type is invalid'
3757 raise ValueError(msg)
3758
3759 self._reader = weakref.proxy(exodus_reader.reader)
3760 self._object_type = object_type
3761
3762 @property
3763 def number(self):
3764 """Return the number of blocks or sets in object.
3765
3766 Returns
3767 -------
3768 int
3769 Number of block or sets in object.
3770
3771 """
3772 return self._reader.GetNumberOfObjects(self._object_type)
3773
3774 @property
3775 def names(self):
3776 """Returns the list of the names of the sets or blocks in object.
3777
3778 Returns
3779 -------
3780 list[str]
3781 List of all names of blocks/sets in object.
3782
3783 """
3784 return [self._reader.GetObjectName(self._object_type, i) for i in range(self.number)]
3785
3786 def enable(self, name):
3787 """Enable the block/set with name.
3788
3789 Parameters
3790 ----------
3791 name: str
3792 name of set/block to be enabled.
3793
3794 """
3795 self._reader.SetObjectStatus(self._object_type, name, 1)
3796
3797 def enable_all(self):
3798 """Enable all names in block/set."""
3799 for name in self.names:
3800 self.enable(name)
3801
3802 def disable(self, name):
3803 """Disable the block/set with name.
3804
3805 Parameters
3806 ----------
3807 name: str
3808 name of set/block to be disabled.
3809
3810 """
3811 self._reader.SetObjectStatus(self._object_type, name, 0)
3812
3813 def disable_all(self):
3814 """Disable all names in block/set."""
3815 for name in self.names:
3816 self.disable(name)
3817
3818 def status(self, name):
3819 """Get the status of the block/set with name.
3820
3821 Parameters
3822 ----------
3823 name: str
3824 name of set/block to be disabled.
3825
3826 Returns
3827 -------
3828 bool
3829 Whether the block/set is enabled.
3830
3831 """
3832 return bool(self._reader.GetObjectStatus(self._object_type, name))
3833
3834 def _construct_result_method(self, prefix, suffix):
3835 """Construct result array methods from the object type enum."""
3836 # Get object name
3837 objectname = self._reader.GetObjectTypeName(self._object_type).title().replace(' ', '')
3838
3839 # Construct result array method name with prefix/suffix
3840 method_name = prefix + objectname + 'ResultArray' + suffix
3841
3842 # Get method from reader
3843 return getattr(self._reader, method_name)
3844
3845 @property
3846 def number_arrays(self):
3847 """Return the number of block/set arrays in object.
3848
3849 Returns
3850 -------
3851 int
3852 Number of block/set arrays in object.
3853
3854 """
3855 method = self._construct_result_method('GetNumberOf', 's')
3856 return method()
3857
3858 @property
3859 def array_names(self):
3860 """Returns the list of the names of the block/set arrays in object.
3861
3862 Returns
3863 -------
3864 list[str]
3865 List of all names of block/set arrays in object.
3866
3867 """
3868 name_method = self._construct_result_method('Get', 'Name')
3869 return [name_method(i) for i in range(self.number_arrays)]
3870
3871 def enable_array(self, name):
3872 """Enable the block/set array with name.
3873
3874 Parameters
3875 ----------
3876 name: str
3877 name of set/block array to be enabled.
3878
3879 """
3880 enable_method = self._construct_result_method('Set', 'Status')
3881 enable_method(name, 1)
3882
3883 def enable_all_arrays(self):
3884 """Enable all arrays in block/set."""
3885 for name in self.array_names:
3886 self.enable_array(name)
3887
3888 def disable_array(self, name):
3889 """Disable the block/set array with name.
3890
3891 Parameters
3892 ----------
3893 name: str
3894 name of set/block array to be disabled.
3895
3896 """
3897 disable_method = self._construct_result_method('Set', 'Status')
3898 disable_method(name, 0)
3899
3900 def disable_all_arrays(self):
3901 """Disable all arrays in block/set."""
3902 for name in self.array_names:
3903 self.disable_array(name)
3904
3905 def array_status(self, name):
3906 """Get the status of the block/set array with name.
3907
3908 Parameters
3909 ----------
3910 name: str
3911 name of set/block array to be disabled.
3912
3913 Returns
3914 -------
3915 bool
3916 Whether the block/set array is enabled.
3917
3918 """
3919 status_method = self._construct_result_method('Get', 'Status')
3920 return status_method(name)
3921
3922
3923 @dataclass(order=True)
3924 class SeriesDataSet(_NoNewAttrMixin):
3925 """Class for storing dataset info from series file."""
3926
3927 name: str
3928 time: float
3929
3930
3931 _SeriesEachReader = TypeVar('_SeriesEachReader', bound='BaseReader[Any]')
3932
3933
3934 class _SeriesReader(BaseVTKReader, Generic[_SeriesEachReader]):
3935 """Simulate a VTK reader for series file."""
3936
3937 def __init__(self) -> None:
3938 super().__init__()
3939 self._filename: str | None = None
3940 self._directory: str | None = None
3941 self._datasets: list[SeriesDataSet] | None = None
3942 self._active_dataset: SeriesDataSet | None = None
3943 self._time_values: list[float] | None = None
3944 self._reader_type: type[_SeriesEachReader] | None = None
3945 self._active_reader: _SeriesEachReader | None = None
3946
3947 def SetFileName(self, filename) -> None:
3948 """Set filename and update reader."""
3949 self._filename = str(filename)
3950 self._directory = str(Path(filename).parent)
3951
3952 def _deterimine_reader_type(self) -> type[_SeriesEachReader]:
3953 """Determine reader type from first dataset in series."""
3954 if self._datasets is None or len(self._datasets) == 0:
3955 msg = 'No datasets found in series file to determine reader type.'
3956 raise ValueError(msg)
3957
3958 self._filename = cast('str', self._filename)
3959 parent_ext = Path(self._filename.removesuffix('.series')).suffix
3960
3961 child_exts = {Path(dataset.name).suffix for dataset in self._datasets}
3962 if len(child_exts) != 1:
3963 msg = 'Datasets in series file have multiple extensions, cannot determine reader type.'
3964 raise ValueError(msg)
3965
3966 child_ext = child_exts.pop()
3967 if parent_ext != child_ext:
3968 msg = (
3969 f'Dataset extension {child_ext} does not match series file parent extension '
3970 f'{parent_ext}, cannot determine reader type.'
3971 )
3972 raise ValueError(msg)
3973
3974 return cast('type[_SeriesEachReader]', CLASS_READERS[child_ext])
3975
3976 def UpdateInformation(self):
3977 """Parse series file."""
3978 if self._filename is None:
3979 msg = 'Filename must be set'
3980 raise ValueError(msg)
3981
3982 with Path(self._filename).open() as fr:
3983 content = json.load(fr)
3984
3985 if 'files' not in content:
3986 msg = 'Invalid series file: missing "files" entry'
3987 raise ValueError(msg)
3988
3989 datasets = [
3990 SeriesDataSet(element['name'], element['time']) for element in content['files']
3991 ]
3992
3993 self._datasets = sorted(datasets)
3994 self._reader_type = self._deterimine_reader_type()
3995 self._time_values = sorted({dataset.time for dataset in self._datasets})
3996 self._time_mapping: dict[float, SeriesDataSet] = {
3997 dataset.time: dataset for dataset in self._datasets
3998 }
3999 self._SetActiveTime(self._time_values[0])
4000
4001 def Update(self) -> None:
4002 """Read data and store it."""
4003 self._active_reader = cast('_SeriesEachReader', self._active_reader)
4004 self._data_object = self._active_reader.read()
4005
4006 def _SetActiveTime(self, time_value) -> None:
4007 """Set active time."""
4008 self._active_dataset = self._time_mapping[time_value]
4009 self._reader_type = cast('type[_SeriesEachReader]', self._reader_type)
4010 self._active_reader = (
4011 self._reader_type(Path(self._directory) / self._active_dataset.name) # type: ignore[arg-type]
4012 )
4013
4014
4015 class SeriesReader(BaseReader['DataObject'], TimeReader, Generic[_SeriesEachReader]):
4016 """Class for reading .series file supported by Paraview.
4017
4018 .. versionadded:: 0.47.0
4019
4020 Examples
4021 --------
4022 >>> import pyvista as pv
4023 >>> from pyvista import examples
4024 >>> from pathlib import Path
4025 >>> filename = examples.download_file('vtu_series/wavy.zip')
4026 >>> Path(filename[0]).name
4027 'mesh.vtu.series'
4028 >>> reader = pv.get_reader(filename[0])
4029 >>> reader.time_values
4030 [0.0, 1.0, 2.0, 3.0, ... 12.0, 13.0, 14.0]
4031 >>> reader.set_active_time_point(5)
4032 >>> reader.active_time_value
4033 5.0
4034 >>> mesh = reader.read()
4035 >>> mesh.plot(scalars='z')
4036
4037 """
4038
4039 _class_reader: type[_SeriesReader[_SeriesEachReader]] = _SeriesReader[_SeriesEachReader]
4040 _output_types = get_args(_mesh_types)
4041
4042 @property
4043 def active_reader(self):
4044 """Return the active reader.
4045
4046 Returns
4047 -------
4048 pyvista.BaseReader
4049
4050 """
4051 return self.reader._active_reader
4052
4053 @property
4054 def datasets(self):
4055 """Return all datasets.
4056
4057 Returns
4058 -------
4059 list[pyvista.SeriesDataSet]
4060
4061 """
4062 return self.reader._datasets
4063
4064 @property
4065 def active_dataset(self):
4066 """Return all active datasets.
4067
4068 Returns
4069 -------
4070 pyvista.SeriesDataSet
4071
4072 """
4073 return self.reader._active_dataset
4074
4075 @property
4076 def time_values(self): # noqa: D102
4077 return self.reader._time_values
4078
4079 @property
4080 def number_time_points(self): # noqa: D102
4081 return len(self.reader._time_values)
4082
4083 def time_point_value(self, time_point): # noqa: D102
4084 return self.reader._time_values[time_point]
4085
4086 @property
4087 def active_time_value(self): # noqa: D102
4088 return self.reader._active_dataset.time
4089
4090 def set_active_time_value(self, time_value) -> None: # noqa: D102
4091 self.reader._SetActiveTime(time_value)
4092
4093 def set_active_time_point(self, time_point) -> None: # noqa: D102
4094 self.set_active_time_value(self.time_values[time_point])
4095
4096
4097 CLASS_READERS = {
4098 # Standard dataset readers:
4099 '.bmp': BMPReader,
4100 '.cas': FluentReader,
4101 '.case': EnSightReader,
4102 '.cgns': CGNSReader,
4103 '.cube': GaussianCubeReader,
4104 '.dat': TecplotReader,
4105 '.dcm': DICOMReader,
4106 '.dem': DEMReader,
4107 '.e': ExodusIIReader,
4108 '.ex2': ExodusIIReader,
4109 '.exo': ExodusIIReader,
4110 '.exii': ExodusIIReader,
4111 '.facet': FacetReader,
4112 '.foam': POpenFOAMReader,
4113 '.frd': FRDReader,
4114 '.g': BYUReader,
4115 '.gif': GIFReader,
4116 '.glb': GLTFReader,
4117 '.gltf': GLTFReader,
4118 '.h5': FLUENTCFFReader,
4119 '.hdf': HDFReader,
4120 '.hdr': HDRReader,
4121 '.img': DICOMReader,
4122 '.inp': AVSucdReader,
4123 '.jpeg': JPEGReader,
4124 '.jpg': JPEGReader,
4125 '.mha': MetaImageReader,
4126 '.mhd': MetaImageReader,
4127 '.mnc': MINCImageReader,
4128 '.mr': GESignaReader,
4129 '.nek5000': Nek5000Reader,
4130 '.neu': GambitReader,
4131 '.nhdr': NRRDReader,
4132 '.nii': NIFTIReader,
4133 '.nii.gz': NIFTIReader,
4134 '.nrrd': NRRDReader,
4135 '.obj': OBJReader,
4136 '.p3d': Plot3DMetaReader,
4137 '.pdb': PDBReader,
4138 '.ply': PLYReader,
4139 '.png': PNGReader,
4140 '.pnm': PNMReader,
4141 '.pts': PTSReader,
4142 '.pvd': PVDReader,
4143 '.pvti': XMLPImageDataReader,
4144 '.pvtk': VTKPDataSetReader,
4145 '.pvtr': XMLPRectilinearGridReader,
4146 '.pvtu': XMLPUnstructuredGridReader,
4147 '.raw': ParticleReader,
4148 '.res': MFIXReader,
4149 '.segy': SegYReader,
4150 '.sgy': SegYReader,
4151 '.slc': SLCReader,
4152 '.stl': STLReader,
4153 '.tif': TIFFReader,
4154 '.tiff': TIFFReader,
4155 '.tri': BinaryMarchingCubesReader,
4156 '.vrt': ProStarReader,
4157 '.vti': XMLImageDataReader,
4158 '.vtk': VTKDataSetReader,
4159 '.vtkhdf': HDFReader,
4160 '.vtm': XMLMultiBlockDataReader,
4161 '.vtmb': XMLMultiBlockDataReader,
4162 '.vtp': XMLPolyDataReader,
4163 '.vtpd': XMLPartitionedDataSetReader,
4164 '.vtr': XMLRectilinearGridReader,
4165 '.vts': XMLStructuredGridReader,
4166 '.vtu': XMLUnstructuredGridReader,
4167 '.series': SeriesReader,
4168 '.xdmf': XdmfReader,
4169 }
4170
4171
4172 def _extract_base_reader_generic_arg(cls: type[BaseReader[Any]]) -> str | None:
4173 """Return the forward-reference name from a ``BaseReader[X]`` base.
4174
4175 Walks ``cls.__orig_bases__`` looking for a ``BaseReader[X]`` base and
4176 returns ``X`` as a string (the forward-reference text, or a real
4177 class's ``__name__``). Returns ``None`` when the class is not a
4178 parameterized :class:`BaseReader` subclass.
4179 """
4180 import typing as _typing # noqa: PLC0415
4181
4182 for base in getattr(cls, '__orig_bases__', ()):
4183 origin = _typing.get_origin(base)
4184 if origin is None or not (isinstance(origin, type) and issubclass(origin, BaseReader)):
4185 continue
4186 args = _typing.get_args(base)
4187 if not args:
4188 continue
4189 arg = args[0]
4190 if isinstance(arg, _typing.ForwardRef):
4191 return arg.__forward_arg__
4192 if isinstance(arg, type):
4193 return arg.__name__
4194 return None
4195
4196
4197 def _derive_reader_output_types(
4198 cls: type[BaseReader[Any]],
4199 ) -> _mesh_types | tuple[_mesh_types, ...]:
4200 """Return the output type(s) declared by a reader class.
4201
4202 Uses the ``_output_types`` class attribute when a reader's ``BaseReader[X]``
4203 generic parameter is a widened common supertype (multi-output readers);
4204 otherwise returns the generic parameter as a ``_mesh_types`` literal.
4205 Raises :class:`TypeError` if neither source supplies a type.
4206 """
4207 override = getattr(cls, '_output_types', None)
4208 if override is not None:
4209 return override
4210 name = _extract_base_reader_generic_arg(cls)
4211 if name is None:
4212 msg = (
4213 f'Cannot derive output type for reader {cls.__name__!r}: '
4214 f'it does not parameterize BaseReader[X] and does not define '
4215 f'an `_output_types` class attribute.'
4216 )
4217 raise TypeError(msg)
4218 return cast('_mesh_types', name)
4219
4220
4221 # Define reader output types. Primarily used for testing and documentation.
4222 # The mapping is derived from each reader's ``BaseReader[X]`` parameterization
4223 # (with a per-class ``_output_types`` attribute on multi-output readers), so
4224 # adding a new reader automatically produces the right entry here. We seed the
4225 # iteration from :data:`CLASS_READERS` (every reader registered to a file
4226 # extension) — readers not registered to an extension stay out by design.
4227 _CLASS_READER_RETURN_TYPE: dict[type[BaseReader[Any]], _mesh_types | tuple[_mesh_types, ...]] = {
4228 cls: _derive_reader_output_types(cls) for cls in set(CLASS_READERS.values())
4229 }