Legend:

This documentation is behind the current feature-set -- when in doubt use {{{help}}} on the feature in question, as most [browser:django/branches/gis/django/contrib/gis GeoDjango modules] and routines have docstrings.

20

This documentation is behind the current feature-set -- when in doubt use `help` on the feature in question, as most [browser:django/branches/gis/django/contrib/gis GeoDjango modules] and routines have docstrings.

The following is a discussion of features we hope to implement in !GeoDjango. Unless stated otherwise, features in this list are not prioritized. If you have a pet feature you may accelerate its development by submitting code yourself.

* The [source:django/branches/gis/django/contrib/gis/utils/LayerMapping.py LayerMapping] class will import vector data from GDAL-supported data sources. This is still 'beta', and requires installation of the [wiki:GeoDjango#GDAL GDAL library].

* {{{django.contrib.gis.maps.openlayers}}}: Similar plans are in place for a [http://www.openlayers.org/ OpenLayers] module, which is ''the'' open source web mapping framework. Well-tested, BSD-licensed, and includes multitudes of features; for example, !OpenLayers supports WMS/WFS/tiles as well as Google, MS Virtual Earth, and Yahoo layers. ''See also'' ticket #5472.

61

* [http://developer.yahoo.com/maps/ Yahoo!] has a really slick flash interface, I'd like to support this eventually, though not planned at this time.

* `django.contrib.gis.maps.openlayers`: Similar plans are in place for a [http://www.openlayers.org/ OpenLayers] module, which is ''the'' open source web mapping framework. Well-tested, BSD-licensed, and includes multitudes of features; for example, !OpenLayers supports WMS/WFS/tiles as well as Google, MS Virtual Earth, and Yahoo layers. ''See also'' ticket #5472.

* [http://www.mapnik.org/ Mapnik] is modern, but very early on in development and ''completely'' lacks documentation. However, the code is elegant and clean, and it was designed for integration with Python. First to use AGG rendering.

64

* [http://mapserver.gis.umn.edu/ Mapserver] is the leading open source map renderer. !MapServer is well documented and has strong community support. Uses text-based configuration files, which may be difficult to set up. AGG rendering and dynamic loading of configuration files (''e.g.'', from a string) has been added to version 5.0.

63

* [http://www.mapnik.org/ Mapnik] is a modern C++ engine that was designed for use with Python and generates beautiful maps. However, documentation is lacking and installation is difficult. First to use AGG rendering.

64

* [http://mapserver.gis.umn.edu/ Mapserver] is the leading open source map renderer. !MapServer is well documented and has strong community support. Uses text-based configuration files, which may be difficult to set up. AGG rendering and dynamic loading of configuration files (e.g., from a string) has been added to version 5.0.

65

65

* WMS Server

66

* I'm not satisfied with any of the current WMS/WFS implementations. One implemented in Django would be desirable, ''e.g.'', {{{django.contrib.gis.wms}}}. Thoughts anyone? (OWSLib looks good, see below)

66

* I'm not satisfied with any of the current WMS/WFS implementations. One implemented in Django would be desirable, e.g., `django.contrib.gis.wms`. Thoughts anyone? (OWSLib looks good, see below)

* My (JDunck) reading indicates yes. Given the same coordinate system (i.e. datum, origin, and axes), degrees are useful without conversion.

88

87

* '''Q:''' Can this implementation work with [http://dev.mysql.com/doc/refman/5.0/en/spatial-extensions.html MySQL spatial-extensions]. If not, it's planned?

89

* ~~No, unfortunately support is not planned.~~ Support for MySQL was added as of r6527. The changes required for the Oracle backend made it relatively easy to implement one for MySQL. However, MySQL is limited to bounding-box queries only, and many advanced features (''e.g.'', coordinate transformation, {{{geometry_columns}}} and {{{spatial_ref_sys}}} tables) are missing because of MySQL's implementation. Furthermore, MySQL's spatial indexes are limited to MyISAM tables, which are not transactional.

88

* ~~No, unfortunately support is not planned.~~ Support for MySQL was added as of r6527. The changes required for the Oracle backend made it relatively easy to implement one for MySQL. However, MySQL is limited to bounding-box queries only, and many advanced features (e.g., coordinate transformation, `geometry_columns` and `spatial_ref_sys` tables) are missing because of MySQL's implementation. Furthermore, MySQL's spatial indexes are limited to MyISAM tables, which are not transactional.

90

89

* '''Q:''' Is this going to be a WMS Server/WMS Client/Both? OWSLib is just a WMS Client from what I have seen (from ruckc)

91

* WMS Server first, client capability a possibility in certain situations (i.e. you want to cache data from another WMS server). Yes, OWSLib is a client, but it contains code for validating the correct parameters to send to a WMS server, thus it can be adapted into a Django view that validates whether the proper WMS parameters were given. Mapnik has an {{{ogcserver}}} module that can parse the correct parameters for WMS 1.1.1 and 1.3.0, however since it is licensed under the LGPL it cannot be easily incorporated into this branch (unlike OWSLib).

92

* '''Q:''' Per [http://groups.google.com/group/django-developers/browse_thread/thread/9f6c70864bfa7f2e/ this discussion] in {{{django-developers}}}, "I can do spatial queries if they are directly between two models with polygon fields but I can't seem to get at the spatial queries through foreign keys."

93

* Geographic queries require {{{GeoManager}}}, even if the model does not have a geographic field itself (in the case of a foreign key to a geo-field). The reply in the discussion gives detail into why.

* WMS Server first, client capability a possibility in certain situations (i.e. you want to cache data from another WMS server). Yes, OWSLib is a client, but it contains code for validating the correct parameters to send to a WMS server, thus it can be adapted into a Django view that validates whether the proper WMS parameters were given. Mapnik has an `ogcserver` module that can parse the correct parameters for WMS 1.1.1 and 1.3.0, however since it is licensed under the LGPL it cannot be easily incorporated into this branch (unlike OWSLib).

91

* '''Q:''' Per [http://groups.google.com/group/django-developers/browse_thread/thread/9f6c70864bfa7f2e/ this discussion] in `django-developers`, "I can do spatial queries if they are directly between two models with polygon fields but I can't seem to get at the spatial queries through foreign keys."

92

* Geographic queries require `GeoManager`, even if the model does not have a geographic field itself (in the case of a foreign key to a geo-field). The reply in the discussion gives detail into why.

* They are no longer separate, as `transform` now accepts `CoordTransform` and `SpatialReference` objects, as well as string WKT and integer SRID values (`transform` checks the input type and dispatches to the correct routine). The former reason for the separation was that each mapped to the separate OGR routines [http://www.gdal.org/ogr/ogr__api_8h.html#59a5b3f954b11cfbf6e78807c28d6090 OGR_G_Transform] and [http://www.gdal.org/ogr/ogr__api_8h.html#43af4c2127cea0a5059692a62c0feb63 OGR_G_TransformTo]. For better performance use `CoordTransform` objects when you will be performing the same transformation repeatedly.

'''Notes''': The {{{GeoMixin}}} syntax is no longer needed as of r6467. By default, a GiST index will be created for the School {{{PointField}}}s fields. This behavior can be turned off by using {{{models.PointField(spatial_index=False)}}}.

128

'''Notes''': The `GeoMixin` syntax is no longer needed as of r6467. By default, a GiST index will be created for the School `PointField`s fields. This behavior can be turned off by using `models.PointField(spatial_index=False)`.

130

129

131

130

=== Using syncdb ===

132

Both {{{manage.py}}} commands {{{sqlall}}} and {{{syncdb}}} work on geographic models:

131

Both `manage.py` commands `sqlall` and `syncdb` work on geographic models:

After a geographic model has been created, the PostGIS additions to the API may be used. Geographic queries are done normally by using {{{filter()}}} and {{{exclude()}}} on geometry-enabled models using geographic lookup types (''see'' the [wiki:GeoDjangoDatabaseAPI Database API] for lookup types). In the following example, the {{{bbcontains}}} lookup type is used which is the same as the PostGIS {{{&&}}} operator. It looks to see if the ''bounding box'' of the polygon contains the specific point. The next example uses the PostGIS {{{Contains()}}} function, which calls GEOS library to test if the ''polygon'' actually contains the specific point, not just the bounding box.

165

After a geographic model has been created, the PostGIS additions to the API may be used. Geographic queries are done normally by using `filter()` and `exclude()` on geometry-enabled models using geographic lookup types (''see'' the [wiki:GeoDjangoDatabaseAPI Database API] for lookup types). In the following example, the `bbcontains` lookup type is used which is the same as the PostGIS `&&` operator. It looks to see if the ''bounding box'' of the polygon contains the specific point. The next example uses the PostGIS `Contains()` function, which calls GEOS library to test if the ''polygon'' actually contains the specific point, not just the bounding box.

Both spatial queries and normal queries using {{{filter()}}} may be used in the same query. For example, the following query set will only show school districts that have 'Houston' in their name and contain the given point within their polygon boundary:

173

Both spatial queries and normal queries using `filter()` may be used in the same query. For example, the following query set will only show school districts that have 'Houston' in their name and contain the given point within their polygon boundary:

Or combine both the bounding box routines (less accurate, fast) with the GEOS routines (most accurate, slower) to get a query that is both fast and accurate:

179

In PostGIS versions 1.2.2 and above, Refractions introduced a feature called "inline index magic" that automatically combines the indexed bounding box queries with their more computationally expensive counterparts. Prior to this revision the following filter could be used to get the same performance benefits: