3D annotations API

[Carifio24]

Recently I was helping someone make a WWT interactive, and something that we wanted was an annotation in 3D mode (in particular, drawing something in the plane of the Milky Way). This led me to realize that there's no API for specifying 3D coordinates for an annotation; it seems that everything is assumed to be in 2D.

I was able to get around this by doing the following, where ra, dec, and dAu are the coordinates of point to add (distance in AU since that's the conversion that exists):

const ecliptic = Coordinates.meanObliquityOfEcliptic(SpaceTimeController.get_jNow() / 180 * Math.PI);
const pos = Coordinates.geoTo3dRad(ra, dec, dAu);
pos.rotateX(ecliptic);
annotation._points$1.push(pos);

which worked, but is obviously pretty hacky and not at all accessible to the average user. (I needed the ecliptic rotation to make things line up right in that case - not sure how universal this would be). This got me thinking that it might be nice to have some sort of API for making it easier/possible to specify annotation points in 3D.

[pkgw]

Ah, I forgot to bring this up during our call today.

In terms of API, I think that adding 3D support would be pretty straightforward. The implementation might get a little tricky. If you have different annotations at different depths, intermixed with tabular data layers, planets, 3D models, orbit ellipses, etc., getting everything to layer correctly seems like it would get challenging — the engine isn't really set up to handle stacking 3D objects in full generality. You could make some rule like "annotations render on top of everything else, even if they should be occluded" but that really rapidly leads to counterintuitive effects that people don't like. I'm pretty sure this is why there isn't 3D annotation support already.