| 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 | | |
| | 8 | Content migrated to https://gdal.org/api/python.html |
