# Django 5.0.9.dev20240806133106 ドキュメント

# GeoDjango モデル API

このドキュメントでは GeoDjango Model API の詳細を説明します。この節では、次の ZIP code と Digital Elevation Model の地理情報モデルを例として使います:

    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 の選択

モデルに適切な SRID を選択することは、開発者が慎重に検討すべき重要な決定事項です。SRIDは、空間データベースのデータを解釈するために使用される投影システムに対応する整数指定子です。 [3] 投影システムは、場所を特定する座標にコンテキストを与えます。測地学 geodesy の詳細はこのドキュメントの範囲外ですが、一般的な問題は、地球は球形であり、地球の表現 (紙の地図やウェブマップなど) は球形ではないということです。

ほとんどの人は、緯度と経度を使って地表上の位置を参照することに慣れています。しかし、緯度と経度は距離ではなく角度です。言い換えれば、平面上の2点間の最短経路は直線ですが、(地球のような) 曲面上の2点間の最短経路は、great circle の 弧 です [4] 。したがって、平面単位 (キロメートルやマイルなど) で距離を求めるには、追加の計算が必要になります。地理座標系を使うことは、開発者に後で複雑な問題をもたらすかもしれません。例えば、SpatiaLiteでは、地理座標系を使用してジオメトリ間の距離計算を実行する機能がないため、WGS84で格納された郡の境界から5マイル以内のすべてのポイントを検索するクエリを作成することはできません [5] 。

地球の地表の一部は、二次元またはデカルト平面に投影できます。投影座標系は地域固有のアプリケーションに特に便利であり、たとえば、データベースで North Kansas エリアのジオメトリだけを扱うことを知っている場合は、その地域固有の投影系を使用することを検討できます。さらに、投影座標系はデカルト単位 (メートルやフィートなど) で定義されており、距離の計算が容易になります。

注釈

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

追加のリソース:

- spatialreference.org: Djangoを使用した空間参照システムのデータベース。
- The State Plane Coordinate System: 米国で使用されている様々な投影系をカバーするウェブサイトです。WGS84のような地理座標系ではなく、米国で遭遇する空間データの多くはこれらの座標系のいずれかになります。

### `spatial_index`

`BaseSpatialField.``spatial_index`

デフォルトは `True` です。指定されたジオメトリフィールドに空間インデックスを作成します。

注釈

空間インデックスは通常のデータベースインデックスとは異なる方法で作成されるため、これは `db_index` フィールドオプションとは異なります。具体的には、空間インデックスは通常 R-Tree を使用して作成されますが、通常のデータベースインデックスは B-Tree を使用します。

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

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

### `dim`

`GeometryField.``dim`

このオプションは、ジオメトリフィールドの座標次元をカスタマイズするために使用できます。デフォルトでは、2次元ジオメトリを表すために2に設定されています。それをサポートする空間バックエンドでは、3次元をサポートするために3に設定できます。

注釈

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

### `geography`

`GeometryField.``geography`

このオプションを `True` に設定すると、ジオメトリ型ではなくジオグラフィ型のデータベースカラムが作成されます。詳細は以下の ジオグラフィ型 セクションを参照してください。

注釈

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

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

ジオグラフィ (geography) 型は、地理座標 (例えばWGS84経度/緯度)で表現された空間特徴をネイティブにサポートします [6] 。ジオメトリ型が使用する平面とは異なり、ジオグラフィ型はデータを球体で表現します。ジオグラフィのカラムに対して行われる距離や計測の操作は、自動的に大円弧の計算を行い、線形単位を返します。言い換えると、2つのジオグラフィに対して `ST_Distance` を呼び出すと、メートル単位の値が返されます (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
    )

詳細については、PostGISのドキュメントに ジオメトリ型ではなくジオグラフィ型を使うべき場合. を決定するのに役立つセクションがあります。

脚注

[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] | 通常、SRID 整数は EPSG (European Petroleum Survey Group) 識別子に対応します。しかし、空間データベースの空間参照系テーブルで定義されたカスタム投影に関連付けられている場合もあります。

[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 のドキュメントを参照してください。