# dokumentasi Django 2.2.9.dev20191202104323

# API GEOS

## Latar belakang

### 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`.
- Hubungan-renggang pada GeoDjango. Sebagai contoh, obyek-obyek `GEOSGeometry` mungkin digunakan diluar dari aplikasi/proyek Django. Dengan kata lain, tidak diperlukan memiliki kumpulan `DJANGO_SETTINGS_MODULE` atau menggunakan basisdata, dll.
- Berubah-ubah: obyek `GEOSGeometry` mungkin dirubah.
- Lintas-serambi dan teruji; cocok dengan serambi Windows, Linux, Solaris, dan macOS.

## Pengajaran tambahan

Bagian ini mengandung perkenalan singkat dan pengajaran tambahan menggunakan obyek `GEOSGeometry`.

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

Catatan-catatan saya dipenuhi dengan kesalahan berhubungan-GEOS

Anda menemukan banyak pengecualian `TypeError` atau `AttributeError` mengisi berkas-berkas catatan peladen Jaringan. Ini umumnya berarti bahwa anda sedang membuar obyek GEOS pada tingkat atas dari beberapa modul Python anda. Kemudian, karena kondisi yang jarang dalam pengumpul sampah, modul anda dikumpulkan sampah sebelum obyek GEOS. Untuk menghindari ini, buat obyek `GEOSGeometry` didalam cakupan lokal dari fungsi/metode anda.

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

Kesetaraan penghubung tidak memeriksa kesetaraam spasial

Kesetaraan penghubung `GEOSGeometry` menggunakan `equals_exact()`, bukan `equals()`, yaitu itu membutuhkan perbandingan geometri untuk memiliki kordinat sama pada tempat sama dengan SRID sama:

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

## Obyek Geometri

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

Bentuk | Jenis Masukan
--- | ---
WKT / EWKT | `str`
HEX / HEXEWKB | `str`
WKB / EWKB | `buffer`
GeoJSON | `str`

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.

#### Sifat-sifat

`GEOSGeometry.``coords`

  Mengembalikan kordinat dari geometri sebagai tuple.

`GEOSGeometry.``dims`

  Mengembalikan dimensi dari geometri:

  - `0` untuk `Point` dan `MultiPoint`
  - `1` untuk `LineString` dan `MultiLineString`
  - `2` untuk `Polygon` dan `MultiPolygon`
  - `-1` untuk `GeometryCollection` kosong
  - dimensi maksimal dari unsur-unsurnya untuk `GeometryCollection` bukan-kosong.

`GEOSGeometry.``empty`

  Mengembalikan apakah atau tidak disetel dari titik-titik dalam geometri adalah kosong.

`GEOSGeometry.``geom_type`

  Mengembalikan string sesuai pada jenis dari geometri. Sebagai contoh:

      >>> pnt = GEOSGeometry('POINT(5 23)')
      >>> pnt.geom_type
      'Point'

`GEOSGeometry.``geom_typeid`

  Mengembalikan angka penciri jenis geometri GEOS. Tabel berikut menunjukkan nilai untuk setipa jenis geometri:

  Geometri | ID
  --- | ---
  `Point` | 0
  `LineString` | 1
  `LinearRing` | 2
  `Polygon` | 3
  `MultiPoint` | 4
  `MultiLineString` | 5
  `MultiPolygon` | 6
  `GeometryCollection` | 7

`GEOSGeometry.``num_coords`

  Mengembalikan angka dari kordinat di geometri.

`GEOSGeometry.``num_geom`

  Mengembalikan sejumlah geometri dalam geometri ini. Dengan kata lain, akan mengembalikan 1 pada apapun kecuali kumpulan geometri.

`GEOSGeometry.``hasz`

  Mengembalikan sebuah boolean menunjukkan apalah geometri adalah tiga-dimensi.

`GEOSGeometry.``ring`

  Mengembalikan sebuah boolean menunjukkan apakah geometri adalah `LinearRing`.

`GEOSGeometry.``simple`

  Mengembalikan sebuah boolean menunjukkan apakah geometri adalah 'simple'. Sebuah geometri adalah sederhana jika dan hanya jika itu tidak menyilang itu sendiri (kecuali pada titik batasan). Sebagai contoh, sebuah obyek `LineString` tidak sederhana jika itu bersilangan itu sendiri. Dengan demikian, obyek `LinearRing` dan `Polygon` selalu sederhana karena mereka tidak dapat melakukan bersilangan mereka sendiri, menurut pengertian.

