Object Data

Object data functions let add-ons read time-based values from telemetry objects.

Use this section when your add-on already has an object handle and needs to answer practical questions such as:

• When does this object exist?

• Where is this object at a given time?

• How fast is this object moving?

• What air data is available for this aircraft?

These functions are commonly used by analysis tools, charts, trails, labels, exports, and custom visualizations.

For finding objects, filtering objects by type, or reading object names and display information, see Telemetry Objects.

Object active time

Use object active time when you need to know when an object logically exists in the telemetry.

• GetObjectActiveTime()

• GetObjectActiveTimeStart()

• GetObjectActiveTimeEnd()

This is useful for analysis tools, charts, trails, and exports which need to clamp work to the meaningful lifetime of an object.

Object active time is not the same thing as the global transform time range. For telemetry-wide availability and time range helpers, see the Telemetry section.

Object transforms

Use object transforms when you need position or orientation.

• GetObjectTransform()

A transform tells you where an object is at a given time. It can include latitude, longitude, altitude, Tacview global coordinates, roll, pitch, yaw, and other coordinate data when available.

Transforms are commonly used to compute distances, angles, trails, labels, geometry, and exported analysis data.

When possible, use the geometry helpers for common spatial calculations instead of reimplementing coordinate math in your add-on.

Speed and air data

Use speed and air data helpers when you need values that are commonly used in flight analysis.

• GetObjectSpeed()

• GetObjectIndicatedAirspeed()

• GetObjectIndicatedAirspeedBestEstimate()

• GetObjectTrueAirspeed()

• GetObjectTrueAirspeedBestEstimate()

• GetObjectPressureAltitude()

• GetObjectPressureAltitudeBestEstimate()

• GetObjectMachNumber()

• GetObjectMachNumberBestEstimate()

The strict functions return a value only when the corresponding telemetry data is available.

The BestEstimate helpers are more convenient for analysis and visualization tools that need a practical value even when the exact telemetry property was not recorded.

For calculations, keep speeds in meters per second and altitudes in meters. Convert or format values only when displaying them to the user or exporting text.

Typical workflow

A common add-on pattern is:

local currentTime = GetTelemetryPlaybackTime()
local activeTimeStart, activeTimeEnd = GetObjectActiveTime(objectHandle)

if activeTimeStart ~= nil and currentTime >= activeTimeStart and currentTime <= activeTimeEnd then
	local transform = GetObjectTransform(objectHandle, currentTime)
	local trueAirspeed = GetObjectTrueAirspeedBestEstimate(objectHandle, currentTime)

	-- Analyze or display this object's state at the current time.
end

This workflow checks that the object exists at the current time, then reads only the time-based values needed by the add-on.