GEOS APILink to this heading#

GEOS とは？Link to this heading#

GEOS は Geometry Engine - Open Source の略であり、C++ライブラリであり、 Java Topology Suite から移植されました。GEOS は OpenGIS の Simple Features for SQL 空間記述関数や空間演算子を実装しています。GEOS は現在、OSGeo プロジェクトとなっており、もともとはカナダ・ビクトリアの Refractions Research によって開発・維持されていました。

特徴Link to this heading#

GeoDjango は GEOS ライブラリの高レベルな Python ラッパーを実装しており、その機能には次のものがあります:

• ctypes を使用して純粋に Python で実装された GEOS ジオメトリルーチンへの BSD ライセンスのインターフェイス。

• GeoDjango とは疎結合です。たとえば、GEOSGeometry オブジェクトは Django プロジェクト/アプリケーションの外でも使用可能です。つまり、DJANGO_SETTINGS_MODULE を設定したり、データベースを使用する必要はありません。

• ミュータビリティ (Mutability): GEOSGeometry オブジェクトは変更可能です。

• クロスプラットフォームでテストされています。

ジオメトリを作成するLink to this heading#

GEOSGeometry オブジェクトはいくつかの方法で作成できます。最初の方法は、単純に空間入力のオブジェクトをインスタンス化することです。以下は、同じジオメトリを WKT、HEX、WKB、GeoJSON から作成する例です:

>>> from django.contrib.gis.geos import GEOSGeometry
>>> pnt = GEOSGeometry("POINT(5 23)")  # WKT
>>> pnt = GEOSGeometry("010100000000000000000014400000000000003740")  # HEX
>>> pnt = GEOSGeometry(
...     memoryview(
...         b"\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x14@\x00\x00\x00\x00\x00\x007@"
...     )
... )  # WKB
>>> pnt = GEOSGeometry(
...     '{ "type": "Point", "coordinates": [ 5.000000, 23.000000 ] }'
... )  # GeoJSON

もう一つの方法は、作成したい特定のジオメトリタイプのコンストラクタを使用することです。たとえば、Point オブジェクトは、そのコンストラクタに X 座標と Y 座標を渡すことで作成できます:

>>> from django.contrib.gis.geos import Point
>>> pnt = Point(5, 23)

これらのコンストラクタはすべて、キーワード引数 srid を受け取ります。例えば:

>>> from django.contrib.gis.geos import GEOSGeometry, LineString, Point
>>> print(GEOSGeometry("POINT (0 0)", srid=4326))
SRID=4326;POINT (0 0)
>>> print(LineString((0, 0), (1, 1), srid=4326))
SRID=4326;LINESTRING (0 0, 1 1)
>>> print(Point(0, 0, srid=32140))
SRID=32140;POINT (0 0)

最後に、ファイルから GEOSGeometry オブジェクトを返す fromfile() ファクトリーメソッドがあります:

>>> from django.contrib.gis.geos import fromfile
>>> pnt = fromfile("/path/to/pnt.wkt")
>>> pnt = fromfile(open("/path/to/pnt.wkt"))

ジオメトリは Pythonic ですLink to this heading#

GEOSGeometry オブジェクトは 'Pythonic' (Pythonらしい) であり、要素には標準的な Python 形式を使ってアクセスしたり変更したり、イテレートしたりできます。例えば、Point の座標をイテレートできます:

>>> pnt = Point(5, 23)
>>> [coord for coord in pnt]
[5.0, 23.0]

ジオメトリオブジェクトの GEOSGeometry.coords プロパティを使用すると、ジオメトリ座標を Python のタプルで取得できます:

>>> pnt.coords
(5.0, 23.0)

標準の Python インデックス形式を使用して、ジオメトリオブジェクトを取得または設定できます。ただし、返されるものはオブジェクトのジオメトリタイプに依存します。例えば、LineString に対してインデックスを使用すると、座標の Python タプルが返されます:

