# probematch

> A small module for matching probes to road networks

Latest version **2.4.0** (published 2017-03-20) · ISC license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install probematch
pnpm add probematch
yarn add probematch
bun add probematch
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 2.4.0 |
| Published | 2017-03-20 |
| First published | 2016-01-18 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 4 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Tim Channell |
| Maintainers | 1ec5, aaronlidman, aarthykc, ajashton, alulsh, amyleew, ansis, apendleton, arunasank, batpad, bhousel, bsudekum, danieljh, davidtheclark, dnomadb, emilymcafee, emilymdubois, flippmoke, freenerd, geohacker, ghoshkaj, gretacb, ian29, ianshward, ingalls, isiyu, jfirebaugh, jrpruit1, kaidalgleish, karenzshea, kkaefer, lbud, lily-chai, lxbarth, lyzidiamond, mapbox-admin, mapsam, mateov, mattficke, mcwhittemore, miccolis, mollymerp, morganherlocker, mourner, nickidlugash, planemad, rclark, samanbb, sbma44, scothis, sgillies, springmeyer, tcql, themarex, tristen, virginiayung, willwhite, yhahn, zmully |
| Keywords | gps, match, probe, geojson |

## Links

- npm: https://www.npmjs.com/package/probematch
- npm.io page: https://npm.io/package/probematch

## Dependencies (4)

- [rbush](https://npm.io/package/rbush.md) ^2.0.1
- [xtend](https://npm.io/package/xtend.md) ^4.0.0
- [cheap-ruler](https://npm.io/package/cheap-ruler.md) ^2.4.0
- [turf-linestring](https://npm.io/package/turf-linestring.md) ^1.0.0

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 2.4.0 (latest) — 2017-03-20
- 2.3.1 — 2016-12-02
- 2.2.0 — 2016-11-10
- 2.1.0 — 2016-11-08
- 2.0.0 — 2016-08-05
- 1.1.1 — 2016-08-03
- 1.1.0 — 2016-03-18
- 1.0.0 — 2016-01-18

## README

# probematch

Match a single GPS measurements (probe) or line of sequential GPS measurements (trace) to a road network.

*probematch* creates an [rbush index](https://github.com/mourner/rbush) of a road network to allow you to quickly match probes or traces to the roads using configurable distance and bearing filters.

### terms

- **probe** - a single GPS measurement, represented by a Feature<Point>
- **trace** - a collection of sequential GPS measurements, represented by a Feature<LineString>
- **road** - a Feature<LineString> representing a road, which we may attempt to match probes and traces to
- **roads, network, road network** - a FeatureCollection of roads
- **segment** - a single edge of a road. For road A -> B -> C, there are two segments: A -> B and B -> C. Segments always have only 2 points.

# install

`npm install probematch`

# configuration

```js
var probematch = require('probematch');

var roads = {
  'type': 'FeatureCollection',
  'features': [
    // Linestring features representing the road network
  ]
};

var matcher = probematch(roads, {
  compareBearing: true,
  maxBearingRange: 5,
  bidirectionalBearing: false,
  maxProbeDistance: 0.01
});
```

key | type | default | description
--- | --- | --- | ---
compareBearing | boolean | true | Should bearing of probes be used to evaluate match quality? <br /><br />If true, the bearing of the probe is compared to the bearing of each possible matching road segment. This ensures probes don't match cross-streets that obviously aren't the same as the probe's direction of travel
maxBearingRange | number | 5 | Maximum amount in degrees that a probe's bearing may differ from a road segment's when using `compareBearing`
bidirectionalBearing | boolean | false | Should bearing matches allow for probes to be moving in the opposite direction of a road segment's bearing? This should be true if the road network includes 2-way roads.
maxProbeDistance | number | 0.01 | Maximum distance in kilometers that a probe may be from a road segment in order to consider it a possible match. Prevents matching probes to segments that are too far away from them.




# usage
## match

```js
var probematch = require('probematch');

var roads = /* FeatureCollection of road geometries */;
var matcher = probematch(roads, {/* configuration */});

var probe = {
  type: 'Feature',
  geometry: {
    type: 'Point',
    coordinates: [0, 0]
  }
};

var probeBearing  = 57; // probe's direction of travel in degrees

var results = matcher(probe, probeBearing);
```

The result of matching a single proble is an array of possible matches to the road network. Results are ordered by the probe's distance from the candidate road.

Each possible match represents a single segment of a road that is likely to have matched the probe - Multiple segments from the same road could be in the array.

key | type | description
--- | --- | ---
**road** | Feature&lt;LineString&gt; | The geometry of a road that may have been matched
**segment** | Feature&lt;LineString&gt; | The particular segment of the road that the probe may have matched
**distance** | number | Distance (in miles) between the probe and the segment

### Segments

Each segment is a single edge of a road. For road A -> B -> C -> D, there are 3 segments:

- A -> B
- B -> C
- C -> D

As a segment always represents a single edge, segments have only 2 points.

Segments contain specific properties, generated by probematch when the road network is indexed.

##### segment.properties

key | type | description
--- | --- | ---
**roadId** | int | Index in the original road network FeatureCollection of the road this segment belongs to. If roadId = 3, this segment's associated road is `roads.features[3]`
**segmentId** | int | Index indicating which edge of the road this segment is. <br />For road A -> B -> C, <ul><li>A -> B has `segmentId = 0`</li><li>B -> C has `segmentId = 1`</li></ul>
**bearing** | number | The [absolute bearing](https://en.wikipedia.org/wiki/Absolute_bearing) of the segment, used when matching probe bearing.


## matchTrace


```js
var probematch = require('probematch');

var roads = /* FeatureCollection of road geometries */;
var matcher = probematch(roads, {/* configuration */});

var results = matcher.matchTrace(line);
```

`matchTrace` returns an array of `match` results. The order of results is the same as the order of the coordinates in the input trace. This means that the zeroeth element in the `matchTrace` result is an array of possible matches for the zeroeth coordinate, and so on.

---
_Source: https://npm.io/package/probematch · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._