Add tangram bridge: TANGRAM plugin, frontend package, and docs

[amorfinv]

Summary

• New TANGRAM example plugin (example_plugins/tangram.py) bridging the simulation to a tangram deployment over Redis: publishes SI-unit snapshots on to:<channel>:* (wall-clock rate-capped via tangram_max_hz) and listens for stack commands on from:<channel>:*
• Redis is an optional extra (uv sync --extra tangram); fakeredis added to the dev group so tests need no Redis server
• New tangram_minisky frontend plugin package (Vue/TS): aircraft map layer, trail layer, aircraft-count and sim-control widgets
• New guide docs/guides/tangram.md wired into the mkdocs nav

Test plan

• uv run pytest tests/unit/test_tangram_plugin.py tests/integration/test_tangram_bridge.py — 19 passed
• End-to-end against a live tangram deployment

🤖 Generated with Claude Code

[amorfinv]

Hi @abc8747, I have moved the plugin here. Ill work on getting it to match xoolive/traffic#531

Regarding the simulation time controls. Currently minisky can stream a simulation and exposes controls such as play, stop, reset, and changing speed. I suspect these could get out of sync with other tangram plugins since minisky takes care of its own clock.

It is possible to control the simulation without using the stream server. see here. In this way the minisky tangram plugin can effectively control the speed of the simulation and stay in sync with other data.

Note that minisky does not yet support rewinding. Not sure if this is something that will be necessary.

[abc8747]

I'm not too familiar with minisky, but is there a TypedDict or dataclass defined somewhere which we can use as annotations instead of bare dicts? Since pyright is already setup I prefer removing these untyped .get() calls (ideally strict mode too)

[abc8747]

I think this applies to the entire file too, there are lots of bare dict[str, Any] manipulations that are difficult to keep track of

[amorfinv]

I currently get a bunch of failures when we do strict mode. so for now, I will just enforce on plugins and then in future can update core

[abc8747]

@amorfinv Thanks! I'll work on improving/exposing the clock API in the tangram core (play, pause, playback speed) and hope to get it done by Thursday. It will very much look like this in the video (let me know if you would like anything!).

Fyi, I haven't used bluesky (or any air traffic simulator) at all so I don't know too much about its internals/typical painpoints. I assume when you say "lack of rewinding" it's because it's not always possible to step physics or controller actions backward. But let's say I need to seek backward from t = 900s to t = 899s, I guess there is no way to do so other than replaying the entire t = 0..=899s segment? I'm wondering if internally it is able to serialise the history to say, a jsonl or parquet file and just reload it at the requested time.

Before I start designing the historical playback side of tangram, can you tell me what are some long-standing missing functionality you'd like to see in minisky? I'm happy to start contributing to minisky but I might only be free starting mid-Aug

[amorfinv]

Hi @abc8747 thanks for all the comments. I should have some time to go over them later this week/weekend.

You are assumption about rewind is correct. currently, the only way to go from t = 900s to t = 899s is to replay the entire t = 0..=899s. I am not entirely sure how to handle it but serialising the history into a temporary file could be a nice idea.

Regarding, the clock api, I think an important part would probably be to enforce that the slowest component dictates the speed. For example, let's say we have quite a large minisky simulation. If we request a playback speed of 10x it could happen that we can only reach 5x in minisky because conflict detection is quite slow.

I will try to put this into a list somewhere else but there are a couple of parts of minisky that could use some work. These are in no particular order and vary in difficulty.

• rewind capabilities
• modernise performance model. One issue out of many is that it calculates limits during ascent and descent incorrectly.

  minisky/minisky/traffic/performance/perfoap.py

  Line 337 in 9659664

  def limits(

• Support multicopters. This basically requires a new performance model, autopilot model, kinematics model, and some better performance data. See feat: preliminary multicopter plugin #17.
• Plugin to calculate emissions with openap
• Issues near boundaries of lat/lon. see Aircraft positions are not handled at the antimeridian or the poles #14
• ADSB-data (opensky) to minisky simulation. Create a minisky plugin that loads an adsb flight and transform it into a simulation scenario.
• Create a couple of example scenarios/plugins to showcase minisky capabilities.

If you want to play a bit with air traffic simulator you can check my website. I currently only support bluesky simulations but also hoping to add minisky soon

[xoolive]

Create a minisky plugin that loads an adsb flight and transform it into a simulation scenario

This is not an easy problem actually, and maybe it shouldn't be solved with a quick generic patch making it look easy. Still, it is a nice use case to be able to replay history (tangram_history) and compare with the result of a simulation, provided a scenario reconstruction strategy. I will be your first client 👍

[amorfinv]

Hi @xoolive. Yeah this will likely be quite challenging. Also perhaps it does not actually belong in the core code since it is mostly scenario generation.

[amorfinv]

Hi @abc8747, I think i have answered most things. Also made a couple of new issues to address some of your comments.

Main thing was the #24. Also the clock still needs to be synced to tangram once that is ready. However, for now perhaps its ready?

[abc8747]

@amorfinv Thanks! I will take a closer look at it later tonight.

The clock API is not ready yet because I was busy working on integrating navaids/fixes/field 15 to tangram over at open-aviation/tangram#313, but once it is merged, we will release v0.6 then I think we can start working on it in tangram v0.7

[amorfinv]

@abc8747 Ok awesome! Which x-plane data version are you using? i could not find license info about x-plane 11

[abc8747]

I'm not too sure about the xplane data version because the tangram_navaid plugin was written by @xoolive. tangram_navaid currently downloads the data from xoolive/traffic/data/navdata and parses it on the frontend using the traffic.js library. So tracing back the history:

• earth_fix.dat and earth_nav.dat was added in traffic 7cdaf04 (2019-05-19) and earth_awy.dat in traffic 3e33d23 (2019-05-20)
• traffic f29beb4 (2018-03-18) used to download data from ProfHoekstra/bluesky
• bluesky first added the data in 996de35 (2016-12-11) and its file header mentions that it is licensed under GPL-2.0-or-later:

  640 Version - data cycle 2013.10, build 20131334, metadata AwyXP700. Copyright © 2013, Robin A. Peel (robin@x-plane.com). This data is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

• however all three DATs in traffic are missing the header so I am not able to confirm the exact data cycle/licence. I would guess the file format for earth_nav.dat is the legacy XP NAV810 (xplane 8.10-10.52) with an AIRAC dated sometime in 2016-17, but I'm not sure for earth_fix and earth_awy.

Btw, I remember the xplane site used to say data is licensed under GPL, but after some digging it seems like the GPL clause was removed from the website somewhere between 2026-01-21 and 2026-02-07 🤔

Edit: 1901 is the likely AIRAC version

[abc8747]

@amorfinv While prototyping the tangram clock API, I keep running into issues caused by the current minisky plugin system. I will merge this first to focus on #24. After that, I think we can circle back and finish the tangram_minisky plugin improvements in a separate PR