1 | ========
|
---|
2 | GEOS API
|
---|
3 | ========
|
---|
4 |
|
---|
5 | Background
|
---|
6 | ==========
|
---|
7 |
|
---|
8 | What is GEOS?
|
---|
9 | -------------
|
---|
10 |
|
---|
11 | `GEOS`__ stands for **G**\ eometry **E**\ ngine - **O**\ pen **S**\ ource, and is a C++
|
---|
12 | port of the `Java Topology Suite`__, implementing the OpenGIS
|
---|
13 | `Simple Features for SQL`__ spatial predicate functions and spatial operators.
|
---|
14 | GEOS, now an OSGeo project, was initially developed and maintained by
|
---|
15 | `Refractions Research`__ of Victoria, Canada.
|
---|
16 |
|
---|
17 | __ http://trac.osgeo.org/geos/
|
---|
18 | __ http://sourceforge.net/projects/jts-topo-suite/
|
---|
19 | __ http://www.opengeospatial.org/standards/sfs
|
---|
20 | __ http://www.refractions.net/
|
---|
21 |
|
---|
22 | Why the new API?
|
---|
23 | ----------------
|
---|
24 | 1. The GEOS SWIG wrapper is no longer maintained, and requires the installation
|
---|
25 | of `SWIG`__. [#]_
|
---|
26 | 2. The `PCL implementation`__ is over 2K+ lines of C and would make PCL a
|
---|
27 | requisite package for the GeoDjango application stack.
|
---|
28 | 3. Cross-platform compatibility.
|
---|
29 |
|
---|
30 | Thus, the Python ``ctypes`` [#]_ package was used to wrap the `GEOS C API`__
|
---|
31 | to bring the rich capabilities of GEOS to Python and GeoDjango.
|
---|
32 |
|
---|
33 | Features:
|
---|
34 |
|
---|
35 | * A BSD-licensed interface to the GEOS geometry routines, implemented purely
|
---|
36 | in Python using ``ctypes``.
|
---|
37 | * Loosely-coupled to GeoDjango. For example, GEOS geometry objects may be
|
---|
38 | used outside a django project/application (no need to have
|
---|
39 | ``DJANGO_SETTINGS_MODULE`` set, etc.)
|
---|
40 | * Mutability. GEOS Geometry objects may be modified.
|
---|
41 | * Cross-platform and tested. GeoDjango GEOS geometries are well-tested and
|
---|
42 | compatible with Windows, Linux, Solaris, and Mac OS X platforms.
|
---|
43 |
|
---|
44 | __ http://www.swig.org/
|
---|
45 | __ http://trac.gispython.org/projects/PCL/browser/PCL/trunk/PCL-Core/cartography/geometry
|
---|
46 | __ http://trac.osgeo.org/geos/browser/trunk/capi/geos_c.h.in
|
---|
47 |
|
---|
48 | Related Work
|
---|
49 | ------------
|
---|
50 |
|
---|
51 | The ``GEOSGeometry`` interface was first committed to the Django SVN by Justin
|
---|
52 | Bronn (the lead developer of GeoDjango) in April, 2007. [#]_ After learning of
|
---|
53 | GeoDjango's interface [#]_, Sean Gillies created his own ``ctypes`` interface,
|
---|
54 | "Shapely." [#]_ Justin Bronn declined to merge the projects because Shapely
|
---|
55 | was initially licensed under the LGPL, a license incompatible with GeoDjango. [#]_
|
---|
56 | While Shapely was later relicensed under the BSD license (the same as GeoDjango)
|
---|
57 | [#]_, differences in design and implementation prevent the projects from
|
---|
58 | merging at the moment, but are not irreconcilable.
|
---|
59 |
|
---|
60 | Geometry Objects
|
---|
61 | ================
|
---|
62 |
|
---|
63 | .. _point:
|
---|
64 |
|
---|
65 | .. class:: Point
|
---|
66 |
|
---|
67 | The ``Point`` object may be initialized with either a tuple, or individual
|
---|
68 | parameters. For example::
|
---|
69 |
|
---|
70 | >>> from django.contrib.gis.geos import Point
|
---|
71 | >>> p = Point((5, 23)) # 2D point, passed in as a tuple
|
---|
72 | >>> p = Point(5, 23) # Same, passed in with individual parameters
|
---|
73 |
|
---|
74 | The ``srid`` keyword may be used to specify the SRID for the point::
|
---|
75 |
|
---|
76 | >>> pnt = Point(5, 23, srid=4326)
|
---|
77 |
|
---|
78 | Additionally, 3D geometries may be created by specifing a Z value::
|
---|
79 |
|
---|
80 | >>> pnt_3d = Point(5, 23, 17) # Also: Point( (5, 23, 17) )
|
---|
81 | >>> pnt_3d.hasz
|
---|
82 | True
|
---|
83 | >>> pnt_3d.z
|
---|
84 | 17
|
---|
85 |
|
---|
86 | Properties
|
---|
87 | ----------
|
---|
88 |
|
---|
89 | .. attribute:: x
|
---|
90 |
|
---|
91 | This property sets or retrieves the X coordinate for the point.
|
---|
92 |
|
---|
93 | .. attribute:: y
|
---|
94 |
|
---|
95 | This property sets or retrieves the Y coordinate for the point.
|
---|
96 |
|
---|
97 | .. attribute:: z
|
---|
98 |
|
---|
99 | This property sets or retrieves the Z (3D) coordinate for the point.
|
---|
100 | If the point has no Z coordinate, ``None`` is returned.
|
---|
101 |
|
---|
102 | .. note:
|
---|
103 |
|
---|
104 | The ``Point`` must have been created as 3D before it is possible
|
---|
105 | to set the ``z`` property.
|
---|
106 |
|
---|
107 | .. _linestring:
|
---|
108 |
|
---|
109 | .. class:: LineString
|
---|
110 |
|
---|
111 | ``LineString`` objects initialize on a given sequence. For example, the constructor may
|
---|
112 | take lists, tuples, `NumPy`__ arrays of X,Y[,Z] pairs, or ``Point`` objects. If ``Point``
|
---|
113 | objects are used, ownership of the points is *not* transferred to the ``LineString``
|
---|
114 | object. Examples::
|
---|
115 |
|
---|
116 | >>> from django.contrib.gis.geos import LineString, Point
|
---|
117 | >>> ls = LineString((1, 1), (2, 2))
|
---|
118 | >>> ls = LineString([(1, 1), (2, 2)])
|
---|
119 | >>> ls = LineString(Point(1, 1), Point(2, 2))
|
---|
120 | >>> from numpy import array
|
---|
121 | >>> ls = LineString(array([(1, 1), (2, 2)]))
|
---|
122 |
|
---|
123 | .. class:: LinearRing
|
---|
124 |
|
---|
125 | ``LinearRing`` objects are subclasses of ``LineString``; however, an error will
|
---|
126 | be raised if the points used during initialization are not closed (the first
|
---|
127 | point is equal to the last point)::
|
---|
128 |
|
---|
129 | >>> from django.contrib.gis.geos import LinearRing
|
---|
130 | >>> lr = LinearRing((0, 0), (0, 1), (1, 1), (1, 0), (0, 0))
|
---|
131 | >>> lr = LinearRing((0, 0), (0, 1))
|
---|
132 | GEOS_ERROR: IllegalArgumentException: points must form a closed linestring
|
---|
133 |
|
---|
134 | __ http://numpy.scipy.org/
|
---|
135 |
|
---|
136 | Methods
|
---|
137 | -------
|
---|
138 |
|
---|
139 | .. method:: LineString(coords)
|
---|
140 |
|
---|
141 | .. attribute:: x
|
---|
142 |
|
---|
143 | This property returns the X values in a list, or a NumPy array (if installed).
|
---|
144 |
|
---|
145 | .. attribute:: y
|
---|
146 |
|
---|
147 | This property returns the Y values in a list, or a NumPy array (if installed).
|
---|
148 |
|
---|
149 | .. attribute:: z
|
---|
150 |
|
---|
151 | This property returns the Z values in a list, or a NumPy array (if installed).
|
---|
152 |
|
---|
153 | .. _polygon:
|
---|
154 |
|
---|
155 | .. class:: Polygon
|
---|
156 |
|
---|
157 | Polygons are composed of an exterior ring (the shell), and may also have
|
---|
158 | interior rings that denote areas excluded from the exterior.
|
---|
159 |
|
---|
160 | Methods
|
---|
161 | ^^^^^^^
|
---|
162 |
|
---|
163 | .. method:: Polygon(rings)
|
---|
164 |
|
---|
165 | The ``Polygon`` initializes on arguments that are either ``LinearRing`` instances
|
---|
166 | or may be accepted by the ``LinearRing`` constructor.
|
---|
167 |
|
---|
168 | .. method:: from_bbox(bbox)
|
---|
169 | .. versionadded:: 1.1
|
---|
170 |
|
---|
171 | Returns a new ``Polygon`` object for the given bounding box. The bounding box
|
---|
172 | should be a four-tuple comprising the X and Y minimum values followed by the
|
---|
173 | X and Y maximum values. For example::
|
---|
174 |
|
---|
175 | >>> from django.contrib.gis.geos import Polygon
|
---|
176 | >>> bbox = (0, 0, 5, 5)
|
---|
177 | >>> poly = Polygon.from_bbox(bbox)
|
---|
178 | >>> print poly
|
---|
179 | POLYGON ((0.0000000000000000 0.0000000000000000, 0.0000000000000000 5.0000000000000000, 5.0000000000000000 5.0000000000000000, 5.0000000000000000 0.0000000000000000, 0.0000000000000000 0.0000000000000000))
|
---|
180 |
|
---|
181 | .. method:: shell()
|
---|
182 | .. method:: exterior_ring()
|
---|
183 |
|
---|
184 | Returns a ``LinearRing`` corresponding to the exterior ring, or shell, of the
|
---|
185 | ``Polygon``.
|
---|
186 |
|
---|
187 | .. method:: num_interior_rings
|
---|
188 |
|
---|
189 | Returns the number of interior rings contained in the ``Polygon``.
|
---|
190 |
|
---|
191 | Geometry Collections
|
---|
192 | ====================
|
---|
193 |
|
---|
194 | .. _multipoint:
|
---|
195 |
|
---|
196 | .. class:: MultiPoint
|
---|
197 |
|
---|
198 | >>> from django.contrib.gis.geos import Point
|
---|
199 | >>> from django.contrib.gis.geos import MultiPoint
|
---|
200 | >>> p1 = Point((0,0))
|
---|
201 | >>> p2 = Point((1,2))
|
---|
202 | >>> mp = MultiPoint(p1, p2)
|
---|
203 | >>> mp
|
---|
204 | <MultiPoint object>
|
---|
205 | >>> mp[0].wkt
|
---|
206 | 'POINT (0.0000000000000000 0.0000000000000000)'
|
---|
207 | >>> len(mp)
|
---|
208 | 2
|
---|
209 | >>> [ p.wkt for p in mp ]
|
---|
210 | ['POINT (0.0000000000000000 0.0000000000000000)', 'POINT (1.0000000000000000 2.0000000000000000)']
|
---|
211 | >>> mp.ring
|
---|
212 | False
|
---|
213 |
|
---|
214 | .. _multilinestring:
|
---|
215 |
|
---|
216 | .. class:: MultiLineString
|
---|
217 |
|
---|
218 | .. _multipolygon:
|
---|
219 |
|
---|
220 | .. class:: MultiPolygon
|
---|
221 |
|
---|
222 | Methods
|
---|
223 | -------
|
---|
224 |
|
---|
225 | .. method:: cascaded_union
|
---|
226 |
|
---|
227 | .. versionadded:: 1.1
|
---|
228 |
|
---|
229 | .. note::
|
---|
230 |
|
---|
231 | Use of this method requires at least GEOS 3.1.
|
---|
232 |
|
---|
233 | .. _geometrycollection:
|
---|
234 |
|
---|
235 |
|
---|
236 | .. class:: GeometryCollection
|
---|
237 |
|
---|
238 | .. _prepared:
|
---|
239 |
|
---|
240 | Prepared Geometries
|
---|
241 | ===================
|
---|
242 | .. versionadded: 1.1
|
---|
243 |
|
---|
244 | In order to obtain a prepared geometry, just access the ``prepared``
|
---|
245 | property on any ``GEOSGeometry`` object. Once you have a
|
---|
246 | ``PreparedGeometry`` instance its spatial predicate methods, listed below,
|
---|
247 | may be used with other ``GEOSGeometry`` objects. An operation with a prepared
|
---|
248 | geometry can be orders of magnitude faster -- the more complex the geometry
|
---|
249 | that is prepared, the larger the speedup in the operation.
|
---|
250 |
|
---|
251 | .. note::
|
---|
252 |
|
---|
253 | GEOS 3.1 is *required* in order to use prepared geometries.
|
---|
254 |
|
---|
255 | For example::
|
---|
256 |
|
---|
257 | >>> from django.contrib.gis.geos import Point, Polygon
|
---|
258 | >>> poly = Polygon.from_bbox((0, 0, 5, 5))
|
---|
259 | >>> prep_poly = poly.prepared
|
---|
260 | >>> prep_poly.contains(Point(2.5, 2.5))
|
---|
261 | True
|
---|
262 |
|
---|
263 | .. class:: PreparedGeometry
|
---|
264 |
|
---|
265 | All methods on ``PreparedGeometry`` take an ``other`` argument, which
|
---|
266 | must be a ``GEOSGeometry`` object.
|
---|
267 |
|
---|
268 | .. method:: contains(other)
|
---|
269 |
|
---|
270 | .. method:: contains_properly(other)
|
---|
271 |
|
---|
272 | .. method:: covers(other)
|
---|
273 |
|
---|
274 | .. method:: intersects(other)
|
---|
275 |
|
---|
276 | I/O Objects
|
---|
277 | ===========
|
---|
278 | .. versionadded: 1.1
|
---|
279 |
|
---|
280 | Inside GEOS, I/O classes are used to output geometries to WKT, WKB, and EWKB.
|
---|
281 | GeoDjango allows access to these I/O classes if finer-grained control of
|
---|
282 | serialization is required. Typically,
|
---|
283 |
|
---|
284 | Reader Objects
|
---|
285 | --------------
|
---|
286 |
|
---|
287 | The reader I/O classes simply return a ``GEOSGeometry`` instance from the
|
---|
288 | WKB and/or WKT input given to their ``read(geom)`` method.
|
---|
289 |
|
---|
290 | .. class:: WKBReader
|
---|
291 |
|
---|
292 | Example::
|
---|
293 |
|
---|
294 | >>> from django.contrib.gis.geos import WKBReader
|
---|
295 | >>> wkb_r = WKBReader()
|
---|
296 | >>> wkb_r.read('0101000000000000000000F03F000000000000F03F')
|
---|
297 | <Point object at 0x103a88910>
|
---|
298 |
|
---|
299 | .. class:: WKTReader
|
---|
300 |
|
---|
301 | Example::
|
---|
302 |
|
---|
303 | >>> from django.contrib.gis.geos import WKTReader
|
---|
304 | >>> wkt_r = WKTReader()
|
---|
305 | >>> wkt_r.read('POINT(1 1)')
|
---|
306 | <Point object at 0x103a88b50>
|
---|
307 |
|
---|
308 | Writer Objects
|
---|
309 | --------------
|
---|
310 |
|
---|
311 | All writer objects have a ``write(geom)`` method that returns either the
|
---|
312 | WKB or WKT of the given geometry. In addition, ``WKBWriter`` objects
|
---|
313 | also have properties that may be used to change the byte order, and or
|
---|
314 | include the SRID and 3D values (in other words, EWKB).
|
---|
315 |
|
---|
316 | .. class:: WKBWriter
|
---|
317 |
|
---|
318 | The ``WKBWriter`` provides the most control over its output. By default it
|
---|
319 | returns OGC-compliant WKB when it's ``write`` method is called. However,
|
---|
320 | it has properties that
|
---|
321 |
|
---|
322 | .. function:: write(geom)
|
---|
323 |
|
---|
324 | Returns the WKB of the given geometry as a Python ``buffer`` object.
|
---|
325 | Example::
|
---|
326 |
|
---|
327 | >>> from django.contrib.gis.geos import Point, WKBWriter
|
---|
328 | >>> pnt = Point(1, 1)
|
---|
329 | >>> wkb_w = WKBWriter()
|
---|
330 | >>> wkb_w.write(pnt)
|
---|
331 | <read-only buffer for 0x103a898f0, size -1, offset 0 at 0x103a89930>
|
---|
332 |
|
---|
333 | .. function:: write_hex(geom)
|
---|
334 |
|
---|
335 | Returns WKB of the geometry in hexadecimal. Example::
|
---|
336 |
|
---|
337 | >>> from django.contrib.gis.geos import Point, WKBWriter
|
---|
338 | >>> pnt = Point(1, 1)
|
---|
339 | >>> wkb_w = WKBWriter()
|
---|
340 | >>> wkb_w.write_hex(pnt)
|
---|
341 | '0101000000000000000000F03F000000000000F03F'
|
---|
342 |
|
---|
343 | .. function:: byteorder
|
---|
344 |
|
---|
345 | This property may be be set to change the byte-order of the geometry
|
---|
346 | representation.
|
---|
347 |
|
---|
348 | =============== =================================================
|
---|
349 | Byteorder Value Description
|
---|
350 | =============== =================================================
|
---|
351 | 0 Big Endian (e.g., compatible with RISC systems)
|
---|
352 | 1 Little Endian (e.g., compatible with x86 systems)
|
---|
353 | =============== =================================================
|
---|
354 |
|
---|
355 | Example::
|
---|
356 |
|
---|
357 | >>> from django.contrib.gis.geos import Point, WKBWriter
|
---|
358 | >>> wkb_w = WKBWriter()
|
---|
359 | >>> pnt = Point(1, 1)
|
---|
360 | >>> wkb_w.write_hex(pnt)
|
---|
361 | '0101000000000000000000F03F000000000000F03F'
|
---|
362 | >>> wkb_w.byteorder = 0
|
---|
363 | '00000000013FF00000000000003FF0000000000000'
|
---|
364 |
|
---|
365 | .. attribute:: outdim
|
---|
366 |
|
---|
367 | This property may be set to change the output dimension of the geometry
|
---|
368 | representation. In other words, if you have a 3D geometry then set to 3
|
---|
369 | so that the Z value is included in the WKB.
|
---|
370 |
|
---|
371 | ============ ===========================
|
---|
372 | Outdim Value Description
|
---|
373 | ============ ===========================
|
---|
374 | 2 The default, output 2D WKB.
|
---|
375 | 3 Output 3D EWKB.
|
---|
376 | ============ ===========================
|
---|
377 |
|
---|
378 | Example::
|
---|
379 |
|
---|
380 | >>> from django.contrib.gis.geos import Point, WKBWriter
|
---|
381 | >>> wkb_w = WKBWriter()
|
---|
382 | >>> wkb_w.outdim
|
---|
383 | 2
|
---|
384 | >>> pnt = Point(1, 1, 1)
|
---|
385 | >>> wkb_w.write_hex(pnt) # By default, no Z value included:
|
---|
386 | '0101000000000000000000F03F000000000000F03F'
|
---|
387 | >>> wkb_w.outdim = 3 # Tell writer to include Z values
|
---|
388 | >>> wkb_w.write_hex(pnt)
|
---|
389 | '0101000080000000000000F03F000000000000F03F000000000000F03F'
|
---|
390 |
|
---|
391 | .. attribute:: srid
|
---|
392 |
|
---|
393 | Set this property with a boolean to indicate whether the SRID of the
|
---|
394 | geometry should be included with the WKB representation. Example::
|
---|
395 |
|
---|
396 | >>> from django.contrib.gis.geos import Point, WKBWriter
|
---|
397 | >>> wkb_w = WKBWriter()
|
---|
398 | >>> pnt = Point(1, 1, srid=4326)
|
---|
399 | >>> wkb_w.write_hex(pnt) # By default, no SRID included:
|
---|
400 | '0101000000000000000000F03F000000000000F03F'
|
---|
401 | >>> wkb_w.srid = True # Tell writer to include SRID
|
---|
402 | >>> wkb_w.write_hex(pnt)
|
---|
403 | '0101000020E6100000000000000000F03F000000000000F03F'
|
---|
404 |
|
---|
405 | .. class:: WKTWriter
|
---|
406 |
|
---|
407 | .. method:: write(geom)
|
---|
408 |
|
---|
409 | Returns the WKT of the given geometry. Example::
|
---|
410 |
|
---|
411 | >>> from django.contrib.gis.geos import Point, WKTWriter
|
---|
412 | >>> pnt = Point(1, 1)
|
---|
413 | >>> wkt_w = WKTWriter()
|
---|
414 | >>> wkt_w.write(pnt)
|
---|
415 | 'POINT (1.0000000000000000 1.0000000000000000)'
|
---|
416 |
|
---|
417 | API
|
---|
418 | ===
|
---|
419 |
|
---|
420 | Creation
|
---|
421 | --------
|
---|
422 |
|
---|
423 | .. class:: GEOSGeometry(geo_input, srid=None)
|
---|
424 |
|
---|
425 | Geometries may be created using the ``GEOSGeometry`` constructor; ``geo_input``
|
---|
426 | may be any of the following types of data:
|
---|
427 |
|
---|
428 | ============ ====================== =========================================================================================
|
---|
429 | Input Type Python Type Example
|
---|
430 | ============ ====================== =========================================================================================
|
---|
431 | WKT ``str`` / ``unicode`` ``'POINT(5 23)'``
|
---|
432 | EWKT ``str`` / ``unicode`` ``'SRID=4326;POINT(5 23)'``
|
---|
433 | HEX ``str`` / ``unicode`` ``'010100000000000000000014400000000000003740'``
|
---|
434 | HEXEWKB ``str`` / ``unicode`` ``''0101000020E610000000000000000014400000000000003740'``
|
---|
435 | GeoJSON ``str`` / ``unicode`` ``'{ "type": "Point", "coordinates": [ 5.000000, 23.000000 ] }'``
|
---|
436 | WKB ``buffer`` ``buffer('\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x14@\x00\x00\x00\x00\x00\x007@')``
|
---|
437 | ============ ====================== =========================================================================================
|
---|
438 |
|
---|
439 | While this may seem like an acronym soup, all are standardized geospatial data
|
---|
440 | formats or extensions thereof.
|
---|
441 |
|
---|
442 | The ``srid`` keyword may be used to set the spatial reference system
|
---|
443 | identifier number for the geometry. This will be used to conduct any needed
|
---|
444 | transformations for spatial lookups and geographic model creation.
|
---|
445 |
|
---|
446 | .. method:: fromfile(file_h)
|
---|
447 |
|
---|
448 | This factory creates a GEOS geometry from the given file name or an open
|
---|
449 | file handle (1.1 only)::
|
---|
450 |
|
---|
451 | >>> from django.contrib.gis.geos import fromfile
|
---|
452 | >>> g = fromfile('/home/bob/geom.wkt')
|
---|
453 |
|
---|
454 | .. method:: fromstr(string)
|
---|
455 |
|
---|
456 | GEOS geometry objects may be created from strings using the ``fromstr()``
|
---|
457 | factory, or using the constructor for each geometry object (as described
|
---|
458 | above)::
|
---|
459 |
|
---|
460 | >>> from django.contrib.gis.geos import fromstr
|
---|
461 | >>> pnt = fromstr('POINT(-90.5 29.5)', srid=4326)
|
---|
462 |
|
---|
463 | It should be noted that ``fromstr`` is a shortcut to the constructor for the
|
---|
464 | base ``GEOSGeometry`` object.
|
---|
465 |
|
---|
466 | Geometry Properties
|
---|
467 | -------------------
|
---|
468 |
|
---|
469 | .. attribute:: empty
|
---|
470 |
|
---|
471 | Returns whether or not the set of points in the geometry is empty.
|
---|
472 |
|
---|
473 | .. attribute:: geom_type
|
---|
474 |
|
---|
475 | Returns a string corresponding to the type of geometry. For example::
|
---|
476 |
|
---|
477 | >>> pnt = GEOSGeometry('POINT(5 23)')
|
---|
478 | >>> pnt.geom_type
|
---|
479 | 'Point'
|
---|
480 |
|
---|
481 | .. attribute:: geom_typeid
|
---|
482 |
|
---|
483 | Returns the GEOS geometry type identification number. The following table
|
---|
484 | shows the value for each geometry type:
|
---|
485 |
|
---|
486 | ====================== ========
|
---|
487 | Geometry ID
|
---|
488 | ====================== ========
|
---|
489 | ``Point`` 0
|
---|
490 | ``LineString`` 1
|
---|
491 | ``LinearRing`` 2
|
---|
492 | ``Polygon`` 3
|
---|
493 | ``MultiPoint`` 4
|
---|
494 | ``MultiLineString`` 5
|
---|
495 | ``MultiPolygon`` 6
|
---|
496 | ``GeometryCollection`` 7
|
---|
497 | ====================== ========
|
---|
498 |
|
---|
499 | .. attribute:: hasz
|
---|
500 |
|
---|
501 | Returns a boolean indicating whether the geometry is three-dimensional.
|
---|
502 |
|
---|
503 | .. attribute:: num_coords
|
---|
504 |
|
---|
505 | .. attribute:: num_points
|
---|
506 |
|
---|
507 | Returns the total number of coordinates in this geometry. For
|
---|
508 | polygons and collections, this is the cumulative number of all
|
---|
509 | coordinates from the component geometries.
|
---|
510 |
|
---|
511 | .. attribute:: ring
|
---|
512 |
|
---|
513 | Returns a boolean indicating whether the geometry is a ``LinearRing``.
|
---|
514 |
|
---|
515 | .. attribute:: simple
|
---|
516 |
|
---|
517 | A Geometry is simple if and only if the only self-intersections are at boundary
|
---|
518 | points. For example, a ``LineString`` object is not simple if it intersects
|
---|
519 | itself. Thus, ``LinearRing`` and ``Polygon`` objects are always simple because
|
---|
520 | they do not intersect themselves.
|
---|
521 |
|
---|
522 | .. attribute:: valid
|
---|
523 |
|
---|
524 | Returns a boolean indicating whether the geometry is valid.
|
---|
525 |
|
---|
526 | Output Properties
|
---|
527 | -----------------
|
---|
528 |
|
---|
529 | .. _ewkt:
|
---|
530 |
|
---|
531 | .. attribute:: ewkt
|
---|
532 |
|
---|
533 | Returns the "extended" Well-Known Text of the geometry. This representation
|
---|
534 | is specific to PostGIS and is a super set of the OGC WKT standard. [#]_
|
---|
535 | Essentially the SRID is prepended to the WKT representation, for example
|
---|
536 | ``SRID=4326;POINT(5 23)``. Please note that this does not include
|
---|
537 | the 3dm, 3dz, and 4d information that PostGIS supports in its EWKT
|
---|
538 | representations.
|
---|
539 |
|
---|
540 | .. _hex:
|
---|
541 |
|
---|
542 | .. attribute:: hex
|
---|
543 |
|
---|
544 | Returns the WKB of this Geometry in hexadecimal form. Please note
|
---|
545 | that the SRID and Z values are not included in this representation
|
---|
546 | because it is not a part of the OGC specification (use the :ref:`hexewkb`
|
---|
547 | property instead).
|
---|
548 |
|
---|
549 | .. _hexewkb:
|
---|
550 |
|
---|
551 | .. versionadded:: 1.2
|
---|
552 |
|
---|
553 | .. attribute:: hexewkb
|
---|
554 |
|
---|
555 | Returns the EWKB of this Geometry in hexadecimal form. This is an
|
---|
556 | extension of the WKB specification that includes SRID and Z values
|
---|
557 | that are a part of this geometry.
|
---|
558 |
|
---|
559 | .. note::
|
---|
560 |
|
---|
561 | GEOS 3.1 is *required* if you want valid 3D HEXEWKB.
|
---|
562 |
|
---|
563 | .. attribute:: json
|
---|
564 |
|
---|
565 | .. attribute:: geojson
|
---|
566 |
|
---|
567 | Returns the GeoJSON representation of the geometry. Requires GDAL.
|
---|
568 |
|
---|
569 | .. attribute:: kml
|
---|
570 |
|
---|
571 | Returns a `KML`__ (Keyhole Markup Language) representation of the
|
---|
572 | geometry. This should only be used for geometries with an SRID of
|
---|
573 | 4326 (WGS84), but this restriction is not enforced.
|
---|
574 |
|
---|
575 | .. attribute:: ogr
|
---|
576 |
|
---|
577 | Returns an OGR ``OGRGeometry`` object correspondg to the GEOS geometry.
|
---|
578 | Consult the `OGRGeometry`_ documentation for more information.
|
---|
579 |
|
---|
580 | .. _OGRGeometry: gdal.html#ogrgeometry
|
---|
581 |
|
---|
582 | .. note::
|
---|
583 |
|
---|
584 | Requires GDAL.
|
---|
585 |
|
---|
586 | .. _wkb:
|
---|
587 |
|
---|
588 | .. attribute:: wkb
|
---|
589 |
|
---|
590 | Returns the WKB (Well-Known Binary) representation of this Geometry
|
---|
591 | as a Python buffer. SRID and Z values are not included, use the
|
---|
592 | :ref:`ewkb` property instead.
|
---|
593 |
|
---|
594 | .. _ewkb:
|
---|
595 |
|
---|
596 | .. attribute:: ewkb
|
---|
597 |
|
---|
598 | .. versionadded:: 1.2
|
---|
599 |
|
---|
600 | Return the EWKB representation of this Geometry as a Python buffer.
|
---|
601 | This is an extension of the WKB specification that includes any SRID
|
---|
602 | and Z values that are a part of this geometry.
|
---|
603 |
|
---|
604 | .. note::
|
---|
605 |
|
---|
606 | GEOS 3.1 is *required* if you want valid 3D EWKB.
|
---|
607 |
|
---|
608 | .. attribute:: wkt
|
---|
609 |
|
---|
610 | Returns the Well-Known Text of the geometry (an OGC standard).
|
---|
611 |
|
---|
612 | __ http://code.google.com/apis/kml/documentation/
|
---|
613 |
|
---|
614 | Spatial Predicate Methods
|
---|
615 | -------------------------
|
---|
616 | All of the following spatial predicate methods take another GEOS Geometry
|
---|
617 | instance (``other``) as an argument.
|
---|
618 |
|
---|
619 | .. method:: contains(other)
|
---|
620 |
|
---|
621 | Returns True if ``within(other)`` is False.
|
---|
622 |
|
---|
623 | .. method:: crosses(other)
|
---|
624 |
|
---|
625 | Returns true if the DE-9IM intersection matrix for the two Geometries
|
---|
626 | is ``T*T******`` (for a point and a curve,a point and an area or a line
|
---|
627 | and an area) ``0********`` (for two curves).
|
---|
628 |
|
---|
629 | .. method:: disjoint(other)
|
---|
630 |
|
---|
631 | Returns true if the DE-9IM intersection matrix for the two Geometries
|
---|
632 | is ``FF*FF****``.
|
---|
633 |
|
---|
634 | .. method:: equals(other)
|
---|
635 |
|
---|
636 | Returns true if the DE-9IM intersection matrix for the two Geometries
|
---|
637 | is ``T*F**FFF*``.
|
---|
638 |
|
---|
639 | .. method:: equals_exact(other, tolerance=0)
|
---|
640 |
|
---|
641 | Returns true if the two Geometries are exactly equal, up to a
|
---|
642 | specified tolerance. The ``tolerance`` value should be a floating
|
---|
643 | point number representing the error tolerance in the comparison, e.g.,
|
---|
644 | ``poly1.equals_exact(poly2, 0.001)`` will compare equality to within
|
---|
645 | one thousandth of a unit.
|
---|
646 |
|
---|
647 | .. method:: intersects(other)
|
---|
648 |
|
---|
649 | Returns True if ``disjoint(other)`` is False.
|
---|
650 |
|
---|
651 | .. method:: overlaps(other)
|
---|
652 |
|
---|
653 | Returns true if the DE-9IM intersection matrix for the two Geometries
|
---|
654 | is ``T*T***T**`` (for two points or two surfaces) ``1*T***T**``
|
---|
655 | (for two curves).
|
---|
656 |
|
---|
657 | .. method:: relate_pattern(other, pattern)
|
---|
658 |
|
---|
659 | Returns true if the elements in the DE-9IM intersection matrix
|
---|
660 | for this geometry and the other matches the given ``pattern`` --
|
---|
661 | a string of nine characters from the alphabet: {``T``, ``F``, ``*``, ``0``}.
|
---|
662 |
|
---|
663 | .. method:: touches(other)
|
---|
664 |
|
---|
665 | Returns true if the DE-9IM intersection matrix for the two Geometries
|
---|
666 | is ``FT*******``, ``F**T*****`` or ``F***T****``.
|
---|
667 |
|
---|
668 | .. method:: within(other)
|
---|
669 |
|
---|
670 | Returns true if the DE-9IM intersection matrix for the two Geometries
|
---|
671 | is ``T*F**F***``.
|
---|
672 |
|
---|
673 | Topological Methods
|
---|
674 | -------------------
|
---|
675 |
|
---|
676 | .. method:: buffer(width, quadsegs=8)
|
---|
677 |
|
---|
678 | Returns a geometry that represents all points whose distance from this
|
---|
679 | geometry is less than or equal to the given ``width``. The optional
|
---|
680 | ``quadsegs`` keyword sets the number of segments used to approximate a
|
---|
681 | quarter circle (defaults is 8).
|
---|
682 |
|
---|
683 | .. method:: difference(other)
|
---|
684 |
|
---|
685 | Returns a geometry representing the points making up this geometry
|
---|
686 | that do not make up other.
|
---|
687 |
|
---|
688 | .. method:: intersection(other)
|
---|
689 |
|
---|
690 | Returns a geometry representing the points shared by this geometry and other.
|
---|
691 |
|
---|
692 | .. method:: relate(other)
|
---|
693 |
|
---|
694 | Returns the DE-9IM intersection matrix for this geometry and the other.
|
---|
695 |
|
---|
696 | .. method:: simplify(tolerance=0.0, preserve_topology=False)
|
---|
697 |
|
---|
698 | Returns the geometry, simplified using the Douglas-Peucker algorithm
|
---|
699 | to the specified tolerance (higher tolerance => less points). If no
|
---|
700 | tolerance provided, defaults to 0.
|
---|
701 |
|
---|
702 | By default, this function does not preserve topology - e.g. polygons can
|
---|
703 | be split, collapse to lines or disappear holes can be created or
|
---|
704 | disappear, and lines can cross. By specifying ``preserve_topology=True``,
|
---|
705 | the result will have the same dimension and number of components as the
|
---|
706 | input. This is significantly slower.
|
---|
707 |
|
---|
708 | .. method:: sym_difference(other)
|
---|
709 |
|
---|
710 | Returns a set combining the points in this geometry not in other,
|
---|
711 | and the points in other not in this geometry.
|
---|
712 |
|
---|
713 | .. method:: union(other)
|
---|
714 |
|
---|
715 | Returns a Geometry representing all the points in this Geometry and other.
|
---|
716 |
|
---|
717 | Topological Properties
|
---|
718 | ----------------------
|
---|
719 |
|
---|
720 | .. attribute:: boundary
|
---|
721 |
|
---|
722 | Returns the boundary as a newly allocated Geometry object.
|
---|
723 |
|
---|
724 | .. attribute:: centroid
|
---|
725 |
|
---|
726 | The centroid is equal to the centroid of the set of component Geometries
|
---|
727 | of highest dimension (since the lower-dimension geometries contribute zero
|
---|
728 | "weight" to the centroid).
|
---|
729 |
|
---|
730 | .. attribute:: convex_hull
|
---|
731 |
|
---|
732 | Returns the smallest convex Polygon that contains all the points in
|
---|
733 | the Geometry.
|
---|
734 |
|
---|
735 | .. attribute:: envelope
|
---|
736 |
|
---|
737 | Returns a ``Polygon`` that represents the bounding envelope of this geometry.
|
---|
738 |
|
---|
739 | .. attribute:: point_on_surface
|
---|
740 |
|
---|
741 | Computes and returns a ``Point`` guaranteed to be on the interior of this
|
---|
742 | geometry.
|
---|
743 |
|
---|
744 | Other Properties & Methods
|
---|
745 | --------------------------
|
---|
746 |
|
---|
747 | .. attribute:: extent
|
---|
748 |
|
---|
749 | This property returns the extent of this geometry as a 4-tuple,
|
---|
750 | consisting of (xmin, ymin, xmax, ymax).
|
---|
751 |
|
---|
752 | .. attribute:: area
|
---|
753 |
|
---|
754 | This property returns the area of the Geometry.
|
---|
755 |
|
---|
756 | .. method:: distance(geom)
|
---|
757 |
|
---|
758 | Returns the distance between the closest points on this Geometry and the given
|
---|
759 | ``geom`` (another ``GEOSGeometry`` object).
|
---|
760 |
|
---|
761 | .. note::
|
---|
762 |
|
---|
763 | GEOS distance calculations are linear -- in other words, GEOS will not
|
---|
764 | perform a spherical calculation even if the SRID specifies a geographic
|
---|
765 | coordinate system.
|
---|
766 |
|
---|
767 | .. attribute:: length
|
---|
768 |
|
---|
769 | Returns the length of this Geometry (e.g., 0 for point or the
|
---|
770 | circumference of a Polygo
|
---|
771 | .. attribute:: prepared
|
---|
772 |
|
---|
773 | .. versionadded:: 1.1
|
---|
774 |
|
---|
775 | .. note::
|
---|
776 |
|
---|
777 | Support for prepared geometries requires GEOS 3.1.
|
---|
778 |
|
---|
779 | Returns a GEOS ``PreparedGeometry`` for the contents of this geometry.
|
---|
780 | ``PreparedGeometry`` objects are optimized for the contains, intersects,
|
---|
781 | and covers operations. Refer to the :ref:`prepared` documentation for
|
---|
782 | more information.
|
---|
783 |
|
---|
784 | .. attribute:: srs
|
---|
785 |
|
---|
786 | Returns an OGR ``SpatialReference`` object corresponding to the SRID of the
|
---|
787 | geometry or ``None``. Consult the `SpatialReference documentation`_ for more
|
---|
788 | information about these objects.
|
---|
789 |
|
---|
790 | .. _SpatialReference documentation: gdal.html#spatialreference
|
---|
791 |
|
---|
792 | .. note::
|
---|
793 |
|
---|
794 | Requires GDAL.
|
---|
795 |
|
---|
796 | .. method:: transform(ct, clone=False)
|
---|
797 |
|
---|
798 | Transforms the geometry according to the given transformation object, which may
|
---|
799 | be an integer SRID, spatial reference WKT string, a PROJ.4 string, or a
|
---|
800 | ``SpatialReference`` object. By default, the geometry is transformed in-place and
|
---|
801 | nothing is returned. However if the `clone` keyword is set, then the geometry
|
---|
802 | is not modified and a transformed clone is returned instead.
|
---|
803 |
|
---|
804 | .. note::
|
---|
805 |
|
---|
806 | GDAL and PROJ.4 are required to perform coordinate system transformations.
|
---|
807 |
|
---|
808 | .. rubric:: Footnotes
|
---|
809 | .. [#] *See* Sean Gillies, `Geometries for Python <http://zcologia.com/news/150/geometries-for-python/>`_ (blog post explaining rationale for abandoning GEOS support); *see also* Sean's message on the `geos-devel mailing list <http://geos.refractions.net/pipermail/geos-devel/2007-March/002851.html>`_, Mar. 5, 2007
|
---|
810 | .. [#] *See generally* `Python's ctypes documentation <http://docs.python.org/lib/module-ctypes.html>`_, at Ch. 14.14.
|
---|
811 | .. [#] Specifically, ``GEOSGeometry`` was introduced in `revision 5008 <http://code.djangoproject.com/changeset/5008>`_ on April 15th, 2007.
|
---|
812 | .. [#] *See* Sean Gillies, `Geometries for Python Update <http://zcologia.com/news/429/geometries-for-python-update/>`_, April 16th 2007 ("The ctypes-based geometry module in r5008 looks kickass. I'm checking it out now.").
|
---|
813 | .. [#] Sean Gillies, `Proposal to launch the Shapely Project <http://lists.gispython.org/pipermail/community/2007-May/000953.html>`_, May 1, 2007.
|
---|
814 | .. [#] Justin Bronn, `RE: Proposal to launch the Shapely project <http://lists.gispython.org/pipermail/community/2007-May/000964.html>`_, May 1, 2007.
|
---|
815 | .. [#] Sean Gillies, `Proposal to change Shapely license from LGPL to BSD <http://lists.gispython.org/pipermail/community/2007-November/001271.html>`_, Nov. 20, 2007.
|
---|
816 | .. [#] *See* `PostGIS EWKB, EWKT and Canonical Forms <http://postgis.refractions.net/docs/ch04.html#id2591381>`_, PostGIS documentation at Ch. 4.1.2.
|
---|
817 |
|
---|