# Django 6.0.7 ドキュメント

# GeoDjango モデル API

This document explores the details of the GeoDjango Model API. Throughout this section, we'll be using the following geographic model of a ZIP code and of a Digital Elevation Model as our examples:

    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()

## 空間フィールドのタイプ

空間フィールドは一連のジオメトリフィールド型と1つのラスターフィールド型で構成されます。各ジオメトリフィールド型は OpenGIS Simple Features 仕様 [1] に対応しています。ラスターデータに対するこのような標準は存在しません。

### `GeometryField`

class GeometryField

ジオメトリフィールドの基本クラス。

### `PointField`

class PointField

`Point` を格納します。

### `LineStringField`

class LineStringField

`LineString` を格納します。

### `PolygonField`

class PolygonField

`Polygon` を格納します。

### `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] (Spatial Reference System Identity) を指定した値に設定します。デフォルトは 4326 (別名 WGS84 、単位は緯度経度)。

#### SRID の選択

Choosing an appropriate SRID for your model is an important decision that the developer should consider carefully. The SRID is an integer specifier that corresponds to the projection system that will be used to interpret the data in the spatial database. [3] Projection systems give the context to the coordinates that specify a location. Although the details of geodesy are beyond the scope of this documentation, the general problem is that the earth is spherical and representations of the earth (e.g., paper maps, web maps) are not.

Most people are familiar with using latitude and longitude to reference a location on the earth's surface. However, latitude and longitude are angles, not distances. In other words, while the shortest path between two points on a flat surface is a straight line, the shortest path between two points on a curved surface (such as the earth) is an arc of a great circle. [4]

Thus, additional computation is required to obtain distances in planar units (e.g., kilometers and miles). Using a geographic coordinate system may introduce complications for the developer later on. For example, SpatiaLite does not have the capability to perform distance calculations between geometries using geographic coordinate systems, e.g. constructing a query to find all points within 5 miles of a county boundary stored as WGS84. [5]

Portions of the earth's surface may projected onto a two-dimensional, or Cartesian, plane. Projected coordinate systems are especially convenient for region-specific applications, e.g., if you know that your database will only cover geometries in North Kansas, then you may consider using projection system specific to that region. Moreover, projected coordinate systems are defined in Cartesian units (such as meters or feet), easing distance calculations.

注釈

PostGISでWGS84の点以外のジオメトリを使用して任意の距離クエリを実行したい場合で、適切なパフォーマンスが必要な場合は、 `GeometryField.geography` キーワードを有効にして、代わりに ジオグラフィデータベース型 が使用されるようにします。

追加のリソース:

- spatialreference.org: A database of spatial reference systems.

- The State Plane Coordinate System: A website covering the various projection systems used in the United States. Much of the U.S. spatial data encountered will be in one of these coordinate systems rather than in a geographic coordinate system such as WGS84.

### `spatial_index`

BaseSpatialField.spatial_index

Defaults to `True`. Creates a spatial index for the given geometry field.

注釈

This is different from the `db_index` field option because spatial indexes are created in a different manner than regular database indexes. Specifically, spatial indexes are typically created using a variant of the R-Tree, while regular database indexes typically use B-Trees.

## ジオメトリフィールドのオプション

ジオメトリフィールドには追加オプションがあります。以下のすべてのオプションは任意です。

### `dim`

GeometryField.dim

This option may be used for customizing the coordinate dimension of the geometry field. By default, it is set to 2, for representing two-dimensional geometries. For spatial backends that support it, it may be set to 3 for three-dimensional support.

注釈

現時点では、3Dサポートは PostGIS と SpatiaLite バックエンドに限られています。

### `geography`

GeometryField.geography

If set to `True`, this option will create a database column of type geography, rather than geometry. Please refer to the geography type section below for more details.

注釈

ジオグラフィのサポートは PostGIS に限定され、SRID が 4326 に強制されます。

### `max_geom_collections`

GeometryField.max_geom_collections

New in Django 5.2.17.

This option is forwarded to the `form field` generated for this model field, bounding how many geometry collections may be contained in submitted WKB/WKT inputs before raising `ValueError`. Since spatial field assignments are lazy, it is also checked when values are accessed, e.g. when saving an instance, but not when read from a database. It defaults to `198`.

#### ジオグラフィ (Geography) 型

The geography type provides native support for spatial features represented with geographic coordinates (e.g., WGS84 longitude/latitude). [6] Unlike the plane used by a geometry type, the geography type uses a spherical representation of its data. Distance and measurement operations performed on a geography column automatically employ great circle arc calculations and return linear units. In other words, when `ST_Distance` is called on two geographies, a value in meters is returned (as opposed to degrees if called on a geometry column in WGS84).

地理計算にはより多くの数学が関わるため、地理型に対して使用できる PostGIS 空間ルックアップのサブセットが限られています。具体的には、距離ルックアップ に加えて、ジオグラフィカラム用に利用可能な追加の 空間ルックアップ は以下のみです。

- `bboverlaps`

- `coveredby`

- `covers`

- `intersects`

入力としてジオグラフィ型をサポートしていない空間ルックアップや集計を使用する必要がある場合、 `Cast` データベース関数を使用して、クエリの中でジオグラフィカラムをジオメトリ型に変換できます:

    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
    )

For more information, the PostGIS documentation contains a helpful section on determining when to use geography data type over geometry data type.

脚注

[1]

OpenGIS Consortium, Inc., Simple Feature Specification For SQL.

[2]

See id. at Ch. 2.3.8, p. 39 (Geometry Values and Spatial Reference Systems).

[3]

Typically, SRID integer corresponds to an EPSG (European Petroleum Survey Group) identifier. However, it may also be associated with custom projections defined in spatial database's spatial reference systems table.

[4]

Terry A. Slocum, Robert B. McMaster, Fritz C. Kessler, & Hugh H. Howard, Thematic Cartography and Geographic Visualization (Prentice Hall, 2nd edition), at Ch. 7.1.3.

[5]

この制限は PostGIS には適用されません。

[6]

詳細は PostGIS Geography Type のドキュメントを参照してください。