Code

Changes between Version 2 and Version 3 of GEOSGeometry


Ignore:
Timestamp:
08/15/07 18:41:56 (7 years ago)
Author:
jbronn
Comment:

filled out more documentation and added images of geometry objects

Legend:

Unmodified
Added
Removed
Modified
  • GEOSGeometry

    v2 v3  
    1717 
    1818''Features'': 
    19  * A BSD licensed interface to the GEOS geometry routines, implemented purely in Python using {{{ctypes}}}. 
    20  * Loosely-coupled to !GeoDjango, ''e.g.'', GEOS geometry objects may be used outside a django project/application (no need have {{{DJANGO_SETTINGS_MODULE}}} set). 
     19 * A BSD-licensed interface to the GEOS geometry routines, implemented purely in Python using {{{ctypes}}}. 
     20 * Loosely-coupled to !GeoDjango, ''e.g.'', GEOS geometry objects may be used outside a django project/application (no need to have {{{DJANGO_SETTINGS_MODULE}}} set). 
    2121 * Mutability.  GEOS Geometry objects may be modified, and memory is safely re-used when possible. 
    2222 * Cross-platform and tested.  !GeoDjango GEOS geometries are well-tested and compatible with Windows, Linux, Solaris, and Mac OSX platforms. 
    2323 
    2424=== Related Work === 
     25Upon learning of the GEOS Geometry work in GeoDjango in May, 2007, Sean Gillies began implementation of PCL's {{{ctypes}}} interface to GEOS, called [http://trac.gispython.org/projects/PCL/wiki/ShapeLy ShapeLy].  !ShapeLy is still evolving, ''e.g.'', it lacks support for the full GEOS API, mutable geometries, and fully-functional constructors for Polygons and !GeometryCollections.  However, the PCL team is implementing exciting features including a geometry interface (similar to NumPy's [http://numpy.scipy.org/array_interface.shtml array interface]) and excellent GeoJSON support. 
     26 
     27Because !ShapeLy is licensed under the LGPL, I (Justin Bronn) declined to merge the projects.  ''See'' [http://lists.gispython.org/pipermail/community/2007-May/000964.html Proposal to launch the Shapely project], GISPython.com mailing list. 
    2528 
    2629== Geometry Objects == 
    2730 
     31'''Note:''' The images shown below are courtesy of the [http://www.jump-project.org/project.php?PID=JTS&SID=OVER Java Topology Suite (JTS) webpage], Copyright (C) 2003, [http://www.jump-project.org/ The JUMP-Project . Org].   
     32 
    2833=== Point === 
    2934 
    30 The Point object may be initialized with either a tuple, or individual parameters.  For example: 
     35{{{ 
     36#!html 
     37<img src="http://www.jump-project.org/inc/JTS/img/GeometryPoint.gif"> 
     38}}} 
     39 
     40The {{{Point}}} object may be initialized with either a tuple, or individual parameters.  For example: 
    3141{{{ 
    3242#!python 
     
    3848=== !LineString === 
    3949 
    40 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: 
     50{{{ 
     51#!html 
     52<img src="http://www.jump-project.org/inc/JTS/img/GeometryLineString.gif"> 
     53}}} 
     54 
     55{{{LineString}}} objects initialize on a given sequence.  For example, the constructor may take lists, tuples, [http://numpy.scipy.org/ 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: 
    4156 
    4257{{{ 
     
    5166 
    5267=== !LinearRing === 
     68{{{ 
     69#!html 
     70<img src="http://www.jump-project.org/inc/JTS/img/GeometryLinearRing.gif"> 
     71}}} 
     72 
     73{{{LinearRing}}} objects are subclasses of {{{LineString}}} objects, however, an error will be thrown if the points used during initialization do not form a closed linestring. 
     74 
     75{{{ 
     76#!python 
     77>>> from django.contrib.gis.geos import LinearRing 
     78>>> lr = LinearRing((0, 0), (0, 1), (1, 1), (1, 0), (0, 0)) 
     79>>> lr = LinearRing((0, 0), (0, 1)) 
     80GEOS_ERROR: IllegalArgumentException: points must form a closed linestring 
     81... 
     82}}} 
    5383 
    5484=== Polygon === 
     85 
     86{{{ 
     87#!html 
     88<img src="http://www.jump-project.org/inc/JTS/img/GeometryPolygon.bmp"> 
     89}}} 
    5590 
    5691== Geometry Collections == 
     
    77112 
    78113=== Output Properties === 
    79  * {{{wkt}}}: Returns the Well-Known Text of the geometry (an OGC standard). 
    80  * {{{hex}}}: Returns the HEXEWKB PostGIS canonical representation of the geometry.  This representation is specific to PostGIS, and is not a standard. 
    81  * {{{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. 
     114 * {{{wkt}}} 
     115   * Returns the Well-Known Text of the geometry (an OGC standard). 
     116 * {{{hex}}} 
     117   * Returns the HEXEWKB PostGIS canonical representation of the geometry.  This representation is specific to PostGIS, and is not a standard. 
     118 * {{{kml}}} 
     119   * Returns a [http://code.google.com/apis/kml/documentation/ 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. 
    82120 
    83121=== Spatial Predicate Properties === 
    84  * empty 
    85  * valid 
    86  * simple 
    87  * ring 
    88  * hasz 
     122 * {{{empty}}} 
     123   * Returns whether or not the set of points in the geometry is empty.  
     124 * {{{valid}}} 
     125   * Returns a boolean indicating whether the geometry is valid. 
     126 * {{{simple}}} 
     127   * A Geometry is simple if and only if the only self-intersections are at boundary points.  For example, a {{{LineString}}} object is not simple if it intersects itself (like the one pictured above). Thus, {{{LinearRing}}} and {{{Polygon}}} objects are always simple because they do not intersect themselves. 
     128 * {{{ring}}} 
     129   * Returns a boolean indicating whether the geometry is a {{{LinearRing}}}. 
     130 * {{{hasz}}} 
     131   * Returns a boolean indicating whether the geometry is three-dimensional.   
    89132 
    90133=== Spatial Predicate Methods === 
    91  * contains() 
    92  * crosses() 
    93  * disjoint() 
    94  * equals() 
    95  * equals_exact() 
    96  * intersects() 
    97  * overlaps() 
    98  * relate_pattern() 
    99  * within() 
     134All of the following spatial predicate methods take another GEOS Geometry instance as an argument (referred to below as {{{other}}}). 
     135 * {{{contains(other)}}} 
     136 * {{{crosses(other)}}} 
     137 * {{{disjoint(other)}}} 
     138 * {{{equals(other)}}} 
     139 * {{{equals_exact(other)}}} 
     140 * {{{intersects(other)}}} 
     141 * {{{overlaps(other)}}} 
     142 * {{{relate_pattern(other)}}} 
     143 * {{{within(other)}}} 
    100144 
    101145=== Topological Methods === 
    102  * buffer() 
    103  * difference() 
    104  * intersection() 
    105  * relate() 
    106  * sym_difference() 
    107  * union() 
     146 * {{{buffer()}}} 
     147 * {{{difference()}}} 
     148 * {{{intersection()}}} 
     149 * {{{relate()}}} 
     150 * {{{sym_difference()}}} 
     151 * {{{union()}}} 
    108152 
    109153=== Topological Properties === 
    110  * area 
    111  * boundary 
    112  * centroid 
    113  * convex_hull 
    114  * envelope 
    115  * point_on_surface 
     154 * {{{area}}} 
     155 * {{{boundary}}} 
     156 * {{{centroid}}} 
     157 * {{{convex_hull}}} 
     158 * {{{envelope}}} 
     159 * {{{point_on_surface}}}