>>> from django.contrib.gis.geos import LineString
>>> line = LineString((0, 0), (0, 50), (50, 50), (50, 0), (0, 0))
>>> line[0]
(0.0, 0.0)
>>> line[-2]
(50.0, 0.0)

Polygon 上のインデックス指定は、そのインデックスに対応するリング (LinearRing オブジェクト) を返します:

>>> from django.contrib.gis.geos import Polygon
>>> poly = Polygon(((0.0, 0.0), (0.0, 50.0), (50.0, 50.0), (50.0, 0.0), (0.0, 0.0)))
>>> poly[0]
<LinearRing object at 0x1044395b0>
>>> poly[0][-2]  # second-to-last coordinate of external ring
(50.0, 0.0)

さらに、ジオメトリの座標や要素はPythonのリストのように追加や変更が可能です:

>>> line[0] = (1.0, 1.0)
>>> line.pop()
(0.0, 0.0)
>>> line.append((1.0, 1.0))
>>> line.coords
((1.0, 1.0), (0.0, 50.0), (50.0, 50.0), (50.0, 0.0), (1.0, 1.0))

ジオメトリーは set のような演算子をサポートします:

>>> from django.contrib.gis.geos import LineString
>>> ls1 = LineString((0, 0), (2, 2))
>>> ls2 = LineString((1, 1), (3, 3))
>>> print(ls1 | ls2)  # equivalent to `ls1.union(ls2)`
MULTILINESTRING ((0 0, 1 1), (1 1, 2 2), (2 2, 3 3))
>>> print(ls1 & ls2)  # equivalent to `ls1.intersection(ls2)`
LINESTRING (1 1, 2 2)
>>> print(ls1 - ls2)  # equivalent to `ls1.difference(ls2)`
LINESTRING(0 0, 1 1)
>>> print(ls1 ^ ls2)  # equivalent to `ls1.sym_difference(ls2)`
MULTILINESTRING ((0 0, 1 1), (2 2, 3 3))

GEOSGeometryLink to this heading#

class GEOSGeometry(geo_input, srid=None, *, max_geom_collections=198)Link to this definition#

パラメータ:

• geo_input -- ジオメトリ入力値 (文字列または memoryview)

• srid (int) -- 空間参照識別子

• max_geom_collections -- maximum number of nested (WKT) or total (WKB) geometry collections accepted before parsing is refused

これはすべてのGEOSジオメトリオブジェクトの基底クラスです。geo_input 引数で初期化され、適切なジオメトリサブクラスを想定します (たとえば、 GEOSGeometry('POINT(1 1)') は Point オブジェクトを作成します)。

パラメータ srid が与えられた場合、 geo_input が SRID を持っていない場合は、作成されたジオメトリの SRID が設定されます。パラメータ geo_input と srid で異なる SRID が指定された場合、 ValueError が発生します:

>>> from django.contrib.gis.geos import GEOSGeometry
>>> GEOSGeometry("POINT EMPTY", srid=4326).ewkt
'SRID=4326;POINT EMPTY'
>>> GEOSGeometry("SRID=4326;POINT EMPTY", srid=4326).ewkt
'SRID=4326;POINT EMPTY'
>>> GEOSGeometry("SRID=1;POINT EMPTY", srid=4326)
Traceback (most recent call last):
...
ValueError: Input geometry already has SRID: 1.

以下の入力形式とそれに対応するPythonの型を受け付けます:

GeoJSON形式では、SRIDは crs メンバーに基づいて設定されます。もし crs が指定されていない場合、SRIDはデフォルトで4326になります。

classmethod GEOSGeometry.from_gml(gml_string)Link to this definition#

与えられたGML文字列から GEOSGeometry を構築します。

PointLink to this heading#

class Point(x=None, y=None, z=None, srid=None)Link to this definition#

Point オブジェクトは、ポイントの座標を表す引数を使用してインスタンス化されたり、1 つのシーケンス座標でインスタンス化されたりします。例えば、以下は同等です:

Python console

>>> pnt = Point(5, 23)
>>> pnt = Point([5, 23])

