diff -r 5ff1fc726848 -r c6bca38c1cbf parts/django/docs/ref/contrib/gis/geos.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/parts/django/docs/ref/contrib/gis/geos.txt Sat Jan 08 11:20:57 2011 +0530 @@ -0,0 +1,911 @@ +.. _ref-geos: + +======== +GEOS API +======== + +.. module:: django.contrib.gis.geos + :synopsis: GeoDjango's high-level interface to the GEOS library. + +Background +========== + +What is GEOS? +------------- + +`GEOS`__ stands for **G**\ eometry **E**\ ngine - **O**\ pen **S**\ ource, +and is a C++ library, ported from the `Java Topology Suite`__. GEOS +implements the OpenGIS `Simple Features for SQL`__ spatial predicate functions +and spatial operators. GEOS, now an OSGeo project, was initially developed and +maintained by `Refractions Research`__ of Victoria, Canada. + +__ http://trac.osgeo.org/geos/ +__ http://sourceforge.net/projects/jts-topo-suite/ +__ http://www.opengeospatial.org/standards/sfs +__ http://www.refractions.net/ + +Features +-------- + +GeoDjango implements a high-level Python wrapper for the GEOS library, its +features include: + +* A BSD-licensed interface to the GEOS geometry routines, implemented purely + in Python using ``ctypes``. +* Loosely-coupled to GeoDjango. For example, :class:`GEOSGeometry` objects + may be used outside of a django project/application. In other words, + no need to have ``DJANGO_SETTINGS_MODULE`` set or use a database, etc. +* Mutability: :class:`GEOSGeometry` objects may be modified. +* Cross-platform and tested; compatible with Windows, Linux, Solaris, and Mac + OS X platforms. + +.. _geos-tutorial: + +Tutorial +======== + +This section contains a brief introduction and tutorial to using +:class:`GEOSGeometry` objects. + +Creating a Geometry +------------------- + +:class:`GEOSGeometry` objects may be created in a few ways. The first is +to simply instantiate the object on some spatial input -- the following +are examples of creating the same geometry from WKT, HEX, WKB, and GeoJSON:: + + >>> from django.contrib.gis.geos import GEOSGeometry + >>> pnt = GEOSGeometry('POINT(5 23)') # WKT + >>> pnt = GEOSGeometry('010100000000000000000014400000000000003740') # HEX + >>> pnt = GEOSGeometry(buffer('\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x14@\x00\x00\x00\x00\x00\x007@')) + >>> pnt = GEOSGeometry('{ "type": "Point", "coordinates": [ 5.000000, 23.000000 ] }') # GeoJSON + +Another option is to use the constructor for the specific geometry type +that you wish to create. For example, a :class:`Point` object may be +created by passing in the X and Y coordinates into its constructor:: + + >>> from django.contrib.gis.geos import Point + >>> pnt = Point(5, 23) + +Finally, there are :func:`fromstr` and :func:`fromfile` factory methods, which +return a :class:`GEOSGeometry` object from an input string or a file:: + + >>> from django.contrib.gis.geos import fromstr, fromfile + >>> pnt = fromstr('POINT(5 23)') + >>> pnt = fromfile('/path/to/pnt.wkt') + >>> pnt = fromfile(open('/path/to/pnt.wkt')) + +Geometries are Pythonic +----------------------- +:class:`GEOSGeometry` objects are 'Pythonic', in other words components may +be accessed, modified, and iterated over using standard Python conventions. +For example, you can iterate over the coordinates in a :class:`Point`:: + + >>> pnt = Point(5, 23) + >>> [coord for coord in pnt] + [5.0, 23.0] + +With any geometry object, the :attr:`GEOSGeometry.coords` property +may be used to get the geometry coordinates as a Python tuple:: + + >>> pnt.coords + (5.0, 23.0) + +You can get/set geometry components using standard Python indexing +techniques. However, what is returned depends on the geometry type +of the object. For example, indexing on a :class:`LineString` +returns a coordinate tuple:: + + >>> from django.contrib.gis.geos import LineString + >>> line = LineString((0, 0), (0, 50), (50, 50), (50, 0), (0, 0)) + >>> line[0] + (0.0, 0.0) + >>> line[-2] + (50.0, 0.0) + +Whereas indexing on a :class:`Polygon` will return the ring +(a :class:`LinearRing` object) corresponding to the index:: + + >>> from django.contrib.gis.geos import Polygon + >>> poly = Polygon( ((0.0, 0.0), (0.0, 50.0), (50.0, 50.0), (50.0, 0.0), (0.0, 0.0)) ) + >>> poly[0] + + >>> poly[0][-2] # second-to-last coordinate of external ring + (50.0, 0.0) + +In addition, coordinates/components of the geometry may added or modified, +just like a Python list:: + + >>> line[0] = (1.0, 1.0) + >>> line.pop() + (0.0, 0.0) + >>> line.append((1.0, 1.0)) + >>> line.coords + ((1.0, 1.0), (0.0, 50.0), (50.0, 50.0), (50.0, 0.0), (1.0, 1.0)) + +Geometry Objects +================ + +``GEOSGeometry`` +---------------- + +.. class:: GEOSGeometry(geo_input[, srid=None]) + + :param geo_input: Geometry input value + :type geo_input: string or buffer + :param srid: spatial reference identifier + :type srid: integer + +This is the base class for all GEOS geometry objects. It initializes on the +given ``geo_input`` argument, and then assumes the proper geometry subclass +(e.g., ``GEOSGeometry('POINT(1 1)')`` will create a :class:`Point` object). + +The following input formats, along with their corresponding Python types, +are accepted: + +============= ====================== +Format Input Type +============= ====================== +WKT / EWKT ``str`` or ``unicode`` +HEX / HEXEWKB ``str`` or ``unicode`` +WKB / EWKB ``buffer`` +GeoJSON ``str`` or ``unicode`` +============= ====================== + +Properties +~~~~~~~~~~ + +.. attribute:: GEOSGeometry.coords + +Returns the coordinates of the geometry as a tuple. + +.. attribute:: GEOSGeometry.empty + +Returns whether or not the set of points in the geometry is empty. + +.. attribute:: GEOSGeometry.geom_type + +Returns a string corresponding to the type of geometry. For example:: + + >>> pnt = GEOSGeometry('POINT(5 23)') + >>> pnt.geom_type + 'Point' + +.. attribute:: GEOSGeometry.geom_typeid + +Returns the GEOS geometry type identification number. The following table +shows the value for each geometry type: + +=========================== ======== +Geometry ID +=========================== ======== +:class:`Point` 0 +:class:`LineString` 1 +:class:`LinearRing` 2 +:class:`Polygon` 3 +:class:`MultiPoint` 4 +:class:`MultiLineString` 5 +:class:`MultiPolygon` 6 +:class:`GeometryCollection` 7 +=========================== ======== + +.. attribute:: GEOSGeometry.num_coords + +Returns the number of coordinates in the geometry. + +.. attribute:: GEOSGeometry.num_geom + +Returns the number of geometries in this geometry. In other words, will +return 1 on anything but geometry collections. + +.. attribute:: GEOSGeometry.hasz + +Returns a boolean indicating whether the geometry is three-dimensional. + +.. attribute:: GEOSGeometry.ring + +Returns a boolean indicating whether the geometry is a ``LinearRing``. + +.. attribute:: GEOSGeometry.simple + +Returns a boolean indicating whether the geometry is 'simple'. A geometry +is simple if and only if it does not intersect itself (except at boundary +points). For example, a :class:`LineString` object is not simple if it +intersects itself. Thus, :class:`LinearRing` and :class`Polygon` objects +are always simple because they do cannot intersect themselves, by +definition. + +.. attribute:: GEOSGeometry.valid + +Returns a boolean indicating whether the geometry is valid. + +.. attribute:: GEOSGeometry.srid + +Property that may be used to retrieve or set the SRID associated with the +geometry. For example:: + + >>> pnt = Point(5, 23) + >>> print pnt.srid + None + >>> pnt.srid = 4326 + >>> pnt.srid + 4326 + +Output Properties +~~~~~~~~~~~~~~~~~ + +The properties in this section export the :class:`GEOSGeometry` object into +a different. This output may be in the form of a string, buffer, or even +another object. + +.. attribute:: GEOSGeometry.ewkt + +Returns the "extended" Well-Known Text of the geometry. This representation +is specific to PostGIS and is a super set of the OGC WKT standard. [#fnogc]_ +Essentially the SRID is prepended to the WKT representation, for example +``SRID=4326;POINT(5 23)``. + +.. note:: + + The output from this property does not include the 3dm, 3dz, and 4d + information that PostGIS supports in its EWKT representations. + +.. attribute:: GEOSGeometry.hex + +Returns the WKB of this Geometry in hexadecimal form. Please note +that the SRID and Z values are not included in this representation +because it is not a part of the OGC specification (use the +:attr:`GEOSGeometry.hexewkb` property instead). + +.. attribute:: GEOSGeometry.hexewkb + +.. versionadded:: 1.2 + +Returns the EWKB of this Geometry in hexadecimal form. This is an +extension of the WKB specification that includes SRID and Z values +that are a part of this geometry. + +.. note:: + + GEOS 3.1 is *required* if you want valid 3D HEXEWKB. + +.. attribute:: GEOSGeometry.json + +Returns the GeoJSON representation of the geometry. + +.. note:: + + Requires GDAL. + +.. attribute:: GEOSGeometry.geojson + +Alias for :attr:`GEOSGeometry.json`. + +.. attribute:: GEOSGeometry.kml + +Returns a `KML`__ (Keyhole Markup Language) representation of the +geometry. This should only be used for geometries with an SRID of +4326 (WGS84), but this restriction is not enforced. + +.. attribute:: GEOSGeometry.ogr + +Returns an :class:`~django.contrib.gis.gdal.OGRGeometry` object +correspondg to the GEOS geometry. + +.. note:: + + Requires GDAL. + +.. _wkb: + +.. attribute:: GEOSGeometry.wkb + +Returns the WKB (Well-Known Binary) representation of this Geometry +as a Python buffer. SRID and Z values are not included, use the +:attr:`GEOSGeometry.ewkb` property instead. + +.. _ewkb: + +.. attribute:: GEOSGeometry.ewkb + +.. versionadded:: 1.2 + +Return the EWKB representation of this Geometry as a Python buffer. +This is an extension of the WKB specification that includes any SRID +and Z values that are a part of this geometry. + +.. note:: + + GEOS 3.1 is *required* if you want valid 3D EWKB. + +.. attribute:: GEOSGeometry.wkt + +Returns the Well-Known Text of the geometry (an OGC standard). + +__ http://code.google.com/apis/kml/documentation/ + +Spatial Predicate Methods +~~~~~~~~~~~~~~~~~~~~~~~~~ + +All of the following spatial predicate methods take another +:class:`GEOSGeometry` instance (``other``) as a parameter, and +return a boolean. + +.. method:: GEOSGeometry.contains(other) + +Returns ``True`` if :meth:`GEOSGeometry.within` is ``False``. + +.. method:: GEOSGeometry.crosses(other) + +Returns ``True`` if the DE-9IM intersection matrix for the two Geometries +is ``T*T******`` (for a point and a curve,a point and an area or a line +and an area) ``0********`` (for two curves). + +.. method:: GEOSGeometry.disjoint(other) + +Returns ``True`` if the DE-9IM intersection matrix for the two geometries +is ``FF*FF****``. + +.. method:: GEOSGeometry.equals(other) + +Returns ``True`` if the DE-9IM intersection matrix for the two geometries +is ``T*F**FFF*``. + +.. method:: GEOSGeometry.equals_exact(other, tolerance=0) + +Returns true if the two geometries are exactly equal, up to a +specified tolerance. The ``tolerance`` value should be a floating +point number representing the error tolerance in the comparison, e.g., +``poly1.equals_exact(poly2, 0.001)`` will compare equality to within +one thousandth of a unit. + +.. method:: GEOSGeometry.intersects(other) + +Returns ``True`` if :meth:`GEOSGeometry.disjoint` is ``False``. + +.. method:: GEOSGeometry.overlaps(other) + +Returns true if the DE-9IM intersection matrix for the two geometries +is ``T*T***T**`` (for two points or two surfaces) ``1*T***T**`` +(for two curves). + +.. method:: GEOSGeometry.relate_pattern(other, pattern) + +Returns ``True`` if the elements in the DE-9IM intersection matrix +for this geometry and the other matches the given ``pattern`` -- +a string of nine characters from the alphabet: {``T``, ``F``, ``*``, ``0``}. + +.. method:: GEOSGeometry.touches(other) + +Returns ``True`` if the DE-9IM intersection matrix for the two geometries +is ``FT*******``, ``F**T*****`` or ``F***T****``. + +.. method:: GEOSGeometry.within(other) + +Returns ``True`` if the DE-9IM intersection matrix for the two geometries +is ``T*F**F***``. + +Topological Methods +~~~~~~~~~~~~~~~~~~~ + +.. method:: GEOSGeometry.buffer(width, quadsegs=8) + +Returns a :class:`GEOSGeometry` that represents all points whose distance +from this geometry is less than or equal to the given ``width``. The optional +``quadsegs`` keyword sets the number of segments used to approximate a +quarter circle (defaults is 8). + +.. method:: GEOSGeometry.difference(other) + +Returns a :class:`GEOSGeometry` representing the points making up this +geometry that do not make up other. + +.. method:: GEOSGeometry:intersection(other) + +Returns a :class:`GEOSGeometry` representing the points shared by this +geometry and other. + +.. method:: GEOSGeometry.relate(other) + +Returns the DE-9IM intersection matrix (a string) representing the +topological relationship between this geometry and the other. + +.. method:: GEOSGeometry.simplify(tolerance=0.0, preserve_topology=False) + +Returns a new :class:`GEOSGeometry`, simplified using the Douglas-Peucker +algorithm to the specified tolerance. A higher tolerance value implies +less points in the output. If no tolerance is tolerance provided, +it defaults to 0. + +By default, this function does not preserve topology - e.g., +:class:`Polygon` objects can be split, collapsed into lines or disappear. +:class:`Polygon` holes can be created or disappear, and lines can cross. +By specifying ``preserve_topology=True``, the result will have the same +dimension and number of components as the input, however, this is +significantly slower. + +.. method:: GEOSGeometry.sym_difference(other) + +Returns a :class:`GEOSGeometry` combining the points in this geometry +not in other, and the points in other not in this geometry. + +.. method:: GEOSGeometry.union(other) + +Returns a :class:`GEOSGeometry` representing all the points in this +geometry and the other. + +Topological Properties +~~~~~~~~~~~~~~~~~~~~~~ + +.. attribute:: GEOSGeometry.boundary + +Returns the boundary as a newly allocated Geometry object. + +.. attribute:: GEOSGeometry.centroid + +Returns a :class:`Point` object representing the geometric center of +the geometry. The point is not guaranteed to be on the interior +of the geometry. + +.. attribute:: GEOSGeometry.convex_hull + +Returns the smallest :class:`Polygon` that contains all the points in +the geometry. + +.. attribute:: GEOSGeometry.envelope + +Returns a :class:`Polygon` that represents the bounding envelope of +this geometry. + +.. attribute:: GEOSGeometry.point_on_surface + +Computes and returns a :class:`Point` guaranteed to be on the interior +of this geometry. + +Other Properties & Methods +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. attribute:: GEOSGeometry.area + +This property returns the area of the Geometry. + +.. attribute:: GEOSGeometry.extent + +This property returns the extent of this geometry as a 4-tuple, +consisting of (xmin, ymin, xmax, ymax). + +.. method:: GEOSGeometry.clone() + +This method returns a :class:`GEOSGeometry` that is a clone of the original. + +.. method:: GEOSGeometry.distance(geom) + +Returns the distance between the closest points on this geometry and the given +``geom`` (another :class:`GEOSGeometry` object). + +.. note:: + + GEOS distance calculations are linear -- in other words, GEOS does not + perform a spherical calculation even if the SRID specifies a geographic + coordinate system. + +.. attribute:: GEOSGeometry.length + +Returns the length of this geometry (e.g., 0 for a :class:`Point`, +the length of a :class:`LineString`, or the circumference of +a :class:`Polygon`). + +.. attribute:: GEOSGeometry.prepared + +.. versionadded:: 1.1 + +.. note:: + + Support for prepared geometries requires GEOS 3.1. + +Returns a GEOS ``PreparedGeometry`` for the contents of this geometry. +``PreparedGeometry`` objects are optimized for the contains, intersects, +and covers operations. Refer to the :ref:`prepared-geometries` documentation +for more information. + +.. attribute:: GEOSGeometry.srs + +Returns a :class:`~django.contrib.gis.gdal.SpatialReference` object +corresponding to the SRID of the geometry or ``None``. + +.. note:: + + Requires GDAL. + +.. method:: transform(ct, clone=False) + +Transforms the geometry according to the given coordinate transformation paramter +(``ct``), which may be an integer SRID, spatial reference WKT string, +a PROJ.4 string, a :class:`~django.contrib.gis.gdal.SpatialReference` object, or a +:class:`~django.contrib.gis.gdal.CoordTransform` object. By default, the geometry +is transformed in-place and nothing is returned. However if the ``clone`` keyword +is set, then the geometry is not modified and a transformed clone of the geometry +is returned instead. + +.. note:: + + Requires GDAL. + +``Point`` +--------- + +.. class:: Point(x, y, z=None, srid=None) + + ``Point`` objects are instantiated using arguments that represent + the component coordinates of the point or with a single sequence + coordinates. For example, the following are equivalent:: + + >>> pnt = Point(5, 23) + >>> pnt = Point([5, 23]) + +``LineString`` +-------------- + +.. class:: LineString(*args, **kwargs) + + ``LineString`` objects are instantiated using arguments that are + either a sequence of coordinates or :class:`Point` objects. + For example, the following are equivalent:: + + >>> ls = LineString((0, 0), (1, 1)) + >>> ls = LineString(Point(0, 0), Point(1, 1)) + + In addition, ``LineString`` objects may also be created by passing + in a single sequence of coordinate or :class:`Point` objects:: + + >>> ls = LineString( ((0, 0), (1, 1)) ) + >>> ls = LineString( [Point(0, 0), Point(1, 1)] ) + +``LinearRing`` +-------------- + +.. class:: LinearRing(*args, **kwargs) + + ``LinearRing`` objects are constructed in the exact same way as + :class:`LineString` objects, however the coordinates must be + *closed*, in other words, the first coordinates must be the + same as the last coordinates. For example:: + + >>> ls = LinearRing((0, 0), (0, 1), (1, 1), (0, 0)) + + Notice that ``(0, 0)`` is the first and last coordinate -- if + they were not equal, an error would be raised. + +``Polygon`` +----------- + +.. class:: Polygon(*args, **kwargs) + + ``Polygon`` objects may be instantiated by passing in one or + more parameters that represent the rings of the polygon. The + parameters must either be :class:`LinearRing` instances, or + a sequence that may be used to construct a :class:`LinearRing`:: + + >>> ext_coords = ((0, 0), (0, 1), (1, 1), (1, 0), (0, 0)) + >>> int_coords = ((0.4, 0.4), (0.4, 0.6), (0.6, 0.6), (0.6, 0.4), (0.4, 0.4)) + >>> poly = Polygon(ext_coords, int_coords) + >>> poly = Polygon(LinearRing(ext_coords), LinearRing(int_coords)) + + .. classmethod:: from_bbox(bbox) + + .. versionadded:: 1.1 + + Returns a polygon object from the given bounding-box, a 4-tuple + comprising (xmin, ymin, xmax, ymax). + + .. attribute:: num_interior_rings + + Returns the number of interior rings in this geometry. + +Geometry Collections +==================== + +``MultiPoint`` +-------------- + +.. class:: MultiPoint(*args, **kwargs) + + ``MultiPoint`` objects may be instantiated by passing in one + or more :class:`Point` objects as arguments, or a single + sequence of :class:`Point` objects:: + + >>> mp = MultiPoint(Point(0, 0), Point(1, 1)) + >>> mp = MultiPoint( (Point(0, 0), Point(1, 1)) ) + +``MultiLineString`` +------------------- + +.. class:: MultiLineString(*args, **kwargs) + + ``MultiLineString`` objects may be instantiated by passing in one + or more :class:`LineString` objects as arguments, or a single + sequence of :class:`LineString` objects:: + + >>> ls1 = LineString((0, 0), (1, 1)) + >>> ls2 = LineString((2, 2), (3, 3)) + >>> mls = MultiLineString(ls1, ls2) + >>> mls = MultiLineString([ls1, ls2]) + + .. attribute:: merged + + .. versionadded:: 1.1 + + Returns a :class:`LineString` representing the line merge of + all the components in this ``MultiLineString``. + + +``MultiPolygon`` +---------------- + +.. class:: MultiPolygon(*args, **kwargs) + + ``MultiPolygon`` objects may be instantiated by passing one or + more :class:`Polygon` objects as arguments, or a single sequence + of :class:`Polygon` objects:: + + >>> p1 = Polygon( ((0, 0), (0, 1), (1, 1), (0, 0)) ) + >>> p2 = Polygon( ((1, 1), (1, 2), (2, 2), (1, 1)) ) + >>> mp = MultiPolygon(p1, p2) + >>> mp = MultiPolygon([p1, p2]) + + .. attribute:: cascaded_union + + .. versionadded:: 1.1 + + Returns a :class:`Polygon` that is the union of all of the component + polygons in this collection. The algorithm employed is significantly + more efficient (faster) than trying to union the geometries together + individually. [#fncascadedunion]_ + + .. note:: + + GEOS 3.1 is *required* to peform cascaded unions. + +``GeometryCollection`` +---------------------- + +.. class:: GeometryCollection(*args, **kwargs) + + ``GeometryCollection`` objects may be instantiated by passing in + one or more other :class:`GEOSGeometry` as arguments, or a single + sequence of :class:`GEOSGeometry` objects:: + + >>> poly = Polygon( ((0, 0), (0, 1), (1, 1), (0, 0)) ) + >>> gc = GeometryCollection(Point(0, 0), MultiPoint(Point(0, 0), Point(1, 1)), poly) + >>> gc = GeometryCollection((Point(0, 0), MultiPoint(Point(0, 0), Point(1, 1)), poly)) + +.. _prepared-geometries: + +Prepared Geometries +=================== + +.. versionadded: 1.1 + +In order to obtain a prepared geometry, just access the +:attr:`GEOSGeometry.prepared` property. Once you have a +``PreparedGeometry`` instance its spatial predicate methods, listed below, +may be used with other ``GEOSGeometry`` objects. An operation with a prepared +geometry can be orders of magnitude faster -- the more complex the geometry +that is prepared, the larger the speedup in the operation. For more information, +please consult the `GEOS wiki page on prepared geometries `_. + +.. note:: + + GEOS 3.1 is *required* in order to use prepared geometries. + +For example:: + + >>> from django.contrib.gis.geos import Point, Polygon + >>> poly = Polygon.from_bbox((0, 0, 5, 5)) + >>> prep_poly = poly.prepared + >>> prep_poly.contains(Point(2.5, 2.5)) + True + +``PreparedGeometry`` +-------------------- + +.. class:: PreparedGeometry + + All methods on ``PreparedGeometry`` take an ``other`` argument, which + must be a :class:`GEOSGeometry` instance. + + .. method:: contains(other) + + .. method:: contains_properly(other) + + .. method:: covers(other) + + .. method:: intersects(other) + +Geometry Factories +================== + +.. function:: fromfile(file_h) + + :param file_h: input file that contains spatial data + :type file_h: a Python ``file`` object or a string path to the file + :rtype: a :class:`GEOSGeometry` corresponding to the spatial data in the file + +Example:: + + >>> from django.contrib.gis.geos import fromfile + >>> g = fromfile('/home/bob/geom.wkt') + +.. function:: fromstr(string, [,srid=None]) + + :param string: string that contains spatial data + :type string: string + :param srid: spatial reference identifier + :type srid: integer + :rtype: a :class:`GEOSGeometry` corresponding to the spatial data in the string + +Example:: + + >>> from django.contrib.gis.geos import fromstr + >>> pnt = fromstr('POINT(-90.5 29.5)', srid=4326) + +I/O Objects +=========== + +.. versionadded: 1.1 + +Reader Objects +-------------- + +The reader I/O classes simply return a :class:`GEOSGeometry` instance from the +WKB and/or WKT input given to their ``read(geom)`` method. + +.. class:: WKBReader + +Example:: + + >>> from django.contrib.gis.geos import WKBReader + >>> wkb_r = WKBReader() + >>> wkb_r.read('0101000000000000000000F03F000000000000F03F') + + +.. class:: WKTReader + +Example:: + + >>> from django.contrib.gis.geos import WKTReader + >>> wkt_r = WKTReader() + >>> wkt_r.read('POINT(1 1)') + + +Writer Objects +-------------- + +All writer objects have a ``write(geom)`` method that returns either the +WKB or WKT of the given geometry. In addition, :class:`WKBWriter` objects +also have properties that may be used to change the byte order, and or +include the SRID and 3D values (in other words, EWKB). + +.. class:: WKBWriter + +``WKBWriter`` provides the most control over its output. By default it +returns OGC-compliant WKB when it's ``write`` method is called. However, +it has properties that allow for the creation of EWKB, a superset of the +WKB standard that includes additional information. + +.. method:: WKBWriter.write(geom) + +Returns the WKB of the given geometry as a Python ``buffer`` object. +Example:: + + >>> from django.contrib.gis.geos import Point, WKBWriter + >>> pnt = Point(1, 1) + >>> wkb_w = WKBWriter() + >>> wkb_w.write(pnt) + + +.. method:: WKBWriter.write_hex(geom) + +Returns WKB of the geometry in hexadecimal. Example:: + + >>> from django.contrib.gis.geos import Point, WKBWriter + >>> pnt = Point(1, 1) + >>> wkb_w = WKBWriter() + >>> wkb_w.write_hex(pnt) + '0101000000000000000000F03F000000000000F03F' + +.. attribute:: WKBWriter.byteorder + +This property may be be set to change the byte-order of the geometry +representation. + +=============== ================================================= +Byteorder Value Description +=============== ================================================= +0 Big Endian (e.g., compatible with RISC systems) +1 Little Endian (e.g., compatible with x86 systems) +=============== ================================================= + +Example:: + + >>> from django.contrib.gis.geos import Point, WKBWriter + >>> wkb_w = WKBWriter() + >>> pnt = Point(1, 1) + >>> wkb_w.write_hex(pnt) + '0101000000000000000000F03F000000000000F03F' + >>> wkb_w.byteorder = 0 + '00000000013FF00000000000003FF0000000000000' + +.. attribute:: WKBWriter.outdim + +This property may be set to change the output dimension of the geometry +representation. In other words, if you have a 3D geometry then set to 3 +so that the Z value is included in the WKB. + +============ =========================== +Outdim Value Description +============ =========================== +2 The default, output 2D WKB. +3 Output 3D EWKB. +============ =========================== + +Example:: + + >>> from django.contrib.gis.geos import Point, WKBWriter + >>> wkb_w = WKBWriter() + >>> wkb_w.outdim + 2 + >>> pnt = Point(1, 1, 1) + >>> wkb_w.write_hex(pnt) # By default, no Z value included: + '0101000000000000000000F03F000000000000F03F' + >>> wkb_w.outdim = 3 # Tell writer to include Z values + >>> wkb_w.write_hex(pnt) + '0101000080000000000000F03F000000000000F03F000000000000F03F' + +.. attribute:: WKBWriter.srid + +Set this property with a boolean to indicate whether the SRID of the +geometry should be included with the WKB representation. Example:: + + >>> from django.contrib.gis.geos import Point, WKBWriter + >>> wkb_w = WKBWriter() + >>> pnt = Point(1, 1, srid=4326) + >>> wkb_w.write_hex(pnt) # By default, no SRID included: + '0101000000000000000000F03F000000000000F03F' + >>> wkb_w.srid = True # Tell writer to include SRID + >>> wkb_w.write_hex(pnt) + '0101000020E6100000000000000000F03F000000000000F03F' + +.. class:: WKTWriter + +.. method:: WKTWriter.write(geom) + +Returns the WKT of the given geometry. Example:: + + >>> from django.contrib.gis.geos import Point, WKTWriter + >>> pnt = Point(1, 1) + >>> wkt_w = WKTWriter() + >>> wkt_w.write(pnt) + 'POINT (1.0000000000000000 1.0000000000000000)' + + +.. rubric:: Footnotes +.. [#fnogc] *See* `PostGIS EWKB, EWKT and Canonical Forms `_, PostGIS documentation at Ch. 4.1.2. +.. [#fncascadedunion] For more information, read Paul Ramsey's blog post about `(Much) Faster Unions in PostGIS 1.4 `_ and Martin Davis' blog post on `Fast polygon merging in JTS using Cascaded Union `_. + +Settings +======== + +.. setting:: GEOS_LIBRARY_PATH + +GEOS_LIBRARY_PATH +----------------- + +A string specifying the location of the GEOS C library. Typically, +this setting is only used if the GEOS C library is in a non-standard +location (e.g., ``/home/bob/lib/libgeos_c.so``). + +.. note:: + + The setting must be the *full* path to the **C** shared library; in + other words you want to use ``libgeos_c.so``, not ``libgeos.so``.