mirror of
https://github.com/django/django.git
synced 2024-12-24 01:55:49 +00:00
Fixed #16949 -- Fixed a small typo in the GIS tutorial and also made some minor PEP8 fixes and added some code-block directives while I was at it. Thanks to jgomo3 for the report.
git-svn-id: http://code.djangoproject.com/svn/django/trunk@16911 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Julien Phalip
parent
c340f6aa4d
commit
804e32fae0
@ -7,7 +7,8 @@ Introduction
|
||||
|
||||
GeoDjango is an add-on for Django that turns it into a world-class geographic
|
||||
Web framework. GeoDjango strives to make it as simple as possible to create
|
||||
geographic Web applications, like location-based services. Some features include:
|
||||
geographic Web applications, like location-based services. Some features
|
||||
include:
|
||||
|
||||
* Django model fields for `OGC`_ geometries.
|
||||
* Extensions to Django's ORM for the querying and manipulation of spatial data.
|
||||
@ -16,8 +17,8 @@ geographic Web applications, like location-based services. Some features includ
|
||||
* Editing of geometry fields inside the admin.
|
||||
|
||||
This tutorial assumes a familiarity with Django; thus, if you're brand new to
|
||||
Django please read through the :doc:`regular tutorial </intro/tutorial01>` to introduce
|
||||
yourself with basic Django concepts.
|
||||
Django please read through the :doc:`regular tutorial </intro/tutorial01>` to
|
||||
introduce yourself with basic Django concepts.
|
||||
|
||||
.. note::
|
||||
|
||||
@ -52,7 +53,10 @@ Create a Spatial Database
|
||||
|
||||
First, a spatial database needs to be created for our project. If using
|
||||
PostgreSQL and PostGIS, then the following commands will
|
||||
create the database from a :ref:`spatial database template <spatialdb_template>`::
|
||||
create the database from a :ref:`spatial database template
|
||||
<spatialdb_template>`:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ createdb -T template_postgis geodjango
|
||||
|
||||
@ -60,7 +64,9 @@ create the database from a :ref:`spatial database template <spatialdb_template>`
|
||||
|
||||
This command must be issued by a database user that has permissions to
|
||||
create a database. Here is an example set of commands to create such
|
||||
a user::
|
||||
a user:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ sudo su - postgres
|
||||
$ createuser --createdb geo
|
||||
@ -76,12 +82,17 @@ to create a :ref:`SpatiaLite database <create_spatialite_db>`.
|
||||
Create GeoDjango Project
|
||||
------------------------
|
||||
|
||||
Use the ``django-admin.py`` script like normal to create a ``geodjango`` project::
|
||||
Use the ``django-admin.py`` script like normal to create a ``geodjango``
|
||||
project:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ django-admin.py startproject geodjango
|
||||
|
||||
With the project initialized, now create a ``world`` Django application within
|
||||
the ``geodjango`` project::
|
||||
the ``geodjango`` project:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ cd geodjango
|
||||
$ python manage.py startapp world
|
||||
@ -89,7 +100,7 @@ the ``geodjango`` project::
|
||||
Configure ``settings.py``
|
||||
-------------------------
|
||||
|
||||
The ``geodjango`` project settings are stored in the ``settings.py`` file. Edit
|
||||
The ``geodjango`` project settings are stored in the ``settings.py`` file. Edit
|
||||
the database connection settings appropriately::
|
||||
|
||||
DATABASES = {
|
||||
@ -126,9 +137,11 @@ Geographic Data
|
||||
World Borders
|
||||
-------------
|
||||
|
||||
The world borders data is available in this `zip file`__. Create a data directory
|
||||
in the ``world`` application, download the world borders data, and unzip.
|
||||
On GNU/Linux platforms the following commands should do it::
|
||||
The world borders data is available in this `zip file`__. Create a data
|
||||
directory in the ``world`` application, download the world borders data, and
|
||||
unzip. On GNU/Linux platforms the following commands should do it:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ mkdir world/data
|
||||
$ cd world/data
|
||||
@ -138,7 +151,8 @@ On GNU/Linux platforms the following commands should do it::
|
||||
|
||||
The world borders ZIP file contains a set of data files collectively known as
|
||||
an `ESRI Shapefile`__, one of the most popular geospatial data formats. When
|
||||
unzipped the world borders data set includes files with the following extensions:
|
||||
unzipped the world borders data set includes files with the following
|
||||
extensions:
|
||||
|
||||
* ``.shp``: Holds the vector data for the world borders geometries.
|
||||
* ``.shx``: Spatial index file for geometries stored in the ``.shp``.
|
||||
@ -154,7 +168,9 @@ Use ``ogrinfo`` to examine spatial data
|
||||
---------------------------------------
|
||||
|
||||
The GDAL ``ogrinfo`` utility is excellent for examining metadata about
|
||||
shapefiles (or other vector data sources)::
|
||||
shapefiles (or other vector data sources):
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ ogrinfo world/data/TM_WORLD_BORDERS-0.3.shp
|
||||
INFO: Open of `world/data/TM_WORLD_BORDERS-0.3.shp'
|
||||
@ -163,7 +179,9 @@ shapefiles (or other vector data sources)::
|
||||
|
||||
Here ``ogrinfo`` is telling us that the shapefile has one layer, and that
|
||||
layer contains polygon data. To find out more we'll specify the layer name
|
||||
and use the ``-so`` option to get only important summary information::
|
||||
and use the ``-so`` option to get only important summary information:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ ogrinfo -so world/data/TM_WORLD_BORDERS-0.3.shp TM_WORLD_BORDERS-0.3
|
||||
INFO: Open of `world/data/TM_WORLD_BORDERS-0.3.shp'
|
||||
@ -197,8 +215,8 @@ as well as detailed information for each attribute field. For example,
|
||||
``FIPS: String (2.0)`` indicates that there's a ``FIPS`` character field
|
||||
with a maximum length of 2; similarly, ``LON: Real (8.3)`` is a floating-point
|
||||
field that holds a maximum of 8 digits up to three decimal places. Although
|
||||
this information may be found right on the `world borders`_ Web site, this shows
|
||||
you how to determine this information yourself when such metadata is not
|
||||
this information may be found right on the `world borders`_ Web site, this
|
||||
shows you how to determine this information yourself when such metadata is not
|
||||
provided.
|
||||
|
||||
Geographic Models
|
||||
@ -243,24 +261,27 @@ Two important things to note:
|
||||
:class:`~django.contrib.gis.db.models.GeoManager`; this is *required*
|
||||
to perform spatial queries.
|
||||
|
||||
When declaring a geometry field on your model the default spatial reference system
|
||||
is WGS84 (meaning the `SRID`__ is 4326) -- in other words, the field coordinates are in
|
||||
longitude/latitude pairs in units of degrees. If you want the coordinate system to be
|
||||
different, then SRID of the geometry field may be customized by setting the ``srid``
|
||||
with an integer corresponding to the coordinate system of your choice.
|
||||
When declaring a geometry field on your model the default spatial reference
|
||||
system is WGS84 (meaning the `SRID`__ is 4326) -- in other words, the field
|
||||
coordinates are in longitude/latitude pairs in units of degrees. If you want
|
||||
the coordinate system to be different, then SRID of the geometry field may be
|
||||
customized by setting the ``srid`` with an integer corresponding to the
|
||||
coordinate system of your choice.
|
||||
|
||||
__ http://en.wikipedia.org/wiki/SRID
|
||||
|
||||
Run ``syncdb``
|
||||
--------------
|
||||
|
||||
After you've defined your model, it needs to be synced with the spatial database.
|
||||
First, let's look at the SQL that will generate the table for the ``WorldBorder``
|
||||
model::
|
||||
After you've defined your model, it needs to be synced with the spatial
|
||||
database. First, let's look at the SQL that will generate the table for the
|
||||
``WorldBorder`` model::
|
||||
|
||||
$ python manage.py sqlall world
|
||||
|
||||
This management command should produce the following output::
|
||||
This management command should produce the following output:
|
||||
|
||||
.. code-block:: sql
|
||||
|
||||
BEGIN;
|
||||
CREATE TABLE "world_worldborders" (
|
||||
@ -290,18 +311,19 @@ If satisfied, you may then create this table in the database by running the
|
||||
Creating table world_worldborders
|
||||
Installing custom SQL for world.WorldBorder model
|
||||
|
||||
The ``syncdb`` command may also prompt you to create an admin user; go ahead and
|
||||
do so (not required now, may be done at any point in the future using the
|
||||
The ``syncdb`` command may also prompt you to create an admin user; go ahead
|
||||
and do so (not required now, may be done at any point in the future using the
|
||||
``createsuperuser`` management command).
|
||||
|
||||
Importing Spatial Data
|
||||
======================
|
||||
|
||||
This section will show you how to take the data from the world borders
|
||||
shapefile and import it into GeoDjango models using the :ref:`ref-layermapping`.
|
||||
There are many different different ways to import data in to a
|
||||
spatial database -- besides the tools included within GeoDjango, you
|
||||
may also use the following to populate your spatial database:
|
||||
shapefile and import it into GeoDjango models using the
|
||||
:ref:`ref-layermapping`.
|
||||
There are many different ways to import data in to a spatial database --
|
||||
besides the tools included within GeoDjango, you may also use the following to
|
||||
populate your spatial database:
|
||||
|
||||
* `ogr2ogr`_: Command-line utility, included with GDAL, that
|
||||
supports loading a multitude of vector data formats into
|
||||
@ -322,7 +344,9 @@ shapefile. Included within GeoDjango is an interface to GDAL's powerful OGR
|
||||
library -- in other words, you'll be able explore all the vector data sources
|
||||
that OGR supports via a Pythonic API.
|
||||
|
||||
First, invoke the Django shell::
|
||||
First, invoke the Django shell:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ python manage.py shell
|
||||
|
||||
@ -385,7 +409,8 @@ system associated with it -- if it does, the ``srs`` attribute will return a
|
||||
'+proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs '
|
||||
|
||||
Here we've noticed that the shapefile is in the popular WGS84 spatial reference
|
||||
system -- in other words, the data uses units of degrees longitude and latitude.
|
||||
system -- in other words, the data uses units of degrees longitude and
|
||||
latitude.
|
||||
|
||||
In addition, shapefiles also support attribute fields that may contain
|
||||
additional data. Here are the fields on the World Borders layer:
|
||||
@ -484,7 +509,9 @@ A few notes about what's going on:
|
||||
the shapefile. This ensures that string values are read and saved correctly
|
||||
from their original encoding system.
|
||||
|
||||
Afterwards, invoke the Django shell from the ``geodjango`` project directory::
|
||||
Afterwards, invoke the Django shell from the ``geodjango`` project directory:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ python manage.py shell
|
||||
|
||||
@ -502,10 +529,12 @@ Try ``ogrinspect``
|
||||
Now that you've seen how to define geographic models and import data with the
|
||||
:ref:`ref-layermapping`, it's possible to further automate this process with
|
||||
use of the :djadmin:`ogrinspect` management command. The :djadmin:`ogrinspect`
|
||||
command introspects a GDAL-supported vector data source (e.g., a shapefile) and
|
||||
generates a model definition and ``LayerMapping`` dictionary automatically.
|
||||
command introspects a GDAL-supported vector data source (e.g., a shapefile)
|
||||
and generates a model definition and ``LayerMapping`` dictionary automatically.
|
||||
|
||||
The general usage of the command goes as follows::
|
||||
The general usage of the command goes as follows:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ python manage.py ogrinspect [options] <data_source> <model_name> [options]
|
||||
|
||||
@ -514,7 +543,9 @@ Where ``data_source`` is the path to the GDAL-supported data source and
|
||||
be used to further define how the model is generated.
|
||||
|
||||
For example, the following command nearly reproduces the ``WorldBorder`` model
|
||||
and mapping dictionary created above, automatically::
|
||||
and mapping dictionary created above, automatically:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ python manage.py ogrinspect world/data/TM_WORLD_BORDERS-0.3.shp WorldBorder --srid=4326 --mapping --multi
|
||||
|
||||
@ -522,7 +553,8 @@ A few notes about the command-line options given above:
|
||||
|
||||
* The ``--srid=4326`` option sets the SRID for the geographic field.
|
||||
* The ``--mapping`` option tells ``ogrinspect`` to also generate a
|
||||
mapping dictionary for use with :class:`~django.contrib.gis.utils.LayerMapping`.
|
||||
mapping dictionary for use with
|
||||
:class:`~django.contrib.gis.utils.LayerMapping`.
|
||||
* The ``--multi`` option is specified so that the geographic field is a
|
||||
:class:`~django.contrib.gis.db.models.MultiPolygonField` instead of just a
|
||||
:class:`~django.contrib.gis.db.models.PolygonField`.
|
||||
@ -571,7 +603,9 @@ Spatial Lookups
|
||||
---------------
|
||||
GeoDjango extends the Django ORM and allows the use of spatial lookups.
|
||||
Let's do an example where we find the ``WorldBorder`` model that contains
|
||||
a point. First, fire up the management shell::
|
||||
a point. First, fire up the management shell:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ python manage.py shell
|
||||
|
||||
@ -592,8 +626,8 @@ a ``contains`` lookup using the ``pnt_wkt`` as the parameter::
|
||||
|
||||
Here we retrieved a ``GeoQuerySet`` that has only one model: the one
|
||||
for the United States (which is what we would expect). Similarly,
|
||||
a :ref:`GEOS geometry object <ref-geos>` may also be used -- here the ``intersects``
|
||||
spatial lookup is combined with the ``get`` method to retrieve
|
||||
a :ref:`GEOS geometry object <ref-geos>` may also be used -- here the
|
||||
``intersects`` spatial lookup is combined with the ``get`` method to retrieve
|
||||
only the ``WorldBorder`` instance for San Marino instead of a queryset::
|
||||
|
||||
>>> from django.contrib.gis.geos import Point
|
||||
@ -641,9 +675,9 @@ __ http://spatialreference.org/ref/epsg/32140/
|
||||
Lazy Geometries
|
||||
---------------
|
||||
Geometries come to GeoDjango in a standardized textual representation. Upon
|
||||
access of the geometry field, GeoDjango creates a `GEOS geometry object <ref-geos>`,
|
||||
exposing powerful functionality, such as serialization properties for
|
||||
popular geospatial formats::
|
||||
access of the geometry field, GeoDjango creates a `GEOS geometry object
|
||||
<ref-geos>`, exposing powerful functionality, such as serialization properties
|
||||
for popular geospatial formats::
|
||||
|
||||
>>> sm = WorldBorder.objects.get(name='San Marino')
|
||||
>>> sm.mpoly
|
||||
@ -706,7 +740,9 @@ as follows::
|
||||
(r'^admin/', include(admin.site.urls)),
|
||||
)
|
||||
|
||||
Start up the Django development server::
|
||||
Start up the Django development server:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ python manage.py runserver
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user