Improve documentation and code comments

[miles-dev]

Working on a project to better understand how to use this repo. Using South Sudan as a sample use case for diff'ing.

Goals:

1. Primary: use this project to produce geojson which represents the new roads in OSM within South Sudan when comparing January 2017 with January 2016.
2. Secondary goal is to document the steps necessary to produce this and update the README.md in this repo for future use.

Resources:

• This repo
• https://osmlab.github.io/osm-qa-tiles/historic.html - Where to pull the entire planet QA tiles for January 2016.
• https://osmlab.github.io/osm-qa-tiles/country.html - Where to pull today's QA tiles on a country level.

/cc @tcql

[miles-dev]

Current status:

• I've successfully gotten this repo to run:
  • Used the master branch to create the valid geojson output which is all one big block of text.
  • Used the linestrings branch to create ldjson (line delimited json) which isn't valid geojson, but is broken out as one feature per line and thus is easier to work with.
• Changes to index.js (these are for the linestrings branch, but are nearly identical on the master branch):
  • Rename the second process.argv to a relevant name (in my case south_sudan).
  • Add sourceCover: 'south_sudan', to the tileReduce object.
  • This will have it only diff within the bounds of the south_sudan.mbtiles file and not the entire planet.
  • Rename the second tileReduce object's source to a relevant name (in my case south_sudan).
  • Update both source object's mbtiles path to just be the same of the process.argv variables (in this case osm and south_sudan respectively).
  • Update the name of the output file.
• Change to the diff.js (these are for the linestrings branch, but are nearly identical on the master branch):
  • Change the tiger2015 property to be osm.
  • This is found by running: sqlite3 south_sudan.mbtiles in your terminal and then select * from metadata limit 15;. Look for this line in the output json|{"vector_layers":[{"id":"osm","description":"","minzoom":12,"maxzoom":12,"fields":{}}]} and use the value of the id field.
  • Replace all occurrences of 'tigerwith a more relevant name (in my casesouth_sudan`).
• Successfully ran the diff project:
  • npm install
  • linestring branch: node index.js <path_to_planet.mbtiles> <path_to_south_sudan.mbtiles>
  • master branch: node index.js > south_sudan_diff.geojson

[miles-dev]

@tcql - Inspecting the geojson I got back, I noticed that I'm getting results which doesn't look like roads to me. As an example, https://www.openstreetmap.org/edit?way=466049354#map=16/8.7761/27.4289. The large straight line marking the edge of the grasslands there is coming back in my diff. Given that isn't a road I wouldn't expect it to be part of my results. Does this look like an incorrectly mapped feature or something not being filtered out in this repo?

[mourner]

@miles-dev the diff.js script only considers lines with highway property and Tiger roads with FULLNAME property. You may need to modify this line: https://github.com/mapbox/road-diff/blob/master/diff.js#L61

[mourner]

I'll close this since this is not an actual, actionable issue with the repository. It's a working example of using linematch for road diffing in TileReduce, and tweaks when using other data sources are expected.

[mourner]

On a second thought, let's keep this open until we improve the readme and code comments to make it easier to customize for various use cases.

[miles-dev]

Created a new branch osm_to_osm_diff which includes the updated README.md as well as changes to the index.js and diff.js to specifically target OSM vs OSM diffing. End goal here is for that to be 'walk up usable' with little to no code adjustment when diffing two OSM mbtiles files.

[miles-dev]

Question for @mourner and @aaronlidman - What're your thoughts on me merging my new osm_to_osm_diff into master? The differences as I'm tracking them:

• osm_to_osm_diff is setup to expect two OSM mbtiles file and not a tiger one.
• osm_to_osm_diff returns ldjson rather than full geojson
• osm_to_osm_diff takes in the mbtiles files as arguments of the CLI and writes the output to a specific file rather than standard out.
• osm_to_osm_diff uses a slightly different filter meant for any OSM file for just roads as the tiger filter was bringing through other non-road data.

[mourner]

@miles-dev I'm not sure about making OSM vs OSM the default implementation. I think OSM vs Tiger is a more common use case (comparing different datasets).

[miles-dev]

@mourner - Sounds good. I'll leave this as a separate branch for now then. I think I'm all set here with updating the readme and updating the code for osm-to-osm diffing. Closing out this ticket.