TrackSource¶
class nmeasim::core::simulation::TrackSource · Library API
Follows a track leg by leg, one leg per pair of consecutive points.
#include <nmeasim/core/simulation/track_source.hpp>
Inherits nmeasim::core::simulation::Source
Declared in src/core/include/nmeasim/core/simulation/track_source.hpp (line 76)
Every leg has a duration: on a timed track the difference of its end points' timestamps, otherwise its length divided by the speed to sail it at (the start point's recorded speed, or TrackConfig::speed_kn, but at least 0.1 knots). The speed over ground shown is the speed the leg is sailed at, except on a timed track whose start point has a recorded speed, which is shown as recorded. The position is the WGS 84 geodesic point at the elapsed fraction of the current leg, so the output rate and the point density of the file are independent. Course over ground is the start point's recorded course when it has one, otherwise the leg's initial bearing; heading equals course, speed through water equals speed over ground, and the rate of turn follows from the heading change over the step. Altitude is interpolated when both ends of the leg have an elevation. The apparent wind is recomputed from the seed's true wind and the motion.
Time: the position along the track (position()) is simulated time since the first point. On a timed track the state's time_utc is the first point's timestamp plus that position, so it rewinds when the track loops and jumps when it seeks. On an untimed track it is the seed's time plus the total simulated time advanced since the start or the last reset, which keeps growing through loops and is not changed by a seek.
See also
- GeographicLib::Geodesic
Nested types¶
| Type | Description |
|---|---|
TrackSource::Leg |
One leg of the track, between two consecutive points. |
Summary¶
Public member functions
| Name | Description |
|---|---|
TrackSource() |
Builds the legs and places the vessel at the first point. |
advance() |
Moves the vessel dt further along the track. |
current() |
Returns the current state. |
reset() |
Returns to the first point with the seed state and restarts the clock. |
finished() |
Returns whether the source stopped at the end of the track. |
duration() |
Returns the time it takes to sail the whole track. |
position() |
Returns the elapsed time along the track. |
seek() |
Moves the vessel to a time along the track at once. |
jump_to_point() |
Moves the vessel to a point of the track at once, as seek to the time the vessel passes it. |
point_index() |
Returns the index of the track point most recently passed. |
timed() |
Returns whether the source follows the track's own timestamps. |
config() |
Returns the configuration. |
set_fix() |
Simulates losing or regaining the GNSS fix; the change survives advance and seek but not reset. |
set_destination() |
Sets or clears the destination; the change survives reset and seek. |
Private member functions
| Name | Description |
|---|---|
build_legs() |
Rebuilds the leg table, timed_ and total_s_ from the configuration. |
seek_seconds() |
Moves to a time along the track and recomputes the state with a zero rate of turn. |
update_state() |
Recomputes the state from the current leg and the elapsed times. |
leg_at() |
Returns the leg the vessel is on at a time along the track. |
Private data members
| Name | Description |
|---|---|
config_ |
Configuration, including the destination set since construction. |
legs_ |
One leg per pair of consecutive points, in track order; empty for fewer than two points. |
timed_ |
Whether the leg durations come from the track's timestamps. |
total_s_ |
Total duration of the track, in seconds. |
progress_s_ |
Elapsed time along the track, in seconds, in [0, total_s_]. |
elapsed_s_ |
Simulated time advanced since the start or the last reset, in seconds; it keeps growing when the track loops and drives the clock of an untimed track. |
finished_ |
Whether a stopping track has reached its end. |
state_ |
The current state. |
Public member functions¶
TrackSource()¶
explicit TrackSource(TrackConfig config)
Builds the legs and places the vessel at the first point.
Parameters
| Name | Type | Description |
|---|---|---|
config |
TrackConfig |
The track, seed and playback settings. |
Declared in src/core/include/nmeasim/core/simulation/track_source.hpp:81 · defined in src/core/src/simulation/track_source.cpp:36
advance()¶
const model::VesselState& advance(std::chrono::milliseconds dt) override
Moves the vessel dt further along the track.
At the end, a stopping track holds the last point with zero speed and becomes finished; a looping one carries all the time that ran past the end into the next lap, over as many laps as dt spans. A stopping track whose total duration is zero, such as a single point, becomes finished on the first advance; a looping one stays at its point, never finishes, and its clock keeps running. Once finished, advance changes nothing.
Parameters
| Name | Type | Description |
|---|---|---|
dt |
std::chrono::milliseconds |
Simulated time to advance by. |
Returns const model::VesselState&: The new state.
Preconditions
dtis not negative.
Overrides advance · Declared in src/core/include/nmeasim/core/simulation/track_source.hpp:95 · defined in src/core/src/simulation/track_source.cpp:143
current()¶
const model::VesselState& current() const noexcept override
Returns the current state.
Returns const model::VesselState&: The state owned by the source, valid for its lifetime.
Overrides current · Declared in src/core/include/nmeasim/core/simulation/track_source.hpp:99
reset()¶
void reset() override
Returns to the first point with the seed state and restarts the clock.
The destination set with set_destination survives; a fix set with set_fix is lost.
Overrides reset · Declared in src/core/include/nmeasim/core/simulation/track_source.hpp:104 · defined in src/core/src/simulation/track_source.cpp:171
finished()¶
bool finished() const noexcept override
Returns whether the source stopped at the end of the track.
Returns bool: True once a track configured with EndBehaviour::Stop has reached its end.
Overrides finished · Declared in src/core/include/nmeasim/core/simulation/track_source.hpp:108
duration()¶
std::optional<std::chrono::milliseconds> duration() const noexcept override
Returns the time it takes to sail the whole track.
Returns std::optional<std::chrono::milliseconds>: The sum of the leg durations, rounded to the nearest millisecond; zero for a track with fewer than two points. Never std::nullopt.
Overrides duration · Declared in src/core/include/nmeasim/core/simulation/track_source.hpp:113 · defined in src/core/src/simulation/track_source.cpp:179
position()¶
std::chrono::milliseconds position() const noexcept override
Returns the elapsed time along the track.
Returns std::chrono::milliseconds: The time since the first point, rounded to the nearest millisecond, in [0, duration()].
Overrides position · Declared in src/core/include/nmeasim/core/simulation/track_source.hpp:118 · defined in src/core/src/simulation/track_source.cpp:183
seek()¶
void seek(std::chrono::milliseconds position) override
Moves the vessel to a time along the track at once.
The state is recomputed from the leg table with a zero rate of turn. Seeking to the end of a stopping track finishes it; seeking anywhere else clears finished().
Parameters
| Name | Type | Description |
|---|---|---|
position |
std::chrono::milliseconds |
Time since the first point, clamped to [0, duration()]. |
Overrides seek · Declared in src/core/include/nmeasim/core/simulation/track_source.hpp:125 · defined in src/core/src/simulation/track_source.cpp:193
jump_to_point()¶
void jump_to_point(std::size_t index)
Moves the vessel to a point of the track at once, as seek to the time the vessel passes it.
Parameters
| Name | Type | Description |
|---|---|---|
index |
std::size_t |
Index into TrackConfig::track's points; an index at or past the last point moves to the end of the track, which finishes a stopping track. |
Declared in src/core/include/nmeasim/core/simulation/track_source.hpp:132 · defined in src/core/src/simulation/track_source.cpp:197
point_index()¶
std::size_t point_index() const noexcept
Returns the index of the track point most recently passed.
Returns std::size_t: The index of the current leg's start point, the index of the last point once the end is reached, or zero for a track with fewer than two points.
Declared in src/core/include/nmeasim/core/simulation/track_source.hpp:137 · defined in src/core/src/simulation/track_source.cpp:207
timed()¶
bool timed() const noexcept
Returns whether the source follows the track's own timestamps.
Returns bool: True when TrackConfig::use_timestamps is set, the track has at least two points, and every point has a timestamp that is not earlier than the one before.
Declared in src/core/include/nmeasim/core/simulation/track_source.hpp:143
config()¶
const TrackConfig& config() const noexcept
Returns the configuration.
Returns const TrackConfig&: The configuration given to the constructor, with the destination set since then in its seed.
Declared in src/core/include/nmeasim/core/simulation/track_source.hpp:148
set_fix()¶
void set_fix(bool has_fix) noexcept
Simulates losing or regaining the GNSS fix; the change survives advance and seek but not reset.
Parameters
| Name | Type | Description |
|---|---|---|
has_fix |
bool |
False to report no fix, true to report a fix again. |
Declared in src/core/include/nmeasim/core/simulation/track_source.hpp:154
set_destination()¶
void set_destination(std::optional<model::Destination> destination) override
Sets or clears the destination; the change survives reset and seek.
Parameters
| Name | Type | Description |
|---|---|---|
destination |
std::optional<model::Destination> |
The new destination, or std::nullopt to clear it and stop the autopilot sentences. |
Overrides set_destination · Declared in src/core/include/nmeasim/core/simulation/track_source.hpp:159 · defined in src/core/src/simulation/track_source.cpp:166
Private member functions¶
build_legs()¶
void build_legs()
Rebuilds the leg table, timed_ and total_s_ from the configuration.
Declared in src/core/include/nmeasim/core/simulation/track_source.hpp:192 · defined in src/core/src/simulation/track_source.cpp:41
seek_seconds()¶
void seek_seconds(double progress_s)
Moves to a time along the track and recomputes the state with a zero rate of turn.
Parameters
| Name | Type | Description |
|---|---|---|
progress_s |
double |
Time since the first point, in seconds, clamped to [0, total_s_]. |
Declared in src/core/include/nmeasim/core/simulation/track_source.hpp:196 · defined in src/core/src/simulation/track_source.cpp:187
update_state()¶
void update_state(double dt_seconds)
Recomputes the state from the current leg and the elapsed times.
Parameters
| Name | Type | Description |
|---|---|---|
dt_seconds |
double |
Length of the step that led here, in seconds, used for the rate of turn; zero gives a zero rate of turn. |
Declared in src/core/include/nmeasim/core/simulation/track_source.hpp:201 · defined in src/core/src/simulation/track_source.cpp:84
leg_at()¶
const Leg& leg_at(double progress_s) const noexcept
Returns the leg the vessel is on at a time along the track.
Parameters
| Name | Type | Description |
|---|---|---|
progress_s |
double |
Time since the first point, in seconds. |
Returns const Leg&: The last leg that starts at or before progress_s, so that legs of zero duration are skipped; the first leg for a negative time.
Preconditions
legs_is not empty.
Declared in src/core/include/nmeasim/core/simulation/track_source.hpp:208 · defined in src/core/src/simulation/track_source.cpp:76
Private data members¶
config_¶
TrackConfig config_
Configuration, including the destination set since construction.
Declared in src/core/include/nmeasim/core/simulation/track_source.hpp:211
legs_¶
std::vector<Leg> legs_
One leg per pair of consecutive points, in track order; empty for fewer than two points.
Declared in src/core/include/nmeasim/core/simulation/track_source.hpp:214
timed_¶
bool timed_{false}
Whether the leg durations come from the track's timestamps.
Declared in src/core/include/nmeasim/core/simulation/track_source.hpp:216
total_s_¶
double total_s_{0.0}
Total duration of the track, in seconds.
Declared in src/core/include/nmeasim/core/simulation/track_source.hpp:218
progress_s_¶
double progress_s_{0.0}
Elapsed time along the track, in seconds, in [0, total_s_].
Declared in src/core/include/nmeasim/core/simulation/track_source.hpp:220
elapsed_s_¶
double elapsed_s_{0.0}
Simulated time advanced since the start or the last reset, in seconds; it keeps growing when the track loops and drives the clock of an untimed track.
Declared in src/core/include/nmeasim/core/simulation/track_source.hpp:223
finished_¶
bool finished_{false}
Whether a stopping track has reached its end.
Declared in src/core/include/nmeasim/core/simulation/track_source.hpp:225
state_¶
model::VesselState state_
The current state.
Declared in src/core/include/nmeasim/core/simulation/track_source.hpp:227
Inherited members¶
From nmeasim::core::simulation::TrackSource: operator=(), operator=(), provides_sentences(), Source(), Source(), Source(), step_once(), take_sentences(), ~Source()