.. _ref-gdal:

========

GDAL API

========

.. module:: django.contrib.gis.gdal

   :synopsis: GeoDjango's high-level interface to the GDAL library.

`GDAL`__ stands for **G**\ eospatial **D**\ ata **A**\ bstraction **L**\ ibrary,

and is a veritable "swiss army knife" of GIS data functionality.  A subset

of GDAL is the `OGR`__ Simple Features Library, which specializes

in reading and writing vector geographic data in a variety of standard

formats.

GeoDjango provides a high-level Python interface for some of the 

capabilities of OGR, including the reading and coordinate transformation

of vector spatial data.

.. note::

     Although the module is named ``gdal``, GeoDjango only supports

     some of the capabilities of OGR.  Thus, none of GDAL's features

     with respect to raster (image) data are supported at this time.

__ http://www.gdal.org/

__ http://www.gdal.org/ogr/

Overview

========

Sample Data

-----------

The GDAL/OGR tools described here are designed to help you read in

your geospatial data, in order for most of them to be useful you have

to have some data to work with.  If you're starting out and don't yet

have any data of your own to use, GeoDjango comes with a number of

simple data sets that you can use for testing.  This snippet will

determine where these sample files are installed on your computer::

    >>> import os

    >>> import django.contrib.gis

    >>> GIS_PATH = os.path.dirname(django.contrib.gis.__file__)

    >>> CITIES_PATH = os.path.join(GIS_PATH, 'tests/data/cities/cities.shp')

Vector Data Source Objects

==========================

``DataSource``

--------------

:class:`DataSource` is a wrapper for the OGR data source object that

supports reading data from a variety of OGR-supported geospatial file

formats and data sources using a simple, consistent interface.  Each

data source is represented by a :class:`DataSource` object which contains

one or more layers of data.  Each layer, represented by a :class:`Layer`

object, contains some number of geographic features (:class:`Feature`),

information about the type of features contained in that layer (e.g.

points, polygons, etc.), as well as the names and types of any

additional fields (:class:`Field`) of data that may be associated with

each feature in that layer.

.. class:: DataSource(ds_input)

   The constructor for ``DataSource`` just a single parameter: the path of

   the file you want to read.  However, OGR

   also supports a variety of more complex data sources, including

   databases, that may be accessed by passing a special name string instead

   of a path.  For more information, see the `OGR Vector Formats`__

   documentation.  The :attr:`name` property of a ``DataSource`` 

   instance gives the OGR name of the underlying data source that it is

   using.

   Once you've created your ``DataSource``, you can find out how many 

   layers of data it contains by accessing the :attr:`layer_count` property, 

   or (equivalently) by using the ``len()`` function.  For information on 

   accessing the layers of data themselves, see the next section::

       >>> from django.contrib.gis.gdal import DataSource

       >>> ds = DataSource(CITIES_PATH)

       >>> ds.name                         # The exact filename may be different on your computer

       '/usr/local/lib/python2.6/site-packages/django/contrib/gis/tests/data/cities/cities.shp'

       >>> ds.layer_count                  # This file only contains one layer

       1

   .. attribute:: layer_count

   Returns the number of layers in the data source.

   .. attribute:: name

   Returns the name of the data source.

__ http://www.gdal.org/ogr/ogr_formats.html

``Layer``

---------

