Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 281 lines (163 sloc) 7.272 kB
c814fd2 @leplatrem Update README
leplatrem authored
1 *django-geojson* is a set of tools to manipulate GeoJSON with Django :
2
3 * (De)Serializer for (Geo)Django objects, querysets and lists
4 * Base views to serve GeoJSON map layers from models
5 * GeoJSON model and form fields to avoid spatial database backends
6 (compatible with *django-leaflet* for map widgets)
7
4ec7f12 @leplatrem Rewrite some doc and changelog
leplatrem authored
8
1cab56c @leplatrem Add pypip.in badges
leplatrem authored
9 .. image:: https://pypip.in/v/django-geojson/badge.png
10 :target: https://pypi.python.org/pypi/django-geojson
11
12 .. image:: https://pypip.in/d/django-geojson/badge.png
13 :target: https://pypi.python.org/pypi/django-geojson
14
2a3c88e @amarandon Show badges for the master branch
amarandon authored
15 .. image:: https://travis-ci.org/makinacorpus/django-geojson.png?branch=master
4ec7f12 @leplatrem Rewrite some doc and changelog
leplatrem authored
16 :target: https://travis-ci.org/makinacorpus/django-geojson
17
2a3c88e @amarandon Show badges for the master branch
amarandon authored
18 .. image:: https://coveralls.io/repos/makinacorpus/django-geojson/badge.png?branch=master
4ec7f12 @leplatrem Rewrite some doc and changelog
leplatrem authored
19 :target: https://coveralls.io/r/makinacorpus/django-geojson
c3cac0c @leplatrem Initial import of working version
leplatrem authored
20
21
22 =======
23 INSTALL
24 =======
25
26 ::
27
28 pip install django-geojson
29
88f2312 @leplatrem Shapely should be an optional dependency
leplatrem authored
30
59d6749 @leplatrem Rework GeoJSON doc
leplatrem authored
31 This package has **optional** `extra dependencies <http://pythonhosted.org/setuptools/setuptools.html#declaring-extras-optional-features-with-their-own-dependencies>`_.
88f2312 @leplatrem Shapely should be an optional dependency
leplatrem authored
32
59d6749 @leplatrem Rework GeoJSON doc
leplatrem authored
33
34 If you need GeoJSON fields with map widgets :
35
36 ::
37
38 pip install "django-geojson [field]"
39
40
c3cac0c @leplatrem Initial import of working version
leplatrem authored
41 =====
42 USAGE
43 =====
44
57aa6ce @leplatrem Update README.rst
leplatrem authored
45 Add ``djgeojson`` to your applications :
46
47 ::
48
49 # settings.py
50
51 INSTALLED_APPS += (
52 'djgeojson',
53 )
54
55 *(not required for views)*
56
4ec7f12 @leplatrem Rewrite some doc and changelog
leplatrem authored
57
c3cac0c @leplatrem Initial import of working version
leplatrem authored
58 GeoJSON layer view
215e3dc @leplatrem Fix README and setup formatting
leplatrem authored
59 ==================
c3cac0c @leplatrem Initial import of working version
leplatrem authored
60
61 Very useful for web mapping :
62
63 ::
64
e5ffc0a @leplatrem Update README with clearer usage of CBV
leplatrem authored
65 # urls.py
5eaece4 @leplatrem Nice try, but wrong
leplatrem authored
66 from djgeojson.views import GeoJSONLayerView
67 ...
68 url(r'^data.geojson$', GeoJSONLayerView.as_view(model=MushroomSpot), name='data'),
c3cac0c @leplatrem Initial import of working version
leplatrem authored
69
70
240b769 @leplatrem Readme touch-up
leplatrem authored
71 Consume the vector layer as usual, for example, with Leaflet loaded with jQuery Ajax:
c3cac0c @leplatrem Initial import of working version
leplatrem authored
72
73 ::
74
7b393b0 @leplatrem Minor README improvement
leplatrem authored
75 # Leaflet JS
4ec7f12 @leplatrem Rewrite some doc and changelog
leplatrem authored
76 var layer = L.geoJson();
c3cac0c @leplatrem Initial import of working version
leplatrem authored
77 map.addLayer(layer);
e5ffc0a @leplatrem Update README with clearer usage of CBV
leplatrem authored
78 $.getJSON("{% url 'data' %}", function (data) {
c3cac0c @leplatrem Initial import of working version
leplatrem authored
79 layer.addData(data);
80 });
81
82
7b393b0 @leplatrem Minor README improvement
leplatrem authored
83 Inherit generic views **only** if you need a reusable set of options :
e5ffc0a @leplatrem Update README with clearer usage of CBV
leplatrem authored
84
85 ::
86
87 # views.py
88 from djgeojson.views import GeoJSONLayerView
89
90 class MapLayer(GeoJSONLayerView):
91 # Options
92 precision = 4 # float
93 simplify = 0.5 # generalization
94
95
96 # urls.py
97 from .views import MapLayer, MeetingLayer
98 ...
2810df5 @willemarcel change 'fields' to 'properties' in code example
willemarcel authored
99 url(r'^mushrooms.geojson$', MapLayer.as_view(model=MushroomSpot, properties=('name',)), name='mushrooms')
e5ffc0a @leplatrem Update README with clearer usage of CBV
leplatrem authored
100
7b393b0 @leplatrem Minor README improvement
leplatrem authored
101 Most common use-cases of reusable options are: low-fi precision, common list of fields between several views, etc.
4ec7f12 @leplatrem Rewrite some doc and changelog
leplatrem authored
102
103 Options are :
e5ffc0a @leplatrem Update README with clearer usage of CBV
leplatrem authored
104
4ec7f12 @leplatrem Rewrite some doc and changelog
leplatrem authored
105 * **properties** : ``list`` of properties names, or ``dict`` for mapping field names and properties
106 * **simplify** : generalization of geometries (See ``simplify()``)
107 * **precision** : number of digit after comma
108 * **geometry_field** : name of geometry field (*default*: ``geom``)
109 * **srid** : projection (*default*: 4326, for WGS84)
dafee34 @7wonders Added note to readme and small test for bbox_auto
7wonders authored
110 * **bbox** : Allows you to set your own bounding box on feature collection level
111 * **bbox_auto** : True/False (default false). Will automatically generate a bounding box on a per feature level.
e5ffc0a @leplatrem Update README with clearer usage of CBV
leplatrem authored
112
113
28e010d @leplatrem First set of documentation
leplatrem authored
114
115 Tiled GeoJSON layer view
116 ========================
117
118 Vectorial tiles can help display a great number of objects on the map,
119 with `reasonnable performance <https://groups.google.com/forum/?fromgroups#!searchin/leaflet-js/GeoJSON$20performance$3F$20River$20vector$20tile$20map./leaflet-js/_WJquNpdmH0/qQsasZpCTPUJ>`_.
120
121 ::
122
123 # urls.py
124 from djgeojson.views import TiledGeoJSONLayerView
125 ...
126
127 url(r'^data/(?P<z>\d+)/(?P<x>\d+)/(?P<y>\d+).geojson$',
128 TiledGeoJSONLayerView.as_view(model=MushroomSpot), name='data'),
129
130
60b0a8a @leplatrem Mention ol3 for vector tiles
leplatrem authored
131 Consume the vector tiles using `Leaflet TileLayer GeoJSON <https://github.com/glenrobertson/leaflet-tilelayer-geojson/>`_, `Polymaps <http://polymaps.org/>`_, `OpenLayers 3 <http://twpayne.github.io/ol3/remote-vector/examples/tile-vector.html>`_ or `d3.js <http://d3js.org>`_ for example.
28e010d @leplatrem First set of documentation
leplatrem authored
132
133 Options are :
134
135 * **trim_to_boundary** : if ``True`` geometries are trimmed to the tile boundary
136 * **simplifications** : a dict of simplification values by zoom level
137
138
139
c3cac0c @leplatrem Initial import of working version
leplatrem authored
140 GeoJSON template filter
215e3dc @leplatrem Fix README and setup formatting
leplatrem authored
141 =======================
c3cac0c @leplatrem Initial import of working version
leplatrem authored
142
4ec7f12 @leplatrem Rewrite some doc and changelog
leplatrem authored
143 Mainly useful to dump features in HTML output and bypass AJAX call :
144
145 ::
146
7b393b0 @leplatrem Minor README improvement
leplatrem authored
147 // Leaflet JS
4ec7f12 @leplatrem Rewrite some doc and changelog
leplatrem authored
148 L.geoJson({{ object_list|geojsonfeature|safe}}).addTo(map);
149
150
c3cac0c @leplatrem Initial import of working version
leplatrem authored
151 Will work either for a model, a geometry field or a queryset.
152
153 ::
154
155 {% load geojson_tags %}
156
4ec7f12 @leplatrem Rewrite some doc and changelog
leplatrem authored
157 var feature = {{ object|geojsonfeature|safe }};
c3cac0c @leplatrem Initial import of working version
leplatrem authored
158
4ec7f12 @leplatrem Rewrite some doc and changelog
leplatrem authored
159 var geom = {{ object.geom|geojsonfeature|safe }};
c3cac0c @leplatrem Initial import of working version
leplatrem authored
160
4ec7f12 @leplatrem Rewrite some doc and changelog
leplatrem authored
161 var collection = {{ object_list|geojsonfeature|safe }};
c3cac0c @leplatrem Initial import of working version
leplatrem authored
162
163
2a56367 @leplatrem Update docs
leplatrem authored
164 Properties and custom geometry field name can be provided.
165
166 ::
167
168 {{ object|geojsonfeature:"name,age" }}
169 {{ object|geojsonfeature:"name,age:the_geom" }}
170 {{ object|geojsonfeature:":geofield" }}
171
172
c206bed @leplatrem Nicer layout and documentation
leplatrem authored
173 Model and forms fields
174 ======================
175
176 GeoJSON fields are based on Brad Jasper's `JSONField <https://pypi.python.org/pypi/jsonfield>`_.
59d6749 @leplatrem Rework GeoJSON doc
leplatrem authored
177 See `INSTALL`_ to install extra dependencies.
c206bed @leplatrem Nicer layout and documentation
leplatrem authored
178
179 They are useful to avoid usual GIS stacks (GEOS, GDAL, PostGIS...)
180 for very simple use-cases (no spatial operation yet).
181
182 ::
183
cff4c60 @leplatrem Update docs
leplatrem authored
184 from djgeojson.fields import PointField
c206bed @leplatrem Nicer layout and documentation
leplatrem authored
185
186 class Address(models.Model):
cff4c60 @leplatrem Update docs
leplatrem authored
187 geom = PointField()
c206bed @leplatrem Nicer layout and documentation
leplatrem authored
188
189 address = Address()
190 address.geom = {'type': 'Point', 'coordinates': [0, 0]}
191 address.save()
192
193
194 Form widgets are rendered with Leaflet maps automatically if
195 `django-leaflet <https://github.com/makinacorpus/django-leaflet>`_
196 is available.
197
cff4c60 @leplatrem Update docs
leplatrem authored
198 All geometry types are supported and respectively validated :
199 `GeometryField`, `PointField`, `MultiPointField`, `LineStringField`,
200 `MultiLineStringField`, `PolygonField`, `MultiPolygonField`,
201 `GeometryCollectionField`.
202
c206bed @leplatrem Nicer layout and documentation
leplatrem authored
203
7b393b0 @leplatrem Minor README improvement
leplatrem authored
204 Low-level serializer
205 ====================
4ec7f12 @leplatrem Rewrite some doc and changelog
leplatrem authored
206
207 ::
208
209 from djgeojson.serializers import Serializer as GeoJSONSerializer
210
3f81ee8 @varnerac-ubnt Add an with_modelname option to serializer
varnerac-ubnt authored
211 GeoJSONSerializer().serialize(Restaurants.objects.all(), use_natural_keys=True, with_modelname=False)
4ec7f12 @leplatrem Rewrite some doc and changelog
leplatrem authored
212
213
214
d8436b2 @vross Update README.
vross authored
215 Low-level deserializer
216 ======================
217
218 ::
219
220 from djgeojson.serializers import Serializer as GeoJSONSerializer
221
222 GeoJSONSerializer().deserialize('geojson', my_geojson)
223
224 You can optionally specify the model name directly in the parameters:
225
226 ::
227
228 GeoJSONSerializer().deserialize('geojson', my_geojson, model_name=my_model_name)
229
230
231
232
4ec7f12 @leplatrem Rewrite some doc and changelog
leplatrem authored
233 Dump GIS models, or fixtures
234 ============================
c3cac0c @leplatrem Initial import of working version
leplatrem authored
235
236 Register the serializer in your project :
237
238 ::
239
240 # settings.py
241
242 SERIALIZATION_MODULES = {
243 'geojson' : 'djgeojson.serializers'
244 }
245
246 Command-line ``dumpdata`` can export files, viewable in GIS software like QGis :
247
248 ::
249
98f58de @leplatrem Typo in README
leplatrem authored
250 python manage.py dumpdata --format=geojson yourapp.Model > export.geojson
c3cac0c @leplatrem Initial import of working version
leplatrem authored
251
252 Works with ``loaddata`` as well, which can now import GeoJSON files.
253
254
255
256 =======
257 AUTHORS
258 =======
259
260 * Mathieu Leplatre <mathieu.leplatre@makina-corpus.com>
88678e8 @leplatrem Complete rewrite using @glenrobertson serializer
leplatrem authored
261 * Glen Robertson author of django-geojson-tiles at: https://github.com/glenrobertson/django-geojson-tiles/
4ec7f12 @leplatrem Rewrite some doc and changelog
leplatrem authored
262 * @jeffkistler's author of geojson serializer at: https://gist.github.com/967274
263 * Ben Welsh and Lukasz Dziedzia for `quick test script <http://datadesk.latimes.com/posts/2012/06/test-your-django-app-with-travisci/>`_
e6302ae @leplatrem Add fle to authors
leplatrem authored
264 * Florent Lebreton http://github.com/fle
4ec7f12 @leplatrem Rewrite some doc and changelog
leplatrem authored
265
266 Version 1.X:
267
268 * Daniel Sokolowski, serializer snippet
b1db269 @leplatrem Update README.rst
leplatrem authored
269 * ozzmo, python 2.6 compatibility
c3cac0c @leplatrem Initial import of working version
leplatrem authored
270
271 |makinacom|_
272
273 .. |makinacom| image:: http://depot.makina-corpus.org/public/logo.gif
274 .. _makinacom: http://www.makina-corpus.com
275
276 =======
277 LICENSE
278 =======
279
280 * Lesser GNU Public License
Something went wrong with that request. Please try again.