# Django 5.0.9.dev20240806133106 ドキュメント

# 地理情報データベース関数

このページで説明する関数を使えば、Django のアノテーションや集約、フィルタで使う地理情報データベース関数にアクセスできます。

例:

    >>> from django.contrib.gis.db.models.functions import Length
    >>> Track.objects.annotate(length=Length("line")).filter(length__gt=100)

すべてのバックエンドがすべての関数をサポートしているわけではないので、それぞれの関数のドキュメントを参照して、使用したい関数をサポートしているかどうかを確認してください。サポートしていないバックエンドで地理情報関数を呼び出すと、 `NotImplementedError` 例外が発生します。

関数の概要:

測定 | リレーション | 操作 | 編集 | 入力フォーマット | 出力フォーマット | その他
--- | --- | --- | --- | --- | --- | ---
`Area` | `Azimuth` | `Difference` | `ForcePolygonCW` |  | `AsGeoJSON` | `IsEmpty`
`Distance` | `BoundingCircle` | `Intersection` | `MakeValid` |  | `AsGML` | `IsValid`
`GeometryDistance` | `Centroid` | `SymDifference` | `Reverse` |  | `AsKML` | `MemSize`
`Length` | `ClosestPoint` | `Union` | `Scale` |  | `AsSVG` | `NumGeometries`
`Perimeter` | `Envelope` `LineLocatePoint` `PointOnSurface` |  | `SnapToGrid` `Transform` `Translate` | `FromWKB` `FromWKT` | `AsWKB` `AsWKT` `GeoHash` | `NumPoints`

## `Area`

class `Area`(expression, **extra)

利用可能なDB: MariaDB、MySQL、Oracle、PostGIS、SpatiaLite

単一の地理情報フィールドまたは式を受け取り、そのフィールドの面積を `Area` 測定値として返します。

LWGEOM/RTTOPOを使用しないMySQLとSpatiaLiteは、地理SRSの面積計算をサポートしていません。

## `AsGeoJSON`

class `AsGeoJSON`(expression, bbox=False, crs=False, precision=8, **extra)

利用可能なDB: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

単一の地理情報フィールドまたは式を受け取り、地理情報の GeoJSON 表現を返す。結果は完全な GeoJSON 構造体ではなく、GeoJSON 構造体のキーコンテンツ `geometry` だけであることに注意してください。 GeoJSON シリアライザ も参照。

例:

    >>> City.objects.annotate(json=AsGeoJSON("point")).get(name="Chicago").json
    {"type":"Point","coordinates":[-87.65018,41.85039]}

キーワード引数 | 説明
--- | ---
`bbox` | 返される GeoJSON にバウンディングボックスを含めたい場合は、これを `True` に設定します。Oracle では無視される。
`crs` | 返される GeoJSON に座標参照系を含めたい場合は、これを `True` に設定してください。MySQLとOracleでは無視されます。
`precision` | GeoJSON 表現での座標の有効数字の桁数を指定します。デフォルト値は8です。Oracleでは無視されます。

## `AsGML`

class `AsGML`(expression, version=2, precision=8, **extra)

利用可能なDB: Oracle, PostGIS, SpatiaLite

単一の地理情報フィールドまたは式を受け取り、そのジオメトリの Geographic Markup Language (GML) 表現を返します。

例:

    >>> qs = Zipcode.objects.annotate(gml=AsGML("poly"))
    >>> print(qs[0].gml)
    <gml:Polygon srsName="EPSG:4326"><gml:OuterBoundaryIs>-147.78711,70.245363 ...
    -147.78711,70.245363</gml:OuterBoundaryIs></gml:Polygon>

キーワード引数 | 説明
--- | ---
`precision` | GML 表現における座標の有効桁数を指定します (デフォルト値は 8)。Oracle では無視されます。
`version` | 使用するGMLバージョンを指定します: 2 (デフォルト) または 3。

## `AsKML`

class `AsKML`(expression, precision=8, **extra)

利用可能なDB: PostGIS、SpatiaLite

単一の地理情報フィールドまたは式を受け取り、地理情報の Keyhole Markup Language (KML) 表現を返す。

