djangorestframework-gis 1.1

GeometryField

提供 GeometryField，它是 Django Rest Framework (以下简称 DRF) 的子类 WritableField。该字段处理 GeoDjango 几何字段，为 GeoJSON 输入/输出提供自定义的 to_native 和 from_native 方法。

此字段接受三个可选参数

• precision：通过 Python 内置的 round() 函数（文档）传递坐标，将值四舍五入到提供的精度级别。例如，一个经纬度为 [51.0486, -114.0708] 的点通过 GeometryField(precision=2) 传递，将返回一个经纬度为 [51.05, -114.07] 的点。

• remove_duplicates：从线和多边形几何中删除重复的坐标。当与 precision 参数一起使用时，这特别有用，因为坐标的重复概率会随着坐标精度的降低而增加。

• auto_bbox：如果为 True，GeoJSON 对象将包含一个 边界框，即包围几何形状的最小可能矩形。

注意：虽然 precision 和 remove_duplicates 设计用于减小 API 响应的字节大小，但它们也会增加渲染响应所需的处理时间。对于小的 GeoJSON 响应，这可能是微不足道的，但对于大型响应可能会成为问题。

自 0.9.3 以来新增：无需在序列化器中显式定义此字段，它将在 rest_framework_gis.apps.AppConfig.ready() 初始化期间自动映射。

GeometrySerializerMethodField

提供了一种名为 GeometrySerializerMethodField 的字段，它是 DRF SerializerMethodField 的子类，用于处理通过序列化方法计算并用作 geo_field 的值。请参见下面的示例。

GeoModelSerializer (已废弃)

已废弃，将在 1.0 版本中删除：从 0.9.3 版本开始，使用此序列化器不再需要，如果将 rest_framework_gis 添加到 settings.INSTALLED_APPS，则序列化将直接与 DRF 一起工作。请参考 问题 #156。

提供了一种名为 GeoModelSerializer 的序列化器，它是 DRF ModelSerializer 的子类。此序列化器更新 field_mapping 字典，包括 GeoDjango 几何字段的映射到上面的 GeometryField。

例如，以下模型

class Location(models.Model):
    """
    A model which holds information about a particular location
    """
    address = models.CharField(max_length=255)
    city = models.CharField(max_length=100)
    state = models.CharField(max_length=100)
    point = models.PointField()

默认情况下，DRF ModelSerializer ver < 0.9.3 将输出

{
    "id": 1,
    "address": "742 Evergreen Terrace",
    "city":  "Springfield",
    "state": "Oregon",
    "point": "POINT(-123.0208 44.0464)"
}

相比之下，GeoModelSerializer 将输出

{
    "id": 1,
    "address": "742 Evergreen Terrace",
    "city":  "Springfield",
    "state": "Oregon",
    "point": {
        "type": "Point",
        "coordinates": [-123.0208, 44.0464],
    }
}

注意：对于 ver>=0.9.3：如果；

• rest_framework_gis 设置在 settings.INSTALLED_APPS 或

• 序列化器中的字段明确设置为 GeometryField，则 DRF 模型序列化器将给出与上面相同的输出。

GeoFeatureModelSerializer

GeoFeatureModelSerializer 是 rest_framework.ModelSerializer 的子类，它将以与 GeoJSON 兼容的格式输出数据。使用上面的示例，GeoFeatureModelSerializer 将输出

 {
    "id": 1,
    "type": "Feature",
    "geometry": {
        "type": "Point",
        "coordinates": [-123.0208, 44.0464],
    },
    "properties": {
        "address": "742 Evergreen Terrace",
        "city":  "Springfield",
        "state": "Oregon"
    }
}

如果您正在序列化对象列表，GeoFeatureModelSerializer 将创建一个 FeatureCollection

