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

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

例:

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

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

Measurements

Area

class Area(expression, **extra)[ソース]

利用可能なDB: 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
...

注釈

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

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 上でのみ使用されます。

Changed in Django 5.1:

SpatiaLite 5.1以降のサポートが追加されました。

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

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

Scale

class Scale(expression, x, y, z=0.0, **extra)[ソース]

利用可能なDB: PostGIS, SpatiaLite

単一の地理情報フィールドまたは式を受け取り、それらを xy、任意で 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の原点。

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 の数値パラメータでオフセットしたジオメトリを返します。

入力フォーマット

FromWKB

class FromWKB(expression, srid=0, **extra)[ソース]

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

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

Changed in Django 5.1:

srid 引数が追加されました。

FromWKT

class FromWKT(expression, srid=0, **extra)[ソース]

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

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

Changed in Django 5.1:

srid 引数が追加されました。

出力フォーマット

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)[ソース]

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

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

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

その他

IsEmpty

class IsEmpty(expr)[ソース]

利用可能なDB: PostGIS

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

IsValid

class IsValid(expr)[ソース]

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

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

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