=============================
``grail.data.srvfile`` Module
=============================

.. include:: ..\..\version.h

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

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

The Survey File (SRV) is a space-delimited ASCII file used to store the vertices of 3D polylines. Multiple polylines can be stored 
in the same file (using `$` as the break code character).  The standard format is::

   code   X_0  Y_0  Z_0
   code   X_1  Y_1  Z_1
        ...
   code   X_n  Y_n  Z_n
   $
   code   X_0  Y_0  Z_0
   code   X_1  Y_1  Z_1
        ...
   code   X_n  Y_n  Z_n
   $
   ...

where X\_n, Z\_n and Y\_n are the coordinates of the polyline vertices,
and `code` is a user-specified survey code.  Codes can be used for many 
purposes such as specifying display attributes (type of line, symbol, and 
associated colors) and whether to treat the data as part of a string (i.e. 
bench toes) or as individual points (i.e. blastholes).

.. Warning::
   It should be noted that the file created by this module is different than the fixed column width 
   "Survey Code File" described in the MS3D documentation.

--------------------
Standard Definitions
--------------------

point_list:
   A list of points, defined as: [[x0, y0, z0], ..., [xN, yN, zN]].

coded_point_list:
   A tuple containing two items: the first item is a code (string), the second is the corresponding point_list.  This data type
   is intended to mimic the srv file format.  The code should match with an accompanying parameter file (survey code file).
   For example, ['BENCH', [[x0, y0, z0], ..., [xN, yN, zN]]] 


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


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

    Arguments:
      `path` : string

    Returns:
      `pointLists` : a list of lists


:df:`writeSRVFile(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


:df:`writeCodedSRVFile(codedPointLists, path)`
    Creates a SRV file with a code for each polyline.

    Arguments:
      `path` : string

      `codedPointLists` : a list of lists with the following format: `[['code1',pointList1], ['code2',pointList2], ... ]`



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

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

.. Python::

	from grail.data import srvfile

	path = "C:\\example.srv"
	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]
        
        srvfile.writeSRVFile(myList, path)