例:

    >>> qs = Zipcode.objects.annotate(kml=AsKML("poly"))
    >>> print(qs[0].kml)
    <Polygon><outerBoundaryIs><LinearRing><coordinates>-103.04135,36.217596,0 ...
    -103.04135,36.217596,0</coordinates></LinearRing></outerBoundaryIs></Polygon>

キーワード引数 | 説明
--- | ---
`precision` | このキーワードは、KML表現で座標の有効桁数を指定するために使用できます。デフォルト値は8です。

## `AsSVG`

class `AsSVG`(expression, relative=False, precision=8, **extra)

利用可能なDB: PostGIS, SpatiaLite

単一の地理情報フィールドまたは式を受け取り、そのジオメトリの Scalable Vector Graphics (SVG) 表現を返します。

キーワード引数 | 説明
--- | ---
`relative` | `True` に設定すると、経路データは相対移動として実装されます。デフォルトは `False` で、代わりに絶対移動が使用されます。
`precision` | このキーワードは、SVG 表現内の座標の有効桁数を指定するために使用できます。デフォルト値は 8 です。

## `AsWKB`

class `AsWKB`(expression, **extra)

利用可能なDB: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

単一の地理情報フィールドまたは式を受け取り、そのジオメトリの Well-known binary (WKB) 表現を返します。

例:

    >>> bytes(City.objects.annotate(wkb=AsWKB("point")).get(name="Chelyabinsk").wkb)
    b'\x01\x01\x00\x00\x00]3\xf9f\x9b\x91K@\x00X\x1d9\xd2\xb9N@'

## `AsWKT`

class `AsWKT`(expression, **extra)

利用可能なDB: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

単一の地理情報フィールドまたは式を受け取り、ジオメトリの Well-known text (WKT) 表現を返します。

例:

    >>> City.objects.annotate(wkt=AsWKT("point")).get(name="Chelyabinsk").wkt
    'POINT (55.137555 61.451728)'

## `Azimuth`

class `Azimuth`(point_a, point_b, **extra)

利用可能なDB: PostGIS, SpatiaLite (LWGEOM/RTTOPO)

与えられた点のジオメトリで定義されるセグメントの方位をラジアンで返します。2つの点が重なっている場合は `None` を返します。方位は北を基準とした角度で、時計回りが正です: 北 = `0`; 東 = `π/2`; 南 = `π`; 西 = `3π/2` 。

## `BoundingCircle`

class `BoundingCircle`(expression, num_seg=48, **extra)

利用可能なDB: PostGIS, Oracle

単一の地理情報フィールドまたは式を受け取り、そのジオメトリを完全に含むことができる最小の円ポリゴンを返します。

`num_seg` パラメータは PostGIS 上でのみ使用されます。

## `Centroid`

class `Centroid`(expression, **extra)

利用可能なDB: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

単一の地理情報フィールドまたは式を受け取り、ジオメトリの `centroid` 値を返す。

## `ClosestPoint`

New in Django 5.0.

class `ClosestPoint`(expr1, expr2, **extra)

利用可能なDB: PostGIS, SpatiaLite

2つの地理情報フィールドまたは式を受け取り、地理情報 A 上で地理情報 B に最も近い 2次元ポイントを返します。

## `Difference`

class `Difference`(expr1, expr2, **extra)

利用可能なDB: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

2つの地理情報フィールドまたは式を受け取り、幾何学的な差、つまり地理情報Aのうち地理情報Bと重ならない部分を返す。

## `Distance`

class `Distance`(expr1, expr2, spheroid=None, **extra)

利用可能なDB: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

2つの地理情報フィールドまたは式を受け取り、それらの間の距離を `Distance` オブジェクトとして返します。MySQL では、座標が測地系の場合、生の float 値が返されます。

測地座標での距離計算をサポートするバックエンドでは、ジオメトリの SRID 値に応じて適切なバックエンド関数が自動的に選択されます (例: PostGIS の ST_DistanceSphere)。

デフォルトのWGS84 (4326) SRIDのように測地 (角度) 座標で距離を計算する場合、 `spheroid` キーワード引数を設定することで、単純な球体 (精度が低く、リソースをあまり必要としない) か球体 (精度が高く、リソースを多く必要とする) のどちらに基づいて計算するかを決めることができます。

