Expand description
Tag logs opened and viewed through sensorViz’s C++ core.
Session is a safe wrapper over the C interface in
host/libraries/tagcore-c/sensorviz_c.h, which wraps the Qt-free
sensorviz::Session – the code the Qt sensorViz runs. So a Rust program
shows a log exactly as sensorViz does: the same log reader, display
transforms (altitude, IMU magnitudes, compass), plot policy, hover text and
preference file.
use sensorviz_session::{Preferences, Session};
let preferences = Preferences::new()?;
let mut session = Session::new()?;
session.open("log.db3", Some(&preferences))?;
let spec = session.spec()?;
for trace in &spec.traces {
let envelope = session.envelope(trace.stream, f64::NEG_INFINITY, f64::INFINITY, 1200,
spec.break_at_gaps);
// draw envelope.time / envelope.value
}
let changes = session.set_stream_range("imu_pressure", 950.0, 1010.0);
if changes.contains(sensorviz_session::Changes::RANGES) {
// redraw
}Descriptions – the catalog, the view state, the plot spec, the parameters – cross as JSON and are parsed into the types here; samples cross as arrays. Times are seconds in the log’s time domain: since the Unix epoch, or since the start of collection for IMUTag.
§Linking
As for taglogwriter and calibsession: tagcore-c-sys links
libtagcore_c, found through TAGCORE_C_LIB_DIR, statically on macOS and
shared on Linux and Windows, and a program may use this crate beside them.
§Safety model
All unsafe is in this file. A Session or Preferences owns exactly
one C handle, never null, freed exactly once in Drop. Every pointer
passed in points at Rust memory that lives until the call returns, sized
as the header requires. A string the library returns belongs to the handle
and stays valid until the next call on it, so it is copied before any
other call. Each handle may move between threads but not be shared: both
types are Send and not Sync, and every call that changes or reads
through the handle’s string buffer takes &mut self.
§Maintaining
The declarations are tagcore_c_sys::svz
(host/libraries/tagcore-c-sys/src/svz.rs), written by hand from
sensorviz_c.h. When the header changes, change the declaration and the
safe method over it. If a signature, meaning or JSON schema changed, the
header raises SVZ_ABI_VERSION, and svz::SVZ_ABI_VERSION must follow;
Session::new refuses a library built from another version. The JSON
types here mirror the writers in sensorviz_c.cc; a field added there is
ignored here until it is added.
Structs§
- Axis
- One y axis.
- Catalog
- The open log: what it is and what it holds besides its streams.
- Changes
- What a call changed, as the
SVZ_CHANGE_*bits: what a front end redraws. - Compass
Calibration - The newest compass calibration in the log.
- Custom
Range - A y range the user set, or one linked to such a range.
- Envelope
- One stream’s M4 envelope: at most four points per column, plus gap markers.
- Event
Marker - Discrete events drawn as vertical lines.
- Orientation
Sample - One compass orientation sample.
- Parameter
- A transform parameter, described for building its control.
- Preferences
- The per-tag display preferences: colors, axis sides, visibility and gaps that follow a tag type, and their JSON file. Outlives sessions.
- Record
Set - A multi-column table that transforms read, such as
compass_raw. - Session
- One opened log: its catalog, the view state, the transforms, and what the plot and readout show.
- Spec
- What the plot shows: everything a renderer needs besides the samples.
- Stream
- One stream: what it is, how it is drawn, and its plot data.
- Trace
- One drawn trace.
- Transform
Failure - A transform that failed when the log was opened.
- View
- The view state: the streams and every choice about them.
Enums§
- Axis
Mode - How an axis’s range is chosen.
- Error
- Why a call failed.
- Side
- A side of the plot.
- Time
Domain - A time domain.