`GEOSGeometry.``valid`

  Mengembalikan sebuah boolean menunjukkan apakah geometri adalah sah.

`GEOSGeometry.``valid_reason`

  Mengembalikan deretan kalimat menggambarkan alasan mengapa geometri sah.

`GEOSGeometry.``srid`

  Sifat yang mungkin digunakan untuk mengambil atau menyetel SRID berkaitan dengan geometri. Sebagai contoh:

      >>> pnt = Point(5, 23)
      >>> print(pnt.srid)
      None
      >>> pnt.srid = 4326
      >>> pnt.srid
      4326

#### Sifat-sifat Keluaran

Sifat dalam bagian ini mengexpor obyek `GEOSGeometry` menjadi sebuah yang berbeda. Keluaran ini mungkin dalam bentuk string, penyangga, atau bahkan obyek lain.

`GEOSGeometry.``ewkt`

  Mengembalikan "extended" Well-Known Text dari geometri ini. Perwakilan ini khusus untuk PostGIS dan superset dari standar WKT OGC. [1] Pada dasarnya SRID ditambahkan pada perwakilan WKT, sebagai contoh `SRID=4326;POINT(5 23)`.

  Catatan

  Keluaran dari sifat ini tidak menyertakan informasi 3dm, 3dz, dan 4d yang PostGIS dukung dalam perwakilan EWKT nya.

`GEOSGeometry.``hex`

  Mengembalikan WKB dari Geometri dalam bentuk heksadesimal. Harap catat bahwa nilai SRID tidak disertakan dalam perwakilan ini karena itu bukan bagian dari spesifikasi OGC (gunakan sifat `GEOSGeometry.hexewkb` sebagai gantinya).

`GEOSGeometry.``hexewkb`

  Mengembalikan WKB dari Geometri dalam bentuk heksadesimal. Ini adalah sebuah tambahan dari spesifikasi WKB yang menyertakan nilai SRID yang merupakan bagian dari geometri ini.

`GEOSGeometry.``json`

  Mengembalikan perwakilan GeoJSON dari geometri. Catat bahwa ahsiladalah bukan struktur GeoJSON lengkap tetapi hanya isi kunci `geometry` dari struktur GeoJSON. Lihat juga Penserial GeoJSON.

`GEOSGeometry.``geojson`

  Nama lain dari `GEOSGeometry.json`.

`GEOSGeometry.``kml`

  Mengembalikan perwakilan KML (Keyhole Markup Language) dari geometri. Ini jangan hanya digunakan untuk geometri dengan SRID dari 4326 (WGS84), tetapi pembatasan ini tidak dilaksanakan.

`GEOSGeometry.``ogr`

  Mengembalikan obyek `OGRGeometry` terkait pada permintaan pada geometri GEOS.

`GEOSGeometry.``wkb`

  Mengembalikan perwakilan WKB (Well-Known Binary) dari Geometry ini sebagai sebuah penyangga Python. Nilai SRID tidak disertakan, gunakan sifat `GEOSGeometry.ewkb` sebagai gantinya.

`GEOSGeometry.``ewkb`

  Mengembalikan perwakilan EWKB dari Geometry sebagai sebuah penyangga Python. Ini adalah sebuah tambahan dari spesifikasi WKB yang menyertakan nilai SRID apapun yang bagian dari geometri ini.

`GEOSGeometry.``wkt`

  Mengembalikan Well-Known Text dari geometri (sebuah standar OGC).

#### Metode Predikat Spasial

Semua dari metode-metode predikat spasial berikut mengambil contoh `GEOSGeometry` lain (`other`) sebagai sebuah parameter, dan mengembalikan boolean.

`GEOSGeometry.``contains`(other)

  Mengembalikan `True` jika `other.within(this)` mengembalikan `True`.

`GEOSGeometry.``covers`(other)

  Mengembalikan `True` jika geometri mencangkup geometri tertentu.

  Sebutan `covers` mempunyai pengertian kesetaraan berikut:

  - Setiap titik dari geometri lain adalah sebuah titik dari geometri ini.
  - The DE-9IM Intersection Matrix untuk dua geometri adalah `T*****FF*`, `*T****FF*`, `***T**FF*`, atau `****T*FF*`.

  Jika salah satu geometri adalah kosong, kembalikan `False`.

  Prediakt ini mirip pada `GEOSGeometry.contains()`, tetapi lebih termasuk (yaitu mengembalikan `True` untuk kasus-kasus lebih). Khususnya, tidak seperti `contains()` itu tidak membedakan diantara titik-titik dalam batasan dan dalam interior dari geometri. Untuk kebanyakan situasi, `covers()` harus dipilih pada `contains()`. Sebagai sebuah keuntungan tambahan, `covers()` lebih menerima untuk optimalisasi dan karena itu harus mengungguli `contains()`.

