2.5. File I/O
Before VTK‑m can be used to process data, data need to be loaded into the
system.
VTK‑m comes with a basic file I/O package to get started developing very
quickly.
All the file I/O classes are declared under the vtkm::io
namespace.
Did You Know?
Files are just one of many ways to get data in and out of VTK‑m. In later chapters we explore ways to define VTK‑m data structures of increasing power and complexity. In particular, Section 2.4.1 (Building Data Sets) describes how to build VTK‑m data set objects and Section ref{sec:ArrayHandle:Adapting} documents how to adapt data structures defined in other libraries to be used directly in VTK‑m.
2.5.1. Readers
All reader classes provided by VTK‑m are located in the vtkm::io
namespace.
The general interface for each reader class is to accept a filename in the constructor and to provide a ReadDataSet
method to load the data from disk.
The data in the file are returned in a vtkm::cont::DataSet
object
as described in Chapter 2.4 (Data Sets), but it is sufficient to know that a DataSet
can be passed among readers, writers, filters, and rendering units.
2.5.1.1. Legacy VTK File Reader
Legacy VTK files are a simple open format for storing visualization data.
These files typically have a .vtk
extension.
Legacy VTK files are popular because they are simple to create and read and
are consequently supported by a large number of tools.
The format of legacy VTK files is well documented in The VTK User’s
Guide [as well as online](https://examples.vtk.org/site/VTKFileFormats/).
Legacy VTK files can also be read and written with tools like ParaView and VisIt.
Legacy VTK files can be read using the vtkm::io::VTKDataSetReader
class.
-
class VTKDataSetReader : public vtkm::io::VTKDataSetReaderBase
Reads a legacy VTK file.
By convention, legacy VTK files have a
.vtk
extension. This class should be constructed with a filename, and the data read withReadDataSet
.Public Functions
-
VTKDataSetReader(const std::string &fileName)
Construct a reader to load data from the given file.
-
VTKDataSetReader(const std::string &fileName)
1#include <vtkm/io/VTKDataSetReader.h>
2
3vtkm::cont::DataSet OpenDataFromVTKFile()
4{
5 vtkm::io::VTKDataSetReader reader("data.vtk");
6
7 return reader.ReadDataSet();
8}
2.5.1.2. Image Readers
VTK‑m provides classes to read images from some standard image formats.
These readers will store the data in a vtkm::cont::DataSet
object with the colors stored as a named point field.
The colors are read as 4-component RGBA vectors for each pixel.
Each component in the pixel color is stored as a 32-bit float between 0 and 1.
Portable Network Graphics (PNG) files can be read using the vtkm::io::ImageReaderPNG
class.
-
class ImageReaderPNG : public vtkm::io::ImageReaderBase
Reads images using the PNG format.
ImageReaderPNG
is constructed with the name of the file to read. The data from the file is read by calling theReadDataSet
method.ImageReaderPNG
will automatically upsample/downsample read image data to a 16 bit RGB no matter how the image is compressed. It is up to the user to decide the pixel format for input PNGsBy default, the colors are stored in a field named “colors”, but the name of the field can optionally be changed using the
SetPointFieldName
method.
1#include <vtkm/io/ImageReaderPNG.h>
2
3vtkm::cont::DataSet OpenDataFromPNG()
4{
5 vtkm::io::ImageReaderPNG imageReader("data.png");
6 imageReader.SetPointFieldName("pixel_colors");
7 return imageReader.ReadDataSet();
8}
Portable anymap (PNM) files can be read using the vtkm::io::ImageReaderPNM
class.
-
class ImageReaderPNM : public vtkm::io::ImageReaderBase
Reads images using the PNM format.
ImageReaderPNM
is constructed with the name of the file to read. The data from the file is read by calling theReadDataSet
method.Currently,
ImageReaderPNM
only supports files using the portable pixmap (PPM) format (with magic number `P6’). These files are most commonly stored with a.ppm
extension although the.pnm
extension is also valid. More details on the PNM format can be found here at http://netpbm.sourceforge.net/doc/ppm.htmlBy default, the colors are stored in a field named “colors”, but the name of the field can optionally be changed using the
SetPointFieldName
method.
Like for PNG files, a vtkm::io::ImageReaderPNM
is constructed with the name of the file to read from.
1#include <vtkm/io/ImageReaderPNM.h>
2
3vtkm::cont::DataSet OpenDataFromPNM()
4{
5 vtkm::io::ImageReaderPNM imageReader("data.ppm");
6 imageReader.SetPointFieldName("pixels");
7 return imageReader.ReadDataSet();
8}
2.5.2. Writers
All writer classes provided by VTK‑m are located in the vtkm::io
namespace.
The general interface for each writer class is to accept a filename in the constructor and to provide a WriteDataSet
method to save data to the disk.
The WriteDataSet
method takes a vtkm::cont::DataSet
object as an argument, which contains the data to write to the file.
2.5.2.1. Legacy VTK File Writer
Legacy VTK files can be written using the vtkm::io::VTKDataSetWriter
class.
-
class VTKDataSetWriter
Reads a legacy VTK file.
By convention, legacy VTK files have a
.vtk
extension. This class should be constructed with a filename, and the data read withReadDataSet
.Public Functions
-
VTKDataSetWriter(const std::string &fileName)
Construct a writer to save data to the given file.
-
void WriteDataSet(const vtkm::cont::DataSet &dataSet) const
Write data from the given
DataSet
object to the file specified in the constructor.
-
vtkm::io::FileType GetFileType() const
Get whether the file will be written in ASCII or binary format.
-
void SetFileType(vtkm::io::FileType type)
Set whether the file will be written in ASCII or binary format.
-
inline void SetFileTypeToAscii()
Set whether the file will be written in ASCII or binary format.
-
inline void SetFileTypeToBinary()
Set whether the file will be written in ASCII or binary format.
-
VTKDataSetWriter(const std::string &fileName)
1#include <vtkm/io/VTKDataSetWriter.h>
2
3void SaveDataAsVTKFile(vtkm::cont::DataSet data)
4{
5 vtkm::io::VTKDataSetWriter writer("data.vtk");
6
7 writer.WriteDataSet(data);
8}
2.5.2.2. Image Writers
VTK‑m provides classes to some standard image formats.
These writers store data in a vtkm::cont::DataSet
.
The data must be a 2D structure with the colors stored in a point field.
(See Chapter 2.4 (Data Sets) for details on vtkm::cont::DataSet
objects.)
Portable Network Graphics (PNG) files can be written using the vtkm::io::ImageWriterPNG
class.
-
class ImageWriterPNG : public vtkm::io::ImageWriterBase
Writes images using the PNG format.
ImageWriterPNG
is constructed with the name of the file to write. The data is written to the file by calling theWriteDataSet
method.When writing files,
ImageReaderPNG
automatically compresses data to optimal sizes relative to the actual bit complexity of the provided image.
By default, PNG files are written as RGBA colors using 8-bits for each component.
You can change the format written using the vtkm::io::ImageWriterPNG::SetPixelDepth()
method.
This takes an item in the vtkm::io::ImageWriterPNG::PixelDepth
enumeration.
1#include <vtkm/io/ImageWriterPNG.h>
2
3void WriteToPNG(const vtkm::cont::DataSet& dataSet)
4{
5 vtkm::io::ImageWriterPNG imageWriter("data.png");
6 imageWriter.SetPixelDepth(vtkm::io::ImageWriterPNG::PixelDepth::PIXEL_16);
7 imageWriter.WriteDataSet(dataSet);
8}
Portable anymap (PNM) files can be written using the vtkm::io::ImageWriterPNM
class.
-
class ImageWriterPNM : public vtkm::io::ImageWriterBase
Writes images using the PNM format.
ImageWriterPNM
is constructed with the name of the file to write. The data is written to the file by calling theWriteDataSet
method.ImageWriterPNM
writes images in PNM format (for magic number P6). These files are most commonly stored with a.ppm
extension although the.pnm
extension is also valid. More details on the PNM format can be found at http://netpbm.sourceforge.net/doc/ppm.htmlPublic Functions
-
virtual void Write(vtkm::Id width, vtkm::Id height, const ColorArrayType &pixels) override
Attempts to write the ImageDataSet to a PNM file.
The MaxColorValue set in the file with either be selected from the stored MaxColorValue member variable, or from the templated type if MaxColorValue hasn’t been set from a read file.
-
virtual void Write(vtkm::Id width, vtkm::Id height, const ColorArrayType &pixels) override
1#include <vtkm/io/ImageWriterPNM.h>
2
3void WriteToPNM(const vtkm::cont::DataSet& dataSet)
4{
5 vtkm::io::ImageWriterPNM imageWriter("data.ppm");
6 imageWriter.SetPixelDepth(vtkm::io::ImageWriterPNM::PixelDepth::PIXEL_16);
7 imageWriter.WriteDataSet(dataSet);
8}