/docs/ref/contrib/gis/gdal.txt
Plain Text | 1106 lines | 707 code | 399 blank | 0 comment | 0 complexity | d714bd935d7ded4e23034fda15830011 MD5 | raw file
1.. _ref-gdal: 2 3======== 4GDAL API 5======== 6 7.. module:: django.contrib.gis.gdal 8 :synopsis: GeoDjango's high-level interface to the GDAL library. 9 10`GDAL`__ stands for **G**\ eospatial **D**\ ata **A**\ bstraction **L**\ ibrary, 11and is a veritable "swiss army knife" of GIS data functionality. A subset 12of GDAL is the `OGR`__ Simple Features Library, which specializes 13in reading and writing vector geographic data in a variety of standard 14formats. 15 16GeoDjango provides a high-level Python interface for some of the 17capabilities of OGR, including the reading and coordinate transformation 18of vector spatial data. 19 20.. note:: 21 22 Although the module is named ``gdal``, GeoDjango only supports 23 some of the capabilities of OGR. Thus, none of GDAL's features 24 with respect to raster (image) data are supported at this time. 25 26__ http://www.gdal.org/ 27__ http://www.gdal.org/ogr/ 28 29Overview 30======== 31 32Sample Data 33----------- 34 35The GDAL/OGR tools described here are designed to help you read in 36your geospatial data, in order for most of them to be useful you have 37to have some data to work with. If you're starting out and don't yet 38have any data of your own to use, GeoDjango comes with a number of 39simple data sets that you can use for testing. This snippet will 40determine where these sample files are installed on your computer:: 41 42 >>> import os 43 >>> import django.contrib.gis 44 >>> GIS_PATH = os.path.dirname(django.contrib.gis.__file__) 45 >>> CITIES_PATH = os.path.join(GIS_PATH, 'tests/data/cities/cities.shp') 46 47Vector Data Source Objects 48========================== 49 50``DataSource`` 51-------------- 52 53:class:`DataSource` is a wrapper for the OGR data source object that 54supports reading data from a variety of OGR-supported geospatial file 55formats and data sources using a simple, consistent interface. Each 56data source is represented by a :class:`DataSource` object which contains 57one or more layers of data. Each layer, represented by a :class:`Layer` 58object, contains some number of geographic features (:class:`Feature`), 59information about the type of features contained in that layer (e.g. 60points, polygons, etc.), as well as the names and types of any 61additional fields (:class:`Field`) of data that may be associated with 62each feature in that layer. 63 64.. class:: DataSource(ds_input) 65 66 The constructor for ``DataSource`` just a single parameter: the path of 67 the file you want to read. However, OGR 68 also supports a variety of more complex data sources, including 69 databases, that may be accessed by passing a special name string instead 70 of a path. For more information, see the `OGR Vector Formats`__ 71 documentation. The :attr:`name` property of a ``DataSource`` 72 instance gives the OGR name of the underlying data source that it is 73 using. 74 75 Once you've created your ``DataSource``, you can find out how many 76 layers of data it contains by accessing the :attr:`layer_count` property, 77 or (equivalently) by using the ``len()`` function. For information on 78 accessing the layers of data themselves, see the next section:: 79 80 >>> from django.contrib.gis.gdal import DataSource 81 >>> ds = DataSource(CITIES_PATH) 82 >>> ds.name # The exact filename may be different on your computer 83 '/usr/local/lib/python2.6/site-packages/django/contrib/gis/tests/data/cities/cities.shp' 84 >>> ds.layer_count # This file only contains one layer 85 1 86 87 .. attribute:: layer_count 88 89 Returns the number of layers in the data source. 90 91 .. attribute:: name 92 93 Returns the name of the data source. 94 95__ http://www.gdal.org/ogr/ogr_formats.html 96 97``Layer`` 98--------- 99 100.. class:: Layer 101 102 ``Layer`` is a wrapper for a layer of data in a ``DataSource`` object. 103 You never create a ``Layer`` object directly. Instead, you retrieve 104 them from a :class:`DataSource` object, which is essentially a standard 105 Python container of ``Layer`` objects. For example, you can access a 106 specific layer by its index (e.g. ``ds[0]`` to access the first 107 layer), or you can iterate over all the layers in the container in a 108 ``for`` loop. The ``Layer`` itself acts as a container for geometric 109 features. 110 111 Typically, all the features in a given layer have the same geometry type. 112 The :attr:`geom_type` property of a layer is an :class:`OGRGeomType` 113 that identifies the feature type. We can use it to print out some basic 114 information about each layer in a :class:`DataSource`:: 115 116 >>> for layer in ds: 117 ... print 'Layer "%s": %i %ss' % (layer.name, len(layer), layer.geom_type.name) 118 ... 119 Layer "cities": 3 Points 120 121 The example output is from the cities data source, loaded above, which 122 evidently contains one layer, called ``"cities"``, which contains three 123 point features. For simplicity, the examples below assume that you've 124 stored that layer in the variable ``layer``:: 125 126 >>> layer = ds[0] 127 128 .. attribute:: name 129 130 Returns the name of this layer in the data source. 131 132 >>> layer.name 133 'cities' 134 135 .. attribute:: num_feat 136 137 Returns the number of features in the layer. Same as ``len(layer)``:: 138 139 >>> layer.num_feat 140 3 141 142 .. attribute:: geom_type 143 144 Returns the geometry type of the layer, as an :class:`OGRGeomType` 145 object:: 146 147 >>> layer.geom_type.name 148 'Point' 149 150 .. attribute:: num_fields 151 152 Returns the number of fields in the layer, i.e the number of fields of 153 data associated with each feature in the layer:: 154 155 >>> layer.num_fields 156 4 157 158 .. attribute:: fields 159 160 Returns a list of the names of each of the fields in this layer:: 161 162 >>> layer.fields 163 ['Name', 'Population', 'Density', 'Created'] 164 165 .. attribute field_types 166 167 Returns a list of the data types of each of the fields in this layer. 168 These are subclasses of ``Field``, discussed below:: 169 170 >>> [ft.__name__ for ft in layer.field_types] 171 ['OFTString', 'OFTReal', 'OFTReal', 'OFTDate'] 172 173 .. attribute:: field_widths 174 175 Returns a list of the maximum field widths for each of the fields in 176 this layer:: 177 178 >>> layer.field_widths 179 [80, 11, 24, 10] 180 181 .. attribute:: field_precisions 182 183 Returns a list of the numeric precisions for each of the fields in 184 this layer. This is meaningless (and set to zero) for non-numeric 185 fields:: 186 187 >>> layer.field_precisions 188 [0, 0, 15, 0] 189 190 .. attribute:: extent 191 192 Returns the spatial extent of this layer, as an :class:`Envelope` 193 object:: 194 195 >>> layer.extent.tuple 196 (-104.609252, 29.763374, -95.23506, 38.971823) 197 198 .. attribute:: srs 199 200 Property that returns the :class:`SpatialReference` associated 201 with this layer:: 202 203 >>> print layer.srs 204 GEOGCS["GCS_WGS_1984", 205 DATUM["WGS_1984", 206 SPHEROID["WGS_1984",6378137,298.257223563]], 207 PRIMEM["Greenwich",0], 208 UNIT["Degree",0.017453292519943295]] 209 210 If the :class:`Layer` has no spatial reference information associated 211 with it, ``None`` is returned. 212 213 .. attribute:: spatial_filter 214 215 .. versionadded:: 1.2 216 217 Property that may be used to retrieve or set a spatial filter for this 218 layer. A spatial filter can only be set with an :class:`OGRGeometry` 219 instance, a 4-tuple extent, or ``None``. When set with something 220 other than ``None``, only features that intersect the filter will be 221 returned when iterating over the layer:: 222 223 >>> print layer.spatial_filter 224 None 225 >>> print len(layer) 226 3 227 >>> [feat.get('Name') for feat in layer] 228 ['Pueblo', 'Lawrence', 'Houston'] 229 >>> ks_extent = (-102.051, 36.99, -94.59, 40.00) # Extent for state of Kansas 230 >>> layer.spatial_filter = ks_extent 231 >>> len(layer) 232 1 233 >>> [feat.get('Name') for feat in layer] 234 ['Lawrence'] 235 >>> layer.spatial_filter = None 236 >>> len(layer) 237 3 238 239 .. method:: get_fields() 240 241 A method that returns a list of the values of a given field for each 242 feature in the layer:: 243 244 >>> layer.get_fields('Name') 245 ['Pueblo', 'Lawrence', 'Houston'] 246 247 .. method:: get_geoms([geos=False]) 248 249 A method that returns a list containing the geometry of each feature 250 in the layer. If the optional argument ``geos`` is set to ``True`` 251 then the geometries are converted to :class:`~django.contrib.gis.geos.GEOSGeometry` 252 objects. Otherwise, they are returned as :class:`OGRGeometry` objects:: 253 254 >>> [pt.tuple for pt in layer.get_geoms()] 255 [(-104.609252, 38.255001), (-95.23506, 38.971823), (-95.363151, 29.763374)] 256 257 .. method:: test_capability(capability) 258 259 Returns a boolean indicating whether this layer supports the 260 given capability (a string). Examples of valid capability strings 261 include: ``'RandomRead'``, ``'SequentialWrite'``, ``'RandomWrite'``, 262 ``'FastSpatialFilter'``, ``'FastFeatureCount'``, ``'FastGetExtent'``, 263 ``'CreateField'``, ``'Transactions'``, ``'DeleteFeature'``, and 264 ``'FastSetNextByIndex'``. 265 266``Feature`` 267----------- 268 269.. class:: Feature 270 271 272 ``Feature`` wraps an OGR feature. You never create a ``Feature`` 273 object directly. Instead, you retrieve them from a :class:`Layer` object. 274 Each feature consists of a geometry and a set of fields containing 275 additional properties. The geometry of a field is accessible via its 276 ``geom`` property, which returns an :class:`OGRGeometry` object. A ``Feature`` 277 behaves like a standard Python container for its fields, which it returns as 278 :class:`Field` objects: you can access a field directly by its index or name, 279 or you can iterate over a feature's fields, e.g. in a ``for`` loop. 280 281 .. attribute:: geom 282 283 Returns the geometry for this feature, as an ``OGRGeometry`` object:: 284 285 >>> city.geom.tuple 286 (-104.609252, 38.255001) 287 288 .. attribute:: get 289 290 A method that returns the value of the given field (specified by name) 291 for this feature, **not** a ``Field`` wrapper object:: 292 293 >>> city.get('Population') 294 102121 295 296 .. attribute:: geom_type 297 298 Returns the type of geometry for this feature, as an :class:`OGRGeomType` 299 object. This will be the same for all features in a given layer, and 300 is equivalent to the :attr:`Layer.geom_type` property of the 301 :class:`Layer`` object the feature came from. 302 303 .. attribute:: num_fields 304 305 Returns the number of fields of data associated with the feature. 306 This will be the same for all features in a given layer, and is 307 equivalent to the :attr:`Layer.num_fields` property of the 308 :class:`Layer` object the feature came from. 309 310 .. attribute:: fields 311 312 Returns a list of the names of the fields of data associated with the 313 feature. This will be the same for all features in a given layer, and 314 is equivalent to the :attr:`Layer.fields` property of the :class:`Layer` 315 object the feature came from. 316 317 .. attribute:: fid 318 319 Returns the feature identifier within the layer:: 320 321 >>> city.fid 322 0 323 324 .. attribute:: layer_name 325 326 Returns the name of the :class:`Layer` that the feature came from. 327 This will be the same for all features in a given layer:: 328 329 >>> city.layer_name 330 'cities' 331 332 .. attribute:: index 333 334 A method that returns the index of the given field name. This will be 335 the same for all features in a given layer:: 336 337 >>> city.index('Population') 338 1 339 340``Field`` 341--------- 342 343.. class:: Field 344 345 .. attribute:: name 346 347 Returns the name of this field:: 348 349 >>> city['Name'].name 350 'Name' 351 352 .. attribute:: type 353 354 Returns the OGR type of this field, as an integer. The 355 ``FIELD_CLASSES`` dictionary maps these values onto 356 subclasses of ``Field``:: 357 358 >>> city['Density'].type 359 2 360 361 .. attribute:: type_name 362 363 Returns a string with the name of the data type of this field:: 364 365 >>> city['Name'].type_name 366 'String' 367 368 .. attribute:: value 369 370 Returns the value of this field. The ``Field`` class itself 371 returns the value as a string, but each subclass returns the 372 value in the most appropriate form:: 373 374 >>> city['Population'].value 375 102121 376 377 .. attribute:: width 378 379 Returns the width of this field:: 380 381 >>> city['Name'].width 382 80 383 384 .. attribute:: precision 385 386 Returns the numeric precision of this field. This is meaningless (and 387 set to zero) for non-numeric fields:: 388 389 >>> city['Density'].precision 390 15 391 392 .. method:: as_double() 393 394 Returns the value of the field as a double (float):: 395 396 >>> city['Density'].as_double() 397 874.7 398 399 .. method:: as_int() 400 401 Returns the value of the field as an integer:: 402 403 >>> city['Population'].as_int() 404 102121 405 406 .. method:: as_string() 407 408 Returns the value of the field as a string:: 409 410 >>> city['Name'].as_string() 411 'Pueblo' 412 413 .. method:: as_datetime() 414 415 Returns the value of the field as a tuple of date and time components:: 416 417 >>> city['Created'].as_datetime() 418 (c_long(1999), c_long(5), c_long(23), c_long(0), c_long(0), c_long(0), c_long(0)) 419 420``Driver`` 421---------- 422 423.. class:: Driver(dr_input) 424 425 The ``Driver`` class is used internally to wrap an OGR :class:`DataSource` driver. 426 427 .. attribute:: driver_count 428 429 Returns the number of OGR vector drivers currently registered. 430 431 432OGR Geometries 433============== 434 435``OGRGeometry`` 436--------------- 437 438:class:`OGRGeometry` objects share similar functionality with 439:class:`~django.contrib.gis.geos.GEOSGeometry` objects, and are thin 440wrappers around OGR's internal geometry representation. Thus, 441they allow for more efficient access to data when using :class:`DataSource`. 442Unlike its GEOS counterpart, :class:`OGRGeometry` supports spatial reference 443systems and coordinate transformation:: 444 445 >>> from django.contrib.gis.gdal import OGRGeometry 446 >>> polygon = OGRGeometry('POLYGON((0 0, 5 0, 5 5, 0 5))') 447 448.. class:: OGRGeometry(geom_input[, srs=None]) 449 450 This object is a wrapper for the `OGR Geometry`__ class. 451 These objects are instantiated directly from the given ``geom_input`` 452 parameter, which may be a string containing WKT or HEX, a ``buffer`` 453 containing WKB data, or an :class:`OGRGeomType` object. These objects 454 are also returned from the :class:`Feature.geom` attribute, when 455 reading vector data from :class:`Layer` (which is in turn a part of 456 a :class:`DataSource`). 457 458 __ http://www.gdal.org/ogr/classOGRGeometry.html 459 460 .. classmethod:: from_bbox(bbox) 461 462 Constructs a :class:`Polygon` from the given bounding-box (a 4-tuple). 463 464 .. method:: __len__ 465 466 Returns the number of points in a :class:`LineString`, the 467 number of rings in a :class:`Polygon`, or the number of geometries in a 468 :class:`GeometryCollection`. Not applicable to other geometry types. 469 470 .. method:: __iter__ 471 472 Iterates over the points in a :class:`LineString`, the rings in a 473 :class:`Polygon`, or the geometries in a :class:`GeometryCollection`. 474 Not applicable to other geometry types. 475 476 .. method:: __getitem__ 477 478 Returns the point at the specified index for a :class:`LineString`, the 479 interior ring at the specified index for a :class:`Polygon`, or the geometry 480 at the specified index in a :class:`GeometryCollection`. Not applicable to 481 other geometry types. 482 483 .. attribute:: dimension 484 485 Returns the number of coordinated dimensions of the geometry, i.e. 0 486 for points, 1 for lines, and so forth:: 487 488 >> polygon.dimension 489 2 490 491 .. attribute:: coord_dim 492 493 .. versionchanged:: 1.2 494 495 Returns or sets the coordinate dimension of this geometry. For 496 example, the value would be 2 for two-dimensional geometries. 497 498 .. note:: 499 500 Setting this property is only available in versions 1.2 and above. 501 502 .. attribute:: geom_count 503 504 Returns the number of elements in this geometry:: 505 506 >>> polygon.geom_count 507 1 508 509 .. attribute:: point_count 510 511 Returns the number of points used to describe this geometry:: 512 513 >>> polygon.point_count 514 4 515 516 .. attribute:: num_points 517 518 Alias for :attr:`point_count`. 519 520 .. attribute:: num_coords 521 522 Alias for :attr:`point_count`. 523 524 .. attribute:: geom_type 525 526 Returns the type of this geometry, as an :class:`OGRGeomType` object. 527 528 .. attribute:: geom_name 529 530 Returns the name of the type of this geometry:: 531 532 >>> polygon.geom_name 533 'POLYGON' 534 535 .. attribute:: area 536 537 Returns the area of this geometry, or 0 for geometries that do not 538 contain an area:: 539 540 >>> polygon.area 541 25.0 542 543 .. attribute:: envelope 544 545 Returns the envelope of this geometry, as an :class:`Envelope` object. 546 547 .. attribute:: extent 548 549 Returns the envelope of this geometry as a 4-tuple, instead of as an 550 :class:`Envelope` object:: 551 552 >>> point.extent 553 (0.0, 0.0, 5.0, 5.0) 554 555 .. attribute:: srs 556 557 This property controls the spatial reference for this geometry, or 558 ``None`` if no spatial reference system has been assigned to it. 559 If assigned, accessing this property returns a :class:`SpatialReference` 560 object. It may be set with another :class:`SpatialReference` object, 561 or any input that :class:`SpatialReference` accepts. Example:: 562 563 >>> city.geom.srs.name 564 'GCS_WGS_1984' 565 566 .. attribute:: srid 567 568 Returns or sets the spatial reference identifier corresponding to 569 :class:`SpatialReference` of this geometry. Returns ``None`` if 570 there is no spatial reference information associated with this 571 geometry, or if an SRID cannot be determined. 572 573 .. attribute:: geos 574 575 Returns a :class:`~django.contrib.gis.geos.GEOSGeometry` object 576 corresponding to this geometry. 577 578 .. attribute:: gml 579 580 Returns a string representation of this geometry in GML format:: 581 582 >>> OGRGeometry('POINT(1 2)').gml 583 '<gml:Point><gml:coordinates>1,2</gml:coordinates></gml:Point>' 584 585 .. attribute:: hex 586 587 Returns a string representation of this geometry in HEX WKB format:: 588 589 >>> OGRGeometry('POINT(1 2)').hex 590 '0101000000000000000000F03F0000000000000040' 591 592 .. attribute:: json 593 594 Returns a string representation of this geometry in JSON format:: 595 596 >>> OGRGeometry('POINT(1 2)').json 597 '{ "type": "Point", "coordinates": [ 1.000000, 2.000000 ] }' 598 599 600 .. attribute:: kml 601 602 Returns a string representation of this geometry in KML format. 603 604 .. attribute:: wkb_size 605 606 Returns the size of the WKB buffer needed to hold a WKB representation 607 of this geometry:: 608 609 >>> OGRGeometry('POINT(1 2)').wkb_size 610 21 611 612 .. attribute:: wkb 613 614 Returns a ``buffer`` containing a WKB representation of this geometry. 615 616 .. attribute:: wkt 617 618 Returns a string representation of this geometry in WKT format. 619 620 .. attribute:: ewkt 621 622 .. versionadded:: 1.2 623 624 Returns the EWKT representation of this geometry. 625 626 .. method:: clone() 627 628 Returns a new :class:`OGRGeometry` clone of this geometry object. 629 630 .. method:: close_rings() 631 632 If there are any rings within this geometry that have not been closed, 633 this routine will do so by adding the starting point to the end:: 634 635 >>> triangle = OGRGeometry('LINEARRING (0 0,0 1,1 0)') 636 >>> triangle.close_rings() 637 >>> triangle.wkt 638 'LINEARRING (0 0,0 1,1 0,0 0)' 639 640 .. method:: transform(coord_trans, clone=False) 641 642 Transforms this geometry to a different spatial reference system. May 643 take a :class:`CoordTransform` object, a :class:`SpatialReference` object, 644 or any other input accepted by :class:`SpatialReference` (including 645 spatial reference WKT and PROJ.4 strings, or an integer SRID). 646 By default nothing is returned and the geometry is transformed in-place. 647 However, if the `clone` keyword is set to ``True`` then a transformed clone 648 of this geometry is returned instead. 649 650 .. method:: intersects(other) 651 652 Returns ``True`` if this geometry intersects the other, otherwise returns 653 ``False``. 654 655 .. method:: equals(other) 656 657 Returns ``True`` if this geometry is equivalent to the other, otherwise returns 658 ``False``. 659 660 .. method:: disjoint(other) 661 662 Returns ``True`` if this geometry is spatially disjoint to (i.e. does 663 not intersect) the other, otherwise returns ``False``. 664 665 .. method:: touches(other) 666 667 Returns ``True`` if this geometry touches the other, otherwise returns 668 ``False``. 669 670 .. method:: crosses(other) 671 672 Returns ``True`` if this geometry crosses the other, otherwise returns 673 ``False``. 674 675 .. method:: within(other) 676 677 Returns ``True`` if this geometry is contained within the other, otherwise returns 678 ``False``. 679 680 .. method:: contains(other) 681 682 Returns ``True`` if this geometry contains the other, otherwise returns 683 ``False``. 684 685 .. method:: overlaps(other) 686 687 Returns ``True`` if this geometry overlaps the other, otherwise returns 688 ``False``. 689 690 .. method:: boundary 691 692 The boundary of this geometry, as a new :class:`OGRGeometry` object. 693 694 .. attribute:: convex_hull 695 696 The smallest convex polygon that contains this geometry, as a new 697 :class:`OGRGeometry` object. 698 699 .. method:: difference 700 701 Returns the region consisting of the difference of this geometry and 702 the other, as a new :class:`OGRGeometry` object. 703 704 .. method:: intersection 705 706 Returns the region consisting of the intersection of this geometry and 707 the other, as a new :class:`OGRGeometry` object. 708 709 .. method:: sym_difference 710 711 Returns the region consisting of the symmetric difference of this 712 geometry and the other, as a new :class:`OGRGeometry` object. 713 714 .. method:: union 715 716 Returns the region consisting of the union of this geometry and 717 the other, as a new :class:`OGRGeometry` object. 718 719 .. attribute:: tuple 720 721 Returns the coordinates of a point geometry as a tuple, the 722 coordinates of a line geometry as a tuple of tuples, and so forth:: 723 724 >>> OGRGeometry('POINT (1 2)').tuple 725 (1.0, 2.0) 726 >>> OGRGeometry('LINESTRING (1 2,3 4)').tuple 727 ((1.0, 2.0), (3.0, 4.0)) 728 729 .. attribute:: coords 730 731 An alias for :attr:`tuple`. 732 733.. class:: Point 734 735 .. attribute:: x 736 737 Returns the X coordinate of this point:: 738 739 >>> OGRGeometry('POINT (1 2)').x 740 1.0 741 742 .. attribute:: y 743 744 Returns the Y coordinate of this point:: 745 746 >>> OGRGeometry('POINT (1 2)').y 747 2.0 748 749 .. attribute:: z 750 751 Returns the Z coordinate of this point, or ``None`` if the 752 the point does not have a Z coordinate:: 753 754 >>> OGRGeometry('POINT (1 2 3)').z 755 3.0 756 757.. class:: LineString 758 759 .. attribute:: x 760 761 Returns a list of X coordinates in this line:: 762 763 >>> OGRGeometry('LINESTRING (1 2,3 4)').x 764 [1.0, 3.0] 765 766 .. attribute:: y 767 768 Returns a list of Y coordinates in this line:: 769 770 >>> OGRGeometry('LINESTRING (1 2,3 4)').y 771 [2.0, 4.0] 772 773 .. attribute:: z 774 775 Returns a list of Z coordinates in this line, or ``None`` if the 776 line does not have Z coordinates:: 777 778 >>> OGRGeometry('LINESTRING (1 2 3,4 5 6)').z 779 [3.0, 6.0] 780 781 782.. class:: Polygon 783 784 .. attribute:: shell 785 786 Returns the shell or exterior ring of this polygon, as a ``LinearRing`` 787 geometry. 788 789 .. attribute:: exterior_ring 790 791 An alias for :attr:`shell`. 792 793 .. attribute:: centroid 794 795 Returns a :class:`Point` representing the centroid of this polygon. 796 797.. class:: GeometryCollection 798 799 .. method:: add(geom) 800 801 Adds a geometry to this geometry collection. Not applicable to other 802 geometry types. 803 804 805``OGRGeomType`` 806--------------- 807 808.. class:: OGRGeomType(type_input) 809 810 This class allows for the representation of an OGR geometry type 811 in any of several ways:: 812 813 >>> from django.contrib.gis.gdal import OGRGeomType 814 >>> gt1 = OGRGeomType(3) # Using an integer for the type 815 >>> gt2 = OGRGeomType('Polygon') # Using a string 816 >>> gt3 = OGRGeomType('POLYGON') # It's case-insensitive 817 >>> print gt1 == 3, gt1 == 'Polygon' # Equivalence works w/non-OGRGeomType objects 818 True True 819 820 .. attribute:: name 821 822 Returns a short-hand string form of the OGR Geometry type:: 823 824 >>> gt1.name 825 'Polygon' 826 827 .. attribute:: num 828 829 Returns the number corresponding to the OGR geometry type:: 830 831 >>> gt1.num 832 3 833 834 .. attribute:: django 835 836 Returns the Django field type (a subclass of GeometryField) to use for 837 storing this OGR type, or ``None`` if there is no appropriate Django 838 type:: 839 840 >>> gt1.django 841 'PolygonField' 842 843``Envelope`` 844------------ 845 846.. class:: Envelope(*args) 847 848 Represents an OGR Envelope structure that contains the 849 minimum and maximum X, Y coordinates for a rectangle bounding box. 850 The naming of the variables is compatible with the OGR Envelope 851 C structure. 852 853 .. attribute:: min_x 854 855 The value of the minimum X coordinate. 856 857 .. attribute:: min_y 858 859 The value of the maximum X coordinate. 860 861 .. attribute:: max_x 862 863 The value of the minimum Y coordinate. 864 865 .. attribute:: max_y 866 867 The value of the maximum Y coordinate. 868 869 .. attribute:: ur 870 871 The upper-right coordinate, as a tuple. 872 873 .. attribute:: ll 874 875 The lower-left coordinate, as a tuple. 876 877 .. attribute:: tuple 878 879 A tuple representing the envelope. 880 881 .. attribute:: wkt 882 883 A string representing this envelope as a polygon in WKT format. 884 885 886 .. method:: expand_to_include(self, *args) 887 888Coordinate System Objects 889========================= 890 891``SpatialReference`` 892-------------------- 893 894.. class:: SpatialReference(srs_input) 895 896 Spatial reference objects are initialized on the given ``srs_input``, 897 which may be one of the following: 898 899 * OGC Well Known Text (WKT) (a string) 900 * EPSG code (integer or string) 901 * PROJ.4 string 902 * A shorthand string for well-known standards (``'WGS84'``, ``'WGS72'``, ``'NAD27'``, ``'NAD83'``) 903 904 Example:: 905 906 >>> wgs84 = SpatialReference('WGS84') # shorthand string 907 >>> wgs84 = SpatialReference(4326) # EPSG code 908 >>> wgs84 = SpatialReference('EPSG:4326') # EPSG string 909 >>> proj4 = '+proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs ' 910 >>> wgs84 = SpatialReference(proj4) # PROJ.4 string 911 >>> wgs84 = SpatialReference("""GEOGCS["WGS 84", 912 DATUM["WGS_1984", 913 SPHEROID["WGS 84",6378137,298.257223563, 914 AUTHORITY["EPSG","7030"]], 915 AUTHORITY["EPSG","6326"]], 916 PRIMEM["Greenwich",0, 917 AUTHORITY["EPSG","8901"]], 918 UNIT["degree",0.01745329251994328, 919 AUTHORITY["EPSG","9122"]], 920 AUTHORITY["EPSG","4326"]]""") # OGC WKT 921 922 .. method:: __getitem__(target) 923 924 Returns the value of the given string attribute node, ``None`` if the node 925 doesn't exist. Can also take a tuple as a parameter, (target, child), 926 where child is the index of the attribute in the WKT. For example:: 927 928 >>> wkt = 'GEOGCS["WGS 84", DATUM["WGS_1984, ... AUTHORITY["EPSG","4326"]]') 929 >>> srs = SpatialReference(wkt) # could also use 'WGS84', or 4326 930 >>> print srs['GEOGCS'] 931 WGS 84 932 >>> print srs['DATUM'] 933 WGS_1984 934 >>> print srs['AUTHORITY'] 935 EPSG 936 >>> print srs['AUTHORITY', 1] # The authority value 937 4326 938 >>> print srs['TOWGS84', 4] # the fourth value in this wkt 939 0 940 >>> print srs['UNIT|AUTHORITY'] # For the units authority, have to use the pipe symbole. 941 EPSG 942 >>> print srs['UNIT|AUTHORITY', 1] # The authority value for the untis 943 9122 944 945 .. method:: attr_value(target, index=0) 946 947 The attribute value for the given target node (e.g. ``'PROJCS'``). 948 The index keyword specifies an index of the child node to return. 949 950 .. method:: auth_name(target) 951 952 Returns the authority name for the given string target node. 953 954 .. method:: auth_code(target) 955 956 Returns the authority code for the given string target node. 957 958 .. method:: clone() 959 960 Returns a clone of this spatial reference object. 961 962 .. method:: identify_epsg() 963 964 This method inspects the WKT of this SpatialReference, and will 965 add EPSG authority nodes where an EPSG identifier is applicable. 966 967 .. method:: from_esri() 968 969 Morphs this SpatialReference from ESRI's format to EPSG 970 971 .. method:: to_esri() 972 973 Morphs this SpatialReference to ESRI's format. 974 975 .. method:: validate() 976 977 Checks to see if the given spatial reference is valid, if not 978 an exception will be raised. 979 980 .. method:: import_epsg(epsg) 981 982 Import spatial reference from EPSG code. 983 984 .. method:: import_proj(proj) 985 986 Import spatial reference from PROJ.4 string. 987 988 .. method:: import_user_input(user_input) 989 990 .. method:: import_wkt(wkt) 991 992 Import spatial reference from WKT. 993 994 .. method:: import_xml(xml) 995 996 Import spatial reference from XML. 997 998 .. attribute:: name 999 1000 Returns the name of this Spatial Reference. 1001 1002 .. attribute:: srid 1003 1004 Returns the SRID of top-level authority, or ``None`` if undefined. 1005 1006 .. attribute:: linear_name 1007 1008 Returns the name of the linear units. 1009 1010 .. attribute:: linear_units 1011 1012 Returns the value of the linear units. 1013 1014 .. attribute:: angular_name 1015 1016 Returns the name of the angular units." 1017 1018 .. attribute:: angular_units 1019 1020 Returns the value of the angular units. 1021 1022 .. attribute:: units 1023 1024 Returns a 2-tuple of the units value and the units name, 1025 and will automatically determines whether to return the linear 1026 or angular units. 1027 1028 .. attribute:: ellisoid 1029 1030 Returns a tuple of the ellipsoid parameters for this spatial 1031 reference: (semimajor axis, semiminor axis, and inverse flattening) 1032 1033 .. attribute:: semi_major 1034 1035 Returns the semi major axis of the ellipsoid for this spatial reference. 1036 1037 .. attribute:: semi_minor 1038 1039 Returns the semi minor axis of the ellipsoid for this spatial reference. 1040 1041 .. attribute:: inverse_flattening 1042 1043 Returns the inverse flattening of the ellipsoid for this spatial reference. 1044 1045 .. attribute:: geographic 1046 1047 Returns ``True`` if this spatial reference is geographic 1048 (root node is ``GEOGCS``). 1049 1050 .. attribute:: local 1051 1052 Returns ``True`` if this spatial reference is local 1053 (root node is ``LOCAL_CS``). 1054 1055 .. attribute:: projected 1056 1057 Returns ``True`` if this spatial reference is a projected coordinate 1058 system (root node is ``PROJCS``). 1059 1060 .. attribute:: wkt 1061 1062 Returns the WKT representation of this spatial reference. 1063 1064 .. attribute:: pretty_wkt 1065 1066 Returns the 'pretty' representation of the WKT. 1067 1068 .. attribute:: proj 1069 1070 Returns the PROJ.4 representation for this spatial reference. 1071 1072 .. attribute:: proj4 1073 1074 Alias for :attr:`SpatialReference.proj`. 1075 1076 .. attribute:: xml 1077 1078 Returns the XML representation of this spatial reference. 1079 1080 1081``CoordTransform`` 1082------------------ 1083 1084.. class:: CoordTransform(source, target) 1085 1086Represents a coordinate system transform. It is initialized with two 1087:class:`SpatialReference`, representing the source and target coordinate 1088systems, respectively. These objects should be used when performing 1089the same coordinate transformation repeatedly on different geometries:: 1090 1091 >>> ct = CoordTransform(SpatialReference('WGS84'), SpatialReference('NAD83')) 1092 >>> for feat in layer: 1093 ... geom = feat.geom # getting clone of feature geometry 1094 ... geom.transform(ct) # transforming 1095 1096Settings 1097======== 1098 1099.. setting:: GDAL_LIBRARY_PATH 1100 1101GDAL_LIBRARY_PATH 1102----------------- 1103 1104A string specifying the location of the GDAL library. Typically, 1105this setting is only used if the GDAL library is in a non-standard 1106location (e.g., ``/home/john/lib/libgdal.so``).