Debian Codegraph @

docs/ref/contrib/gis/geos.txt

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