`GEOSGeometry.``crosses`(other)

  Mengembalikan `True` jika matriks persimpangan DE-9IM untuk dua geometri adalah `T*T******` (untuk titik dan kurva, titik dan kawasan atau baris dan kawasan) `0********` (untuk dua kurva).

`GEOSGeometry.``disjoint`(other)

  Mengembalikan `True` jika matriks persimpangan DE-9IM untuk dua geometri adalah `FF*FF****`.

`GEOSGeometry.``equals`(other)

  Mengembalikan `True` jika matriks persimpangan DE-9IM untuk dua geometri adalah `T*F**FFF*`.

`GEOSGeometry.``equals_exact`(other, tolerance=0)

  Mengembalikan true jika dua geometri tepatnya setara, sampai toleransi yang ditentukan. Nilai `tolerance` harus berupa angka floating point mewakili toleransi kesalahan dalam perbandingan, misalnya, `poly1.equals_exact(poly2, 0.001)` akan membandingkan kesetaraan dalam ribuan dari sebuah satuan.

`GEOSGeometry.``intersects`(other)

  Mengembalikan `True` jika `GEOSGeometry.disjoint()` adalah `False`.

`GEOSGeometry.``overlaps`(other)

  Mengembalikan `True` jika matriks persimpangan DE-9IM untuk dua geometri adalah `T*T***T**` (untuk titik dan kurva, titik dan kawasan atau baris dan kawasan) `1*T***T**` (untuk dua kurva).

`GEOSGeometry.``relate_pattern`(other, pattern)

  Mengembalikan `True` jika matriks persimpangan DE-9IM untuk geometri ini dah lainnya cocok pada `pattern` yang diberikan -- string dari sembilan karakter dari alfabet: {`T`, `F`, `*`, `0`}.

`GEOSGeometry.``touches`(other)

  Mengembalikan `True` jika matriks persimpangan DE-9IM untuk dua geometri adalah `FT*******`, `F**T*****` or `F***T****`.

`GEOSGeometry.``within`(other)

  Mengembalikan `True` jika matriks persimpangan DE-9IM untuk dua geometri adalah `T*F**F***`.

#### Metode-metode Topologi

`GEOSGeometry.``buffer`(width, quadsegs=8)

  Mengembalikan sebuah `GEOSGeometry` yang mewakili semua titik-titik yang jaraknya dari geometri ini kurang dari atau setara pada `width` yang diberikan. Kata kunci `quadsegs` pilihan mensetel angka dari bagian-bagian digunakan untuk memperkirakan seperempat lingkaran (awalan adalah 8).

`GEOSGeometry.``buffer_with_style`(width, quadsegs=8, end_cap_style=1, join_style=1, mitre_limit=5.0)
  New in Django 2.1.

  Sama seperti `buffer()`, tetapi mengizinkan gaya dari penyangga.

  - `end_cap_style` dapat berupa round (`1`), flat (`2`), atau square (`3`).
  - `join_style` dapat berupa round (`1`), mitre (`2`), atau bevel (`3`).
  - Batas rasio siku (`mitre_limit`) hanya mempengaruhi gaya gabungan sudut.

`GEOSGeometry.``difference`(other)

  Mengembalikan `GEOSGeometry` mewakili titik-titik membuat geometri ini yang tidak membuat lain.

`GEOSGeometry.``interpolate`(distance)

`GEOSGeometry.``interpolate_normalized`(distance)

  Diberikan sebuah jarak (float), mengembalikan titik (atau titik terdekat) dalam geometri (`LineString` atau `MultiLineString`) pada jarak itu. Versi biasa mengambil jarak sebagai sebuah float diantara 0 (asli) dan 1 (titik akhir).

  Membalikkan dari `GEOSGeometry.project()`.

`GEOSGeometry.``intersection`(other)

  Mengembalikan `GEOSGeometry` mewakili titik-titik dibgi oleh geometri ini dan lainnya.

`GEOSGeometry.``project`(point)

`GEOSGeometry.``project_normalized`(point)

  Mengembalikan jarak (float) dari asli geometri (`LineString` atau `MultiLineString`) ke titik diproyeksikan pada geometri (yaitu pada titik dari baris terdekat pada titik yang diberikan). Versi biasa mengembalikan jarak sebagai sebuah float diantara 0 (asli) dan 1 (titik akhir).

  Membalikkan dari `GEOSGeometry.interpolate()`.

