Учебник по GeoDjango

Введение

GeoDjango — это модуль contrib для Django, который превращает его в полнофункциональный географический веб-фреймворк. GeoDjango стремится упростить создание географических веб-приложений, таких как сервисы с привязкой к местоположению. Его возможности включают:

• Поля модели Django для геометрий OGC.
• Расширения ORM Django для запросов и манипулирования пространственными данными.
• Слабосвязанные, высокоуровневые Python-интерфейсы для операций с геометрией ГИС и форматами данных.
• Редактирование полей геометрии в админском интерфейсе.

Этот учебник предполагает знакомство с Django; поэтому, если вы новичок в Django, пожалуйста, прочтите обычный учебник, чтобы сначала ознакомиться с Django.

Этот учебник проведет вас через создание географического веб-приложения для просмотра границ стран мира. [1] Некоторые фрагменты кода, используемые в этом учебнике, взяты из проекта GeoDjango basic apps или вдохновлены им. [2]

Настройка

Создание пространственной базы данных

Сначала создайте пространственную базу данных для своего проекта.

Если вы используете PostGIS, создайте базу данных из шаблона пространственной базы данных:

$ createdb -T template_postgis geodjango

$ sudo su - postgres
$ createuser --createdb geo
$ exit

Если вы используете SQLite и SpatiaLite, ознакомьтесь с инструкциями по созданию базы данных SpatiaLite.

Создание нового проекта

Используйте стандартный django-admin скрипт для создания проекта под названием geodjango:

$ django-admin startproject geodjango

Это инициализирует новый проект. Теперь создайте world приложение Django в рамках проекта geodjango:

$ cd geodjango
$ python manage.py startapp world

Настройка settings.py

Настройки проекта geodjango хранятся в файле geodjango/settings.py. Измените настройки подключения к базе данных, чтобы они соответствовали вашей настройке:

DATABASES = {
    'default': {
         'ENGINE': 'django.contrib.gis.db.backends.postgis',
         'NAME': 'geodjango',
         'USER': 'geo',
    },
}

Кроме того, измените настройку INSTALLED_APPS, чтобы включить django.contrib.admin, django.contrib.gis и world (ваше недавно созданное приложение):

INSTALLED_APPS = (
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'django.contrib.gis',
    'world',
)

Географические данные

Границы стран

Данные о границах стран доступны в этом файле zip. Создайте директорию data в приложении world, загрузите данные о границах стран, и распакуйте их. На платформах GNU/Linux используйте следующие команды:

$ mkdir world/data
$ cd world/data
$ wget http://thematicmapping.org/downloads/TM_WORLD_BORDERS-0.3.zip
$ unzip TM_WORLD_BORDERS-0.3.zip
$ cd ../..

Файл ZIP с границами стран содержит набор файлов данных, которые вместе известны как ESRI Shapefile — один из самых популярных форматов пространственных данных. При распаковке набор данных о границах стран содержит файлы со следующими расширениями:

• .shp: Содержит векторные данные для геометрии границ стран.
• .shx: Файл пространственного индекса для геометрий, хранящихся в .shp.
• .dbf: Файл базы данных для хранения атрибутивных данных, не являющихся геометрическими (например, целые числа и символьные поля).
• .prj: Содержит информацию о системе пространственной привязки для географических данных, хранящихся в shapefile.

Использование ogrinfo для просмотра пространственных данных

Утилита GDAL ogrinfo позволяет просматривать метаданные shapefile или других источников векторных данных:

$ ogrinfo world/data/TM_WORLD_BORDERS-0.3.shp
INFO: Open of `world/data/TM_WORLD_BORDERS-0.3.shp'
      using driver `ESRI Shapefile' successful.
1: TM_WORLD_BORDERS-0.3 (Polygon)

ogrinfo указывает, что shapefile содержит один слой, и этот слой содержит полигональные данные. Чтобы узнать больше, укажем имя слоя и воспользуемся опцией -so для получения только важной сводной информации:

$ 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'
      using driver `ESRI Shapefile' successful.

Layer name: TM_WORLD_BORDERS-0.3
Geometry: Polygon
Feature Count: 246
Extent: (-180.000000, -90.000000) - (180.000000, 83.623596)
Layer SRS WKT:
GEOGCS["GCS_WGS_1984",
    DATUM["WGS_1984",
        SPHEROID["WGS_1984",6378137.0,298.257223563]],
    PRIMEM["Greenwich",0.0],
    UNIT["Degree",0.0174532925199433]]
FIPS: String (2.0)
ISO2: String (2.0)
ISO3: String (3.0)
UN: Integer (3.0)
NAME: String (50.0)
AREA: Integer (7.0)
POP2005: Integer (10.0)
REGION: Integer (3.0)
SUBREGION: Integer (3.0)
LON: Real (8.3)
LAT: Real (7.3)

Эта подробная сводная информация сообщает о количестве объектов в слое (246), географических границах данных, системе пространственной привязки («SRS WKT»), а также информации о типе каждого атрибутивного поля. Например, FIPS: String (2.0) указывает, что символьное поле FIPS имеет максимальную длину 2. Аналогично, LON: Real (8.3) — это поле с плавающей точкой, которое может содержать максимум 8 цифр до трех десятичных знаков.

Географические модели

Определение географической модели

Теперь, когда вы изучили свой набор данных с помощью ogrinfo, создайте модель GeoDjango для представления этих данных:

from django.contrib.gis.db import models

class WorldBorder(models.Model):
    # Regular Django fields corresponding to the attributes in the
    # world borders shapefile.
    name = models.CharField(max_length=50)
    area = models.IntegerField()
    pop2005 = models.IntegerField('Population 2005')
    fips = models.CharField('FIPS Code', max_length=2)
    iso2 = models.CharField('2 Digit ISO', max_length=2)
    iso3 = models.CharField('3 Digit ISO', max_length=3)
    un = models.IntegerField('United Nations Code')
    region = models.IntegerField('Region Code')
    subregion = models.IntegerField('Sub-Region Code')
    lon = models.FloatField()
    lat = models.FloatField()

    # GeoDjango-specific: a geometry field (MultiPolygonField), and
    # overriding the default manager with a GeoManager instance.
    mpoly = models.MultiPolygonField()
    objects = models.GeoManager()

    # Returns the string representation of the model.
    def __str__(self):              # __unicode__ on Python 2
        return self.name

Обратите внимание на две важные вещи:

1. Модуль models импортируется из django.contrib.gis.db.
2. Вы должны переопределить менеджер модели по умолчанию с помощью GeoManager для выполнения пространственных запросов.

Система пространственной привязки по умолчанию для полей геометрии — WGS84 (что означает, что SRID равен 4326) — другими словами, координаты поля представлены парами долготы и широты в градусах. Для использования другой системы координат установите SRID поля геометрии с помощью аргумента srid. Используйте целое число, представляющее код EPSG системы координат.

Выполнение migrate

После определения модели необходимо синхронизировать её с базой данных. Сначала создайте миграцию базы данных:

$ python manage.py makemigrations
Migrations for 'world':
  0001_initial.py:
    - Create model WorldBorder

Давайте посмотрим на SQL-запрос, который сгенерирует таблицу для модели WorldBorder:

$ python manage.py sqlmigrate world 0001

Эта команда должна вывести следующий результат:

BEGIN;
CREATE TABLE "world_worldborder" (
    "id" serial NOT NULL PRIMARY KEY,
    "name" varchar(50) NOT NULL,
    "area" integer NOT NULL,
    "pop2005" integer NOT NULL,
    "fips" varchar(2) NOT NULL,
    "iso2" varchar(2) NOT NULL,
    "iso3" varchar(3) NOT NULL,
    "un" integer NOT NULL,
    "region" integer NOT NULL,
    "subregion" integer NOT NULL,
    "lon" double precision NOT NULL,
    "lat" double precision NOT NULL
    "mpoly" geometry(MULTIPOLYGON,4326) NOT NULL
)
;
CREATE INDEX "world_worldborder_mpoly_id" ON "world_worldborder" USING GIST ( "mpoly" );
COMMIT;

Если это выглядит правильно, выполните migrate, чтобы создать эту таблицу в базе данных:

$ python manage.py migrate
Operations to perform:
  Apply all migrations: admin, world, contenttypes, auth, sessions
Running migrations:
  ...
  Applying world.0001_initial... OK

Импорт пространственных данных

Этот раздел покажет вам, как импортировать shapefile с границами стран в базу данных через модели GeoDjango, используя утилиту импорта данных LayerMapping.

Существует множество способов импорта данных в пространственную базу данных — помимо инструментов, включённых в GeoDjango, вы также можете использовать следующие:

• ogr2ogr: Утилита командной строки, включённая в GDAL, которая может импортировать множество форматов векторных данных в базы данных PostGIS, MySQL и Oracle.
• shp2pgsql: Эта утилита, включённая в PostGIS, импортирует ESRI shapefiles в PostGIS.

Интерфейс GDAL

Ранее вы использовали ogrinfo для просмотра содержимого shapefile с границами стран. GeoDjango также включает Python-интерфейс к мощной библиотеке GDAL OGR, которая может работать со всеми источниками векторных данных, поддерживаемыми OGR.

Сначала вызовите оболочку Django:

$ python manage.py shell

Если вы загрузили данные о границах стран ранее в учебнике, вы можете определить их путь, используя встроенный модуль Python os:

>>> import os
>>> import world
>>> world_shp = os.path.abspath(os.path.join(os.path.dirname(world.__file__),
...                             'data', 'TM_WORLD_BORDERS-0.3.shp'))

Теперь откройте shapefile с границами стран, используя интерфейс GeoDjango DataSource:

>>> from django.contrib.gis.gdal import DataSource
>>> ds = DataSource(world_shp)
>>> print(ds)
/ ... /geodjango/world/data/TM_WORLD_BORDERS-0.3.shp (ESRI Shapefile)

Объекты источника данных могут иметь разные слои географических объектов; однако shapefiles могут содержать только один слой:

>>> print(len(ds))
1
>>> lyr = ds[0]
>>> print(lyr)
TM_WORLD_BORDERS-0.3

Вы можете увидеть тип геометрии слоя и количество объектов в нём:

>>> print(lyr.geom_type)
Polygon
>>> print(len(lyr))
246

В Layer также может быть связана система пространственной привязки. Если она есть, атрибут srs вернёт объект SpatialReference:

>>> srs = lyr.srs
>>> print(srs)
GEOGCS["GCS_WGS_1984",
    DATUM["WGS_1984",
        SPHEROID["WGS_1984",6378137.0,298.257223563]],
    PRIMEM["Greenwich",0.0],
    UNIT["Degree",0.0174532925199433]]
>>> srs.proj4 # PROJ.4 representation
'+proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs '

Этот шейп-файл находится в популярной пространственной системе координат WGS84 – другими словами, данные используют пары долготы и широты в единицах градусов.

Кроме того, шейп-файлы также поддерживают атрибутивные поля, которые могут содержать дополнительные данные. Вот поля слоя «Границы стран мира»:

>>> print(lyr.fields)
['FIPS', 'ISO2', 'ISO3', 'UN', 'NAME', 'AREA', 'POP2005', 'REGION', 'SUBREGION', 'LON', 'LAT']

Следующий код позволит вам изучить типы OGR (например, целое число или строка), связанные с каждым из полей:

>>> [fld.__name__ for fld in lyr.field_types]
['OFTString', 'OFTString', 'OFTString', 'OFTInteger', 'OFTString', 'OFTInteger', 'OFTInteger', 'OFTInteger', 'OFTInteger', 'OFTReal', 'OFTReal']

Вы можете перебирать каждый объект в слое и извлекать информацию как из геометрии объекта (доступ к которой осуществляется через атрибут geom), так и из атрибутивных полей объекта (значения которых доступны через метод get()):

>>> for feat in lyr:
...    print(feat.get('NAME'), feat.geom.num_points)
...
Guernsey 18
Jersey 26
South Georgia South Sandwich Islands 338
Taiwan 363

Layer объекты могут быть срезаны:

>>> lyr[0:2]
[<django.contrib.gis.gdal.feature.Feature object at 0x2f47690>, <django.contrib.gis.gdal.feature.Feature object at 0x2f47650>]

И отдельные объекты могут быть извлечены по их идентификатору:

>>> feat = lyr[234]
>>> print(feat.get('NAME'))
San Marino

Геометрии границ могут быть экспортированы как WKT и GeoJSON:

>>> geom = feat.geom
>>> print(geom.wkt)
POLYGON ((12.415798 43.957954,12.450554 ...
>>> print(geom.json)
{ "type": "Polygon", "coordinates": [ [ [ 12.415798, 43.957954 ], [ 12.450554, 43.979721 ], ...

LayerMapping

Для импорта данных используйте LayerMapping в скрипте Python. Создайте файл с именем load.py внутри приложения world, с кодом:

import os
from django.contrib.gis.utils import LayerMapping
from .models import WorldBorder

world_mapping = {
    'fips' : 'FIPS',
    'iso2' : 'ISO2',
    'iso3' : 'ISO3',
    'un' : 'UN',
    'name' : 'NAME',
    'area' : 'AREA',
    'pop2005' : 'POP2005',
    'region' : 'REGION',
    'subregion' : 'SUBREGION',
    'lon' : 'LON',
    'lat' : 'LAT',
    'mpoly' : 'MULTIPOLYGON',
}

world_shp = os.path.abspath(os.path.join(os.path.dirname(__file__), 'data', 'TM_WORLD_BORDERS-0.3.shp'))

def run(verbose=True):
    lm = LayerMapping(WorldBorder, world_shp, world_mapping,
                      transform=False, encoding='iso-8859-1')

    lm.save(strict=True, verbose=verbose)

Несколько примечаний о том, что происходит:

• Каждый ключ в словаре world_mapping соответствует полю в модели WorldBorder. Значение – это имя поля шейп-файла, из которого будут загружаться данные.
• Ключ mpoly для поля геометрии – это MULTIPOLYGON, тип геометрии, который GeoDjango импортирует как поле. Даже простые многоугольники в шейп-файле автоматически преобразуются в коллекции перед вставкой в базу данных.
• Путь к шейп-файлу не является абсолютным – другими словами, если вы перемещаете приложение world (с подкаталогом data) в другое место, скрипт всё равно будет работать.
• Ключевое слово transform установлено в значение False, поскольку данные в шейп-файле не требуют преобразования – они уже находятся в системе координат WGS84 (SRID=4326).
• Ключевое слово encoding установлено в кодировку символов строковых значений в шейп-файле. Это гарантирует, что строковые значения считываются и сохраняются правильно из их исходной кодировочной системы.

Затем вызовите Django shell из каталога проекта geodjango:

$ python manage.py shell

Далее, импортируйте модуль load, вызовите процедуру run, и наблюдайте, как LayerMapping выполняет свою работу:

>>> from world import load
>>> load.run()

Попробуйте ogrinspect

Теперь, когда вы увидели, как определять географические модели и импортировать данные с помощью утилиты импорта данных LayerMapping, вы можете дополнительно автоматизировать этот процесс с помощью команды управления ogrinspect. Команда ogrinspect инспектирует источник векторных данных, поддерживаемых GDAL (например, шейп-файл), и автоматически генерирует определение модели и словарь LayerMapping.

Общее использование команды следующее:

$ python manage.py ogrinspect [options] <data_source> <model_name> [options]

data_source — путь к источнику данных, поддерживаемому GDAL, а model_name — имя, используемое для модели. Используя опции командной строки, можно дополнительно определить, как генерируется модель.

Например, следующая команда практически воспроизводит модель WorldBorder и словарь сопоставлений, созданные выше, автоматически:

$ python manage.py ogrinspect world/data/TM_WORLD_BORDERS-0.3.shp WorldBorder \
    --srid=4326 --mapping --multi

Несколько примечаний об опциях командной строки, указанных выше:

• Опция --srid=4326 задаёт SRID для географического поля.
• Опция --mapping указывает команде ogrinspect также сгенерировать словарь сопоставлений для использования с LayerMapping.
• Опция --multi задаётся для того, чтобы географическое поле было MultiPolygonField, а не просто PolygonField.

Команда генерирует следующий вывод, который можно скопировать непосредственно в models.py приложения GeoDjango:

# This is an auto-generated Django model module created by ogrinspect.
from django.contrib.gis.db import models

class WorldBorder(models.Model):
    fips = models.CharField(max_length=2)
    iso2 = models.CharField(max_length=2)
    iso3 = models.CharField(max_length=3)
    un = models.IntegerField()
    name = models.CharField(max_length=50)
    area = models.IntegerField()
    pop2005 = models.IntegerField()
    region = models.IntegerField()
    subregion = models.IntegerField()
    lon = models.FloatField()
    lat = models.FloatField()
    geom = models.MultiPolygonField(srid=4326)
    objects = models.GeoManager()

# Auto-generated `LayerMapping` dictionary for WorldBorder model
worldborders_mapping = {
    'fips' : 'FIPS',
    'iso2' : 'ISO2',
    'iso3' : 'ISO3',
    'un' : 'UN',
    'name' : 'NAME',
    'area' : 'AREA',
    'pop2005' : 'POP2005',
    'region' : 'REGION',
    'subregion' : 'SUBREGION',
    'lon' : 'LON',
    'lat' : 'LAT',
    'geom' : 'MULTIPOLYGON',
}

Пространственные запросы

Пространственные поиски

GeoDjango добавляет пространственные поиски в Django ORM. Например, вы можете найти страну в таблице WorldBorder, содержащую определённую точку. Сначала запустите оболочку управления:

$ python manage.py shell

Теперь определите точку интереса [3]:

>>> pnt_wkt = 'POINT(-95.3385 29.7245)'

Строка pnt_wkt представляет точку с координатами -95.3385 градусов долготы и 29.7245 градусов широты. Геометрия представлена в формате Well Known Text (WKT), стандарт, выпущенный Open Geospatial Consortium (OGC). [4] Импортируйте модель WorldBorder и выполните поиск contains с использованием pnt_wkt в качестве параметра:

>>> from world.models import WorldBorder
>>> qs = WorldBorder.objects.filter(mpoly__contains=pnt_wkt)
>>> qs
[<WorldBorder: United States>]

Здесь вы извлекли GeoQuerySet только с одной моделью: границей Соединенных Штатов (в точности как ожидалось).

Аналогично, вы также можете использовать объект геометрии GEOS. Здесь вы можете объединить пространственный поиск intersects с методом get, чтобы получить только экземпляр WorldBorder для Сан-Марино, а не весь запрос:

>>> from django.contrib.gis.geos import Point
>>> pnt = Point(12.4604, 43.9420)
>>> sm = WorldBorder.objects.get(mpoly__intersects=pnt)
>>> sm
<WorldBorder: San Marino>

Поиски contains и intersects – это лишь подмножество доступных запросов – документация GeoDjango Database API содержит больше информации.

Автоматические пространственные преобразования

При выполнении пространственных запросов GeoDjango автоматически преобразует геометрии, если они находятся в другой системе координат. В следующем примере координаты будут выражены в системе координат EPSG SRID 32140, специфичной для Южной Техаса только и в единицах метров, а не градусов:

>>> from django.contrib.gis.geos import Point, GEOSGeometry
>>> pnt = Point(954158.1, 4215137.1, srid=32140)

Обратите внимание, что pnt также может быть создан с помощью EWKT, «расширенного» формата WKT, который включает SRID:

>>> pnt = GEOSGeometry('SRID=32140;POINT(954158.1 4215137.1)')

ORM GeoDjango автоматически обернёт значения геометрии в SQL-преобразования, позволяя разработчику работать на более высоком уровне абстракции:

>>> qs = WorldBorder.objects.filter(mpoly__intersects=pnt)
>>> print(qs.query) # Generating the SQL
SELECT "world_worldborder"."id", "world_worldborder"."name", "world_worldborder"."area",
"world_worldborder"."pop2005", "world_worldborder"."fips", "world_worldborder"."iso2",
"world_worldborder"."iso3", "world_worldborder"."un", "world_worldborder"."region",
"world_worldborder"."subregion", "world_worldborder"."lon", "world_worldborder"."lat",
"world_worldborder"."mpoly" FROM "world_worldborder"
WHERE ST_Intersects("world_worldborder"."mpoly", ST_Transform(%s, 4326))
>>> qs # printing evaluates the queryset
[<WorldBorder: United States>]

City.objects.raw('SELECT id, name, asText(point) from myapp_city')

Ленивые геометрии

GeoDjango загружает геометрии в стандартизированном текстовом представлении. При первом обращении к полю геометрии GeoDjango создаёт GEOS geometry object <ref-geos>, раскрывая мощные возможности, такие как свойства сериализации для популярных геопространственных форматов:

>>> sm = WorldBorder.objects.get(name='San Marino')
>>> sm.mpoly
<MultiPolygon object at 0x24c6798>
>>> sm.mpoly.wkt # WKT
MULTIPOLYGON (((12.4157980000000006 43.9579540000000009, 12.4505540000000003 43.9797209999999978, ...
>>> sm.mpoly.wkb # WKB (as Python binary buffer)
<read-only buffer for 0x1fe2c70, size -1, offset 0 at 0x2564c40>
>>> sm.mpoly.geojson # GeoJSON (requires GDAL)
'{ "type": "MultiPolygon", "coordinates": [ [ [ [ 12.415798, 43.957954 ], [ 12.450554, 43.979721 ], ...

Это включает доступ ко всем расширенным геометрическим операциям, предоставляемым библиотекой GEOS:

>>> pnt = Point(12.4604, 43.9420)
>>> sm.mpoly.contains(pnt)
True
>>> pnt.contains(sm.mpoly)
False

GeoQuerySet Методы

Отображение данных на карте

Географический администратор

GeoDjango расширяет приложение администратора Django с поддержкой редактирования полей геометрии.

Основы

GeoDjango дополняет администратор Django, позволяя пользователям создавать и изменять геометрии на JavaScript-карте (на основе OpenLayers).

Давайте сразу приступим. Создайте файл с именем admin.py внутри приложения world с указанным кодом:

from django.contrib.gis import admin
from .models import WorldBorder

admin.site.register(WorldBorder, admin.GeoModelAdmin)

Далее, отредактируйте файл urls.py в папке приложения geodjango следующим образом:

from django.conf.urls import url, include
from django.contrib.gis import admin

urlpatterns = [
    url(r'^admin/', include(admin.site.urls)),
]

Создайте пользователя администратора:

$ python manage.py createsuperuser

Затем запустите сервер разработки Django:

$ python manage.py runserver

Наконец, перейдите к http://localhost:8000/admin/, и войдите в систему с созданным пользователем. Перейдите к любой из записей WorldBorder – границы могут быть изменены путём клика на многоугольник и перемещения вершин в нужное положение.

OSMGeoAdmin

С помощью OSMGeoAdmin, GeoDjango использует слой OpenStreetMap в администраторе. Это обеспечивает больший контекст (включая улицы и проезжие части), чем с GeoModelAdmin (который использует набор данных WMS Vector Map Level 0, размещённый в OSGeo).

Сначала есть некоторые важные требования:

• OSMGeoAdmin требует установки GDAL.
• Должны быть установлены файлы сдвига референций DATUM PROJ.4 (подробнее см. инструкции по установке PROJ.4).

Если вы выполнили эти требования, замените класс опции OSMGeoAdmin в файле admin.py:

admin.site.register(WorldBorder, admin.OSMGeoAdmin)

Примечания