vis_setup.h file

Sub header exposing the visualization setup API.

Classes

struct OTV_LayerConfig: A struct storing the configuration for a single on-tube visualization layer.

Enums

enum OTV_ExtrapolProgression { Instant = 0, Natural }: The enumeration of time progression modes for the display of trajectory extrapolations.

Typedefs

using OTV_VisSetup = struct OTV_VisSetup: A handle type representing a visualization setup.
using OTV_VisSetupHandle = OTV_VisSetup*: The typed handle for visualization setups.
using otv__create_VisSetup_funct = OTV_VisSetupHandle(*)(const char*const): The function pointer type for the otv__create_VisSetup() function.
using otv__free_VisSetup_funct = void(*)(OTV_VisSetupHandle): The function pointer type for the otv__free_VisSetup() function.
using otv__add_trajectory_funct = uint32_t(*)(OTV_VisSetupHandle): The function pointer type for the otv__add_trajectory() function.
using otv__add_layer_funct = bool(*)(OTV_VisSetupHandle, const OTV_LayerConfig*): The function pointer type for the otv__add_layer() function.
using otv__layer_color_source_funct = bool(*)(OTV_VisSetupHandle, const unsigned, const OTV_Interval, const char*const): The function pointer type for the otv__layer_color_source() function.
using otv__layer_height_source_funct = bool(*)(OTV_VisSetupHandle, const unsigned, const OTV_Interval, const OTV_Interval, const char*const): The function pointer type for the otv__layer_height_source() function.
using otv__layer_orientation_source_funct = bool(*)(OTV_VisSetupHandle, const unsigned, const OTV_Interval, const OTV_Interval, const char*const): The function pointer type for the otv__layer_orientation_source() function.
using otv__layer_radius_source_funct = bool(*)(OTV_VisSetupHandle, const unsigned, const OTV_Interval, const OTV_Interval, const char*const): The function pointer type for the otv__layer_radius_source() function.
using otv__layer_value_source_funct = bool(*)(OTV_VisSetupHandle, const unsigned, const unsigned, const OTV_Interval, const char*const): The function pointer type for the otv__layer_value_source() function.
using otv__layer_width_source_funct = bool(*)(OTV_VisSetupHandle, const unsigned, const OTV_Interval, const OTV_Interval, const char*const): The function pointer type for the otv__layer_width_source() function.
using otv__geo_reference_funct = void(*)(OTV_VisSetupHandle, const double, const double): The function pointer type for the otv__geo_reference() function.
using otv__extrapolation_length_funct = void(*)(OTV_VisSetupHandle, const double, const double): The function pointer type for the otv__extrapolation_length() function.
using otv__extrapol_progression_funct = void(*)(OTV_VisSetupHandle vis_setup, const OTV_ExtrapolProgression): The function pointer type for the otv__geo_reference() function.

Functions

auto otv__create_VisSetup(const char*const name) -> OTV_API OTV_VisSetupHandle: Allocates a visualization setup. Must be deallocated via otv__free_VisSetup() when not needed anymore, e.g. after the setup has been used to spawn a visualization session.
auto otv__free_VisSetup(OTV_VisSetupHandle vis_setup) -> OTV_API void: De-allocates a visualization setup that was allocated using otv__create_VisSetup().
auto otv__add_trajectory(OTV_VisSetupHandle vis_setup, const float radius) -> OTV_API uint32_t: Adds a trajectory to the given visualization setup.
auto otv__add_layer(OTV_VisSetupHandle vis_setup, const OTV_LayerConfig* config) -> OTV_API bool: Add an on-tube visualization layer with the given configuration to a visualization setup.
auto otv__layer_color_source(OTV_VisSetupHandle vis_setup, const unsigned layer, const OTV_Interval in_range, const char*const desc) -> OTV_API void: Set the source of the dynamic color attribute used by this layer (if in use).
auto otv__layer_height_source(OTV_VisSetupHandle vis_setup, const unsigned layer, const OTV_Interval in_range, const OTV_Interval out_range, const char*const desc) -> OTV_API void: Set the source of the dynamic height attribute used by this layer (if in use).
auto otv__layer_orientation_source(OTV_VisSetupHandle vis_setup, const unsigned layer, const OTV_Interval in_range, const OTV_Interval out_range, const char*const desc) -> OTV_API void: Set the source of the dynamic orientation attribute used by this layer (if in use).
auto otv__layer_radius_source(OTV_VisSetupHandle vis_setup, const unsigned layer, const OTV_Interval in_range, const OTV_Interval out_range, const char*const desc) -> OTV_API void: Set the source of the dynamic radius attribute used by this layer (if in use).
auto otv__layer_value_source(OTV_VisSetupHandle vis_setup, const unsigned layer, const unsigned value_id, const OTV_Interval in_range, const char*const desc) -> OTV_API void: Set the source of one of the 4 dynamic value attributes used by this layer (if in use).
auto otv__layer_width_source(OTV_VisSetupHandle vis_setup, const unsigned layer, const OTV_Interval in_range, const OTV_Interval out_range, const char*const desc) -> OTV_API void: Set the source of the dynamic width attribute used by this layer (if in use).
auto otv__geo_reference(OTV_VisSetupHandle vis_setup, const double latitude, const double longitude) -> OTV_API void: Provide a geo reference in WGS84 lat/long coordinates for the trajectory data. Implementations may act on this e.g. by displaying map data, 3D buildings etc. around the trajectories.
auto otv__extrapolation_length(OTV_VisSetupHandle vis_setup, const uint32_t num_segments) -> OTV_API void: Set the amount of Hermite spline segments that should be used for smooth extrapolation of the trajectory while waiting for new spline nodes to arrive. Setting this to 0 (the default) disables extrapolation display entirely.
auto otv__extrapol_progression(OTV_VisSetupHandle vis_setup, const OTV_ExtrapolProgression progression) -> OTV_API void: Set how the extrapolations (if enabled) should be visualized in terms of time progression.

