Changes between Version 6 and Version 7 of GdalOgrInPython


Ignore:
Timestamp:
Dec 4, 2007 10:12:31 PM (12 years ago)
Author:
hobu
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • GdalOgrInPython

    v6 v7  
    1 = GDAL/OGR In Python =
    2 
    3 The GDAL project (primarily Howard Butler) maintains SWIG generated Python bindings for GDAL and OGR.  Generally speaking the classes and methods mostly match those of the GDAL and OGR C++ classes.  There is no python specific reference documentation, but the [http://www.gdal.org/gdal_tutorial.html GDAL API Tutorial] includes Python examples.
    4 
    5 == New vs. Old Bindings ==
    6 
    7 Python was the first set of bindings supported by GDAL/OGR and though the bindings were generated with SWIG, the process was very python specific.  In 2005 Kevin Ruland launched an effort for a set of ''Next Generation'' bindings generated with SWIG and supported by a variety of languages.  With GDAL 1.4.0 the various bindings are becoming fairly mature, and the ''next generation'' python bindings are becoming the preferred set in place of the old bindings.  However for python both are still available.
    8 
    9 The ''old generation'' bindings live in the gdal/pymod directory, and are mixed up with various python utility scripts, and samples.  The ''new generation'' bindings live in the gdal/swig/python directory.  On unix to build with the old generation bindings you would configure --with-python --without-ngpython.  To build with the new generation bindings you would use --without-python --with-ngpython. 
    10 
    11 The new python bindings are generally compatible with the old bindings though some quirks exist.  As time goes on the new bindings will continue to be extended as GDAL is extended, but the old generation bindings will not.  At this time the test suite should pass with either the old or new bindings.  Some applications, such as OpenEV 1.x still depend on the old Python bindings (which is why [wiki:FWTools] still ships with the old bindings).
    12 
    13 == Numpy / Numeric ==
    14 
    15 One advanced feature of the GDAL python bindings not found in the other bindings is integration with the Python numerical array facilities.  The gdal.Dataset.!ReadAsArray() method can be used to read raster data as numerical arrays, ready to use with the Python numerical array capabilities. 
    16 
    17 These facilities have evolved somewhat over time.  In the past the package was known as "Numeric" and imported using "import Numeric".  A new generation is imported using "import numpy".  Currently the old generation bindings only support the older Numeric package, and the new generatio bindings only support the new generation numpy package.  They are mostly compatible, and by importing gdalnumeric you will get whichever is appropriate to the current bindings type.
    18 
    19 One example of GDAL/numpy integration is found in the sample [http://trac.osgeo.org/gdal/browser/trunk/gdal/pymod/samples/val_repl.py pymod/samples/val_repl.py] script.
    20 
    21 == Examples ==
    22 
    23  * [http://trac.osgeo.org/gdal/browser/trunk/gdal/swig/python/samples swig/python/samples] contains some example python scripts
    24  * [http://trac.osgeo.org/gdal/browser/trunk/gdal/swig/python/scripts swig/python/scripts] has a several interesting python utilities.
    25  * Much of the GDAL [http://trac.osgeo.org/gdal/browser/trunk/autotest autotest] suite is written in python and can be browsed for examples
     1{{{
     2#!rst
     3GDAL/OGR in Python
     4==================
     5
     6This Python package and extensions are a number of tools for programming and
     7manipulating the GDAL_ Geospatial Data Abstraction Library.  Actually, it is
     8two libraries -- GDAL for manipulating geospatial raster data and OGR for
     9manipulating geospatial vector data -- but we'll refer to the entire package
     10as the GDAL library for the purposes of this document.
     11
     12The GDAL project (primarily Howard Butler) maintains SWIG generated Python
     13bindings for GDAL and OGR. Generally speaking the classes and methods mostly
     14match those of the GDAL and OGR C++ classes. There is no Python specific
     15reference documentation, but the `GDAL API Tutorial`_ includes Python examples.
     16
     17Dependencies
     18------------
     19 
     20 * libgdal (1.5.0 or greater) and header files (gdal-devel)
     21 * numpy (1.0.0 or greater) and header files (numpy-devel) (not explicitly
     22   required, but many examples and utilities will not work without it)
     23
     24Installation
     25------------
     26
     27The GDAL Python bindings support both distutils and setuptools, with a
     28preference for using setuptools.  If setuptools can be imported, setup will
     29use that to build an egg by default.  If setuptools cannot be imported, a
     30simple distutils root install of the GDAL package (and no dependency
     31chaining for numpy) will be made. 
     32
     33easy_install
     34~~~~~~~~~~~~
     35
     36GDAL can be installed from the Python CheeseShop::
     37
     38  $ sudo easy_install GDAL
     39
     40It may be necessary to have libgdal and its development headers installed
     41if easy_install is expected to do a source build because no egg is available
     42for your specified platform and Python version.
     43
     44setup.py
     45~~~~~~~~~
     46
     47Most of setup.py's important variables are controlled with the setup.cfg
     48file.  In setup.cfg, you can modify pointers to include files and libraries. 
     49The most important option that will likely need to be modified is the
     50gdal_config parameter.  If you installed GDAL from a package, the location
     51of this program is likely /usr/bin/gdal-config, but it may be in another place
     52depending on how your packager arranged things. 
     53
     54After modifying the location of gdal-config, you can build and install
     55with the setup script::
     56 
     57  $ python setup.py build
     58  $ python setup.py install
     59
     60If you have setuptools installed, you can also generate an egg::
     61 
     62  $ python setup.py bdist_egg
     63
     64Building as part of the GDAL library source tree
     65~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     66
     67You can also have the GDAL Python bindings built as part of a source
     68build by specifying --with-python as part of your configure line::
     69
     70  $ ./configure --with-python
     71
     72Use the typical make and make install commands to complete the installation::
     73 
     74  $ make
     75  $ make install
     76
     77A note about setuptools
     78.......................
     79
     80./configure attempts to detect if you have setuptools installed in the tree
     81of the Python binary it was given (or detected on the execution path), and it
     82will use an egg build by default in that instance.  If you have a need to
     83use a distutils-only install, you will have to edit setup.py to ensure that
     84the HAVE_SETUPTOOLS variable is ultimately set to False and proceed with a
     85typical 'python setup.py install' command.
     86
     87SWIG
     88----
     89
     90The GDAL Python package is built using SWIG_. The earliest version of SWIG_
     91that is supported to generate the wrapper code is 1.3.31.  It is possible
     92that usable bindings will build with a version earlier than 1.3.31, but no
     93development efforts are targeted at versions below it.  You should not have
     94to run SWIG in your development tree to generate the binding code, as it
     95is usually included with the source.  However, if you do need to regenerate,
     96you can do so with the following make command from within the ./swig/python
     97directory::
     98
     99  $ make generate
     100
     101To ensure that all of the bindings are regenerated, you can clean the
     102bindings code out before the generate command by issuing::
     103
     104  $ make veryclean
     105
     106Usage
     107-----
     108
     109Imports
     110~~~~~~~
     111
     112There are five major modules that are included with the GDAL_ Python bindings.::
     113
     114  >>> from osgeo import gdal
     115  >>> from osgeo import ogr
     116  >>> from osgeo import osr
     117  >>> from osgeo import gdal_array
     118  >>> from osgeo import gdalconst
     119
     120Additionally, there are five compatibility modules that are included but
     121provide notices to state that they are deprecated and will be going away. 
     122If you are using GDAL 1.5 bindings, you should update your imports to utilize
     123the usage above, but the following will work until at least GDAL 2.0. ::
     124
     125  >>> import gdal
     126  >>> import ogr
     127  >>> import osr
     128  >>> import gdalnumeric
     129  >>> import gdalconst
     130
     131If you have previous code that imported the global module and still need to
     132support the old import, a simple try...except import can silence the
     133deprecation warning and keep things named essentially the same as before::
     134
     135  >>> try:
     136  ...     from osgeo import gdal
     137  ... except ImportError:
     138  ...     import gdal
     139
     140Docstrings
     141~~~~~~~~~~
     142
     143Currently, only the OGR module has docstrings which are generated from the
     144C/C++ API doxygen materials.  Some of the arguments and types might not
     145match up exactly with what you are seeing from Python, but they should be
     146enough to get you going.  Docstrings for GDAL and OSR are planned for a future
     147release.
     148
     149The History of Using GDAL/OGR in Python
     150---------------------------------------
     151
     152Python was the first set of bindings supported by GDAL/OGR and though the
     153bindings were generated with SWIG (1.1 series), the process was very Python
     154specific and contained a significant amount of hand written wrapper code. In
     1552005, Kevin Ruland launched an effort for a set of next generation bindings
     156generated with SWIG (1.3 series) and supported by a variety of languages.
     157With GDAL 1.4.0 the various bindings became fairly mature, and for GDAL 1.5.0,
     158the "next-generation" bindings become the default bindings.  The previous,
     159"old-generation," bindings will continue to be available, but they will not
     160be widely supported and no new development will be targeted at them.  From
     161the viewpoint of a user, with GDAL 1.5.0 and above, you should not have to
     162worry very much about the distinction between these two development efforts.
     163
     164Usage of Old-Generation Python Bindings
     165~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     166
     167For certain legacy applications (most notably OpenEV 1.x), it may be necessary
     168to continue to use the old-generation Python bindings.  These can be built
     169and installed as part of a source build from ./configure::
     170 
     171  $ ./configure --with-ogpython=/usr/bin/python
     172
     173As noted earlier, these bindings are not widely supported and no new
     174development is expected to take place with them (including serious bug
     175fixes). 
     176
     177Numpy/Numeric
     178-------------
     179
     180One advanced feature of the GDAL Python bindings not found in the other
     181language bindings (C#, Perl) is integration with the Python numerical array
     182facilities. The gdal.Dataset.ReadAsArray() method can be used to read raster
     183data as numerical arrays, ready to use with the Python numerical array
     184capabilities.
     185
     186These facilities have evolved somewhat over time. In the past the package was
     187known as "Numeric" and imported using "import Numeric". A new generation is
     188imported using "import numpy". Currently the old generation bindings only
     189support the older Numeric package, and the new generation bindings only
     190support the new generation numpy package. They are mostly compatible, and
     191by importing gdalnumeric you will get whichever is appropriate to the
     192current bindings type.
     193
     194Examples
     195~~~~~~~~
     196
     197One example of GDAL/numpy integration is found in the `val_repl.py`_ script.
     198
     199Performance Notes
     200~~~~~~~~~~~~~~~~~
     201
     202ReadAsArray expects to make an entire copy of a raster band or dataset unless
     203the data are explicitly subsetted as part of the function call. For large
     204data, this approach is expected to be prohibitively memory intensive.
     205
     206.. _GDAL API Tutorial: http://www.gdal.org/gdal_tutorial.html
     207.. _val_repl.py: http://trac.osgeo.org/gdal/browser/trunk/gdal/swig/python/samples/val_repl.py
     208.. _GDAL: http://www.gdal.org
     209.. _SWIG: http://www.swig.org
     210}}}