`GEOSGeometry.``relate`(other)

  Mengembalikan matriks (string) persimpangan DE-9IM mewakili hubungan topologi diantara geometri ini dan lainnya.

`GEOSGeometry.``simplify`(tolerance=0.0, preserve_topology=False)

  Mengembalikan sebuah `GEOSGeometry` baru, disederhanakan pada toleransi yang ditentukan menggunakan algoritma Douglas-Peucker. Nilai toleransi lebih tinggi mengartikan sedikit titik dalam keluaran. Jika toleransi tidak disediakan, awalan itu pada 0.

  Secara awalan, fungsi ini tidak mempertahankan topologi. Sebagai contoh, obyek-obyek `Polygon` dapat dipisah, dirobohkan menjadi baris-baris, atau hilang. Lubang-lubang `Polygon` dapat dibuat atau hilang, dan baris-baris mungkin bersilangan. Dengan menentukan `preserve_topology=True`, hasil akan mempunyai dimensi sama dan jumlah komponen sebagai masukan; ini secara signifikan lebih lama, bagaimanapun.

`GEOSGeometry.``sym_difference`(other)

  Mengembalikan `GEOSGeometry` menggabungkan titik-titik dalam geometri ini bukan yang lain, dan titik-titik di lainnya bukan dalam geometri ini.

`GEOSGeometry.``union`(other)

  Mengembalikan `GEOSGeometry` mewakili semua titik dalam geometri ini dan lainnya.

#### Sifat-sifat Topologi

`GEOSGeometry.``boundary`

  Mengembalikan batasan sebagai sebuah obyek Geometri baru dialokasikan.

`GEOSGeometry.``centroid`

  Mengembalikan obyek `Point` mewakili pusat geometri dari geometri. Titik tidak menjamin menjadi interior dari geometri.

`GEOSGeometry.``convex_hull`

  Mengembalikan `Polygon` terkecil yang mengandung semua titik dalam geometri.

`GEOSGeometry.``envelope`

  Mengembalikan sebuah `Polygon` yang meakili batasan bungkus dari geometri. Catat bahwa itu dapat juga mengembalikan sebuah `Point` jika masukan geometri adalah sebuah titik.

`GEOSGeometry.``point_on_surface`

  Menghitung dan mengembalikan jaminan `Point` untuk berada dalam interior dari geometri ini.

`GEOSGeometry.``unary_union`

  Menghitung gabungan dari semua unsur dari geometri ini.

  Hasil mematuhi kontrak berikut:

  - Unioning a set of `LineString`s has the effect of fully noding and dissolving the linework.
  - Menyatukan kumpulan dari `Polygon` akan selalu mengembalikan geometri `Polygon` atau `MultiPolygon` (tidak seperti `GEOSGeometry.union()`, yang mungkin mengembalikan geometri dari dimensi terendah jika topologi runtuh timbul).

#### Sifat dan Metode lain

`GEOSGeometry.``area`

  Sifat ini mengembalikan kawasan dari Geometri.

`GEOSGeometry.``extent`

  Sifat ini mengembalikan jangkauan dari geometri ini sebagai 4-tuple, terdiri dari `(xmin, ymin, xmax, ymax)`.

`GEOSGeometry.``clone`()

  Metode ini mengembalikan `GEOSGeometry` yaitu sebuah kloningan dari asli.

`GEOSGeometry.``distance`(geom)

  Mengembalikan jarak diantara titik-titik terdekat pada geometri ini dan `geom` yang diberikan (obyek `GEOSGeometry` lain).

  Catatan

  Perhitungan jarak GEOS adalah segaris -- dengan kata lain, GEOS tidak melakukan perhitungan bola bahkan jika SRID menentukan sistem kordinat geografis.

`GEOSGeometry.``length`

  Mengembalikan panjang dari geometri (misalnya, 0 untuk sebuah `Point`, panjang dari sebuah `LineString`, atau lingkaran dari sebuah `Polygon`).

`GEOSGeometry.``prepared`

  Mengembalikan `PreparedGeometry` GEOS untuk isi dari geometri ini. Obyek-obyek `PreparedGeometry` dioptimalkan untuk mengandung, bersimpangan, menutupi, bersilangan, menguraikan, tumpang tindih, menyentuh dan dalam tindakan-tindakan. Mengacu pada dokumentasi Prepared Geometry untuk informasi lebih.