空の Point オブジェクトを引数なしまたは空のシーケンスを渡すことでインスタンス化できます。以下は同等です:

Python console

>>> pnt = Point()
>>> pnt = Point([])

LineStringLink to this heading#

class LineString(*args, **kwargs)Link to this definition#

LineString オブジェクトは、座標のシーケンスまたは Point オブジェクトを引数としてインスタンス化されます。例えば、以下は同等です:

Python console

>>> ls = LineString((0, 0), (1, 1))
>>> ls = LineString(Point(0, 0), Point(1, 1))

さらに、LineString オブジェクトは、座標または Point オブジェクトのシーケンスを渡すことによっても作成できます:

Python console

>>> ls = LineString(((0, 0), (1, 1)))
>>> ls = LineString([Point(0, 0), Point(1, 1)])

空の LineString オブジェクトは、引数を渡さないか空のシーケンスを渡すことでインスタンス化できます。以下は同等です:

Python console

>>> ls = LineString()
>>> ls = LineString([])

closedLink to this definition#

この LineString が閉じているかどうかを返します。

LinearRingLink to this heading#

class LinearRing(*args, **kwargs)Link to this definition#

LinearRing オブジェクトは、LineString オブジェクトとまったく同じ方法で構築されますが、座標は 閉じている 必要があります。つまり、最初の座標と最後の座標が同じである必要があります。例:

Python console

>>> ls = LinearRing((0, 0), (0, 1), (1, 1), (0, 0))

(0, 0) は最初で最後の座標です。もし等しくなければ、エラーが発生します。

is_counterclockwiseLink to this definition#

この LinearRing が反時計回りかどうかを返します。

PolygonLink to this heading#

class Polygon(*args, **kwargs)Link to this definition#

Polygon オブジェクトは、多角形のリングを表すパラメータを渡すことでインスタンス化できます。パラメータは、 LinearRing インスタンスであるか、 LinearRing を構築するために使用できるシーケンスである必要があります。

Python console

>>> ext_coords = ((0, 0), (0, 1), (1, 1), (1, 0), (0, 0))
>>> int_coords = ((0.4, 0.4), (0.4, 0.6), (0.6, 0.6), (0.6, 0.4), (0.4, 0.4))
>>> poly = Polygon(ext_coords, int_coords)
>>> poly = Polygon(LinearRing(ext_coords), LinearRing(int_coords))

classmethod from_bbox(bbox)Link to this definition#

与えられたバウンディングボックスからポリゴンオブジェクトを返します。ポリゴンオブジェクトは (xmin, ymin, xmax, ymax) からなる4タプルで構成されます。

num_interior_ringsLink to this definition#

このジオメトリの内部リングの数を返します。

MultiPointLink to this heading#

class MultiPoint(*args, **kwargs)Link to this definition#

MultiPoint オブジェクトは Point オブジェクトを引数として渡すか、1つの Point オブジェクトのシーケンスを渡すことでインスタンス化できます。

Python console

>>> mp = MultiPoint(Point(0, 0), Point(1, 1))
>>> mp = MultiPoint((Point(0, 0), Point(1, 1)))

MultiLineStringLink to this heading#

class MultiLineString(*args, **kwargs)Link to this definition#

MultiLineString オブジェクトは、 LineString オブジェクトを引数として渡すか、1つの LineString オブジェクトのシーケンスを渡すことでインスタンス化が可能です。

Python console

>>> ls1 = LineString((0, 0), (1, 1))
>>> ls2 = LineString((2, 2), (3, 3))
>>> mls = MultiLineString(ls1, ls2)
>>> mls = MultiLineString([ls1, ls2])

mergedLink to this definition#

この MultiLineString のすべてのコンポーネントを結合した線を表す LineString を返します。

closedLink to this definition#

すべての要素が閉じられている場合にのみ True を返します。

MultiPolygonLink to this heading#

class MultiPolygon(*args, **kwargs)Link to this definition#

MultiPolygon オブジェクトは、 Polygon オブジェクトを引数として渡すか、1つの Polygon オブジェクトのシーケンスを渡すことでインスタンス化できます。

