什麼是 GEOS？¶

GEOS 代表 Geometry Engine - Open Source (幾何引擎 - 開放原始碼)，是一個 C++ 函式庫，從 Java Topology Suite 移植而來。GEOS 實作了 OpenGIS Simple Features for SQL 空間謂詞函數和空間運算符。GEOS 現在是一個 OSGeo 專案，最初由加拿大維多利亞的 Refractions Research 開發和維護。

特性¶

GeoDjango 實作了 GEOS 函式庫的高階 Python 包裝器，其特性包括：

• 一個以 BSD 授權的 GEOS 幾何常式介面，完全使用 ctypes 在 Python 中實作。

• 與 GeoDjango 鬆散耦合。例如，GEOSGeometry 物件可以在 Django 專案/應用程式之外使用。換句話說，不需要設定 DJANGO_SETTINGS_MODULE 環境變數或使用資料庫等等。

• 可變性：GEOSGeometry 物件可以修改。

• 跨平台且經過測試；與 Windows、Linux、Solaris 和 macOS 平台相容。

建立幾何¶

可以透過幾種方式建立 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

另一種選擇是使用您想要建立的特定幾何類型的建構函式。例如，可以將 X 和 Y 座標傳遞到其建構函式中來建立 Point 物件。

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

最後，還有 fromfile() 工廠方法，該方法會從檔案中傳回 GEOSGeometry 物件。

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

幾何是 Python 式的¶

GEOSGeometry 物件是「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 進行索引會傳回座標元組

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

幾何支援類似集合的運算符

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

>>> from django.contrib.gis.geos import LineString
>>> ls1 = LineString((0, 0), (1, 1))
>>> ls2 = LineString((1, 1), (0, 0))
>>> ls3 = LineString((1, 1), (0, 0), srid=4326)
>>> ls1.equals(ls2)
True
>>> ls1 == ls2
False
>>> ls3 == ls2  # different SRIDs
False

GEOSGeometry¶

class GEOSGeometry(geo_input, srid=None)[原始碼]¶

參數:

• geo_input – 幾何輸入值（字串或 memoryview）

• srid (int) – 空間參考識別符

這是所有 GEOS 幾何物件的基底類別。它使用給定的 geo_input 引數進行初始化，然後假設適當的幾何子類別（例如，GEOSGeometry('POINT(1 1)') 將建立 Point 物件）。

如果 geo_input 沒有 SRID，則 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)¶

從給定的 GML 字串建構 GEOSGeometry。

Point¶

class Point(x=None, y=None, z=None, srid=None)[原始碼]¶

可以使用代表點的組成座標的引數，或使用單一座標序列來例項化 Point 物件。 例如，以下是等效的

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

可以透過不傳遞任何引數或傳遞空序列來例項化空的 Point 物件。 以下是等效的

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

LineString¶

class LineString(*args, **kwargs)[原始碼]¶

LineString 物件可以使用座標序列或 Point 物件的引數來例項化。 例如，以下是等效的

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

此外，也可以透過傳遞單一座標序列或 Point 物件來建立 LineString 物件

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

可以透過不傳遞任何引數或傳遞空序列來例項化空的 LineString 物件。 以下是等效的

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

closed¶

回傳此 LineString 是否已關閉。

LinearRing¶

class LinearRing(*args, **kwargs)[原始碼]¶

LinearRing 物件的建構方式與 LineString 物件完全相同，但是座標必須是封閉的，換句話說，第一個座標必須與最後一個座標相同。 例如

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

請注意，(0, 0) 是第一個和最後一個座標 – 如果它們不相等，則會引發錯誤。

is_counterclockwise[原始碼]¶

回傳此 LinearRing 是否為逆時針方向。

Polygon¶

class Polygon(*args, **kwargs)[原始碼]¶

可以透過傳遞代表多邊形環的參數來例項化 Polygon 物件。 參數必須是 LinearRing 實例，或可用於建構 LinearRing 的序列

>>> 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)[原始碼]¶

從給定的邊界框返回一個多邊形物件，該邊界框是一個包含 (xmin, ymin, xmax, ymax) 的 4 元組。

num_interior_rings[原始碼]¶

返回此幾何圖形中的內部環數量。

