Code

Changes between Version 6 and Version 7 of GeoDjangoModelAPI


Ignore:
Timestamp:
09/03/08 19:00:51 (6 years ago)
Author:
jbronn
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • GeoDjangoModelAPI

    v6 v7  
    1 [[TOC]] 
    2 = Model API = 
    3 This section explores the details of the GeoDjango Model API.  Throughout this section, we'll be using the following geographic model of a Zip code as our example: 
    4 {{{ 
    5 #!python 
    6 from django.contrib.gis.db import models 
     1The !GeoDjango Model API documentation is now located at [http://geodjango.org/docs/model-api.html geodjango.org] 
    72 
    8 class Zip(models.Model): 
    9   code = models.CharField(maxlength=5) 
    10   poly = models.PolygonField() 
    11  
    12   objects = models.GeoManager() 
    13 }}} 
    14  
    15 == Field Types == 
    16  
    17 The following geometry-enabled fields are available: 
    18  * {{{PointField}}} 
    19  * {{{LineStringField}}} 
    20  * {{{PolygonField}}} 
    21  * {{{MultiPointField}}} 
    22  * {{{MultiLineStringField}}} 
    23  * {{{MultiPolygonField}}} 
    24  * {{{GeometryCollectionField}}} 
    25  
    26 Each of these fields correspond with OpenGIS [http://en.wikipedia.org/wiki/Simple_Features Simple Features].   
    27  
    28 == Field Options == 
    29  
    30 In addition to the regular [http://www.djangoproject.com/documentation/model-api/#field-options field options] available for Django models, Geographic-enabled models have  the following additional options: 
    31  * `srid` 
    32    * Sets the SRID (Spatial Reference System Identity) of geometry to the given value.  Defaults to 4326 (WGS84).  ''See'' Open GIS Consortium, Inc., ''[http://www.opengis.org/docs/99-049.pdf OpenGIS Simple Feature Specification For SQL]'', Document 99-049 (May 5, 1999), at  Ch. 2.3.8 (Geometry Values and Spatial Reference Systems, pg. 39). 
    33  * `spatial_index` 
    34    * Defaults to True.  Creates a GiST index for the given geometry.  Update the index with the PostgreSQL command `VACUUM ANALYZE` (may take a while to execute depending on how large your geographic-enabled tables are).  Please note that this is different from the `db_index` field option since geographic indexes are created in a different manner than regular indexes.  The original keyword, `index`, has been deprecated and will disappear in future revisions. 
    35  
    36 == !GeoManager == 
    37  
    38 In order to conduct geographic queries, each geographic model requires `GeoManager`.  This [http://www.djangoproject.com/documentation/model-api/#managers manager] allows for the proper SQL construction for geographic queries; thus, without it, all geographic filters will fail.  It should also be noted that a `GeoManager` will be required even if the model does not have a geographic field itself, ''i.e.'',in the case of a `ForeignKey` to a geographic model.  For example, if we had an `Address` model with a `ForeignKey` to our `Zip` geographic model: 
    39 {{{ 
    40 #!python 
    41 from django.contrib.gis.db import models 
    42  
    43 class Address(models.Model): 
    44     num = models.IntegerField() 
    45     street = models.CharField(maxlength=100) 
    46     city = models.CharField(maxlength=100) 
    47     state = models.USStateField() 
    48     zip = models.ForeignKey(Zip) 
    49  
    50     objects = models.GeoManager() 
    51 }}} 
    52  
    53 The geographic manager is needed to do spatial queries on [http://www.djangoproject.com/documentation/db-api/#related-objects related Zip objects], for example: 
    54 {{{ 
    55 >>> qs = Address.objects.filter(zip__poly__contains='POINT(-104.590948 38.319914)') 
    56 }}} 
    57  
    58  
    59 == !GeoMixin == 
    60  
    61 '''Update:''' The [http://code.djangoproject.com/browser/django/branches/gis/django/contrib/gis/db/models/GeoMixin.py GeoMixin] is no longer necessary for geographic models as of r6467.  The mixin used to provide extra instance methods ([wiki:GeoDjangoDatabaseAPI#ExtraInstanceMethods discussed in the database api docs]) for geographic models without subclassing (aka ModelInheritance) -- which is not yet functional in Django. 
     3Feel free to leave comments and/or suggestions about the !GeoDjango Model API documentation here.