Python console

>>> p1 = Polygon(((0, 0), (0, 1), (1, 1), (0, 0)))
>>> p2 = Polygon(((1, 1), (1, 2), (2, 2), (1, 1)))
>>> mp = MultiPolygon(p1, p2)
>>> mp = MultiPolygon([p1, p2])

GeometryCollectionLink to this heading#

class GeometryCollection(*args, **kwargs)Link to this definition#

GeometryCollection オブジェクトは、他の GEOSGeometry オブジェクトを引数として渡すか、または単一の GEOSGeometry オブジェクトのシーケンスを引数として渡すことでインスタンス化できます:

Python console

>>> poly = Polygon(((0, 0), (0, 1), (1, 1), (0, 0)))
>>> gc = GeometryCollection(Point(0, 0), MultiPoint(Point(0, 0), Point(1, 1)), poly)
>>> gc = GeometryCollection((Point(0, 0), MultiPoint(Point(0, 0), Point(1, 1)), poly))

PreparedGeometryLink to this heading#

class PreparedGeometryLink to this definition#

PreparedGeometry のすべてのメソッドは other 引数を取ります。この引数は GEOSGeometry インスタンスでなければなりません。

contains(other)Link to this definition#

contains_properly(other)Link to this definition#

covers(other)Link to this definition#

crosses(other)Link to this definition#

disjoint(other)Link to this definition#

intersects(other)Link to this definition#

overlaps(other)Link to this definition#

touches(other)Link to this definition#

within(other)Link to this definition#

Reader オブジェクトLink to this heading#

Reader I/Oクラスは、 read(geom) メソッドに渡されたWKBおよび/またはWKT入力から GEOSGeometry インスタンスを返します。

class WKBReaderLink to this definition#

例:

Python console

>>> from django.contrib.gis.geos import WKBReader
>>> wkb_r = WKBReader()
>>> wkb_r.read("0101000000000000000000F03F000000000000F03F")
<Point object at 0x103a88910>

class WKTReaderLink to this definition#

例:

Python console

>>> from django.contrib.gis.geos import WKTReader
>>> wkt_r = WKTReader()
>>> wkt_r.read("POINT(1 1)")
<Point object at 0x103a88b50>

Writer オブジェクトLink to this heading#

すべての Writer オブジェクトは write(geom) メソッドを持っており、与えられたジオメトリの WKB または WKT を返します。さらに、WKBWriter オブジェクトは、バイトオーダーを変更したり、SRID 値 (言い換えれば、EWKB) を含めるために使用できるプロパティも持っています。

class WKBWriter(dim=2)Link to this definition#

WKBWriter はその出力を最もコントロールできます。デフォルトでは、 write メソッドが呼ばれると OGC 準拠の WKB を返します。ただし、追加情報を含むWKB標準のスーパーセットであるEWKBを作成できるプロパティも持っています。引数 dim の詳細については WKBWriter.outdim のドキュメントを参照してください。

write(geom)Link to this definition#

与えられたジオメトリの WKB を Python の buffer オブジェクトとして返します。例:

Python console

>>> from django.contrib.gis.geos import Point, WKBWriter
>>> pnt = Point(1, 1)
>>> wkb_w = WKBWriter()
>>> wkb_w.write(pnt)
<read-only buffer for 0x103a898f0, size -1, offset 0 at 0x103a89930>

write_hex(geom)Link to this definition#

ジオメトリのWKBを16進数で返します。例:

Python console

>>> from django.contrib.gis.geos import Point, WKBWriter
>>> pnt = Point(1, 1)
>>> wkb_w = WKBWriter()
>>> wkb_w.write_hex(pnt)
'0101000000000000000000F03F000000000000F03F'

byteorderLink to this definition#

このプロパティを設定すると、ジオメトリ表現のバイトオーダーを変更できます。

バイトオーダーの値	説明
0	ビッグエンディアン (例: RISC システムと互換性あり)
1	リトルエンディアン (例: x86 システムと互換性あり)

例:

Python console

>>> from django.contrib.gis.geos import Point, WKBWriter
>>> wkb_w = WKBWriter()
>>> pnt = Point(1, 1)
>>> wkb_w.write_hex(pnt)
'0101000000000000000000F03F000000000000F03F'
>>> wkb_w.byteorder = 0
'00000000013FF00000000000003FF0000000000000'

outdimLink to this definition#

このプロパティは、ジオメトリ表現の出力次元を変更するために設定できます。つまり、3D ジオメトリの場合は 3 に設定し、Z 値が WKB に含まれるようにします。

Outdim 値	説明
2	デフォルトで、2次元のWKBを出力します。
3	3D の WKB を出力します。

例:

Python console

>>> from django.contrib.gis.geos import Point, WKBWriter
>>> wkb_w = WKBWriter()
>>> wkb_w.outdim
2
>>> pnt = Point(1, 1, 1)
>>> wkb_w.write_hex(pnt)  # By default, no Z value included:
'0101000000000000000000F03F000000000000F03F'
>>> wkb_w.outdim = 3  # Tell writer to include Z values
>>> wkb_w.write_hex(pnt)
'0101000080000000000000F03F000000000000F03F000000000000F03F'

sridLink to this definition#

このプロパティに真偽値を設定して、ジオメトリのSRIDがWKB表現に含まれるかどうかを示します。例:

Python console

>>> from django.contrib.gis.geos import Point, WKBWriter
>>> wkb_w = WKBWriter()
>>> pnt = Point(1, 1, srid=4326)
>>> wkb_w.write_hex(pnt)  # By default, no SRID included:
'0101000000000000000000F03F000000000000F03F'
>>> wkb_w.srid = True  # Tell writer to include SRID
>>> wkb_w.write_hex(pnt)
'0101000020E6100000000000000000F03F000000000000F03F'

class WKTWriter(dim=2, trim=False, precision=None)Link to this definition#

このクラスを使用すると、ジオメトリの WKT 表現を出力できます。コンストラクタの引数の詳細については WKBWriter.outdim, trim, precision 属性を参照してください。

write(geom)Link to this definition#

与えられたジオメトリのWKTを返します。例:

Python console

>>> from django.contrib.gis.geos import Point, WKTWriter
>>> pnt = Point(1, 1)
>>> wkt_w = WKTWriter()
>>> wkt_w.write(pnt)
'POINT (1.0000000000000000 1.0000000000000000)'

outdimLink to this definition#

WKBWriter.outdim を参照。

trimLink to this definition#

このプロパティは、不要な小数のトリミングを有効または無効にするために使用されます。

Python console

>>> from django.contrib.gis.geos import Point, WKTWriter
>>> pnt = Point(1, 1)
>>> wkt_w = WKTWriter()
>>> wkt_w.trim
False
>>> wkt_w.write(pnt)
'POINT (1.0000000000000000 1.0000000000000000)'
>>> wkt_w.trim = True
>>> wkt_w.write(pnt)
'POINT (1 1)'

precisionLink to this definition#

このプロパティは座標の丸め精度をコントロールします。もし None に設定すると丸めは無効になります。

Code

>>> from django.contrib.gis.geos import Point, WKTWriter
>>> pnt = Point(1.44, 1.66)
>>> wkt_w = WKTWriter()
>>> print(wkt_w.precision)
None
>>> wkt_w.write(pnt)
'POINT (1.4399999999999999 1.6599999999999999)'
>>> wkt_w.precision = 0
>>> wkt_w.write(pnt)
'POINT (1 2)'
>>> wkt_w.precision = 1
>>> wkt_w.write(pnt)
'POINT (1.4 1.7)'

脚注

GEOS_LIBRARY_PATHLink to this heading#

GEOS Cライブラリの場所を指定する文字列。通常、この設定は GEOS C ライブラリが標準以外の場所にある場合にのみ使用されます (/home/bob/lib/libgeos_c.so など)。