.. class:: Layer

   ``Layer`` is a wrapper for a layer of data in a ``DataSource`` object.

   You never create a ``Layer`` object directly.  Instead, you retrieve

   them from a :class:`DataSource` object, which is essentially a standard

   Python container of ``Layer`` objects.  For example, you can access a

   specific layer by its index (e.g. ``ds[0]`` to access the first

   layer), or you can iterate over all the layers in the container in a

   ``for`` loop.  The ``Layer`` itself acts as a container for geometric 

   features.

   Typically, all the features in a given layer have the same geometry type.

   The :attr:`geom_type` property of a layer is an :class:`OGRGeomType`

   that identifies the feature type.  We can use it to print out some basic

   information about each layer in a :class:`DataSource`::

       >>> for layer in ds:

       ...     print 'Layer "%s": %i %ss' % (layer.name, len(layer), layer.geom_type.name)

       ...

       Layer "cities": 3 Points

   The example output is from the cities data source, loaded above, which

   evidently contains one layer, called ``"cities"``, which contains three

   point features.  For simplicity, the examples below assume that you've 

   stored that layer in the variable ``layer``::

       >>> layer = ds[0]

   .. attribute:: name

   Returns the name of this layer in the data source.

       >>> layer.name

       'cities'

   .. attribute:: num_feat

   Returns the number of features in the layer.  Same as ``len(layer)``::

       >>> layer.num_feat

       3

   .. attribute:: geom_type

   Returns the geometry type of the layer, as an :class:`OGRGeomType`

   object::

       >>> layer.geom_type.name

       'Point'

   .. attribute:: num_fields

   Returns the number of fields in the layer, i.e the number of fields of

   data associated with each feature in the layer::

       >>> layer.num_fields

       4

   .. attribute:: fields

   Returns a list of the names of each of the fields in this layer::

       >>> layer.fields

       ['Name', 'Population', 'Density', 'Created']

   .. attribute field_types

   Returns a list of the data types of each of the fields in this layer.

   These are subclasses of ``Field``, discussed below::

       >>> [ft.__name__ for ft in layer.field_types]

       ['OFTString', 'OFTReal', 'OFTReal', 'OFTDate']

   .. attribute:: field_widths

   Returns a list of the maximum field widths for each of the fields in

   this layer::

      >>> layer.field_widths

      [80, 11, 24, 10]

   .. attribute:: field_precisions

   Returns a list of the numeric precisions for each of the fields in

   this layer.  This is meaningless (and set to zero) for non-numeric 

   fields::

       >>> layer.field_precisions

       [0, 0, 15, 0]

   .. attribute:: extent

   Returns the spatial extent of this layer, as an :class:`Envelope` 

   object::

      >>> layer.extent.tuple

      (-104.609252, 29.763374, -95.23506, 38.971823)

   .. attribute:: srs

   Property that returns the :class:`SpatialReference` associated

   with this layer::

       >>> print layer.srs

       GEOGCS["GCS_WGS_1984",

           DATUM["WGS_1984",

               SPHEROID["WGS_1984",6378137,298.257223563]],

           PRIMEM["Greenwich",0],

           UNIT["Degree",0.017453292519943295]]

   If the :class:`Layer` has no spatial reference information associated

   with it, ``None`` is returned.

   .. attribute:: spatial_filter

   .. versionadded:: 1.2

   Property that may be used to retrieve or set a spatial filter for this

   layer.  A spatial filter can only be set with an :class:`OGRGeometry`

   instance, a 4-tuple extent, or ``None``.  When set with something 

   other than ``None``, only features that intersect the filter will be

   returned when iterating over the layer::

       >>> print layer.spatial_filter

       None

       >>> print len(layer)

       3

       >>> [feat.get('Name') for feat in layer]

       ['Pueblo', 'Lawrence', 'Houston']

       >>> ks_extent = (-102.051, 36.99, -94.59, 40.00) # Extent for state of Kansas

       >>> layer.spatial_filter = ks_extent

       >>> len(layer)

       1

       >>> [feat.get('Name') for feat in layer]

       ['Lawrence']

       >>> layer.spatial_filter = None

       >>> len(layer)

       3

   .. method:: get_fields()

   A method that returns a list of the values of a given field for each

   feature in the layer::

      >>> layer.get_fields('Name')

      ['Pueblo', 'Lawrence', 'Houston']

   .. method:: get_geoms([geos=False])

   A method that returns a list containing the geometry of each feature

   in the layer.  If the optional argument ``geos`` is set to ``True``

   then the geometries are converted to :class:`~django.contrib.gis.geos.GEOSGeometry`

   objects. Otherwise, they are returned as :class:`OGRGeometry` objects::

       >>> [pt.tuple for pt in layer.get_geoms()]

       [(-104.609252, 38.255001), (-95.23506, 38.971823), (-95.363151, 29.763374)]

   .. method:: test_capability(capability)

   Returns a boolean indicating whether this layer supports the

   given capability (a string).  Examples of valid capability strings

   include: ``'RandomRead'``, ``'SequentialWrite'``, ``'RandomWrite'``,

   ``'FastSpatialFilter'``, ``'FastFeatureCount'``, ``'FastGetExtent'``,

   ``'CreateField'``, ``'Transactions'``, ``'DeleteFeature'``, and 

   ``'FastSetNextByIndex'``.

``Feature``

-----------

