.. _tlayer:

Layer
_____

A ogr-dataset has one or more layers. ``osgeo.ogr.Layer`` provides methods to retrieve 
layer definitions and features. The methods available in ``osgeo.ogr.Layer`` can be found in 
http://gdal.org/python/osgeo.ogr.Layer-class.html or with the following code block:

.. code-block:: python

    from girs.feat.layers import LayersReader
    lrs = LayersReader('D:/tmp/girs/DEU_adm_shp/DEU_adm4.shp')
    methods = [m for m in dir(lrs.get_layer()) if not m.startswith('_')]

In the sections below you will find examples about some of the following layer descripiton capabilities:

    * GetDescription, GetExtent, GetName, SetDescription
    * TestCapability
    * GetStyleTable, SetStyleTable
    * GetMetadata, GetMetadataDomainList, GetMetadataItem, GetMetadata_Dict, GetMetadata_List, SetMetadata, SetMetadataItem
    
Section :ref:`tgeoprocessing` describe these and other tools:

    * Clip, Erase, Identity, Intersection, SymDifference, Union, Update

In :ref:`tselection` you will find examples on filters

    * SetAttributeFilter, SetSpatialFilter, SetSpatialFilterRect, GetSpatialFilter, GetSpatialRef

The following *layer* capabilities are used only internally:

    * SetNextByIndex, next
    * ResetReading, SyncToDisk
    * Dereference, GetRefCount, Reference
    * CommitTransaction, RollbackTransaction, StartTransaction

The following *feature* capabilites are used internally in `girs`: 

    * CreateFeature, DeleteFeature, GetFeature, GetFeatureCount, GetFeaturesRead, GetNextFeature, SetFeature
    * GetLayerDefn
    * AlterFieldDefn, CreateField, CreateFields, CreateGeomField, DeleteField, FindFieldIndex, GetFIDColumn, ReorderField, ReorderFields, SetIgnoredFields
    * GetGeomType, GetGeometryColumn


The class ``girs.feat.layers.LayersSet`` provides a set of methods build upon ``osgeo.ogr.Layer`` as described below:

Iteration through layers
^^^^^^^^^^^^^^^^^^^^^^^^

Using ``LayersSet.layers()`` it is possible to iterate over ogr-layers and 
call any method defined above to all layers. Using the layer out of the scope 
of the loop will crash the programm. The same applies to 
``LayersSet.get_layer(layer_number)``: it can be used to call any method defined 
above for a specific layer. If the layer goes out of scope, the system crashes. 
Therefore, it is less error prone to use neither ``LayersSet.layers()`` nor 
``LayersSet.get_layer(layer_number)``. Instead, use the corresponding method to 
retrieve information from layer. For example, 

instead of:

.. code-block:: python

    lrs = LayersReader('D:/tmp/girs/DEU_adm_shp/DEU_adm4.shp')
    lyr = lrs.get_layer(layer_number=0)
    print lyr.GetName()
    
use:

.. code-block:: python

    lrs = LayersReader('D:/tmp/girs/DEU_adm_shp/DEU_adm4.shp')
    lyr = lrs.get_name(layer_number=0)

Inside the loop, the layers iterator guarantees that the layer does not loose the scope, crashing the program.

.. code-block:: python

    from girs.feat.layers import LayersReader
    lrs = LayersReader('D:/tmp/girs/DEU_adm_shp/DEU_adm4.shp')
    for lyr in lrs.layers():
        print lyr.GetName()  # use lyr only inside this loop
        
The example below shows how to retrieve a layer directly and how this can 
crash the program:

.. code-block:: python

    from girs.feat.layers import LayersReader
    lrs = LayersReader('D:/tmp/girs/DEU_adm_shp/DEU_adm4.shp')
    lyr = lrs.get_layer()
    print lyr.GetName()  # it works, because lrs.dataset is valid
    del lrs  # delete lrs, deleting also lrs.dataset
    print lyr.GetName()  # program crashes

The following will also crash the program, because after `get_layer()` is called, 
`LayersReader(filename)` goes out of scope:

.. code-block:: python
    
    from girs.feat.layers import LayersReader
    # This works: the instance LayersReader(filename) goes out of scope just 
    # after calling get_layer()
    print LayersReader('D:/tmp/girs/DEU_adm_shp/DEU_adm4.shp').get_layer()
    # This crashes: the instance LayersReader(filename) goes out of scope just 
    # after calling get_layer(), then a dangling pointer tries to call get_layer()
    print LayersReader('D:/tmp/girs/DEU_adm_shp/DEU_adm4.shp').get_layer().GetDescription()
    
.. note::

    Avoid using an OGR-layer instance directily. Instead, use the corresponding `girs` layer methods.
    
    
Layer description
^^^^^^^^^^^^^^^^^

In order to retrieve any layer information, the corresponding layer number must be given.  
The default layer number is zero.

**Layer name**


.. code-block:: python

    from girs.feat.layers import LayersReader
    lrs = LayersReader('D:/tmp/girs/DEU_adm_shp/DEU_adm4.shp')
    print lrs.get_layer_name()  # DEU_adm4
    print lrs.get_layer_name(layer_number=0)  # same result: DEU_adm4


**Description**

.. code-block:: python

    from girs.feat.layers import LayersReader
    print lrs.get_description()

**Number of layers in the dataset**

.. code-block:: python

    from girs.feat.layers import LayersReader
    lrs = LayersReader('D:/tmp/girs/DEU_adm_shp/DEU_adm4.shp')
    print lrs.get_layer_count()  # Shapefile have only one layer

    
**Layer extent**

The parameter `scale` expands or contracts the the layer extension height and width 
for positive resp. negative values. Default is ``scale=0.0``.

.. code-block:: python
    
    from girs.feat.layers import LayersReader
    lrs = LayersReader('D:/tmp/girs/DEU_adm_shp/DEU_adm4.shp')
    print lrs.get_extent()
    # (5.8662505149842445, 15.041815757751444, 47.27012252807623, 55.05652618408206)
    print lrs.get_extent(scale=0.1)
    # (4.9486939907075245, 16.051127934455835, 46.49148216247565, 55.9130305862427)
    print lrs.get_extent(scale=-0.1)
    # (6.783807039260965, 14.124259233474724, 48.04876289367681, 54.27788581848148)