AcresSessionLog.h

Acres/Source/Acres/AcresSessionLog.h Generated

Streaming 120 Hz tractor log for menu sessions: <session>/tractor.csv plus session-summary.json on close.

Enabled by the -SessionLog command-line flag, which the in-game menu adds when it launches a session (AcresSession.cpp). AAcresVehiclePawn formats one CSV row per physics step on the physics thread and hands it over through a lock-free queue; the game thread writes queued rows to disk once per frame. The queue is bounded, so a slow disk drops rows (counted in the summary) instead of stalling physics.

Frames in the CSV: Unreal world coordinates (X east, Y south, Z up, written in metres) and ENU (east, north, up) about the ACRE origin, plus latitude/longitude from the inverse EPSG:2968 projection (NAD83(HARN) / Indiana West, US survey feet). NAD83(HARN) is within about a metre of WGS84; the GNSS sensor stream models the datum difference, this log does not.

FAcresSessionLog

class FAcresSessionLog

Writer for tractor.csv and session-summary.json.

Unreal background: FArchive is Unreal's binary stream (here a file writer), TUniquePtr its unique_ptr, TQueue<..., EQueueMode::Spsc> a lock-free single-producer / single-consumer queue, FString its string class.

Usage: the vehicle pawn calls Open in BeginPlay, Push from its 120 Hz physics callback, Flush from Tick and Close in EndPlay. Only one thread may call Push (the physics thread) and one may call Flush (the game thread).

Example

SessionLog = MakeShared<FAcresSessionLog>();
if (!SessionLog->Open(OutputDirectory, Parameters.WheelbaseM)) SessionLog.Reset();
SessionLog->Push(Telemetry, &EnvState, Parameters.MassKg, Parameters.PtoKW); // physics thread
SessionLog->Flush();                                                          // game thread
SessionLog->Close();                                                          // EndPlay

FAcresSessionLog::Open

Creates the directory, opens tractor.csv and writes the header row.

Argument	Description
Directory	Session output directory (created if missing).
WheelbaseM	Tractor wheelbase, m, used for the commanded and low-speed curvature.

Returns: False if the file could not be created.

Note

The implement_draft_n column is the live draft from each row's telemetry (FAcresVehicleTelemetry::DraftN, ASABE D497.7 draft at the current speed, depth and soil), and diff_lock the differential lock state.

bool Open(const FString& Directory, double WheelbaseM);

FAcresSessionLog::Push

Formats one CSV row from a physics step and queues it; updates the summary totals.

Derives body-frame velocity and acceleration (finite difference of velocity), ENU yaw rate, heading, lat/lon, engine power, the model's fuel flow and energy ledger, and commanded vs measured path curvature. If more than 24000 rows (about 200 s) are waiting, the row is dropped and counted.

Argument	Description
T	Vehicle telemetry for this step (positions in cm, velocities in m/s, Unreal axes).
Env	Weather state for the time, temperature and weather columns, or null to write zeros.
MassKg	Current vehicle mass, kg (grows with the harvester's grain bunker).
PtoKW	Current power take-off load, kW.

Note

Physics thread only. Does nothing if the file is not open.

void Push(const FAcresVehicleTelemetry& T, const AcresEnv::State* Env, double MassKg, double PtoKW);

FAcresSessionLog::Flush

Writes all queued rows to disk and flushes the file.

Note

Game thread, once per frame.

void Flush();

FAcresSessionLog::Close

Flushes the remaining rows, closes tractor.csv and writes session-summary.json.

Summary fields: schema, rows, dropped_rows, duration_s, distance_m, max_speed_mps, fuel_used_l, engine_energy_kwh, max_abs_slip, max_sinkage_m, distance_model, fuel_model (text) and a files map describing the session folder.

Note

Game thread. Safe while the physics thread is still pushing: Close takes the same lock as Push, marks the log closed, and later Push calls return without writing.

void Close();

FAcresSessionLog::IsOpen

True between a successful Open and Close.

bool IsOpen() const ;