Add Configuration | config.toml

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.