Indicate which geometry alt should be used for reverse geocoding

[stepps00]

(updated) We should indicate to Point in Polygon (reverse geo) services which of the multiple geometry alts to use as the default geometry is not always the best to use.

In the following example we should use Quattroshapes geometries by defaul, instead of NaturalEarth geometries (this is true for several records). As seen in Canada (below), this caused the descendants of Sumas, WA to be given a hierarchy that contained Canada.

This is due to the NaturalEarth shapes overlapping international borders (Canada overlapping the US shown below):

We should add a new property that specifies which alt-shape to use with PIP service.

[nvkelso]

I've updated the title to reflect the data model change.

@dianashk, @trescube, and @thisisaaronland for PIP reverse geo service implications.

[nvkelso]

I propose this new property go in the src property block like so:

src:rev_geo = quattroshapes

[nvkelso]

@thisisaaronland there are a bunch of WOF venues that will need reprocessing, and this faulty PIP results will also affect OSM record decoration in Pelias until it's fixed.

[nvkelso]

We'll need to backfill this for country place types only at first.

[nvkelso]

Here's a white boarding session from last week:

Even without all that moving around, I think it'd be pretty easy to take the ~10 countries with ne sourced geometries and set a new revgeo property to qs for now to unblock Pelias. It's just a question of what namespace to put it in? Loose in the top-level property or under wof or in a new geometry section in properties (unless that's confusing with the geometry object sibling to properties in GeoJSON)?

[nvkelso]

Related, generating "display" geometries at 640, 2048, and 4096 resolutions: #131

[thisisaaronland]

How is this related? I mean I understand that they're related by the pointers but one issue is about the pointers and the other is about actually generating files.

[nvkelso]

Making this the forward original (sorry @nvkelso) of #224.

and here's @thisisaaronland relevant comment copied here:

I would like to propose that we categorize reverse-geocoding by level. Specifically:

level 0 (default) - land-masses; basically places where fish would die, 
notwithstanding lakes and rivers and the like.

level 1 - land-masses but inclusive of coastal areas; places where 
fishermen in newfoundland would petition the federal government to 
seize the fishing trawlers of countries like portugal and japan; the so-called 
"200 mile" limit for some definition of "200 miles"

And so on. Honestly we can (and should) stop there for the time being. The
 notion of levels would allow for things like the Alphashapes and the notion 
of reverse-geocoding at something rather than in it. But that is tomorrow's problem.

All of which is to say, this is what the mz: namespace is for. So mz:reversegeo and 
perhaps mz:reversegeo#1 if necessary ?

I'd like to think about fragment identifiers in keys/machinetags but at a glance 
nothing seems overly problematic about the idea...

[nvkelso]

@thisisaaronland Regarding #367 (comment), exactly that & making related issues easier to find.

[nvkelso]

Copying over discussion from a few other issues into this main issue.

Template:

• id-alt-source-use-scope-detail.geojson

Where:

• source (eg: uscensus), common – this is the raw original geom from the source
• ** function** is intended use (e.g.: display), common-optional – why would this be in the filename, should it instead be a property in the master record pointing at one of these geom alt files?
• scope is level-of-scope (e.g.: terrestrial), optional
• detail is the level-of-detail (e.g.: zoom10 or 1024px), optional

All together:

• 85668127-alt-uscensus-display-terrestrial-zoom10.geojson

And in the master record:

• "src:geom_alt":[ "uscensus-display-terrestrial-zoom10"],

Permutations:

• 85668127-alt-uscensus.geojson (common)
• 85668127-alt-uscensus-display.geojson (common-optional)
• 85668127-alt-uscensus-display-terrestrial.geojson (optional)
• 85668127-alt-uscensus-display-zoom10.geojson (optional)
• 85668127-alt-uscensus-display-1024px.geojson (optional)
• 85668127-alt-uscensus-display-terrestrial-zoom10.geojson (optional)
• 85668127-alt-uscensus-display-terrestrial-1024px.geojson (optional)

From #538 (comment):

Since I can't find a goal list for Who's On First geometries, here's my list.

• search for place by text (free or structured, e.g. forward geocoding) and getting back a (label) lat-long, (label) bounding box, full geometry, and hints about "hierarchy label" generation.
• reverse geocode of lat-long to a place (preferring the "biggest" shape inclusive of territorial waters)
• data visualization (map display) based on polygon features (e.g. choropleth, with some sophistication around water and land parts, preferring the land parts)
• label basemap "points" (e.g.: locality townspots + text) and "polygons" (e.g.: region area text). It's important to know which "locality" features do not usually represent a single compact populated place so their mz:min_zoom can be properly set, and we can choose the correct "point" or "polygon" labeling (and possibly switch between them at different zooms)
• showing boundary lines on a basemap (e.g. region boundary, disputed area boundaries, with some sophistication around water and land parts – e.g. option to not show territorial water parts, coastline parts, and/or inland water parts).

Function: I think the above use goals map to:

• display - if we've optimized it for display
• search - if we've optimized it for reverse geocoding

From #539:

Scope (geometry clipping is one of):

• territorial - default optimized for revGeo inclusive of all marine and territorial waters (no water clipping), understood that Mapzen may have modified the original, but it's still "sourced" to the source.
• terrestrial - clipped to land + terrestrial waters (e.g. clipped to ocean coastline, but not punched thru for large inland water bodies), understood that Mapzen may have modified the original, but it's still "sourced" to the source. Used for most choropleth maps.
• land - no marine waters, no inland waters. Used in contexts where someone doesn't want to load separate "earth" base or "water" top layers. This matches Tilezen's kind value (terrestrial is more the general catch all for the Tilezen layer). The computed label position should be based on this geometry, when available.
• marine - geometric opposite of terrestrial, useful for boundary lines.

Here's table converting 1:x representative fractions (eg: 1:500k) into web map zooms (src), with some integer rounding:

Detail:

• zoom0
• zoom1
• zoom2 - around Natural Earth's 1:110m
• zoom3
• zoom4 - around Natural Earth's 1:50m
• zoom5
• zoom6 - around Natural Earth's 1:10m (what's in WOF today)
• zoom7
• zoom8
• zoom9 - the old Digital Chart of the World data
• zoom10 - some generalized US Census data, GlobalMap sourced data
• zoom11
• zoom12 - some of the coarser Mesoshape data
• zoom13
• zoom14
• zoom15
• zoom16 - most the existing Who's On First data, assumed WOF default until proven otherwise
• zoom17
• zoom18
• zoom19
• zoom20
• zoom21
• 100px - width by whatever height
• 256px
• 512px
• 1024px - default?
• 2048px

