Changes between Version 35 and Version 36 of GdalOgrInPython


Ignore:
Timestamp:
Apr 7, 2021, 1:26:46 AM (8 months ago)
Author:
Even Rouault
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • GdalOgrInPython

    v35 v36  
    66==================
    77
    8 This Python package and extensions are a number of tools for programming and
    9 manipulating the GDAL_ Geospatial Data Abstraction Library.  Actually, it is
    10 two libraries -- GDAL for manipulating geospatial raster data and OGR for
    11 manipulating geospatial vector data -- but we'll refer to the entire package
    12 as the GDAL library for the purposes of this document.
    13 
    14 The GDAL project (primarily Howard Butler) maintains SWIG generated Python
    15 bindings for GDAL and OGR.
    16 
    17 API
    18 ---
    19 
    20 Generally speaking the classes and methods mostly match those of the GDAL and
    21 OGR C++ classes. An automatically generated API documentation is available on
    22 http://gdal.org/python. It is far from being ideal however : you will essentially
    23 get the names of available classes and functions, but few descriptions (except
    24 for OGR classes where the OGR C documentation is copied). For more details,
    25 look at the `GDAL API Tutorial`_ includes Python examples.
    26 
    27 
    28 Tutorials
    29 ---------
    30 
    31 Chris Garrard has given courses at Utah State University on "Geoprocessing with Python using Open Source GIS" (http://www.gis.usu.edu/~chrisg/python). There are many slides, examples, test data... and homework ;-) that can be greatly helpful for beginners with GDAL/OGR in Python.
    32 
    33 Greg Petrie has an OGR related tutorial available at http://cosmicproject.org/OGR.
    34 
    35 A cookbook full of recipes for using the Python GDAL/OGR bindings : http://pcjericks.github.io/py-gdalogr-cookbook/index.html
    36 
    37 
    38 Examples
    39 --------
    40 
    41 * One example of GDAL/numpy integration is found in the `val_repl.py`_ script.
    42 * An assortment of other samples are available in the Python SVN samples directory at http://svn.osgeo.org/gdal/trunk/gdal/swig/python/samples/ with some description in the `samples README`_.
    43 * Several `GDAL utilities`_ are implemented in Python and can be useful examples.
    44 * The majority of GDAL regression tests are written in Python. They are available at http://svn.osgeo.org/gdal/trunk/autotest
    45 
    46 Gotchas
    47 -------
    48 
    49 Although GDAL's and OGR's Python bindings provide a fairly "Pythonic" wrapper around the underlying C++ code, there are several ways in which the Python bindings differ from typical Python libraries. These differences can catch Python programmers by surprise and lead to unexpected results. These differences result from the complexity of developing a large, long-lived library while continuing to maintain backward compatibility. They are being addressed over time, but until they are all gone, please review this list of `Python gotchas`_.
    50 
    51 
    52 Dependencies
    53 ------------
    54 
    55 * Python 2.X (and 3.X since GDAL 1.7.0). Python 2 versions known to work range from 2.3 to 2.7.
    56 * libgdal (1.5.0 or greater) and header files (gdal-devel)
    57 * numpy (1.0.0 or greater) and header files (numpy-devel) (not explicitly
    58   required, but many examples and utilities will not work without it).
    59 
    60 Installation
    61 ------------
    62 
    63 Unix
    64 ~~~~~~~~~~~~~
    65 
    66 The GDAL Python bindings support both distutils and setuptools, with a
    67 preference for using setuptools.  If setuptools can be imported, setup will
    68 use that to build an egg by default.  If setuptools cannot be imported, a
    69 simple distutils root install of the GDAL package (and no dependency
    70 chaining for numpy) will be made. 
    71 
    72 easy_install
    73 ~~~~~~~~~~~~
    74 
    75 GDAL can be installed from the Python CheeseShop::
    76 
    77   $ sudo easy_install GDAL
    78 
    79 It may be necessary to have libgdal and its development headers installed
    80 if easy_install is expected to do a source build because no egg is available
    81 for your specified platform and Python version.
    82 
    83 setup.py
    84 ~~~~~~~~~
    85 
    86 Most of setup.py's important variables are controlled with the setup.cfg
    87 file.  In setup.cfg, you can modify pointers to include files and libraries. 
    88 The most important option that will likely need to be modified is the
    89 gdal_config parameter.  If you installed GDAL from a package, the location
    90 of this program is likely /usr/bin/gdal-config, but it may be in another place
    91 depending on how your packager arranged things. 
    92 
    93 After modifying the location of gdal-config, you can build and install
    94 with the setup script::
    95  
    96   $ python setup.py build
    97   $ python setup.py install
    98 
    99 If you have setuptools installed, you can also generate an egg::
    100  
    101   $ python setup.py bdist_egg
    102 
    103 Building as part of the GDAL library source tree
    104 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    105 
    106 You can also have the GDAL Python bindings built as part of a source
    107 build by specifying --with-python as part of your configure line::
    108 
    109   $ ./configure --with-python
    110 
    111 Use the typical make and make install commands to complete the installation::
    112  
    113   $ make
    114   $ make install
    115 
    116 A note about setuptools
    117 .......................
    118 
    119 ./configure attempts to detect if you have setuptools installed in the tree
    120 of the Python binary it was given (or detected on the execution path), and it
    121 will use an egg build by default in that instance.  If you have a need to
    122 use a distutils-only install, you will have to edit setup.py to ensure that
    123 the HAVE_SETUPTOOLS variable is ultimately set to False and proceed with a
    124 typical 'python setup.py install' command.
    125 
    126 Windows
    127 ~~~~~~~~~~~~
    128 
    129 You will need the following items to complete an install of the GDAL Python
    130 bindings on Windows:
    131 
    132 * `GDAL Windows Binaries`_ The basic install requires the gdalwin32exe160.zip
    133   distribution file.  Other files you see in the directory are
    134   for various optional plugins and development headers/include files. After
    135   downloading the zip file, extract it to the directory of your choosing.
    136 
    137 * GDAL Python Bindings for GDAL 1.6.1 are available at the `Python Cheeseshop`_.
    138   Executable installers (MSI or egg) are available for Python 2.4, 2.5 or 2.6.
    139 
    140 As explained in the README_EXE.txt file, after unzipping the GDAL binaries you
    141 will need to modify your system path and variables. If you're not sure how to
    142 do this, read the `Microsoft KnowledgeBase doc`_
    143 
    144 1. Add the installation directory bin folder to your system PATH, remember
    145    to put a semicolon in front of it before you add to the existing path.
    146 
    147    ::
    148  
    149      C:\gdalwin32-1.6\bin
    150 
    151 2. Create a new user or system variable with the data folder from
    152    your installation.
    153 
    154    ::
    155  
    156      Name : GDAL_DATA
    157      Path : C:\gdalwin32-1.6\data
    158 
    159 Skip down to the `Usage`_ section to test your install. Note, a reboot
    160 may be required.
    161 
    162 SWIG
    163 ----
    164 
    165 The GDAL Python package is built using SWIG_. The earliest version of SWIG_
    166 that is supported to generate the wrapper code is 1.3.31.  It is possible
    167 that usable bindings will build with a version earlier than 1.3.31, but no
    168 development efforts are targeted at versions below it.  You should not have
    169 to run SWIG in your development tree to generate the binding code, as it
    170 is usually included with the source.  However, if you do need to regenerate,
    171 you can do so with the following make command from within the ./swig/python
    172 directory::
    173 
    174   $ make generate
    175 
    176 To ensure that all of the bindings are regenerated, you can clean the
    177 bindings code out before the generate command by issuing::
    178 
    179   $ make veryclean
    180 
    181 Usage
    182 -----
    183 
    184 Imports
    185 ~~~~~~~
    186 
    187 There are five major modules that are included with the GDAL_ Python bindings.::
    188 
    189   >>> from osgeo import gdal
    190   >>> from osgeo import ogr
    191   >>> from osgeo import osr
    192   >>> from osgeo import gdal_array
    193   >>> from osgeo import gdalconst
    194 
    195 Additionally, there are five compatibility modules that are included but
    196 provide notices to state that they are deprecated and will be going away. 
    197 If you are using GDAL 1.5 bindings, you should update your imports to utilize
    198 the usage above, but the following will work until at least GDAL 2.0. ::
    199 
    200   >>> import gdal
    201   >>> import ogr
    202   >>> import osr
    203   >>> import gdalnumeric
    204   >>> import gdalconst
    205 
    206 If you have previous code that imported the global module and still need to
    207 support the old import, a simple try...except import can silence the
    208 deprecation warning and keep things named essentially the same as before::
    209 
    210   >>> try:
    211   ...     from osgeo import gdal
    212   ... except ImportError:
    213   ...     import gdal
    214 
    215 Docstrings
    216 ~~~~~~~~~~
    217 
    218 Currently, only the OGR module has docstrings which are generated from the
    219 C/C++ API doxygen materials.  Some of the arguments and types might not
    220 match up exactly with what you are seeing from Python, but they should be
    221 enough to get you going.  Docstrings for GDAL and OSR are planned for a future
    222 release.
    223 
    224 
    225 The History of Using GDAL/OGR in Python
    226 ---------------------------------------
    227 
    228 Python was the first set of bindings supported by GDAL/OGR and though the
    229 bindings were generated with SWIG (1.1 series), the process was very Python
    230 specific and contained a significant amount of hand written wrapper code. In
    231 2005, Kevin Ruland launched an effort for a set of next generation bindings
    232 generated with SWIG (1.3 series) and supported by a variety of languages.
    233 With GDAL 1.4.0 the various bindings became fairly mature, and for GDAL 1.5.0,
    234 the "next-generation" bindings become the default bindings.  The previous,
    235 "old-generation," bindings will continue to be available, but they will not
    236 be widely supported and no new development will be targeted at them.  From
    237 the viewpoint of a user, with GDAL 1.5.0 and above, you should not have to
    238 worry very much about the distinction between these two development efforts.
    239 
    240 Usage of Old-Generation Python Bindings
    241 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    242 
    243 For certain legacy applications (most notably OpenEV 1.x), it may be necessary
    244 to continue to use the old-generation Python bindings.  These can be built
    245 and installed as part of a source build from ./configure::
    246  
    247   $ ./configure --with-ogpython=/usr/bin/python
    248 
    249 As noted earlier, these bindings are not widely supported and no new
    250 development is expected to take place with them (including serious bug
    251 fixes). 
    252 
    253 Numpy/Numeric
    254 -------------
    255 
    256 One advanced feature of the GDAL Python bindings not found in the other
    257 language bindings (C#, Perl) is integration with the Python numerical array
    258 facilities. The gdal.Dataset.ReadAsArray() method can be used to read raster
    259 data as numerical arrays, ready to use with the Python numerical array
    260 capabilities.
    261 
    262 These facilities have evolved somewhat over time. In the past the package was
    263 known as "Numeric" and imported using "import Numeric". A new generation is
    264 imported using "import numpy". Currently the old generation bindings only
    265 support the older Numeric package, and the new generation bindings only
    266 support the new generation numpy package. They are mostly compatible, and
    267 by importing gdalnumeric (or osgeo.gdal_array) you will get whichever is
    268 appropriate to the current bindings type.
    269 
    270 Examples
    271 ~~~~~~~~
    272 
    273 One example of GDAL/numpy integration is found in the `val_repl.py`_ script.
    274 
    275 Performance Notes
    276 ~~~~~~~~~~~~~~~~~
    277 
    278 ReadAsArray expects to make an entire copy of a raster band or dataset unless
    279 the data are explicitly subsetted as part of the function call. For large
    280 data, this approach is expected to be prohibitively memory intensive.
    281 
    282 .. _GDAL API Tutorial: http://www.gdal.org/gdal_tutorial.html
    283 .. _GDAL Windows Binaries: http://download.osgeo.org/gdal/win32/1.6/
    284 .. _Microsoft KnowledgeBase doc: http://support.microsoft.com/kb/310519
    285 .. _Python Cheeseshop: http://pypi.python.org/pypi/GDAL/1.6.1
    286 .. _val_repl.py: http://trac.osgeo.org/gdal/browser/trunk/gdal/swig/python/samples/val_repl.py
    287 .. _GDAL: http://www.gdal.org
    288 .. _SWIG: http://www.swig.org
    289 .. _Samples README: http://svn.osgeo.org/gdal/trunk/gdal/swig/python/samples/README
    290 .. _GDAL utilities: http://svn.osgeo.org/gdal/trunk/gdal/swig/python/scripts/
    291 .. _Python gotchas: http://trac.osgeo.org/gdal/wiki/PythonGotchas
    292 
     8Content migrated to https://gdal.org/api/python.html
    2939}}}