@mapbox/graph-normalizer - npm Package Compare versions

Comparing version 2.0.3 to 2.0.4

package.json

 {
   "name": "@mapbox/graph-normalizer",
-  "version": "2.0.3",
+  "version": "2.0.4",
   "description": "Takes nodes and ways and turn them into a normalized graph of intersections and ways.",
@@ -5,0 +5,0 @@ "bin": "./bin/normalize-ways",

README.md

@@ -6,5 +6,5 @@ # Graph-normalizer
 
-In this latest v2 version, graph-normalizer is a Command Line Interface that pipes in a geojson file of ways (usually at the z7 level), and outputs normalized pieces of graph at the z14 level.
+`graph-normalizer` is a Command Line Interface that pipes in a geojson file of ways (usually at the z7 level), and outputs normalized pieces of graph at a given zoom level.
 
-This package is intended as a utility for graph-tiler.
+This package is intended as a utility for graph-tiler, but can be used on its own.
 
@@ -24,3 +24,3 @@ ### Installation
 
-The output is a number of files, each named by its quadkey, of line-delimited geojson way features.
+The output is a number of files, named `<quadkey>.json`, of line-delimited geojson way features.
 
@@ -31,3 +31,22 @@ It satisfies the following constraints:
 - Normalized way ids keep track of the history of transformations that led to it.
+- `highway` and `oneway` tags are conserved from the original graph.
 
 Edges that are shared by multiple tiles are conserved in all of them.
+
+It is recommended to keep the output zoom level high, as performance might drop when trying to normalize at a larger scale.
+
+### Algorithm
+
+`graph-normalizer` expects geojson LineString features that have a `refs` property, each ref corresponding to the node id of the matching coordinates in the `geometry.coordinates` array.
+
+Any way that does not respect this constraint will be dropped.
+
+The algorithm follows this workflow:
+
+- **Indexing** - It loads the ways into memory and indexes their segments into the quadkey(s) of the target zoom level in which they land.
+
+- **Tiling** - For each quadkey, it reconstructs each way from its segments. The segments of the original way that do not intersect with the tile are effectively dropped from this tile. Conversely, any segment that overlaps multiple tiles will be duplicated in all tiles.
+
+- **Splitting** - Having the ways from each quadkey, `graph-normalizer` then splits the ways that traverse an intersection into two. `!<i>` is appended to the way id where `i` is the index of the split way in the original geometry.
+
+- **Merging** - Ways that share a node which is not an intersection (only 2 way owners) are merged together. The resulting id is `<wayOne>,<wayTwo>`.

No alert changes

Improved metrics

Total package byte prevSize

7353409

increased by0.02%

Number of lines in readme file

50

increased by61.29%

No dependency changes