Interpose: Dynamic Pursuit-Evasion & Coordination Framework

Interpose is a real-time pursuit-evasion framework designed to evaluate and demonstrate coordinated multi-agent intercept strategies on procedural road networks.

By modeling containment tactics, predicting evader trajectories, and distributing tactical roles, the framework simulates how coordinated vehicle squads can contain a high-speed evader using physical roadblocks and spike strips.

Core Features

• Procedural Road Networks: Generates complex city layouts combining spanning trees (highways) and cyclical meshes (residential streets) to ensure realistic routing alternatives.
• Dynamic Role Allocation: Distributes roles across the pursuing squad on the fly:
  • Pursuer: Direct pressure-chase on the evader's current location.
  • Interceptor: Intersects the evader at predicted ahead junctions.
  • Flanker: Moves ahead to set up physical road containments.
• Influence-Map Prediction: Combines spatial reachability and squad threat diffusion equations to predict evader trajectories based on environmental safety rather than naive straight lines.
• Physical Spike Strips: Flankers deploy barricades dynamically. Crossing a spike strip does not block movement but pops tires, permanently reducing evader speed.
• Autonomous Autopilot: Includes an automated evader bot that uses live threat heatmaps to run escape routes, serving as a baseline for pursuit testing.
• Headless Benchmarking: Includes a command-line testing suite to run hundreds of iterations headlessly, collecting metrics on capture rates and time-to-capture.

Architecture

src/
├── agents/        # Vehicle movement, Player controls, and Cop pursuit logic
├── ai/            # Pathfinding caches, role allocation, and trajectory predictors
├── render/        # Camera viewports and Cyberpunk-themed Pygame rendering
└── world/         # Road network generators and influence map computations

Getting Started

Prerequisites

• Python 3.10+
• Pygame
• NetworkX
• NumPy

Installation

Clone the repository and install dependencies:

pip install -r requirements.txt

Running the Simulator

Launch the interactive visual environment:

python main.py

• Drive: WASD / Arrow Keys
• Toggle Autopilot (AI Evader): Press [B]
• Switch Cop Strategy: [1] Greedy Chase, [2] Predictive Intercept, [3] Coordinated Squad
• Toggle Escalation Mode: Press [M] (Spawns cops progressively: 1 initially, escalating to 4)
• Toggle Debug Heatmaps: Press [H]
• Regenerate Seed: Press [R]

Running Headless Benchmarks

Evaluate the pursuit algorithms across multiple seeds without rendering graphics:

python scripts/benchmark.py 30

Performance Benchmarks (30 Seeds)

The table below summarizes performance metrics gathered headlessly against the autonomous threat-avoiding evader bot:

Strategy Configuration	Capture Rate	Avg Capture Time	Spike Strips Triggered
Greedy Pursuit (Individual)	93.3%	32.2s	0
Predictive Intercept (Individual)	80.0%	40.5s	0
Coordinated Squad (Standard)	96.7%	27.3s	1
Coordinated Squad (Escalation Mode)	93.3%	33.8s	0

Key finding: Coordinating the squad into Pursuer, Interceptor, and Flanker roles captures the evader 13.2 seconds faster on average than standard predictive interception.

License

This project is licensed under the MIT License - see the LICENSE file for details.