1
0
mirror of https://github.com/django/django.git synced 2025-06-07 04:29:12 +00:00

Updated indentation in GEOS docs

This commit is contained in:
Claude Paroz 2016-04-16 19:49:10 +02:00
parent 10c53385f8
commit 6c9603277d

View File

@ -203,26 +203,26 @@ Properties
.. attribute:: GEOSGeometry.coords .. attribute:: GEOSGeometry.coords
Returns the coordinates of the geometry as a tuple. Returns the coordinates of the geometry as a tuple.
.. attribute:: GEOSGeometry.dims .. attribute:: GEOSGeometry.dims
Returns the dimension of the geometry: Returns the dimension of the geometry:
* ``0`` for :class:`Point`\s and :class:`MultiPoint`\s * ``0`` for :class:`Point`\s and :class:`MultiPoint`\s
* ``1`` for :class:`LineString`\s and :class:`MultiLineString`\s * ``1`` for :class:`LineString`\s and :class:`MultiLineString`\s
* ``2`` for :class:`Polygon`\s and :class:`MultiPolygon`\s * ``2`` for :class:`Polygon`\s and :class:`MultiPolygon`\s
* ``-1`` for empty :class:`GeometryCollection`\s * ``-1`` for empty :class:`GeometryCollection`\s
* the maximum dimension of its elements for non-empty * the maximum dimension of its elements for non-empty
:class:`GeometryCollection`\s :class:`GeometryCollection`\s
.. attribute:: GEOSGeometry.empty .. attribute:: GEOSGeometry.empty
Returns whether or not the set of points in the geometry is empty. Returns whether or not the set of points in the geometry is empty.
.. attribute:: GEOSGeometry.geom_type .. attribute:: GEOSGeometry.geom_type
Returns a string corresponding to the type of geometry. For example:: Returns a string corresponding to the type of geometry. For example::
>>> pnt = GEOSGeometry('POINT(5 23)') >>> pnt = GEOSGeometry('POINT(5 23)')
>>> pnt.geom_type >>> pnt.geom_type
@ -230,60 +230,60 @@ Returns a string corresponding to the type of geometry. For example::
.. attribute:: GEOSGeometry.geom_typeid .. attribute:: GEOSGeometry.geom_typeid
Returns the GEOS geometry type identification number. The following table Returns the GEOS geometry type identification number. The following table
shows the value for each geometry type: shows the value for each geometry type:
=========================== ======== =========================== ========
Geometry ID Geometry ID
=========================== ======== =========================== ========
:class:`Point` 0 :class:`Point` 0
:class:`LineString` 1 :class:`LineString` 1
:class:`LinearRing` 2 :class:`LinearRing` 2
:class:`Polygon` 3 :class:`Polygon` 3
:class:`MultiPoint` 4 :class:`MultiPoint` 4
:class:`MultiLineString` 5 :class:`MultiLineString` 5
:class:`MultiPolygon` 6 :class:`MultiPolygon` 6
:class:`GeometryCollection` 7 :class:`GeometryCollection` 7
=========================== ======== =========================== ========
.. attribute:: GEOSGeometry.num_coords .. attribute:: GEOSGeometry.num_coords
Returns the number of coordinates in the geometry. Returns the number of coordinates in the geometry.
.. attribute:: GEOSGeometry.num_geom .. attribute:: GEOSGeometry.num_geom
Returns the number of geometries in this geometry. In other words, will Returns the number of geometries in this geometry. In other words, will
return 1 on anything but geometry collections. return 1 on anything but geometry collections.
.. attribute:: GEOSGeometry.hasz .. attribute:: GEOSGeometry.hasz
Returns a boolean indicating whether the geometry is three-dimensional. Returns a boolean indicating whether the geometry is three-dimensional.
.. attribute:: GEOSGeometry.ring .. attribute:: GEOSGeometry.ring
Returns a boolean indicating whether the geometry is a ``LinearRing``. Returns a boolean indicating whether the geometry is a ``LinearRing``.
.. attribute:: GEOSGeometry.simple .. attribute:: GEOSGeometry.simple
Returns a boolean indicating whether the geometry is 'simple'. A geometry 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 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 points). For example, a :class:`LineString` object is not simple if it
intersects itself. Thus, :class:`LinearRing` and :class:`Polygon` objects intersects itself. Thus, :class:`LinearRing` and :class:`Polygon` objects
are always simple because they do cannot intersect themselves, by are always simple because they do cannot intersect themselves, by
definition. definition.
.. attribute:: GEOSGeometry.valid .. attribute:: GEOSGeometry.valid
Returns a boolean indicating whether the geometry is valid. Returns a boolean indicating whether the geometry is valid.
.. attribute:: GEOSGeometry.valid_reason .. attribute:: GEOSGeometry.valid_reason
Returns a string describing the reason why a geometry is invalid. Returns a string describing the reason why a geometry is invalid.
.. attribute:: GEOSGeometry.srid .. attribute:: GEOSGeometry.srid
Property that may be used to retrieve or set the SRID associated with the Property that may be used to retrieve or set the SRID associated with the
geometry. For example:: geometry. For example::
>>> pnt = Point(5, 23) >>> pnt = Point(5, 23)
>>> print(pnt.srid) >>> print(pnt.srid)
@ -301,51 +301,51 @@ another object.
.. attribute:: GEOSGeometry.ewkt .. attribute:: GEOSGeometry.ewkt
Returns the "extended" Well-Known Text of the geometry. This representation Returns the "extended" Well-Known Text of the geometry. This representation
is specific to PostGIS and is a superset of the OGC WKT standard. [#fnogc]_ is specific to PostGIS and is a superset of the OGC WKT standard. [#fnogc]_
Essentially the SRID is prepended to the WKT representation, for example Essentially the SRID is prepended to the WKT representation, for example
``SRID=4326;POINT(5 23)``. ``SRID=4326;POINT(5 23)``.
.. note:: .. note::
The output from this property does not include the 3dm, 3dz, and 4d The output from this property does not include the 3dm, 3dz, and 4d
information that PostGIS supports in its EWKT representations. information that PostGIS supports in its EWKT representations.
.. attribute:: GEOSGeometry.hex .. attribute:: GEOSGeometry.hex
Returns the WKB of this Geometry in hexadecimal form. Please note Returns the WKB of this Geometry in hexadecimal form. Please note
that the SRID value is not included in this representation that the SRID value is not included in this representation
because it is not a part of the OGC specification (use the because it is not a part of the OGC specification (use the
:attr:`GEOSGeometry.hexewkb` property instead). :attr:`GEOSGeometry.hexewkb` property instead).
.. attribute:: GEOSGeometry.hexewkb .. attribute:: GEOSGeometry.hexewkb
Returns the EWKB of this Geometry in hexadecimal form. This is an Returns the EWKB of this Geometry in hexadecimal form. This is an
extension of the WKB specification that includes the SRID value extension of the WKB specification that includes the SRID value
that are a part of this geometry. that are a part of this geometry.
.. attribute:: GEOSGeometry.json .. attribute:: GEOSGeometry.json
Returns the GeoJSON representation of the geometry. Note that the result is not Returns the GeoJSON representation of the geometry. Note that the result is
a complete GeoJSON structure but only the ``geometry`` key content of a not a complete GeoJSON structure but only the ``geometry`` key content of a
GeoJSON structure. See also :doc:`/ref/contrib/gis/serializers`. GeoJSON structure. See also :doc:`/ref/contrib/gis/serializers`.
.. attribute:: GEOSGeometry.geojson .. attribute:: GEOSGeometry.geojson
Alias for :attr:`GEOSGeometry.json`. Alias for :attr:`GEOSGeometry.json`.
.. attribute:: GEOSGeometry.kml .. attribute:: GEOSGeometry.kml
Returns a `KML`__ (Keyhole Markup Language) representation of the Returns a `KML`__ (Keyhole Markup Language) representation of the
geometry. This should only be used for geometries with an SRID of geometry. This should only be used for geometries with an SRID of
4326 (WGS84), but this restriction is not enforced. 4326 (WGS84), but this restriction is not enforced.
.. attribute:: GEOSGeometry.ogr .. attribute:: GEOSGeometry.ogr
Returns an :class:`~django.contrib.gis.gdal.OGRGeometry` object Returns an :class:`~django.contrib.gis.gdal.OGRGeometry` object
corresponding to the GEOS geometry. corresponding to the GEOS geometry.
.. note:: .. note::
Requires GDAL. Requires GDAL.
@ -353,21 +353,21 @@ corresponding to the GEOS geometry.
.. attribute:: GEOSGeometry.wkb .. attribute:: GEOSGeometry.wkb
Returns the WKB (Well-Known Binary) representation of this Geometry Returns the WKB (Well-Known Binary) representation of this Geometry
as a Python buffer. SRID value is not included, use the as a Python buffer. SRID value is not included, use the
:attr:`GEOSGeometry.ewkb` property instead. :attr:`GEOSGeometry.ewkb` property instead.
.. _ewkb: .. _ewkb:
.. attribute:: GEOSGeometry.ewkb .. attribute:: GEOSGeometry.ewkb
Return the EWKB representation of this Geometry as a Python buffer. Return the EWKB representation of this Geometry as a Python buffer.
This is an extension of the WKB specification that includes any SRID This is an extension of the WKB specification that includes any SRID
value that are a part of this geometry. value that are a part of this geometry.
.. attribute:: GEOSGeometry.wkt .. attribute:: GEOSGeometry.wkt
Returns the Well-Known Text of the geometry (an OGC standard). Returns the Well-Known Text of the geometry (an OGC standard).
__ https://developers.google.com/kml/documentation/ __ https://developers.google.com/kml/documentation/
@ -380,216 +380,217 @@ return a boolean.
.. method:: GEOSGeometry.contains(other) .. method:: GEOSGeometry.contains(other)
Returns ``True`` if :meth:`other.within(this) <GEOSGeometry.within>` returns Returns ``True`` if :meth:`other.within(this) <GEOSGeometry.within>` returns
``True``. ``True``.
.. method:: GEOSGeometry.covers(other) .. method:: GEOSGeometry.covers(other)
.. versionadded:: 1.10 .. versionadded:: 1.10
Returns ``True`` if this geometry covers the specified geometry. Returns ``True`` if this geometry covers the specified geometry.
The ``covers`` predicate has the following equivalent definitions: The ``covers`` predicate has the following equivalent definitions:
* Every point of the other geometry is a point of this geometry. * Every point of the other geometry is a point of this geometry.
* The DE-9IM Intersection Matrix for the two geometries is * The DE-9IM Intersection Matrix for the two geometries is
``T*****FF*``, ``*T****FF*``, ``***T**FF*``, or ``****T*FF*``. ``T*****FF*``, ``*T****FF*``, ``***T**FF*``, or ``****T*FF*``.
If either geometry is empty, returns ``False``. If either geometry is empty, returns ``False``.
This predicate is similar to :meth:`GEOSGeometry.contains`, but is more This predicate is similar to :meth:`GEOSGeometry.contains`, but is more
inclusive (i.e. returns ``True`` for more cases). In particular, unlike inclusive (i.e. returns ``True`` for more cases). In particular, unlike
:meth:`~GEOSGeometry.contains` it does not distinguish between points in the :meth:`~GEOSGeometry.contains` it does not distinguish between points in the
boundary and in the interior of geometries. For most situations, ``covers()`` boundary and in the interior of geometries. For most situations,
should be preferred to :meth:`~GEOSGeometry.contains`. As an added benefit, ``covers()`` should be preferred to :meth:`~GEOSGeometry.contains`. As an
``covers()`` is more amenable to optimization and hence should outperform added benefit, ``covers()`` is more amenable to optimization and hence
:meth:`~GEOSGeometry.contains`. should outperform :meth:`~GEOSGeometry.contains`.
.. method:: GEOSGeometry.crosses(other) .. method:: GEOSGeometry.crosses(other)
Returns ``True`` if the DE-9IM intersection matrix for the two Geometries 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 is ``T*T******`` (for a point and a curve,a point and an area or a line
and an area) ``0********`` (for two curves). and an area) ``0********`` (for two curves).
.. method:: GEOSGeometry.disjoint(other) .. method:: GEOSGeometry.disjoint(other)
Returns ``True`` if the DE-9IM intersection matrix for the two geometries Returns ``True`` if the DE-9IM intersection matrix for the two geometries
is ``FF*FF****``. is ``FF*FF****``.
.. method:: GEOSGeometry.equals(other) .. method:: GEOSGeometry.equals(other)
Returns ``True`` if the DE-9IM intersection matrix for the two geometries Returns ``True`` if the DE-9IM intersection matrix for the two geometries
is ``T*F**FFF*``. is ``T*F**FFF*``.
.. method:: GEOSGeometry.equals_exact(other, tolerance=0) .. method:: GEOSGeometry.equals_exact(other, tolerance=0)
Returns true if the two geometries are exactly equal, up to a Returns true if the two geometries are exactly equal, up to a
specified tolerance. The ``tolerance`` value should be a floating specified tolerance. The ``tolerance`` value should be a floating
point number representing the error tolerance in the comparison, e.g., point number representing the error tolerance in the comparison, e.g.,
``poly1.equals_exact(poly2, 0.001)`` will compare equality to within ``poly1.equals_exact(poly2, 0.001)`` will compare equality to within
one thousandth of a unit. one thousandth of a unit.
.. method:: GEOSGeometry.intersects(other) .. method:: GEOSGeometry.intersects(other)
Returns ``True`` if :meth:`GEOSGeometry.disjoint` is ``False``. Returns ``True`` if :meth:`GEOSGeometry.disjoint` is ``False``.
.. method:: GEOSGeometry.overlaps(other) .. method:: GEOSGeometry.overlaps(other)
Returns true if the DE-9IM intersection matrix for the two geometries 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**`` is ``T*T***T**`` (for two points or two surfaces) ``1*T***T**``
(for two curves). (for two curves).
.. method:: GEOSGeometry.relate_pattern(other, pattern) .. method:: GEOSGeometry.relate_pattern(other, pattern)
Returns ``True`` if the elements in the DE-9IM intersection matrix Returns ``True`` if the elements in the DE-9IM intersection matrix
for this geometry and the other matches the given ``pattern`` -- for this geometry and the other matches the given ``pattern`` --
a string of nine characters from the alphabet: {``T``, ``F``, ``*``, ``0``}. a string of nine characters from the alphabet: {``T``, ``F``, ``*``, ``0``}.
.. method:: GEOSGeometry.touches(other) .. method:: GEOSGeometry.touches(other)
Returns ``True`` if the DE-9IM intersection matrix for the two geometries Returns ``True`` if the DE-9IM intersection matrix for the two geometries
is ``FT*******``, ``F**T*****`` or ``F***T****``. is ``FT*******``, ``F**T*****`` or ``F***T****``.
.. method:: GEOSGeometry.within(other) .. method:: GEOSGeometry.within(other)
Returns ``True`` if the DE-9IM intersection matrix for the two geometries Returns ``True`` if the DE-9IM intersection matrix for the two geometries
is ``T*F**F***``. is ``T*F**F***``.
Topological Methods Topological Methods
~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~
.. method:: GEOSGeometry.buffer(width, quadsegs=8) .. method:: GEOSGeometry.buffer(width, quadsegs=8)
Returns a :class:`GEOSGeometry` that represents all points whose distance Returns a :class:`GEOSGeometry` that represents all points whose distance
from this geometry is less than or equal to the given ``width``. The optional from this geometry is less than or equal to the given ``width``. The
``quadsegs`` keyword sets the number of segments used to approximate a optional ``quadsegs`` keyword sets the number of segments used to
quarter circle (defaults is 8). approximate a quarter circle (defaults is 8).
.. method:: GEOSGeometry.difference(other) .. method:: GEOSGeometry.difference(other)
Returns a :class:`GEOSGeometry` representing the points making up this Returns a :class:`GEOSGeometry` representing the points making up this
geometry that do not make up other. geometry that do not make up other.
.. method:: GEOSGeometry.interpolate(distance) .. method:: GEOSGeometry.interpolate(distance)
.. method:: GEOSGeometry.interpolate_normalized(distance) .. method:: GEOSGeometry.interpolate_normalized(distance)
Given a distance (float), returns the point (or closest point) within the Given a distance (float), returns the point (or closest point) within the
geometry (:class:`LineString` or :class:`MultiLineString`) at that distance. geometry (:class:`LineString` or :class:`MultiLineString`) at that distance.
The normalized version takes the distance as a float between 0 (origin) and 1 The normalized version takes the distance as a float between 0 (origin) and
(endpoint). 1 (endpoint).
Reverse of :meth:`GEOSGeometry.project`. Reverse of :meth:`GEOSGeometry.project`.
.. method:: GEOSGeometry.intersection(other) .. method:: GEOSGeometry.intersection(other)
Returns a :class:`GEOSGeometry` representing the points shared by this Returns a :class:`GEOSGeometry` representing the points shared by this
geometry and other. geometry and other.
.. method:: GEOSGeometry.project(point) .. method:: GEOSGeometry.project(point)
.. method:: GEOSGeometry.project_normalized(point) .. method:: GEOSGeometry.project_normalized(point)
Returns the distance (float) from the origin of the geometry Returns the distance (float) from the origin of the geometry
(:class:`LineString` or :class:`MultiLineString`) to the point projected on the (:class:`LineString` or :class:`MultiLineString`) to the point projected on
geometry (that is to a point of the line the closest to the given point). the geometry (that is to a point of the line the closest to the given
The normalized version returns the distance as a float between 0 (origin) and 1 point). The normalized version returns the distance as a float between 0
(endpoint). (origin) and 1 (endpoint).
Reverse of :meth:`GEOSGeometry.interpolate`. Reverse of :meth:`GEOSGeometry.interpolate`.
.. method:: GEOSGeometry.relate(other) .. method:: GEOSGeometry.relate(other)
Returns the DE-9IM intersection matrix (a string) representing the Returns the DE-9IM intersection matrix (a string) representing the
topological relationship between this geometry and the other. topological relationship between this geometry and the other.
.. method:: GEOSGeometry.simplify(tolerance=0.0, preserve_topology=False) .. method:: GEOSGeometry.simplify(tolerance=0.0, preserve_topology=False)
Returns a new :class:`GEOSGeometry`, simplified to the specified tolerance Returns a new :class:`GEOSGeometry`, simplified to the specified tolerance
using the Douglas-Peucker algorithm. A higher tolerance value implies using the Douglas-Peucker algorithm. A higher tolerance value implies
fewer points in the output. If no tolerance is provided, it defaults to 0. fewer points in the output. If no tolerance is provided, it defaults to 0.
By default, this function does not preserve topology. For example, By default, this function does not preserve topology. For example,
:class:`Polygon` objects can be split, be collapsed into lines, or disappear. :class:`Polygon` objects can be split, be collapsed into lines, or
:class:`Polygon` holes can be created or disappear, and lines may cross. disappear. :class:`Polygon` holes can be created or disappear, and lines may
By specifying ``preserve_topology=True``, the result will have the same cross. By specifying ``preserve_topology=True``, the result will have the
dimension and number of components as the input; this is significantly same dimension and number of components as the input; this is significantly
slower, however. slower, however.
.. method:: GEOSGeometry.sym_difference(other) .. method:: GEOSGeometry.sym_difference(other)
Returns a :class:`GEOSGeometry` combining the points in this geometry Returns a :class:`GEOSGeometry` combining the points in this geometry
not in other, and the points in other not in this geometry. not in other, and the points in other not in this geometry.
.. method:: GEOSGeometry.union(other) .. method:: GEOSGeometry.union(other)
Returns a :class:`GEOSGeometry` representing all the points in this Returns a :class:`GEOSGeometry` representing all the points in this
geometry and the other. geometry and the other.
Topological Properties Topological Properties
~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~
.. attribute:: GEOSGeometry.boundary .. attribute:: GEOSGeometry.boundary
Returns the boundary as a newly allocated Geometry object. Returns the boundary as a newly allocated Geometry object.
.. attribute:: GEOSGeometry.centroid .. attribute:: GEOSGeometry.centroid
Returns a :class:`Point` object representing the geometric center of Returns a :class:`Point` object representing the geometric center of
the geometry. The point is not guaranteed to be on the interior the geometry. The point is not guaranteed to be on the interior
of the geometry. of the geometry.
.. attribute:: GEOSGeometry.convex_hull .. attribute:: GEOSGeometry.convex_hull
Returns the smallest :class:`Polygon` that contains all the points in Returns the smallest :class:`Polygon` that contains all the points in
the geometry. the geometry.
.. attribute:: GEOSGeometry.envelope .. attribute:: GEOSGeometry.envelope
Returns a :class:`Polygon` that represents the bounding envelope of Returns a :class:`Polygon` that represents the bounding envelope of
this geometry. Note that it can also return a :class:`Point` if the input this geometry. Note that it can also return a :class:`Point` if the input
geometry is a point. geometry is a point.
.. attribute:: GEOSGeometry.point_on_surface .. attribute:: GEOSGeometry.point_on_surface
Computes and returns a :class:`Point` guaranteed to be on the interior Computes and returns a :class:`Point` guaranteed to be on the interior
of this geometry. of this geometry.
.. attribute:: GEOSGeometry.unary_union .. attribute:: GEOSGeometry.unary_union
.. versionadded:: 1.10 .. versionadded:: 1.10
Computes the union of all the elements of this geometry. Computes the union of all the elements of this geometry.
The result obeys the following contract: The result obeys the following contract:
* Unioning a set of :class:`LineString`\s has the effect of fully noding and * Unioning a set of :class:`LineString`\s has the effect of fully noding and
dissolving the linework. dissolving the linework.
* Unioning a set of :class:`Polygon`\s will always return a :class:`Polygon` or * Unioning a set of :class:`Polygon`\s will always return a :class:`Polygon`
:class:`MultiPolygon` geometry (unlike :meth:`GEOSGeometry.union`, which may or :class:`MultiPolygon` geometry (unlike :meth:`GEOSGeometry.union`,
return geometries of lower dimension if a topology collapse occurs). which may return geometries of lower dimension if a topology collapse
occurs).
Other Properties & Methods Other Properties & Methods
~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~
.. attribute:: GEOSGeometry.area .. attribute:: GEOSGeometry.area
This property returns the area of the Geometry. This property returns the area of the Geometry.
.. attribute:: GEOSGeometry.extent .. attribute:: GEOSGeometry.extent
This property returns the extent of this geometry as a 4-tuple, This property returns the extent of this geometry as a 4-tuple,
consisting of ``(xmin, ymin, xmax, ymax)``. consisting of ``(xmin, ymin, xmax, ymax)``.
.. method:: GEOSGeometry.clone() .. method:: GEOSGeometry.clone()
This method returns a :class:`GEOSGeometry` that is a clone of the original. This method returns a :class:`GEOSGeometry` that is a clone of the original.
.. method:: GEOSGeometry.distance(geom) .. method:: GEOSGeometry.distance(geom)
Returns the distance between the closest points on this geometry and the given Returns the distance between the closest points on this geometry and the
``geom`` (another :class:`GEOSGeometry` object). given ``geom`` (another :class:`GEOSGeometry` object).
.. note:: .. note::
GEOS distance calculations are linear -- in other words, GEOS does not GEOS distance calculations are linear -- in other words, GEOS does not
perform a spherical calculation even if the SRID specifies a geographic perform a spherical calculation even if the SRID specifies a geographic
@ -597,47 +598,48 @@ Returns the distance between the closest points on this geometry and the given
.. attribute:: GEOSGeometry.length .. attribute:: GEOSGeometry.length
Returns the length of this geometry (e.g., 0 for a :class:`Point`, Returns the length of this geometry (e.g., 0 for a :class:`Point`,
the length of a :class:`LineString`, or the circumference of the length of a :class:`LineString`, or the circumference of
a :class:`Polygon`). a :class:`Polygon`).
.. attribute:: GEOSGeometry.prepared .. attribute:: GEOSGeometry.prepared
Returns a GEOS ``PreparedGeometry`` for the contents of this geometry. Returns a GEOS ``PreparedGeometry`` for the contents of this geometry.
``PreparedGeometry`` objects are optimized for the contains, intersects, ``PreparedGeometry`` objects are optimized for the contains, intersects,
covers, crosses, disjoint, overlaps, touches and within operations. Refer to covers, crosses, disjoint, overlaps, touches and within operations. Refer to
the :ref:`prepared-geometries` documentation for more information. the :ref:`prepared-geometries` documentation for more information.
.. attribute:: GEOSGeometry.srs .. attribute:: GEOSGeometry.srs
Returns a :class:`~django.contrib.gis.gdal.SpatialReference` object Returns a :class:`~django.contrib.gis.gdal.SpatialReference` object
corresponding to the SRID of the geometry or ``None``. corresponding to the SRID of the geometry or ``None``.
.. note:: .. note::
Requires GDAL. Requires GDAL.
.. method:: GEOSGeometry.transform(ct, clone=False) .. method:: GEOSGeometry.transform(ct, clone=False)
Transforms the geometry according to the given coordinate transformation parameter Transforms the geometry according to the given coordinate transformation
(``ct``), which may be an integer SRID, spatial reference WKT string, parameter (``ct``), which may be an integer SRID, spatial reference WKT
a PROJ.4 string, a :class:`~django.contrib.gis.gdal.SpatialReference` object, or a string, a PROJ.4 string, a
:class:`~django.contrib.gis.gdal.CoordTransform` object. By default, the geometry :class:`~django.contrib.gis.gdal.SpatialReference` object, or a
is transformed in-place and nothing is returned. However if the ``clone`` keyword :class:`~django.contrib.gis.gdal.CoordTransform` object. By default, the
is set, then the geometry is not modified and a transformed clone of the geometry geometry is transformed in-place and nothing is returned. However if the
is returned instead. ``clone`` keyword is set, then the geometry is not modified and a
transformed clone of the geometry is returned instead.
.. note:: .. note::
Requires GDAL. Raises :class:`~django.contrib.gis.geos.GEOSException` if Requires GDAL. Raises :class:`~django.contrib.gis.geos.GEOSException` if
GDAL is not available or if the geometry's SRID is ``None`` or less than 0. GDAL is not available or if the geometry's SRID is ``None`` or less than
It doesn't impose any constraints on the geometry's SRID if called with a 0. It doesn't impose any constraints on the geometry's SRID if called
:class:`~django.contrib.gis.gdal.CoordTransform` object. with a :class:`~django.contrib.gis.gdal.CoordTransform` object.
.. versionchanged:: 1.10 .. versionchanged:: 1.10
In previous versions, it required the geometry's SRID to be a positive In previous versions, it required the geometry's SRID to be a
integer even if it was called with a positive integer even if it was called with a
:class:`~django.contrib.gis.gdal.CoordTransform` object. :class:`~django.contrib.gis.gdal.CoordTransform` object.
``Point`` ``Point``
@ -901,7 +903,7 @@ Geometry Factories
:type file_h: a Python ``file`` object or a string path to the file :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 :rtype: a :class:`GEOSGeometry` corresponding to the spatial data in the file
Example:: Example::
>>> from django.contrib.gis.geos import fromfile >>> from django.contrib.gis.geos import fromfile
>>> g = fromfile('/home/bob/geom.wkt') >>> g = fromfile('/home/bob/geom.wkt')
@ -914,10 +916,10 @@ Example::
:type srid: int :type srid: int
:rtype: a :class:`GEOSGeometry` corresponding to the spatial data in the string :rtype: a :class:`GEOSGeometry` corresponding to the spatial data in the string
``fromstr(string, srid)`` is equivalent to :class:`GEOSGeometry(string, srid) ``fromstr(string, srid)`` is equivalent to
<GEOSGeometry>`. :class:`GEOSGeometry(string, srid) <GEOSGeometry>`.
Example:: Example::
>>> from django.contrib.gis.geos import fromstr >>> from django.contrib.gis.geos import fromstr
>>> pnt = fromstr('POINT(-90.5 29.5)', srid=4326) >>> pnt = fromstr('POINT(-90.5 29.5)', srid=4326)
@ -933,7 +935,7 @@ WKB and/or WKT input given to their ``read(geom)`` method.
.. class:: WKBReader .. class:: WKBReader
Example:: Example::
>>> from django.contrib.gis.geos import WKBReader >>> from django.contrib.gis.geos import WKBReader
>>> wkb_r = WKBReader() >>> wkb_r = WKBReader()
@ -942,7 +944,7 @@ Example::
.. class:: WKTReader .. class:: WKTReader
Example:: Example::
>>> from django.contrib.gis.geos import WKTReader >>> from django.contrib.gis.geos import WKTReader
>>> wkt_r = WKTReader() >>> wkt_r = WKTReader()
@ -959,21 +961,21 @@ include the SRID value (in other words, EWKB).
.. class:: WKBWriter(dim=2) .. class:: WKBWriter(dim=2)
``WKBWriter`` provides the most control over its output. By default it ``WKBWriter`` provides the most control over its output. By default it
returns OGC-compliant WKB when its ``write`` method is called. However, returns OGC-compliant WKB when its ``write`` method is called. However,
it has properties that allow for the creation of EWKB, a superset of the it has properties that allow for the creation of EWKB, a superset of the
WKB standard that includes additional information. See the WKB standard that includes additional information. See the
:attr:`WKBWriter.outdim` documentation for more details about the ``dim`` :attr:`WKBWriter.outdim` documentation for more details about the ``dim``
argument. argument.
.. versionchanged:: 1.10 .. versionchanged:: 1.10
The ability to pass the ``dim`` argument to the constructor was added. The ability to pass the ``dim`` argument to the constructor was added.
.. method:: WKBWriter.write(geom) .. method:: WKBWriter.write(geom)
Returns the WKB of the given geometry as a Python ``buffer`` object. Returns the WKB of the given geometry as a Python ``buffer`` object.
Example:: Example::
>>> from django.contrib.gis.geos import Point, WKBWriter >>> from django.contrib.gis.geos import Point, WKBWriter
>>> pnt = Point(1, 1) >>> pnt = Point(1, 1)
@ -981,9 +983,9 @@ Example::
>>> wkb_w.write(pnt) >>> wkb_w.write(pnt)
<read-only buffer for 0x103a898f0, size -1, offset 0 at 0x103a89930> <read-only buffer for 0x103a898f0, size -1, offset 0 at 0x103a89930>
.. method:: WKBWriter.write_hex(geom) .. method:: WKBWriter.write_hex(geom)
Returns WKB of the geometry in hexadecimal. Example:: Returns WKB of the geometry in hexadecimal. Example::
>>> from django.contrib.gis.geos import Point, WKBWriter >>> from django.contrib.gis.geos import Point, WKBWriter
>>> pnt = Point(1, 1) >>> pnt = Point(1, 1)
@ -991,19 +993,19 @@ Returns WKB of the geometry in hexadecimal. Example::
>>> wkb_w.write_hex(pnt) >>> wkb_w.write_hex(pnt)
'0101000000000000000000F03F000000000000F03F' '0101000000000000000000F03F000000000000F03F'
.. attribute:: WKBWriter.byteorder .. attribute:: WKBWriter.byteorder
This property may be set to change the byte-order of the geometry This property may be set to change the byte-order of the geometry
representation. representation.
=============== ================================================= =============== =================================================
Byteorder Value Description Byteorder Value Description
=============== ================================================= =============== =================================================
0 Big Endian (e.g., compatible with RISC systems) 0 Big Endian (e.g., compatible with RISC systems)
1 Little Endian (e.g., compatible with x86 systems) 1 Little Endian (e.g., compatible with x86 systems)
=============== ================================================= =============== =================================================
Example:: Example::
>>> from django.contrib.gis.geos import Point, WKBWriter >>> from django.contrib.gis.geos import Point, WKBWriter
>>> wkb_w = WKBWriter() >>> wkb_w = WKBWriter()
@ -1013,20 +1015,20 @@ Example::
>>> wkb_w.byteorder = 0 >>> wkb_w.byteorder = 0
'00000000013FF00000000000003FF0000000000000' '00000000013FF00000000000003FF0000000000000'
.. attribute:: WKBWriter.outdim .. attribute:: WKBWriter.outdim
This property may be set to change the output dimension of the geometry 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 representation. In other words, if you have a 3D geometry then set to 3
so that the Z value is included in the WKB. so that the Z value is included in the WKB.
============ =========================== ============ ===========================
Outdim Value Description Outdim Value Description
============ =========================== ============ ===========================
2 The default, output 2D WKB. 2 The default, output 2D WKB.
3 Output 3D WKB. 3 Output 3D WKB.
============ =========================== ============ ===========================
Example:: Example::
>>> from django.contrib.gis.geos import Point, WKBWriter >>> from django.contrib.gis.geos import Point, WKBWriter
>>> wkb_w = WKBWriter() >>> wkb_w = WKBWriter()
@ -1039,10 +1041,10 @@ Example::
>>> wkb_w.write_hex(pnt) >>> wkb_w.write_hex(pnt)
'0101000080000000000000F03F000000000000F03F000000000000F03F' '0101000080000000000000F03F000000000000F03F000000000000F03F'
.. attribute:: WKBWriter.srid .. attribute:: WKBWriter.srid
Set this property with a boolean to indicate whether the SRID of the Set this property with a boolean to indicate whether the SRID of the
geometry should be included with the WKB representation. Example:: geometry should be included with the WKB representation. Example::
>>> from django.contrib.gis.geos import Point, WKBWriter >>> from django.contrib.gis.geos import Point, WKBWriter
>>> wkb_w = WKBWriter() >>> wkb_w = WKBWriter()
@ -1064,9 +1066,9 @@ geometry should be included with the WKB representation. Example::
The ability to pass the ``dim``, ``trim``, and ``precision`` arguments The ability to pass the ``dim``, ``trim``, and ``precision`` arguments
to the constructor was added. to the constructor was added.
.. method:: WKTWriter.write(geom) .. method:: WKTWriter.write(geom)
Returns the WKT of the given geometry. Example:: Returns the WKT of the given geometry. Example::
>>> from django.contrib.gis.geos import Point, WKTWriter >>> from django.contrib.gis.geos import Point, WKTWriter
>>> pnt = Point(1, 1) >>> pnt = Point(1, 1)
@ -1074,16 +1076,16 @@ Returns the WKT of the given geometry. Example::
>>> wkt_w.write(pnt) >>> wkt_w.write(pnt)
'POINT (1.0000000000000000 1.0000000000000000)' 'POINT (1.0000000000000000 1.0000000000000000)'
.. attribute:: WKTWriter.outdim .. attribute:: WKTWriter.outdim
See :attr:`WKBWriter.outdim`. See :attr:`WKBWriter.outdim`.
.. attribute:: WKTWriter.trim .. attribute:: WKTWriter.trim
.. versionadded:: 1.10 .. versionadded:: 1.10
This property is used to enable or disable trimming of This property is used to enable or disable trimming of
unnecessary decimals. unnecessary decimals.
>>> from django.contrib.gis.geos import Point, WKTWriter >>> from django.contrib.gis.geos import Point, WKTWriter
>>> pnt = Point(1, 1) >>> pnt = Point(1, 1)
@ -1096,12 +1098,12 @@ unnecessary decimals.
>>> wkt_w.write(pnt) >>> wkt_w.write(pnt)
'POINT (1 1)' 'POINT (1 1)'
.. attribute:: WKTWriter.precision .. attribute:: WKTWriter.precision
.. versionadded:: 1.10 .. versionadded:: 1.10
This property controls the rounding precision of coordinates; This property controls the rounding precision of coordinates;
if set to ``None`` rounding is disabled. if set to ``None`` rounding is disabled.
>>> from django.contrib.gis.geos import Point, WKTWriter >>> from django.contrib.gis.geos import Point, WKTWriter
>>> pnt = Point(1.44, 1.66) >>> pnt = Point(1.44, 1.66)
@ -1143,4 +1145,4 @@ Exceptions
.. exception:: GEOSException .. exception:: GEOSException
The base GEOS exception, indicates a GEOS-related error. The base GEOS exception, indicates a GEOS-related error.