mirror of
https://github.com/django/django.git
synced 2025-10-25 14:46:09 +00:00
262 lines
8.4 KiB
Plaintext
262 lines
8.4 KiB
Plaintext
===============================
|
|
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.5, 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 2.1, 2.0, 1.11, 1.10, 1.9
|
|
:doc:`GeoIP <../geoip2>` IP-based geolocation library No 2
|
|
`PostGIS`__ Spatial extensions for PostgreSQL Yes (PostgreSQL only) 2.3, 2.2, 2.1
|
|
`SpatiaLite`__ Spatial extensions for SQLite Yes (SQLite only) 4.3, 4.2, 4.1, 4.0
|
|
======================== ==================================== ================================ ===================================
|
|
|
|
Note that older or more recent versions of these libraries *may* also work
|
|
totally fine with GeoDjango. Your mileage may vary.
|
|
|
|
.. versionchanged:: 1.11
|
|
|
|
In older versions, GDAL is required only for SQLite. Now it's required for
|
|
all databases.
|
|
|
|
..
|
|
Libs release dates:
|
|
GEOS 3.3.0 2011-05-30
|
|
GEOS 3.4.0 2013-08-11
|
|
GEOS 3.5.0 2015-08-15
|
|
GDAL 1.9.0 2012-01-03
|
|
GDAL 1.10.0 2013-04-29
|
|
GDAL 1.11.0 2014-04-25
|
|
GDAL 2.0.0 2015-06
|
|
GDAL 2.1.0 2016-04
|
|
PostGIS 2.1.0 2013-08-17
|
|
PostGIS 2.2.0 2015-10-17
|
|
PostGIS 2.3.0 2016-09-26
|
|
SpatiaLite 4.0.0 2012-11-25
|
|
SpatiaLite 4.1.0 2013-06-04
|
|
SpatiaLite 4.2.0 2014-07-25
|
|
SpatiaLite 4.3.0 2015-09-07
|
|
|
|
.. 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/
|
|
__ https://postgis.net/
|
|
__ https://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 <../geoip2>` support
|
|
* ``python-gdal`` for GDAL's own Python bindings -- includes interfaces for raster manipulation
|
|
|
|
Please also consult platform-specific instructions if you are on :ref:`macos`
|
|
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::
|
|
|
|
macOS users must install `Xcode`_ in order to compile software from source.
|
|
|
|
.. _Xcode: https://developer.apple.com/xcode/
|
|
|
|
.. _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.
|