Enum documentation

enum OTV_ExtrapolProgression

The enumeration of time progression modes for the display of trajectory extrapolations.

Enumerators
Instant	Show the full extrapolated path immediately, as soon as it is known. Implementations are free to use additional means of visualizing the current time, e.g. by drawing a time cursor on the extrapolated path.
Natural	Smoothly extend the trajectory along its extrapolated path as time progresses, giving of the impression of natural movement. Implementations are still free to mark extrapolated parts of the displayed trajectory in any way they see fit (e.g. by drawing the extrapolated part translucent).

Function documentation

OTV_API OTV_VisSetupHandle otv__create_VisSetup(const char*const name)

Allocates a visualization setup. Must be deallocated via otv__free_VisSetup() when not needed anymore, e.g. after the setup has been used to spawn a visualization session.

Parameters
name	The name the visualization should show up as within OnTubeVis.
Returns	A handle to the newly created visualization setup.

OTV_API void otv__free_VisSetup(OTV_VisSetupHandle vis_setup)

De-allocates a visualization setup that was allocated using otv__create_VisSetup().

Parameters
vis_setup	The handle to the visualization setup to destroy.

OTV_API uint32_t otv__add_trajectory(OTV_VisSetupHandle vis_setup, const float radius)

Adds a trajectory to the given visualization setup.

Parameters
vis_setup	The visualization setup to change the number of trajectories of.
radius	The desired initial radius for the trajectory.
Returns	The ID of the new trajectory which it will be accessible by within the visualization session resulting from the setup, e.g. via `otv__stream_spline_sample()` or `otv__stream_glyph()`.

OTV_API bool otv__add_layer(OTV_VisSetupHandle vis_setup, const OTV_LayerConfig* config)

Add an on-tube visualization layer with the given configuration to a visualization setup.

Parameters
vis_setup	The visualization setup to add the layer to.
config	The layer configuration to use for the new layer.
Returns	`true` if the layer could be added, `false` otherwise (typically because there are already 4 layers).

Note that there can only be a maximum of 4 visualization layers active. Trying to add more than that will cause this function to fail.

OTV_API void otv__layer_color_source(OTV_VisSetupHandle vis_setup, const unsigned layer, const OTV_Interval in_range, const char*const desc)

Set the source of the dynamic color attribute used by this layer (if in use).

Parameters
vis_setup	The visualization setup to add the layer to.
layer	The index of the layer to set the attribute source for.
in_range	The inclusive interval of input values that will linearly map to the default output range defined for this visual attribute by the configured glyph/plot type.
desc	A short descriptive name indicating the source of the attribute's values.

If glyphs/plots on this layer don't use this attribute for instantiation, the source information will simply be ignored. Attributes that did not get a source set explicitly but are used will be assigned a nondescript generic source by the implementation, with input values mapping unchanged to the default output range.

OTV_API void otv__layer_height_source(OTV_VisSetupHandle vis_setup, const unsigned layer, const OTV_Interval in_range, const OTV_Interval out_range, const char*const desc)

Set the source of the dynamic height attribute used by this layer (if in use).

Parameters
vis_setup	The visualization setup to add the layer to.
layer	The index of the layer to set the attribute source for.
in_range	The inclusive interval of input values that will linearly map to the output range out_range.
out_range	The inclusive interval of values that will be produced for the visual attribute by linearly mapping from the in_range. The semantics of the numbers in out_range correspond to the semantics of the `height` attribute of the configured glyph/plot type. Consult the corresponding `OTV_...Info` struct for details. Typically, the values are in multiples of the tube/ribbon radius.
desc	A short descriptive name indicating the source of the attribute's values.

OTV_API void otv__layer_orientation_source(OTV_VisSetupHandle vis_setup, const unsigned layer, const OTV_Interval in_range, const OTV_Interval out_range, const char*const desc)

Set the source of the dynamic orientation attribute used by this layer (if in use).