以下の例では、Hobart 市から `AustraliaCity` クエリセット内の他の `PointField` までの距離を計算しています:

    >>> from django.contrib.gis.db.models.functions import Distance
    >>> pnt = AustraliaCity.objects.get(name="Hobart").point
    >>> for city in AustraliaCity.objects.annotate(distance=Distance("point", pnt)):
    ...     print(city.name, city.distance)
    ...
    Wollongong 990071.220408 m
    Shellharbour 972804.613941 m
    Thirroul 1002334.36351 m
    ...

注釈

`distance` 属性は `Distance` オブジェクトなので、簡単に任意の単位で値を表現できます。例えば、 `city.distance.mi` はマイル単位の距離値であり、 `city.distance.km` はキロメートル単位の距離値です。使用方法の詳細や サポートされる単位 のリストについては、 測定オブジェクト を参照してください。

## `Envelope`

class `Envelope`(expression, **extra)

利用可能なDB: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

1つの地理情報フィールドまたは式を受け取り、ジオメトリのバウンディングボックスを表すジオメトリを返します。

## `ForcePolygonCW`

class `ForcePolygonCW`(expression, **extra)

利用可能なDB: PostGIS, SpatiaLite

1つの地理情報フィールドまたは式を受け取り、すべての外側のリングが時計回り、すべての内側のリングが反時計回りであるポリゴン/マルチポリゴンの修正版を返します。多角形以外のジオメトリは変更されずに返されます。

## `FromWKB`

New in Django 4.2.

class `FromWKB`(expression, **extra)

利用可能なDB: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Well-known binary (WKB) 表現からジオメトリを作成します。

## `FromWKT`

New in Django 4.2.

class `FromWKT`(expression, **extra)

利用可能なDB: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Well-known text (WKT) 表現からジオメトリを作成します。

## `GeoHash`

class `GeoHash`(expression, precision=None, **extra)

利用可能なDB: MySQL, PostGIS, SpatiaLite (LWGEOM/RTTOPO)

単一の地理情報フィールドまたは式を受け取り、ジオメトリの GeoHash 表現を返します。

キーワード引数 `precision` は結果の文字数をコントロールします。

## `GeometryDistance`

class `GeometryDistance`(expr1, expr2, **extra)

利用可能なDB: PostGIS

2つの地理情報フィールドまたは式を受け取り、それらの間の距離を返します。 `order_by()` 節で使用すると、インデックスアシストされた最近傍の結果セットを提供します。

## `Intersection`

class `Intersection`(expr1, expr2, **extra)

利用可能なDB: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

2 つの地理情報フィールドや式を受け取り、それらの間の幾何学的な交点を返します。

## `IsEmpty`

New in Django 4.2.

class `IsEmpty`(expr)

利用可能なDB: PostGIS

地理情報フィールドまたは式を受け取り、その値が空のジオメトリであるかどうかをテストします。値が空の場合は `True` を返し、そうでない場合は `False` を返します。

## `IsValid`

class `IsValid`(expr)

利用可能なDB: MySQL, PostGIS, Oracle, SpatiaLite

地理情報フィールドまたは式を受け取り、その値が整形されているかどうかをテストします。値が有効なジオメトリであれば `True` を返し、そうでなければ `False` を返します。

## `Length`

class `Length`(expression, spheroid=True, **extra)

利用可能なDB: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

単一の地理的な linestring または multilinestring フィールドまたは式を受け取り、その長さを `Distance` メジャーとして返します。

PostGISとSpatiaLiteでは、座標が測地系 (角度) である場合、単純な球 (精度が低く、リソースの消費量が少ない) か、球体 (精度が高く、リソースの消費量が多い) かを `spheroid` キーワード引数で指定できます。

MySQLは地理空間SRSにおける長さの計算をサポートしていません。

## `LineLocatePoint`

class `LineLocatePoint`(linestring, point, **extra)

利用可能なDB: PostGIS, SpatiaLite

与えられた `point` に最も近い `linestring` 上の点の位置を 0 から 1 までの float で表し、2D 線の長さに対する割合で返す。

## `MakeValid`

class `MakeValid`(expr)

利用可能なDB: PostGIS, SpatiaLite (LWGEOM/RTTOPO)

