Skip to content

Instantly share code, notes, and snippets.

@sgillies

sgillies/geo_interface.rst

Last active January 14, 2025 06:59
Show Gist options
  • Save sgillies/2217756 to your computer and use it in GitHub Desktop.
Save sgillies/2217756 to your computer and use it in GitHub Desktop.
Download ZIP

Revisions

  1. sgillies renamed this gist Mar 22, 2017. 1 changed file with 3 additions and 3 deletions.
    6 changes: 3 additions & 3 deletions __geo_interface__.rst → geo_interface.rst
    View file
    Original file line number Diff line number Diff line change
    @@ -135,9 +135,9 @@ References
    ==========

    .. [1] http://docs.scipy.org/doc/numpy/reference/arrays.interface.html
    .. [2] http://geojson.org
    .. [3] http://help.arcgis.com/en/arcgisdesktop/10.0/help/index.html#//000v00000153000000
    .. [2] https://tools.ietf.org/html/rfc7946
    .. [3] https://desktop.arcgis.com/en/arcmap/latest/analyze/arcpy-functions/asshape.htm
    .. [4] https://bitbucket.org/sgillies/descartes/src/f97e54f3b8d4/descartes/patch.py#cl-14
    .. [5] http://pypi.python.org/pypi/geojson/
    .. [6] http://pysal.geodacenter.org/1.3/users/tutorials/shapely.html
    .. [6] https://pysal.readthedocs.io/en/latest/users/tutorials/shapely.html
    .. [7] https://github.com/Toblerity/Shapely
  2. sgillies revised this gist Mar 28, 2012. 1 changed file with 5 additions and 4 deletions.
    9 changes: 5 additions & 4 deletions __geo_interface__.rst
    View file
    Original file line number Diff line number Diff line change
    @@ -1,9 +1,10 @@
    Author: Sean Gillies
    Version: 1.0

    Abstract
    ========

    This document describes a GeoJSON-like protocol for geospatial vector data.
    This document describes a GeoJSON-like protocol for geo-spatial (GIS) vector data.

    Introduction
    ============
    @@ -12,7 +13,7 @@ Python has a number of built-in protocols (descriptors, iterators, etc). A very
    simple and familiar one involves string representations of objects. The
    built-in ``str()`` function calls the ``__str__()`` method of its single
    argument. By implementing ``__str__()``, instances of any class can be printed
    by anyother Python program.
    by any other Python program.
    ::

    >>> class A(object):
    @@ -25,7 +26,7 @@ by anyother Python program.
    >>> "%s" % a
    'Eh!'

    What if we could do something like this for geospatial (GIS) objects? It might,
    What if we could do something like this for geo-spatial objects? It might,
    for example, let any object be analyzed using any other hypothetical software
    package like this::

    @@ -53,7 +54,7 @@ type (required)
    a geometry type: "Point", "LineString", "Polygon", etc.

    bbox (optional)
    A tuple of floats that describes the geospatial bounds of the object: (left,
    A tuple of floats that describes the geo-spatial bounds of the object: (left,
    bottom, right, top) or (west, south, east, north).

    properties (optional)
  3. sgillies revised this gist Mar 28, 2012. 1 changed file with 25 additions and 16 deletions.
    41 changes: 25 additions & 16 deletions __geo_interface__.rst
    View file
    Original file line number Diff line number Diff line change
    @@ -8,9 +8,12 @@ This document describes a GeoJSON-like protocol for geospatial vector data.
    Introduction
    ============

    Python has a number of built-in protocols (descriptor, iterator, etc). A very
    simple one involves string representations of objects. The built-in ``str()``
    function calls the ``__str__()`` method of its single argument. Example::
    Python has a number of built-in protocols (descriptors, iterators, etc). A very
    simple and familiar one involves string representations of objects. The
    built-in ``str()`` function calls the ``__str__()`` method of its single
    argument. By implementing ``__str__()``, instances of any class can be printed
    by anyother Python program.
    ::

    >>> class A(object):
    ... def __str__(self):
    @@ -22,18 +25,17 @@ function calls the ``__str__()`` method of its single argument. Example::
    >>> "%s" % a
    'Eh!'

    By implementing ``__str__()``, instances of any class can be printed by any
    other Python program. What if we could do something like this for geospatial
    (GIS) objects? It might, for example, let any object be analyzed using any
    other hypothetical software package like this::
    What if we could do something like this for geospatial (GIS) objects? It might,
    for example, let any object be analyzed using any other hypothetical software
    package like this::

    >>> from some_analytic_module import as_geometry
    >>> as_geometry(obj).buffer(1.0).area # obj is a "point" of some kind
    3.1365484905459389

    The hypothetical ``as_geometry()`` function of the hypothetical module would
    access relevant data of its single argument using an agreed upon method or
    attribute.
    The hypothetical ``as_geometry()`` function of the hypothetical
    `some_analytic_module` module would access relevant data of its single argument
    using an agreed upon method or attribute.

    __geo_interface__
    =================
    @@ -92,14 +94,18 @@ Next, a toy class with a feature representation::
    Implementations
    ===============

    * `ArcPy <http://help.arcgis.com/en/arcgisdesktop/10.0/help/index.html#//000v00000153000000>`__
    * `descartes <https://bitbucket.org/sgillies/descartes/src/f97e54f3b8d4/descartes/patch.py#cl-14>`__
    * `PySAL <http://pysal.geodacenter.org/1.3/users/tutorials/shapely.html>`__
    Python programs and packages that you have heard of – and made be a frequent
    user of – already implement this protocol:

    * ArcPy [3]_
    * descartes [4]_
    * geojson [5]_
    * PySAL [6]_

    Shapely
    -------

    Shapely [3]_ provides a ``shape()`` function that makes Shapely geometries from
    Shapely [7]_ provides a ``shape()`` function that makes Shapely geometries from
    objects that provide ``__geo_interface__`` and a ``mapping()`` function that
    writes geometries out as dictionaries::

    @@ -129,5 +135,8 @@ References

    .. [1] http://docs.scipy.org/doc/numpy/reference/arrays.interface.html
    .. [2] http://geojson.org
    .. [3] https://github.com/Toblerity/Shapely
    .. [3] http://help.arcgis.com/en/arcgisdesktop/10.0/help/index.html#//000v00000153000000
    .. [4] https://bitbucket.org/sgillies/descartes/src/f97e54f3b8d4/descartes/patch.py#cl-14
    .. [5] http://pypi.python.org/pypi/geojson/
    .. [6] http://pysal.geodacenter.org/1.3/users/tutorials/shapely.html
    .. [7] https://github.com/Toblerity/Shapely
  4. sgillies revised this gist Mar 27, 2012. 1 changed file with 1 addition and 116 deletions.
    117 changes: 1 addition & 116 deletions __geo_interface__.rst
    View file
    Original file line number Diff line number Diff line change
    @@ -1,10 +1,4 @@
    Abstract
    ========

    This document describes a GeoJSON-like protocol for geospatial vector data.

    Introduction
    ============Author: Sean Gillies
    Author: Sean Gillies

    Abstract
    ========
    @@ -137,112 +131,3 @@ References
    .. [2] http://geojson.org
    .. [3] https://github.com/Toblerity/Shapely
    Python has a number of built-in protocols (descriptor, iterator, etc). A very simple one involves string representations of objects. The built-in ``str()`` function calls the ``__str__()`` method of its single argument. Example::

    >>> class A(object):
    ... def __str__(self):
    ... return "Eh!"
    ...
    >>> a = A()
    >>> str(a)
    'Eh!'
    >>> "%s" % a
    'Eh!'

    By implementing ``__str__()``, instances of any class can be printed by any other Python program. What if we could do something like this for geospatial (GIS) objects? It might, for example, let any object be analyzed using any other hypothetical software package like
    this::

    >>> from some_analytic_module import as_geometry
    >>> as_geometry(obj).buffer(1.0).area # obj is a "point" of some kind
    3.1365484905459389

    The hypothetical ``as_geometry()`` function of the hypothetical module would access relevant data of its single argument using an agreed upon method or attribute.

    __geo_interface__
    =================

    Following the lead of numpy's Array Interface [1]_, let's agree on a ``__geo_interface__`` property. To avoid creating
    even more protocols, let's make the value of this attribute a Python mapping. To further minimize invention, let's
    borrow from the GeoJSON format [2]_ for the structure of this mapping.

    The keys are:

    type (required)
    A string indicating the geospatial type. Possible values are "Feature" or a geometry type: "Point", "LineString", "Polygon", etc.

    bbox (optional)
    A tuple of floats that describes the geospatial bounds of the object: (left, bottom, right, top) or (west, south, east, north).

    properties (optional)
    A mapping of feature properties (labels, populations ... you name it. Dependent on the data). Valid for "Feature" types only.

    geometry (optional)
    The geometric object of a "Feature" type, also as a mapping.

    coordinates (required)
    Valid only for geometry types. This is an ``(x, y)`` or ``(longitude, latitude)`` tuple in the case of a "Point", a list of such tuples in the "LineString" case, or a list of lists in the "Polygon" case. See the GeoJSON spec for details.

    Examples
    ========

    First, a toy class with a point representation::

    >>> class Pointy(object):
    ... __geo_interface__ = {'type': 'Point', 'coordinates': (0.0, 0.0)}
    ...
    >>> as_geometry(Pointy()).buffer(1.0).area
    3.1365484905459389

    Next, a toy class with a feature representation::

    >>> class Placemark(object):
    ... __geo_interface__ = {
    ... 'type': 'Feature',
    ... 'properties': {'name': 'Phoo'},
    ... 'geometry': Pointy.__geo_interface__ }
    >>> from my_analytic_module import as_feature
    >>> as_feature(Placemark())['properties']['name']
    'Phoo'

    Implementations
    ===============

    * `ArcPy <http://help.arcgis.com/en/arcgisdesktop/10.0/help/index.html#//000v00000153000000>`__
    * `descartes <https://bitbucket.org/sgillies/descartes/src/f97e54f3b8d4/descartes/patch.py#cl-14>`__
    * `PySAL <http://pysal.geodacenter.org/1.3/users/tutorials/shapely.html>`__

    Shapely
    -------

    Shapely [3]_ provides a ``shape()`` function that makes Shapely geometries from objects
    that provide ``__geo_interface__`` and a ``mapping()`` function that writes geometries
    out as dictionaries::

    >>> from shapely.geometry import Point
    >>> from shapely.geometry import mapping, shape
    >>> Point(0.0, 0.0).__geo_interface__
    {'type': 'Point', 'coordinates': (0.0, 0.0)}
    >>> shape(Point(0.0, 0.0))
    <shapely.geometry.point.Point object at 0x...>
    >>> mapping(Point(0.0, 0.0))
    {'type': 'Point', 'coordinates': (0.0, 0.0)}

    The Shapely version of the example in the introduction is::

    >>> from shapely.geometry import shape
    >>> shape(obj).buffer(1.0).area
    3.1365484905459389

    where ``obj`` could be a geometry object from ArcPy or PySAL, or even a mapping directly::

    >>> shape({'type': 'Point', 'coordinates': (0.0, 0.0)}).buffer(1.0).area
    3.1365484905459389

    References
    ==========

    .. [1] http://docs.scipy.org/doc/numpy/reference/arrays.interface.html
    .. [2] http://geojson.org
    .. [3] https://github.com/Toblerity/Shapely
  5. sgillies revised this gist Mar 27, 2012. 1 changed file with 133 additions and 0 deletions.
    133 changes: 133 additions & 0 deletions __geo_interface__.rst
    View file
    Original file line number Diff line number Diff line change
    @@ -3,9 +3,142 @@ Abstract

    This document describes a GeoJSON-like protocol for geospatial vector data.

    Introduction
    ============Author: Sean Gillies

    Abstract
    ========

    This document describes a GeoJSON-like protocol for geospatial vector data.

    Introduction
    ============

    Python has a number of built-in protocols (descriptor, iterator, etc). A very
    simple one involves string representations of objects. The built-in ``str()``
    function calls the ``__str__()`` method of its single argument. Example::

    >>> class A(object):
    ... def __str__(self):
    ... return "Eh!"
    ...
    >>> a = A()
    >>> str(a)
    'Eh!'
    >>> "%s" % a
    'Eh!'

    By implementing ``__str__()``, instances of any class can be printed by any
    other Python program. What if we could do something like this for geospatial
    (GIS) objects? It might, for example, let any object be analyzed using any
    other hypothetical software package like this::

    >>> from some_analytic_module import as_geometry
    >>> as_geometry(obj).buffer(1.0).area # obj is a "point" of some kind
    3.1365484905459389

    The hypothetical ``as_geometry()`` function of the hypothetical module would
    access relevant data of its single argument using an agreed upon method or
    attribute.

    __geo_interface__
    =================

    Following the lead of numpy's Array Interface [1]_, let's agree on
    a ``__geo_interface__`` property. To avoid creating even more protocols, let's
    make the value of this attribute a Python mapping. To further minimize
    invention, let's borrow from the GeoJSON format [2]_ for the structure of this
    mapping.

    The keys are:

    type (required)
    A string indicating the geospatial type. Possible values are "Feature" or
    a geometry type: "Point", "LineString", "Polygon", etc.

    bbox (optional)
    A tuple of floats that describes the geospatial bounds of the object: (left,
    bottom, right, top) or (west, south, east, north).

    properties (optional)
    A mapping of feature properties (labels, populations ... you name it.
    Dependent on the data). Valid for "Feature" types only.

    geometry (optional)
    The geometric object of a "Feature" type, also as a mapping.

    coordinates (required)
    Valid only for geometry types. This is an ``(x, y)`` or ``(longitude,
    latitude)`` tuple in the case of a "Point", a list of such tuples in the
    "LineString" case, or a list of lists in the "Polygon" case. See the GeoJSON
    spec for details.

    Examples
    ========

    First, a toy class with a point representation::

    >>> class Pointy(object):
    ... __geo_interface__ = {'type': 'Point', 'coordinates': (0.0, 0.0)}
    ...
    >>> as_geometry(Pointy()).buffer(1.0).area
    3.1365484905459389

    Next, a toy class with a feature representation::

    >>> class Placemark(object):
    ... __geo_interface__ = {
    ... 'type': 'Feature',
    ... 'properties': {'name': 'Phoo'},
    ... 'geometry': Pointy.__geo_interface__ }
    >>> from my_analytic_module import as_feature
    >>> as_feature(Placemark())['properties']['name']
    'Phoo'

    Implementations
    ===============

    * `ArcPy <http://help.arcgis.com/en/arcgisdesktop/10.0/help/index.html#//000v00000153000000>`__
    * `descartes <https://bitbucket.org/sgillies/descartes/src/f97e54f3b8d4/descartes/patch.py#cl-14>`__
    * `PySAL <http://pysal.geodacenter.org/1.3/users/tutorials/shapely.html>`__

    Shapely
    -------

    Shapely [3]_ provides a ``shape()`` function that makes Shapely geometries from
    objects that provide ``__geo_interface__`` and a ``mapping()`` function that
    writes geometries out as dictionaries::

    >>> from shapely.geometry import Point
    >>> from shapely.geometry import mapping, shape
    >>> Point(0.0, 0.0).__geo_interface__
    {'type': 'Point', 'coordinates': (0.0, 0.0)}
    >>> shape(Point(0.0, 0.0))
    <shapely.geometry.point.Point object at 0x...>
    >>> mapping(Point(0.0, 0.0))
    {'type': 'Point', 'coordinates': (0.0, 0.0)}

    The Shapely version of the example in the introduction is::

    >>> from shapely.geometry import shape
    >>> shape(obj).buffer(1.0).area
    3.1365484905459389

    where ``obj`` could be a geometry object from ArcPy or PySAL, or even a mapping
    directly::

    >>> shape({'type': 'Point', 'coordinates': (0.0, 0.0)}).buffer(1.0).area
    3.1365484905459389

    References
    ==========

    .. [1] http://docs.scipy.org/doc/numpy/reference/arrays.interface.html
    .. [2] http://geojson.org
    .. [3] https://github.com/Toblerity/Shapely
    Python has a number of built-in protocols (descriptor, iterator, etc). A very simple one involves string representations of objects. The built-in ``str()`` function calls the ``__str__()`` method of its single argument. Example::

    >>> class A(object):
  6. sgillies revised this gist Mar 27, 2012. 1 changed file with 1 addition and 1 deletion.
    2 changes: 1 addition & 1 deletion __geo_interface__.rst
    View file
    Original file line number Diff line number Diff line change
    @@ -30,7 +30,7 @@ The hypothetical ``as_geometry()`` function of the hypothetical module would acc
    __geo_interface__
    =================

    Following the lead of numpy's Array Interface [1]_, let's agree on a ``__geo_interface__`` attribute. To avoid creating
    Following the lead of numpy's Array Interface [1]_, let's agree on a ``__geo_interface__`` property. To avoid creating
    even more protocols, let's make the value of this attribute a Python mapping. To further minimize invention, let's
    borrow from the GeoJSON format [2]_ for the structure of this mapping.

  7. sgillies revised this gist Mar 27, 2012. 1 changed file with 14 additions and 3 deletions.
    17 changes: 14 additions & 3 deletions __geo_interface__.rst
    View file
    Original file line number Diff line number Diff line change
    @@ -6,7 +6,7 @@ This document describes a GeoJSON-like protocol for geospatial vector data.
    Introduction
    ============

    Python has a number of built-in protocols (descriptor, iterator, etc). A very simple one involves string representations of objects. The built-in ``str()`` function delegates to the ``__str__()`` method of its single argument. Example::
    Python has a number of built-in protocols (descriptor, iterator, etc). A very simple one involves string representations of objects. The built-in ``str()`` function calls the ``__str__()`` method of its single argument. Example::

    >>> class A(object):
    ... def __str__(self):
    @@ -18,8 +18,8 @@ Python has a number of built-in protocols (descriptor, iterator, etc). A very si
    >>> "%s" % a
    'Eh!'

    By implementing ``__str__()``, instances of any class can be printed by any other Python program. What if we could do something like this for geospatial (GIS) objects? It might, for example, let any object be analyzed using another
    hypothetical software package like this::
    By implementing ``__str__()``, instances of any class can be printed by any other Python program. What if we could do something like this for geospatial (GIS) objects? It might, for example, let any object be analyzed using any other hypothetical software package like
    this::

    >>> from some_analytic_module import as_geometry
    >>> as_geometry(obj).buffer(1.0).area # obj is a "point" of some kind
    @@ -96,6 +96,17 @@ out as dictionaries::
    >>> mapping(Point(0.0, 0.0))
    {'type': 'Point', 'coordinates': (0.0, 0.0)}

    The Shapely version of the example in the introduction is::

    >>> from shapely.geometry import shape
    >>> shape(obj).buffer(1.0).area
    3.1365484905459389

    where ``obj`` could be a geometry object from ArcPy or PySAL, or even a mapping directly::

    >>> shape({'type': 'Point', 'coordinates': (0.0, 0.0)}).buffer(1.0).area
    3.1365484905459389

    References
    ==========

  8. sgillies revised this gist Mar 27, 2012. 1 changed file with 3 additions and 3 deletions.
    6 changes: 3 additions & 3 deletions __geo_interface__.rst
    View file
    Original file line number Diff line number Diff line change
    @@ -76,9 +76,9 @@ Next, a toy class with a feature representation::
    Implementations
    ===============

    * ArcPy
    * descartes
    * PySAL
    * `ArcPy <http://help.arcgis.com/en/arcgisdesktop/10.0/help/index.html#//000v00000153000000>`__
    * `descartes <https://bitbucket.org/sgillies/descartes/src/f97e54f3b8d4/descartes/patch.py#cl-14>`__
    * `PySAL <http://pysal.geodacenter.org/1.3/users/tutorials/shapely.html>`__

    Shapely
    -------
  9. sgillies revised this gist Mar 27, 2012. 1 changed file with 22 additions and 10 deletions.
    32 changes: 22 additions & 10 deletions __geo_interface__.rst
    View file
    Original file line number Diff line number Diff line change
    @@ -30,21 +30,18 @@ The hypothetical ``as_geometry()`` function of the hypothetical module would acc
    __geo_interface__
    =================

    Following the lead of numpy's Array Interface [2]_, let's agree on a ``__geo_interface__`` attribute. To avoid creating
    Following the lead of numpy's Array Interface [1]_, let's agree on a ``__geo_interface__`` attribute. To avoid creating
    even more protocols, let's make the value of this attribute a Python mapping. To further minimize invention, let's
    borrow from the GeoJSON format [3]_ for the structure of this mapping.
    borrow from the GeoJSON format [2]_ for the structure of this mapping.

    The keys are:

    type (required)
    A string indicating the geospatial type. Possible values are "FeatureCollection", "Feature", or a geometry type: "Point", "LineString", "Polygon", etc.
    A string indicating the geospatial type. Possible values are "Feature" or a geometry type: "Point", "LineString", "Polygon", etc.

    bbox (optional)
    A tuple of floats that describes the geospatial bounds of the object: (left, bottom, right, top) or (west, south, east, north).

    features (optional)
    An iterator (including lists and other sequences) over "Feature" type mappings. Valid for "FeatureCollection" types only.

    properties (optional)
    A mapping of feature properties (labels, populations ... you name it. Dependent on the data). Valid for "Feature" types only.

    @@ -82,11 +79,26 @@ Implementations
    * ArcPy
    * descartes
    * PySAL
    * Shapely

    Shapely
    -------

    Shapely [3]_ provides a ``shape()`` function that makes Shapely geometries from objects
    that provide ``__geo_interface__`` and a ``mapping()`` function that writes geometries
    out as dictionaries::

    >>> from shapely.geometry import Point
    >>> from shapely.geometry import mapping, shape
    >>> Point(0.0, 0.0).__geo_interface__
    {'type': 'Point', 'coordinates': (0.0, 0.0)}
    >>> shape(Point(0.0, 0.0))
    <shapely.geometry.point.Point object at 0x...>
    >>> mapping(Point(0.0, 0.0))
    {'type': 'Point', 'coordinates': (0.0, 0.0)}

    References
    ==========

    .. [1] https://github.com/Toblerity/Shapely
    .. [2] http://docs.scipy.org/doc/numpy/reference/arrays.interface.html
    .. [3] http://geojson.org
    .. [1] http://docs.scipy.org/doc/numpy/reference/arrays.interface.html
    .. [2] http://geojson.org
    .. [3] https://github.com/Toblerity/Shapely
  10. sgillies revised this gist Mar 27, 2012. 1 changed file with 16 additions and 5 deletions.
    21 changes: 16 additions & 5 deletions __geo_interface__.rst
    View file
    Original file line number Diff line number Diff line change
    @@ -21,11 +21,11 @@ Python has a number of built-in protocols (descriptor, iterator, etc). A very si
    By implementing ``__str__()``, instances of any class can be printed by any other Python program. What if we could do something like this for geospatial (GIS) objects? It might, for example, let any object be analyzed using another
    hypothetical software package like this::

    >>> from some_analytic_module import shape
    >>> shape(obj).buffer(1.0).area # obj is a "point" of some kind
    >>> from some_analytic_module import as_geometry
    >>> as_geometry(obj).buffer(1.0).area # obj is a "point" of some kind
    3.1365484905459389

    The ``shape()`` function of the hypothetical module would access relevant data of its single argument using an agreed upon method or attribute.
    The hypothetical ``as_geometry()`` function of the hypothetical module would access relevant data of its single argument using an agreed upon method or attribute.

    __geo_interface__
    =================
    @@ -57,14 +57,25 @@ coordinates (required)
    Examples
    ========

    Here's a toy class with a point representation::
    First, a toy class with a point representation::

    >>> class Pointy(object):
    ... __geo_interface__ = {'type': 'Point', 'coordinates': (0.0, 0.0)}
    ...
    >>> shape(Pointy()).buffer(1.0).area
    >>> as_geometry(Pointy()).buffer(1.0).area
    3.1365484905459389

    Next, a toy class with a feature representation::

    >>> class Placemark(object):
    ... __geo_interface__ = {
    ... 'type': 'Feature',
    ... 'properties': {'name': 'Phoo'},
    ... 'geometry': Pointy.__geo_interface__ }
    >>> from my_analytic_module import as_feature
    >>> as_feature(Placemark())['properties']['name']
    'Phoo'

    Implementations
    ===============

  11. sgillies revised this gist Mar 27, 2012. 1 changed file with 4 additions and 4 deletions.
    8 changes: 4 additions & 4 deletions __geo_interface__.rst
    View file
    Original file line number Diff line number Diff line change
    @@ -18,14 +18,14 @@ Python has a number of built-in protocols (descriptor, iterator, etc). A very si
    >>> "%s" % a
    'Eh!'

    By implementing ``__str__()``, instances of any class can be printed by any other Python program. What if we could do something like this for geospatial (GIS) objects? It might, for example, let any object be analyzed using Shapely [1]_
    as simply as::
    By implementing ``__str__()``, instances of any class can be printed by any other Python program. What if we could do something like this for geospatial (GIS) objects? It might, for example, let any object be analyzed using another
    hypothetical software package like this::

    >>> from shapely.geometry import shape
    >>> from some_analytic_module import shape
    >>> shape(obj).buffer(1.0).area # obj is a "point" of some kind
    3.1365484905459389

    Shapely's ``shape()`` function would access relevant data of its single argument using an agreed upon method or attribute.
    The ``shape()`` function of the hypothetical module would access relevant data of its single argument using an agreed upon method or attribute.

    __geo_interface__
    =================
  12. sgillies revised this gist Mar 27, 2012. 1 changed file with 8 additions and 0 deletions.
    8 changes: 8 additions & 0 deletions __geo_interface__.rst
    View file
    Original file line number Diff line number Diff line change
    @@ -65,6 +65,14 @@ Here's a toy class with a point representation::
    >>> shape(Pointy()).buffer(1.0).area
    3.1365484905459389

    Implementations
    ===============

    * ArcPy
    * descartes
    * PySAL
    * Shapely

    References
    ==========

  13. sgillies revised this gist Mar 27, 2012. 1 changed file with 7 additions and 1 deletion.
    8 changes: 7 additions & 1 deletion __geo_interface__.rst
    View file
    Original file line number Diff line number Diff line change
    @@ -57,7 +57,13 @@ coordinates (required)
    Examples
    ========

    A class
    Here's a toy class with a point representation::

    >>> class Pointy(object):
    ... __geo_interface__ = {'type': 'Point', 'coordinates': (0.0, 0.0)}
    ...
    >>> shape(Pointy()).buffer(1.0).area
    3.1365484905459389

    References
    ==========
  14. sgillies revised this gist Mar 27, 2012. 1 changed file with 15 additions and 1 deletion.
    16 changes: 15 additions & 1 deletion __geo_interface__.rst
    View file
    Original file line number Diff line number Diff line change
    @@ -43,7 +43,21 @@ bbox (optional)
    A tuple of floats that describes the geospatial bounds of the object: (left, bottom, right, top) or (west, south, east, north).

    features (optional)
    A list of "Feature" type mappings. Valid only "FeatureCollection" types only.
    An iterator (including lists and other sequences) over "Feature" type mappings. Valid for "FeatureCollection" types only.

    properties (optional)
    A mapping of feature properties (labels, populations ... you name it. Dependent on the data). Valid for "Feature" types only.

    geometry (optional)
    The geometric object of a "Feature" type, also as a mapping.

    coordinates (required)
    Valid only for geometry types. This is an ``(x, y)`` or ``(longitude, latitude)`` tuple in the case of a "Point", a list of such tuples in the "LineString" case, or a list of lists in the "Polygon" case. See the GeoJSON spec for details.

    Examples
    ========

    A class

    References
    ==========
  15. sgillies revised this gist Mar 27, 2012. 1 changed file with 8 additions and 2 deletions.
    10 changes: 8 additions & 2 deletions __geo_interface__.rst
    View file
    Original file line number Diff line number Diff line change
    @@ -36,8 +36,14 @@ borrow from the GeoJSON format [3]_ for the structure of this mapping.

    The keys are:

    type (string)
    "FeatureCollection", "Feature", or a geometry type: "Point", "LineString", "Polygon", etc.
    type (required)
    A string indicating the geospatial type. Possible values are "FeatureCollection", "Feature", or a geometry type: "Point", "LineString", "Polygon", etc.

    bbox (optional)
    A tuple of floats that describes the geospatial bounds of the object: (left, bottom, right, top) or (west, south, east, north).

    features (optional)
    A list of "Feature" type mappings. Valid only "FeatureCollection" types only.

    References
    ==========
  16. sgillies revised this gist Mar 27, 2012. 1 changed file with 11 additions and 3 deletions.
    14 changes: 11 additions & 3 deletions __geo_interface__.rst
    View file
    Original file line number Diff line number Diff line change
    @@ -34,6 +34,14 @@ Following the lead of numpy's Array Interface [2]_, let's agree on a ``__geo_int
    even more protocols, let's make the value of this attribute a Python mapping. To further minimize invention, let's
    borrow from the GeoJSON format [3]_ for the structure of this mapping.

    [1] https://github.com/Toblerity/Shapely
    [2] http://docs.scipy.org/doc/numpy/reference/arrays.interface.html
    [3] http://geojson.org
    The keys are:

    type (string)
    "FeatureCollection", "Feature", or a geometry type: "Point", "LineString", "Polygon", etc.

    References
    ==========

    .. [1] https://github.com/Toblerity/Shapely
    .. [2] http://docs.scipy.org/doc/numpy/reference/arrays.interface.html
    .. [3] http://geojson.org
  17. sgillies revised this gist Mar 27, 2012. 1 changed file with 3 additions and 3 deletions.
    6 changes: 3 additions & 3 deletions __geo_interface__.rst
    View file
    Original file line number Diff line number Diff line change
    @@ -34,6 +34,6 @@ Following the lead of numpy's Array Interface [2]_, let's agree on a ``__geo_int
    even more protocols, let's make the value of this attribute a Python mapping. To further minimize invention, let's
    borrow from the GeoJSON format [3]_ for the structure of this mapping.

    .. [1] https://github.com/Toblerity/Shapely
    .. [2] http://docs.scipy.org/doc/numpy/reference/arrays.interface.html
    .. [3] http://geojson.org
    [1] https://github.com/Toblerity/Shapely
    [2] http://docs.scipy.org/doc/numpy/reference/arrays.interface.html
    [3] http://geojson.org
  18. sgillies revised this gist Mar 27, 2012. 1 changed file with 8 additions and 4 deletions.
    12 changes: 8 additions & 4 deletions __geo_interface__.rst
    View file
    Original file line number Diff line number Diff line change
    @@ -18,8 +18,8 @@ Python has a number of built-in protocols (descriptor, iterator, etc). A very si
    >>> "%s" % a
    'Eh!'

    By implementing ``__str__()``, instances of any class can be printed by any other Python program. What if we could do something like this for geospatial (GIS) objects? It might, for example, let any object be analyzed using Shapely as
    simply as::
    By implementing ``__str__()``, instances of any class can be printed by any other Python program. What if we could do something like this for geospatial (GIS) objects? It might, for example, let any object be analyzed using Shapely [1]_
    as simply as::

    >>> from shapely.geometry import shape
    >>> shape(obj).buffer(1.0).area # obj is a "point" of some kind
    @@ -30,6 +30,10 @@ Shapely's ``shape()`` function would access relevant data of its single argument
    __geo_interface__
    =================

    Following the lead of numpy's Array Interface [1]_, let's agree on a ``__geo_interface__`` attribute.
    Following the lead of numpy's Array Interface [2]_, let's agree on a ``__geo_interface__`` attribute. To avoid creating
    even more protocols, let's make the value of this attribute a Python mapping. To further minimize invention, let's
    borrow from the GeoJSON format [3]_ for the structure of this mapping.

    .. [1] http://docs.scipy.org/doc/numpy/reference/arrays.interface.html
    .. [1] https://github.com/Toblerity/Shapely
    .. [2] http://docs.scipy.org/doc/numpy/reference/arrays.interface.html
    .. [3] http://geojson.org
  19. sgillies revised this gist Mar 27, 2012. 1 changed file with 2 additions and 2 deletions.
    4 changes: 2 additions & 2 deletions __geo_interface__.rst
    View file
    Original file line number Diff line number Diff line change
    @@ -30,6 +30,6 @@ Shapely's ``shape()`` function would access relevant data of its single argument
    __geo_interface__
    =================

    Following the lead of numpy's Array Interface [1], let's agree on a ``__geo_interface__`` attribute.
    Following the lead of numpy's Array Interface [1]_, let's agree on a ``__geo_interface__`` attribute.

    [1] http://docs.scipy.org/doc/numpy/reference/arrays.interface.html
    .. [1] http://docs.scipy.org/doc/numpy/reference/arrays.interface.html
  20. sgillies revised this gist Mar 27, 2012. 1 changed file with 4 additions and 2 deletions.
    6 changes: 4 additions & 2 deletions __geo_interface__.rst
    View file
    Original file line number Diff line number Diff line change
    @@ -25,9 +25,11 @@ simply as::
    >>> shape(obj).buffer(1.0).area # obj is a "point" of some kind
    3.1365484905459389

    Shapely's ``shape()`` function would access some data of its single argument using an agreed upon method or attribute.
    Shapely's ``shape()`` function would access relevant data of its single argument using an agreed upon method or attribute.

    __geo_interface__
    =================

    A mapping with a type key.
    Following the lead of numpy's Array Interface [1], let's agree on a ``__geo_interface__`` attribute.

    [1] http://docs.scipy.org/doc/numpy/reference/arrays.interface.html
  21. sgillies revised this gist Mar 27, 2012. 1 changed file with 25 additions and 1 deletion.
    26 changes: 25 additions & 1 deletion __geo_interface__.rst
    View file
    Original file line number Diff line number Diff line change
    @@ -1,7 +1,31 @@
    Abstract
    ========

    This document describes a GeoJSON-like protocol for geospatial vector data.

    Introduction
    ============

    Blah, blah.
    Python has a number of built-in protocols (descriptor, iterator, etc). A very simple one involves string representations of objects. The built-in ``str()`` function delegates to the ``__str__()`` method of its single argument. Example::

    >>> class A(object):
    ... def __str__(self):
    ... return "Eh!"
    ...
    >>> a = A()
    >>> str(a)
    'Eh!'
    >>> "%s" % a
    'Eh!'

    By implementing ``__str__()``, instances of any class can be printed by any other Python program. What if we could do something like this for geospatial (GIS) objects? It might, for example, let any object be analyzed using Shapely as
    simply as::

    >>> from shapely.geometry import shape
    >>> shape(obj).buffer(1.0).area # obj is a "point" of some kind
    3.1365484905459389

    Shapely's ``shape()`` function would access some data of its single argument using an agreed upon method or attribute.

    __geo_interface__
    =================
  22. sgillies revised this gist Mar 27, 2012. 1 changed file with 6 additions and 1 deletion.
    7 changes: 6 additions & 1 deletion __geo_interface__.rst
    View file
    Original file line number Diff line number Diff line change
    @@ -1,4 +1,9 @@
    Introduction
    ============

    Blah, blah.

    __geo_interface__
    =================

    A mapping with a type key.
    A mapping with a type key.
  23. sgillies created this gist Mar 27, 2012.
    4 changes: 4 additions & 0 deletions __geo_interface__.rst
    View file
    Original file line number Diff line number Diff line change
    @@ -0,0 +1,4 @@

    __geo_interface__

    A mapping with a type key.