Parameters
vis_setup	The visualization setup to add the layer to.
layer	The index of the layer to set the attribute source for.
in_range	The inclusive interval of input values that will linearly map to the output range out_range.
out_range	The inclusive interval of values that will be produced for the visual attribute by linearly mapping from the in_range. The semantics of the numbers in out_range correspond to the semantics of the `orientation` attribute of the configured glyph/plot type. Consult the corresponding `OTV_...Info` struct for details. Typically, values for orientation are in degree from `-180...180`.
desc	A short descriptive name indicating the source of the attribute's values.

OTV_API void otv__layer_radius_source(OTV_VisSetupHandle vis_setup, const unsigned layer, const OTV_Interval in_range, const OTV_Interval out_range, const char*const desc)

Set the source of the dynamic radius attribute used by this layer (if in use).

Parameters
vis_setup	The visualization setup to add the layer to.
layer	The index of the layer to set the attribute source for.
in_range	The inclusive interval of input values that will linearly map to the output range out_range.
out_range	The inclusive interval of values that will be produced for the visual attribute by linearly mapping from the in_range. The semantics of the numbers in out_range correspond to the semantics of the `radius` attribute of the configured glyph/plot type. Consult the corresponding `OTV_...Info` struct for details. Typically, the values are in multiples of the tube/ribbon radius.
desc	A short descriptive name indicating the source of the attribute's values.

OTV_API void otv__layer_value_source(OTV_VisSetupHandle vis_setup, const unsigned layer, const unsigned value_id, const OTV_Interval in_range, const char*const desc)

Set the source of one of the 4 dynamic value attributes used by this layer (if in use).

Parameters
vis_setup	The visualization setup to add the layer to.
layer	The index of the layer to set the attribute source for.
value_id	The ID of the value attribute to set the source for (must be in the range of `0..3`)
in_range	The inclusive interval of input values that will linearly map to the default output range defined for this visual attribute by the configured glyph/plot type.
desc	A short descriptive name indicating the source of the attribute's values.

Currently, SignBlob glyphs support value 0 and LinePlot supports values 0..3.

OTV_API void otv__layer_width_source(OTV_VisSetupHandle vis_setup, const unsigned layer, const OTV_Interval in_range, const OTV_Interval out_range, const char*const desc)

Set the source of the dynamic width attribute used by this layer (if in use).

Parameters
vis_setup	The visualization setup to add the layer to.
layer	The index of the layer to set the attribute source for.
in_range	The inclusive interval of input values that will linearly map to the output range out_range.
out_range	The inclusive interval of values that will be produced for the visual attribute by linearly mapping from the in_range. The semantics of the numbers in out_range correspond to the semantics of the `width` attribute of the configured glyph/plot type. Consult the corresponding `OTV_...Info` struct for details. Typically, the values are in multiples of the tube/ribbon radius.
desc	A short descriptive name indicating the source of the attribute's values.

OTV_API void otv__geo_reference(OTV_VisSetupHandle vis_setup, const double latitude, const double longitude)

Provide a geo reference in WGS84 lat/long coordinates for the trajectory data. Implementations may act on this e.g. by displaying map data, 3D buildings etc. around the trajectories.

Parameters
vis_setup	The visualization setup to attach the geo reference to.
latitude	The latitude of the geo reference.
longitude	The latitude of the geo reference.

When a geo reference is provided for a visualization setup, then all 3D coordinates submitted to the API under this setup will be interpreted as being Cartesian coordinates with unit 1 meter, with the provided geo reference located in the Cartesian origin (0, 0, 0). Furthermore, the reference point is assumed to be located at exactly ground level at this geographical location.

OTV_API void otv__extrapolation_length(OTV_VisSetupHandle vis_setup, const uint32_t num_segments)

Set the amount of Hermite spline segments that should be used for smooth extrapolation of the trajectory while waiting for new spline nodes to arrive. Setting this to 0 (the default) disables extrapolation display entirely.

Parameters
vis_setup	The visualization setup to set the extrapolation length for.
num_segments	The desired length of the trajectory extrapolations, in segments (default: 0).:

In the time between submission of spline nodes, which can (and ideally should) be streamed relatively infrequent (≤ 1/s) to utilize the expressiveness of cubic curves, an extrapolation can be displayed. This enables (a) smooth, continuous updates of the trajectory at screen refresh rates and (b) displaying glyphs / updating plots on the current, to-be-completed segment pending an actual position measurement.

The API does not provide or use any sort of predictive models, instead the prediction should be made by the client and submitted to the API. Depending on the sophistication that clients want in their prediction, the number of extrapolated segments can be adjusted to account for more complex paths.

OTV_API void otv__extrapol_progression(OTV_VisSetupHandle vis_setup, const OTV_ExtrapolProgression progression)

Set how the extrapolations (if enabled) should be visualized in terms of time progression.

Parameters
vis_setup	The visualization setup to set the progression of extrapolations for.
progression	The progression mode for extrapolations.