1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
|
===============================
Installing Geospatial libraries
===============================
GeoDjango uses and/or provides interfaces for the following open source
geospatial libraries:
======================== ==================================== ================================ ============================
Program Description Required Supported Versions
======================== ==================================== ================================ ============================
:doc:`GEOS <../geos>` Geometry Engine Open Source Yes 3.4, 3.3
`PROJ.4`_ Cartographic Projections library Yes (PostgreSQL and SQLite only) 4.9, 4.8, 4.7, 4.6, 4.5, 4.4
:doc:`GDAL <../gdal>` Geospatial Data Abstraction Library Yes (SQLite only) 2.0, 1.11, 1.10, 1.9, 1.8, 1.7
:doc:`GeoIP <../geoip>` IP-based geolocation library No 1.4
`PostGIS`__ Spatial extensions for PostgreSQL Yes (PostgreSQL only) 2.1, 2.0
`SpatiaLite`__ Spatial extensions for SQLite Yes (SQLite only) 4.1, 4.0, 3.0
======================== ==================================== ================================ ============================
Note that older or more recent versions of these libraries *may* also work
totally fine with GeoDjango. Your mileage may vary.
..
Libs release dates:
GEOS 3.3.0 2011-05-30
GEOS 3.4.0 2013-08-11
GDAL 1.7.1 2010-02-08
GDAL 1.8.0 2011-01-13
GDAL 1.9.0 2012-01-03
GDAL 1.10.0 2013-04-29
GDAL 1.11.0 2014-04-25
PostGIS 2.0.0 2012-04-03
PostGIS 2.1.0 2013-08-17
Spatialite 3.0.0 2011-12-30
Spatialite 4.0.0 2012-11-25
Spatialite 4.1.0 2013-06-04
.. admonition:: Install GDAL
While :ref:`gdalbuild` is technically not required, it is *recommended*.
Important features of GeoDjango (including the :doc:`../layermapping`,
geometry reprojection, and the geographic admin) depend on its
functionality.
.. note::
The GeoDjango interfaces to GEOS, GDAL, and GeoIP may be used
independently of Django. In other words, no database or settings file
required -- just import them as normal from :mod:`django.contrib.gis`.
.. _PROJ.4: https://github.com/OSGeo/proj.4/wiki/
__ http://postgis.net/
__ http://www.gaia-gis.it/gaia-sins/
On Debian/Ubuntu, you are advised to install the following packages which will
install, directly or by dependency, the required geospatial libraries:
.. code-block:: console
$ sudo apt-get install binutils libproj-dev gdal-bin
Optional packages to consider:
* ``libgeoip1``: for :doc:`GeoIP <../geoip>` support
* ``gdal-bin``: for GDAL command line programs like ``ogr2ogr``
* ``python-gdal`` for GDAL's own Python bindings -- includes interfaces for raster manipulation
Please also consult platform-specific instructions if you are on :ref:`macosx`
or :ref:`windows`.
.. _build_from_source:
Building from source
====================
When installing from source on UNIX and GNU/Linux systems, please follow
the installation instructions carefully, and install the libraries in the
given order. If using MySQL or Oracle as the spatial database, only GEOS
is required.
.. note::
On Linux platforms, it may be necessary to run the ``ldconfig``
command after installing each library. For example::
$ sudo make install
$ sudo ldconfig
.. note::
OS X users are required to install `Apple Developer Tools`_ in order
to compile software from source. This is typically included on your
OS X installation DVDs.
.. _Apple Developer Tools: https://developer.apple.com/technologies/tools/
.. _geosbuild:
GEOS
----
GEOS is a C++ library for performing geometric operations, and is the default
internal geometry representation used by GeoDjango (it's behind the "lazy"
geometries). Specifically, the C API library is called (e.g., ``libgeos_c.so``)
directly from Python using ctypes.
First, download GEOS 3.4.2 from the GEOS website and untar the source
archive::
$ wget http://download.osgeo.org/geos/geos-3.4.2.tar.bz2
$ tar xjf geos-3.4.2.tar.bz2
Next, change into the directory where GEOS was unpacked, run the configure
script, compile, and install::
$ cd geos-3.4.2
$ ./configure
$ make
$ sudo make install
$ cd ..
Troubleshooting
~~~~~~~~~~~~~~~
Can't find GEOS library
^^^^^^^^^^^^^^^^^^^^^^^
When GeoDjango can't find GEOS, this error is raised:
.. code-block:: text
ImportError: Could not find the GEOS library (tried "geos_c"). Try setting GEOS_LIBRARY_PATH in your settings.
The most common solution is to properly configure your :ref:`libsettings` *or* set
:ref:`geoslibrarypath` in your settings.
If using a binary package of GEOS (e.g., on Ubuntu), you may need to :ref:`binutils`.
.. _geoslibrarypath:
``GEOS_LIBRARY_PATH``
^^^^^^^^^^^^^^^^^^^^^
If your GEOS library is in a non-standard location, or you don't want to
modify the system's library path then the :setting:`GEOS_LIBRARY_PATH`
setting may be added to your Django settings file with the full path to the
GEOS C library. For example::
GEOS_LIBRARY_PATH = '/home/bob/local/lib/libgeos_c.so'
.. note::
The setting must be the *full* path to the **C** shared library; in
other words you want to use ``libgeos_c.so``, not ``libgeos.so``.
See also :ref:`My logs are filled with GEOS-related errors <geos-exceptions-in-logfile>`.
.. _proj4:
PROJ.4
------
`PROJ.4`_ is a library for converting geospatial data to different coordinate
reference systems.
First, download the PROJ.4 source code and datum shifting files [#]_::
$ wget http://download.osgeo.org/proj/proj-4.9.1.tar.gz
$ wget http://download.osgeo.org/proj/proj-datumgrid-1.5.tar.gz
Next, untar the source code archive, and extract the datum shifting files in the
``nad`` subdirectory. This must be done *prior* to configuration::
$ tar xzf proj-4.9.1.tar.gz
$ cd proj-4.9.1/nad
$ tar xzf ../../proj-datumgrid-1.5.tar.gz
$ cd ..
Finally, configure, make and install PROJ.4::
$ ./configure
$ make
$ sudo make install
$ cd ..
.. _gdalbuild:
GDAL
----
`GDAL`__ is an excellent open source geospatial library that has support for
reading most vector and raster spatial data formats. Currently, GeoDjango only
supports :doc:`GDAL's vector data <../gdal>` capabilities [#]_.
:ref:`geosbuild` and :ref:`proj4` should be installed prior to building GDAL.
First download the latest GDAL release version and untar the archive::
$ wget http://download.osgeo.org/gdal/1.11.2/gdal-1.11.2.tar.gz
$ tar xzf gdal-1.11.2.tar.gz
$ cd gdal-1.11.2
Configure, make and install::
$ ./configure
$ make # Go get some coffee, this takes a while.
$ sudo make install
$ cd ..
.. note::
Because GeoDjango has its own Python interface, the preceding instructions
do not build GDAL's own Python bindings. The bindings may be built by
adding the ``--with-python`` flag when running ``configure``. See
`GDAL/OGR In Python`__ for more information on GDAL's bindings.
If you have any problems, please see the troubleshooting section below for
suggestions and solutions.
__ https://trac.osgeo.org/gdal/
__ https://trac.osgeo.org/gdal/wiki/GdalOgrInPython
.. _gdaltrouble:
Troubleshooting
~~~~~~~~~~~~~~~
Can't find GDAL library
^^^^^^^^^^^^^^^^^^^^^^^
When GeoDjango can't find the GDAL library, the ``HAS_GDAL`` flag
will be false:
.. code-block:: pycon
>>> from django.contrib.gis import gdal
>>> gdal.HAS_GDAL
False
The solution is to properly configure your :ref:`libsettings` *or* set
:ref:`gdallibrarypath` in your settings.
.. _gdallibrarypath:
``GDAL_LIBRARY_PATH``
^^^^^^^^^^^^^^^^^^^^^
If your GDAL library is in a non-standard location, or you don't want to
modify the system's library path then the :setting:`GDAL_LIBRARY_PATH`
setting may be added to your Django settings file with the full path to
the GDAL library. For example::
GDAL_LIBRARY_PATH = '/home/sue/local/lib/libgdal.so'
.. rubric:: Footnotes
.. [#] The datum shifting files are needed for converting data to and from
certain projections.
For example, the PROJ.4 string for the `Google projection (900913 or 3857)
<http://spatialreference.org/ref/sr-org/6864/prj/>`_ requires the
``null`` grid file only included in the extra datum shifting files.
It is easier to install the shifting files now, then to have debug a
problem caused by their absence later.
.. [#] Specifically, GeoDjango provides support for the `OGR
<http://gdal.org/ogr_arch.html>`_ library, a component of GDAL.
|