{
    "type": "FeatureCollection",
    "features": [
    {
        "id": 1
        "type": "Feature",
        "geometry": {
            "type": "Point",
            "coordinates": [-123.0208, 44.0464],
        },
        "properties": {
            "address": "742 Evergreen Terrace",
            "city":  "Springfield",
            "state": "Oregon",
        }
    }
    {
        "id": 2,
        "type": "Feature",
        "geometry": {
            "type": "Point",
            "coordinates": [-123.0208, 44.0489],
        },
        "properties": {
            "address": "744 Evergreen Terrace",
            "city":  "Springfield",
            "state": "Oregon"
        }
    }
}

from rest_framework_gis.serializers import GeoFeatureModelSerializer

class LocationSerializer(GeoFeatureModelSerializer):
    """ A class to serialize locations as GeoJSON compatible data """

    class Meta:
        model = Location
        geo_field = "point"

        # you can also explicitly declare which fields you want to include
        # as with a ModelSerializer.
        fields = ('id', 'address', 'city', 'state')

from django.contrib.gis.geos import Point
from rest_framework_gis.serializers import GeoFeatureModelSerializer, GeometrySerializerMethodField

class LocationSerializer(GeoFeatureModelSerializer):
    """ A class to serialize locations as GeoJSON compatible data """

    # a field which contains a geometry value and can be used as geo_field
    other_point = GeometrySerializerMethodField()

    def get_other_point(self, obj):
        return Point(obj.point.lat / 2, obj.point.lon / 2)

    class Meta:
        model = Location
        geo_field = 'other_point'

from rest_framework_gis.serializers import GeoFeatureModelSerializer

class LocationSerializer(GeoFeatureModelSerializer):

    class Meta:
        model = Location
        geo_field = "point"
        id_field = False
        fields = ('id', 'address', 'city', 'state')

from rest_framework_gis.serializers import GeoFeatureModelSerializer

class LocationSerializer(GeoFeatureModelSerializer):

    class Meta:
        model = Location
        geo_field = 'point'
        id_field = 'slug'
        fields = ('slug', 'address', 'city', 'state')

from rest_framework_gis.serializers import GeoFeatureModelSerializer

class LocationSerializer(GeoFeatureModelSerializer):
    class Meta:
        model = Location
        geo_field = 'geometry'
        auto_bbox = True

from rest_framework_gis.serializers import GeoFeatureModelSerializer

class LocationSerializer(GeoFeatureModelSerializer):

    class Meta:
        model = BoxedLocation
        geo_field = 'geometry'
        bbox_geo_field = 'bbox_geometry'

# models.py
class Link(models.Model):
    """
    Metadata is stored in a PostgreSQL HStore field, which allows us to
    store arbitrary key-value pairs with a link record.
    """
    metadata = HStoreField(blank=True, null=True, default=dict)
    geo = models.LineStringField()
    objects = models.GeoManager()

# serializers.py
class NetworkGeoSerializer(GeoFeatureModelSerializer):
    class Meta:
        model = models.Link
        geo_field = 'geo'
        auto_bbox = True

    def get_properties(self, instance, fields):
        # This is a PostgreSQL HStore field, which django maps to a dict
        return instance.metadata

    def unformat_geojson(self, feature):
        attrs = {
            self.Meta.geo_field: feature["geometry"],
            "metadata": feature["properties"]
        }

        if self.Meta.bbox_geo_field and "bbox" in feature:
            attrs[self.Meta.bbox_geo_field] = Polygon.from_bbox(feature["bbox"])

        return attrs

GeoJsonPagination

基于rest_framework.pagination.PageNumberPagination。

代码示例

from rest_framework_gis.pagination import GeoJsonPagination
# --- other omitted imports --- #

class GeojsonLocationList(generics.ListCreateAPIView):
    # -- other omitted view attributes --- #
    pagination_class = GeoJsonPagination

示例结果响应（仅截取一个元素，而不是10个）

{
    "type": "FeatureCollection",
    "count": 25,
    "next": "http://localhost:8000/geojson/?page=2",
    "previous": null,
    "features": [
        {
            "type": "Feature",
            "geometry": {
                "type": "Point",
                "coordinates": [
                    42.0,
                    50.0
                ]
            },
            "properties": {
                "name": "test"
            }
        }
    ]
}

GeometryFilter

from rest_framework_gis.filterset import GeoFilterSet
from rest_framework_gis.filters import GeometryFilter
from django_filters import filters

class RegionFilter(GeoFilterSet):
    slug = filters.CharFilter(name='slug', lookup_expr='istartswith')
    contains_geom = GeometryFilter(name='geom', lookup_expr='contains')

    class Meta:
        model = Region

然后我们可以在URL中使用GeoJSON进行过滤，并将执行一个__contains几何查找，例如：/region/?contains_geom={ "type": "Point", "coordinates": [ -123.26436996459961, 44.564178042345375 ] }。

GeoFilterSet

GeoFilterSet提供了一个与django_filter兼容的FilterSet，该FilterSet将自动为GeometryFields创建GeometryFilters。

InBBoxFilter

提供了一个InBBoxFilter，它是DRF BaseFilterBackend的子类。将查询集过滤为仅包含特定边界框内的实例。

views.py

from rest_framework_gis.filters import InBBoxFilter

class LocationList(ListAPIView):

    queryset = models.Location.objects.all()
    serializer_class = serializers.LocationSerializer
    bbox_filter_field = 'point'
    filter_backends = (InBBoxFilter,)
    bbox_filter_include_overlapping = True # Optional

然后我们可以在URL中使用边界框格式（最小经度，最小纬度，最大经度，最大纬度）进行过滤，并可以搜索边界框内的实例，例如：/location/?in_bbox=-90,29,-89,35。

默认情况下，InBBoxFilter仅返回完全位于指定边界框内的实例。要包含与边界框重叠的实例，请在您的视图中包含bbox_filter_include_overlapping = True。

注意：如果您使用其他过滤器，您还需要在视图中包含您的其他过滤器后端。例如

filter_backends = (InBBoxFilter, DjangoFilterBackend,)

TMSTileFilter

提供了一个TMSTileFilter，它是InBBoxFilter的子类。它将查询集过滤为仅包含由TMS瓦片地址定义的边界框内的实例。

views.py

from rest_framework_gis.filters import TMSTileFilter

class LocationList(ListAPIView):

    queryset = models.Location.objects.all()
    serializer_class = serializers.LocationSerializer
    bbox_filter_field = 'point'
    filter_backends = (TMSTileFilter,)
    bbox_filter_include_overlapping = True # Optional

然后我们可以在URL中进行过滤，使用TMS瓦片地址的缩放/x/y格式，例如：/location/?tile=8/100/200，这相当于对边界框(-39.37500,-71.07406,-37.96875,-70.61261)进行过滤。

有关配置选项的更多信息，请参阅InBBoxFilter。

请注意，瓦片地址从上左角开始，而不是某些实现中使用的下左角原点。

DistanceToPointFilter

提供了一个DistanceToPointFilter，它是DRF BaseFilterBackend的子类。它将查询集过滤为仅包含在给定点一定距离内的实例。

views.py

from rest_framework_gis.filters import DistanceToPointFilter

class LocationList(ListAPIView):

    queryset = models.Location.objects.all()
    serializer_class = serializers.LocationSerializer
    distance_filter_field = 'geometry'
    filter_backends = (DistanceToPointFilter,)

然后我们可以在URL中进行过滤，使用以(lon, lat)格式表示的距离和点。距离可以用米或度表示。

例如：/location/?dist=4000&point=-122.4862,37.7694&format=json，这相当于在点(-122.4862, 37.7694)周围4000米内进行过滤。

默认情况下，DistanceToPointFilter会将URL中的‘distance’直接传递给数据库进行搜索。效果取决于使用的数据库srid。如果地理数据以米为索引（srid 3875，即900913），则可以直接传递米距离，无需转换。对于如srid 4326的经纬度数据库，它以度为索引，‘distance’将被解释为度。将标志‘distance_filter_convert_meters’设置为‘True’以将输入距离从米转换为度。这种转换是近似的，且在纬度>60度时的误差大于25%。

DistanceToPointOrderingFilter

提供了一个DistanceToPointOrderingFilter，适用于Django >= 3.0，它是DistanceToPointFilter的子类。根据到给定点的距离对查询集进行排序，从最近的点到最远的点。

views.py

from rest_framework_gis.filters import DistanceToPointOrderingFilter

class LocationList(ListAPIView):

    queryset = models.Location.objects.all()
    serializer_class = serializers.LocationSerializer
    distance_ordering_filter_field = 'geometry'
    filter_backends = (DistanceToPointOrderingFilter,)

然后我们可以通过在URL中传递以(lon, lat)格式表示的点来对结果进行排序。

例如：/location/?point=-122.4862,37.7694&format=json将根据点(-122.4862, 37.7694)的距离对结果进行排序。

我们还可以通过传递order=desc来反转结果的顺序：/location/?point=-122.4862,37.7694&order=desc&format=json