= Extended Regions =

|| '''Date''' || 2012/09/14 ||
|| '''Contact(s)''' || [http://wiki.osgeo.org/wiki/User:Jeichar Jesse Eichar] ||
|| '''Last edited''' || ||
|| '''Status''' || Motion Passed - Done ||
|| '''Assigned to release''' || 2.9.x ||
|| '''Resources''' || Swisstopo ||
|| '''Code''' || https://github.com/jesseeichar/core-geonetwork/tree/improvement/regions ||

== Overview ==

This proposal intends to extend the existing Regions API with the following features:

 * Add category for each region so they can be displayed in categories (for example continent, country, province)
 * Add API for searching regions based:
  * name
  * category
  * bbox
 * Add optional geometry for each region (in addition to bbox)
 * integrate into !XmlSearch and Csw so that the region id can be used to look up the geometry of the region for a spatial filter
 * Add a configurable strategy object for that allows the region implementation to be easily pluggable.  For example it might be based on a table in the rdf file or wfs 

=== Proposal Type ===
 * '''Type''': Improvement
 * '''App''': Geonetwork
 * '''Module''': Web

=== Links ===
 
 * '''Email discussions''':
 * '''IRC discussions''':
 * '''Related work''':

 
=== Voting History ===

 * None as yet

----


== Proposal == 

The Regions will be backwards compatible but will simply extend the functionality.  Currently the Regions API provides a list of regions, each with a unique id.  Each region has translated labels and a bounding box.  The proposal will extend that API.  The new API will be:


 * Get
  * Params
    * id - required
  * Example Response: 
{{{
<regions>
  <region id="338" hasGeom="false" categoryId="continent">
    <north>38.2</north>
    <south>-34.6</south>
    <west>-17.3</west>
    <east>51.1</east>
    <label>
      <eng>Africa</eng>
      <fre>Afrique</fre>
      <ger>Afrika</ger>
      <spa>Africa</spa>
      <rus>Africa</rus>
      <por>Africa</por>
      <chi>Africa</chi>
      <dut>Afrika</dut>
      <nor>Africa</nor>
      <fin>Africa</fin>
      <ara>Africa</ara>
      <ita>Africa</ita>
    </label>
    <category>
         <fre>Continent</fre>
         <eng>Continent</eng>
    </category>
  </record>
</response>
}}}
 * List
  * Params
   * category - only return labels contained in the given category - optional
   * label - searches the labels for regions that contain the text in this parameters - optional
   * maxRecords - limit the number of results returned - optional
  * Example Response
{{{
<regions count="1">
  <region id="country.1" hasGeom="true" categoryId="country">
    <label>
      <eng>France</eng>
    </label>
    <category>
         <fre>Pays</fre>
         <eng>Country</eng>
    </category>
  </region>
</regions>
}}}
 * !GetGeom - will return the geometry for the region. If the geometry does not have a geometry then the bbox will be used to construct a polygon.
  * Params
   * id - required
   * simplified - optional (if present and true then the geometry will be a simplified version.  Some implementations may ignore this hint and return full geometry)
  * Example Response:
{{{
  MULTIPOLYGON (((30 20, 10 40, 45 40, 30 20)), ((15 5, 40 10, 10 20, 5 10, 15 5)))
}}}
 * !GetMap - return a rendering of the geometry as a png.  If no background is specified the image will be a transparent png
  * id - required
  * mapsrs - (optional) default is EPSG:4326 otherwise it is the project to use when rendering the image
  * width - (optional) width of the image that is created.  Only one of width and height are permitted
  * height - (optional) height of the image that is created.  Only one of width and height are permitted
  * background - (optional) URL for loading a background image for regions or a key that references the namedBackgrounds (configured in config.xml).   A WMS Getmap request is the typical example.  The URL must be parameterized with the following parameters: 
   * minx
   * maxx
   * miny
   * maxy
   * width
   * height
   * srs (optional)
 * geom - (optional) a wkt or gml encoded geometry. 
 * geomtype - (optional) defines if geom is wkt or gml.  allowed values are wkt and gml.  if not specified the it is assumed the geometry is wkt
 * geomsrs - (optional) the srs of the geometry passed in via the geom parameter

'''!XmlSearch and !CswSearch Integration'''

The !XmlSearch API will be modified so the geom parameter can either be WKT or have the form: region:id, where id is the id of the region to use as a geometry.  If the region has a geometry then that geometry will be loaded otherwise the bbox will be used to create a polygon geometry.

For example:

 * Search for metadata intersecting with france:
  * http://localhost:8080/geonetwork/srv/eng/q?fast=index&from=1&to=20&geometry=region:http%3A%2F%2Fgeonetwork-opensource.org%2Fregions%2368
 * Search within the union of France and Switzerland, two regions are comma separated (http%3A%2F%2Fgeonetwork-opensource.org%2Fregions%2368 is the uri encoded id of france and http%3A%2F%2Fgeonetwork-opensource.org%2Fregions%23211 is the encoded id of switzerland)
  * http://localhost:8080/geonetwork/srv/eng/q?fast=index&from=1&to=20&geometry=region:http%3A%2F%2Fgeonetwork-opensource.org%2Fregions%23211,http%3A%2F%2Fgeonetwork-opensource.org%2Fregions%2368

The !CatalogSearcher (part of Csw !GetRecords) will be modified to replace elements with the attribute gml:id which have the form: region:id.

For example:
{{{
<csw:GetRecords xmlns:csw="http://www.opengis.net/cat/csw/2.0.2" service="CSW" version="2.0.2" resultType="results_with_summary" startPosition="1" maxRecords="10">
  <csw:Query typeNames="csw:Record">
    <csw:ElementSetName>full</csw:ElementSetName>
    <ogc:SortBy xmlns:ogc="http://www.opengis.net/ogc">
      <ogc:SortProperty>
        <ogc:PropertyName>relevance</ogc:PropertyName>
        <ogc:SortOrder>DESC</ogc:SortOrder>
      </ogc:SortProperty>
    </ogc:SortBy>
    <csw:Constraint version="1.0.0">
      <ogc:Filter xmlns:ogc="http://www.opengis.net/ogc">
        <ogc:And>
          <ogc:PropertyIsEqualTo>
            <ogc:PropertyName>similarity</ogc:PropertyName>
            <ogc:Literal>0.8</ogc:Literal>
          </ogc:PropertyIsEqualTo>
          <ogc:Within>
            <ogc:PropertyName>ows:BoundingBox</ogc:PropertyName>
            <gml:MultiPolygon xmlns:gml="http://www.opengis.net/gml" gml:id="kantone:10,kantone:22"/>
          </ogc:Within>
        </ogc:And>
      </ogc:Filter>
    </csw:Constraint>
  </csw:Query>
</csw:GetRecords>
}}}

'''Implementation Notes'''

The actual implementation will consist of the services and a strategy object that can be configured the geonetwork configuration files (config-spring.xml).  The intention is that for a particular application the strategy object can be implemented and configured for use.  The default implementation will be the current implementation factored out into the strategy object.

The main strategy object is called:

RegionsDAO which is the entry point into searching and querying regions.  See the javadocs of this class for information on how to use the class and implement new custom regions strategies.

'''Default implementations'''
Two strategies will be shipped with Geonetwork by default:

 * Thesaurus Regions - The regions and region categories are derived from the regions listed in the regions thesaurus that is shipped with geonetwork by default
* Metadata Regions - Each region is an extent in one of the metadata elements.  Because of the cost to search the metadata the first version will no allow list searching all regions in this strategy.  The search options are limited to category (the fileid of the MD), this will list the ids of the "regions/extents" within that metadata.  The other option is to get a region by id.  This is the form:  metadata:<fileIdentifier>:<edit ref of geometry>.  In the first version only iso19139 can be obtained and only polygons (not bbox) 


'''Example URLS'''
 * http://localhost:8080/geonetwork/srv/eng/xml.regions.category.list
 * http://localhost:8080/geonetwork/srv/eng/xml.regions.list?categoryId=country
 * http://localhost:8080/geonetwork/srv/eng/xml.regions.list?categoryId=kantone
 * http://localhost:8080/geonetwork/srv/eng/xml.regions.list?categoryId=kantone&categoryId=country
 * http://localhost:8080/geonetwork/srv/eng/xml.regions.list?categoryId=gemeinden
 * http://localhost:8080/geonetwork/srv/eng/xml.regions.list?categoryId=gemeinden&maxRecords=5
 * http://localhost:8080/geonetwork/srv/eng/xml.region.get?id=kantone:25
 * http://localhost:8080/geonetwork/srv/eng/region.geom.wkt?id=kantone:25
 * http://localhost:8080/geonetwork/srv/eng/region.geom.wkt?id=kantone:25&srs=EPSG:21781
 * http://localhost:8080/geonetwork/srv/eng/region.getmap.png?id=kantone:25&height=100
 * http://localhost:8080/geonetwork/srv/eng/region.getmap.png?id=kantone:25&srs=EPSG:21781&height=100
 * http://localhost:8080/geonetwork/srv/eng/xml.regions.list?label=aarg
 * http://localhost:8080/geonetwork/srv/eng/xml.regions.list?label=aarg&categoryId=kantone
 * http://localhost:8080/geonetwork/srv/eng/xml.regions.list?label=aarg&maxRecords=5

=== Backwards Compatibility Issues ===

The set of regions will not be the same as for the previous versions because they will be derived from the thesaurus instead of database.

== Risks ==

== Participants ==
 * As above