`GEOSGeometry.``srs`

  Mengembalikan obyek `SpatialReference` yang sesuai pada SRID dari geometri atau `None`.

`GEOSGeometry.``transform`(ct, clone=False)

  Merubah geometri menurut pada parameter perubahan kordinat yang diberikan (`ct`), yang mungkin berupa integer SRID, string WKT acuan spasial, string PROJ.4, obyek `SpatialReference`, atau obyek `CoordTransform`. Secara awalan, geometri dirubah di-tempat dan tidak ada yang dikembalikan. Bagaimanapun, jika kata kunci `clone` disetel, kemudian geometri tidak dirubah dan kloningan berubah dari geometri dikembalikan sebagai gantinya.

  Catatan

  Memunculkan `GEOSException` jika GDAL tidak tersedia atau jika SRID geometri adalah `None` atau kurang dari 0. Itu tidak mengenakan batasan apapun pada SRID geometri jika dipanggil dengan obyek `CoordTransform`.

`GEOSGeometry.``normalize`()

  Merubah geometri ini menjadi bentuk resmi:

      >>> g = MultiPoint(Point(0, 0), Point(2, 2), Point(1, 1))
      >>> print(g)
      MULTIPOINT (0 0, 2 2, 1 1)
      >>> g.normalize()
      >>> print(g)
      MULTIPOINT (2 2, 1 1, 0 0)

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

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

Membandingkan Polygon

Catat bahwa itu memungkinkan membandingkan obyek-obyek `Polygon` langsung dengan `<` atau `>`, tetapi sebagai pembanding dibuat melalui `LineString` Polygon, itu tidak berarti banyak(tetapi tetap dan cepat). Anda dapat selalu memaksa perbandingan dengan sifat `area`:

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

## Kumpulan Geometri

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

    Mengembalikan `True` jika dan hanya jika semua unsur ditutup. Membutuhkan GEOS 3.5.

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

## Prepared Geometry

Untuk mendapatkan geometri yang siap, cukup akses sifat `GEOSGeometry.prepared`. Sekali anda telah `PreparedGeometry` mencontohkan metode prodikat spasialnya, terlampir dibawah, mungkin digunakan dengan obyek-obyek `GEOSGeometry` lain. Sebuah tindakan dengan geometri yang siap dapat mengurutkan ukurannya lebih cepat -- lebih rumit geometri dipersiapkan, lebih besar perpcepatan dalam tindakan. Untuk informasi lebih, harap obrolkan GEOS wiki page on prepared geometries.

Sebagai contoh:

    >>> from django.contrib.gis.geos import Point, Polygon
    >>> poly = Polygon.from_bbox((0, 0, 5, 5))
    >>> prep_poly = poly.prepared
    >>> prep_poly.contains(Point(2.5, 2.5))
    True

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

## Pabrik Geometri

`fromfile`(file_h)

  Parameter: | file_h (a Python `file` object or a string path to the file) -- masukan berkas yang mengandung data spasial
  Jenis Kembalian:
  | `GEOSGeometry` berhubungan ke data spasial dalam berkas

  Contoh:

      >>> from django.contrib.gis.geos import fromfile
      >>> g = fromfile('/home/bob/geom.wkt')

`fromstr`(string, srid=None)

  Parameter: | string (str) -- deretan karakter yang mengandung data spasial srid (int) -- penciri acuan spasial
  Jenis Kembalian:
  | `GEOSGeometry` terkait pada data spasial di deretan karakter

  `fromstr(string, srid)` setara dengan `GEOSGeometry(string, srid)`.

  Contoh:

      >>> from django.contrib.gis.geos import fromstr
      >>> pnt = fromstr('POINT(-90.5 29.5)', srid=4326)

## Obyek I/O

### Obyek Pembaca

Kelas-kelas pembaca I/O cukup mengembalikan contoh `GEOSGeometry` dari masukan WKB dan/atau WKT diberikan pada metode `read(geom)` mereka.

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

[1] | Lihat PostGIS EWKB, EWKT and Canonical Forms, Dokumentasi PostGIS bab 4.1.2.

## Pengaturan

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

Catatan

Pengaturan harus berupa jalur penuh pada pustaka berbagi C; dengan kata lain anda ingin menggunakan `libgeos_c.so`, bukan `libgeos.so`.

## Pengecualian

exception `GEOSException`

  Pengecualian GEOS dasar, menunjukkan kesalahan terkait-GEOS.