This project has been created as part of the 42 curriculum by lvasconc.

Fly-In

Description

Fly-In is a drone network visualization and routing simulator. It loads a text-based map that defines hubs, connections, capacities, zones, and a drone fleet size. The application computes valid flight itineraries, enforces hub capacity and per-connection link limits, and renders the resulting network and drone movement in a Pygame window.

The goal is to help users understand graph navigation, constrained pathfinding, and visualization of network routing under capacity and zone constraints.

Instructions

Requirements

• Python 3.13+
• Dependencies installed from pyproject.toml
• Pygame asset files must be available in the assets/ directory

Installation

1. Activate your virtual environment if you have one.
2. Install dependencies with:

python -m pip install -r requirements.txt

If a requirements.txt file is not available, install using the project dependencies directly from pyproject.toml:

python -m pip install flake8 mypy networkx pydantic pygame

Execution

Run the visualizer from the repository root:

python src/main.py

To choose a different map file:

python src/main.py --map maps/easy/01_linear_path.txt

Notes

• The first run may create or update movement_log.txt in the project root.
• If image assets are missing, the simulator falls back to a procedural background and drone sprite.

Algorithm Choices and Implementation Strategy

Parsing and Validation

The project uses a custom parser to read map files and build the simulation configuration. The parser handles:

• nb_drones declaration
• start_hub and end_hub
• regular hub definitions
• connection definitions with optional max_link_capacity attributes, defaulting to 1 when omitted

Validation ensures the map is well-formed and rejects mutual bidirectional connection definitions. The parser also populates hub wall configuration based on the connection graph.

Data Modeling

Data structures are defined using pydantic models for strict validation and type safety:

• Hub: represents a node with coordinates, walls, zone type, color, and capacity
• Connection: represents a link between hubs with a max_link_capacity value, defaulting to 1 if omitted
• Configs: aggregates hubs, connections, start/end definitions, and drone count

Pathfinding and Routing

The simulator computes drone itineraries using a custom min-cost route generation strategy:

• Builds an adjacency structure from the hub graph
• Applies zone-based costs for restricted and priority areas
• Generates exactly nb_drones itineraries while respecting defined capacities and link capacities
• Skips hubs with zero capacity to avoid impossible routes

This approach maintains control over path costs and avoids external dependency complexity for the pathfinder.

Simulation and Movement

Drone movement is performed with step-based interpolation:

• Drones are activated sequentially
• Each drone moves from hub to hub along its itinerary
• Straight connections use linear interpolation
• Non-adjacent portal links use curved Bézier movement
• Hub occupancy is tracked to enforce capacity constraints
• Edge occupancy is checked against connection max_link_capacity, so only the allowed number of drones can occupy a connection at once

When a drone reaches a restricted zone, the simulator logs a specific formatted movement string and applies a higher cost.

Visual Representation Features

The Pygame visualizer is designed to enhance user experience through:

• Distinct hub coloring and zone indicators
• Straight lines for adjacent connections and curved paths for longer portal links
• Animated drone movement with rotation aligned to travel direction
• A heads-up overlay showing system status and controls
• A fallback background and sprite rendering when assets are missing

These features make the simulation easier to understand and provide immediate visual feedback on path selection, restricted zones, and active drone traffic.

Resources

• Python documentation: https://docs.python.org/3/
• Pygame documentation: https://www.pygame.org/docs/
• Pydantic documentation: https://docs.pydantic.dev/
• Graph algorithms overview: https://en.wikipedia.org/wiki/Graph_(discrete_mathematics)

AI usage

AI was used to assist with:

• Code organization and package refactoring
• Writing and refining documentation and comments
• Creating clearer module names and import structure
• Improving readability while preserving functionality

No AI was used for core algorithm logic design; the routing and visualization implementation was written and verified manually.

Additional Notes

• The project is designed to be extensible: the parser, simulation, and rendering layers are separated into distinct modules.
• The pyproject.toml file includes packaging metadata for the fly_in package located under src/.