\chapter{File I/O}
\label{chap:FileIO}

\index{I/O|(}
\index{file I/O|(}

Before \VTKm can be used to process data, data need to be loaded into the
system. \VTKm comes with a basic file I/O package to get started developing
very quickly. All the file I/O classes are declared under the \vtkmio{}
namespace.

\begin{didyouknow}
  Files are just one of many ways to get data in and out of \VTKm.
  In later chapters we explore ways to define \VTKm data structures of increasing power and complexity.
  In particular, Section \ref{sec:DataSets:Building} describes how to build \VTKm data set objects and Section \ref{sec:ArrayHandle:Adapting} documents how to adapt data structures defined in other libraries to be used directly in \VTKm.
\end{didyouknow}

\section{Readers}

\index{file I/O!read|(}
\index{read file|(}

All reader classes provided by \VTKm are located in the \vtkmioreader{}
namespace. The general interface for each reader class is to accept a
filename in the constructor and to provide a \textcode{ReadDataSet} method
to load the data from disk.

The data in the file are returned in a \vtkmcont{DataSet} object as described in Chapter~\ref{chap:DataSets}, but it is sufficient to known that a \textidentifier{DataSet} can be passed around readers, writers, filters, and rendering units.

\subsection{Legacy VTK File Reader}

Legacy VTK files are a simple open format for storing visualization data.
These files typically have a \textfilename{.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 \textit{The VTK User's Guide}.\footnote{A free
  excerpt describing the file format is available at
  \url{http://www.vtk.org/Wiki/File:VTK-File-Formats.pdf}.} Legacy VTK
files can also be read and written with tools like ParaView and VisIt.

Legacy VTK files can be read using the \vtkmioreader{VTKDataSetReader}
class. The constructor for this class takes a string containing the
filename. The \classmember*{VTKDataSetReader}{ReadDataSet} method reads the data from the
previously indicated file and returns a \vtkmcont{DataSet} object, which
can be used with filters and rendering.

\vtkmlisting{Reading a legacy VTK file.}{VTKDataSetReader.cxx}

\subsection{Image Reader}

\VTKm allows you to read images from PNM and PNG files.
All readers have no argument constructors and supply a \textidentifier{readFromFile} method that reads a file from the file-system path provided and returns a \vtkmcont{DataSet}.
This \vtkmcont{DataSet} is a 2D uniform explicit cell-set with a single point field named "pixel-data".
The data in the \vtkmcont{DataSet} is stored as \vtkm{Vec4f\_32} with rgba channels.
The PNM file reader only supports PNM files with the MagicNumber of P6 (aka PMM files).
The PNG file reader can parse from any underlying image type correctly, and upcoverts it to a 16 bit rgba image type.
Additionally, all ImageReaders support creating a \vtkmcont{DataSet} from a \vtkmrendering{Canvas}.

\vtkmlisting{Reading an Image.}{VTKmImageReader.cxx}

\index{read file|)}
\index{file I/O!read|)}

\section{Writers}

\index{file I/O!write|(}
\index{write file|(}

All writer classes provided by \VTKm are located in the \vtkmiowriter{}
namespace. The general interface for each writer class is to accept a
filename in the constructor and to provide a \textcode{WriteDataSet} method
to save data to the disk. The \textcode{WriteDataSet} method takes a
\vtkmcont{DataSet} object as an argument, which contains the data to write
to the file.

\subsection{Legacy VTK File Writer}

\index{write file|)}
\index{file I/O!write|)}

Legacy VTK files can be written using the \vtkmiowriter{VTKDataSetWriter}
class. The constructor for this class takes a string containing the
filename. The \classmember*{VTKDataSetWriter}{WriteDataSet} method takes a \vtkmcont{DataSet}
object and writes its data to the previously indicated file.

\vtkmlisting{Writing a legacy VTK file.}{VTKDataSetWriter.cxx}

\subsection{Image Writer}

\VTKm allows you to read images from PNM and PNG files.
All writers have no argument constructors and supply a \textidentifier{writeToFile} method that writes a supplied \vtkmcont{DataSet} to the file-system path provided.
The input \vtkmcont{DataSet} is a 2D uniform explicit cell-set with a single point field named "pixel-data".
The data in the \vtkmcont{DataSet} must be stored as \vtkm{Vec4f\_32} with rgba channels.
The PNM file writer only supports writing PNM files with the MagicNumber of P6 (aka PMM files).
The PNG file writer automatically compresses the PNG file to minimize the image size without losing pixel data.
Additionally, all ImageWriters support accepting a \textidentifier{MaxColorValue} to provide a hint on setting the color size when writing out the data in the \vtkmcont{DataSet}.

\vtkmlisting{Writing an Image.}{VTKmImageWriter.cxx}

\index{file I/O|)}
\index{I/O|)}
