API GEOS¶

Apa itu GEOS?¶

GEOS kepanjangan untuk Geometry Engine - Open Source, dan adalah sebuah pustaka C++, dihubungkan dari Java Topology Suite. GEOS menerapkan OpenGIS Simple Features for SQL fungsi predikat spasial dan penghubung spasial. GEOS, sekarang sebuah proyek OSGeo, yang aslinya dikembangkan dan dirawat oleh Refractions Research dari Victoria, Canada.

Fitur¶

GeoDjango menerapkan pembungkus Python tingkat-tinggi untuk pustaka GEOS, fitur-fiturnya termasuk:

• Sebuah antarmuka berlisensi-BSD pada rutin geometri GEOS, diterapkan sepenuhnya dalam Python menggunakan ctypes.
• Loosely-coupled to GeoDjango. For example, GEOSGeometry objects may be used outside of a Django project/application. In other words, no need to have DJANGO_SETTINGS_MODULE set or use a database, etc.
• Berubah-ubah: obyek GEOSGeometry mungkin dirubah.
• Lintas-serambi dan teruji; cocok dengan serambi Windows, Linux, Solaris, dan macOS.

Membuat Geometri¶

Obyek GEOSGeometry mungkin dibuat dalam beberapa cara. Pertama cukup menginstansiasi obyek pada beberapa masukan spasial -- berikut adalah contoh dari membuat geometri sama dari WKT, HEX, WKB, dan GeoJSON:

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

Pilihan lain adalah menggunakan pembangun untuk jenis geometri khusus yang anda harap dibuat. Sebagai contoh, obyek Point mungkin dibuat dengan melewatkan dalam kordinat X dan Y kedalam pembangunnya:

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

Semua pembangun ini mengambil argumen kata kunci srid. Sebagai contoh:

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

Akhirnya, ada metode pabrik fromfile() yang mengembalikan obyek GEOSGeometry dari sebuah berkas:

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

Geometri adalah Pythonic¶

Obyek-obyek GEOSGeometry adalah 'Pythonic', dengan kata lain komponen-komponen dapat diakses, dirubah, dan diperulangkan menggunakan kebiasaan Python standar. Sebagai contoh, anda dapat mengulangi kordinat dalam Point:

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

Dengan obyek geometri apapun, sifat GEOSGeometry.coords mungkin digunakan untuk mendapatkan kordinat geometri sebagai sebuah tuple Python:

>>> pnt.coords
(5.0, 23.0)

Anda dapat mendapatkan/menyetel komponen geometri menggunakan teknik-teknik pengindeksan Python standar. bagaimanapun, apa yang dikembalikan bergantung pada jenis geometri dari obyek. Sebagai contoh, pengindeksan pada LineString mengembalikan sebuah kordinat tuple:

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

Dimana pengindeksan pada Polygon akan mengembalikan lingkaran (sebuah obyek LinearRing) berhubungan pada index:

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

Sebagai tambahan, kordinat/komponen dari geometri mungkin ditambahkan atau dirubah, seperti list 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))

Geometri mendukung penghubung set-like:

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

Parameter:	geo_input -- Nilai masukan geometri (string atau buffer) srid (int) -- penciri acuan spasial

Ini adalah kelas dasar untuk semua obyek geometri GEOS. Itu menginisialisasikan pada argumen geo_input yang diberikan, dan kemudian mengganggap subkelas geometri sesuai (misalnya, GEOSGeometry('POINT(1 1)') akan membuat sebuah obyek Point).

Parameter srid, jika diberikan, disetel sebagai SRID dari geometri dibuat jika geo_input tidak memiliki SRID. Jika SRID berbeda disediakan melalui geo_input dan parameter srid, ValueError dimunculkan:

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

Bentuk-bentuk masukan berikut, bersama dengan jenis-jenis Python yang sesuai, adalah diterima:

Untuk bentuk GeoJSON, SRID disetel berdasarkan pada anggota crs. jika crs tidak disediakan, SRID awalan pada 4326.

classmethod GEOSGeometry.from_gml(gml_string)¶

Membangun sebuah GEOSGeometry dari string GML yang diberikan.

Point¶

class Point(x=None, y=None, z=None, srid=None)¶

Obyek point dipakai menggunakan argumen-argumen yang mewakili komponen kordinat dari titik atau dengan kordinat urutan tunggal. Sebagai contoh, berikut adalah setara:

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

Obyek-obyek Point Empty mungkin dipakai dengan melewatkan tidak ada argumen atau urutan kosong. Berikut adalah setara:

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

LineString¶

class LineString(*args, **kwargs)¶

Obyek-obyek LineString dipakai menggunakan argumen-argumen yang baik urutan dari kordinat atau obyek Point. Sebagai contoh, berikut adalah setara:

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

Sebagai tambahahan, obyek LineString mungkin juga dibuat dengan melewatkan dalam urutan tunggal dari kordinat atau obyek Point.

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

Obyek-obyek LineString Empty mungkin dipakai dengan melewatkan tidak ada argumen atau urutan kosong. Berikut adalah setara:

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

closed¶

Mengembalikan apakah atau tidak LineString ini ditutup.

LinearRing¶

class LinearRing(*args, **kwargs)¶

Obyek-obyek LinearRing dibangun dalam cara sama yang tepat seperti obyek-obyek LineString, bagaimanapun kordinat-kordinat harus tertutup, dengan kata lain, kordinat pertama harus sama seperti kordinat terakhir. Sebagai contoh:

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

