Command Line Interface

Overview

The CLI brings the Wheels4Wheels workflow together in one end-to-end pipeline. Rather than supporting isolated processing steps, it takes ride telemetry through classification, map-matching, aggregation, confidence evaluation, and export into OSM-ready proposals. This makes the full method reproducible in a single workflow and shows how the project can move from individual test rides towards scalable implementation.

Installation Requirements

The pipeline runs on any machine with a recent Python installation and needs no special hardware. Besides a handful of standard scientific libraries, the only external dependency is a Mapbox API token for map matching, plus a little disk space for cached intermediate results.

Prerequisites

Requirement	Details
Python Version	3.8 or higher
Dependencies	pandas, numpy, requests, shapely, scipy
Map Matching	Mapbox API token required
Storage	Minimum 100 MB for processing cache

Install Commands

pip install -r requirements.txt
# or
pip install pandas numpy requests shapely scipy

Core Commands

The basic invocation turns a single ride into reviewable proposals, while the advanced form exposes the thresholds and tolerances behind the defaults.

Basic Processing

# Process single ride
python scripts/OSM/OSM_smoothness_workflow.py \
  --input telemetry_json/ride_12345.json \
  --out-csv output/proposals.csv \
  --out-map output/review_map.html

# Dry-run reviewed proposals through the current apply filters
python scripts/OSM/apply_smoothness_batch.py \
  --csv output/proposals.csv \
  --min-coverage 0.7 \
  --min-agree 0.7 \
  --dry-run

Advanced Configuration

# Custom parameters
python OSM_smoothness_workflow.py \
  --input ride_data.json \
  --buffer-m 18.0 \
  --tolerance-m 25.0 \
  --bad-run-threshold 30.0 \
  --confidence-min 75 \
  --speed-optimal 4.0 \
  --speed-range 2.0

Configuration Options

Users can customize how the CLI handles telemetry data by setting configuration options that control extraction, cleaning, and preparation for analysis. The parameters carry sensible defaults, and the same run can emit CSV, HTML, or GeoJSON output as needed.

Processing Parameters

Parameter	Default	Description
`--buffer-m`	18.0	Corridor buffer width for clipping
`--tolerance-m`	25.0	Max distance for point-to-way assignment
`--bad-run-threshold`	30.0	Minimum bad segment length for classification
`--confidence-min`	75	Minimum confidence for OSM proposals
`--speed-optimal`	4.0	Optimal speed for assessment (km/h)
`--speed-range`	2.0	Acceptable speed deviation (km/h)

Output Formats

# CSV output (OSM-ready)
--out-csv proposals.csv

# Interactive HTML map
--out-map review_map.html

# GeoJSON for GIS tools
--out-geojson proposals.geojson

# All formats
--out-all output_directory/

Batch Processing

The CLI supports processing multiple rides at once, whether working with individual files or entire directories. Directory runs can be parallelized and filtered by date or city, and the same quality filters used for single rides keep low-quality telemetry out of batch results.

Directory Processing

# Process all JSON files in directory
python apply_smoothness_batch.py \
  --input-dir /path/to/telemetry/ \
  --output-dir /path/to/results/ \
  --pattern "*.json" \
  --workers 8

# Filter by date range
python apply_smoothness_batch.py \
  --input-dir telemetry/ \
  --date-from 2024-01-01 \
  --date-to 2024-12-31 \
  --city "Tallinn"

Quality Filtering

# Current single-ride apply workflow
python scripts/OSM/apply_smoothness_batch.py \
  --csv output/proposals.csv \
  --min-coverage 0.7 \
  --min-agree 0.7 \
  --dry-run

Automatic multi-ride consensus is future work. A 75% consensus threshold remains a proposed target rather than an implemented CLI option, so multi-ride runs currently produce independent per-ride proposals instead of one merged verdict.

Configuration Files

Configuration files define processing parameters in one reusable place, enabling reproducible analyses across datasets. A YAML file captures the full set of thresholds and output options, and a single flag loads it in place of individual command-line arguments.

YAML Configuration

# config.yaml
processing:
  buffer_m: 18.0
  tolerance_m: 25.0
  bad_run_threshold: 30.0

quality:
  min_confidence: 75
  min_coverage: 0.5
  max_speed: 25.0

output:
  formats: [csv, html, geojson]
  directory: "./output"
  prefix: "accessibility_"

Loading a Config

python OSM_smoothness_workflow.py \
  --config config.yaml \
  --input ride_data.json

Advanced Features

Advanced features provide additional tools to fine-tune the analysis. Calibration mode fits thresholds against existing OSM tags, while validation mode checks finished proposals against the live API before anything is uploaded.

Calibration Mode

# Calibrate thresholds against existing OSM tags
python calibration.py \
  --reference-osm existing_tags.osm \
  --training-data training_rides/ \
  --output thresholds.json

# Apply calibrated thresholds
python OSM_smoothness_workflow.py \
  --thresholds thresholds.json \
  --input new_rides.json

Validation Mode

# Validate proposals before upload
python validate_proposals.py \
  --proposals proposals.csv \
  --osm-api https://api.openstreetmap.org \
  --dry-run \
  --output validation_report.html

Performance Tuning

Performance tuning keeps large datasets manageable. Core processing spreads rides across workers within a configurable memory budget, and caching avoids repeating expensive map-matching calls when rides are reprocessed.

Parallel Processing

# Multi-core processing
python apply_smoothness_batch.py \
  --input-dir large_dataset/ \
  --workers 16 \
  --batch-size 1000

# Memory optimization
python apply_smoothness_batch.py \
  --input-dir large_dataset/ \
  --memory-limit 4GB \
  --chunk-size 500

Caching

# Cache map-matching results
python OSM_smoothness_workflow.py \
  --input ride_data.json \
  --cache-dir ./cache/ \
  --cache-ttl 86400

Error Handling

Error handling covers the failures that occur in practice: API timeouts, malformed telemetry, and missing GPS fixes. Feedback makes clear what went wrong, and a single bad ride cannot abort an entire batch.

Common Issues

# Missing API token
export MAPBOX_ACCESS_TOKEN="your_token_here"

# Rate limiting
python apply_smoothness_batch.py \
  --input-dir telemetry/ \
  --rate-limit 10 \
  --retry-delay 1.0

# Large file processing
python OSM_smoothness_workflow.py \
  --input large_ride.json \
  --memory-efficient \
  --progress-bar

Integration Examples

Several integration strategies let you automate processing and feed Wheels4Wheels data into existing workflows, from a scheduled cron job on a server to a containerized run inside a larger data pipeline.

Cron Job

# Daily processing
0 2 * * * /usr/bin/python /path/to/apply_smoothness_batch.py \
  --input-dir /data/telemetry/ \
  --output-dir /data/results/ \
  --date-yesterday \
  --email-report admin@example.com

Docker Usage

# Docker container
docker run -v $(pwd)/data:/data \
  wheels4wheels/cli \
  --input /data/telemetry/ \
  --output /data/results/

Monitoring and Logging

Long runs can be tracked in real time. Progress reporting shows how far a batch has come, and quality reports summarize what the filters kept and discarded.

Progress Tracking

# Verbose logging
python apply_smoothness_batch.py \
  --input-dir telemetry/ \
  --verbose \
  --log-file processing.log

# Progress bar
python OSM_smoothness_workflow.py \
  --input ride_data.json \
  --progress-bar \
  --eta

Quality Reports

# Generate quality report
python generate_quality_report.py \
  --input-dir processed/ \
  --output report.html \
  --include-maps \
  --statistics