Geografic-Information-System/lib/python/pygrass/docs/raster.rst

.. _raster-label:

Introduction on Raster
===========================

PyGRASS uses 4 different Raster classes, that respect the 4 different approaches
of GRASS-C API.
The read access is row wise for :ref:`RasterRow-label` and
:ref:`RasterRowIO-label` and additionally
cached in the RowIO class. Both classes write sequentially.
RowIO is row cached, :ref:`RasterSegment-label` and :ref:`RasterNumpy-label`
are tile cached for reading and writing therefore a randomly access is possible.
Hence RasterRow and RasterRowIO should be used in case for fast (cached)
row read access and RasterRow for fast sequential writing.
Segment and Numpy should be used for random access, but Numpy only for files
not larger than 2GB.


==========================  =======================  ========  ============
Class Name                  C library                Read      Write
==========================  =======================  ========  ============
:ref:`RasterRow-label`      `Raster library`_        randomly  sequentially
:ref:`RasterRowIO-label`    `RowIO library`_         cached    no
:ref:`RasterSegment-label`  `Segmentation library`_  cached    randomly
:ref:`RasterNumpy-label`    `numpy.memmap`_          cached    randomly
==========================  =======================  ========  ============


All these classes share common methods and attributes, necessary to address
common tasks as rename, remove, open, close, exist, is_open.
In the next examples we instantiate a RasterRow object. ::

    >>> from pygrass import raster
    >>> elev = raster.RasterRow('elevation')
    >>> elev.name
    'elevation'
    >>> print(elev)
    elevation@PERMANENT
    >>> elev.exist()
    True
    >>> elev.is_open()
    False
    >>> new = raster.RasterRow('new')
    >>> new.exist()
    False
    >>> new.is_open()
    False


We can rename the map: ::

    >>> # setting the attribute
    >>> new.name = 'new_map'
    >>> print(new)
    new_map
    >>> # or using the rename methods
    >>> new.rename('new')
    >>> print(new)
    new

.. _RasterRow-label:

RastRow
-------

PyGrass allow user to open the maps, in read and write mode,
row by row using the `Raster library`_, there is not support to read and write
to the same map at the same time, for this functionality, please see the
:ref:`RasterSegment-label` and :ref:`RasterNumpy-label` classes.
The RasterRow class allow to read in a randomly order the row from a map, but
it is only possible to write the map using only a sequence order, therefore every
time you are writing a new map, the row is add to the file as the last row. ::

    >>> raster = reload(raster)
    >>> elev = raster.RasterRow('elevation')
    >>> # the cols attribute is set from the current region only when the map is open
    >>> elev.cols
    >>> elev.open()
    >>> elev.is_open()
    True
    >>> elev.cols
    1500
    >>> # we can read the elevation map, row by row
    >>> for row in elev[:5]: print(row[:3])
    [ 141.99613953  141.27848816  141.37904358]
    [ 142.90461731  142.39450073  142.68611145]
    [ 143.81854248  143.54707336  143.83972168]
    [ 144.56524658  144.58493042  144.86477661]
    [ 144.99488831  145.22894287  145.57142639]
    >>> # we can open a new map in write mode
    >>> new = raster.RasterRow('new')
    >>> new.open('w', 'CELL')
    >>> # for each elev row we can perform computation, and write the result into
    >>> # the new map
    >>> for row in elev:
    ...     new.put_row(row < 144)
    ...
    >>> # close the maps
    >>> new.close()
    >>> elev.close()
    >>> # check if the map exist
    >>> new.exist()
    True
    >>> # we can open the map in read mode
    >>> new.open('r')
    >>> for row in new[:5]: print(row[:3])
    [1 1 1]
    [1 1 1]
    [1 1 1]
    [0 0 0]
    [0 0 0]
    >>> new.close()
    >>> new.remove()
    >>> new.exist()
    False

.. autoclass:: pygrass.raster.RasterRow
    :members:

.. _RasterRowIO-label:

RasterRowIO
-----------

The RasterRowIO class use the grass `RowIO library`_, and implement a row
cache. The RasterRowIO class support only reading the raster, because the
raster rows can only be written in sequential order, writing by row id is not
supported by design. Hence, we should use the rowio lib only for caching rows
for reading and use the default row write access as in the RasterRow class. ::

    >>> raster = reload(raster)
    >>> elev = raster.RasterRowIO('elevation')
    >>> elev.open('r')
    >>> for row in elev[:5]: print(row[:3])
    [ 141.99613953  141.27848816  141.37904358]
    [ 142.90461731  142.39450073  142.68611145]
    [ 143.81854248  143.54707336  143.83972168]
    [ 144.56524658  144.58493042  144.86477661]
    [ 144.99488831  145.22894287  145.57142639]
    >>> elev.close()

