include/OnTubeVis/OnTubeVis.h file

OTV_API bool otv__startup(const int argc, const char*const* argv)

Initializes and starts the OnTubeVis main event loop. Since startup can take a while, this call will not block. Use otv__wait_for_startup() to wait until the implementation is ready to receive commands and check if the initialization was actually successful.

Control flow. OnTubeVis is typically its own application, and the CGV Framework used internally always operates under the assumption that it runs its own host process. To emulate this when using OnTubeVis as a module, the calling process must enter into the execution of OnTubeVis as if it was the operating system, i.e. it must hand off control to the main() function of the CGV Framework. This function handles all of that and hosts the OnTubeVis main loop in its own, specially spawned thread.

Arguments. We adopt the convention that the very first argument, required to contain the command name by the POSIX standard, should point to the library file containing the OnTubeVis service. otv__startup() will prepend this first argument automatically – the arguments passed to this function should only contain actual, functional args without the initial command name.

Arguments that the OnTubeVis implementation recognizes include all arguments known to the CGV Framework, as well as the following OnTubeVis-specific options:

OTV_API bool otv__wait_for_startup(void)

Waits until the startup process initiated by otv__startup() is complete and the OnTubeVis implementation can receive commands.

OTV_API OTV_TerminateResult otv__terminate(void)

Requests the OnTubeVis main event loop to terminate and shut down.

OTV_API const char* otv__get_module_filepath(void)

Reports the file path of the currently loaded OnTubeVis library file.

Can be used for setting the 0th command line argument to be passed to the OnTubeVis main() function in case the library was linked against directly. There should typically be no need to use this whatsoever, since the preferred way to launch the OnTubeVis implementation is otv__startup(), which takes care of this automatically. When using dlopen()-like functionality, this path will already be known a-priori by the client anyway, but it can be used to check the location of the library the module was loaded from by the OS during process startup.

OTV_API bool otv__start_vis_session(OTV_VisSetupHandle vis_setup)

Start the visualization with the given setup.

When this function returns successfully, clients may start streaming samples to the trajectories created during visualization setup. There can only be one session active at a time, hence there is no handle for the session started this way. A new session can be started (replacing the currently running one, if any) by calling otv__start_vis_session again with a new (or the same) setup.

OTV_API OTV_Vec2 otv__instantiate_Glyph(const uint32_t traj_id, const uint32_t layer, const OTV_GlyphData* data)

Instantiates the given glyph to calculate its geometry and returns its extents along the trajectory.

Requires an active visualization session to determine the static glyph parameters.

OTV_API void otv__stream_spline_node(const uint32_t traj_id, const OTV_HermiteNode* node, const OTV_SegmentArclen* arclen)

Stream a spline node (made up of position, tangent and a timestamp) to the indicated trajectory, when the active visualization is set up to not use smooth extrapolation.

To accommodate time-critical realtime processes, this function is "fire-and-forget", i.e. no checks will be done to determine whether the sample was processed successfully. Instead, the function will return immediatly after the command to add the sample was submitted.

Using this function on a setup that uses at least one extrapolation segment will cause the extrapolation to be point-like, i.e. all extrapolated nodes will be set to the position of the passed-in spline node.

OTV_API void otv__stream_spline_node_and_extrapol(const uint32_t traj_id, const OTV_HermiteNode* node, const OTV_SegmentArclen* arclen, const OTV_Extrapolation* extrapol)

Stream a spline node (made up of position, tangent and a timestamp) to the indicated trajectory, as well as the extrapolated path following the node that should be used for smooth position refreshes and displaying as-of-yet orphaned glyphs.

To accommodate time-critical realtime processes, this function is "fire-and-forget", i.e. no checks will be done to determine whether the sample was processed successfully. Instead, the function will return immediately after the command to add the sample was submitted.

Using this function on a setup that uses no extrapolation segments will cause the provided extrapolation to be ignored.

OTV_API OTV_SegmentArclen otv__compute_arclen(const OTV_HermiteNode* node0, const OTV_HermiteNode* node1, const float sigma)

Compute an arc length parameterization for the given Hermite curve.

The arc length up to the segment currently being parameterized, typically called sigma, can be provided as well, resulting in all values of s computed by the resulting parameterization being offset by this value.

The implementation will typically perform a numerical approximation from scratch, which is relatively slow (albeit fairly accurate). Consider using information available to you in your data to infer arc length instead of relying on this function.

OTV_API float otv__eval_arclen(const OTV_SegmentArclen* s, const float t)

Evaluate s(t), where s is defined by the coefficients of the provided arc length parameterization, to compute the arc length s at the given (time-like) curve parameter t.

The parameter t can be any number, but the arc length parameterization strategy used in the OnTubeVis API by construction only gives reliable results for t=0..1 on the corresponding segment, and can potentially even decrease again for t≥1 (or increase for t≤0)

OTV_API OTV_Vec3 otv__latlon_height_to_cartesian(const double latitude, const double longitude, const double height)

Obtain the Cartesian coordinates for the given set of latitude/longitude and height values. This is only available if a geo reference has been configured during setup.

OTV_API void otv__compute_extrapol(OTV_Extrapolation* out, const uint32_t num, const OTV_HermiteNode* ref_node0, const OTV_HermiteNode* ref_node1, const OTV_SegmentArclen* ref_arclen)

Create a primitive extrapolation with the desired number of segments given one reference Hermite segment to extrapolate from.

It is up to the implementation how the extrapolation is done exactly. The OnTubeVis desktop application currently just adds perfectly straight segments with the same velocity as the end node of the provided segment.

OTV_API void otv__stream_glyph(const uint32_t traj_id, const uint32_t layer, const OTV_GlyphData* glyph_data)

Stream a single glyph instance to the specified layer on the specified trajectory.

To accomodate time-critical realtime processes, this function is "fire-and-forget", i.e. no checks will be done to determine whether the glyph was processed successfully. Instead, the function will return immediatly after the command to add the glyph was submitted.

OTV_API void otv__stream_glyphs(const uint32_t traj_id, const uint32_t layer, const OTV_GlyphData* glyphs_data, const uint32_t num_glyphs)

Stream a number of glyph instances to the specified layer on the specified trajectory.

To accomodate time-critical realtime processes, this function is "fire-and-forget", i.e. no checks will be done to determine whether the glyphs were processed successfully. Instead, the function will return immediatly after the command to add the glyphs was submitted.