The Streaming Mesh API library ( SM_API ) contains all the files/functions/modules for working with meshes of vertices and triangles.

The Streaming Mesh Library consists of 'streaming mesh' readers, Writers, and utilities

Overview

SM Readers represent the concept of extracting points and triangles from an input stream (or file) SM Writers represent the concept of writing points and triangles to an output stream (or file)

All readers / writers are derived from the same base class which supports the concepts

Readers / Writers can be ...

Non-streaming

• which implies the entire stream (file) must be in memory before you can safely process any element (vertex, triangle)

Streaming

• Only a small portion of the file needs to be in memory before you start processing elements
• Streaming is made easier by the concept of finalization
  • A Finalization command allows us to know when we are done with vertices and triangles
  • IE we have seen all triangles which are incident on this vertex
  • Once a vertex is finalized, we can make smart decisions about when we can throw it away and reuse it's memory for other vertices in the stream
  • Once all 3 vertices in a triangle are finalized, we can also reuse their memory for other triangles in the stream.
• Processing becomes
  • Read in vertices and triangles form the stream
  • When a vertex becomes finalized, process it, write it out, and reclaim it's memory
  • When a triangle becomes finalized, process it, write it out, and reclaim it's memory
• Streaming is also possible in the case of an ordered DEM where we can read in 2 rows (strip) of triangles at a time (see smreader_asc for an example)

Fields

• A current count of vertices seen so far
• A current count of triangles seen so far
• A total count of vertices expected to be in the file
• A total count of triangles expected to be in the file
• Optionally, a bounding box, around all the points in the stream
• A current vertex position, the point just read from the stream
  • 3 floats reperesenting the current position
  • the current index uniquely identifies this vertex (used by the triangle events)
• A current triangle , the triangle just read from the stream
  • 3 indices representing the indices of the vertices
  • 3 booleans indicating the finalization state of each corresponding vertex
• A current finalization index just read from the stream
  • An index which indicates a specific vertex has now become finalized
• Info specific to that file format

Operations

• Open Stream
  • Note: usually the underlying file is opened outside of the reader and the file handle is passed in
• Close Stream
• Read Header, read any header information unique to this file format from the stream
• Write Header, write any header info unique to this file format to the stream
• Compute Bounds, compute min/max bounds for the entire stream (requires a pass thru the entire file)
• Read Event
  • SM_VERTEX, read in a vertex from the stream
  • SM_TRIANGLE, read in a triangle from the stream
    • Note: also includes a set of 3 booleans indicating each corresponding vertex may have become finalized
  • SM_FINALIZE, returns the index of the vertex which has become finalized
  • SM_EOF, we have reached the end of the stream
• Write Vertex, write a vertex to the stream
• Write Triangle, write a triangle to the stream
  • including finalization state, where appopriate
• Write Finalize, write a finalization command for a single vertex to the stream

Readers

• smreader - base reader class
• smreader_asc - reader for ESRI ASCII DEM file format (Streaming *)
  • Streaming accomplished by only storing 2 rows of points
  • Triangles for TIN can be inferred from points.
• smreader_jrs - reader for Jonathan R. Schewchuk's file format (Non-Streaming)
• smreader_off - reader for GeomView's Standard Object File Format (OFF) (Non-streaming)
• smreader_ply - reader for Stanford's Triangle Format (PLY) (Non-Streaming)
• smreader_sma - reader for our Streaming Mesh ASCII format (Streaming)
• smreader_smb - reader for our Streaming Mesh Binary format (Streaming)
• smreader_smc - reader for our Streaming Mesh Compressed Binary format (Streaming)
• smreader_smd - experimental compressed format
• smreader_smq - experimental format

Writers

• smwriter - base writer class
• smwriter_nil - DO NOTHING writer, stub
• smwriter_off - writer for GeomView's Standard Object File Format (OFF) (Non-streaming)
• smwriter_ply - writer for Stanford's Triangle Format (PLY) (Non-Streaming)
• smwriter_sma - writer for our Streaming Mesh ASCII format (Streaming)
• smwriter_smb - writer for our Streaming Mesh Binary format (Streaming)
• smwriter_smc - writer for our Streaming Mesh Compressed Binary format (Streaming)
• smwriter_smd - experimental compressed format
• smwriter_smq - experimental format

Utilities

• Compression Tools - various utilities to assist in binary compression & parrallelogram rule for .smc format

• smreadopener.h - Wrapper around other readers for easier use in tools & apps
• smreadpostascompactpre.h - allows reading files in reversed order
• smreadpreascompactpre.h - ???

• smwriteopener.h - Wrapper around other writers for easier use in tools & apps
• smwritebuffered.h - ???

-- ShawnDB - 01 Jun 2008