Perhatikan bahwa (0, 0) adalah kordinat pertama dan terakhir -- jika mereka tidak setara, sebuah kesalahan akan dimunculkan.

is_counterclockwise¶

New in Django 3.1.

Returns whether this LinearRing is counterclockwise.

Polygon¶

class Polygon(*args, **kwargs)¶

Obyek-obyek Polygon mungkin digunakan dengan melewatkan parameter yang mewakili lingkaran dari poligon. Parameters harus berupa salah satu instance LinearRing, atau urutan yang mungkin digunakan untuk membangun sebuah 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)¶

Mengembalikan sebuah obyek poligon dari kotak-dikelilingi diberikan, 4-tuple meliputi (xmin, ymin, xmax, ymax).

num_interior_rings¶

Mengembalikan sejumlah lingkaran interior di geometri ini.

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

MultiPoint¶

class MultiPoint(*args, **kwargs)¶

Obyek-obyek MultiPoint mungkin digunakan dengan melewatkan obyek-obyek Point sebagai argumen, atau urutan tunggal dari obyek-obyek Point:

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

MultiLineString¶

class MultiLineString(*args, **kwargs)¶

Obyek-obyek MultiLineString mungkin digunakan dengan melewatkan dalam obyek-obyek LineString sebagai argumen, atau urutan tunggal dari obyek-obyek LineString:

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

merged¶

Mengembalikan sebuah LineString mewakili baris menggabungkan semua komponen di MultiLineString ini.

closed¶

Returns True if and only if all elements are closed.

MultiPolygon¶

class MultiPolygon(*args, **kwargs)¶

Obyek-obyek MultiPolygon mungkin digunakan dengan melewatkan obyek-obyek Polygon sebagai argumen, atau urutan tunggal dari obyek-obyek Polygon:

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

Obyek-obyek GeometryCollection mungkin digunakan dengan melewatkan GEOSGeometry lain sebagai argumen, atau urutan tunggal dari obyek-obyek GEOSGeometry:

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

Semua metode pada PreparedGeometry mengambil sebuah argumen other, yang harus berupa instance GEOSGeometry.

contains(other)¶

contains_properly(other)¶

covers(other)¶

crosses(other)¶

disjoint(other)¶

intersects(other)¶

overlaps(other)¶

touches(other)¶

within(other)¶

Obyek Pembaca¶

The reader I/O classes return a GEOSGeometry instance from the WKB and/or WKT input given to their read(geom) method.

class WKBReader¶

Contoh:

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

class WKTReader¶

Contoh:

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

Obyek Penulis¶

Semua penulis obyek-obyek memiliki sebuah metode write(geom) yang mengembalikan salah satu WKB atau WKT dari geometri diberikan. Sebagai tambahan, obyek-obyek WKBWriter juga memiliki sifat yang mungkin digunakan untuk merubah urutan byte, dan atau menyertakan nilai SRID (dengan kata lain, EWKB).

class WKBWriter(dim=2)¶

WKBWriter menyediakan kendali kebanyakan terhadap keluarannya. Secara awalan itu mengembalikan WKB sesuai-OGC ketika metode write nya dipanggil. Bagaimanapun, itu mempunyai sifat yang mengizinkan untuk pembuatan dari EWKB, sebuah superset dari standar WKB yang menyertakan informasi tambahan. Lihat dokumentasi WKBWriter.outdim untuk lebih rinci tentang argumen dim.

write(geom)¶

Mengembalikan WKB dari geometri yang diberikan sebagai obyek buffer Python. Contoh:

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

Mengembalikan WKB dari geometri di heksadesimal. Contoh:

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

byteorder¶

Milik ini mungkin disetel untuk merubah urutan-byte dari perwakilan geometri.

Nilai Byteorder	Deskripsi
0	Big Endian (misalnya, cocok dengan sistem RISC)
1	Little Endian (misalnya, cocok dengan sistem x86)

Contoh:

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

Sifat ini mungkin disetel untuk merubah dimensi keluaran dari perwakilan geometri. Dengan kata lain, jika anda memiliki geometri 3D kemudian disetel menjadi 3 sehingga nilai Z disertakan dalam WKB.

Nilai Outdim	Deskripsi
2	Awalan, keluaran 2D WKB.
3	Keluaran 3D WKB.

Contoh:

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

Setel sifat ini dengan sebuah boolean untuk menunjukkan apakah SRID dari geometri harus disertakan dengan perwakilan 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)¶

Kelas ini mengeizinkan pengeluaran perwakilan WKT dari geometri. Lihat atribut WKBWriter.outdim, trim, dan precision untuk rincian tentang argumen pembangun.

write(geom)¶

Mengembalikan WKT dari geometri diberikan. Contoh:

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

Lihat WKBWriter.outdim.

trim¶

Sifat ini digunakan untuk mengadakan atau meniadakan memangkas dari desimal yang tidak diperlukan.

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

Sifat ini mengendalikan ketelitian pembulatan dari kordinat; jika disetel menjadi None pembulatan adalah ditiadakan.

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

Catatan kaki

GEOS_LIBRARY_PATH¶

Sebuah string menentukan tempat dari pustaka C GEOS. Khususnya, pengaturan ini hanya digunakan jika pustaka C GEOS adalah di tempat bukan-standar (misalnya, /home/bob/lib/libgeos_c.so).