GeometryDefinition

Geometry definition

Every CouchDB design document can contain information for populating GeoCouch’s spatial index. All you need to do is adding a geo property to one of your design documents. This property defines where to find geometries within your documents and which type they have. Supported Simple Features as specified by the OGC are Points, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon (GeometryCollection isn’t supported).

General properties

  • _srid (optional, default: 4326)
    Specifies the SRID that should be used for the geometry.
  • arbitrary string (mandatory)
    Every string without a leading underscore (_) will be interpreted as a geometry name. This name is important when you query the database (e.g. for bounding box searches).
    • type (mandatory)
      Type of the geometry. At the moment Point and LineString are supported.
    • coordinates (mandatory)
      Where to to find the actual x and y coordinates in the documents. The syntax is quite simple (bit like XPath/JSONPath), a dot (.propertyname) for properties, array notation for an
      array element ([position]). The escape character is backslash ().

Example geo property (in a CouchDB design document):

{
    "_srid": 4326,  
    "loc": {  
       "type": "Point",  
       "coordinates": [  
         "geometry.coordinates[0]",  
         "geometry.coordinates[1]"  
       ]  
    }  
}

For a document like:

{
    "type": "Feature",  
    "geometry": {  
        "type": "Point",  
        "coordinates": [10.46, 51.17]  
    },  
    "name": "Germany"  
}

Geometry type specific properties

Some properties are specific to a geometry type.

Point

  • arbitrary string
    • root (optional)
      Sets a root path which is prepended to the coordinates paths.
      Examples (all are equivalent):
      {
      "loc": {
    "type": "Point",  
    "coordinates": [  
        "geometry.coordinates[0]",  
        "geometry.coordinates[1]"  
    ]  
}
      }
      {
      "loc": {
    "type": "Point",  
    "root": "geometry",  
    "coordinates": [  
        "coordinates[0]",  
        "coordinates[1]"  
    ]      
}
      }
      {
      "loc": {
    "type": "Point",  
    "root": "geometry.coordinates",  
    "coordinates": [  
        "[0]",  
        "[1]"  
    ]  
}
      }

LineString

  • arbitrary string
    • root (mandatory)
      A LineString is a list of points, root specifies the property that contains the list of points. GeoCouch loops through this list and takes the points specified in the coordinate property. Two examples should make it a bit clearer.
      Example 1:
      Document
      {
      "street": [
    [10, 20], [10, 30], [20, 30]  
]
      }
      geo property
      {
      "streets": {
    "type": "LineString",  
    "root": "street",  
    "coordinates": [  
        "[0]", "[1]"  
    ]  
}
      }
      Example 2:
      Document
      {
      "street": [
    {"x": 10, "y": 20}, {"x": 10, "y": 30}, {"x": 20, "y": 30}  
]
      }
      geo property
      {
      "streets": {
    "type": "LineString",  
    "root": "street",  
    "coordinates": [  
        "x", "y"  
    ]  
}
      }

Polygon

GeoCouch uses Shapely internally therefore polygons will automatically closed if starting and end point are not the same.

To support holes, Polygons are organised in so-called rings. One ring (the exterior ring) may contain multiple holes (interior rings).

  • arbitrary string
    • root (mandatory)
      The root property specifies the path to the exterior ring. As always it’s prepended to the coordinates path.
    • holes (optional)
      The holes property specifies holes (interior rings) within a polygon. One polygon may contain one or more holes.
      • *multiple (optional, default: true)
        Whether the polygon contains more than one hole or not.
      • root (mandatory)
        If multiple is false, the root property is simply looped through to get the coordinates. If multiple is true, then root specifies a list of holes that is lopped through (where every hole is looped through again for the coordinates).
        Example 1 (single hole):
        Document
        {
        “donut”: [
          [[10, 20], [10, 30], [50, 30], [50, 20]],
  [[12, 22], [12, 28], [48, 28], [48, 22]]
        ]
        }
        geo property
        {
        “_srid”: 4326,
        “donuts”: {
          "type": "Polygon",
  "root": "donut[0]",  
  "coordinates": [  
      "[0]", "[1]"  
  ],  
  "holes": {  
      "root": "donut[1]",  
      "multiple": false,  
      "coordinates": [  
          "[0]", "[1]"  
      ]  
  }
        }
        }
        Example 2 (two holes):
        Document
        {
        “donut”: [
          [[10, 20], [10, 30], [50, 30], [50, 20]],
  [  
      [[12, 22], [12, 28], [48, 28]],  
      [[48, 26], [48, 22], [14, 22]]  
  ]
        ]
        }
        geo property
        {
        “_srid”: 4326,
        “donuts”: {
          "type": "Polygon",
  "root": "donut[0]",  
  "coordinates": [  
      "[0]", "[1]"  
  ],  
  "holes": {  
      "root": "donut[1]",  
      "multiple": true,  
      "coordinates": [  
          "[0]", "[1]"  
      ]  
  }
        }
        }
        Example 3: (no holes)
        Document
        {
        “rectangle”: [
          [10, 20], [10, 30], [50, 30], [50, 20]
        ]
        }
        geo property
        {
        “_srid”: 4326,
        “rectangles”: {
          "type": "Polygon",
  "root": "rectangle",  
  "coordinates": [  
      "[0]", "[1]"  
  ]
        }
        }

