diff --git a/Configuration-%7C-config.toml.md b/Configuration-%7C-config.toml.md new file mode 100644 index 0000000..9b90a36 --- /dev/null +++ b/Configuration-%7C-config.toml.md @@ -0,0 +1,67 @@ +# Configuration File Overview | `config.toml` + +This configuration controls a **trajectory processing pipeline** that combines GPS clustering, path simplification, and map-matched routing. The three sections run sequentially: raw GPS points are first clustered into stops/movement segments, simplified geometrically, then aligned to the actual road network. + +--- + +## `[T-DBSCAN]` — Stay-Point Detection + +T-DBSCAN (Time-based Density-Based Spatial Clustering) identifies **stay points** (locations where the user paused for a significant time) versus **movement segments** in a raw GPS trajectory. + +| Parameter | Value | Description | +|-----------|-------|-------------| +| `eps_time` | `60` | **Temporal threshold** in seconds. GPS points are considered part of the same cluster if they are within this time window of each other. | +| `k` | `3` | **Spatial epsilon multiplier** or spatial threshold scaling factor. Defines how close points must be spatially to belong to the same cluster. | +| `min_pts` | `5` | **Minimum points** required to form a valid cluster. Fewer than 5 points within the `eps_time` window are treated as noise/transit rather than a stay point. | + +**How it works:** The algorithm scans the trajectory and groups consecutive GPS readings that are close together both in space (scaled by `k`) and time (within `60` seconds). Clusters with at least `5` points are labeled as **stay points** (e.g., a coffee break or delivery stop). Everything else is labeled as **movement**. + +--- + +## `[Douglas]` — Trajectory Simplification + +This section configures the **Douglas-Peucker** polyline simplification algorithm, which reduces the number of GPS points in movement segments while preserving the overall shape. + +| Parameter | Value | Description | +|-----------|-------|-------------| +| `eps` | `-1` | **Simplification tolerance**. A value of `-1` enables **adaptive/auto mode**, meaning the tolerance is calculated dynamically rather than using a fixed distance. | +| `base` | `3` | **Base value** for the adaptive tolerance formula. Serves as the starting reference distance (often in meters or a unit relative to the coordinate system). | +| `k` | `1.5` | **Adaptive multiplier**. The final tolerance is derived as something like `base × k` (or a similar function), producing an adaptive threshold of roughly `4.5` units in this case. | + +**How it works:** After T-DBSCAN extracts movement segments, Douglas-Peucker removes redundant GPS points from those segments. Because `eps = -1`, the simplification strength automatically scales based on the `base` and `k` values rather than requiring a hard-coded meter value. + +--- + +## `[OSRM]` — Map Matching & Routing + +This section points to the pre-processed road network data used to snap the simplified GPS trajectory onto actual drivable roads. + +| Parameter | Value | Description | +|-----------|-------|-------------| +| `path` | `C:\Users\TRIZ\clones\TrackEngine\data\algeria-260108.osrm` | Absolute path to the **OSRM dataset file**. | + +**About the file:** +- `algeria-260108.osrm` is a pre-processed OpenStreetMap extract for **Algeria**, built using OSRM's toolchain (`osrm-extract` + `osrm-contract` or `osrm-customize`). +- The filename likely encodes the region and extract date/version (e.g., Algeria from 26/01/2008 or a similar versioning scheme). +- This `.osrm` file is not the raw OSM XML; it is a binary, memory-mapped routing graph optimized for fast queries. + +**How it fits in the pipeline:** +1. **T-DBSCAN** finds stops and movement phases. +2. **Douglas-Peucker** cleans up the movement phases by dropping unnecessary points. +3. **OSRM** takes the cleaned polyline and performs **map matching**, snapping the GPS trace to the most likely road path in Algeria's road network. + +--- + +## Pipeline Summary + +``` +Raw GPS Trace + ↓ +[T-DBSCAN] → Stay Points + Movement Segments + ↓ +[Douglas] → Simplified Movement Segments + ↓ +[OSRM] → Map-Matched Road Paths +``` + +This three-stage design is common in **trajectory mining** and **vehicle telematics**: it separates meaningful stops from travel, compresses the data for efficiency, and finally grounds the geometry to real-world roads.