read

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,
**kwargs,
) → DataObject[source]#

Read any file type supported by vtk or meshio.

Note

Reading a file and saving it in another format is also available via command-line interface. See pyvista convert for details.

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.

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 the tables below for a list of all supported file formats. See also pyvista.get_reader() for a similar list organized by reader class.

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 Image

.bmp

DICOM

.dcm, .img

Digital Elevation Model

.dem

Gaussian Cube

.cube

GE Signa MR

.mr

GIF Image

.gif

JPEG Image

.jpeg, .jpg

Legacy VTK

.vtk

Legacy VTK (partitioned)

.pvtk

MetaImage

.mha, .mhd

MINC Image

.mnc

NIfTI

.nii, .nii.gz

NRRD

.nhdr, .nrrd

PNG Image

.png

PNM Image

.pnm

Radiance HDR

.hdr

SEG-Y

.segy, .sgy

SLC Volume

.slc

TIFF Image

.tif, .tiff

VTK File Series

.series

VTK ImageData

.vti

VTK ImageData (partitioned)

.pvti

VTKHDF

.hdf, .vtkhdf

RectilinearGrid File Formats

File Format

File Extension(s)

read()

save()

Legacy VTK

.vtk

Legacy VTK (partitioned)

.pvtk

VTK File Series

.series

VTK RectilinearGrid

.vtr

VTK RectilinearGrid (partitioned)

.pvtr

XDMF

.xdmf

StructuredGrid File Formats

File Format

File Extension(s)

read()

save()

Legacy VTK

.vtk

Legacy VTK (partitioned)

.pvtk

SEG-Y

.segy, .sgy

VTK File Series

.series

VTK StructuredGrid

.vts

XDMF

.xdmf

PolyData File Formats

File Format

File Extension(s)

read()

save()

Binary Marching Cubes

.tri

Facet Polygonal Data

.facet

Gaussian Cube

.cube

Houdini Geometry

.geo

Legacy VTK

.vtk

Legacy VTK (partitioned)

.pvtk

MOVIE.BYU

.g

Open Inventor

.iv

Protein Data Bank

.pdb

PTS Point Cloud

.pts

Stanford PLY

.ply

Stereolithography

.stl

VTK File Series

.series

VTK Particle

.raw

VTK PolyData

.vtp

VTKHDF

.hdf, .vtkhdf

Wavefront OBJ

.obj

UnstructuredGrid File Formats

File Format

File Extension(s)

read()

save()

AVS UCD

.inp

EnSight

.case

Fluent Case

.cas

GAMBIT Neutral

.neu

Legacy VTK

.vtk

Legacy VTK (partitioned)

.pvtk

MFIX

.res

Nek5000

.nek5000

proSTAR

.vrt

VTK File Series

.series

VTK UnstructuredGrid

.vtu

VTK UnstructuredGrid (partitioned)

.pvtu

VTKHDF

.hdf, .vtkhdf

XDMF

.xdmf

ExplicitStructuredGrid File Formats

File Format

File Extension(s)

read()

save()

Eclipse GRDECL

.grdecl

Legacy VTK

.vtk

VTK File Series

.series

VTK UnstructuredGrid

.vtu

MultiBlock File Formats

File Format

File Extension(s)

read()

save()

3D Studio

.3ds

CGNS

.cgns

EnSight

.case

Exodus II

.e, .ex2, .exii, .exo

Exodus II (partitioned)

.e.N.p, .n.N.p

Fluent CFF Case

.h5

glTF 2.0

.glb, .gltf

OpenFOAM

.foam

ParaView Data

.pvd

PLOT3D Meta

.p3d

Tecplot

.dat

VRML 2.0

.vrml, .wrl

VTK File Series

.series

VTK MultiBlock

.vtm, .vtmb

VTKHDF

.hdf, .vtkhdf

XDMF

.xdmf

PartitionedDataSet File Formats

File Format

File Extension(s)

read()

save()

VTK File Series

.series

VTK PartitionedDataSet

.vtpd

VTKHDF

.hdf, .vtkhdf

Note

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

Warning

.pkl / .pickle files are not supported and will be refused. Pickle is a Python serialization protocol, not a mesh file format, and loading an untrusted pickle is arbitrary code execution (CWE-502). Use a real mesh format (.vtu, .vtp, .vtm, .vtk, .ply, .stl, and so on) or install pyvista-zstd for the .pv single-blob format.

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, for example, 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 code paths.

Added in version 0.48.

**kwargsdict, optional

Additional keyword arguments set on the reader after initialization but before reading the file.

This is effectively the same as using get_reader() and setattr.

reader = pyvista.get_reader(file)
for key, value in kwargs.items():
    setattr(reader, key, value)
mesh = reader.read()

When the extension resolves to a callable registered with pyvista.register_reader(), **kwargs is forwarded to that callable as handler(path, **kwargs) instead. progress_bar and validate are never forwarded, and a callable that overrides an extension PyVista already reads is bypassed entirely so that these arguments keep naming attributes of the built-in reader.

Added in version 0.49.

Returns:
pyvista.DataSet | pyvista.MultiBlock

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

Examples#

Download Python source code | Download Jupyter notebook

Load an example mesh.

>>> import pyvista as pv
>>> from pyvista import examples
>>> mesh = pv.read(examples.antfile)
>>> mesh.plot(cpos='xz')
../../../_images/pyvista-read-25ba4c8392d82266_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 .foam file and use keyword arguments to set reader-specific properties such as skip_zero_time.

>>> file = examples.download_openfoam_tubes(load=False)
>>> mesh = pv.read(file, skip_zero_time=True)

See Also#

pyvista.DataObject.save

Save a mesh to file.