PageRenderTime 36ms CodeModel.GetById 15ms RepoModel.GetById 0ms app.codeStats 0ms

/docs/ref/contrib/gis/model-api.txt

https://code.google.com/p/mango-py/
Plain Text | 265 lines | 193 code | 72 blank | 0 comment | 0 complexity | 81393970f45dc3a568290be0ddd051bd MD5 | raw file
Possible License(s): BSD-3-Clause
  1. .. _ref-gis-model-api:
  2. ===================
  3. GeoDjango Model API
  4. ===================
  5. .. module:: django.contrib.gis.db.models
  6. :synopsis: GeoDjango model and field API.
  7. This document explores the details of the GeoDjango Model API. Throughout this
  8. section, we'll be using the following geographic model of a `ZIP code`__ as our
  9. example::
  10. from django.contrib.gis.db import models
  11. class Zipcode(models.Model):
  12. code = models.CharField(max_length=5)
  13. poly = models.PolygonField()
  14. objects = models.GeoManager()
  15. __ http://en.wikipedia.org/wiki/ZIP_code
  16. Geometry Field Types
  17. ====================
  18. Each of the following geometry field types correspond with the
  19. OpenGIS Simple Features specification [#fnogc]_.
  20. ``GeometryField``
  21. -----------------
  22. .. class:: GeometryField
  23. ``PointField``
  24. --------------
  25. .. class:: PointField
  26. ``LineStringField``
  27. -------------------
  28. .. class:: LineStringField
  29. ``PolygonField``
  30. ----------------
  31. .. class:: PolygonField
  32. ``MultiPointField``
  33. -------------------
  34. .. class:: MultiPointField
  35. ``MultiLineStringField``
  36. ------------------------
  37. .. class:: MultiLineStringField
  38. ``MultiPolygonField``
  39. ---------------------
  40. .. class:: MultiPolygonField
  41. ``GeometryCollectionField``
  42. ---------------------------
  43. .. class:: GeometryCollectionField
  44. .. _geometry-field-options:
  45. Geometry Field Options
  46. ======================
  47. In addition to the regular :ref:`common-model-field-options` available for
  48. Django model fields, geometry fields have the following additional options.
  49. All are optional.
  50. ``srid``
  51. --------
  52. .. attribute:: GeometryField.srid
  53. Sets the SRID [#fnogcsrid]_ (Spatial Reference System Identity) of the geometry field to
  54. the given value. Defaults to 4326 (also known as `WGS84`__, units are in degrees
  55. of longitude and latitude).
  56. __ http://en.wikipedia.org/wiki/WGS84
  57. .. _selecting-an-srid:
  58. Selecting an SRID
  59. ^^^^^^^^^^^^^^^^^
  60. Choosing an appropriate SRID for your model is an important decision that the
  61. developer should consider carefully. The SRID is an integer specifier that
  62. corresponds to the projection system that will be used to interpret the data
  63. in the spatial database. [#fnsrid]_ Projection systems give the context to the
  64. coordinates that specify a location. Although the details of `geodesy`__ are
  65. beyond the scope of this documentation, the general problem is that the earth
  66. is spherical and representations of the earth (e.g., paper maps, Web maps)
  67. are not.
  68. Most people are familiar with using latitude and longitude to reference a
  69. location on the earth's surface. However, latitude and longitude are angles,
  70. not distances. [#fnharvard]_ In other words, while the shortest path between two points on
  71. a flat surface is a straight line, the shortest path between two points on a curved
  72. surface (such as the earth) is an *arc* of a `great circle`__. [#fnthematic]_ Thus,
  73. additional computation is required to obtain distances in planar units (e.g.,
  74. kilometers and miles). Using a geographic coordinate system may introduce
  75. complications for the developer later on. For example, PostGIS versions 1.4
  76. and below do not have the capability to perform distance calculations between
  77. non-point geometries using geographic coordinate systems, e.g., constructing a
  78. query to find all points within 5 miles of a county boundary stored as WGS84.
  79. [#fndist]_
  80. Portions of the earth's surface may projected onto a two-dimensional, or
  81. Cartesian, plane. Projected coordinate systems are especially convenient
  82. for region-specific applications, e.g., if you know that your database will
  83. only cover geometries in `North Kansas`__, then you may consider using projection
  84. system specific to that region. Moreover, projected coordinate systems are
  85. defined in Cartesian units (such as meters or feet), easing distance
  86. calculations.
  87. .. note::
  88. If you wish to peform arbitrary distance queries using non-point
  89. geometries in WGS84, consider upgrading to PostGIS 1.5. For
  90. better performance, enable the :attr:`GeometryField.geography`
  91. keyword so that :ref:`geography database type <geography-type>`
  92. is used instead.
  93. Additional Resources:
  94. * `spatialreference.org`__: A Django-powered database of spatial reference
  95. systems.
  96. * `The State Plane Coordinate System`__: A Web site covering the various
  97. projection systems used in the United States. Much of the U.S. spatial
  98. data encountered will be in one of these coordinate systems rather than
  99. in a geographic coordinate system such as WGS84.
  100. __ http://en.wikipedia.org/wiki/Geodesy
  101. __ http://en.wikipedia.org/wiki/Great_circle
  102. __ http://www.spatialreference.org/ref/epsg/2796/
  103. __ http://spatialreference.org/
  104. __ http://welcome.warnercnr.colostate.edu/class_info/nr502/lg3/datums_coordinates/spcs.html
  105. ``spatial_index``
  106. -----------------
  107. .. attribute:: GeometryField.spatial_index
  108. Defaults to ``True``. Creates a spatial index for the given geometry
  109. field.
  110. .. note::
  111. This is different from the ``db_index`` field option because spatial
  112. indexes are created in a different manner than regular database
  113. indexes. Specifically, spatial indexes are typically created using
  114. a variant of the R-Tree, while regular database indexes typically
  115. use B-Trees.
  116. ``dim``
  117. -------
  118. .. versionadded:: 1.2
  119. .. attribute:: GeometryField.dim
  120. This option may be used for customizing the coordinate dimension of the
  121. geometry field. By default, it is set to 2, for representing two-dimensional
  122. geometries. For spatial backends that support it, it may be set to 3 for
  123. three-dimensonal support.
  124. .. note::
  125. At this time 3D support requires that GEOS 3.1 be installed, and is
  126. limited only to the PostGIS spatial backend.
  127. ``geography``
  128. -------------
  129. .. versionadded:: 1.2
  130. .. attribute:: GeometryField.geography
  131. If set to ``True``, this option will create a database column of
  132. type geography, rather than geometry. Please refer to the
  133. :ref:`geography type <geography-type>` section below for more
  134. details.
  135. .. note::
  136. Geography support is limited only to PostGIS 1.5+, and will
  137. force the SRID to be 4326.
  138. .. _geography-type:
  139. Geography Type
  140. ^^^^^^^^^^^^^^
  141. In PostGIS 1.5, the geography type was introduced -- it provides
  142. provides native support for spatial features represented with geographic
  143. coordinates (e.g., WGS84 longitude/latitude). [#fngeography]_
  144. Unlike the plane used by a geometry type, the geography type uses a spherical
  145. representation of its data. Distance and measurement operations
  146. performed on a geography column automatically employ great circle arc
  147. calculations and return linear units. In other words, when ``ST_Distance``
  148. is called on two geographies, a value in meters is returned (as opposed
  149. to degrees if called on a geometry column in WGS84).
  150. Because geography calculations involve more mathematics, only a subset of the
  151. PostGIS spatial lookups are available for the geography type. Practically,
  152. this means that in addition to the :ref:`distance lookups <distance-lookups>`
  153. only the following additional :ref:`spatial lookups <spatial-lookups>` are
  154. available for geography columns:
  155. * :lookup:`bboverlaps`
  156. * :lookup:`coveredby`
  157. * :lookup:`covers`
  158. * :lookup:`intersects`
  159. For more information, the PostGIS documentation contains a helpful section on
  160. determining `when to use geography data type over geometry data type
  161. <http://postgis.refractions.net/documentation/manual-1.5/ch04.html#PostGIS_GeographyVSGeometry>`_.
  162. ``GeoManager``
  163. ==============
  164. .. currentmodule:: django.contrib.gis.db.models
  165. .. class:: GeoManager
  166. In order to conduct geographic queries, each geographic model requires
  167. a ``GeoManager`` model manager. This manager allows for the proper SQL
  168. construction for geographic queries; thus, without it, all geographic filters
  169. will fail. It should also be noted that ``GeoManager`` is required even if the
  170. model does not have a geographic field itself, e.g., in the case of a
  171. ``ForeignKey`` relation to a model with a geographic field. For example,
  172. if we had an ``Address`` model with a ``ForeignKey`` to our ``Zipcode``
  173. model::
  174. from django.contrib.gis.db import models
  175. from django.contrib.localflavor.us.models import USStateField
  176. class Address(models.Model):
  177. num = models.IntegerField()
  178. street = models.CharField(max_length=100)
  179. city = models.CharField(max_length=100)
  180. state = USStateField()
  181. zipcode = models.ForeignKey(Zipcode)
  182. objects = models.GeoManager()
  183. The geographic manager is needed to do spatial queries on related ``Zipcode`` objects,
  184. for example::
  185. qs = Address.objects.filter(zipcode__poly__contains='POINT(-104.590948 38.319914)')
  186. .. rubric:: Footnotes
  187. .. [#fnogc] OpenGIS Consortium, Inc., `Simple Feature Specification For SQL <http://www.opengis.org/docs/99-049.pdf>`_, Document 99-049 (May 5, 1999).
  188. .. [#fnogcsrid] *See id.* at Ch. 2.3.8, p. 39 (Geometry Values and Spatial Reference Systems).
  189. .. [#fnsrid] Typically, SRID integer corresponds to an EPSG (`European Petroleum Survey Group <http://www.epsg.org>`_) identifier. However, it may also be associated with custom projections defined in spatial database's spatial reference systems table.
  190. .. [#fnharvard] Harvard Graduate School of Design, `An Overview of Geodesy and Geographic Referencing Systems <http://www.gsd.harvard.edu/gis/manual/projections/fundamentals/>`_. This is an excellent resource for an overview of principles relating to geographic and Cartesian coordinate systems.
  191. .. [#fnthematic] Terry A. Slocum, Robert B. McMaster, Fritz C. Kessler, & Hugh H. Howard, *Thematic Cartography and Geographic Visualization* (Prentice Hall, 2nd edition), at Ch. 7.1.3.
  192. .. [#fndist] This limitation does not apply to PostGIS 1.5. It should be noted that even in previous versions of PostGIS, this isn't impossible using GeoDjango; you could for example, take a known point in a projected coordinate system, buffer it to the appropriate radius, and then perform an intersection operation with the buffer transformed to the geographic coordinate system.
  193. .. [#fngeography] Please refer to the `PostGIS Geography Type <http://postgis.refractions.net/documentation/manual-1.5/ch04.html#PostGIS_Geography>`_ documentation for more details.