| 1 |
======== |
| 2 |
GEOS API |
| 3 |
======== |
| 4 |
|
| 5 |
.. module:: django.contrib.gis.geos |
| 6 |
:synopsis: GeoDjango's high-level interface to the GEOS library. |
| 7 |
|
| 8 |
Background |
| 9 |
========== |
| 10 |
|
| 11 |
What is GEOS? |
| 12 |
------------- |
| 13 |
|
| 14 |
`GEOS`__ stands for **Geometry Engine - Open Source**, |
| 15 |
and is a C++ library, ported from the `Java Topology Suite`__. GEOS |
| 16 |
implements the OpenGIS `Simple Features for SQL`__ spatial predicate functions |
| 17 |
and spatial operators. GEOS, now an OSGeo project, was initially developed and |
| 18 |
maintained by `Refractions Research`__ of Victoria, Canada. |
| 19 |
|
| 20 |
__ https://libgeos.org/ |
| 21 |
__ https://sourceforge.net/projects/jts-topo-suite/ |
| 22 |
__ https://www.ogc.org/standard/sfs/ |
| 23 |
__ http://www.refractions.net/ |
| 24 |
|
| 25 |
Features |
| 26 |
-------- |
| 27 |
|
| 28 |
GeoDjango implements a high-level Python wrapper for the GEOS library, its |
| 29 |
features include: |
| 30 |
|
| 31 |
* A BSD-licensed interface to the GEOS geometry routines, implemented purely |
| 32 |
in Python using ``ctypes``. |
| 33 |
* Loosely-coupled to GeoDjango. For example, :class:`GEOSGeometry` objects |
| 34 |
may be used outside of a Django project/application. In other words, |
| 35 |
no need to have :envvar:`DJANGO_SETTINGS_MODULE` set or use a database, etc. |
| 36 |
* Mutability: :class:`GEOSGeometry` objects may be modified. |
| 37 |
* Cross-platform tested. |
| 38 |
|
| 39 |
.. _geos-tutorial: |
| 40 |
|
| 41 |
Tutorial |
| 42 |
======== |
| 43 |
|
| 44 |
This section contains a brief introduction and tutorial to using |
| 45 |
:class:`GEOSGeometry` objects. |
| 46 |
|
| 47 |
Creating a Geometry |
| 48 |
------------------- |
| 49 |
|
| 50 |
:class:`GEOSGeometry` objects may be created in a few ways. The first is |
| 51 |
to simply instantiate the object on some spatial input -- the following |
| 52 |
are examples of creating the same geometry from WKT, HEX, WKB, and GeoJSON: |
| 53 |
|
| 54 |
.. code-block:: pycon |
| 55 |
|
| 56 |
>>> from django.contrib.gis.geos import GEOSGeometry |
| 57 |
>>> pnt = GEOSGeometry("POINT(5 23)") # WKT |
| 58 |
>>> pnt = GEOSGeometry("010100000000000000000014400000000000003740") # HEX |
| 59 |
>>> pnt = GEOSGeometry( |
| 60 |
... memoryview( |
| 61 |
... b"\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x14@\x00\x00\x00\x00\x00\x007@" |
| 62 |
... ) |
| 63 |
... ) # WKB |
| 64 |
>>> pnt = GEOSGeometry( |
| 65 |
... '{ "type": "Point", "coordinates": [ 5.000000, 23.000000 ] }' |
| 66 |
... ) # GeoJSON |
| 67 |
|
| 68 |
Another option is to use the constructor for the specific geometry type |
| 69 |
that you wish to create. For example, a :class:`Point` object may be |
| 70 |
created by passing in the X and Y coordinates into its constructor: |
| 71 |
|
| 72 |
.. code-block:: pycon |
| 73 |
|
| 74 |
>>> from django.contrib.gis.geos import Point |
| 75 |
>>> pnt = Point(5, 23) |
| 76 |
|
| 77 |
All these constructors take the keyword argument ``srid``. For example: |
| 78 |
|
| 79 |
.. code-block:: pycon |
| 80 |
|
| 81 |
>>> from django.contrib.gis.geos import GEOSGeometry, LineString, Point |
| 82 |
>>> print(GEOSGeometry("POINT (0 0)", srid=4326)) |
| 83 |
SRID=4326;POINT (0 0) |
| 84 |
>>> print(LineString((0, 0), (1, 1), srid=4326)) |
| 85 |
SRID=4326;LINESTRING (0 0, 1 1) |
| 86 |
>>> print(Point(0, 0, srid=32140)) |
| 87 |
SRID=32140;POINT (0 0) |
| 88 |
|
| 89 |
Finally, there is the :func:`fromfile` factory method which returns a |
| 90 |
:class:`GEOSGeometry` object from a file: |
| 91 |
|
| 92 |
.. code-block:: pycon |
| 93 |
|
| 94 |
>>> from django.contrib.gis.geos import fromfile |
| 95 |
>>> pnt = fromfile("/path/to/pnt.wkt") |
| 96 |
>>> pnt = fromfile(open("/path/to/pnt.wkt")) |
| 97 |
|
| 98 |
.. _geos-exceptions-in-logfile: |
| 99 |
|
| 100 |
.. admonition:: My logs are filled with GEOS-related errors |
| 101 |
|
| 102 |
You find many ``TypeError`` or ``AttributeError`` exceptions filling your |
| 103 |
web server's log files. This generally means that you are creating GEOS |
| 104 |
objects at the top level of some of your Python modules. Then, due to a race |
| 105 |
condition in the garbage collector, your module is garbage collected before |
| 106 |
the GEOS object. To prevent this, create :class:`GEOSGeometry` objects |
| 107 |
inside the local scope of your functions/methods. |
| 108 |
|
| 109 |
Geometries are Pythonic |
| 110 |
----------------------- |
| 111 |
:class:`GEOSGeometry` objects are 'Pythonic', in other words components may |
| 112 |
be accessed, modified, and iterated over using standard Python conventions. |
| 113 |
For example, you can iterate over the coordinates in a :class:`Point`: |
| 114 |
|
| 115 |
.. code-block:: pycon |
| 116 |
|
| 117 |
>>> pnt = Point(5, 23) |
| 118 |
>>> [coord for coord in pnt] |
| 119 |
[5.0, 23.0] |
| 120 |
|
| 121 |
With any geometry object, the :attr:`GEOSGeometry.coords` property |
| 122 |
may be used to get the geometry coordinates as a Python tuple: |
| 123 |
|
| 124 |
.. code-block:: pycon |
| 125 |
|
| 126 |
>>> pnt.coords |
| 127 |
(5.0, 23.0) |
| 128 |
|
| 129 |
You can get/set geometry components using standard Python indexing |
| 130 |
techniques. However, what is returned depends on the geometry type |
| 131 |
of the object. For example, indexing on a :class:`LineString` |
| 132 |
returns a coordinate tuple: |
| 133 |
|
| 134 |
.. code-block:: pycon |
| 135 |
|
| 136 |
>>> from django.contrib.gis.geos import LineString |
| 137 |
>>> line = LineString((0, 0), (0, 50), (50, 50), (50, 0), (0, 0)) |
| 138 |
>>> line[0] |
| 139 |
(0.0, 0.0) |
| 140 |
>>> line[-2] |
| 141 |
(50.0, 0.0) |
| 142 |
|
| 143 |
Whereas indexing on a :class:`Polygon` will return the ring |
| 144 |
(a :class:`LinearRing` object) corresponding to the index: |
| 145 |
|
| 146 |
.. code-block:: pycon |
| 147 |
|
| 148 |
>>> from django.contrib.gis.geos import Polygon |
| 149 |
>>> poly = Polygon(((0.0, 0.0), (0.0, 50.0), (50.0, 50.0), (50.0, 0.0), (0.0, 0.0))) |
| 150 |
>>> poly[0] |
| 151 |
<LinearRing object at 0x1044395b0> |
| 152 |
>>> poly[0][-2] # second-to-last coordinate of external ring |
| 153 |
(50.0, 0.0) |
| 154 |
|
| 155 |
In addition, coordinates/components of the geometry may added or modified, |
| 156 |
just like a Python list: |
| 157 |
|
| 158 |
.. code-block:: pycon |
| 159 |
|
| 160 |
>>> line[0] = (1.0, 1.0) |
| 161 |
>>> line.pop() |
| 162 |
(0.0, 0.0) |
| 163 |
>>> line.append((1.0, 1.0)) |
| 164 |
>>> line.coords |
| 165 |
((1.0, 1.0), (0.0, 50.0), (50.0, 50.0), (50.0, 0.0), (1.0, 1.0)) |
| 166 |
|
| 167 |
Geometries support set-like operators: |
| 168 |
|
| 169 |
.. code-block:: pycon |
| 170 |
|
| 171 |
>>> from django.contrib.gis.geos import LineString |
| 172 |
>>> ls1 = LineString((0, 0), (2, 2)) |
| 173 |
>>> ls2 = LineString((1, 1), (3, 3)) |
| 174 |
>>> print(ls1 | ls2) # equivalent to `ls1.union(ls2)` |
| 175 |
MULTILINESTRING ((0 0, 1 1), (1 1, 2 2), (2 2, 3 3)) |
| 176 |
>>> print(ls1 & ls2) # equivalent to `ls1.intersection(ls2)` |
| 177 |
LINESTRING (1 1, 2 2) |
| 178 |
>>> print(ls1 - ls2) # equivalent to `ls1.difference(ls2)` |
| 179 |
LINESTRING(0 0, 1 1) |
| 180 |
>>> print(ls1 ^ ls2) # equivalent to `ls1.sym_difference(ls2)` |
| 181 |
MULTILINESTRING ((0 0, 1 1), (2 2, 3 3)) |
| 182 |
|
| 183 |
.. admonition:: Equality operator doesn't check spatial equality |
| 184 |
|
| 185 |
The :class:`~GEOSGeometry` equality operator uses |
| 186 |
:meth:`~GEOSGeometry.equals_exact`, not :meth:`~GEOSGeometry.equals`, i.e. |
| 187 |
it requires the compared geometries to have the same coordinates in the |
| 188 |
same positions with the same SRIDs: |
| 189 |
|
| 190 |
.. code-block:: pycon |
| 191 |
|
| 192 |
>>> from django.contrib.gis.geos import LineString |
| 193 |
>>> ls1 = LineString((0, 0), (1, 1)) |
| 194 |
>>> ls2 = LineString((1, 1), (0, 0)) |
| 195 |
>>> ls3 = LineString((1, 1), (0, 0), srid=4326) |
| 196 |
>>> ls1.equals(ls2) |
| 197 |
True |
| 198 |
>>> ls1 == ls2 |
| 199 |
False |
| 200 |
>>> ls3 == ls2 # different SRIDs |
| 201 |
False |
| 202 |
|
| 203 |
Geometry Objects |
| 204 |
================ |
| 205 |
|
| 206 |
``GEOSGeometry`` |
| 207 |
---------------- |
| 208 |
|
| 209 |
.. class:: GEOSGeometry(geo_input, srid=None) |
| 210 |
|
| 211 |
:param geo_input: Geometry input value (string or :class:`memoryview`) |
| 212 |
:param srid: spatial reference identifier |
| 213 |
:type srid: int |
| 214 |
|
| 215 |
This is the base class for all GEOS geometry objects. It initializes on the |
| 216 |
given ``geo_input`` argument, and then assumes the proper geometry subclass |
| 217 |
(e.g., ``GEOSGeometry('POINT(1 1)')`` will create a :class:`Point` object). |
| 218 |
|
| 219 |
The ``srid`` parameter, if given, is set as the SRID of the created geometry if |
| 220 |
``geo_input`` doesn't have an SRID. If different SRIDs are provided through the |
| 221 |
``geo_input`` and ``srid`` parameters, ``ValueError`` is raised: |
| 222 |
|
| 223 |
.. code-block:: pycon |
| 224 |
|
| 225 |
>>> from django.contrib.gis.geos import GEOSGeometry |
| 226 |
>>> GEOSGeometry("POINT EMPTY", srid=4326).ewkt |
| 227 |
'SRID=4326;POINT EMPTY' |
| 228 |
>>> GEOSGeometry("SRID=4326;POINT EMPTY", srid=4326).ewkt |
| 229 |
'SRID=4326;POINT EMPTY' |
| 230 |
>>> GEOSGeometry("SRID=1;POINT EMPTY", srid=4326) |
| 231 |
Traceback (most recent call last): |
| 232 |
... |
| 233 |
ValueError: Input geometry already has SRID: 1. |
| 234 |
|
| 235 |
The following input formats, along with their corresponding Python types, |
| 236 |
are accepted: |
| 237 |
|
| 238 |
======================= ============== |
| 239 |
Format Input Type |
| 240 |
======================= ============== |
| 241 |
WKT / EWKT ``str`` |
| 242 |
HEX / HEXEWKB ``str`` |
| 243 |
WKB / EWKB ``memoryview`` |
| 244 |
:rfc:`GeoJSON <7946>` ``str`` |
| 245 |
======================= ============== |
| 246 |
|
| 247 |
For the GeoJSON format, the SRID is set based on the ``crs`` member. If ``crs`` |
| 248 |
isn't provided, the SRID defaults to 4326. |
| 249 |
|
| 250 |
.. classmethod:: GEOSGeometry.from_gml(gml_string) |
| 251 |
|
| 252 |
Constructs a :class:`GEOSGeometry` from the given GML string. |
| 253 |
|
| 254 |
Properties |
| 255 |
~~~~~~~~~~ |
| 256 |
|
| 257 |
.. attribute:: GEOSGeometry.coords |
| 258 |
|
| 259 |
Returns the coordinates of the geometry as a tuple. |
| 260 |
|
| 261 |
.. attribute:: GEOSGeometry.dims |
| 262 |
|
| 263 |
Returns the dimension of the geometry: |
| 264 |
|
| 265 |
* ``0`` for :class:`Point`\s and :class:`MultiPoint`\s |
| 266 |
* ``1`` for :class:`LineString`\s and :class:`MultiLineString`\s |
| 267 |
* ``2`` for :class:`Polygon`\s and :class:`MultiPolygon`\s |
| 268 |
* ``-1`` for empty :class:`GeometryCollection`\s |
| 269 |
* the maximum dimension of its elements for non-empty |
| 270 |
:class:`GeometryCollection`\s |
| 271 |
|
| 272 |
.. attribute:: GEOSGeometry.empty |
| 273 |
|
| 274 |
Returns whether or not the set of points in the geometry is empty. |
| 275 |
|
| 276 |
.. attribute:: GEOSGeometry.geom_type |
| 277 |
|
| 278 |
Returns a string corresponding to the type of geometry. For example: |
| 279 |
|
| 280 |
.. code-block:: pycon |
| 281 |
|
| 282 |
>>> pnt = GEOSGeometry("POINT(5 23)") |
| 283 |
>>> pnt.geom_type |
| 284 |
'Point' |
| 285 |
|
| 286 |
.. attribute:: GEOSGeometry.geom_typeid |
| 287 |
|
| 288 |
Returns the GEOS geometry type identification number. The following table |
| 289 |
shows the value for each geometry type: |
| 290 |
|
| 291 |
=========================== ======== |
| 292 |
Geometry ID |
| 293 |
=========================== ======== |
| 294 |
:class:`Point` 0 |
| 295 |
:class:`LineString` 1 |
| 296 |
:class:`LinearRing` 2 |
| 297 |
:class:`Polygon` 3 |
| 298 |
:class:`MultiPoint` 4 |
| 299 |
:class:`MultiLineString` 5 |
| 300 |
:class:`MultiPolygon` 6 |
| 301 |
:class:`GeometryCollection` 7 |
| 302 |
=========================== ======== |
| 303 |
|
| 304 |
.. attribute:: GEOSGeometry.num_coords |
| 305 |
|
| 306 |
Returns the number of coordinates in the geometry. |
| 307 |
|
| 308 |
.. attribute:: GEOSGeometry.num_geom |
| 309 |
|
| 310 |
Returns the number of geometries in this geometry. In other words, will |
| 311 |
return 1 on anything but geometry collections. |
| 312 |
|
| 313 |
.. attribute:: GEOSGeometry.hasz |
| 314 |
|
| 315 |
Returns a boolean indicating whether the geometry is three-dimensional. |
| 316 |
|
| 317 |
.. attribute:: GEOSGeometry.ring |
| 318 |
|
| 319 |
Returns a boolean indicating whether the geometry is a ``LinearRing``. |
| 320 |
|
| 321 |
.. attribute:: GEOSGeometry.simple |
| 322 |
|
| 323 |
Returns a boolean indicating whether the geometry is 'simple'. A geometry |
| 324 |
is simple if and only if it does not intersect itself (except at boundary |
| 325 |
points). For example, a :class:`LineString` object is not simple if it |
| 326 |
intersects itself. Thus, :class:`LinearRing` and :class:`Polygon` objects |
| 327 |
are always simple because they cannot intersect themselves, by definition. |
| 328 |
|
| 329 |
.. attribute:: GEOSGeometry.valid |
| 330 |
|
| 331 |
Returns a boolean indicating whether the geometry is valid. |
| 332 |
|
| 333 |
.. attribute:: GEOSGeometry.valid_reason |
| 334 |
|
| 335 |
Returns a string describing the reason why a geometry is invalid. |
| 336 |
|
| 337 |
.. attribute:: GEOSGeometry.srid |
| 338 |
|
| 339 |
Property that may be used to retrieve or set the SRID associated with the |
| 340 |
geometry. For example: |
| 341 |
|
| 342 |
.. code-block:: pycon |
| 343 |
|
| 344 |
>>> pnt = Point(5, 23) |
| 345 |
>>> print(pnt.srid) |
| 346 |
None |
| 347 |
>>> pnt.srid = 4326 |
| 348 |
>>> pnt.srid |
| 349 |
4326 |
| 350 |
|
| 351 |
Output Properties |
| 352 |
~~~~~~~~~~~~~~~~~ |
| 353 |
|
| 354 |
The properties in this section export the :class:`GEOSGeometry` object into |
| 355 |
a different. This output may be in the form of a string, buffer, or even |
| 356 |
another object. |
| 357 |
|
| 358 |
.. attribute:: GEOSGeometry.ewkt |
| 359 |
|
| 360 |
Returns the "extended" Well-Known Text of the geometry. This representation |
| 361 |
is specific to PostGIS and is a superset of the OGC WKT standard. [#fnogc]_ |
| 362 |
Essentially the SRID is prepended to the WKT representation, for example |
| 363 |
``SRID=4326;POINT(5 23)``. |
| 364 |
|
| 365 |
.. note:: |
| 366 |
|
| 367 |
The output from this property does not include the 3dm, 3dz, and 4d |
| 368 |
information that PostGIS supports in its EWKT representations. |
| 369 |
|
| 370 |
.. attribute:: GEOSGeometry.hex |
| 371 |
|
| 372 |
Returns the WKB of this Geometry in hexadecimal form. Please note |
| 373 |
that the SRID value is not included in this representation |
| 374 |
because it is not a part of the OGC specification (use the |
| 375 |
:attr:`GEOSGeometry.hexewkb` property instead). |
| 376 |
|
| 377 |
.. attribute:: GEOSGeometry.hexewkb |
| 378 |
|
| 379 |
Returns the EWKB of this Geometry in hexadecimal form. This is an |
| 380 |
extension of the WKB specification that includes the SRID value |
| 381 |
that are a part of this geometry. |
| 382 |
|
| 383 |
.. attribute:: GEOSGeometry.json |
| 384 |
|
| 385 |
Returns the GeoJSON representation of the geometry. Note that the result is |
| 386 |
not a complete GeoJSON structure but only the ``geometry`` key content of a |
| 387 |
GeoJSON structure. See also :doc:`/ref/contrib/gis/serializers`. |
| 388 |
|
| 389 |
.. attribute:: GEOSGeometry.geojson |
| 390 |
|
| 391 |
Alias for :attr:`GEOSGeometry.json`. |
| 392 |
|
| 393 |
.. attribute:: GEOSGeometry.kml |
| 394 |
|
| 395 |
Returns a `KML`__ (Keyhole Markup Language) representation of the |
| 396 |
geometry. This should only be used for geometries with an SRID of |
| 397 |
4326 (WGS84), but this restriction is not enforced. |
| 398 |
|
| 399 |
.. attribute:: GEOSGeometry.ogr |
| 400 |
|
| 401 |
Returns an :class:`~django.contrib.gis.gdal.OGRGeometry` object |
| 402 |
corresponding to the GEOS geometry. |
| 403 |
|
| 404 |
.. _wkb: |
| 405 |
|
| 406 |
.. attribute:: GEOSGeometry.wkb |
| 407 |
|
| 408 |
Returns the WKB (Well-Known Binary) representation of this Geometry |
| 409 |
as a Python buffer. SRID value is not included, use the |
| 410 |
:attr:`GEOSGeometry.ewkb` property instead. |
| 411 |
|
| 412 |
.. _ewkb: |
| 413 |
|
| 414 |
.. attribute:: GEOSGeometry.ewkb |
| 415 |
|
| 416 |
Return the EWKB representation of this Geometry as a Python buffer. |
| 417 |
This is an extension of the WKB specification that includes any SRID |
| 418 |
value that are a part of this geometry. |
| 419 |
|
| 420 |
.. attribute:: GEOSGeometry.wkt |
| 421 |
|
| 422 |
Returns the Well-Known Text of the geometry (an OGC standard). |
| 423 |
|
| 424 |
__ https://developers.google.com/kml/documentation/ |
| 425 |
|
| 426 |
Spatial Predicate Methods |
| 427 |
~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 428 |
|
| 429 |
All of the following spatial predicate methods take another |
| 430 |
:class:`GEOSGeometry` instance (``other``) as a parameter, and |
| 431 |
return a boolean. |
| 432 |
|
| 433 |
.. method:: GEOSGeometry.contains(other) |
| 434 |
|
| 435 |
Returns ``True`` if :meth:`other.within(this) <GEOSGeometry.within>` returns |
| 436 |
``True``. |
| 437 |
|
| 438 |
.. method:: GEOSGeometry.covers(other) |
| 439 |
|
| 440 |
Returns ``True`` if this geometry covers the specified geometry. |
| 441 |
|
| 442 |
The ``covers`` predicate has the following equivalent definitions: |
| 443 |
|
| 444 |
* Every point of the other geometry is a point of this geometry. |
| 445 |
* The `DE-9IM`_ Intersection Matrix for the two geometries is |
| 446 |
``T*****FF*``, ``*T****FF*``, ``***T**FF*``, or ``****T*FF*``. |
| 447 |
|
| 448 |
If either geometry is empty, returns ``False``. |
| 449 |
|
| 450 |
This predicate is similar to :meth:`GEOSGeometry.contains`, but is more |
| 451 |
inclusive (i.e. returns ``True`` for more cases). In particular, unlike |
| 452 |
:meth:`~GEOSGeometry.contains` it does not distinguish between points in the |
| 453 |
boundary and in the interior of geometries. For most situations, |
| 454 |
``covers()`` should be preferred to :meth:`~GEOSGeometry.contains`. As an |
| 455 |
added benefit, ``covers()`` is more amenable to optimization and hence |
| 456 |
should outperform :meth:`~GEOSGeometry.contains`. |
| 457 |
|
| 458 |
.. _DE-9IM: https://en.wikipedia.org/wiki/DE-9IM |
| 459 |
|
| 460 |
.. method:: GEOSGeometry.crosses(other) |
| 461 |
|
| 462 |
Returns ``True`` if the DE-9IM intersection matrix for the two Geometries |
| 463 |
is ``T*T******`` (for a point and a curve,a point and an area or a line |
| 464 |
and an area) ``0********`` (for two curves). |
| 465 |
|
| 466 |
.. method:: GEOSGeometry.disjoint(other) |
| 467 |
|
| 468 |
Returns ``True`` if the DE-9IM intersection matrix for the two geometries |
| 469 |
is ``FF*FF****``. |
| 470 |
|
| 471 |
.. method:: GEOSGeometry.equals(other) |
| 472 |
|
| 473 |
Returns ``True`` if the DE-9IM intersection matrix for the two geometries |
| 474 |
is ``T*F**FFF*``. |
| 475 |
|
| 476 |
.. method:: GEOSGeometry.equals_exact(other, tolerance=0) |
| 477 |
|
| 478 |
Returns true if the two geometries are exactly equal, up to a |
| 479 |
specified tolerance. The ``tolerance`` value should be a floating |
| 480 |
point number representing the error tolerance in the comparison, e.g., |
| 481 |
``poly1.equals_exact(poly2, 0.001)`` will compare equality to within |
| 482 |
one thousandth of a unit. |
| 483 |
|
| 484 |
.. method:: GEOSGeometry.equals_identical(other) |
| 485 |
|
| 486 |
Returns ``True`` if the two geometries are point-wise equivalent by |
| 487 |
checking that the structure, ordering, and values of all vertices are |
| 488 |
identical in all dimensions. ``NaN`` values are considered to be equal to |
| 489 |
other ``NaN`` values. Requires GEOS 3.12. |
| 490 |
|
| 491 |
.. method:: GEOSGeometry.intersects(other) |
| 492 |
|
| 493 |
Returns ``True`` if :meth:`GEOSGeometry.disjoint` is ``False``. |
| 494 |
|
| 495 |
.. method:: GEOSGeometry.overlaps(other) |
| 496 |
|
| 497 |
Returns true if the DE-9IM intersection matrix for the two geometries |
| 498 |
is ``T*T***T**`` (for two points or two surfaces) ``1*T***T**`` |
| 499 |
(for two curves). |
| 500 |
|
| 501 |
.. method:: GEOSGeometry.relate_pattern(other, pattern) |
| 502 |
|
| 503 |
Returns ``True`` if the elements in the DE-9IM intersection matrix |
| 504 |
for this geometry and the other matches the given ``pattern`` -- |
| 505 |
a string of nine characters from the alphabet: {``T``, ``F``, ``*``, ``0``}. |
| 506 |
|
| 507 |
.. method:: GEOSGeometry.touches(other) |
| 508 |
|
| 509 |
Returns ``True`` if the DE-9IM intersection matrix for the two geometries |
| 510 |
is ``FT*******``, ``F**T*****`` or ``F***T****``. |
| 511 |
|
| 512 |
.. method:: GEOSGeometry.within(other) |
| 513 |
|
| 514 |
Returns ``True`` if the DE-9IM intersection matrix for the two geometries |
| 515 |
is ``T*F**F***``. |
| 516 |
|
| 517 |
Topological Methods |
| 518 |
~~~~~~~~~~~~~~~~~~~ |
| 519 |
|
| 520 |
.. method:: GEOSGeometry.buffer(width, quadsegs=8) |
| 521 |
|
| 522 |
Returns a :class:`GEOSGeometry` that represents all points whose distance |
| 523 |
from this geometry is less than or equal to the given ``width``. The |
| 524 |
optional ``quadsegs`` keyword sets the number of segments used to |
| 525 |
approximate a quarter circle (defaults is 8). |
| 526 |
|
| 527 |
.. method:: GEOSGeometry.buffer_with_style(width, quadsegs=8, end_cap_style=1, join_style=1, mitre_limit=5.0) |
| 528 |
|
| 529 |
Same as :meth:`buffer`, but allows customizing the style of the buffer. |
| 530 |
|
| 531 |
* ``end_cap_style`` can be round (``1``), flat (``2``), or square (``3``). |
| 532 |
* ``join_style`` can be round (``1``), mitre (``2``), or bevel (``3``). |
| 533 |
* Mitre ratio limit (``mitre_limit``) only affects mitered join style. |
| 534 |
|
| 535 |
.. method:: GEOSGeometry.difference(other) |
| 536 |
|
| 537 |
Returns a :class:`GEOSGeometry` representing the points making up this |
| 538 |
geometry that do not make up other. |
| 539 |
|
| 540 |
.. method:: GEOSGeometry.interpolate(distance) |
| 541 |
.. method:: GEOSGeometry.interpolate_normalized(distance) |
| 542 |
|
| 543 |
Given a distance (float), returns the point (or closest point) within the |
| 544 |
geometry (:class:`LineString` or :class:`MultiLineString`) at that distance. |
| 545 |
The normalized version takes the distance as a float between 0 (origin) and |
| 546 |
1 (endpoint). |
| 547 |
|
| 548 |
Reverse of :meth:`GEOSGeometry.project`. |
| 549 |
|
| 550 |
.. method:: GEOSGeometry.intersection(other) |
| 551 |
|
| 552 |
Returns a :class:`GEOSGeometry` representing the points shared by this |
| 553 |
geometry and other. |
| 554 |
|
| 555 |
.. method:: GEOSGeometry.project(point) |
| 556 |
.. method:: GEOSGeometry.project_normalized(point) |
| 557 |
|
| 558 |
Returns the distance (float) from the origin of the geometry |
| 559 |
(:class:`LineString` or :class:`MultiLineString`) to the point projected on |
| 560 |
the geometry (that is to a point of the line the closest to the given |
| 561 |
point). The normalized version returns the distance as a float between 0 |
| 562 |
(origin) and 1 (endpoint). |
| 563 |
|
| 564 |
Reverse of :meth:`GEOSGeometry.interpolate`. |
| 565 |
|
| 566 |
.. method:: GEOSGeometry.relate(other) |
| 567 |
|
| 568 |
Returns the DE-9IM intersection matrix (a string) representing the |
| 569 |
topological relationship between this geometry and the other. |
| 570 |
|
| 571 |
.. method:: GEOSGeometry.simplify(tolerance=0.0, preserve_topology=False) |
| 572 |
|
| 573 |
Returns a new :class:`GEOSGeometry`, simplified to the specified tolerance |
| 574 |
using the Douglas-Peucker algorithm. A higher tolerance value implies |
| 575 |
fewer points in the output. If no tolerance is provided, it defaults to 0. |
| 576 |
|
| 577 |
By default, this function does not preserve topology. For example, |
| 578 |
:class:`Polygon` objects can be split, be collapsed into lines, or |
| 579 |
disappear. :class:`Polygon` holes can be created or disappear, and lines may |
| 580 |
cross. By specifying ``preserve_topology=True``, the result will have the |
| 581 |
same dimension and number of components as the input; this is significantly |
| 582 |
slower, however. |
| 583 |
|
| 584 |
.. method:: GEOSGeometry.sym_difference(other) |
| 585 |
|
| 586 |
Returns a :class:`GEOSGeometry` combining the points in this geometry |
| 587 |
not in other, and the points in other not in this geometry. |
| 588 |
|
| 589 |
.. method:: GEOSGeometry.union(other) |
| 590 |
|
| 591 |
Returns a :class:`GEOSGeometry` representing all the points in this |
| 592 |
geometry and the other. |
| 593 |
|
| 594 |
Topological Properties |
| 595 |
~~~~~~~~~~~~~~~~~~~~~~ |
| 596 |
|
| 597 |
.. attribute:: GEOSGeometry.boundary |
| 598 |
|
| 599 |
Returns the boundary as a newly allocated Geometry object. |
| 600 |
|
| 601 |
.. attribute:: GEOSGeometry.centroid |
| 602 |
|
| 603 |
Returns a :class:`Point` object representing the geometric center of |
| 604 |
the geometry. The point is not guaranteed to be on the interior |
| 605 |
of the geometry. |
| 606 |
|
| 607 |
.. attribute:: GEOSGeometry.convex_hull |
| 608 |
|
| 609 |
Returns the smallest :class:`Polygon` that contains all the points in |
| 610 |
the geometry. |
| 611 |
|
| 612 |
.. attribute:: GEOSGeometry.envelope |
| 613 |
|
| 614 |
Returns a :class:`Polygon` that represents the bounding envelope of |
| 615 |
this geometry. Note that it can also return a :class:`Point` if the input |
| 616 |
geometry is a point. |
| 617 |
|
| 618 |
.. attribute:: GEOSGeometry.point_on_surface |
| 619 |
|
| 620 |
Computes and returns a :class:`Point` guaranteed to be on the interior |
| 621 |
of this geometry. |
| 622 |
|
| 623 |
.. attribute:: GEOSGeometry.unary_union |
| 624 |
|
| 625 |
Computes the union of all the elements of this geometry. |
| 626 |
|
| 627 |
The result obeys the following contract: |
| 628 |
|
| 629 |
* Unioning a set of :class:`LineString`\s has the effect of fully noding and |
| 630 |
dissolving the linework. |
| 631 |
|
| 632 |
* Unioning a set of :class:`Polygon`\s will always return a :class:`Polygon` |
| 633 |
or :class:`MultiPolygon` geometry (unlike :meth:`GEOSGeometry.union`, |
| 634 |
which may return geometries of lower dimension if a topology collapse |
| 635 |
occurs). |
| 636 |
|
| 637 |
Other Properties & Methods |
| 638 |
~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 639 |
|
| 640 |
.. attribute:: GEOSGeometry.area |
| 641 |
|
| 642 |
This property returns the area of the Geometry. |
| 643 |
|
| 644 |
.. attribute:: GEOSGeometry.extent |
| 645 |
|
| 646 |
This property returns the extent of this geometry as a 4-tuple, |
| 647 |
consisting of ``(xmin, ymin, xmax, ymax)``. |
| 648 |
|
| 649 |
.. method:: GEOSGeometry.clone() |
| 650 |
|
| 651 |
This method returns a :class:`GEOSGeometry` that is a clone of the original. |
| 652 |
|
| 653 |
.. method:: GEOSGeometry.distance(geom) |
| 654 |
|
| 655 |
Returns the distance between the closest points on this geometry and the |
| 656 |
given ``geom`` (another :class:`GEOSGeometry` object). |
| 657 |
|
| 658 |
.. note:: |
| 659 |
|
| 660 |
GEOS distance calculations are linear -- in other words, GEOS does not |
| 661 |
perform a spherical calculation even if the SRID specifies a geographic |
| 662 |
coordinate system. |
| 663 |
|
| 664 |
.. attribute:: GEOSGeometry.length |
| 665 |
|
| 666 |
Returns the length of this geometry (e.g., 0 for a :class:`Point`, |
| 667 |
the length of a :class:`LineString`, or the circumference of |
| 668 |
a :class:`Polygon`). |
| 669 |
|
| 670 |
.. attribute:: GEOSGeometry.prepared |
| 671 |
|
| 672 |
Returns a GEOS ``PreparedGeometry`` for the contents of this geometry. |
| 673 |
``PreparedGeometry`` objects are optimized for the contains, intersects, |
| 674 |
covers, crosses, disjoint, overlaps, touches and within operations. Refer to |
| 675 |
the :ref:`prepared-geometries` documentation for more information. |
| 676 |
|
| 677 |
.. attribute:: GEOSGeometry.srs |
| 678 |
|
| 679 |
Returns a :class:`~django.contrib.gis.gdal.SpatialReference` object |
| 680 |
corresponding to the SRID of the geometry or ``None``. |
| 681 |
|
| 682 |
.. method:: GEOSGeometry.transform(ct, clone=False) |
| 683 |
|
| 684 |
Transforms the geometry according to the given coordinate transformation |
| 685 |
parameter (``ct``), which may be an integer SRID, spatial reference WKT |
| 686 |
string, a PROJ string, a :class:`~django.contrib.gis.gdal.SpatialReference` |
| 687 |
object, or a :class:`~django.contrib.gis.gdal.CoordTransform` object. By |
| 688 |
default, the geometry is transformed in-place and nothing is returned. |
| 689 |
However if the ``clone`` keyword is set, then the geometry is not modified |
| 690 |
and a transformed clone of the geometry is returned instead. |
| 691 |
|
| 692 |
.. note:: |
| 693 |
|
| 694 |
Raises :class:`~django.contrib.gis.geos.GEOSException` if GDAL is not |
| 695 |
available or if the geometry's SRID is ``None`` or less than 0. It |
| 696 |
doesn't impose any constraints on the geometry's SRID if called with a |
| 697 |
:class:`~django.contrib.gis.gdal.CoordTransform` object. |
| 698 |
|
| 699 |
.. method:: GEOSGeometry.make_valid() |
| 700 |
|
| 701 |
Returns a valid :class:`GEOSGeometry` equivalent, trying not to lose any of |
| 702 |
the input vertices. If the geometry is already valid, it is returned |
| 703 |
untouched. This is similar to the |
| 704 |
:class:`~django.contrib.gis.db.models.functions.MakeValid` database |
| 705 |
function. Requires GEOS 3.8. |
| 706 |
|
| 707 |
.. method:: GEOSGeometry.normalize(clone=False) |
| 708 |
|
| 709 |
Converts this geometry to canonical form. If the ``clone`` keyword is set, |
| 710 |
then the geometry is not modified and a normalized clone of the geometry is |
| 711 |
returned instead: |
| 712 |
|
| 713 |
.. code-block:: pycon |
| 714 |
|
| 715 |
>>> g = MultiPoint(Point(0, 0), Point(2, 2), Point(1, 1)) |
| 716 |
>>> print(g) |
| 717 |
MULTIPOINT (0 0, 2 2, 1 1) |
| 718 |
>>> g.normalize() |
| 719 |
>>> print(g) |
| 720 |
MULTIPOINT (2 2, 1 1, 0 0) |
| 721 |
|
| 722 |
``Point`` |
| 723 |
--------- |
| 724 |
|
| 725 |
.. class:: Point(x=None, y=None, z=None, srid=None) |
| 726 |
|
| 727 |
``Point`` objects are instantiated using arguments that represent the |
| 728 |
component coordinates of the point or with a single sequence coordinates. |
| 729 |
For example, the following are equivalent: |
| 730 |
|
| 731 |
.. code-block:: pycon |
| 732 |
|
| 733 |
>>> pnt = Point(5, 23) |
| 734 |
>>> pnt = Point([5, 23]) |
| 735 |
|
| 736 |
Empty ``Point`` objects may be instantiated by passing no arguments or an |
| 737 |
empty sequence. The following are equivalent: |
| 738 |
|
| 739 |
.. code-block:: pycon |
| 740 |
|
| 741 |
>>> pnt = Point() |
| 742 |
>>> pnt = Point([]) |
| 743 |
|
| 744 |
``LineString`` |
| 745 |
-------------- |
| 746 |
|
| 747 |
.. class:: LineString(*args, **kwargs) |
| 748 |
|
| 749 |
``LineString`` objects are instantiated using arguments that are either a |
| 750 |
sequence of coordinates or :class:`Point` objects. For example, the |
| 751 |
following are equivalent: |
| 752 |
|
| 753 |
.. code-block:: pycon |
| 754 |
|
| 755 |
>>> ls = LineString((0, 0), (1, 1)) |
| 756 |
>>> ls = LineString(Point(0, 0), Point(1, 1)) |
| 757 |
|
| 758 |
In addition, ``LineString`` objects may also be created by passing in a |
| 759 |
single sequence of coordinate or :class:`Point` objects: |
| 760 |
|
| 761 |
.. code-block:: pycon |
| 762 |
|
| 763 |
>>> ls = LineString(((0, 0), (1, 1))) |
| 764 |
>>> ls = LineString([Point(0, 0), Point(1, 1)]) |
| 765 |
|
| 766 |
Empty ``LineString`` objects may be instantiated by passing no arguments |
| 767 |
or an empty sequence. The following are equivalent: |
| 768 |
|
| 769 |
.. code-block:: pycon |
| 770 |
|
| 771 |
>>> ls = LineString() |
| 772 |
>>> ls = LineString([]) |
| 773 |
|
| 774 |
.. attribute:: closed |
| 775 |
|
| 776 |
Returns whether or not this ``LineString`` is closed. |
| 777 |
|
| 778 |
``LinearRing`` |
| 779 |
-------------- |
| 780 |
|
| 781 |
.. class:: LinearRing(*args, **kwargs) |
| 782 |
|
| 783 |
``LinearRing`` objects are constructed in the exact same way as |
| 784 |
:class:`LineString` objects, however the coordinates must be *closed*, in |
| 785 |
other words, the first coordinates must be the same as the last |
| 786 |
coordinates. For example: |
| 787 |
|
| 788 |
.. code-block:: pycon |
| 789 |
|
| 790 |
>>> ls = LinearRing((0, 0), (0, 1), (1, 1), (0, 0)) |
| 791 |
|
| 792 |
Notice that ``(0, 0)`` is the first and last coordinate -- if they were not |
| 793 |
equal, an error would be raised. |
| 794 |
|
| 795 |
.. attribute:: is_counterclockwise |
| 796 |
|
| 797 |
Returns whether this ``LinearRing`` is counterclockwise. |
| 798 |
|
| 799 |
``Polygon`` |
| 800 |
----------- |
| 801 |
|
| 802 |
.. class:: Polygon(*args, **kwargs) |
| 803 |
|
| 804 |
``Polygon`` objects may be instantiated by passing in parameters that |
| 805 |
represent the rings of the polygon. The parameters must either be |
| 806 |
:class:`LinearRing` instances, or a sequence that may be used to construct a |
| 807 |
:class:`LinearRing`: |
| 808 |
|
| 809 |
.. code-block:: pycon |
| 810 |
|
| 811 |
>>> ext_coords = ((0, 0), (0, 1), (1, 1), (1, 0), (0, 0)) |
| 812 |
>>> int_coords = ((0.4, 0.4), (0.4, 0.6), (0.6, 0.6), (0.6, 0.4), (0.4, 0.4)) |
| 813 |
>>> poly = Polygon(ext_coords, int_coords) |
| 814 |
>>> poly = Polygon(LinearRing(ext_coords), LinearRing(int_coords)) |
| 815 |
|
| 816 |
.. classmethod:: from_bbox(bbox) |
| 817 |
|
| 818 |
Returns a polygon object from the given bounding-box, a 4-tuple |
| 819 |
comprising ``(xmin, ymin, xmax, ymax)``. |
| 820 |
|
| 821 |
.. attribute:: num_interior_rings |
| 822 |
|
| 823 |
Returns the number of interior rings in this geometry. |
| 824 |
|
| 825 |
.. admonition:: Comparing Polygons |
| 826 |
|
| 827 |
Note that it is possible to compare ``Polygon`` objects directly with ``<`` |
| 828 |
or ``>``, but as the comparison is made through Polygon's |
| 829 |
:class:`LineString`, it does not mean much (but is consistent and quick). |
| 830 |
You can always force the comparison with the :attr:`~GEOSGeometry.area` |
| 831 |
property: |
| 832 |
|
| 833 |
.. code-block:: pycon |
| 834 |
|
| 835 |
>>> if poly_1.area > poly_2.area: |
| 836 |
... pass |
| 837 |
... |
| 838 |
|
| 839 |
.. _geos-geometry-collections: |
| 840 |
|
| 841 |
Geometry Collections |
| 842 |
==================== |
| 843 |
|
| 844 |
``MultiPoint`` |
| 845 |
-------------- |
| 846 |
|
| 847 |
.. class:: MultiPoint(*args, **kwargs) |
| 848 |
|
| 849 |
``MultiPoint`` objects may be instantiated by passing in :class:`Point` |
| 850 |
objects as arguments, or a single sequence of :class:`Point` objects: |
| 851 |
|
| 852 |
.. code-block:: pycon |
| 853 |
|
| 854 |
>>> mp = MultiPoint(Point(0, 0), Point(1, 1)) |
| 855 |
>>> mp = MultiPoint((Point(0, 0), Point(1, 1))) |
| 856 |
|
| 857 |
``MultiLineString`` |
| 858 |
------------------- |
| 859 |
|
| 860 |
.. class:: MultiLineString(*args, **kwargs) |
| 861 |
|
| 862 |
``MultiLineString`` objects may be instantiated by passing in |
| 863 |
:class:`LineString` objects as arguments, or a single sequence of |
| 864 |
:class:`LineString` objects: |
| 865 |
|
| 866 |
.. code-block:: pycon |
| 867 |
|
| 868 |
>>> ls1 = LineString((0, 0), (1, 1)) |
| 869 |
>>> ls2 = LineString((2, 2), (3, 3)) |
| 870 |
>>> mls = MultiLineString(ls1, ls2) |
| 871 |
>>> mls = MultiLineString([ls1, ls2]) |
| 872 |
|
| 873 |
.. attribute:: merged |
| 874 |
|
| 875 |
Returns a :class:`LineString` representing the line merge of |
| 876 |
all the components in this ``MultiLineString``. |
| 877 |
|
| 878 |
.. attribute:: closed |
| 879 |
|
| 880 |
Returns ``True`` if and only if all elements are closed. |
| 881 |
|
| 882 |
``MultiPolygon`` |
| 883 |
---------------- |
| 884 |
|
| 885 |
.. class:: MultiPolygon(*args, **kwargs) |
| 886 |
|
| 887 |
``MultiPolygon`` objects may be instantiated by passing :class:`Polygon` |
| 888 |
objects as arguments, or a single sequence of :class:`Polygon` objects: |
| 889 |
|
| 890 |
.. code-block:: pycon |
| 891 |
|
| 892 |
>>> p1 = Polygon(((0, 0), (0, 1), (1, 1), (0, 0))) |
| 893 |
>>> p2 = Polygon(((1, 1), (1, 2), (2, 2), (1, 1))) |
| 894 |
>>> mp = MultiPolygon(p1, p2) |
| 895 |
>>> mp = MultiPolygon([p1, p2]) |
| 896 |
|
| 897 |
``GeometryCollection`` |
| 898 |
---------------------- |
| 899 |
|
| 900 |
.. class:: GeometryCollection(*args, **kwargs) |
| 901 |
|
| 902 |
``GeometryCollection`` objects may be instantiated by passing in other |
| 903 |
:class:`GEOSGeometry` as arguments, or a single sequence of |
| 904 |
:class:`GEOSGeometry` objects: |
| 905 |
|
| 906 |
.. code-block:: pycon |
| 907 |
|
| 908 |
>>> poly = Polygon(((0, 0), (0, 1), (1, 1), (0, 0))) |
| 909 |
>>> gc = GeometryCollection(Point(0, 0), MultiPoint(Point(0, 0), Point(1, 1)), poly) |
| 910 |
>>> gc = GeometryCollection((Point(0, 0), MultiPoint(Point(0, 0), Point(1, 1)), poly)) |
| 911 |
|
| 912 |
.. _prepared-geometries: |
| 913 |
|
| 914 |
Prepared Geometries |
| 915 |
=================== |
| 916 |
|
| 917 |
In order to obtain a prepared geometry, access the |
| 918 |
:attr:`GEOSGeometry.prepared` property. Once you have a |
| 919 |
``PreparedGeometry`` instance its spatial predicate methods, listed below, |
| 920 |
may be used with other ``GEOSGeometry`` objects. An operation with a prepared |
| 921 |
geometry can be orders of magnitude faster -- the more complex the geometry |
| 922 |
that is prepared, the larger the speedup in the operation. For more information, |
| 923 |
please consult the `GEOS wiki page on prepared geometries <https://trac.osgeo.org/geos/wiki/PreparedGeometry>`_. |
| 924 |
|
| 925 |
For example: |
| 926 |
|
| 927 |
.. code-block:: pycon |
| 928 |
|
| 929 |
>>> from django.contrib.gis.geos import Point, Polygon |
| 930 |
>>> poly = Polygon.from_bbox((0, 0, 5, 5)) |
| 931 |
>>> prep_poly = poly.prepared |
| 932 |
>>> prep_poly.contains(Point(2.5, 2.5)) |
| 933 |
True |
| 934 |
|
| 935 |
``PreparedGeometry`` |
| 936 |
-------------------- |
| 937 |
|
| 938 |
.. class:: PreparedGeometry |
| 939 |
|
| 940 |
All methods on ``PreparedGeometry`` take an ``other`` argument, which |
| 941 |
must be a :class:`GEOSGeometry` instance. |
| 942 |
|
| 943 |
.. method:: contains(other) |
| 944 |
|
| 945 |
.. method:: contains_properly(other) |
| 946 |
|
| 947 |
.. method:: covers(other) |
| 948 |
|
| 949 |
.. method:: crosses(other) |
| 950 |
|
| 951 |
.. method:: disjoint(other) |
| 952 |
|
| 953 |
.. method:: intersects(other) |
| 954 |
|
| 955 |
.. method:: overlaps(other) |
| 956 |
|
| 957 |
.. method:: touches(other) |
| 958 |
|
| 959 |
.. method:: within(other) |
| 960 |
|
| 961 |
Geometry Factories |
| 962 |
================== |
| 963 |
|
| 964 |
.. function:: fromfile(file_h) |
| 965 |
|
| 966 |
:param file_h: input file that contains spatial data |
| 967 |
:type file_h: a Python ``file`` object or a string path to the file |
| 968 |
:rtype: a :class:`GEOSGeometry` corresponding to the spatial data in the file |
| 969 |
|
| 970 |
Example: |
| 971 |
|
| 972 |
.. code-block:: pycon |
| 973 |
|
| 974 |
>>> from django.contrib.gis.geos import fromfile |
| 975 |
>>> g = fromfile("/home/bob/geom.wkt") |
| 976 |
|
| 977 |
.. function:: fromstr(string, srid=None) |
| 978 |
|
| 979 |
:param string: string that contains spatial data |
| 980 |
:type string: str |
| 981 |
:param srid: spatial reference identifier |
| 982 |
:type srid: int |
| 983 |
:rtype: a :class:`GEOSGeometry` corresponding to the spatial data in the string |
| 984 |
|
| 985 |
``fromstr(string, srid)`` is equivalent to |
| 986 |
:class:`GEOSGeometry(string, srid) <GEOSGeometry>`. |
| 987 |
|
| 988 |
Example: |
| 989 |
|
| 990 |
.. code-block:: pycon |
| 991 |
|
| 992 |
>>> from django.contrib.gis.geos import fromstr |
| 993 |
>>> pnt = fromstr("POINT(-90.5 29.5)", srid=4326) |
| 994 |
|
| 995 |
I/O Objects |
| 996 |
=========== |
| 997 |
|
| 998 |
Reader Objects |
| 999 |
-------------- |
| 1000 |
|
| 1001 |
The reader I/O classes return a :class:`GEOSGeometry` instance from the WKB |
| 1002 |
and/or WKT input given to their ``read(geom)`` method. |
| 1003 |
|
| 1004 |
.. class:: WKBReader |
| 1005 |
|
| 1006 |
Example: |
| 1007 |
|
| 1008 |
.. code-block:: pycon |
| 1009 |
|
| 1010 |
>>> from django.contrib.gis.geos import WKBReader |
| 1011 |
>>> wkb_r = WKBReader() |
| 1012 |
>>> wkb_r.read("0101000000000000000000F03F000000000000F03F") |
| 1013 |
<Point object at 0x103a88910> |
| 1014 |
|
| 1015 |
.. class:: WKTReader |
| 1016 |
|
| 1017 |
Example: |
| 1018 |
|
| 1019 |
.. code-block:: pycon |
| 1020 |
|
| 1021 |
>>> from django.contrib.gis.geos import WKTReader |
| 1022 |
>>> wkt_r = WKTReader() |
| 1023 |
>>> wkt_r.read("POINT(1 1)") |
| 1024 |
<Point object at 0x103a88b50> |
| 1025 |
|
| 1026 |
Writer Objects |
| 1027 |
-------------- |
| 1028 |
|
| 1029 |
All writer objects have a ``write(geom)`` method that returns either the |
| 1030 |
WKB or WKT of the given geometry. In addition, :class:`WKBWriter` objects |
| 1031 |
also have properties that may be used to change the byte order, and or |
| 1032 |
include the SRID value (in other words, EWKB). |
| 1033 |
|
| 1034 |
.. class:: WKBWriter(dim=2) |
| 1035 |
|
| 1036 |
``WKBWriter`` provides the most control over its output. By default it |
| 1037 |
returns OGC-compliant WKB when its ``write`` method is called. However, |
| 1038 |
it has properties that allow for the creation of EWKB, a superset of the |
| 1039 |
WKB standard that includes additional information. See the |
| 1040 |
:attr:`WKBWriter.outdim` documentation for more details about the ``dim`` |
| 1041 |
argument. |
| 1042 |
|
| 1043 |
.. method:: WKBWriter.write(geom) |
| 1044 |
|
| 1045 |
Returns the WKB of the given geometry as a Python ``buffer`` object. |
| 1046 |
Example: |
| 1047 |
|
| 1048 |
.. code-block:: pycon |
| 1049 |
|
| 1050 |
>>> from django.contrib.gis.geos import Point, WKBWriter |
| 1051 |
>>> pnt = Point(1, 1) |
| 1052 |
>>> wkb_w = WKBWriter() |
| 1053 |
>>> wkb_w.write(pnt) |
| 1054 |
<read-only buffer for 0x103a898f0, size -1, offset 0 at 0x103a89930> |
| 1055 |
|
| 1056 |
.. method:: WKBWriter.write_hex(geom) |
| 1057 |
|
| 1058 |
Returns WKB of the geometry in hexadecimal. Example: |
| 1059 |
|
| 1060 |
.. code-block:: pycon |
| 1061 |
|
| 1062 |
>>> from django.contrib.gis.geos import Point, WKBWriter |
| 1063 |
>>> pnt = Point(1, 1) |
| 1064 |
>>> wkb_w = WKBWriter() |
| 1065 |
>>> wkb_w.write_hex(pnt) |
| 1066 |
'0101000000000000000000F03F000000000000F03F' |
| 1067 |
|
| 1068 |
.. attribute:: WKBWriter.byteorder |
| 1069 |
|
| 1070 |
This property may be set to change the byte-order of the geometry |
| 1071 |
representation. |
| 1072 |
|
| 1073 |
=============== ================================================= |
| 1074 |
Byteorder Value Description |
| 1075 |
=============== ================================================= |
| 1076 |
0 Big Endian (e.g., compatible with RISC systems) |
| 1077 |
1 Little Endian (e.g., compatible with x86 systems) |
| 1078 |
=============== ================================================= |
| 1079 |
|
| 1080 |
Example: |
| 1081 |
|
| 1082 |
.. code-block:: pycon |
| 1083 |
|
| 1084 |
>>> from django.contrib.gis.geos import Point, WKBWriter |
| 1085 |
>>> wkb_w = WKBWriter() |
| 1086 |
>>> pnt = Point(1, 1) |
| 1087 |
>>> wkb_w.write_hex(pnt) |
| 1088 |
'0101000000000000000000F03F000000000000F03F' |
| 1089 |
>>> wkb_w.byteorder = 0 |
| 1090 |
'00000000013FF00000000000003FF0000000000000' |
| 1091 |
|
| 1092 |
.. attribute:: WKBWriter.outdim |
| 1093 |
|
| 1094 |
This property may be set to change the output dimension of the geometry |
| 1095 |
representation. In other words, if you have a 3D geometry then set to 3 |
| 1096 |
so that the Z value is included in the WKB. |
| 1097 |
|
| 1098 |
============ =========================== |
| 1099 |
Outdim Value Description |
| 1100 |
============ =========================== |
| 1101 |
2 The default, output 2D WKB. |
| 1102 |
3 Output 3D WKB. |
| 1103 |
============ =========================== |
| 1104 |
|
| 1105 |
Example: |
| 1106 |
|
| 1107 |
.. code-block:: pycon |
| 1108 |
|
| 1109 |
>>> from django.contrib.gis.geos import Point, WKBWriter |
| 1110 |
>>> wkb_w = WKBWriter() |
| 1111 |
>>> wkb_w.outdim |
| 1112 |
2 |
| 1113 |
>>> pnt = Point(1, 1, 1) |
| 1114 |
>>> wkb_w.write_hex(pnt) # By default, no Z value included: |
| 1115 |
'0101000000000000000000F03F000000000000F03F' |
| 1116 |
>>> wkb_w.outdim = 3 # Tell writer to include Z values |
| 1117 |
>>> wkb_w.write_hex(pnt) |
| 1118 |
'0101000080000000000000F03F000000000000F03F000000000000F03F' |
| 1119 |
|
| 1120 |
.. attribute:: WKBWriter.srid |
| 1121 |
|
| 1122 |
Set this property with a boolean to indicate whether the SRID of the |
| 1123 |
geometry should be included with the WKB representation. Example: |
| 1124 |
|
| 1125 |
.. code-block:: pycon |
| 1126 |
|
| 1127 |
>>> from django.contrib.gis.geos import Point, WKBWriter |
| 1128 |
>>> wkb_w = WKBWriter() |
| 1129 |
>>> pnt = Point(1, 1, srid=4326) |
| 1130 |
>>> wkb_w.write_hex(pnt) # By default, no SRID included: |
| 1131 |
'0101000000000000000000F03F000000000000F03F' |
| 1132 |
>>> wkb_w.srid = True # Tell writer to include SRID |
| 1133 |
>>> wkb_w.write_hex(pnt) |
| 1134 |
'0101000020E6100000000000000000F03F000000000000F03F' |
| 1135 |
|
| 1136 |
.. class:: WKTWriter(dim=2, trim=False, precision=None) |
| 1137 |
|
| 1138 |
This class allows outputting the WKT representation of a geometry. See the |
| 1139 |
:attr:`WKBWriter.outdim`, :attr:`trim`, and :attr:`precision` attributes for |
| 1140 |
details about the constructor arguments. |
| 1141 |
|
| 1142 |
.. method:: WKTWriter.write(geom) |
| 1143 |
|
| 1144 |
Returns the WKT of the given geometry. Example: |
| 1145 |
|
| 1146 |
.. code-block:: pycon |
| 1147 |
|
| 1148 |
>>> from django.contrib.gis.geos import Point, WKTWriter |
| 1149 |
>>> pnt = Point(1, 1) |
| 1150 |
>>> wkt_w = WKTWriter() |
| 1151 |
>>> wkt_w.write(pnt) |
| 1152 |
'POINT (1.0000000000000000 1.0000000000000000)' |
| 1153 |
|
| 1154 |
.. attribute:: WKTWriter.outdim |
| 1155 |
|
| 1156 |
See :attr:`WKBWriter.outdim`. |
| 1157 |
|
| 1158 |
.. attribute:: WKTWriter.trim |
| 1159 |
|
| 1160 |
This property is used to enable or disable trimming of |
| 1161 |
unnecessary decimals. |
| 1162 |
|
| 1163 |
.. code-block:: pycon |
| 1164 |
|
| 1165 |
>>> from django.contrib.gis.geos import Point, WKTWriter |
| 1166 |
>>> pnt = Point(1, 1) |
| 1167 |
>>> wkt_w = WKTWriter() |
| 1168 |
>>> wkt_w.trim |
| 1169 |
False |
| 1170 |
>>> wkt_w.write(pnt) |
| 1171 |
'POINT (1.0000000000000000 1.0000000000000000)' |
| 1172 |
>>> wkt_w.trim = True |
| 1173 |
>>> wkt_w.write(pnt) |
| 1174 |
'POINT (1 1)' |
| 1175 |
|
| 1176 |
.. attribute:: WKTWriter.precision |
| 1177 |
|
| 1178 |
This property controls the rounding precision of coordinates; |
| 1179 |
if set to ``None`` rounding is disabled. |
| 1180 |
|
| 1181 |
>>> from django.contrib.gis.geos import Point, WKTWriter |
| 1182 |
>>> pnt = Point(1.44, 1.66) |
| 1183 |
>>> wkt_w = WKTWriter() |
| 1184 |
>>> print(wkt_w.precision) |
| 1185 |
None |
| 1186 |
>>> wkt_w.write(pnt) |
| 1187 |
'POINT (1.4399999999999999 1.6599999999999999)' |
| 1188 |
>>> wkt_w.precision = 0 |
| 1189 |
>>> wkt_w.write(pnt) |
| 1190 |
'POINT (1 2)' |
| 1191 |
>>> wkt_w.precision = 1 |
| 1192 |
>>> wkt_w.write(pnt) |
| 1193 |
'POINT (1.4 1.7)' |
| 1194 |
|
| 1195 |
.. rubric:: Footnotes |
| 1196 |
.. [#fnogc] *See* `PostGIS EWKB, EWKT and Canonical Forms <https://postgis.net/docs/using_postgis_dbmanagement.html#EWKB_EWKT>`_, PostGIS documentation at Ch. 4.1.2. |
| 1197 |
|
| 1198 |
Settings |
| 1199 |
======== |
| 1200 |
|
| 1201 |
.. setting:: GEOS_LIBRARY_PATH |
| 1202 |
|
| 1203 |
``GEOS_LIBRARY_PATH`` |
| 1204 |
--------------------- |
| 1205 |
|
| 1206 |
A string specifying the location of the GEOS C library. Typically, |
| 1207 |
this setting is only used if the GEOS C library is in a non-standard |
| 1208 |
location (e.g., ``/home/bob/lib/libgeos_c.so``). |
| 1209 |
|
| 1210 |
.. note:: |
| 1211 |
|
| 1212 |
The setting must be the *full* path to the **C** shared library; in |
| 1213 |
other words you want to use ``libgeos_c.so``, not ``libgeos.so``. |
| 1214 |
|
| 1215 |
Exceptions |
| 1216 |
========== |
| 1217 |
|
| 1218 |
.. exception:: GEOSException |
| 1219 |
|
| 1220 |
The base GEOS exception, indicates a GEOS-related error. |