GeoDjango 模型 API

本文档探讨了 GeoDjango 模型 API 的详细信息。在本节中，我们将使用邮政编码和数字高程模型的以下地理模型作为示例：

from django.contrib.gis.db import models

class Zipcode(models.Model):
    code = models.CharField(max_length=5)
    poly = models.PolygonField()

class Elevation(models.Model):
    name = models.CharField(max_length=100)
    rast = models.RasterField()

空间字段类型

空间字段由一系列几何字段类型和一个栅格字段类型组成。每个几何字段类型都对应于 OpenGIS 简单要素规范 1。栅格数据没有这样的标准。

GeometryField

class GeometryField

几何字段的基类。

PointField

class PointField

存储点。

LineStringField

class LineStringField

存储 LineString。

PolygonField

class PolygonField

存储多边形。

MultiPointField

class MultiPointField

存储 MultiPoint。

MultiLineStringField

class MultiLineStringField

存储 MultiLineString。

MultiPolygonField

class MultiPolygonField

存储 MultiPolygon。

GeometryCollectionField

class GeometryCollectionField

存储 GeometryCollection。

RasterField

class RasterField

存储 GDALRaster。

RasterField 目前只为 PostGIS 后端实现。

空间字段选项

除了可用于 Django 模型字段的常规字段选项之外，空间字段还有以下附加选项。都是可选的。

srid

BaseSpatialField.srid

将几何字段的 SRID 2（空间参考系统标识）设置为给定值。默认为 4326（也称为 WGS84，单位为经度和纬度）。

选择 SRID

为您的模型选择合适的 SRID 是开发人员应仔细考虑的重要决定。 SRID 是一个整数说明符，对应于将用于解释空间数据库中数据的投影系统。 3 投影系统为指定位置的坐标提供上下文。尽管 geodesy 的细节超出了本文档的范围，但普遍的问题是地球是球形的，而地球的表示（例如，纸质地图、Web 地图）不是。

大多数人都熟悉使用纬度和经度来引用地球表面上的位置。但是，纬度和经度是角度，而不是距离。换句话说，平面上两点之间的最短路径是直线，而曲面（例如地球）上两点之间的最短路径是的弧大圆。 4 因此，需要额外的计算来获得平面单位（例如，公里和英里）的距离。使用地理坐标系可能会给开发人员带来麻烦。例如，SpatiaLite 不具有使用地理坐标系在几何之间执行距离计算的能力，例如构建查询以查找存储为 WGS84 的县边界 5 英里内的所有点。 5

地球表面的一部分可以投影到二维或笛卡尔平面上。投影坐标系对于特定区域的应用程序特别方便，例如，如果您知道您的数据库将仅涵盖北堪萨斯中的几何图形，那么您可以考虑使用特定于该区域的投影系统。此外，投影坐标系以笛卡尔单位（例如米或英尺）定义，便于距离计算。

笔记

如果您希望在 PostGIS 中使用 WGS84 中的非点几何执行任意距离查询，并且希望获得不错的性能，请启用 GeometryField.geography 关键字，以便使用 geography 数据库类型。

其他资源：

spatialreference.org：Django 驱动的空间参考系统数据库。
The State Plane Coordinate System：一个涵盖美国使用的各种投影系统的网站。美国大部分地区遇到的空间数据将位于这些坐标系之一中，而不是位于诸如 WGS84 之类的地理坐标系中。

spatial_index

BaseSpatialField.spatial_index

默认为 True。为给定的几何字段创建空间索引。

笔记

这与 db_index 字段选项不同，因为空间索引的创建方式与常规数据库索引不同。具体来说，空间索引通常使用 R 树的变体创建，而常规数据库索引通常使用 B 树。

几何字段选项

几何字段还有其他可用选项。以下所有选项都是可选的。

dim

GeometryField.dim

此选项可用于自定义几何字段的坐标尺寸。默认情况下，它设置为 2，用于表示二维几何。对于支持它的空间后端，它可以设置为 3 以进行三维支持。

笔记

目前 3D 支持仅限于 PostGIS 和 SpatiaLite 后端。

geography

GeometryField.geography

如果设置为 True，此选项将创建一个地理类型的数据库列，而不是几何。有关详细信息，请参阅下面的地理类型部分。

笔记

地理支持仅限于 PostGIS，并将强制 SRID 为 4326。

地理类型

geography 类型为用地理坐标（例如，WGS84 经度/纬度）表示的空间特征提供本机支持。 6 与几何类型使用的平面不同，地理类型使用其数据的球面表示。在地理柱上执行的距离和测量操作会自动采用大圆弧计算并返回线性单位。换句话说，当在两个地理区域上调用 ST_Distance 时，将返回一个以米为单位的值（如果在 WGS84 中的几何列上调用，则与度相反）。

由于地理计算涉及更多数学，因此只有一部分 PostGIS 空间查找可用于地理类型。实际上，这意味着除了距离查找之外，只有以下额外的空间查找可用于地理列：

:lookup:`bboverlaps`
:lookup:`coveredby`
:lookup:`covers`
:lookup:`intersects`

如果您需要使用不支持 geography 类型作为输入的空间查找或聚合，您可以使用 Cast 数据库函数将 geography 列转换为查询中的几何类型：

from django.contrib.gis.db.models import PointField
from django.db.models.functions import Cast

Zipcode.objects.annotate(
    geom=Cast('geography_field', PointField())
).filter(geom__within=poly)

有关更多信息，PostGIS 文档包含有关确定何时使用地理数据类型而不是几何数据类型的有用部分。

脚注

1: OpenGIS Consortium, Inc., SQL 的简单特征规范。
2: 见第 id. 章节。 2.3.8，第。 39（几何值和空间参考系统）。
3: 通常，SRID 整数对应于 EPSG ( 欧洲石油调查组 ) 标识符。但是，它也可能与空间数据库的空间参考系统表中定义的自定义投影相关联。
4: 特里 A。斯洛克姆，罗伯特 B. 麦克马斯特，弗里茨 C. 凯斯勒和休 H. 霍华德， 专题制图和地理可视化 （Prentice Hall，第 2 版），在 Ch。 7.1.3.
5: 此限制不适用于 PostGIS。
6: 有关详细信息，请参阅 PostGIS Geography Type 文档。

GeoDjango 模型 API — Django 文档

目录