===============================
``grail.data.lgomodule`` module
===============================
.. include:: ../../version.h


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


-------
Summary
-------

MineSightŪ Large Grided Objects (LGO) file access.  This module allows for
manipulation of surfaces in pre-existing LGO files.

The general order operations are:

  1. Open the LGO file
  2. Open the surface
  3. Read a row
  4. Set values in row
  5. Write row

.. Note::
  Buffers are flushed and files are closed after the objects are out of 
  scope.

---------------------
Terms and Definitions
---------------------

During a discussion of LGO's there are several terms that need defining.

  LGO
    MineSightŪ Large Grided Objects that contains surfaces.

  Surface
    An entry in the LGO file that contains rows.

  Row
    An array of elevation levels in a surface

----------------
Undefined Values
----------------

All elevation levels that are undefined will return a Python None value.
Any elevation level to be set as undefined, Python None will be used.
The :c:`Surface` :f:`get_value` and the :c:`Row` :f:`get` methods allow for
overwriting the undefined value via the optional :a:`undefined` keyword.

------------------
Accessing LGO Data
------------------

LGO files contain surfaces that contains rows that contains values.
Each surface in the LGO file has a unique name.

LGO files are accessed using the lgomodule

 .. Python::

   from grail.data import lgomodule
   lgo = lgomodule.open("test.lgo","w")

Each :c:`Lgo` contains direction vectors for the plane of orientation via :f:`get_xvector` and :f:`get_yvector` methods. :f:`is_inverted` returns True when the elevation is inverted.  As well as the size of the data points via :f:`get_xsize` and :f:`get_ysize` and the number of columns and rows via :f:`get_row_count` and :f:`get_col_count` .

The surface in the LGO is accessed by the unique name.

 .. Python::
   
   surface = lgo.open_surface("mysurface")

The name of the :c:`Surface` can be accessed using :f:`get_name` .
Setting the name via :f:`set_name` will only allow unique names to the :c:`Lgo` .

Each :c:`Surface` contains rows that can be accessed by three methods.

Directly:

 .. Python::
   
   value = surface.get_value(5, 5)
   value = value + 1
   surface.set_value(5, 5, value)

Via the :c:`Row` object:

 .. Python::
   
   row = surface.get_row(5)
   row[5] = row[5] + 1
   surface.set_row(5, row)

Or via the :c:`Row` object using a sequence:

 .. Python::
   
   row = surface[5]
   row[5] = row[5] + 1
   surface[5] = row

----------------------
Examples of LGO Access
----------------------

All examples are difference calculations using various methods.

Direct Method
-------------

This method can result in slower access if the values are not transverse by row then columns.  The :c:`Row` method forces this construct.  If only a small number of values in each row are needed, this is the preferred method.

 .. Python::

   from grail.data import lgomodule
   lgo = lgomodule.open("test.lgo","w")
   surf1 = lgo.open_surface("surf1", True)
   surf2 = lgo.open_surface("surf2", True)
   surf3 = lgo.open_surface("surf3")
   for y in range(lgo.get_row_count()):
       for x in range(lgo.get_col_count()):
           val1 = surf1.get_value(x, y)
           val2 = surf2.get_value(x, y)
           if val1 == None or val2 == None:
               surf3.set_value(x, y, None)
           else:
               surf3.set_value(x, y, abs(val1 - val2))

Row Method
----------

This is the preferred method for this type of calculation.

 .. Python::

   from grail.data import lgomodule
   lgo = lgomodule.open("test.lgo","w")
   surf1 = lgo.open_surface("surf1", True)
   surf2 = lgo.open_surface("surf2", True)
   surf3 = lgo.open_surface("surf3")
   row3 = lgomodule.Row(lgo.get_col_count())
   for y in range(lgo.get_row_count()):
       row1 = surf1.get_row(y)
       row2 = surf2.get_row(y)
       for x in range(lgo.get_col_count()):
           val1 = row1[x]
           val2 = row2[x]
           if val1 == None or val2 == None:
               row3[x] = None
           else:
               row3[x] = abs(val1 - val2)
       surf3.set_row(y, row3)

Row Method with Sequences
-------------------------

This is the same as above but more short hand.

 .. Python::

   from grail.data import lgomodule
   lgo = lgomodule.open("test.lgo","w")
   surf1 = lgo.open_surface("surf1", True)
   surf2 = lgo.open_surface("surf2", True)
   surf3 = lgo.open_surface("surf3")
   row3 = lgomodule.Row(lgo.get_col_count())
   for y in range(len(surf1)):
       row1 = surf1[y]
       row2 = surf2[y]
       for x in range(len(row1)):
           val1 = row1[x]
           val2 = row2[x]
           if val1 == None or val2 == None:
               row3[x] = None
           else:
               row3[x] = abs(val1 - val2)
       surf3 = row3

Sequences can also be used to list the surfaces in the LGO file when the name is not known or when a process needs to be performed on each :c:`Surface`.

This example just prints the name of the surfaces in the LGO file.

 .. Python::
   
   from grail.data import lgomodule
   lgo = lgomodule.open("test.lgo","r")
   for surface in lgo:
       print surface.get_name()

-------
Classes
-------

There are three classes defined within this Module.

  :c:`Lgo`
    Defines the LGO file.

  :c:`Surface`
    Defines the surface in the LGO file.

  :c:`Row`
    Defines the row of values in the surface.

