API Request: query the history

[SirMortimer]

Kerbalism Contracts implements a couple of new contract parameters that operate mostly on vessel positions in relation to other vessels and/or celestial bodies. The nature of some of those contracts makes it necessary to validate said parameters based on past information, this happens when the user is time warping at very high speeds, causing KSP to update at time intervals that exceed a sane maximum.

To do that, KerCon uses sub-sampling to recalculates past positions of vessels, celestial bodies and waypoints on those bodies based on the KSP orbits. In the presence of Principia, this will clearly provide wrong results, possibly wrong enough to matter.

Since Principia already has a history for vessels (and, I presume, celestial bodies) I'd like to have a way to query the following information from principia:

• The true position of a vessel at time T
• The true position of a celestial body at time T
• The true position of a waypoint (lat, lon) on the surface of a celestial body, at time T

Where T will always be Math.Floor(Planetarium.GetUniversalTime() - d), and d will always be anywehere in the range 10 .. timestep where timestep depends on the current warp speed.

The KSP equivalent using the stock orbit class is implemented in https://github.com/Kerbalism/KerbalismContracts/blob/master/src/KerbalismContracts/SubRequirements/Evaluation/EvaluationContext.cs

If principias history does not internally use a resolution high enough for one value for every second, I'd like to also have a way to query the available resolution so that I can choose my Ts accordingly.

[eggrobin]

This seems sensible, and it will remain well-defined and useful even as our internals change.
Note that these functions will raise an error if you try to evaluate them earlier than the oldest history we know of, or if you ask for vessels that are not tracked by Principia.

There is however one question, namely, what reference frame you want .
I guess the axes should be those of KSP’s world coordinates?
What should the origin be?

As for

If principias history does not internally use a resolution high enough for one value for every second, I'd like to also have a way to query the available resolution so that I can choose my Ts accordingly.

We should definitely not expose the internal representations of our trajectories (which differ between celestials and vessels, for what it’s worth) via APIs (they have changed from time to time, and are likely to drastically change in order to solve #2400).
Note that a lot of representations are not as a sequence of points. Right now the vessels happen to be a sequence of points, although the points are not equally spaced; this is likely to change to fancier representations based on frequency analysis. The trajectories of the celestials already have a more abstract representation, being sequences of polynomials of varying order), so that the concept of resolution is not very meaningful anyway.

However, regardless of implementation details, our trajectories ultimately represent continuous functions of time, and we have internal APIs that treat them as such, so that an API of the form position(T) should not be a problem.

[SirMortimer]

If position(T) will work for all (sane) values of T that would be ideal.

As for the reference frame, I think it does not actually matter for my use case, as long as the reference frame remains the same for all values of T. I use the positions to calculate a couple of angles and distances, and I don't see how different reference frames could result in different results (barring any hypothetical relativistic effects).

Note that these functions will raise an error if you try to evaluate them earlier than the oldest history we know of, or if you ask for vessels that are not tracked by Principia.

That is fine, as long as "raise an error" doesn't involve an exception (which - from what I recall from a measurement I did eons ago - would be not adviseable regarding execution performance).

[eggrobin]

That is fine, as long as "raise an error" doesn't involve an exception (which - from what I recall from a measurement I did eons ago - would be not adviseable regarding execution performance).

As discussed on Discord, let’s not invent error-handling mechanisms based on ancient benchmarks in other languages.

As a design principle however, exceptions should be exceptional, so you should definitely not use an exception handler if you are trying to figure out when the history starts. If that were needed, we would want to provide an API that gives that time.

I think for now your usage is for times within the last frame (in time warp; the last 20 ms * whatever timewarp is). It should be fairly rare for a vessel to appear in timewarp without a last-frame history, so handling it as an exception seems sensible.