Version 2 (modified by jbronn, 17 years ago) ( diff )

filled in some documentation on Point, LineString and geometry creation

TOC()

GEOS Geometries

Background

What is GEOS?

​GEOS stands for Geometry Engine - Open Source, and is a C++ port of the ​Java Topology Suite, implementing the OpenGIS ​Simple Features for SQL spatial predicate functions and spatial operators. GEOS is developed and maintained by ​Refractions Research of Victoria, Canada.

Why the new API?

  1. The GEOS SWIG wrapper is no longer maintained, and requires the installation of SWIG.
  2. The ​PCL implementation is over 2K+ lines of C and would make PCL a requisite package for the GeoDjango application stack.
  3. Cross-platform compatibility.

Thus, the Python ctypes package was used to wrap the ​GEOS C API to bring the rich capabilities of GEOS to Python and GeoDjango.

Features:

  • A BSD licensed interface to the GEOS geometry routines, implemented purely in Python using ctypes.
  • Loosely-coupled to GeoDjango, e.g., GEOS geometry objects may be used outside a django project/application (no need have DJANGO_SETTINGS_MODULE set).
  • Mutability. GEOS Geometry objects may be modified, and memory is safely re-used when possible.
  • Cross-platform and tested. GeoDjango GEOS geometries are well-tested and compatible with Windows, Linux, Solaris, and Mac OSX platforms.

Related Work

Geometry Objects

Point

The Point object may be initialized with either a tuple, or individual parameters. For example: 

>>> from django.contrib.gis.geos import Point
>>> p = Point((5, 23)) # 2D point, passed in as a tuple
>>> p = Point(5, 23, 8) # 3D point, passed in with individual parameters

LineString

Initializes on the given sequence, for example, the constructor may take lists, tuples, NumPy arrays of X,Y[,Z] pairs, or Point objects. If Point objects are used, ownership of the points is not transferred to the LineString object. Examples: 

>>> from django.contrib.gis.geos import LineString, Point
>>> ls = LineString((1, 1), (2, 2))
>>> ls = LineString([(1, 1), (2, 2)])
>>> ls = LineString(Point(1, 1), Point(2, 2))
>>> from numpy import array
>>> ls = LineString(array([(1, 1), (2, 2)]))

LinearRing

Polygon

Geometry Collections

MultiPoint

MultiLineString

MultiPolygon

GeometryCollection

API

Creation

GEOS geometry objects may be created from strings using the fromstr() factory, or using the constructor for each geometry object (as described above). 

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

The srid keyword may be used to set the spatial reference system identifier number for the geometry. This will be used to conduct any needed transformations for spatial lookups and geographic model creation. It should be noted that fromstr is a shortcut to the constructor for the base GEOSGeometry object.

Output Properties

  • wkt: Returns the Well-Known Text of the geometry (an OGC standard).
  • hex: Returns the HEXEWKB PostGIS canonical representation of the geometry. This representation is specific to PostGIS, and is not a standard.
  • kml: Returns a KML (Keyhole Markup Language) representation of the geometry. Should only be used for geometries with an SRID of 4326 (WGS84), but this restriction is not enforced.

Spatial Predicate Properties

  • empty
  • valid
  • simple
  • ring
  • hasz

Spatial Predicate Methods

  • contains()
  • crosses()
  • disjoint()
  • equals()
  • equals_exact()
  • intersects()
  • overlaps()
  • relate_pattern()
  • within()

Topological Methods

  • buffer()
  • difference()
  • intersection()
  • relate()
  • sym_difference()
  • union()

Topological Properties

  • area
  • boundary
  • centroid
  • convex_hull
  • envelope
  • point_on_surface
Note: See TracWiki for help on using the wiki.
Back to Top