Lgo Class
---------

:dc:`Lgo`
  The :c:`Lgo` class is created only by the :df:`lgomodule.open(file, method)` function.
  
  An example would be,

   .. Python::
     
     from grail.data import lgomodule
     lgo = lgomodule.open("test.lgo", "w")
    
  Arguments:
    :a:`file` : string
      Path to the LGO file to open.
    :a:`method` : string 
      'r' for read only access.
      'w' for read and write access.

  Throws:
    IOError
      When there is a file access error.

  Sequences:
    The use of the :c:`Lgo` object as a sequence will return each :c:`Surface`
    in the LGO.

    Example,
    
     .. Python::
   
       from grail.data import lgomodule
       lgo = lgomodule.open("test.lgo","r")
       for surface in lgo:
           print surface.get_name()

  :df:`open_surface(name[,onlyexisting=False])`
    Opens a surface in the LGO file.

    An example would be,

     .. Python::
       
       from grail.data import lgomodule
       lgo = lgomodule.open("test.lgo", "w")
       surf = lgo.open_surface("mysurface")

    Arguments:
      :a:`name` : string
        The name of the surface in the file.
      :a:`onlyexsting` : boolean
        Do not create a surface.  Default: create.

    Throws:
      IOError
        When a surface cannot be created or does not exist (when onlyexisting=True).

  :df:`get_origin()`
    Returns the origin of the LGO as a point.

  :df:`get_xvector()`
    Returns the vector of the x-axis as a point.

  :df:`get_yvector()`
    Returns the vector of the y-axis as a point.

  :df:`get_xsize()`
    Returns the size of the columns as a float.

  :df:`get_ysize()`
    Returns the size of the rows as a float.

  :df:`get_row_count()`
    Returns the number of rows in the LGO surfaces.

  :df:`get_col_count()`
    Returns the number of columns in the LGO surfaces.

  :df:`is_inverted()`
    Returns True when the elevation vector is negative.

Surface Class
-------------

:dc:`Surface`
  The surface in the LGO file.
  :c:`Surface` objects are only created using the :f:`Lgo.open_surface` function.

  Sequences:
    The use of the :c:`Surface` object as a sequence will return/set each 
    :c:`Row` in the surface.

    Example,
    
     .. Python::
   
       from grail.data import lgomodule
       lgo = lgomodule.open("test.lgo","r")
       surface = lgo.open_surface("test")
       for row in surface:
           print row[5]

  :df:`get_value(col,row[,undefined=None])`
    Returns the elevation level of the location in the LGO surface as a float.

    Arguments:
      :a:`col` : integer
        The column number of the location.
      :a:`row` : integer
        The row number of the location.
      :a:`undefined` : any
        The value to return when undefined.  Default: Python None.

    Throws:
      IndexError
        When the given column and row is out of range.

  :df:`set_value(col,row,value)`
    Sets the elevation level of the location in the LGO surface.

    A Python None can be used for the value to set to undefined.

    Arguments:
      :a:`col` : integer
        The column number of the location.
      :a:`row` : integer
        The row number of the location.
      :a:`value` : float
        The value to set the elevation to.  This can be a Python None.

    Throws:
      IndexError
        When the given column and row is out of range.
      IOError
        When the LGO file is read only.

  :df:`get_name()`
    Returns the name of the surface as a string.

  :df:`set_name(name)`
    Sets the name of the surface.

    Arguments:
      :a:`name` : string
        The name to use.

    Throws:
      ValueError
        When the string is empty.
      IOError
        When the LGO file is read only.
      RuntimeError
        When the surface name is associated with another surface.
      
  :df:`get_row(index)`
    Returns a :c:`Row` object of the row in the surface.

    Arguments:
      :a:`index` : integer
        The row number of the :c:`Row` in the surface to return.
    
    Throws:
      IndexError
        When the row number is out of range.

  :df:`set_row(index,row)`
    Sets the :c:`Row` in the surface.

    Arguments:
      :a:`index` : integer
        The row number of the :c:`Row` in the surface to set.
      :a:`row` : :c:`Row`
        The :c:`Row` object to get the row from.

    Throws:
      IOError
        When the LGO file is read only.

Row Class
---------

:dc:`Row(size)`
  An array of fixed size with elevation values that can be undefined.
  A :c:`Row` object can be made independent of a surface.
  A newly created :c:`Row` object will have all values as undefined.

  Example,

   .. Python::
     
     from gial.data import lgomodule
     row = lgomodule.Row(50)
 
  Arguments:
    :a:`size` : integer
      The size of the array to make.

  Sequences:
    The :c:`Row` object will return/set each elevation level 
    with Python None as the undefined value.

  :df:`get(index[,undefined=None])`
    Gets an elevation level at the given index.

    Arguments:
      :a:`index` : integer
        The location to get the value from.
      :a:`undefined`
        The value to return when undefined.  Default: Python None.

    Throws:
      IndexError
        When index is out of range.

  :df:`set(index,value)`
    Sets an elevation level at the given index.

    Arguments:
      :a:`index` : integer
        The location to set the value.
      :a:`value` : float
        The value to set.  Python None can be used for undefined.

    Throws:
      IndexError
        When index is out of range.