openmesh/Doc/tutorial_08.docu

/** \page tutorial_08 Using IO::Options

This example shows:

- How to control the behaviour of \c Mesh::IO::read_mesh(),
- How to control the behaviour of \c Mesh::IO::write_mesh().

The class \c OpenMesh::IO::Options can be used when reading/writing a
mesh. It controls the behaviour of the reader/writer modules by means
of enabled/disabled bits in a bitset. The class provides an interface
for enabling, disabling and verifying the bits in the set. We
distinguish between

-# mode bits - control binary reading/writing
 - Options::Binary
 - Options::MSB
 - Options::LSB
 - Options::Swap (MSB|LSB)
-# property bits - controls which standard properties to read/write
 - Options::VertexNormal
 - Options::VertexTexCoord
 - Options::VertexColor
 - Options::FaceNormal
 - Options::FaceColor
 - Options::ColorAlpha
 - Options::ColorFloat
 - Options::Custom

These bits have different effects when reading or writing. The file
format itself is selected by the extension of the filename. 
  
Below in the table you can see what options are suported by which reader/writer (it is possible that the data format can support more).
ASCII is not a real option and will be selected, if binary was not defined.

<TABLE>
<CAPTION><EM>Reader/Writer Feature Support List</EM></CAPTION>
<TR><TH>Format/Option<TD>ASCII<TD>Binary<TD>MSB<TD>LSB<TD>Swap<TD>VertexNormal<TD>VertexColor<TD>VertexTexCoord<TD>EdgeColor<TD>FaceNormal<TD>FaceColor<TD>FaceTexCoord<TD>ColorAlpha<TD>ColorFloat<TD>Custom
<TR><TH>OBJ<TD>x<TD> <TD> <TD> <TD> <TD>x<TD>x *)<TD>x<TD> <TD>x<TD>x<TD>x<TD><TD><TD> 
<TR><TH>OFF<TD>x<TD>x<TD> <TD>x<TD> <TD>x<TD>x<TD>x<TD> <TD> <TD>x<TD> <TD>x<TD>x<TD> 
<TR><TH>PLY<TD>x<TD>x<TD>x<TD>x<TD> <TD>x<TD>x<TD>x<TD> <TD> <TD> <TD> <TD>x<TD>x<TD>x **)
<TR><TH>OM<TD> <TD>x<TD>x<TD>x<TD>x<TD>x<TD>x<TD>x<TD><TD>x<TD>x<TD><TD><TD><TD>x (\ref tutorial_09 )
<TR><TH>STL<TD>x<TD>x<TD><TD>x<TD><TD><TD><TD><TD><TD>x<TD><TD><TD><TD><TD>
<TR><TH>VTK ***)<TD>x<TD><TD><TD><TD><TD><TD><TD><TD><TD><TD><TD><TD><TD><TD>
</TABLE>

\*) can <i>read</i> the non-standard extension vertex colors (floats only): 
\li defined with vc (e.g. used by meshlab)
\li colors encoded in a vertex line (v followed by 6 values)

\**) only ascii version and only vertex and face properties with fundamental types

\***) no reader exists

The program does not more than providing a command line based
interface to select the option bits for reading/writing and to request
mesh properties. Hence illegal combinations are possible and will
result in a failure of the program. (The input file won't be damaged
in this case, but be careful where you put the ouput file!)


<h5>Reading meshes</h5>

When reading a file the mode bits are used to give the reader an
advice or hint. Depending on the format we can help the reader to
interpret the data correctly. First of all we can tell it that the
file contains binary data.

\dontinclude 08-io_options/io_options.cc
\skipline ropt += IO::Options::Binary

Further on we can ask the reader two swap the byte-order.

\skipline ropt += IO::Options::Swap

(Both can be done via the command line with the options -b and -s,
respectively.)

By default the geometry and the topology is restored from the
file. The file might contain more, especially it could provide normals
or texture coordinates.  We can examine the property bits after
reading to find out what else is available:

\dontinclude 08-io_options/io_options.cc
\skipline ropt.check(IO::Options::VertexNormal)

If a property bit is set it does not mean, that it has been restored
as well.  The property must have been requested prior reading the
file. (The demo program offers the command line option \c -Xv[nct] and
\c -Xf[nc] to request vertex and face properties.)

<h5>Writing meshes</h5>

When writing the mesh the mode bits apparently control whether to use
the binary variant and the desired byte-ordering. For example, if we
choose binary mode and want to swap the byte order, we set

\skipline wopt += IO::Options::Binary
\skipline wopt += IO::Options::Swap

If the format does not specify the byte order the system byte order is
used. If the format does not support binary storage, the mode bits are
ignored.

If the format supports storing additional information, which are
conform with the standard properties, we can use the property bits to
tell the writer what we would like to have stored. If we would like to
store the vertex normals we simply set

\skipline wopt += IO::Options::VertexNormal

Finally we can write the data to the file

\dontinclude 08-io_options/io_options.cc
\skipline write_mesh

The method returns false on error, which might have three different reasons:

-# the option is not supported by the choosen format
-# a selected standard property is not available
-# a 'system' error like
   - could not open the file due to access rights
   - disk space exhausted during write
   - ...


The complete source looks like this:

\include 08-io_options/io_options.cc

*/