[thisisaaronland]

These details should go over here:

https://github.com/whosonfirst/whosonfirst-cookbook/blob/master/how_to/creating_alt_geometries.md

Again, per the last issue anything besides source and function (described above as use) is left as an arbitrary list of extras specific to the alt geometry.

[nvkelso]

Fixed use to function above. There's some delta between my comment above and what's drafted in the cookbook for @stepps00 to work flag and for us to discuss still. But it feels like we're almost there!

[stepps00]

This commit updated the whosonfirst-cookbook file that outlines alt-geometries. The file should include comments (with some minor edits and formatting) from @nvkelso.

[nvkelso]

Related: #548.

[stepps00]

For now, use Russia as a test case.
Set new reversegeo coordinate properties using the current lbl:latitude and lbl:longitude properties for any administrative areas. Place Russia's point over Moscow.

[nvkelso]

The property name should be:

• reversegeo:polygon: file-name-here
  where if the filename is id-alt-source-stuff.geojson we only store source-stuff.

For wof:placetype = country

• quattroshapes only when it's set as src:geom_alt and there exists an alt file with that src name.

For all other place types skip. The rest can be dealt with by convention, and we don't need to 2x the size of the repo unnecessarily when the default geom is fine.

In the future once #548 lands for the 24 mile nautical limit those new geoms would be added as alts, and we'd point the reversegeo:polygon property to those new alt geoms.

(Maybe it's useful someday to do this for regions, too, but someday.)

[nvkelso]

Related: #1793