Flight Visualizer is a versatile command-line application designed to transform flight data obtained from AeroAPIinto dynamic visualizations using the Keyhole Markup Language (KML). This tool enables users to replay flights in KML client renderers such asGoogle Earth.
By providing either a unique "flight identifier" or an aircraft's "tail number" and time frame, users can visualize flights' paths and performance data. The software offers options for various visualization "layers," including camera perspective, 3D flight paths and performance vectors. The generated KML files can be easily shared and explored, offering a comprehensive and immersive way to analyze and (re-) experience flight trajectories and characteristics.
SeeInstallationbelow to get started.
$ fviz tracks --tailNumber N8050J --cutoffTime 2023-05-22T19:45:00-04:00 --launch
$ fviz tracks --tailNumber N81497 --flightCount 1 --launchArticles about "Featured Flights" can be found in thefeaturedfolder:
Virgin Galactic 02 Spaceflight
Seethis write-upabout a visualization of Galactic 02,the second commercial spaceflight of the American aerospace companyVirgin Galactic.
Follow the instructions in the sections below to install, configure and invoke the flight visualizer tool.
Flight Visualizer is packaged into a standalone CLI command namedfviz.
Installing flight visualizer is simply a matter of copying its executable binary
(e.g.,fvizorfviz.exein Windows) from the release distribution into a location
from which it can be invoked (e.g., a folder within yourPATH,etc.)
Everything needed is contained in the single binary which is pre-built for popular operating systems and included in the standardReleases.
In order to retrieve flight information usingAeroAPI,you'll need to obtain and install an API Key. See theAeroAPIdocumentation to learn more about this.
Flight Visualizer stores and accesses your AeroAPI API Key in its configuration, which is normally stored
in the file.config/fvizlocated underneath yourHOMEdirectory. You can set the environment variable
FVIZ_CONFIG_FILEto point to a different file, if needed. Also, each configuration property can be
overridden by setting it as an environment variable prior to invocation of Flight Visualizer.
You can use your own editor or theconfig editsub-command to create and modify the properties in Flight
Visualizer's configuration file. Here's an example file (with secrets removed:)
$ cat~/.config/fviz
AEROAPI_API_URL=https://aeroapi.flightaware.com/aeroapi
ARTIFACTS_DIR=.
VERBOSE=false
AEROAPI_API_KEY=YourAeroApiKeySecretGoesHere
$ █The console log below illustrates how usingfviz config editsteps through each configuration item,
showing its current value, and giving an opportunity to change it:
$ fviz config edit
2023/06/02 15:54:26 editing'/Users/johnny/.config/fviz':
AEROAPI_API_URL: https://aeroapi.flightaware.com/aeroapi
ARTIFACTS_DIR:.
VERBOSE: (Use the arrow keys to navigate: ↓↑)
▸ False
True
AEROAPI_API_KEY:*******************************
Done?[y/N] y
$ █The typical example invocation scenarios provides below and in the linked documentation should provide
a generally good idea of how to invoke thefviz(Flight Visualizer) command. When in doubt, use the
--helpoption to retrieve a syntax digram, e.g.:
$ fviz --help
Generates visualizations of flight data
Usage:
fviz [flags]
fviz [command]
Available Commands:
config Shows current configuration
helpHelp about anycommand
tracks Visualizes flight tracks
Flags:
-d, --debug Enables'debug'operation
-h, --helphelpfordist/macos/fviz
-v, --verbose Enables'verbose'operation
--version versionfordist/macos/fviz
Use"dist/macos/fviz [command] --help"formore information about a command.Or, to get the options available for thetracks(main) subcommand (for example)...
$ fviz tracks --help
Generates KML visualizations of flight track logs retrieved from FlightAware's AeroAPI
Usage:
fviz tracks [flags]
Flags:
-a, --artifactsDir string Directory to save or load artifacts
-t, --cutoffTime string Cut off time for flight(s) to consider
-c, --flightCount int Count of (most recent) flights to consider (0=unlimited)
-i, --flightNumber string Flight number identifier
-f, --fromArtifacts string Use saved responses instead of querying AeroAPI
-h, --help help for tracks
-o, --launch Open the KML visualization of the most recent flight retrieved
-l, --layers string Layer(s) of the KML depiction to create (default "camera,path,vector" )
-b, --noBanking Disable banking heuristic calculations
-s, --saveArtifacts Save responses from AeroAPI requests
-n, --tailNumber string Tail number identifier
--version version for tracks
Global Flags:
-d, --debug Enables'debug'operation
-v, --verbose Enables'verbose'operationBy default,fvizassumes the artifacts it reads & writes should be located in the directory specified in
itsARTIFACTS_DIRconfiguration property. You can override this per-invocation using the--artifactsDir
option to specify the location for artifacts each time you invokefviz.
Examples of typical invocations offvizare presented below to help jumpstart the uninitiated user.
Additional use cases can be revealed through exploration of the complete set of options available.
Running the command with the--helpoption will reveal the complete set of available options.
In this simple case, defaultKMLvisualizations are created for the (at the time) most recent flights available
viaAeroAPIfor tail numberN335SP,and the most recent one is launched right away intoGoogle Earth Pro,
which was registered to open.kmzfiles in the operating system.
- If you'd like to take a virtual tour around the perimeter of Maui, consider visualizing this flight yourself by loadingthe output fileinto a KML client such asGoogle Earth(Google Mapsisn't recommended since most of this flight is over water 😉).
- BTW,N335SPis operated byMaui Aviators which I've found to be an ultra-cool FBO for flight instruction, or to get checked out, for some aerial adventures when visiting Maui 🤙👍
$ fviz tracks --tailNumber N335SP --launch
$ fviz tracks --verbose --tailNumber N335SP --launch
2023/05/23 17:33:48 INFO: requesting from endpoint(/flights/N335SP)
2023/05/23 17:33:49 INFO: requesting from endpoint(/flights/N335SP-1684874159-adhoc-1864p/track)
2023/05/23 17:33:49 INFO: requesting from endpoint(/flights/N335SP-1684868329-adhoc-760p/track)
2023/05/23 17:33:49 INFO: requesting from endpoint(/flights/N335SP-1684796443-adhoc-635p/track)
2023/05/23 17:33:50 INFO: requesting from endpoint(/flights/N335SP-1684787435-adhoc-1467p/track)
2023/05/23 17:33:50 INFO: writing 4 camera,path,vector KML document(s)Another example leverages more of the available options, including:
--cutoffTime- target a particular flight within the history (e.g., not just the latest available)--flightCount- limit the number of most recent flight(s) for which to produce visualizations--saveArtifacts- save responses obtained fromAeroAPIin order to re-use them later (e.g., with different KML generation options, etc.)--artifactsDir- specify where "artifacts" are read/written (i.e., instead of configuredARTIFACTS_DIR)--layers- specify the visualization "layer(s)" to include in theKMLdocument(s) (e.g.,camera,path,vector)--verbose- generate more detailed runtime logging to help understand what's happening
$ fviz tracks --tailNumber N6189Q --cutoffTime 2023-05-18T20:40:00-04:00 --flightCount 3 --saveArtifacts --artifactsDir /tmp/myflight --layers camera,path,vector --verbose
$ fviz tracks --tailNumber N6189Q --cutoffTime 2023-05-18T20:40:00-04:00 --flightCount 3 --saveArtifacts --artifactsDir /tmp/myflight --layers camera,path,vector --verbose
2023/05/23 19:04:35 INFO: requesting from endpoint(/flights/N6189Q?&end=2023-05-18T20:40:00-04:00)
2023/05/23 19:04:35 INFO: saving to file(/tmp/myflight/fvf_N6189Q_cutoff_20230518T204000-0400.json)
2023/05/23 19:04:35 INFO: requesting from endpoint(/flights/N6189Q-1684452005-adhoc-1107p/track)
2023/05/23 19:04:36 INFO: saving to file(/tmp/myflight/fvt_N6189Q-1684452005-adhoc-1107p.json)
2023/05/23 19:04:36 INFO: requesting from endpoint(/flights/N6189Q-1684113448-adhoc-1454p/track)
2023/05/23 19:04:36 INFO: saving to file(/tmp/myflight/fvt_N6189Q-1684113448-adhoc-1454p.json)
2023/05/23 19:04:36 INFO: requesting from endpoint(/flights/N6189Q-1684108895-adhoc-1665p/track)
2023/05/23 19:04:36 INFO: saving to file(/tmp/myflight/fvt_N6189Q-1684108895-adhoc-1665p.json)
2023/05/23 19:04:36 INFO: writing 3 camera,path,vector KML document(s)
2023/05/23 19:04:36 INFO: saving(/tmp/myflight/fvk_N6189Q-230518233039Z-9003450Z-camera,path,vector.kmz)
2023/05/23 19:04:36 INFO: saving to file(/tmp/myflight/fvk_N6189Q-230518233039Z-9003450Z-camera,path,vector.kmz)
2023/05/23 19:04:36 INFO: saving(/tmp/myflight/fvk_N6189Q-230515011723Z-2559Z-camera,path,vector.kmz)
2023/05/23 19:04:36 INFO: saving to file(/tmp/myflight/fvk_N6189Q-230515011723Z-2559Z-camera,path,vector.kmz)
2023/05/23 19:04:36 INFO: saving(/tmp/myflight/fvk_N6189Q-230515001513Z-11208Z-camera,path,vector.kmz)
2023/05/23 19:04:36 INFO: saving to file(/tmp/myflight/fvk_N6189Q-230515001513Z-11208Z-camera,path,vector.kmz)In the example above, Google EarthKMLvisualizations of the three flights prior to the given "cutoff date" for the given aircraft (identified by its "tail number" ), with three "visualization layers" that can be toggled on/off from within Google Earth:
- Camera (first-person perspective)
- Path (3D flight path appears)
- Vector (A "vector" visualization of performance data)
An important use case for development or support of Flight Visualizer application is to (re-) convert already retrieved responses fromAeroAPIintoKML(e.g., to avoid making unnecessary calls to the API).
This can be accomplished by using the--fromArtifactsoption, pointing it to a file previously created
(i.e., by the--saveArtifactsoption) in which AeroAPI's response from the/flights/{tailNumber}REST
API call is recorded. For example:
$ fviz tracks --fromArtifacts artifacts/fvf_N8731J_cutoff-20230531T083000-0700.json --flightCount 1
2023/06/05 12:13:35 INFO: reading from file(artifacts/fvf_N8731J_cutoff-20230531T083000-0700.json)
2023/06/05 12:13:35 INFO: reading from file(artifacts/fvt_SWA3774-1685372217-schedule-57p.json)
2023/06/05 12:13:35 INFO: saving to file(fvk__230531150622Z-201824Z_camera-path-vector.kmz)Theoutput file produced by the command above visualizes anactual flight from Los Angeles to Maui taken by some lucky vacationers on Southwest Airlines flight SWA3774 on May 31st.
WhileKMLis a standard "Markup Language," and is supported by many other geospatial applications (perhaps most notablyGoogle Maps,QGISandArcGIS Earth), onlyGoogle Earth(as of this writing) appears to best support "live touring" visualizations (e.g., from the "first person" perspective). Accordingly, it's been the preferred target client for rendering the visualizations generated by Flight Visualizer.
By default, Flight Visualizer creates a.kmzfile (compressedKMLfile), that can be rendered successfully byGoogle Earth Web,Google Earth ProandGoogle "My Maps".
Be sure to see how enabling and disabling visualization of each of the "layers" independently can be used to produce different and interesting perspectives.
Queries toAeroAPIcan cost money.This pageis one to keep an eye on while making active use of it.
Have ideas? Try 'em out!
- Use of this source code is governed by an Apache-2.0 license that can be found in theLICENSEfile
- Contributions to this project are encouraged, and guidelines are established in theCONTRIBUTIONSfile
Flight Visualizer is packaged into a standalone CLI command namedfviz.
TheMakefiletargetbuild-allcreates distribution packages
for multiple versions of this executable for popular architectures,
including:MacOs,LinuxandWindows.
The "home" source control repository of Flight Visualizer is on GitHub at
noodnik2/flightvisualizer.
It was written in, and leverages some relatively recent features ofgolang.
Its initial test suite usesgo1.20.2 darwin/amd64,though it should build successfully
with any version ofgoversion1.18or greater.
On a fresh clone / fork of the repository, you should be able to...
$ make clean update build test
$ make clean update buildtest
rm -rf vendor dist tmp
go mod tidy
go mod download
go mod vendor
go build -o dist/fviz.
gotest./...
ok github.com/noodnik2/flightvisualizer/internal/aeroapi 0.211s
ok github.com/noodnik2/flightvisualizer/internal/kml 0.320s
ok github.com/noodnik2/flightvisualizer/pkg/aeroapi 0.372sBe sure also to check out otherREADMEand.md(markdown) files located in sub-folders of this repository,
as they contain additional relevant context. One such file of note is thewishlist.
Please don't hesitate to volunteer your thoughts or ideas regarding enhancements to or collaborations on Flight Visualizer!
fsr- Predecessor to Flight Visualizer
Before the ubiquitous availability of flight track data through online sources such asAeroAPI (e.g., with the advent and requirement forADS-Btransmission), it was necessary to collect flight logs using more primitive, on-board device technology.
A predecessor to Flight Visualizer, thefsrapplication enabled similar "flight replay" visualizations withinMicrosoft Flight Simulatorusing data collected in several older track log file formats, from real-world flights.
If you're a user ofMicrosoft Flight Simulator,be sure to check out a related project that usesKMLto produce visualizations(including in real-time!)of simulated flights inGoogle Earth:
- MSFS2020 Pilot Path Recorderand related pages:
In addition to the online services needed, Flight Visualizer builds atop many other open-source libraries, perhaps most notably:
- Cobra-"A Framework for Modern CLI Apps in Go"
- go-kml-"convenience methods for creating and writing KML documents"
The complete set of libraries used can be seen of course in thego.modfile.
I'd like to express my heartfelt appreciation to the creators and supporters of the high quality services and open-source building blocks which enable projects like Flight Visualizer to quickly get started focusing on their mission and value-add: in this case,vicarious aviation!