.. class:: Feature

   ``Feature`` wraps an OGR feature.  You never create a ``Feature``

   object directly.  Instead, you retrieve them from a :class:`Layer` object.

   Each feature consists of a geometry and a set of fields containing

   additional properties.  The geometry of a field is accessible via its

   ``geom`` property, which returns an :class:`OGRGeometry` object.  A ``Feature``

   behaves like a standard Python container for its fields, which it returns as

   :class:`Field` objects: you can access a field directly by its index or name,

   or you can iterate over a feature's fields, e.g. in a ``for`` loop.

   .. attribute:: geom

   Returns the geometry for this feature, as an ``OGRGeometry`` object::

       >>> city.geom.tuple

       (-104.609252, 38.255001)

   .. attribute:: get

   A method that returns the value of the given field (specified by name)

   for this feature, **not** a ``Field`` wrapper object::

       >>> city.get('Population')

       102121

   .. attribute:: geom_type

   Returns the type of geometry for this feature, as an :class:`OGRGeomType`

   object.  This will be the same for all features in a given layer, and

   is equivalent to the :attr:`Layer.geom_type` property of the 

   :class:`Layer`` object the feature came from.

   .. attribute:: num_fields

   Returns the number of fields of data associated with the feature.

   This will be the same for all features in a given layer, and is

   equivalent to the :attr:`Layer.num_fields` property of the 

   :class:`Layer` object the feature came from.

   .. attribute:: fields

   Returns a list of the names of the fields of data associated with the

   feature.  This will be the same for all features in a given layer, and

   is equivalent to the :attr:`Layer.fields` property of the :class:`Layer`

   object the feature came from.

   .. attribute:: fid

   Returns the feature identifier within the layer::

       >>> city.fid

       0

   .. attribute:: layer_name

   Returns the name of the :class:`Layer` that the feature came from.

   This will be the same for all features in a given layer::

       >>> city.layer_name

       'cities'

   .. attribute:: index

   A method that returns the index of the given field name.  This will be

   the same for all features in a given layer::

       >>> city.index('Population')

       1

``Field``

---------

.. class:: Field

   .. attribute:: name

   Returns the name of this field::

       >>> city['Name'].name

       'Name'

   .. attribute:: type

   Returns the OGR type of this field, as an integer.  The

   ``FIELD_CLASSES`` dictionary maps these values onto 

   subclasses of ``Field``::

       >>> city['Density'].type

       2

   .. attribute:: type_name

   Returns a string with the name of the data type of this field::

       >>> city['Name'].type_name

       'String'

   .. attribute:: value

   Returns the value of this field.  The ``Field`` class itself 

   returns the value as a string, but each subclass returns the 

   value in the most appropriate form::

       >>> city['Population'].value

       102121

   .. attribute:: width

   Returns the width of this field::

       >>> city['Name'].width

       80

   .. attribute:: precision

   Returns the numeric precision of this field.  This is meaningless (and

   set to zero) for non-numeric fields::

       >>> city['Density'].precision

       15

   .. method:: as_double()

   Returns the value of the field as a double (float)::

       >>> city['Density'].as_double()

       874.7

   .. method:: as_int()

   Returns the value of the field as an integer::

       >>> city['Population'].as_int()

       102121

   .. method:: as_string()

   Returns the value of the field as a string::

       >>> city['Name'].as_string()

       'Pueblo'

   .. method:: as_datetime()

   Returns the value of the field as a tuple of date and time components::

       >>> city['Created'].as_datetime()

       (c_long(1999), c_long(5), c_long(23), c_long(0), c_long(0), c_long(0), c_long(0))

``Driver``

----------

.. class:: Driver(dr_input)

   The ``Driver`` class is used internally to wrap an OGR :class:`DataSource` driver.

   .. attribute:: driver_count

   Returns the number of OGR vector drivers currently registered.

OGR Geometries

==============

``OGRGeometry``

---------------

:class:`OGRGeometry` objects share similar functionality with 

:class:`~django.contrib.gis.geos.GEOSGeometry` objects, and are thin

wrappers around OGR's internal geometry representation.  Thus, 

they allow for more efficient access to data when using :class:`DataSource`. 

Unlike its GEOS counterpart, :class:`OGRGeometry` supports spatial reference

systems and coordinate transformation::

    >>> from django.contrib.gis.gdal import OGRGeometry

    >>> polygon = OGRGeometry('POLYGON((0 0, 5 0, 5 5, 0 5))')

.. class:: OGRGeometry(geom_input[, srs=None])

   This object is a wrapper for the `OGR Geometry`__ class.

   These objects are instantiated directly from the given ``geom_input`` 

   parameter, which may be a string containing WKT or HEX, a ``buffer``

   containing WKB data, or an :class:`OGRGeomType` object. These objects

   are also returned from the :class:`Feature.geom` attribute, when 

   reading vector data from :class:`Layer` (which is in turn a part of

   a :class:`DataSource`).

   __ http://www.gdal.org/ogr/classOGRGeometry.html

   .. classmethod:: from_bbox(bbox)

   .. versionadded:: 1.1

   Constructs a :class:`Polygon` from the given bounding-box (a 4-tuple).

   .. method:: __len__

   Returns the number of points in a :class:`LineString`, the

   number of rings in a :class:`Polygon`, or the number of geometries in a

   :class:`GeometryCollection`. Not applicable to other geometry types.

   .. method:: __iter__

   Iterates over the points in a :class:`LineString`, the rings in a

   :class:`Polygon`, or the geometries in a :class:`GeometryCollection`.

   Not applicable to other geometry types.

   .. method:: __getitem__

   Returns the point at the specified index for a :class:`LineString`, the

   interior ring at the specified index for a :class:`Polygon`, or the geometry

   at the specified index in a :class:`GeometryCollection`.  Not applicable to

   other geometry types.

   .. attribute:: dimension

   Returns the number of coordinated dimensions of the geometry, i.e. 0

   for points, 1 for lines, and so forth::

       >> polygon.dimension

       2

   .. attribute:: coord_dim

   .. versionchanged:: 1.2

   Returns or sets the coordinate dimension of this geometry.  For

   example, the value would be 2 for two-dimensional geometries.

   .. note::

      Setting this property is only available in versions 1.2 and above.

   .. attribute:: geom_count

   Returns the number of elements in this geometry::

       >>> polygon.geom_count

       1

   .. attribute:: point_count

   Returns the number of points used to describe this geometry::

      >>> polygon.point_count

      4

   .. attribute:: num_points

   Alias for :attr:`point_count`.

   .. attribute:: num_coords

   Alias for :attr:`point_count`.

   .. attribute:: geom_type

   Returns the type of this geometry, as an :class:`OGRGeomType` object.