The Problem
Visualizing global flight data in 3D is computationally expensive. Standard approaches struggle to render thousands of simultaneous aircraft with smooth animation, and most solutions lack the interactive controls needed for real-time exploration of flight patterns, routes, and timing.
What This Does
flight-path is a Three.js-based 3D flight visualization tool. It renders a photorealistic Earth with atmospheric scattering, day/night cycles based on sun position, and a starfield background. The core simulation lives in src/flights/Flight.ts and src/flights/FlightUtils.ts, which handle path generation and aircraft movement along parabolic trajectories. src/managers/FlightPathManager.ts orchestrates the rendering, while src/planes/Planes.ts and src/planes/PlanesShader.ts implement GPU-instanced aircraft rendering to support up to 30,000 concurrent flights.
The UI is a React wrapper (src/App.ts) around a dat.GUI-style control panel managed by src/managers/UIManager.ts. Controls cover flight count, speed, altitude, plane style (SVG or geometric), path dash styling, and Earth lighting parameters. Custom shaders in src/shaders/ handle atmosphere, plane, and star rendering for GPU-accelerated performance.
How To Use It
Setup: Install dependencies with npm install (requires Node.js 16+). The project uses Vite (vite.config.js) as the build tool.
Running: Start the dev server with npm run dev, then open http://localhost:5173. Build for production with npm run build and preview with npm run preview. Deploy to GitHub Pages via npm run deploy.
Configuration: No environment variables or external API keys are required. All parameters are adjusted at runtime through the GUI controls. Flight data can be procedurally generated or replaced by modifying the data structures in src/common/Data.ts.
npm install npm run dev
Real-World Use
This fits well in an aviation analytics dashboard or a public-facing flight tracking display. A typical integration would embed the visualization in a React application, pass real flight data (lat/lng coordinates, timestamps) into the Flight class, and expose the GUI controls to end users for filtering by region, time, or airline. The coordinate display in the UI makes it straightforward to wire up click-to-inspect behavior for individual flights.
Code Health & Issues
Med - No test files: The repo has zero test coverage. Flight path math and rendering logic are untested, which is risky given the complexity of the simulation code. Med - No CI/CD pipeline: No .github/ directory or CI configuration exists. There is no automated build or test gate, so regressions can ship silently. Low - Single-file managers: src/managers/ classes are large and tightly coupled to Three.js internals. The separation between simulation logic, rendering, and UI is thin, which will complicate maintenance as features are added. Low - Documentation gap: The README covers features well but lacks API documentation for the core classes (Flight, FlightPathManager, PlaneControlsManager). Customizing flight data requires reading the source.
The codebase is otherwise clean: TypeScript is used consistently (19 of 27 source files), shader files are organized, and the project has a license and .gitignore.
The Bottom Line
This is a solid, visually impressive Three.js application with good GPU optimization and a well-designed control interface. The lack of tests and CI is a real concern for production use, but for visualization demos, internal analytics tools, or educational projects, it works well out of the box. Teams needing to extend it with real flight data should budget time for refactoring the manager classes and adding test coverage around the flight path math.