Debian Codegraph @

docs/ref/contrib/gis/gdal.txt

raw
1 ========
2 GDAL API
3 ========
4
5 .. module:: django.contrib.gis.gdal
6 :synopsis: GeoDjango's high-level interface to the GDAL library.
7
8 `GDAL`__ stands for **Geospatial Data Abstraction Library**,
9 and is a veritable "Swiss army knife" of GIS data functionality. A subset
10 of GDAL is the `OGR`__ Simple Features Library, which specializes
11 in reading and writing vector geographic data in a variety of standard
12 formats.
13
14 GeoDjango provides a high-level Python interface for some of the
15 capabilities of OGR, including the reading and coordinate transformation
16 of vector spatial data and minimal support for GDAL's features with respect
17 to raster (image) data.
18
19 .. note::
20
21 Although the module is named ``gdal``, GeoDjango only supports some of the
22 capabilities of OGR and GDAL's raster features at this time.
23
24 __ https://gdal.org/
25 __ https://gdal.org/user/vector_data_model.html
26
27 Overview
28 ========
29
30 .. _gdal_sample_data:
31
32 Sample Data
33 -----------
34
35 The GDAL/OGR tools described here are designed to help you read in
36 your geospatial data, in order for most of them to be useful you have
37 to have some data to work with. If you're starting out and don't yet
38 have any data of your own to use, GeoDjango tests contain a number of
39 data sets that you can use for testing. You can download them here:
40
41 .. code-block:: shell
42
43 $ wget https://raw.githubusercontent.com/django/django/main/tests/gis_tests/data/cities/cities.{shp,prj,shx,dbf}
44 $ wget https://raw.githubusercontent.com/django/django/main/tests/gis_tests/data/rasters/raster.tif
45
46 Vector Data Source Objects
47 ==========================
48
49 ``DataSource``
50 --------------
51
52 :class:`DataSource` is a wrapper for the OGR data source object that
53 supports reading data from a variety of OGR-supported geospatial file
54 formats and data sources using a consistent interface. Each
55 data source is represented by a :class:`DataSource` object which contains
56 one or more layers of data. Each layer, represented by a :class:`Layer`
57 object, contains some number of geographic features (:class:`Feature`),
58 information about the type of features contained in that layer (e.g.
59 points, polygons, etc.), as well as the names and types of any
60 additional fields (:class:`Field`) of data that may be associated with
61 each feature in that layer.
62
63 .. class:: DataSource(ds_input, encoding='utf-8')
64
65 The constructor for ``DataSource`` only requires one parameter: the path of
66 the file you want to read. However, OGR also supports a variety of more
67 complex data sources, including databases, that may be accessed by passing
68 a special name string instead of a path. For more information, see the
69 `OGR Vector Formats`__ documentation. The :attr:`name` property of a
70 ``DataSource`` instance gives the OGR name of the underlying data source
71 that it is using.
72
73 The optional ``encoding`` parameter allows you to specify a non-standard
74 encoding of the strings in the source. This is typically useful when you
75 obtain ``DjangoUnicodeDecodeError`` exceptions while reading field values.
76
77 Once you've created your ``DataSource``, you can find out how many layers
78 of data it contains by accessing the :attr:`layer_count` property, or
79 (equivalently) by using the ``len()`` function. For information on
80 accessing the layers of data themselves, see the next section:
81
82 .. code-block:: pycon
83
84 >>> from django.contrib.gis.gdal import DataSource
85 >>> ds = DataSource("/path/to/your/cities.shp")
86 >>> ds.name
87 '/path/to/your/cities.shp'
88 >>> ds.layer_count # This file only contains one layer
89 1
90
91 .. attribute:: layer_count
92
93 Returns the number of layers in the data source.
94
95 .. attribute:: name
96
97 Returns the name of the data source.
98
99 __ https://gdal.org/drivers/vector/
100
101 ``Layer``
102 ---------
103
104 .. class:: Layer
105
106 ``Layer`` is a wrapper for a layer of data in a ``DataSource`` object. You
107 never create a ``Layer`` object directly. Instead, you retrieve them from
108 a :class:`DataSource` object, which is essentially a standard Python
109 container of ``Layer`` objects. For example, you can access a specific
110 layer by its index (e.g. ``ds[0]`` to access the first layer), or you can
111 iterate over all the layers in the container in a ``for`` loop. The
112 ``Layer`` itself acts as a container for geometric features.
113
114 Typically, all the features in a given layer have the same geometry type.
115 The :attr:`geom_type` property of a layer is an :class:`OGRGeomType` that
116 identifies the feature type. We can use it to print out some basic
117 information about each layer in a :class:`DataSource`:
118
119 .. code-block:: pycon
120
121 >>> for layer in ds:
122 ... print('Layer "%s": %i %ss' % (layer.name, len(layer), layer.geom_type.name))
123 ...
124 Layer "cities": 3 Points
125
126 The example output is from the cities data source, loaded above, which
127 evidently contains one layer, called ``"cities"``, which contains three
128 point features. For simplicity, the examples below assume that you've
129 stored that layer in the variable ``layer``:
130
131 .. code-block:: pycon
132
133 >>> layer = ds[0]
134
135 .. attribute:: name
136
137 Returns the name of this layer in the data source.
138
139 .. code-block:: pycon
140
141 >>> layer.name
142 'cities'
143
144 .. attribute:: num_feat
145
146 Returns the number of features in the layer. Same as ``len(layer)``:
147
148 .. code-block:: pycon
149
150 >>> layer.num_feat
151 3
152
153 .. attribute:: geom_type
154
155 Returns the geometry type of the layer, as an :class:`OGRGeomType` object:
156
157 .. code-block:: pycon
158
159 >>> layer.geom_type.name
160 'Point'
161
162 .. attribute:: num_fields
163
164 Returns the number of fields in the layer, i.e the number of fields of
165 data associated with each feature in the layer:
166
167 .. code-block:: pycon
168
169 >>> layer.num_fields
170 4
171
172 .. attribute:: fields
173
174 Returns a list of the names of each of the fields in this layer:
175
176 .. code-block:: pycon
177
178 >>> layer.fields
179 ['Name', 'Population', 'Density', 'Created']
180
181 .. attribute field_types
182
183 Returns a list of the data types of each of the fields in this layer. These
184 are subclasses of ``Field``, discussed below:
185
186 .. code-block:: pycon
187
188 >>> [ft.__name__ for ft in layer.field_types]
189 ['OFTString', 'OFTReal', 'OFTReal', 'OFTDate']
190
191 .. attribute:: field_widths
192
193 Returns a list of the maximum field widths for each of the fields in this
194 layer:
195
196 .. code-block:: pycon
197
198 >>> layer.field_widths
199 [80, 11, 24, 10]
200
201 .. attribute:: field_precisions
202
203 Returns a list of the numeric precisions for each of the fields in this
204 layer. This is meaningless (and set to zero) for non-numeric fields:
205
206 .. code-block:: pycon
207
208 >>> layer.field_precisions
209 [0, 0, 15, 0]
210
211 .. attribute:: extent
212
213 Returns the spatial extent of this layer, as an :class:`Envelope` object:
214
215 .. code-block:: pycon
216
217 >>> layer.extent.tuple
218 (-104.609252, 29.763374, -95.23506, 38.971823)
219
220 .. attribute:: srs
221
222 Property that returns the :class:`SpatialReference` associated with this
223 layer:
224
225 .. code-block:: pycon
226
227 >>> print(layer.srs)
228 GEOGCS["GCS_WGS_1984",
229 DATUM["WGS_1984",
230 SPHEROID["WGS_1984",6378137,298.257223563]],
231 PRIMEM["Greenwich",0],
232 UNIT["Degree",0.017453292519943295]]
233
234 If the :class:`Layer` has no spatial reference information associated
235 with it, ``None`` is returned.
236
237 .. attribute:: spatial_filter
238
239 Property that may be used to retrieve or set a spatial filter for this
240 layer. A spatial filter can only be set with an :class:`OGRGeometry`
241 instance, a 4-tuple extent, or ``None``. When set with something other than
242 ``None``, only features that intersect the filter will be returned when
243 iterating over the layer:
244
245 .. code-block:: pycon
246
247 >>> print(layer.spatial_filter)
248 None
249 >>> print(len(layer))
250 3
251 >>> [feat.get("Name") for feat in layer]
252 ['Pueblo', 'Lawrence', 'Houston']
253 >>> ks_extent = (-102.051, 36.99, -94.59, 40.00) # Extent for state of Kansas
254 >>> layer.spatial_filter = ks_extent
255 >>> len(layer)
256 1
257 >>> [feat.get("Name") for feat in layer]
258 ['Lawrence']
259 >>> layer.spatial_filter = None
260 >>> len(layer)
261 3
262
263 .. method:: get_fields()
264
265 A method that returns a list of the values of a given field for each
266 feature in the layer:
267
268 .. code-block:: pycon
269
270 >>> layer.get_fields("Name")
271 ['Pueblo', 'Lawrence', 'Houston']
272
273 .. method:: get_geoms(geos=False)
274
275 A method that returns a list containing the geometry of each feature in the
276 layer. If the optional argument ``geos`` is set to ``True`` then the
277 geometries are converted to :class:`~django.contrib.gis.geos.GEOSGeometry`
278 objects. Otherwise, they are returned as :class:`OGRGeometry` objects:
279
280 .. code-block:: pycon
281
282 >>> [pt.tuple for pt in layer.get_geoms()]
283 [(-104.609252, 38.255001), (-95.23506, 38.971823), (-95.363151, 29.763374)]
284
285 .. method:: test_capability(capability)
286
287 Returns a boolean indicating whether this layer supports the given
288 capability (a string). Examples of valid capability strings include:
289 ``'RandomRead'``, ``'SequentialWrite'``, ``'RandomWrite'``,
290 ``'FastSpatialFilter'``, ``'FastFeatureCount'``, ``'FastGetExtent'``,
291 ``'CreateField'``, ``'Transactions'``, ``'DeleteFeature'``, and
292 ``'FastSetNextByIndex'``.
293
294 ``Feature``
295 -----------
296
297 .. class:: Feature
298
299 ``Feature`` wraps an OGR feature. You never create a ``Feature`` object
300 directly. Instead, you retrieve them from a :class:`Layer` object. Each
301 feature consists of a geometry and a set of fields containing additional
302 properties. The geometry of a field is accessible via its ``geom`` property,
303 which returns an :class:`OGRGeometry` object. A ``Feature`` behaves like a
304 standard Python container for its fields, which it returns as :class:`Field`
305 objects: you can access a field directly by its index or name, or you can
306 iterate over a feature's fields, e.g. in a ``for`` loop.
307
308 .. attribute:: geom
309
310 Returns the geometry for this feature, as an ``OGRGeometry`` object:
311
312 .. code-block:: pycon
313
314 >>> city.geom.tuple
315 (-104.609252, 38.255001)
316
317 .. attribute:: get
318
319 A method that returns the value of the given field (specified by name)
320 for this feature, **not** a ``Field`` wrapper object:
321
322 .. code-block:: pycon
323
324 >>> city.get("Population")
325 102121
326
327 .. attribute:: geom_type
328
329 Returns the type of geometry for this feature, as an :class:`OGRGeomType`
330 object. This will be the same for all features in a given layer and is
331 equivalent to the :attr:`Layer.geom_type` property of the :class:`Layer`
332 object the feature came from.
333
334 .. attribute:: num_fields
335
336 Returns the number of fields of data associated with the feature. This will
337 be the same for all features in a given layer and is equivalent to the
338 :attr:`Layer.num_fields` property of the :class:`Layer` object the feature
339 came from.
340
341 .. attribute:: fields
342
343 Returns a list of the names of the fields of data associated with the
344 feature. This will be the same for all features in a given layer and is
345 equivalent to the :attr:`Layer.fields` property of the :class:`Layer`
346 object the feature came from.
347
348 .. attribute:: fid
349
350 Returns the feature identifier within the layer:
351
352 .. code-block:: pycon
353
354 >>> city.fid
355 0
356
357 .. attribute:: layer_name
358
359 Returns the name of the :class:`Layer` that the feature came from. This
360 will be the same for all features in a given layer:
361
362 .. code-block:: pycon
363
364 >>> city.layer_name
365 'cities'
366
367 .. attribute:: index
368
369 A method that returns the index of the given field name. This will be the
370 same for all features in a given layer:
371
372 .. code-block:: pycon
373
374 >>> city.index("Population")
375 1
376
377 ``Field``
378 ---------
379
380 .. class:: Field
381
382 .. attribute:: name
383
384 Returns the name of this field:
385
386 .. code-block:: pycon
387
388 >>> city["Name"].name
389 'Name'
390
391 .. attribute:: type
392
393 Returns the OGR type of this field, as an integer. The ``FIELD_CLASSES``
394 dictionary maps these values onto subclasses of ``Field``:
395
396 .. code-block:: pycon
397
398 >>> city["Density"].type
399 2
400
401 .. attribute:: type_name
402
403 Returns a string with the name of the data type of this field:
404
405 .. code-block:: pycon
406
407 >>> city["Name"].type_name
408 'String'
409
410 .. attribute:: value
411
412 Returns the value of this field. The ``Field`` class itself returns the
413 value as a string, but each subclass returns the value in the most
414 appropriate form:
415
416 .. code-block:: pycon
417
418 >>> city["Population"].value
419 102121
420
421 .. attribute:: width
422
423 Returns the width of this field:
424
425 .. code-block:: pycon
426
427 >>> city["Name"].width
428 80
429
430 .. attribute:: precision
431
432 Returns the numeric precision of this field. This is meaningless (and set
433 to zero) for non-numeric fields:
434
435 .. code-block:: pycon
436
437 >>> city["Density"].precision
438 15
439
440 .. method:: as_double()
441
442 Returns the value of the field as a double (float):
443
444 .. code-block:: pycon
445
446 >>> city["Density"].as_double()
447 874.7
448
449 .. method:: as_int()
450
451 Returns the value of the field as an integer:
452
453 .. code-block:: pycon
454
455 >>> city["Population"].as_int()
456 102121
457
458 .. method:: as_string()
459
460 Returns the value of the field as a string:
461
462 .. code-block:: pycon
463
464 >>> city["Name"].as_string()
465 'Pueblo'
466
467 .. method:: as_datetime()
468
469 Returns the value of the field as a tuple of date and time components:
470
471 .. code-block:: pycon
472
473 >>> city["Created"].as_datetime()
474 (c_long(1999), c_long(5), c_long(23), c_long(0), c_long(0), c_long(0), c_long(0))
475
476 ``Driver``
477 ----------
478
479 .. class:: Driver(dr_input)
480
481 The ``Driver`` class is used internally to wrap an OGR :class:`DataSource`
482 driver.
483
484 .. attribute:: driver_count
485
486 Returns the number of OGR vector drivers currently registered.
487
488 OGR Geometries
489 ==============
490
491 ``OGRGeometry``
492 ---------------
493
494 :class:`OGRGeometry` objects share similar functionality with
495 :class:`~django.contrib.gis.geos.GEOSGeometry` objects and are thin wrappers
496 around OGR's internal geometry representation. Thus, they allow for more
497 efficient access to data when using :class:`DataSource`. Unlike its GEOS
498 counterpart, :class:`OGRGeometry` supports spatial reference systems and
499 coordinate transformation:
500
501 .. code-block:: pycon
502
503 >>> from django.contrib.gis.gdal import OGRGeometry
504 >>> polygon = OGRGeometry("POLYGON((0 0, 5 0, 5 5, 0 5))")
505
506 .. class:: OGRGeometry(geom_input, srs=None)
507
508 This object is a wrapper for the `OGR Geometry`__ class. These objects are
509 instantiated directly from the given ``geom_input`` parameter, which may be
510 a string containing WKT, HEX, GeoJSON, a ``buffer`` containing WKB data, or
511 an :class:`OGRGeomType` object. These objects are also returned from the
512 :class:`Feature.geom` attribute, when reading vector data from
513 :class:`Layer` (which is in turn a part of a :class:`DataSource`).
514
515 __ https://gdal.org/api/ogrgeometry_cpp.html#ogrgeometry-class
516
517 .. classmethod:: from_gml(gml_string)
518
519 Constructs an :class:`OGRGeometry` from the given GML string.
520
521 .. classmethod:: from_bbox(bbox)
522
523 Constructs a :class:`Polygon` from the given bounding-box (a 4-tuple).
524
525 .. method:: __len__()
526
527 Returns the number of points in a :class:`LineString`, the number of rings
528 in a :class:`Polygon`, or the number of geometries in a
529 :class:`GeometryCollection`. Not applicable to other geometry types.
530
531 .. method:: __iter__()
532
533 Iterates over the points in a :class:`LineString`, the rings in a
534 :class:`Polygon`, or the geometries in a :class:`GeometryCollection`.
535 Not applicable to other geometry types.
536
537 .. method:: __getitem__()
538
539 Returns the point at the specified index for a :class:`LineString`, the
540 interior ring at the specified index for a :class:`Polygon`, or the geometry
541 at the specified index in a :class:`GeometryCollection`. Not applicable to
542 other geometry types.
543
544 .. attribute:: dimension
545
546 Returns the number of coordinated dimensions of the geometry, i.e. 0
547 for points, 1 for lines, and so forth:
548
549 .. code-block:: pycon
550
551 >>> polygon.dimension
552 2
553
554 .. attribute:: coord_dim
555
556 Returns the coordinate dimension of this geometry. For example, the value
557 would be 2 for two-dimensional geometries.
558
559 .. deprecated:: 5.1
560
561 The ``coord_dim`` setter is deprecated. Use :meth:`.set_3d` instead.
562
563 .. attribute:: is_3d
564
565 .. versionadded:: 5.1
566
567 A boolean indicating if this geometry has Z coordinates.
568
569 .. method:: set_3d(value)
570
571 .. versionadded:: 5.1
572
573 A method that adds or removes the Z coordinate dimension.
574
575 .. code-block:: pycon
576
577 >>> p = OGRGeometry("POINT (1 2 3)")
578 >>> p.is_3d
579 True
580 >>> p.set_3d(False)
581 >>> p.wkt
582 "POINT (1 2)"
583
584 .. attribute:: is_measured
585
586 .. versionadded:: 5.1
587
588 A boolean indicating if this geometry has M coordinates.
589
590 .. method:: set_measured(value)
591
592 .. versionadded:: 5.1
593
594 A method to add or remove the M coordinate dimension.
595
596 .. code-block:: pycon
597
598 >>> p = OGRGeometry("POINT (1 2)")
599 >>> p.is_measured
600 False
601 >>> p.set_measured(True)
602 >>> p.wkt
603 "POINT M (1 2 0)"
604
605 .. attribute:: geom_count
606
607 Returns the number of elements in this geometry:
608
609 .. code-block:: pycon
610
611 >>> polygon.geom_count
612 1
613
614 .. attribute:: has_curve
615
616 .. versionadded:: 5.2
617
618 A boolean indicating if this geometry is or contains a curve geometry.
619
620 .. method:: get_linear_geometry
621
622 .. versionadded:: 5.2
623
624 Returns a linear version of the geometry. If no conversion can be made, the
625 original geometry is returned.
626
627 .. method:: get_curve_geometry
628
629 .. versionadded:: 5.2
630
631 Returns a curved version of the geometry. If no conversion can be made, the
632 original geometry is returned.
633
634 .. attribute:: point_count
635
636 Returns the number of points used to describe this geometry:
637
638 .. code-block:: pycon
639
640 >>> polygon.point_count
641 4
642
643 .. attribute:: num_points
644
645 Alias for :attr:`point_count`.
646
647 .. attribute:: num_coords
648
649 Alias for :attr:`point_count`.
650
651 .. attribute:: geom_type
652
653 Returns the type of this geometry, as an :class:`OGRGeomType` object.
654
655 .. attribute:: geom_name
656
657 Returns the name of the type of this geometry:
658
659 .. code-block:: pycon
660
661 >>> polygon.geom_name
662 'POLYGON'
663
664 .. attribute:: area
665
666 Returns the area of this geometry, or 0 for geometries that do not contain
667 an area:
668
669 .. code-block:: pycon
670
671 >>> polygon.area
672 25.0
673
674 .. attribute:: envelope
675
676 Returns the envelope of this geometry, as an :class:`Envelope` object.
677
678 .. attribute:: extent
679
680 Returns the envelope of this geometry as a 4-tuple, instead of as an
681 :class:`Envelope` object:
682
683 .. code-block:: pycon
684
685 >>> point.extent
686 (0.0, 0.0, 5.0, 5.0)
687
688 .. attribute:: srs
689
690 This property controls the spatial reference for this geometry, or
691 ``None`` if no spatial reference system has been assigned to it.
692 If assigned, accessing this property returns a :class:`SpatialReference`
693 object. It may be set with another :class:`SpatialReference` object,
694 or any input that :class:`SpatialReference` accepts. Example:
695
696 .. code-block:: pycon
697
698 >>> city.geom.srs.name
699 'GCS_WGS_1984'
700
701 .. attribute:: srid
702
703 Returns or sets the spatial reference identifier corresponding to
704 :class:`SpatialReference` of this geometry. Returns ``None`` if
705 there is no spatial reference information associated with this
706 geometry, or if an SRID cannot be determined.
707
708 .. attribute:: geos
709
710 Returns a :class:`~django.contrib.gis.geos.GEOSGeometry` object
711 corresponding to this geometry.
712
713 .. attribute:: gml
714
715 Returns a string representation of this geometry in GML format:
716
717 .. code-block:: pycon
718
719 >>> OGRGeometry("POINT(1 2)").gml
720 '<gml:Point><gml:coordinates>1,2</gml:coordinates></gml:Point>'
721
722 .. attribute:: hex
723
724 Returns a string representation of this geometry in HEX WKB format:
725
726 .. code-block:: pycon
727
728 >>> OGRGeometry("POINT(1 2)").hex
729 '0101000000000000000000F03F0000000000000040'
730
731 .. attribute:: json
732
733 Returns a string representation of this geometry in JSON format:
734
735 .. code-block:: pycon
736
737 >>> OGRGeometry("POINT(1 2)").json
738 '{ "type": "Point", "coordinates": [ 1.000000, 2.000000 ] }'
739
740 .. attribute:: kml
741
742 Returns a string representation of this geometry in KML format.
743
744 .. attribute:: wkb_size
745
746 Returns the size of the WKB buffer needed to hold a WKB representation
747 of this geometry:
748
749 .. code-block:: pycon
750
751 >>> OGRGeometry("POINT(1 2)").wkb_size
752 21
753
754 .. attribute:: wkb
755
756 Returns a ``buffer`` containing a WKB representation of this geometry.
757
758 .. attribute:: wkt
759
760 Returns a string representation of this geometry in WKT format.
761
762 .. attribute:: ewkt
763
764 Returns the EWKT representation of this geometry.
765
766 .. method:: clone()
767
768 Returns a new :class:`OGRGeometry` clone of this geometry object.
769
770 .. method:: close_rings()
771
772 If there are any rings within this geometry that have not been closed,
773 this routine will do so by adding the starting point to the end:
774
775 .. code-block:: pycon
776
777 >>> triangle = OGRGeometry("LINEARRING (0 0,0 1,1 0)")
778 >>> triangle.close_rings()
779 >>> triangle.wkt
780 'LINEARRING (0 0,0 1,1 0,0 0)'
781
782 .. method:: transform(coord_trans, clone=False)
783
784 Transforms this geometry to a different spatial reference system. May take
785 a :class:`CoordTransform` object, a :class:`SpatialReference` object, or
786 any other input accepted by :class:`SpatialReference` (including spatial
787 reference WKT and PROJ strings, or an integer SRID).
788
789 By default nothing is returned and the geometry is transformed in-place.
790 However, if the ``clone`` keyword is set to ``True`` then a transformed
791 clone of this geometry is returned instead.
792
793 .. method:: intersects(other)
794
795 Returns ``True`` if this geometry intersects the other, otherwise returns
796 ``False``.
797
798 .. method:: equals(other)
799
800 Returns ``True`` if this geometry is equivalent to the other, otherwise
801 returns ``False``.
802
803 .. method:: disjoint(other)
804
805 Returns ``True`` if this geometry is spatially disjoint to (i.e. does
806 not intersect) the other, otherwise returns ``False``.
807
808 .. method:: touches(other)
809
810 Returns ``True`` if this geometry touches the other, otherwise returns
811 ``False``.
812
813 .. method:: crosses(other)
814
815 Returns ``True`` if this geometry crosses the other, otherwise returns
816 ``False``.
817
818 .. method:: within(other)
819
820 Returns ``True`` if this geometry is contained within the other, otherwise
821 returns ``False``.
822
823 .. method:: contains(other)
824
825 Returns ``True`` if this geometry contains the other, otherwise returns
826 ``False``.
827
828 .. method:: overlaps(other)
829
830 Returns ``True`` if this geometry overlaps the other, otherwise returns
831 ``False``.
832
833 .. method:: boundary()
834
835 The boundary of this geometry, as a new :class:`OGRGeometry` object.
836
837 .. attribute:: convex_hull
838
839 The smallest convex polygon that contains this geometry, as a new
840 :class:`OGRGeometry` object.
841
842 .. method:: difference()
843
844 Returns the region consisting of the difference of this geometry and
845 the other, as a new :class:`OGRGeometry` object.
846
847 .. method:: intersection()
848
849 Returns the region consisting of the intersection of this geometry and
850 the other, as a new :class:`OGRGeometry` object.
851
852 .. method:: sym_difference()
853
854 Returns the region consisting of the symmetric difference of this
855 geometry and the other, as a new :class:`OGRGeometry` object.
856
857 .. method:: union()
858
859 Returns the region consisting of the union of this geometry and
860 the other, as a new :class:`OGRGeometry` object.
861
862 .. attribute:: centroid
863
864 Returns a :class:`Point` representing the centroid of this geometry.
865
866 .. versionchanged:: 5.1
867
868 ``centroid`` was promoted from a :class:`.Polygon` only attribute to
869 being available on all geometry types.
870
871 .. attribute:: tuple
872
873 Returns the coordinates of a point geometry as a tuple, the
874 coordinates of a line geometry as a tuple of tuples, and so forth:
875
876 .. code-block:: pycon
877
878 >>> OGRGeometry("POINT (1 2)").tuple
879 (1.0, 2.0)
880 >>> OGRGeometry("LINESTRING (1 2,3 4)").tuple
881 ((1.0, 2.0), (3.0, 4.0))
882
883 .. attribute:: coords
884
885 An alias for :attr:`tuple`.
886
887 .. class:: Point
888
889 .. attribute:: x
890
891 Returns the X coordinate of this point:
892
893 .. code-block:: pycon
894
895 >>> OGRGeometry("POINT (1 2)").x
896 1.0
897
898 .. attribute:: y
899
900 Returns the Y coordinate of this point:
901
902 .. code-block:: pycon
903
904 >>> OGRGeometry("POINT (1 2)").y
905 2.0
906
907 .. attribute:: z
908
909 Returns the Z coordinate of this point, or ``None`` if the point does not
910 have a Z coordinate:
911
912 .. code-block:: pycon
913
914 >>> OGRGeometry("POINT (1 2 3)").z
915 3.0
916
917 .. attribute:: m
918
919 .. versionadded:: 5.1
920
921 Returns the M coordinate of this point, or ``None`` if the Point does not
922 have an M coordinate:
923
924 .. code-block:: pycon
925
926 >>> OGRGeometry("POINT ZM (1 2 3 4)").m
927 4.0
928
929 .. class:: LineString
930
931 .. attribute:: x
932
933 Returns a list of X coordinates in this line:
934
935 .. code-block:: pycon
936
937 >>> OGRGeometry("LINESTRING (1 2,3 4)").x
938 [1.0, 3.0]
939
940 .. attribute:: y
941
942 Returns a list of Y coordinates in this line:
943
944 .. code-block:: pycon
945
946 >>> OGRGeometry("LINESTRING (1 2,3 4)").y
947 [2.0, 4.0]
948
949 .. attribute:: z
950
951 Returns a list of Z coordinates in this line, or ``None`` if the line does
952 not have Z coordinates:
953
954 .. code-block:: pycon
955
956 >>> OGRGeometry("LINESTRING (1 2 3,4 5 6)").z
957 [3.0, 6.0]
958
959 .. attribute:: m
960
961 .. versionadded:: 5.1
962
963 Returns a list of M coordinates in this line or ``None`` if the line does
964 not have M coordinates:
965
966 .. code-block:: pycon
967
968 >>> OGRGeometry("LINESTRING(0 1 2 10, 1 2 3 11, 2 3 4 12)").m
969 [10.0, 11.0, 12.0]
970
971 .. class:: Polygon
972
973 .. attribute:: shell
974
975 Returns the shell or exterior ring of this polygon, as a ``LinearRing``
976 geometry.
977
978 .. attribute:: exterior_ring
979
980 An alias for :attr:`shell`.
981
982 .. class:: GeometryCollection
983
984 .. method:: add(geom)
985
986 Adds a geometry to this geometry collection. Not applicable to other
987 geometry types.
988
989 ``OGRGeomType``
990 ---------------
991
992 .. class:: OGRGeomType(type_input)
993
994 This class allows for the representation of an OGR geometry type
995 in any of several ways:
996
997 .. code-block:: pycon
998
999 >>> from django.contrib.gis.gdal import OGRGeomType
1000 >>> gt1 = OGRGeomType(3) # Using an integer for the type
1001 >>> gt2 = OGRGeomType("Polygon") # Using a string
1002 >>> gt3 = OGRGeomType("POLYGON") # It's case-insensitive
1003 >>> print(gt1 == 3, gt1 == "Polygon") # Equivalence works w/non-OGRGeomType objects
1004 True True
1005
1006 .. attribute:: name
1007
1008 Returns a short-hand string form of the OGR Geometry type:
1009
1010 .. code-block:: pycon
1011
1012 >>> gt1.name
1013 'Polygon'
1014
1015 .. attribute:: num
1016
1017 Returns the number corresponding to the OGR geometry type:
1018
1019 .. code-block:: pycon
1020
1021 >>> gt1.num
1022 3
1023
1024 .. attribute:: django
1025
1026 Returns the Django field type (a subclass of GeometryField) to use for
1027 storing this OGR type, or ``None`` if there is no appropriate Django type:
1028
1029 .. code-block:: pycon
1030
1031 >>> gt1.django
1032 'PolygonField'
1033
1034 ``Envelope``
1035 ------------
1036
1037 .. class:: Envelope(*args)
1038
1039 Represents an OGR Envelope structure that contains the minimum and maximum
1040 X, Y coordinates for a rectangle bounding box. The naming of the variables
1041 is compatible with the OGR Envelope C structure.
1042
1043 .. attribute:: min_x
1044
1045 The value of the minimum X coordinate.
1046
1047 .. attribute:: min_y
1048
1049 The value of the maximum X coordinate.
1050
1051 .. attribute:: max_x
1052
1053 The value of the minimum Y coordinate.
1054
1055 .. attribute:: max_y
1056
1057 The value of the maximum Y coordinate.
1058
1059 .. attribute:: ur
1060
1061 The upper-right coordinate, as a tuple.
1062
1063 .. attribute:: ll
1064
1065 The lower-left coordinate, as a tuple.
1066
1067 .. attribute:: tuple
1068
1069 A tuple representing the envelope.
1070
1071 .. attribute:: wkt
1072
1073 A string representing this envelope as a polygon in WKT format.
1074
1075 .. method:: expand_to_include(*args)
1076
1077 Coordinate System Objects
1078 =========================
1079
1080 ``SpatialReference``
1081 --------------------
1082
1083 .. class:: SpatialReference(srs_input)
1084
1085 Spatial reference objects are initialized on the given ``srs_input``,
1086 which may be one of the following:
1087
1088 * OGC Well Known Text (WKT) (a string)
1089 * EPSG code (integer or string)
1090 * PROJ string
1091 * A shorthand string for well-known standards (``'WGS84'``, ``'WGS72'``,
1092 ``'NAD27'``, ``'NAD83'``)
1093
1094 Example:
1095
1096 .. code-block:: pycon
1097
1098 >>> wgs84 = SpatialReference("WGS84") # shorthand string
1099 >>> wgs84 = SpatialReference(4326) # EPSG code
1100 >>> wgs84 = SpatialReference("EPSG:4326") # EPSG string
1101 >>> proj = "+proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs "
1102 >>> wgs84 = SpatialReference(proj) # PROJ string
1103 >>> wgs84 = SpatialReference("""GEOGCS["WGS 84",
1104 ... DATUM["WGS_1984",
1105 ... SPHEROID["WGS 84",6378137,298.257223563,
1106 ... AUTHORITY["EPSG","7030"]],
1107 ... AUTHORITY["EPSG","6326"]],
1108 ... PRIMEM["Greenwich",0,
1109 ... AUTHORITY["EPSG","8901"]],
1110 ... UNIT["degree",0.01745329251994328,
1111 ... AUTHORITY["EPSG","9122"]],
1112 ... AUTHORITY["EPSG","4326"]]""") # OGC WKT
1113
1114 .. method:: __getitem__(target)
1115
1116 Returns the value of the given string attribute node, ``None`` if the node
1117 doesn't exist. Can also take a tuple as a parameter, (target, child), where
1118 child is the index of the attribute in the WKT. For example:
1119
1120 .. code-block:: pycon
1121
1122 >>> wkt = 'GEOGCS["WGS 84", DATUM["WGS_1984, ... AUTHORITY["EPSG","4326"]]'
1123 >>> srs = SpatialReference(wkt) # could also use 'WGS84', or 4326
1124 >>> print(srs["GEOGCS"])
1125 WGS 84
1126 >>> print(srs["DATUM"])
1127 WGS_1984
1128 >>> print(srs["AUTHORITY"])
1129 EPSG
1130 >>> print(srs["AUTHORITY", 1]) # The authority value
1131 4326
1132 >>> print(srs["TOWGS84", 4]) # the fourth value in this wkt
1133 0
1134 >>> print(srs["UNIT|AUTHORITY"]) # For the units authority, have to use the pipe symbol.
1135 EPSG
1136 >>> print(srs["UNIT|AUTHORITY", 1]) # The authority value for the units
1137 9122
1138
1139 .. method:: attr_value(target, index=0)
1140
1141 The attribute value for the given target node (e.g. ``'PROJCS'``).
1142 The index keyword specifies an index of the child node to return.
1143
1144 .. method:: auth_name(target)
1145
1146 Returns the authority name for the given string target node.
1147
1148 .. method:: auth_code(target)
1149
1150 Returns the authority code for the given string target node.
1151
1152 .. method:: clone()
1153
1154 Returns a clone of this spatial reference object.
1155
1156 .. method:: identify_epsg()
1157
1158 This method inspects the WKT of this ``SpatialReference`` and will add EPSG
1159 authority nodes where an EPSG identifier is applicable.
1160
1161 .. method:: from_esri()
1162
1163 Morphs this SpatialReference from ESRI's format to EPSG
1164
1165 .. method:: to_esri()
1166
1167 Morphs this SpatialReference to ESRI's format.
1168
1169 .. method:: validate()
1170
1171 Checks to see if the given spatial reference is valid, if not
1172 an exception will be raised.
1173
1174 .. method:: import_epsg(epsg)
1175
1176 Import spatial reference from EPSG code.
1177
1178 .. method:: import_proj(proj)
1179
1180 Import spatial reference from PROJ string.
1181
1182 .. method:: import_user_input(user_input)
1183
1184 .. method:: import_wkt(wkt)
1185
1186 Import spatial reference from WKT.
1187
1188 .. method:: import_xml(xml)
1189
1190 Import spatial reference from XML.
1191
1192 .. attribute:: name
1193
1194 Returns the name of this Spatial Reference.
1195
1196 .. attribute:: srid
1197
1198 Returns the SRID of top-level authority, or ``None`` if undefined.
1199
1200 .. attribute:: linear_name
1201
1202 Returns the name of the linear units.
1203
1204 .. attribute:: linear_units
1205
1206 Returns the value of the linear units.
1207
1208 .. attribute:: angular_name
1209
1210 Returns the name of the angular units."
1211
1212 .. attribute:: angular_units
1213
1214 Returns the value of the angular units.
1215
1216 .. attribute:: units
1217
1218 Returns a 2-tuple of the units value and the units name and will
1219 automatically determines whether to return the linear or angular units.
1220
1221 .. attribute:: ellipsoid
1222
1223 Returns a tuple of the ellipsoid parameters for this spatial reference:
1224 (semimajor axis, semiminor axis, and inverse flattening).
1225
1226 .. attribute:: semi_major
1227
1228 Returns the semi major axis of the ellipsoid for this spatial reference.
1229
1230 .. attribute:: semi_minor
1231
1232 Returns the semi minor axis of the ellipsoid for this spatial reference.
1233
1234 .. attribute:: inverse_flattening
1235
1236 Returns the inverse flattening of the ellipsoid for this spatial reference.
1237
1238 .. attribute:: geographic
1239
1240 Returns ``True`` if this spatial reference is geographic (root node is
1241 ``GEOGCS``).
1242
1243 .. attribute:: local
1244
1245 Returns ``True`` if this spatial reference is local (root node is
1246 ``LOCAL_CS``).
1247
1248 .. attribute:: projected
1249
1250 Returns ``True`` if this spatial reference is a projected coordinate system
1251 (root node is ``PROJCS``).
1252
1253 .. attribute:: wkt
1254
1255 Returns the WKT representation of this spatial reference.
1256
1257 .. attribute:: pretty_wkt
1258
1259 Returns the 'pretty' representation of the WKT.
1260
1261 .. attribute:: proj
1262
1263 Returns the PROJ representation for this spatial reference.
1264
1265 .. attribute:: proj4
1266
1267 Alias for :attr:`SpatialReference.proj`.
1268
1269 .. attribute:: xml
1270
1271 Returns the XML representation of this spatial reference.
1272
1273 ``CoordTransform``
1274 ------------------
1275
1276 .. class:: CoordTransform(source, target)
1277
1278 Represents a coordinate system transform. It is initialized with two
1279 :class:`SpatialReference`, representing the source and target coordinate
1280 systems, respectively. These objects should be used when performing the same
1281 coordinate transformation repeatedly on different geometries:
1282
1283 .. code-block:: pycon
1284
1285 >>> ct = CoordTransform(SpatialReference("WGS84"), SpatialReference("NAD83"))
1286 >>> for feat in layer:
1287 ... geom = feat.geom # getting clone of feature geometry
1288 ... geom.transform(ct) # transforming
1289 ...
1290
1291 .. _raster-data-source-objects:
1292
1293 Raster Data Objects
1294 ===================
1295
1296 ``GDALRaster``
1297 ----------------
1298
1299 :class:`GDALRaster` is a wrapper for the GDAL raster source object that
1300 supports reading data from a variety of GDAL-supported geospatial file
1301 formats and data sources using a consistent interface. Each
1302 data source is represented by a :class:`GDALRaster` object which contains
1303 one or more layers of data named bands. Each band, represented by a
1304 :class:`GDALBand` object, contains georeferenced image data. For example, an RGB
1305 image is represented as three bands: one for red, one for green, and one for
1306 blue.
1307
1308 .. note::
1309
1310 For raster data there is no difference between a raster instance and its
1311 data source. Unlike for the Geometry objects, :class:`GDALRaster` objects are
1312 always a data source. Temporary rasters can be instantiated in memory
1313 using the corresponding driver, but they will be of the same class as file-based
1314 raster sources.
1315
1316 .. class:: GDALRaster(ds_input, write=False)
1317
1318 The constructor for ``GDALRaster`` accepts two parameters. The first
1319 parameter defines the raster source, and the second parameter defines if a
1320 raster should be opened in write mode. For newly-created rasters, the second
1321 parameter is ignored and the new raster is always created in write mode.
1322
1323 The first parameter can take three forms: a string or
1324 :class:`~pathlib.Path` representing a file path (filesystem or GDAL virtual
1325 filesystem), a dictionary with values defining a new raster, or a bytes
1326 object representing a raster file.
1327
1328 If the input is a file path, the raster is opened from there. If the input
1329 is raw data in a dictionary, the parameters ``width``, ``height``, and
1330 ``srid`` are required. If the input is a bytes object, it will be opened
1331 using a GDAL virtual filesystem.
1332
1333 For a detailed description of how to create rasters using dictionary input,
1334 see :ref:`gdal-raster-ds-input`. For a detailed description of how to
1335 create rasters in the virtual filesystem, see :ref:`gdal-raster-vsimem`.
1336
1337 The following example shows how rasters can be created from different input
1338 sources (using the sample data from the GeoDjango tests; see also the
1339 :ref:`gdal_sample_data` section).
1340
1341 .. code-block:: pycon
1342
1343 >>> from django.contrib.gis.gdal import GDALRaster
1344 >>> rst = GDALRaster("/path/to/your/raster.tif", write=False)
1345 >>> rst.name
1346 '/path/to/your/raster.tif'
1347 >>> rst.width, rst.height # This file has 163 x 174 pixels
1348 (163, 174)
1349 >>> rst = GDALRaster(
1350 ... { # Creates an in-memory raster
1351 ... "srid": 4326,
1352 ... "width": 4,
1353 ... "height": 4,
1354 ... "datatype": 1,
1355 ... "bands": [
1356 ... {
1357 ... "data": (2, 3),
1358 ... "offset": (1, 1),
1359 ... "size": (2, 2),
1360 ... "shape": (2, 1),
1361 ... "nodata_value": 5,
1362 ... }
1363 ... ],
1364 ... }
1365 ... )
1366 >>> rst.srs.srid
1367 4326
1368 >>> rst.width, rst.height
1369 (4, 4)
1370 >>> rst.bands[0].data()
1371 array([[5, 5, 5, 5],
1372 [5, 2, 3, 5],
1373 [5, 2, 3, 5],
1374 [5, 5, 5, 5]], dtype=uint8)
1375 >>> rst_file = open("/path/to/your/raster.tif", "rb")
1376 >>> rst_bytes = rst_file.read()
1377 >>> rst = GDALRaster(rst_bytes)
1378 >>> rst.is_vsi_based
1379 True
1380 >>> rst.name # Stored in a random path in the vsimem filesystem.
1381 '/vsimem/da300bdb-129d-49a8-b336-e410a9428dad'
1382
1383 .. attribute:: name
1384
1385 The name of the source which is equivalent to the input file path or the name
1386 provided upon instantiation.
1387
1388 .. code-block:: pycon
1389
1390 >>> GDALRaster({"width": 10, "height": 10, "name": "myraster", "srid": 4326}).name
1391 'myraster'
1392
1393 .. attribute:: driver
1394
1395 The name of the GDAL driver used to handle the input file. For ``GDALRaster``\s created
1396 from a file, the driver type is detected automatically. The creation of rasters from
1397 scratch is an in-memory raster by default (``'MEM'``), but can be
1398 altered as needed. For instance, use ``GTiff`` for a ``GeoTiff`` file.
1399 For a list of file types, see also the `GDAL Raster Formats`__ list.
1400
1401 __ https://gdal.org/drivers/raster/
1402
1403 An in-memory raster is created through the following example:
1404
1405 .. code-block:: pycon
1406
1407 >>> GDALRaster({"width": 10, "height": 10, "srid": 4326}).driver.name
1408 'MEM'
1409
1410 A file based GeoTiff raster is created through the following example:
1411
1412 .. code-block:: pycon
1413
1414 >>> import tempfile
1415 >>> rstfile = tempfile.NamedTemporaryFile(suffix=".tif")
1416 >>> rst = GDALRaster(
1417 ... {
1418 ... "driver": "GTiff",
1419 ... "name": rstfile.name,
1420 ... "srid": 4326,
1421 ... "width": 255,
1422 ... "height": 255,
1423 ... "nr_of_bands": 1,
1424 ... }
1425 ... )
1426 >>> rst.name
1427 '/tmp/tmp7x9H4J.tif' # The exact filename will be different on your computer
1428 >>> rst.driver.name
1429 'GTiff'
1430
1431 .. attribute:: width
1432
1433 The width of the source in pixels (X-axis).
1434
1435 .. code-block:: pycon
1436
1437 >>> GDALRaster({"width": 10, "height": 20, "srid": 4326}).width
1438 10
1439
1440 .. attribute:: height
1441
1442 The height of the source in pixels (Y-axis).
1443
1444 .. code-block:: pycon
1445
1446 >>> GDALRaster({"width": 10, "height": 20, "srid": 4326}).height
1447 20
1448
1449 .. attribute:: srs
1450
1451 The spatial reference system of the raster, as a
1452 :class:`SpatialReference` instance. The SRS can be changed by
1453 setting it to an other :class:`SpatialReference` or providing any input
1454 that is accepted by the :class:`SpatialReference` constructor.
1455
1456 .. code-block:: pycon
1457
1458 >>> rst = GDALRaster({"width": 10, "height": 20, "srid": 4326})
1459 >>> rst.srs.srid
1460 4326
1461 >>> rst.srs = 3086
1462 >>> rst.srs.srid
1463 3086
1464
1465 .. attribute:: srid
1466
1467 The Spatial Reference System Identifier (SRID) of the raster. This
1468 property is a shortcut to getting or setting the SRID through the
1469 :attr:`srs` attribute.
1470
1471 .. code-block:: pycon
1472
1473 >>> rst = GDALRaster({"width": 10, "height": 20, "srid": 4326})
1474 >>> rst.srid
1475 4326
1476 >>> rst.srid = 3086
1477 >>> rst.srid
1478 3086
1479 >>> rst.srs.srid # This is equivalent
1480 3086
1481
1482 .. attribute:: geotransform
1483
1484 The affine transformation matrix used to georeference the source, as a
1485 tuple of six coefficients which map pixel/line coordinates into
1486 georeferenced space using the following relationship::
1487
1488 Xgeo = GT(0) + Xpixel * GT(1) + Yline * GT(2)
1489 Ygeo = GT(3) + Xpixel * GT(4) + Yline * GT(5)
1490
1491 The same values can be retrieved by accessing the :attr:`origin`
1492 (indices 0 and 3), :attr:`scale` (indices 1 and 5) and :attr:`skew`
1493 (indices 2 and 4) properties.
1494
1495 The default is ``[0.0, 1.0, 0.0, 0.0, 0.0, -1.0]``.
1496
1497 .. code-block:: pycon
1498
1499 >>> rst = GDALRaster({"width": 10, "height": 20, "srid": 4326})
1500 >>> rst.geotransform
1501 [0.0, 1.0, 0.0, 0.0, 0.0, -1.0]
1502
1503 .. attribute:: origin
1504
1505 Coordinates of the top left origin of the raster in the spatial
1506 reference system of the source, as a point object with ``x`` and ``y``
1507 members.
1508
1509 .. code-block:: pycon
1510
1511 >>> rst = GDALRaster({"width": 10, "height": 20, "srid": 4326})
1512 >>> rst.origin
1513 [0.0, 0.0]
1514 >>> rst.origin.x = 1
1515 >>> rst.origin
1516 [1.0, 0.0]
1517
1518 .. attribute:: scale
1519
1520 Pixel width and height used for georeferencing the raster, as a point
1521 object with ``x`` and ``y`` members. See :attr:`geotransform` for more
1522 information.
1523
1524 .. code-block:: pycon
1525
1526 >>> rst = GDALRaster({"width": 10, "height": 20, "srid": 4326})
1527 >>> rst.scale
1528 [1.0, -1.0]
1529 >>> rst.scale.x = 2
1530 >>> rst.scale
1531 [2.0, -1.0]
1532
1533 .. attribute:: skew
1534
1535 Skew coefficients used to georeference the raster, as a point object
1536 with ``x`` and ``y`` members. In case of north up images, these
1537 coefficients are both ``0``.
1538
1539 .. code-block:: pycon
1540
1541 >>> rst = GDALRaster({"width": 10, "height": 20, "srid": 4326})
1542 >>> rst.skew
1543 [0.0, 0.0]
1544 >>> rst.skew.x = 3
1545 >>> rst.skew
1546 [3.0, 0.0]
1547
1548 .. attribute:: extent
1549
1550 Extent (boundary values) of the raster source, as a 4-tuple
1551 ``(xmin, ymin, xmax, ymax)`` in the spatial reference system of the
1552 source.
1553
1554 .. code-block:: pycon
1555
1556 >>> rst = GDALRaster({"width": 10, "height": 20, "srid": 4326})
1557 >>> rst.extent
1558 (0.0, -20.0, 10.0, 0.0)
1559 >>> rst.origin.x = 100
1560 >>> rst.extent
1561 (100.0, -20.0, 110.0, 0.0)
1562
1563 .. attribute:: bands
1564
1565 List of all bands of the source, as :class:`GDALBand` instances.
1566
1567 .. code-block:: pycon
1568
1569 >>> rst = GDALRaster(
1570 ... {
1571 ... "width": 1,
1572 ... "height": 2,
1573 ... "srid": 4326,
1574 ... "bands": [{"data": [0, 1]}, {"data": [2, 3]}],
1575 ... }
1576 ... )
1577 >>> len(rst.bands)
1578 2
1579 >>> rst.bands[1].data()
1580 array([[ 2., 3.]], dtype=float32)
1581
1582 .. method:: warp(ds_input, resampling='NearestNeighbour', max_error=0.0)
1583
1584 Returns a warped version of this raster.
1585
1586 The warping parameters can be specified through the ``ds_input``
1587 argument. The use of ``ds_input`` is analogous to the corresponding
1588 argument of the class constructor. It is a dictionary with the
1589 characteristics of the target raster. Allowed dictionary key values are
1590 width, height, SRID, origin, scale, skew, datatype, driver, and name
1591 (filename).
1592
1593 By default, the warp functions keeps most parameters equal to the
1594 values of the original source raster, so only parameters that should be
1595 changed need to be specified. Note that this includes the driver, so
1596 for file-based rasters the warp function will create a new raster on
1597 disk.
1598
1599 The only parameter that is set differently from the source raster is the
1600 name. The default value of the raster name is the name of the source
1601 raster appended with ``'_copy' + source_driver_name``. For file-based
1602 rasters it is recommended to provide the file path of the target raster.
1603
1604 The resampling algorithm used for warping can be specified with the
1605 ``resampling`` argument. The default is ``NearestNeighbor``, and the
1606 other allowed values are ``Bilinear``, ``Cubic``, ``CubicSpline``,
1607 ``Lanczos``, ``Average``, and ``Mode``.
1608
1609 The ``max_error`` argument can be used to specify the maximum error
1610 measured in input pixels that is allowed in approximating the
1611 transformation. The default is 0.0 for exact calculations.
1612
1613 For users familiar with ``GDAL``, this function has a similar
1614 functionality to the ``gdalwarp`` command-line utility.
1615
1616 For example, the warp function can be used for aggregating a raster to
1617 the double of its original pixel scale:
1618
1619 .. code-block:: pycon
1620
1621 >>> rst = GDALRaster(
1622 ... {
1623 ... "width": 6,
1624 ... "height": 6,
1625 ... "srid": 3086,
1626 ... "origin": [500000, 400000],
1627 ... "scale": [100, -100],
1628 ... "bands": [{"data": range(36), "nodata_value": 99}],
1629 ... }
1630 ... )
1631 >>> target = rst.warp({"scale": [200, -200], "width": 3, "height": 3})
1632 >>> target.bands[0].data()
1633 array([[ 7., 9., 11.],
1634 [ 19., 21., 23.],
1635 [ 31., 33., 35.]], dtype=float32)
1636
1637 .. method:: transform(srs, driver=None, name=None, resampling='NearestNeighbour', max_error=0.0)
1638
1639 Transforms this raster to a different spatial reference system
1640 (``srs``), which may be a :class:`SpatialReference` object, or any
1641 other input accepted by :class:`SpatialReference` (including spatial
1642 reference WKT and PROJ strings, or an integer SRID).
1643
1644 It calculates the bounds and scale of the current raster in the new
1645 spatial reference system and warps the raster using the
1646 :attr:`~GDALRaster.warp` function.
1647
1648 By default, the driver of the source raster is used and the name of the
1649 raster is the original name appended with
1650 ``'_copy' + source_driver_name``. A different driver or name can be
1651 specified with the ``driver`` and ``name`` arguments.
1652
1653 The default resampling algorithm is ``NearestNeighbour`` but can be
1654 changed using the ``resampling`` argument. The default maximum allowed
1655 error for resampling is 0.0 and can be changed using the ``max_error``
1656 argument. Consult the :attr:`~GDALRaster.warp` documentation for detail
1657 on those arguments.
1658
1659 .. code-block:: pycon
1660
1661 >>> rst = GDALRaster(
1662 ... {
1663 ... "width": 6,
1664 ... "height": 6,
1665 ... "srid": 3086,
1666 ... "origin": [500000, 400000],
1667 ... "scale": [100, -100],
1668 ... "bands": [{"data": range(36), "nodata_value": 99}],
1669 ... }
1670 ... )
1671 >>> target_srs = SpatialReference(4326)
1672 >>> target = rst.transform(target_srs)
1673 >>> target.origin
1674 [-82.98492744885776, 27.601924753080144]
1675
1676 .. attribute:: info
1677
1678 Returns a string with a summary of the raster. This is equivalent to
1679 the `gdalinfo`__ command line utility.
1680
1681 __ https://gdal.org/programs/gdalinfo.html
1682
1683 .. attribute:: metadata
1684
1685 The metadata of this raster, represented as a nested dictionary. The
1686 first-level key is the metadata domain. The second-level contains the
1687 metadata item names and values from each domain.
1688
1689 To set or update a metadata item, pass the corresponding metadata item
1690 to the method using the nested structure described above. Only keys
1691 that are in the specified dictionary are updated; the rest of the
1692 metadata remains unchanged.
1693
1694 To remove a metadata item, use ``None`` as the metadata value.
1695
1696 .. code-block:: pycon
1697
1698 >>> rst = GDALRaster({"width": 10, "height": 20, "srid": 4326})
1699 >>> rst.metadata
1700 {}
1701 >>> rst.metadata = {"DEFAULT": {"OWNER": "Django", "VERSION": "1.0"}}
1702 >>> rst.metadata
1703 {'DEFAULT': {'OWNER': 'Django', 'VERSION': '1.0'}}
1704 >>> rst.metadata = {"DEFAULT": {"OWNER": None, "VERSION": "2.0"}}
1705 >>> rst.metadata
1706 {'DEFAULT': {'VERSION': '2.0'}}
1707
1708 .. attribute:: vsi_buffer
1709
1710 A ``bytes`` representation of this raster. Returns ``None`` for rasters
1711 that are not stored in GDAL's virtual filesystem.
1712
1713 .. attribute:: is_vsi_based
1714
1715 A boolean indicating if this raster is stored in GDAL's virtual
1716 filesystem.
1717
1718 ``GDALBand``
1719 ------------
1720
1721 .. class:: GDALBand
1722
1723 ``GDALBand`` instances are not created explicitly, but rather obtained
1724 from a :class:`GDALRaster` object, through its :attr:`~GDALRaster.bands`
1725 attribute. The GDALBands contain the actual pixel values of the raster.
1726
1727 .. attribute:: description
1728
1729 The name or description of the band, if any.
1730
1731 .. attribute:: width
1732
1733 The width of the band in pixels (X-axis).
1734
1735 .. attribute:: height
1736
1737 The height of the band in pixels (Y-axis).
1738
1739 .. attribute:: pixel_count
1740
1741 The total number of pixels in this band. Is equal to ``width * height``.
1742
1743 .. method:: statistics(refresh=False, approximate=False)
1744
1745 Compute statistics on the pixel values of this band. The return value
1746 is a tuple with the following structure:
1747 ``(minimum, maximum, mean, standard deviation)``.
1748
1749 If the ``approximate`` argument is set to ``True``, the statistics may
1750 be computed based on overviews or a subset of image tiles.
1751
1752 If the ``refresh`` argument is set to ``True``, the statistics will be
1753 computed from the data directly, and the cache will be updated with the
1754 result.
1755
1756 If a persistent cache value is found, that value is returned. For
1757 raster formats using Persistent Auxiliary Metadata (PAM) services, the
1758 statistics might be cached in an auxiliary file. In some cases this
1759 metadata might be out of sync with the pixel values or cause values
1760 from a previous call to be returned which don't reflect the value of
1761 the ``approximate`` argument. In such cases, use the ``refresh``
1762 argument to get updated values and store them in the cache.
1763
1764 For empty bands (where all pixel values are "no data"), all statistics
1765 are returned as ``None``.
1766
1767 The statistics can also be retrieved directly by accessing the
1768 :attr:`min`, :attr:`max`, :attr:`mean`, and :attr:`std` properties.
1769
1770 .. attribute:: min
1771
1772 The minimum pixel value of the band (excluding the "no data" value).
1773
1774 .. attribute:: max
1775
1776 The maximum pixel value of the band (excluding the "no data" value).
1777
1778 .. attribute:: mean
1779
1780 The mean of all pixel values of the band (excluding the "no data"
1781 value).
1782
1783 .. attribute:: std
1784
1785 The standard deviation of all pixel values of the band (excluding the
1786 "no data" value).
1787
1788 .. attribute:: nodata_value
1789
1790 The "no data" value for a band is generally a special marker value used
1791 to mark pixels that are not valid data. Such pixels should generally not
1792 be displayed, nor contribute to analysis operations.
1793
1794 To delete an existing "no data" value, set this property to ``None``.
1795
1796 .. method:: datatype(as_string=False)
1797
1798 The data type contained in the band, as an integer constant between 0
1799 (Unknown) and 14. If ``as_string`` is ``True``, the data type is
1800 returned as a string. Check out the "GDAL Pixel Type" column in the
1801 :ref:`datatype value table <gdal-raster-datatype>` for possible values.
1802
1803 .. method:: color_interp(as_string=False)
1804
1805 The color interpretation for the band, as an integer between 0and 16.
1806 If ``as_string`` is ``True``, the data type is returned as a string
1807 with the following possible values:
1808 ``GCI_Undefined``, ``GCI_GrayIndex``, ``GCI_PaletteIndex``,
1809 ``GCI_RedBand``, ``GCI_GreenBand``, ``GCI_BlueBand``, ``GCI_AlphaBand``,
1810 ``GCI_HueBand``, ``GCI_SaturationBand``, ``GCI_LightnessBand``,
1811 ``GCI_CyanBand``, ``GCI_MagentaBand``, ``GCI_YellowBand``,
1812 ``GCI_BlackBand``, ``GCI_YCbCr_YBand``, ``GCI_YCbCr_CbBand``, and
1813 ``GCI_YCbCr_CrBand``. ``GCI_YCbCr_CrBand`` also represents ``GCI_Max``
1814 because both correspond to the integer 16, but only ``GCI_YCbCr_CrBand``
1815 is returned as a string.
1816
1817 .. method:: data(data=None, offset=None, size=None, shape=None)
1818
1819 The accessor to the pixel values of the ``GDALBand``. Returns the complete
1820 data array if no parameters are provided. A subset of the pixel array can
1821 be requested by specifying an offset and block size as tuples.
1822
1823 If NumPy is available, the data is returned as NumPy array. For performance
1824 reasons, it is highly recommended to use NumPy.
1825
1826 Data is written to the ``GDALBand`` if the ``data`` parameter is provided.
1827 The input can be of one of the following types - packed string, buffer, list,
1828 array, and NumPy array. The number of items in the input should normally
1829 correspond to the total number of pixels in the band, or to the number
1830 of pixels for a specific block of pixel values if the ``offset`` and
1831 ``size`` parameters are provided.
1832
1833 If the number of items in the input is different from the target pixel
1834 block, the ``shape`` parameter must be specified. The shape is a tuple
1835 that specifies the width and height of the input data in pixels. The
1836 data is then replicated to update the pixel values of the selected
1837 block. This is useful to fill an entire band with a single value, for
1838 instance.
1839
1840 For example:
1841
1842 .. code-block:: pycon
1843
1844 >>> rst = GDALRaster(
1845 ... {"width": 4, "height": 4, "srid": 4326, "datatype": 1, "nr_of_bands": 1}
1846 ... )
1847 >>> bnd = rst.bands[0]
1848 >>> bnd.data(range(16))
1849 >>> bnd.data()
1850 array([[ 0, 1, 2, 3],
1851 [ 4, 5, 6, 7],
1852 [ 8, 9, 10, 11],
1853 [12, 13, 14, 15]], dtype=int8)
1854 >>> bnd.data(offset=(1, 1), size=(2, 2))
1855 array([[ 5, 6],
1856 [ 9, 10]], dtype=int8)
1857 >>> bnd.data(data=[-1, -2, -3, -4], offset=(1, 1), size=(2, 2))
1858 >>> bnd.data()
1859 array([[ 0, 1, 2, 3],
1860 [ 4, -1, -2, 7],
1861 [ 8, -3, -4, 11],
1862 [12, 13, 14, 15]], dtype=int8)
1863 >>> bnd.data(data="\x9d\xa8\xb3\xbe", offset=(1, 1), size=(2, 2))
1864 >>> bnd.data()
1865 array([[ 0, 1, 2, 3],
1866 [ 4, -99, -88, 7],
1867 [ 8, -77, -66, 11],
1868 [ 12, 13, 14, 15]], dtype=int8)
1869 >>> bnd.data([1], shape=(1, 1))
1870 >>> bnd.data()
1871 array([[1, 1, 1, 1],
1872 [1, 1, 1, 1],
1873 [1, 1, 1, 1],
1874 [1, 1, 1, 1]], dtype=uint8)
1875 >>> bnd.data(range(4), shape=(1, 4))
1876 array([[0, 0, 0, 0],
1877 [1, 1, 1, 1],
1878 [2, 2, 2, 2],
1879 [3, 3, 3, 3]], dtype=uint8)
1880
1881 .. attribute:: metadata
1882
1883 The metadata of this band. The functionality is identical to
1884 :attr:`GDALRaster.metadata`.
1885
1886 .. _gdal-raster-ds-input:
1887
1888 Creating rasters from data
1889 --------------------------
1890
1891 This section describes how to create rasters from scratch using the
1892 ``ds_input`` parameter.
1893
1894 A new raster is created when a ``dict`` is passed to the :class:`GDALRaster`
1895 constructor. The dictionary contains defining parameters of the new raster,
1896 such as the origin, size, or spatial reference system. The dictionary can also
1897 contain pixel data and information about the format of the new raster. The
1898 resulting raster can therefore be file-based or memory-based, depending on the
1899 driver specified.
1900
1901 There's no standard for describing raster data in a dictionary or JSON flavor.
1902 The definition of the dictionary input to the :class:`GDALRaster` class is
1903 therefore specific to Django. It's inspired by the `geojson`__ format, but the
1904 ``geojson`` standard is currently limited to vector formats.
1905
1906 Examples of using the different keys when creating rasters can be found in the
1907 documentation of the corresponding attributes and methods of the
1908 :class:`GDALRaster` and :class:`GDALBand` classes.
1909
1910 __ https://geojson.org/
1911
1912 The ``ds_input`` dictionary
1913 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
1914
1915 Only a few keys are required in the ``ds_input`` dictionary to create a raster:
1916 ``width``, ``height``, and ``srid``. All other parameters have default values
1917 (see the table below). The list of keys that can be passed in the ``ds_input``
1918 dictionary is closely related but not identical to the :class:`GDALRaster`
1919 properties. Many of the parameters are mapped directly to those properties;
1920 the others are described below.
1921
1922 The following table describes all keys that can be set in the ``ds_input``
1923 dictionary.
1924
1925 ================= ======== ==================================================
1926 Key Default Usage
1927 ================= ======== ==================================================
1928 ``srid`` required Mapped to the :attr:`~GDALRaster.srid` attribute
1929 ``width`` required Mapped to the :attr:`~GDALRaster.width` attribute
1930 ``height`` required Mapped to the :attr:`~GDALRaster.height` attribute
1931 ``driver`` ``MEM`` Mapped to the :attr:`~GDALRaster.driver` attribute
1932 ``name`` ``''`` See below
1933 ``origin`` ``0`` Mapped to the :attr:`~GDALRaster.origin` attribute
1934 ``scale`` ``0`` Mapped to the :attr:`~GDALRaster.scale` attribute
1935 ``skew`` ``0`` Mapped to the :attr:`~GDALRaster.width` attribute
1936 ``bands`` ``[]`` See below
1937 ``nr_of_bands`` ``0`` See below
1938 ``datatype`` ``6`` See below
1939 ``papsz_options`` ``{}`` See below
1940 ================= ======== ==================================================
1941
1942 .. object:: name
1943
1944 String representing the name of the raster. When creating a file-based
1945 raster, this parameter must be the file path for the new raster. If the
1946 name starts with ``/vsimem/``, the raster is created in GDAL's virtual
1947 filesystem.
1948
1949 .. _gdal-raster-datatype:
1950
1951 .. object:: datatype
1952
1953 Integer representing the data type for all the bands. Defaults to ``6``
1954 (Float32). All bands of a new raster are required to have the same datatype.
1955 The value mapping is:
1956
1957 ===== =============== ===================================
1958 Value GDAL Pixel Type Description
1959 ===== =============== ===================================
1960 1 GDT_Byte 8 bit unsigned integer
1961 2 GDT_UInt16 16 bit unsigned integer
1962 3 GDT_Int16 16 bit signed integer
1963 4 GDT_UInt32 32 bit unsigned integer
1964 5 GDT_Int32 32 bit signed integer
1965 6 GDT_Float32 32 bit floating point
1966 7 GDT_Float64 64 bit floating point
1967 12 GDT_UInt64 64 bit unsigned integer (GDAL 3.5+)
1968 13 GDT_Int64 64 bit signed integer (GDAL 3.5+)
1969 14 GDT_Int8 8 bit signed integer (GDAL 3.7+)
1970 ===== =============== ===================================
1971
1972 .. object:: nr_of_bands
1973
1974 Integer representing the number of bands of the raster. A raster can be
1975 created without passing band data upon creation. If the number of bands
1976 isn't specified, it's automatically calculated from the length of the
1977 ``bands`` input. The number of bands can't be changed after creation.
1978
1979 .. object:: bands
1980
1981 A list of ``band_input`` dictionaries with band input data. The resulting
1982 band indices are the same as in the list provided. The definition of the
1983 band input dictionary is given below. If band data isn't provided, the
1984 raster bands values are instantiated as an array of zeros and the "no
1985 data" value is set to ``None``.
1986
1987 .. object:: papsz_options
1988
1989 A dictionary with raster creation options. The key-value pairs of the
1990 input dictionary are passed to the driver on creation of the raster.
1991
1992 The available options are driver-specific and are described in the
1993 documentation of each driver.
1994
1995 The values in the dictionary are not case-sensitive and are automatically
1996 converted to the correct string format upon creation.
1997
1998 The following example uses some of the options available for the
1999 `GTiff driver`__. The result is a compressed raster with an internal tiling
2000 scheme. The internal tiles have a block size of 23 by 23:
2001
2002 .. code-block:: pycon
2003
2004 >>> GDALRaster(
2005 ... {
2006 ... "driver": "GTiff",
2007 ... "name": "/path/to/new/file.tif",
2008 ... "srid": 4326,
2009 ... "width": 255,
2010 ... "height": 255,
2011 ... "nr_of_bands": 1,
2012 ... "papsz_options": {
2013 ... "compress": "packbits",
2014 ... "tiled": "yes",
2015 ... "blockxsize": 23,
2016 ... "blockysize": 23,
2017 ... },
2018 ... }
2019 ... )
2020
2021 __ https://gdal.org/drivers/raster/gtiff.html
2022
2023 The ``band_input`` dictionary
2024 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2025
2026 The ``bands`` key in the ``ds_input`` dictionary is a list of ``band_input``
2027 dictionaries. Each ``band_input`` dictionary can contain pixel values and the
2028 "no data" value to be set on the bands of the new raster. The data array can
2029 have the full size of the new raster or be smaller. For arrays that are smaller
2030 than the full raster, the ``size``, ``shape``, and ``offset`` keys control the
2031 pixel values. The corresponding keys are passed to the :meth:`~GDALBand.data`
2032 method. Their functionality is the same as setting the band data with that
2033 method. The following table describes the keys that can be used.
2034
2035 ================ ================================= ======================================================
2036 Key Default Usage
2037 ================ ================================= ======================================================
2038 ``nodata_value`` ``None`` Mapped to the :attr:`~GDALBand.nodata_value` attribute
2039 ``data`` Same as ``nodata_value`` or ``0`` Passed to the :meth:`~GDALBand.data` method
2040 ``size`` ``(with, height)`` of raster Passed to the :meth:`~GDALBand.data` method
2041 ``shape`` Same as size Passed to the :meth:`~GDALBand.data` method
2042 ``offset`` ``(0, 0)`` Passed to the :meth:`~GDALBand.data` method
2043 ================ ================================= ======================================================
2044
2045 .. _gdal-raster-vsimem:
2046
2047 Using GDAL's Virtual Filesystem
2048 -------------------------------
2049
2050 GDAL can access files stored in the filesystem, but also supports virtual
2051 filesystems to abstract accessing other kind of files, such as compressed,
2052 encrypted, or remote files.
2053
2054 Using memory-based Virtual Filesystem
2055 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2056
2057 GDAL has an internal memory-based filesystem, which allows treating blocks of
2058 memory as files. It can be used to read and write :class:`GDALRaster` objects
2059 to and from binary file buffers.
2060
2061 This is useful in web contexts where rasters might be obtained as a buffer
2062 from a remote storage or returned from a view without being written to disk.
2063
2064 :class:`GDALRaster` objects are created in the virtual filesystem when a
2065 ``bytes`` object is provided as input, or when the file path starts with
2066 ``/vsimem/``.
2067
2068 Input provided as ``bytes`` has to be a full binary representation of a file.
2069 For instance:
2070
2071 .. code-block:: pycon
2072
2073 # Read a raster as a file object from a remote source.
2074 >>> from urllib.request import urlopen
2075 >>> dat = urlopen("https://example.com/raster.tif").read()
2076 # Instantiate a raster from the bytes object.
2077 >>> rst = GDALRaster(dat)
2078 # The name starts with /vsimem/, indicating that the raster lives in the
2079 # virtual filesystem.
2080 >>> rst.name
2081 '/vsimem/da300bdb-129d-49a8-b336-e410a9428dad'
2082
2083 To create a new virtual file-based raster from scratch, use the ``ds_input``
2084 dictionary representation and provide a ``name`` argument that starts with
2085 ``/vsimem/`` (for detail of the dictionary representation, see
2086 :ref:`gdal-raster-ds-input`). For virtual file-based rasters, the
2087 :attr:`~GDALRaster.vsi_buffer` attribute returns the ``bytes`` representation
2088 of the raster.
2089
2090 Here's how to create a raster and return it as a file in an
2091 :class:`~django.http.HttpResponse`:
2092
2093 .. code-block:: pycon
2094
2095 >>> from django.http import HttpResponse
2096 >>> rst = GDALRaster(
2097 ... {
2098 ... "name": "/vsimem/temporarymemfile",
2099 ... "driver": "tif",
2100 ... "width": 6,
2101 ... "height": 6,
2102 ... "srid": 3086,
2103 ... "origin": [500000, 400000],
2104 ... "scale": [100, -100],
2105 ... "bands": [{"data": range(36), "nodata_value": 99}],
2106 ... }
2107 ... )
2108 >>> HttpResponse(rast.vsi_buffer, "image/tiff")
2109
2110 Using other Virtual Filesystems
2111 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2112
2113 Depending on the local build of GDAL other virtual filesystems may be
2114 supported. You can use them by prepending the provided path with the
2115 appropriate ``/vsi*/`` prefix. See the `GDAL Virtual Filesystems
2116 documentation`_ for more details.
2117
2118 .. warning:
2119
2120 Rasters with names starting with `/vsi*/` will be treated as rasters from
2121 the GDAL virtual filesystems. Django doesn't perform any extra validation.
2122
2123 Compressed rasters
2124 ^^^^^^^^^^^^^^^^^^
2125
2126 Instead decompressing the file and instantiating the resulting raster, GDAL can
2127 directly access compressed files using the ``/vsizip/``, ``/vsigzip/``, or
2128 ``/vsitar/`` virtual filesystems:
2129
2130 .. code-block:: pycon
2131
2132 >>> from django.contrib.gis.gdal import GDALRaster
2133 >>> rst = GDALRaster("/vsizip/path/to/your/file.zip/path/to/raster.tif")
2134 >>> rst = GDALRaster("/vsigzip/path/to/your/file.gz")
2135 >>> rst = GDALRaster("/vsitar/path/to/your/file.tar/path/to/raster.tif")
2136
2137 Network rasters
2138 ^^^^^^^^^^^^^^^
2139
2140 GDAL can support online resources and storage providers transparently. As long
2141 as it's built with such capabilities.
2142
2143 To access a public raster file with no authentication, you can use
2144 ``/vsicurl/``:
2145
2146 .. code-block:: pycon
2147
2148 >>> from django.contrib.gis.gdal import GDALRaster
2149 >>> rst = GDALRaster("/vsicurl/https://example.com/raster.tif")
2150 >>> rst.name
2151 '/vsicurl/https://example.com/raster.tif'
2152
2153 For commercial storage providers (e.g. ``/vsis3/``) the system should be
2154 previously configured for authentication and possibly other settings (see the
2155 `GDAL Virtual Filesystems documentation`_ for available options).
2156
2157 .. _`GDAL Virtual Filesystems documentation`: https://gdal.org/user/virtual_file_systems.html
2158
2159 Settings
2160 ========
2161
2162 .. setting:: GDAL_LIBRARY_PATH
2163
2164 ``GDAL_LIBRARY_PATH``
2165 ---------------------
2166
2167 A string specifying the location of the GDAL library. Typically,
2168 this setting is only used if the GDAL library is in a non-standard
2169 location (e.g., ``/home/john/lib/libgdal.so``).
2170
2171 Exceptions
2172 ==========
2173
2174 .. exception:: GDALException
2175
2176 The base GDAL exception, indicating a GDAL-related error.
2177
2178 .. exception:: SRSException
2179
2180 An exception raised when an error occurs when constructing or using a
2181 spatial reference system object.