>>> if poly_1.area > poly_2.area:
...     pass
...

MultiPoint¶

class MultiPoint(*args, **kwargs)[原始碼]¶

可以透過傳入 Point 物件作為引數，或傳入單個 Point 物件序列來實例化 MultiPoint 物件。

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

MultiLineString¶

class MultiLineString(*args, **kwargs)[原始碼]¶

可以透過傳入 LineString 物件作為引數，或傳入單個 LineString 物件序列來實例化 MultiLineString 物件。

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

merged¶

返回一個 LineString，表示此 MultiLineString 中所有元件的線合併。

closed¶

當且僅當所有元素都是封閉的時，才返回 True。

MultiPolygon¶

class MultiPolygon(*args, **kwargs)[原始碼]¶

可以透過傳入 Polygon 物件作為引數，或傳入單個 Polygon 物件序列來實例化 MultiPolygon 物件。

>>> 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])

GeometryCollection¶

class GeometryCollection(*args, **kwargs)[原始碼]¶

可以透過傳入其他 GEOSGeometry 作為引數，或傳入單個 GEOSGeometry 物件序列來實例化 GeometryCollection 物件。

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

PreparedGeometry¶

class PreparedGeometry¶

PreparedGeometry 上的所有方法都接受一個 other 引數，該引數必須是 GEOSGeometry 實例。

contains(other)¶

contains_properly(other)¶

covers(other)¶

crosses(other)¶

disjoint(other)¶

intersects(other)¶

overlaps(other)¶

touches(other)¶

within(other)¶

讀取器物件¶

讀取器 I/O 類別會從傳遞給其 read(geom) 方法的 WKB 和/或 WKT 輸入中傳回 GEOSGeometry 實例。

class WKBReader[原始碼]¶

範例

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

class WKTReader[原始碼]¶

範例

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

寫入器物件¶

所有寫入器物件都有一個 write(geom) 方法，該方法會傳回給定幾何的 WKB 或 WKT。此外，WKBWriter 物件還具有可用於變更位元組順序和/或包含 SRID 值（換句話說，EWKB）的屬性。

class WKBWriter(dim=2)[原始碼]¶

WKBWriter 提供對其輸出的最大控制。預設情況下，當呼叫其 write 方法時，它會傳回符合 OGC 的 WKB。但是，它具有允許建立 EWKB 的屬性，EWKB 是 WKB 標準的超集合，其中包含其他資訊。有關 dim 引數的更多詳細資訊，請參閱 WKBWriter.outdim 文件。

write(geom)[原始碼]¶

將給定幾何的 WKB 以 Python buffer 物件的形式傳回。範例

>>> 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)[原始碼]¶

以十六進位格式傳回幾何的 WKB。範例

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

byteorder¶

可以設定此屬性來變更幾何表示法的位元組順序。

位元組順序值	描述
0	大端序 (例如，與 RISC 系統相容)
1	小端序 (例如，與 x86 系統相容)

範例

>>> 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'

outdim[原始碼]¶

可以設定此屬性來變更幾何表示法的輸出維度。換句話說，如果您有 3D 幾何，則設定為 3，以便將 Z 值包含在 WKB 中。

Outdim 值	描述
2	預設值，輸出 2D WKB。
3	輸出 3D WKB。

範例

>>> 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'

srid[原始碼]¶

設定此屬性的布林值，以表示是否應將幾何的 SRID 與 WKB 表示法一起包含。範例

>>> 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)[原始碼]¶

此類別允許輸出幾何的 WKT 表示法。有關建構函式引數的詳細資訊，請參閱 WKBWriter.outdim、trim 和 precision 屬性。

write(geom)[原始碼]¶

傳回給定幾何的 WKT。範例

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

outdim[原始碼]¶

請參閱 WKBWriter.outdim。

trim[原始碼]¶

此屬性用於啟用或停用修剪不必要的小數位數。

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

precision[原始碼]¶

此屬性控制座標的捨入精確度；如果設定為 None，則停用捨入。

>>> 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_PATH¶

指定 GEOS C 程式庫位置的字串。通常，只有當 GEOS C 程式庫位於非標準位置時才使用此設定（例如，/home/bob/lib/libgeos_c.so）。