read

Contents

read#

read(
filename: PathStrSeq,
force_ext: str | None = None,
file_format: str | None = None,
progress_bar: bool = False,
*,
cls: type[DataObject] | None = None,
validate: bool | None = None,
) → DataObject[source]#

Read any file type supported by vtk or meshio.

Automatically determines the correct reader to use then wraps the corresponding mesh as a pyvista object. Attempts native vtk readers first then tries to use meshio. Pickled meshes ('.pkl' or '.pickle') are also supported.

Remote URIs (https://, s3://, etc.) are downloaded to a temporary file automatically. Install fsspec for full protocol support (pip install pyvista[io]); pooch is used as a fallback for HTTP(S). Third-party reader plugins registered via pyvista.register_reader() are also checked.

See pyvista.get_reader() for list of vtk formats supported.

Tip

A native .pv binary format with zstd compression is available via the pyvista-zstd companion package, included in the io extra (pip install pyvista[io]). It is a compact, multi-threaded alternative to the built-in VTK formats below when file size or I/O latency matters. Third-party packages can register additional custom writers via pyvista.register_writer().

ImageData File Formats

File Format

File Extension(s)

read()

save()

BMP

.bmp

DEM

.dem

DICOM

.dcm, .img

GaussianCube

.cube

GESigna

.mr

GIF

.gif

HDF

.hdf, .vtkhdf

HDR

.hdr

JPEG

.jpeg, .jpg

Meta

.mha, .mhd

MINC

.mnc

NIFTI

.nii, .nii.gz

NRRD

.nhdr, .nrrd

PNG

.png

PNM

.pnm

SegY

.segy, .sgy

Series

.series

SLC

.slc

TIFF

.tif, .tiff

VTK

.vtk

VTKP

.pvtk

XML

.vti

XMLP

.pvti

RectilinearGrid File Formats

File Format

File Extension(s)

read()

save()

Series

.series

VTK

.vtk

VTKP

.pvtk

Xdmf

.xdmf

XMLP

.pvtr

XML

.vtr

StructuredGrid File Formats

File Format

File Extension(s)

read()

save()

SegY

.segy, .sgy

Series

.series

VTK

.vtk

VTKP

.pvtk

Xdmf

.xdmf

XML

.vts

PolyData File Formats

File Format

File Extension(s)

read()

save()

BinaryMarchingCubes

.tri

BYU

.g

Facet

.facet

GaussianCube

.cube

HDF

.hdf, .vtkhdf

OBJ

.obj

Particle

.raw

PDB

.pdb

PLY

.ply

PTS

.pts

Series

.series

STL

.stl

VTK

.vtk

VTKP

.pvtk

XML

.vtp

Houdini

.geo

IV

.iv

UnstructuredGrid File Formats

File Format

File Extension(s)

read()

save()

AVSucd

.inp

Fluent

.cas

FRD

.frd

Gambit

.neu

HDF

.hdf, .vtkhdf

MFIX

.res

Nek5000

.nek5000

ProStar

.vrt

Series

.series

VTK

.vtk

VTKP

.pvtk

Xdmf

.xdmf

XMLP

.pvtu

XML

.vtu

MultiBlock File Formats

File Format

File Extension(s)

read()

save()

CGNS

.cgns

EnSight

.case

ExodusII

.e, .ex2, .exii, .exo

FLUENTCFF

.h5

GLTF

.glb, .gltf

HDF

.hdf, .vtkhdf

Plot3DMeta

.p3d

POpenFOAM

.foam

PVD

.pvd

Series

.series

Tecplot

.dat

Xdmf

.xdmf

XML

.vtm, .vtmb

PartitionedDataSet File Formats

File Format

File Extension(s)

read()

save()

HDF

.hdf, .vtkhdf

Series

.series

XML

.vtpd

Note

See nschloe/meshio for formats supported by meshio. Be sure to install meshio with pip install meshio if you wish to use it.

Added in version 0.45: Support reading pickled meshes.

Warning

The pickle module is not secure. Only read pickled mesh files ('.pkl' or '.pickle') you trust. See pickle for details.

Parameters:
filenamestr, Path, Sequence[str | Path]

The string path to the file to read. If a list of files is given, a pyvista.MultiBlock dataset is returned with each file being a separate block in the dataset.

force_extstr, optional

If specified, the reader will be chosen by an extension which is different to its actual extension. For example, '.vts', '.vtu'.

file_formatstr, optional

Format of file to read with meshio.

progress_barbool, default: False

Optionally show a progress bar. Ignored when using meshio.

clstype, optional

Expected concrete type of the returned mesh. When given, the result is checked with isinstance() and a TypeError is raised on mismatch. Static type checkers (mypy, pyright) use this to narrow the return type to cls directly, so callers do not need typing.cast or a manual assert isinstance to access subclass-specific attributes, e.g. pv.read('file.vtu', cls=pv.UnstructuredGrid).

validatebool, optional

Forwarded to pyvista.wrap() as the validate keyword when using a vtk reader. When None (the default), honors pyvista.core.config.Config.validate_on_wrap. Pass False to skip the cheap array-length sanity check on very large trusted files. Has no effect for meshio or pickle code paths.

Added in version 0.48.

Returns:
pyvista.DataSet | pyvista.MultiBlock

Wrapped PyVista dataset. When cls is given, an instance of cls is returned instead.

See also

pyvista.DataObject.save

Save a mesh to file.

Examples

Load an example mesh.

>>> import pyvista as pv
>>> from pyvista import examples
>>> mesh = pv.read(examples.antfile)
>>> mesh.plot(cpos='xz')
../../../_images/pyvista-read-c72a28173b4b5230_00_00.png

Narrow the return type to a specific class. This avoids the need for a manual cast when working with type checkers such as mypy or pyright.

>>> mesh = pv.read('mesh.vtu', cls=pv.UnstructuredGrid)

Load a vtk file.

>>> mesh = pv.read('my_mesh.vtk')

Load a meshio file.

>>> mesh = pv.read('mesh.obj')

Load a pickled mesh file.

>>> mesh = pv.read('mesh.pkl')
Contents