\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}

\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}

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