MultiPoint

  • arbitrary string
    • root (mandatory)
      Sets a root path which contains a list of Points. It is looped through to access the indiviual Points as specified by the coordinates paths.
      Example:
      Document:
      {
      "type": "Feature",
"geometry": {  
    "type": "MultiPoint",  
    "coordinates": [  
        [10.46, 51.17],  
        [14.61, 31.79],  
        [24.82, 35.86]  
    ]  
},  
"name": "Somepoints"
      }
      geo property:
      {
      "loc": {
    "type": "MultiPoint",  
    "root": "geometry.coordinates",  
    "coordinates": [  
        "[0]",  
        "[1]"  
    ]      
}
      }

MultiLineString

  • arbitrary string
    • root (mandatory)
      Sets a root path which contains a list of LineStrings. It is looped through to access the indiviual points as specified by the coordinates paths.
      Example:
      Document:
      {
      "type": "Feature",
"geometry": {  
    "type": "MultiLineString",  
    "coordinates": [  
        [  
            [10.46, 51.17], [14.61, 31.79]  
        ],[  
            [10, 20], [10, 30], [20, 30]  
        ]  
    ]  
},  
"name": "Somelines"
      }
      geo property:
      {
      "loc": {
    "type": "MultiLineString",  
    "root": "geometry.coordinates",  
    "coordinates": [  
        "[0]",  
        "[1]"  
    ]      
}
      }

MultiPolygon

  • arbitrary string
    • root (mandatory)
      Sets a root path which contains a list of MultiPolygons. It is looped through and each item is treated like a Polygon (see Polygon section for more information).
    • *polygon (optional)
      The polygon property specifies a path where to find the polygon relative to the looped through root.
    • holes (optional)
      All properties from Polygon (see that section for more information) and additionally:
      • rings (optional)
        The rings property specifies a path where to find the (interior) rings relative to the looped through root.
        Example 1
        Document
        {
        “donuts”: [
          [
      [[10, 20], [10, 30], [50, 30], [50, 20]],  
      [[[12, 22], [12, 28], [48, 28], [48, 22]]]  
  ],[  
      [[110, 120], [110, 130], [150, 130], [150, 120]],  
      [[[112, 122], [112, 128], [148, 128], [148, 122]]]  
  ]
        ]
        }
        geo property
        {
        “_srid”: 4326,
        “donuts”: {
          "type": "MultiPolygon",
  "root": "donuts",  
  "polygon": "[0]",  
  "coordinates": [  
      "[0]", "[1]"  
  ],  
  "holes": {  
      "root": "donuts",  
      "rings": "[1]",  
      "multiple": true,  
      "coordinates": [  
          "[0]", "[1]"  
      ]  
  }
        }
        }
        Example 2
        Document
        {
        “donuts”: {
          "exterior": [
      [[10, 20], [10, 30], [50, 30], [50, 20]],  
      [[110, 120], [110, 130], [150, 130], [150, 120]]  
  ],  
  "interior": [  
      [[12, 22], [12, 28], [48, 28], [48, 22]],  
      [[112, 122], [112, 128], [148, 128], [148, 122]]  
  ]
        }
        }
        geo property
        {
        “_srid”: 4326,
        “donuts”: {
          "type": "MultiPolygon",
  "root": "donuts.exterior",  
  "coordinates": [  
      "[0]", "[1]"  
  ],  
  "holes": {  
      "root": "donuts.interior",  
      "multiple": false,  
      "coordinates": [  
          "[0]", "[1]"  
      ]  
  }
        }
        }

17 Sep 16:48