=============================
``grail.data.vbmfile`` Module
=============================
.. include:: ..\..\version.h

.. contents:: Table of Contents
   :backlinks: top


--------
Overview
--------

An ASCII VBM (Variable Block Model) file is used to store the vertices of 2D polylines. 
Multiple polylines can be stored in the same file.  The VBM (ASCII) format consists of a 
header line with a plane number (usually the elevation or section line), a feature code 
to define the line, and optional orientation information. This is followed by a field of 
x, y points in free format::

   2210.00 999
   2480.80 4973.30
   2457.50 4989.80
   2460.40 5010.60
   2463.40 5032.40
   2472.20 5041.20
   2495.70 5039.70
   2515.70 5037.60
   2536.70 5035.30
   2562.50 5027.40
   2589.50 5019.10
   2605.90 5001.80
   2622.20 4984.50
   2639.40 4966.30
   2639.40 4942.80
   2625.10 4929.90
   2610.10 4916.40
   .0 .0
   2225.00 999
   2449.70 5038.20
   2451.70 5041.50
   2461.70 5052.20
   2459.00 5055.80
   2471.10 5080.90
   2483.90 5107.20
   2501.40 5125.40
   2518.80 5143.60
   2536.30 5161.80
   2553.70 5180.00
   2571.20 5198.20
   .0 .0



--------
Examples
--------

The following snippet illustrates how to write to a VBM file:

.. Python::

	from grail.data import vbmfile

	path = "C:\\example.vbm"
	polyline = [[0,0,0],[1,0,0],[1,1,0],[0,1,0],[0,0,0]]

	#note that even though we only have one pointlist, we still must pass it in as a list of lists
        myList = [polyline]
        
        vbmfile.writeVBMFile(myList, path)
    


---------
Functions
---------


:df:`readVBMFile(path, orientation)`
    Opens a VBM file, parses the contents, returns a list of pointlists (one for each polyline contained in the file).

    Arguments:
      `path` : string

      `orientation` : This value indicates on which plane the polyline exists (see constants)

    Returns:
      `pointLists` : a list of lists


:df:`writeVBMFile(pointLists, path)`
    Creates a regular SRV file.  Note that if you only have one polyline to include, the function still expects a list containing the one point list.

    Arguments:
      `path` : string

      `pointLists` : a list of lists


---------
Constants
---------
      
HORIZ
   Used to indicate horizontal VBM Orientation

VERT_EAST_WEST
   Used to indicate vertical E-W VBM Orientation

VERT_NORTH_SOUTH
   Used to indicate vertical N-S VBM Orientation