# Django 5.2.8 ドキュメント

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

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

例:

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

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

## 寸法

### `Area`

class Area(expression, **extra)

Availability: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

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

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

### `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
    ...

注釈

Because the `distance` attribute is a `Distance` object, you can easily express the value in the units of your choice. For example, `city.distance.mi` is the distance value in miles and `city.distance.km` is the distance value in kilometers. See 測定オブジェクト for usage details and the list of サポートされる単位.

### `GeometryDistance`

class GeometryDistance(expr1, expr2, **extra)

利用可能なDB: PostGIS

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

### `Length`

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

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

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

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

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

### `Perimeter`

class Perimeter(expression, **extra)

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

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

## リレーション

### `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)

互換性: PostGIS, Oracle, SpatiaLite 5.1以降

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

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

### `Centroid`

class Centroid(expression, **extra)

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

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

### `ClosestPoint`

class ClosestPoint(expr1, expr2, **extra)

利用可能なDB: PostGIS, SpatiaLite

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

### `Envelope`

class Envelope(expression, **extra)

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

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

### `LineLocatePoint`

class LineLocatePoint(linestring, point, **extra)

利用可能なDB: PostGIS, SpatiaLite

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

### `PointOnSurface`

class PointOnSurface(expression, **extra)

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

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

## 操作

### `Difference`

class Difference(expr1, expr2, **extra)

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

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

### `Intersection`

class Intersection(expr1, expr2, **extra)

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

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

### `SymDifference`

class SymDifference(expr1, expr2, **extra)

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

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

### `Union`

class Union(expr1, expr2, **extra)

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

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

## 編集

### `ForcePolygonCW`

class ForcePolygonCW(expression, **extra)

利用可能なDB: PostGIS, SpatiaLite

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

### `MakeValid`

class MakeValid(expr)

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

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

### `Reverse`

class Reverse(expression, **extra)

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

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

### `Rotate`

New in Django 6.0.

class Rotate(expression, angle, origin=None, **extra)

Availability: PostGIS

Rotates a geometry by a specified `angle` around the origin. Optionally, the rotation can be performed around a point, defined by the `origin` parameter.

### `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

Accepts a single geographic field or expression and returns a geometry with all points snapped to the given grid. How the geometry is snapped to the grid depends on how many numeric (either float, integer, or long) arguments are given.

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

### `Transform`

class Transform(expression, srid, **extra)

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

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

注釈

What spatial reference system an integer SRID corresponds to may depend on the spatial database used. In other words, the SRID numbers used for Oracle are not necessarily the same as those used by PostGIS.

### `Translate`

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

利用可能なDB: PostGIS, SpatiaLite

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

## 入力フォーマット

### `FromWKB`

class FromWKB(expression, srid=0, **extra)

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

Well-known binary (WKB) 表現からジオメトリを作成します。オプションの `srid` 引数を使用すると、結果として得られるジオメトリのSRIDを指定できます。`srid` はOracleでは無視されます。

### `FromWKT`

class FromWKT(expression, srid=0, **extra)

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

Well-known text (WKT) 表現からジオメトリを作成します。オプションの `srid` 引数を使用すると、結果として得られるジオメトリのSRIDを指定できます。`srid` はOracleでは無視されます。

## 出力フォーマット

### `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)'

### `GeoHash`

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

Availability: MariaDB, MySQL, PostGIS, SpatiaLite (LWGEOM/RTTOPO)

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

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

Changed in Django 6.0:

MariaDB 12.0.1+ support was added.

## その他

### `IsEmpty`

class IsEmpty(expr)

利用可能なDB: PostGIS

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

### `IsValid`

class IsValid(expr)

Availability: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

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

Changed in Django 6.0:

MariaDB 12.0.1+ support was added.

### `GeometryType`

New in Django 6.0.

class GeometryType(expr)

Availability: PostGIS, Oracle 23c+, MariaDB, MySQL, SpatiaLite

Accepts a geographic field or expression and returns its geometry type.

### `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` を返します。