v0.1.0 // TECHNICAL ARCHITECTURE

1. Core Invariants & Architecture

TransitFlow operates under a strict principle of city-agnostic modularity. Every metropolitan transit authority is modeled exclusively through external configuration (configs/<city>.yml) and standard transit data formats (General Transit Feed Specification and OpenStreetMap vector extracts).

Non-Negotiable Invariant: The core simulation engine (src/transitflow/) contains zero city-specific conditionals. Adding a new transit network requires only specifying spatial bounds, local CRS projections, and GTFS schedules.

The pipeline executes linearly across isolated functional modules: 

TransitFlow  ──►  Select City  ──►  Ingest OSM/GTFS  ──►  Clean Network  ──►  Interpolate  ──►  Render & Export

2. Spline Kinematics & Dwell Physics

Standard transit maps render vehicles by snapping discretely between station nodes or linearly interpolating at constant speeds. TransitFlow models physical train dynamics along track polylines using arc-length parameterization and smoothstep acceleration profiles.

Continuous Arc-Length Parameterization

Given a polyline track segment with vertices $P_0, P_1, \dots, P_n$, cumulative arc length $s(t)$ parameterizes exact normalized travel progress $\tau \in [0, 1]$ between scheduled departure and arrival times.

Smoothstep Acceleration Easing

To prevent abrupt velocity discontinuities when departing or braking at platforms, TransitFlow applies a smoothstep hermite polynomial:

\tilde{\tau} = 3\tau^2 - 2\tau^3 \quad \text{where} \quad \frac{d\tilde{\tau}}{d\tau}\Big|_{\tau=0} = \frac{d\tilde{\tau}}{d\tau}\Big|_{\tau=1} = 0

This guarantees zero velocity at platform arrival and departure, simulating realistic inertia and braking curves.

Station Dwell Profiles

During the scheduled station dwell window ($T_{\text{dwell}} = 25.0\,\text{s}$), the vehicle position remains clamped to the platform node while passenger boarding state transitions occur.

3. Cartographic Precision & Metric Projections

Raw geospatial data is collected in WGS84 geographic coordinates (EPSG:4326, degrees latitude and longitude). Because lines of longitude converge toward the poles ($\Delta x \propto \cos(\phi)$), distance and velocity calculations in unprojected angular space suffer from severe non-linear spatial distortion.

Reprojection Strategy: Raw WGS84 data is ingested and immediately transformed into local Universal Transverse Mercator (UTM) metric projections (e.g. EPSG:32650 for Beijing, EPSG:32630 for London) using pyproj.

In metric UTM space, vehicle speeds are measured in true physical meters per second ($m/s$), ensuring that simulation time steps correspond to uniform Euclidean distance increments across all axes.

4. Headless FFmpeg Video Pipeline

To render ultra-high-resolution 60 FPS animations without intermediate disk I/O bottlenecks, TransitFlow utilizes a streaming headless pipeline:

  • Matplotlib Agg headless backend renders uncompressed 32-bit RGBA frame buffers in memory.
  • Raw byte buffers are piped directly into an active ffmpeg subprocess via stdin:
ffmpeg -y -f rawvideo -vcodec rawvideo -s 1920x1080 -pix_fmt rgba \
       -r 30 -i - -c:v libx264 -preset medium -crf 18 -pix_fmt yuv420p output.mp4

This bypasses saving intermediate PNG sequences to disk, eliminating gigabytes of temporary storage and achieving rendering throughput limited solely by CPU rasterization and H.264 encoding speed.

5. Unified CLI Reference

TransitFlow exposes all platform capabilities via a unified Click CLI interface:

# Ingest raw OpenStreetMap geometries and GTFS feeds
transitflow download <city>

# Build topological NetworkX graph and validate node connectivity
transitflow build <city>

# Render cinematic H.264 MP4 video
transitflow animate <city> --duration 15 --fps 30 --output video.mp4

# Export optimized animated GIF
transitflow export <city> --format gif --duration 5 --output preview.gif

# Inspect network centrality metrics and transfer hubs
transitflow analytics <city>

# Launch interactive web visualizer and studio
transitflow web --port 8080