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 with ReadDataSet.

Public Functions

VTKDataSetReader(const std::string &fileName)

Construct a reader to load data from the given file.

Example 2.13 Reading a legacy VTK file.
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 the ReadDataSet 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 PNGs

By default, the colors are stored in a field named “colors”, but the name of the field can optionally be changed using the SetPointFieldName method.

Example 2.14 Reading an image from a PNG file.
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 the ReadDataSet 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.html

By 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.

Example 2.15 Reading an image from a PNM file.
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 with ReadDataSet.

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.

enum class vtkm::io::FileType

Values:

enumerator ASCII
enumerator BINARY
Example 2.16 Writing a legacy VTK file.
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 the WriteDataSet 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.

enum class vtkm::io::ImageWriterBase::PixelDepth

Values:

enumerator PIXEL_8
enumerator PIXEL_16
Example 2.17 Writing an image to a PNG file.
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 the WriteDataSet 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.html

Public 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.

Example 2.18 Writing an image to a PNM file.
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}