.. autoclass:: pygrass.raster.RasterRowIO
    :members:

.. _RasterSegment-label:

RastSegment
-----------

The RasterSegment class use the grass `Segmentation library`_, it work dividing
the raster map into small different files, that grass read load into the memory
and write to the hardisk.
The segment library allow to open a map in a read-write mode. ::

    >>> raster = reload(raster)
    >>> elev = raster.RasterSegment('elevation')
    >>> elev.open()
    >>> for row in elev[:5]: print(row[:3])
    [ 141.99613953  141.27848816  141.37904358]
    [ 142.90461731  142.39450073  142.68611145]
    [ 143.81854248  143.54707336  143.83972168]
    [ 144.56524658  144.58493042  144.86477661]
    [ 144.99488831  145.22894287  145.57142639]
    >>> new = raster.RasterSegment('new')
    >>> new.open('w', 'CELL')
    >>> for irow in xrange(elev.rows):
    ...     new[irow] = elev[irow] < 144
    ...
    >>> for row in new[:5]: print(row[:3])
    [1 1 1]
    [1 1 1]
    [1 1 1]
    [0 0 0]
    [0 0 0]

The RasterSegment class define two methods to read and write the map:

    * ``get_row`` that return the buffer object with the row that call the
      C function ``segment_get_row``. ::

        >>> # call explicity the method
        >>> elev_row0 = elev.get_row(0)
        >>> # call implicity the method
        >>> elev_row0 = elev[0]

    * ``get`` that return the value of the call map that call the
      C function ``segment_get``. ::

        >>> # call explicity the method
        >>> elev_val_0_0 = elev.get(0, 0)
        >>> # call implicity the method
        >>> elev_val_0_0 = elev[0, 0]

Similarly to write the map, with ``put_row``, to write a row and with ``put``
to write a single value to the map. ::

    >>> # compare the cell value get using the ``get`` method, and take the first
    >>> # value of the row with the ``get_row`` method
    >>> elev[0, 0] == elev[0][0]
    True
    >>> # write a new value to a cell,
    >>> new[0, 0] = 10
    >>> new[0, 0]
    10
    >>> new.close()
    >>> new.exist()
    True
    >>> new.remove()
    >>> elev.close()
    >>> elev.remove()

.. autoclass:: pygrass.raster.RasterSegment
    :members:

.. _RasterNumpy-label:

RasterNumpy
-----------

The RasterNumpy class, is based on the `numpy.memmap`_ class If you open an
existing map, the map will be copied on a binary format, and read to avoid
to load all the map in memory. ::

    >>> raster = reload(raster)
    >>> elev = raster.RasterNumpy('elevation', 'PERMANENT')
    >>> elev.open('r')
    >>> # in this case RasterNumpy is an extention of the numpy class
    >>> # therefore you may use all the fancy things of numpy.
    >>> elev[:5, :3]
    RasterNumpy([[ 141.99613953,  141.27848816,  141.37904358],
           [ 142.90461731,  142.39450073,  142.68611145],
           [ 143.81854248,  143.54707336,  143.83972168],
           [ 144.56524658,  144.58493042,  144.86477661],
           [ 144.99488831,  145.22894287,  145.57142639]], dtype=float32)
    >>> el = elev < 144
    >>> el[:5, :3]
    RasterNumpy([[1, 1, 1],
           [1, 1, 1],
           [1, 1, 1],
           [0, 0, 0],
           [0, 0, 0]], dtype=int32)
    >>> el.name == None
    True
    >>> # give a name to the new map
    >>> el.name = 'new'
    >>> el.exist()
    False
    >>> el.close()
    >>> el.exist()
    True
    >>> el.remove()

.. autoclass:: pygrass.raster.RasterNumpy
    :members:


.. _Raster library: http://grass.osgeo.org/programming7/rasterlib.html
.. _RowIO library: http://grass.osgeo.org/programming7/rowiolib.html
.. _Segmentation library: http://grass.osgeo.org/programming7/segmentlib.html
.. _numpy.memmap: http://docs.scipy.org/doc/numpy/reference/generated/numpy.memmap.html