Changes between Version 2 and Version 3 of GEOSGeometry


Ignore:
Timestamp:
Aug 15, 2007, 8:41:56 PM (17 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}}}
Back to Top