Debian Codegraph @

pyvista/core/utilities/writer.py

raw
1 """Writers for writing vtk objects to file."""
2
3 from __future__ import annotations
4
5 from abc import abstractmethod
6 import contextlib
7 from typing import TYPE_CHECKING
8 from typing import ClassVar
9 from typing import Literal
10 from typing import get_args
11
12 import numpy as np
13
14 from pyvista.core import _validation
15 from pyvista.core.utilities.fileio import _CompressionOptions
16 from pyvista.core.utilities.fileio import _FileIOBase
17 from pyvista.core.utilities.fileio import _warn_multiblock_nested_field_data
18 from pyvista.core.utilities.misc import abstract_class
19
20 if TYPE_CHECKING:
21 from pathlib import Path
22
23 from pyvista import DataObject
24 from pyvista import NumpyArray
25 from pyvista import _vtk
26
27 _DataFormatOptions = Literal['binary', 'ascii']
28
29
30 @abstract_class
31 class _DataFormatMixin:
32 # Different writers use different values to indicate the current format
33 _ascii0_binary1: ClassVar[dict[int, _DataFormatOptions]] = {0: 'ascii', 1: 'binary'}
34 _ascii1_binary2: ClassVar[dict[int, _DataFormatOptions]] = {1: 'ascii', 2: 'binary'}
35 _format_mapping: ClassVar[dict[int, _DataFormatOptions]] = _ascii1_binary2
36
37 @property
38 @abstractmethod
39 def writer(self) -> _vtk.vtkWriter: ...
40
41 def __init__(self, *args, **kwargs) -> None:
42 super().__init__(*args, **kwargs)
43 self.data_format = 'binary'
44
45 @property
46 def data_format(self) -> _DataFormatOptions:
47 try:
48 mode = self.writer.GetDataMode() # type: ignore[attr-defined]
49 except AttributeError:
50 mode = self.writer.GetFileType() # type: ignore[attr-defined]
51 return self._format_mapping[mode]
52
53 @data_format.setter
54 def data_format(self, data_format: _DataFormatOptions) -> None:
55 _validation.check_contains(get_args(_DataFormatOptions), data_format, name='data format')
56 if data_format == 'binary':
57 try:
58 # DataWriter, PLYWriter, STLWriter
59 self.writer.SetDataModeToBinary() # type: ignore[attr-defined]
60 except AttributeError:
61 # XMLWriter
62 self.writer.SetFileTypeToBinary() # type: ignore[attr-defined]
63 else:
64 try:
65 # DataWriter, PLYWriter, STLWriter
66 self.writer.SetDataModeToAscii() # type: ignore[attr-defined]
67 except AttributeError:
68 # XMLWriter
69 self.writer.SetFileTypeToASCII() # type: ignore[attr-defined]
70
71
72 @abstract_class
73 class BaseWriter(_FileIOBase):
74 """The base writer class.
75
76 The base functionality includes writing data to a file,
77 and allowing access to the underlying vtk writer.
78
79 Parameters
80 ----------
81 path : str, Path
82 Path of the file to write to.
83
84 data_object : DataObject
85 Data object to write.
86
87 """
88
89 def __init__(self, path: str | Path, data_object: DataObject) -> None:
90 """Initialize writer."""
91 self._writer = self._vtk_class()
92 super().__init__()
93 self.path = path
94 self.data_object = data_object
95
96 @classmethod
97 def _get_extension_mappings(cls) -> list[dict[str, type]]:
98 import pyvista as pv # noqa: PLC0415
99
100 all_mesh_types = (
101 pv.ImageData,
102 pv.RectilinearGrid,
103 pv.StructuredGrid,
104 pv.PointSet,
105 pv.PolyData,
106 pv.UnstructuredGrid,
107 pv.ExplicitStructuredGrid,
108 pv.MultiBlock,
109 pv.PartitionedDataSet,
110 )
111 return [mesh_type._WRITERS for mesh_type in all_mesh_types]
112
113 @property
114 def writer(self) -> _vtk.vtkWriter:
115 """Return the vtk writer object.
116
117 Returns
118 -------
119 vtkWriter
120 An instance of the vtk writer.
121
122 """
123 return self._writer
124
125 @property
126 def path(self) -> str: # numpydoc ignore=RT01
127 """Return or set the filename or directory of the writer."""
128 return self.writer.GetFileName() # type: ignore[attr-defined]
129
130 @path.setter
131 def path(self, path: str | Path) -> None:
132 self.writer.SetFileName(str(path)) # type: ignore[attr-defined]
133
134 @property
135 def data_object(self) -> DataObject: # numpydoc ignore=RT01
136 """Get or set the dataset to write."""
137 return self._data_object
138
139 @data_object.setter
140 def data_object(self, data_object: DataObject) -> None:
141 self._data_object = data_object
142 self.writer.SetInputData(data_object)
143
144 def _execute_before_write(self) -> None:
145 """Execute code before calling `write()`.
146
147 Subclasses may optionally define this, e.g. to issue warnings.
148 """
149
150 def write(self) -> None:
151 """Write data to path."""
152 self._execute_before_write()
153 self.writer.Write()
154
155 def _apply_kwargs_safely(self, **kwargs) -> None:
156 """Try to set property keyword values and ignore attribute errors."""
157 for name, value in kwargs.items():
158 with contextlib.suppress(AttributeError):
159 setattr(self, name, value)
160
161
162 class BMPWriter(BaseWriter):
163 """BMPWriter for ``.bmp`` files.
164
165 Wraps :vtk:`vtkBMPWriter`.
166
167 .. versionadded:: 0.47.0
168
169 """
170
171 _vtk_module_name = 'vtkIOImage'
172 _vtk_class_name = 'vtkBMPWriter'
173
174
175 class DataSetWriter(BaseWriter, _DataFormatMixin):
176 """DataSetWriter for VTK legacy dataset files ``.vtk``.
177
178 Wraps :vtk:`vtkDataSetWriter`.
179
180 .. versionadded:: 0.47.0
181
182 """
183
184 _vtk_module_name = 'vtkIOLegacy'
185 _vtk_class_name = 'vtkDataSetWriter'
186
187 def _execute_before_write(self) -> None:
188 import pyvista as pv # noqa: PLC0415
189
190 # Warn if data will be lost
191 if isinstance(mesh := self.data_object, pv.ImageData) and not np.allclose(
192 mesh.direction_matrix, np.eye(3)
193 ):
194 msg = (
195 'The direction matrix for ImageData cannot be saved using the '
196 'legacy `.vtk` format.\n'
197 'See https://gitlab.kitware.com/vtk/vtk/-/issues/19663 \n'
198 'Use the `.vti` extension instead (XML format).'
199 )
200 raise ValueError(msg)
201
202
203 class HDFWriter(BaseWriter):
204 """HDFWriter for ``.hdf`` and ``.vtkhdf`` files.
205
206 Wraps :vtk:`vtkHDFWriter`.
207
208 .. versionadded:: 0.47.0
209
210 """
211
212 _vtk_module_name = 'vtkIOHDF'
213 _vtk_class_name = 'vtkHDFWriter'
214
215 def _execute_before_write(self) -> None:
216 import pyvista as pv # noqa: PLC0415
217
218 if not isinstance(mesh := self.data_object, pv.MultiBlock):
219 return
220 # Check multiblock block types
221 if pv.vtk_version_info < (9, 5, 0):
222 if mesh.is_nested:
223 msg = (
224 'Nested MultiBlocks are not supported by the .vtkhdf format in VTK 9.4.'
225 '\nUpgrade to VTK>=9.5 for this functionality.'
226 )
227 raise TypeError(msg)
228 if type(None) in mesh.block_types:
229 msg = (
230 'Saving None blocks is not supported by the .vtkhdf format in VTK 9.4.'
231 '\nUpgrade to VTK>=9.5 for this functionality.'
232 )
233 raise TypeError(msg)
234
235 supported_block_types: list[type] = [
236 pv.PolyData,
237 pv.UnstructuredGrid,
238 type(None),
239 pv.MultiBlock,
240 pv.PartitionedDataSet,
241 ]
242 for id_, name, block in mesh.recursive_iterator('all'):
243 if type(block) not in supported_block_types:
244 from pyvista.core.filters.composite import _format_nested_index # noqa: PLC0415
245
246 index_fmt = _format_nested_index(id_)
247 msg = (
248 f"Block at index {index_fmt} with name '{name}' has type "
249 f'{block.__class__.__name__!r} '
250 f'which cannot be saved to the .vtkhdf format.\n'
251 f'Supported types are: {[typ.__name__ for typ in supported_block_types]}.'
252 )
253 raise TypeError(msg)
254
255
256 class HoudiniPolyDataWriter(BaseWriter):
257 """HoudiniPolyDataWriter for Houdini geometry ``.geo`` files.
258
259 Wraps :vtk:`vtkHoudiniPolyDataWriter`.
260
261 .. versionadded:: 0.47.0
262
263 """
264
265 _vtk_module_name = 'vtkIOGeometry'
266 _vtk_class_name = 'vtkHoudiniPolyDataWriter'
267
268
269 class IVWriter(BaseWriter):
270 """IVWriter for OpenInventor ``.iv`` files.
271
272 Wraps :vtk:`vtkIVWriter`.
273
274 .. versionadded:: 0.47.0
275
276 """
277
278 _vtk_module_name = 'vtkIOGeometry'
279 _vtk_class_name = 'vtkIVWriter'
280
281
282 class JPEGWriter(BaseWriter):
283 """JPEGWriter for ``.jpeg`` and ``.jpg`` files.
284
285 Wraps :vtk:`vtkJPEGWriter`.
286
287 .. versionadded:: 0.47.0
288
289 """
290
291 _vtk_module_name = 'vtkIOImage'
292 _vtk_class_name = 'vtkJPEGWriter'
293
294
295 class NIFTIImageWriter(BaseWriter):
296 """NIFTIImageWriter for ``.nii`` and ``.nii.gz`` files.
297
298 Wraps :vtk:`vtkNIFTIImageWriter`.
299
300 .. versionadded:: 0.47.0
301
302 """
303
304 _vtk_module_name = 'vtkIOImage'
305 _vtk_class_name = 'vtkNIFTIImageWriter'
306
307
308 class OBJWriter(BaseWriter):
309 """OBJWriter for Wavefront ``.obj`` files.
310
311 Wraps :vtk:`vtkOBJWriter`.
312
313 .. versionadded:: 0.47.0
314
315 """
316
317 _vtk_module_name = 'vtkIOGeometry'
318 _vtk_class_name = 'vtkOBJWriter'
319
320
321 class PLYWriter(BaseWriter, _DataFormatMixin):
322 """PLYWriter for PLY polygonal ``.ply`` files.
323
324 Wraps :vtk:`vtkPLYWriter`.
325
326 .. versionadded:: 0.47.0
327
328 """
329
330 _vtk_module_name = 'vtkIOPLY'
331 _vtk_class_name = 'vtkPLYWriter'
332
333 @property
334 def texture(self) -> str | None: # numpydoc ignore=RT01
335 """Get or set a texture array to be written."""
336 return self.writer.GetArrayName() # type: ignore[attr-defined]
337
338 @texture.setter
339 def texture(self, texture: str | NumpyArray[float] | None) -> None:
340 if texture is None:
341 self.writer.SetArrayName(None) # type: ignore[attr-defined]
342 return
343 _validation.check_instance(texture, (str, np.ndarray), name='texture')
344 if isinstance(texture, str):
345 array_name = texture
346 array = self.data_object[array_name] # type: ignore[index]
347 else:
348 array_name = '_color_array'
349 array = texture
350 self.data_object[array_name] = texture
351
352 _validation.check_subdtype(array, 'uint8', name='texture')
353 self.writer.SetArrayName(array_name) # type: ignore[attr-defined]
354
355 # enable alpha channel if applicable
356 enable_alpha = array.shape[-1] == 4
357 self.writer.SetEnableAlpha(enable_alpha) # type: ignore[attr-defined]
358
359
360 class PNGWriter(BaseWriter):
361 """PNGWriter for ``.png`` files.
362
363 Wraps :vtk:`vtkPNGWriter`.
364
365 .. versionadded:: 0.47.0
366
367 """
368
369 _vtk_module_name = 'vtkIOImage'
370 _vtk_class_name = 'vtkPNGWriter'
371
372
373 class PNMWriter(BaseWriter):
374 """PNMWriter for ``.pnm`` files.
375
376 Wraps :vtk:`vtkPNMWriter`.
377
378 .. versionadded:: 0.47.0
379
380 """
381
382 _vtk_module_name = 'vtkIOImage'
383 _vtk_class_name = 'vtkPNMWriter'
384
385
386 class PolyDataWriter(BaseWriter, _DataFormatMixin):
387 """PolyDataWriter for legacy VTK PolyData ``.vtk`` files.
388
389 Wraps :vtk:`vtkPolyDataWriter`.
390
391 .. versionadded:: 0.47.0
392
393 """
394
395 _vtk_module_name = 'vtkIOLegacy'
396 _vtk_class_name = 'vtkPolyDataWriter'
397
398
399 class RectilinearGridWriter(BaseWriter, _DataFormatMixin):
400 """RectilinearGridWriter for legacy VTK rectilinear grid ``.vtk`` files.
401
402 Wraps :vtk:`vtkRectilinearGridWriter`.
403
404 .. versionadded:: 0.47.0
405
406 """
407
408 _vtk_module_name = 'vtkIOLegacy'
409 _vtk_class_name = 'vtkRectilinearGridWriter'
410
411
412 class STLWriter(BaseWriter, _DataFormatMixin):
413 """STLWriter for stereolithography ``.stl`` files.
414
415 Wraps :vtk:`vtkSTLWriter`.
416
417 .. versionadded:: 0.47.0
418
419 """
420
421 _vtk_module_name = 'vtkIOGeometry'
422 _vtk_class_name = 'vtkSTLWriter'
423
424
425 class SimplePointsWriter(BaseWriter, _DataFormatMixin):
426 """SimplePointsWriter for simple point-set ``.xyz`` files.
427
428 Wraps :vtk:`vtkSimplePointsWriter`.
429
430 .. versionadded:: 0.47.0
431
432 """
433
434 _vtk_module_name = 'vtkIOLegacy'
435 _vtk_class_name = 'vtkSimplePointsWriter'
436
437
438 class StructuredGridWriter(BaseWriter, _DataFormatMixin):
439 """StructuredGridWriter for legacy VTK structured grid ``.vtk`` files.
440
441 Wraps :vtk:`vtkStructuredGridWriter`.
442
443 .. versionadded:: 0.47.0
444
445 """
446
447 _vtk_module_name = 'vtkIOLegacy'
448 _vtk_class_name = 'vtkStructuredGridWriter'
449
450
451 class TIFFWriter(BaseWriter):
452 """TIFFWriter for ``.tif`` and ``.tiff`` files.
453
454 Wraps :vtk:`vtkTIFFWriter`.
455
456 .. versionadded:: 0.47.0
457
458 """
459
460 _vtk_module_name = 'vtkIOImage'
461 _vtk_class_name = 'vtkTIFFWriter'
462
463
464 class UnstructuredGridWriter(BaseWriter, _DataFormatMixin):
465 """UnstructuredGridWriter for legacy VTK unstructured grid ``.vtk`` files.
466
467 Wraps :vtk:`vtkUnstructuredGridWriter`.
468
469 .. versionadded:: 0.47.0
470
471 """
472
473 _vtk_module_name = 'vtkIOLegacy'
474 _vtk_class_name = 'vtkUnstructuredGridWriter'
475
476
477 @abstract_class
478 class _XMLWriter(BaseWriter, _DataFormatMixin):
479 _format_mapping = _DataFormatMixin._ascii0_binary1
480
481 def __init__(self, *args, **kwargs) -> None:
482 super().__init__(*args, **kwargs)
483 self.compression = 'zlib'
484
485 @property
486 def compression(self) -> _CompressionOptions:
487 return self._compression
488
489 @compression.setter
490 def compression(self, compression: _CompressionOptions) -> None:
491 supported = get_args(_CompressionOptions)
492 _validation.check_contains(supported, must_contain=compression, name='compression')
493 self._compression = compression
494 if compression is None:
495 self.writer.SetCompressorTypeToNone() # type: ignore[attr-defined]
496 elif compression == 'zlib':
497 self.writer.SetCompressorTypeToZLib() # type: ignore[attr-defined]
498 elif compression == 'lz4':
499 self.writer.SetCompressorTypeToLZ4() # type: ignore[attr-defined]
500 else:
501 self.writer.SetCompressorTypeToLZMA() # type: ignore[attr-defined]
502
503
504 class XMLImageDataWriter(_XMLWriter):
505 """XMLImageDataWriter for VTK XML image data ``.vti`` files.
506
507 Wraps :vtk:`vtkXMLImageDataWriter`.
508
509 .. versionadded:: 0.47.0
510
511 """
512
513 _vtk_module_name = 'vtkIOXML'
514 _vtk_class_name = 'vtkXMLImageDataWriter'
515
516
517 class XMLMultiBlockDataWriter(_XMLWriter):
518 """XMLMultiBlockDataWriter for VTK XML multiblock ``.vtm`` files.
519
520 Wraps :vtk:`vtkXMLMultiBlockDataWriter`.
521
522 .. versionadded:: 0.47.0
523
524 """
525
526 _vtk_module_name = 'vtkIOXML'
527 _vtk_class_name = 'vtkXMLMultiBlockDataWriter'
528
529 def _execute_before_write(self) -> None:
530 _warn_multiblock_nested_field_data(self.data_object)
531
532
533 class XMLPartitionedDataSetWriter(_XMLWriter):
534 """XMLPartitionedDataSetWriter for VTK XML partitioned datasets ``.vtpd`` files.
535
536 Wraps :vtk:`vtkXMLPartitionedDataSetWriter`.
537
538 .. versionadded:: 0.47.0
539
540 """
541
542 _vtk_module_name = 'vtkIOParallelXML'
543 _vtk_class_name = 'vtkXMLPartitionedDataSetWriter'
544
545
546 class XMLPolyDataWriter(_XMLWriter):
547 """XMLPolyDataWriter for VTK XML polydata ``.vtp`` files.
548
549 Wraps :vtk:`vtkXMLPolyDataWriter`.
550
551 .. versionadded:: 0.47.0
552
553 """
554
555 _vtk_module_name = 'vtkIOXML'
556 _vtk_class_name = 'vtkXMLPolyDataWriter'
557
558
559 class XMLRectilinearGridWriter(_XMLWriter):
560 """XMLRectilinearGridWriter for VTK XML rectilinear grid ``.vtr`` files.
561
562 Wraps :vtk:`vtkXMLRectilinearGridWriter`.
563
564 .. versionadded:: 0.47.0
565
566 """
567
568 _vtk_module_name = 'vtkIOXML'
569 _vtk_class_name = 'vtkXMLRectilinearGridWriter'
570
571
572 class XMLStructuredGridWriter(_XMLWriter):
573 """XMLStructuredGridWriter for VTK XML structured grid ``.vts`` files.
574
575 Wraps :vtk:`vtkXMLStructuredGridWriter`.
576
577 .. versionadded:: 0.47.0
578
579 """
580
581 _vtk_module_name = 'vtkIOXML'
582 _vtk_class_name = 'vtkXMLStructuredGridWriter'
583
584
585 class XMLUnstructuredGridWriter(_XMLWriter):
586 """XMLUnstructuredGridWriter for VTK XML unstructured grid ``.vtu`` files.
587
588 Wraps :vtk:`vtkXMLUnstructuredGridWriter`.
589
590 .. versionadded:: 0.47.0
591
592 """
593
594 _vtk_module_name = 'vtkIOXML'
595 _vtk_class_name = 'vtkXMLUnstructuredGridWriter'