地理情報フィールドまたは式を受け取り、入力頂点を失うことなくその値を有効なジオメトリに変換しようとします。すでに有効なジオメトリは変更されずに返されます。単純なポリゴンはマルチポリゴンになる可能性があり、結果は入力よりも低次元になる可能性があります。

## `MemSize`

class `MemSize`(expression, **extra)

利用可能なDB: PostGIS

1つの地理情報フィールドまたは式を受け取り、その地理情報フィールドが必要とするメモリサイズ (バイト数) を返します。

## `NumGeometries`

class `NumGeometries`(expression, **extra)

利用可能なDB: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

単一の地理情報フィールドまたは式を受け取り、地理情報フィールドがコレクション (たとえば `GEOMETRYCOLLECTION` または `MULTI*` フィールド) の場合は、ジオメトリ数を返します。単一のジオメトリの場合は 1 を返します。

MySQL では、単一のジオメトリに対して `None` を返します。

## `NumPoints`

class `NumPoints`(expression, **extra)

利用可能なDB: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

単一の地理情報フィールドまたは式を受け取り、ジオメトリ内のポイント数を返します。

MySQL では、`LINESTRING` でないジオメトリに対しては `None` を返します。

## `Perimeter`

class `Perimeter`(expression, **extra)

利用可能なDB: PostGIS, Oracle, SpatiaLite

単一の地理情報フィールドまたは式を受け取り、ジオメトリフィールドの周長を `Distance` オブジェクトとして返します。

## `PointOnSurface`

class `PointOnSurface`(expression, **extra)

利用可能なDB: PostGIS, MariaDB, Oracle, SpatiaLite

単一の地理情報フィールドまたは式を受け入れ、そのフィールドの表面上にあることが保証された `Point` ジオメトリを返します。そのような値がない場合は `None` を返します。

## `Reverse`

class `Reverse`(expression, **extra)

利用可能なDB: PostGIS, Oracle, SpatiaLite

単一の地理情報フィールドまたは式を受け取り、座標を反転したジオメトリを返します。

## `Scale`

class `Scale`(expression, x, y, z=0.0, **extra)

利用可能なDB: PostGIS, SpatiaLite

単一の地理情報フィールドまたは式を受け取り、それらを `x`、`y`、任意で `z` パラメータで乗算してスケーリングした座標を持つジオメトリを返します。

## `SnapToGrid`

class `SnapToGrid`(expression, *args, **extra)

利用可能なDB: PostGIS, SpatiaLite

1 つの地理情報フィールドまたは式を受け取り、すべての点が指定されたグリッドにスナップされたジオメトリを返します。ジオメトリがグリッドにスナップされる方法は、与えられた数値 (float、integer、long のいずれか) の数によって異なります。

引数の数 | 説明
--- | ---
1 | XグリッドとYグリッドの両方をスナップする単一のサイズ。
2 | グリッドをスナップさせるXとYのサイズ。
4 | X、Yのサイズと、対応するX、Yの原点。

## `SymDifference`

class `SymDifference`(expr1, expr2, **extra)

利用可能なDB: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

2つの地理情報フィールドまたは式を受け取り、与えられたパラメータ間の幾何学的対称差 (交差を除いた和) を返します。

## `Transform`

class `Transform`(expression, srid, **extra)

利用可能なDB: PostGIS, Oracle, SpatiaLite

地理情報フィールドまたは式と SRID 整数コードを受け取り、`srid` パラメータで指定された空間参照系に変換されたジオメトリを返します。

注釈

整数のSRIDがどの空間参照系に対応するかは、使用する空間データベースによって異なります。つまり、Oracleで使用されるSRID番号は、必ずしもPostGISで使用されるSRID番号と同じではありません。

## `Translate`

class `Translate`(expression, x, y, z=0.0, **extra)

利用可能なDB: PostGIS, SpatiaLite

単一の地理情報フィールドまたは式を受け取り、その座標を `x`, `y`, オプションで `z` の数値パラメータでオフセットしたジオメトリを返します。

## `Union`

class `Union`(expr1, expr2, **extra)

利用可能なDB: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

2 つの地理情報フィールドまたは式を受け取り、それらの両方のジオメトリの和集合を返します。