Location Finding

Location Finding.

Data Structures

struct sl_rtl_loc_locator_item
Locator item which contains the position and orientation of the locator array.

Typedefs

typedef void * sl_rtl_loc_libitem
Locationing library item.

Enumerations

enum sl_rtl_loc_locator_measurement_field {
SL_RTL_LOC_LOCATOR_MEASUREMENT_AZIMUTH , SL_RTL_LOC_LOCATOR_MEASUREMENT_ELEVATION , SL_RTL_LOC_LOCATOR_MEASUREMENT_DISTANCE , SL_RTL_LOC_LOCATOR_MEASUREMENT_AZIMUTH_DEVIATION ,
SL_RTL_LOC_LOCATOR_MEASUREMENT_ELEVATION_DEVIATION , SL_RTL_LOC_LOCATOR_MEASUREMENT_DISTANCE_DEVIATION , SL_RTL_LOC_LOCATOR_LAST
}
Locator-specific measurements.
enum sl_rtl_loc_target_measurement_field { SL_RTL_LOC_TARGET_MEASUREMENT_LAST }
Target-specific measurements - Not yet supported.
enum sl_rtl_loc_estimation_mode {
SL_RTL_LOC_ESTIMATION_MODE_TWO_DIM_FAST_RESPONSE , SL_RTL_LOC_ESTIMATION_MODE_THREE_DIM_FAST_RESPONSE , SL_RTL_LOC_ESTIMATION_MODE_TWO_DIM_HIGH_ACCURACY , SL_RTL_LOC_ESTIMATION_MODE_THREE_DIM_HIGH_ACCURACY ,
SL_RTL_LOC_ESTIMATION_MODE_LAST
}
Estimation mode.
enum sl_rtl_loc_locator_parameter { SL_RTL_LOC_LOCATOR_PARAMETER_AZIMUTH_COVARIANCE , SL_RTL_LOC_LOCATOR_PARAMETER_ELEVATION_COVARIANCE , SL_RTL_LOC_LOCATOR_PARAMETER_DISTANCE_COVARIANCE , SL_RTL_LOC_LOCATOR_PARAMETER_LAST }
Locator-specific parameters related to locationing.
enum sl_rtl_loc_target_parameter { SL_RTL_LOC_TARGET_PARAMETER_TARGET_HEIGHT , SL_RTL_LOC_TARGET_CLEAR_TARGET_HEIGHT , SL_RTL_LOC_TARGET_PARAMETER_LAST }
Target-specific parameters related to locationing.
enum sl_rtl_loc_result {
SL_RTL_LOC_RESULT_POSITION_X = 0, SL_RTL_LOC_RESULT_POSITION_Y , SL_RTL_LOC_RESULT_POSITION_Z , SL_RTL_LOC_RESULT_POSITION_RADIUS ,
SL_RTL_LOC_RESULT_POSITION_STDEV_X , SL_RTL_LOC_RESULT_POSITION_STDEV_Y , SL_RTL_LOC_RESULT_POSITION_STDEV_Z , SL_RTL_LOC_RESULT_POSITION_VELOCITY_X ,
SL_RTL_LOC_RESULT_POSITION_VELOCITY_Y , SL_RTL_LOC_RESULT_POSITION_VELOCITY_Z , SL_RTL_LOC_RESULT_POSITION_ACCELERATION_X , SL_RTL_LOC_RESULT_POSITION_ACCELERATION_Y ,
SL_RTL_LOC_RESULT_POSITION_ACCELERATION_Z , SL_RTL_LOC_RESULT_LAST
}
Locationing state results.

Functions

enum sl_rtl_error_code sl_rtl_loc_init ( sl_rtl_loc_libitem *item)
enum sl_rtl_error_code sl_rtl_loc_deinit ( sl_rtl_loc_libitem *item)
enum sl_rtl_error_code sl_rtl_loc_set_mode ( sl_rtl_loc_libitem *item, enum sl_rtl_loc_estimation_mode mode)
enum sl_rtl_error_code sl_rtl_loc_add_locator ( sl_rtl_loc_libitem *item, struct sl_rtl_loc_locator_item *locator_item, uint32_t *locator_id_out)
enum sl_rtl_error_code sl_rtl_loc_create_position_estimator ( sl_rtl_loc_libitem *item)
enum sl_rtl_error_code sl_rtl_loc_set_locator_parameter ( sl_rtl_loc_libitem *item, uint32_t locator_id, enum sl_rtl_loc_locator_parameter parameter, float value)
enum sl_rtl_error_code sl_rtl_loc_set_target_parameter ( sl_rtl_loc_libitem *item, enum sl_rtl_loc_target_parameter parameter, float value)
enum sl_rtl_error_code sl_rtl_loc_clear_measurements ( sl_rtl_loc_libitem *item)
enum sl_rtl_error_code sl_rtl_loc_set_locator_measurement ( sl_rtl_loc_libitem *item, uint32_t locator_id, enum sl_rtl_loc_locator_measurement_field field, float value)
enum sl_rtl_error_code sl_rtl_loc_set_target_measurement ( sl_rtl_loc_libitem *item, enum sl_rtl_loc_target_measurement_field field, float value)
enum sl_rtl_error_code sl_rtl_loc_process ( sl_rtl_loc_libitem *item, float time_step)
enum sl_rtl_error_code sl_rtl_loc_get_result ( sl_rtl_loc_libitem *item, enum sl_rtl_loc_result result, float *value)
enum sl_rtl_error_code sl_rtl_loc_get_measurement_in_system_coordinates ( sl_rtl_loc_libitem *item, uint32_t locator_id, enum sl_rtl_loc_locator_measurement_field field, float *value_out)

Detailed Description

Location Finding.

These functions are related to the calculation of positions from angles and distances.

Data Structure Documentation

◆ sl_rtl_loc_locator_item

struct sl_rtl_loc_locator_item

Locator item which contains the position and orientation of the locator array.

Data Fields
float coordinate_x X-axis coordinate of the locator.
float coordinate_y Y-axis coordinate of the locator.
float coordinate_z Z-axis coordinate of the locator.
float orientation_x_axis_degrees X-axis rotation of the locator (Euler angles) in degrees.
float orientation_y_axis_degrees Y-axis rotation of the locator (Euler angles) in degrees.
float orientation_z_axis_degrees Z-axis rotation of the locator (Euler angles) in degrees.

Typedef Documentation

◆ sl_rtl_loc_libitem

typedef void* sl_rtl_loc_libitem

Locationing library item.

Enumeration Type Documentation

◆ sl_rtl_loc_locator_measurement_field

enum sl_rtl_loc_locator_measurement_field

Locator-specific measurements.

Enumerator
SL_RTL_LOC_LOCATOR_MEASUREMENT_AZIMUTH

Measured azimuth from locator to tag.

SL_RTL_LOC_LOCATOR_MEASUREMENT_ELEVATION

Measured elevation from locator to tag.

SL_RTL_LOC_LOCATOR_MEASUREMENT_DISTANCE

Measured distance from locator to tag.

SL_RTL_LOC_LOCATOR_MEASUREMENT_AZIMUTH_DEVIATION

Azimuth stdev.

SL_RTL_LOC_LOCATOR_MEASUREMENT_ELEVATION_DEVIATION

Elevation stdev.

SL_RTL_LOC_LOCATOR_MEASUREMENT_DISTANCE_DEVIATION

Distance stdev.

SL_RTL_LOC_LOCATOR_LAST

◆ sl_rtl_loc_target_measurement_field

enum sl_rtl_loc_target_measurement_field

Target-specific measurements - Not yet supported.

Enumerator
SL_RTL_LOC_TARGET_MEASUREMENT_LAST

◆ sl_rtl_loc_estimation_mode

enum sl_rtl_loc_estimation_mode

Estimation mode.

Enumerator
SL_RTL_LOC_ESTIMATION_MODE_TWO_DIM_FAST_RESPONSE

Two-dimensional mode - Only X and Y plane considered, less filtered mode for fast moving assests.

SL_RTL_LOC_ESTIMATION_MODE_THREE_DIM_FAST_RESPONSE

Three-dimensional mode - Covers X, Y and Z planes, less filtered mode for fast moving assests.

SL_RTL_LOC_ESTIMATION_MODE_TWO_DIM_HIGH_ACCURACY

Two-dimensional mode - Only X and Y plane considered, more filtered mode for relatively static assets.

SL_RTL_LOC_ESTIMATION_MODE_THREE_DIM_HIGH_ACCURACY

Three-dimensional mode - Covers X, Y and Z planes, more filtered mode for relatively static assets.

SL_RTL_LOC_ESTIMATION_MODE_LAST

◆ sl_rtl_loc_locator_parameter

enum sl_rtl_loc_locator_parameter

Locator-specific parameters related to locationing.

Enumerator
SL_RTL_LOC_LOCATOR_PARAMETER_AZIMUTH_COVARIANCE

Covariance of the azimuth measurements specific to locator.

SL_RTL_LOC_LOCATOR_PARAMETER_ELEVATION_COVARIANCE

Covariance of the elevation measurements specific to locator.

SL_RTL_LOC_LOCATOR_PARAMETER_DISTANCE_COVARIANCE

Covariance of the distance measurements specific to locator.

SL_RTL_LOC_LOCATOR_PARAMETER_LAST

◆ sl_rtl_loc_target_parameter

enum sl_rtl_loc_target_parameter

Target-specific parameters related to locationing.

Enumerator
SL_RTL_LOC_TARGET_PARAMETER_TARGET_HEIGHT
SL_RTL_LOC_TARGET_CLEAR_TARGET_HEIGHT
SL_RTL_LOC_TARGET_PARAMETER_LAST

◆ sl_rtl_loc_result

enum sl_rtl_loc_result

Locationing state results.

Enumerator
SL_RTL_LOC_RESULT_POSITION_X

Estimated X-axis position of the target.

SL_RTL_LOC_RESULT_POSITION_Y

Estimated Y-axis position of the target.

SL_RTL_LOC_RESULT_POSITION_Z

Estimated Z-axis position of the target.

SL_RTL_LOC_RESULT_POSITION_RADIUS

The combined radius (stdev) of the location estimate.

SL_RTL_LOC_RESULT_POSITION_STDEV_X

The accuracy (stdev) of the location x-coordinate estimate.

SL_RTL_LOC_RESULT_POSITION_STDEV_Y

The accuracy (stdev) of the location y-coordinate estimate.

SL_RTL_LOC_RESULT_POSITION_STDEV_Z

The accuracy (stdev) of the location z-coordinate estimate.

SL_RTL_LOC_RESULT_POSITION_VELOCITY_X

Estimated X-axis velocity of the target.

SL_RTL_LOC_RESULT_POSITION_VELOCITY_Y

Estimated Y-axis velocity of the target.

SL_RTL_LOC_RESULT_POSITION_VELOCITY_Z

Estimated Z-axis velocity of the target.

SL_RTL_LOC_RESULT_POSITION_ACCELERATION_X

Estimated X-axis acceleration of the target.

SL_RTL_LOC_RESULT_POSITION_ACCELERATION_Y

Estimated Y-axis acceleration of the target.

SL_RTL_LOC_RESULT_POSITION_ACCELERATION_Z

Estimated Z-axis acceleration of the target.

SL_RTL_LOC_RESULT_LAST

Number of results.

Function Documentation

◆ sl_rtl_loc_init()

enum sl_rtl_error_code sl_rtl_loc_init ( sl_rtl_loc_libitem * item )

Initialize the locationing libitem instance.

Parameters
[in] item Pointer to the libitem to be initialized
Returns
SL_RTL_ERROR_SUCCESS if successful

◆ sl_rtl_loc_deinit()

enum sl_rtl_error_code sl_rtl_loc_deinit ( sl_rtl_loc_libitem * item )

Deinitialize the locationing libitem instance.

Parameters
[in] item Pointer to the libitem to be initialized
Returns
SL_RTL_ERROR_SUCCESS if successful

◆ sl_rtl_loc_set_mode()

enum sl_rtl_error_code sl_rtl_loc_set_mode ( sl_rtl_loc_libitem * item,
enum sl_rtl_loc_estimation_mode mode
)

Set the locationing dimensionality mode. Possible choices are 2D or 3D modes. Two-dimensional mode does not vary the z-position of the target and assumes it is 0 at all times. When updating e.g. the distance measure- ment from the locator to the target in 2D mode, it should be noted that even if the locator and tag are on different z-planes, the distance should be given as the distance as if they were on the same z-plane.

Parameters
[in] item Pointer to the libitem
[in] mode Estimation mode as enum
Returns
SL_RTL_ERROR_SUCCESS if successful

◆ sl_rtl_loc_add_locator()

enum sl_rtl_error_code sl_rtl_loc_add_locator ( sl_rtl_loc_libitem * item,
struct sl_rtl_loc_locator_item * locator_item,
uint32_t * locator_id_out
)

Add a locator item into the locationing estimator after setting its position and orientation parameters. All locators need to be added using this function before calling sl_rtl_loc_create_position_estimator to create the estimator instance.

Parameters
[in] item Pointer to the libitem
[in] locator_item Locator item instance to be added
[out] locator_id_out ID of the locator assigned by the library
Returns
SL_RTL_ERROR_SUCCESS if successful

◆ sl_rtl_loc_create_position_estimator()

enum sl_rtl_error_code sl_rtl_loc_create_position_estimator ( sl_rtl_loc_libitem * item )

Create the position estimator instance after all locators have been added.

Parameters
[in] item Pointer to the libitem
Returns
SL_RTL_ERROR_SUCCESS if successful

◆ sl_rtl_loc_set_locator_parameter()

enum sl_rtl_error_code sl_rtl_loc_set_locator_parameter ( sl_rtl_loc_libitem * item,
uint32_t locator_id,
enum sl_rtl_loc_locator_parameter parameter,
float value
)

Set locator-specific parameters, such as the azimuth and elevation measurement covariances.

Parameters
[in] item Pointer to the libitem
[in] locator_id ID of the locator for which the parameter shall be set
[in] parameter Parameter to be set (as enum)
[in] value New value for the parameter
Returns
SL_RTL_ERROR_SUCCESS if successful

◆ sl_rtl_loc_set_target_parameter()

enum sl_rtl_error_code sl_rtl_loc_set_target_parameter ( sl_rtl_loc_libitem * item,
enum sl_rtl_loc_target_parameter parameter,
float value
)

Set target-specific parameters, such as the process noise covariance or the known target height.

Parameters
[in] item Pointer to the libitem
[in] parameter Parameter to be set (as enum)
[in] value New value for the parameter
Returns
SL_RTL_ERROR_SUCCESS if successful

◆ sl_rtl_loc_clear_measurements()

enum sl_rtl_error_code sl_rtl_loc_clear_measurements ( sl_rtl_loc_libitem * item )

Clears previous measurements. This function should be called before setting new measurements if the previous measurements are not valid for the next iteration step.

Parameters
[in] item Pointer to the libitem
Returns
SL_RTL_ERROR_SUCCESS if successful

◆ sl_rtl_loc_set_locator_measurement()

enum sl_rtl_error_code sl_rtl_loc_set_locator_measurement ( sl_rtl_loc_libitem * item,
uint32_t locator_id,
enum sl_rtl_loc_locator_measurement_field field,
float value
)

Set a new measurement for a locator specified by the locator ID.

Parameters
[in] item Pointer to the libitem
[in] locator_id ID of the locator for which the measurement will be set
[in] field Measurement to be updated (as enum)
[in] value New value for the measurement
Returns
SL_RTL_ERROR_SUCCESS if successful

◆ sl_rtl_loc_set_target_measurement()

enum sl_rtl_error_code sl_rtl_loc_set_target_measurement ( sl_rtl_loc_libitem * item,
enum sl_rtl_loc_target_measurement_field field,
float value
)

Set a new measurement for the target. Current version does not support this function and calling it will have no effect.

Parameters
[in] item Pointer to the libitem
[in] field Measurement to be updated (as enum)
[in] value New value for the measurement
Returns
SL_RTL_ERROR_SUCCESS if successful

◆ sl_rtl_loc_process()

enum sl_rtl_error_code sl_rtl_loc_process ( sl_rtl_loc_libitem * item,
float time_step
)

Process the current time step of the locationing filter. This function should be called after old measurements have been cleared and new measurements have been set for the current time step. The process will step the filter forward and provide new state results and state covariance values, which can be retrieved with separate function calls.

Parameters
[in] item Pointer to the libitem
[in] time_step Process time interval in seconds. This is the time separation between the previous step and this current step.
Returns
SL_RTL_ERROR_SUCCESS if successful

◆ sl_rtl_loc_get_result()

enum sl_rtl_error_code sl_rtl_loc_get_result ( sl_rtl_loc_libitem * item,
enum sl_rtl_loc_result result,
float * value
)

Get result of the current state variables or state covariances.

Parameters
[in] item Pointer to the libitem
[in] result The desired state variable result as enum
[out] value The value output of the state variable
Returns
SL_RTL_ERROR_SUCCESS if successful

◆ sl_rtl_loc_get_measurement_in_system_coordinates()

enum sl_rtl_error_code sl_rtl_loc_get_measurement_in_system_coordinates ( sl_rtl_loc_libitem * item,
uint32_t locator_id,
enum sl_rtl_loc_locator_measurement_field field,
float * value_out
)

Get latest measurement converted into the coordinate system of the multi-locator system.

Parameters
[in] item Pointer to the libitem
[in] locator_id ID of the locator whose measurement will be retrieved
[in] field Measurement to be retrieved (as enum)
[out] value_out The value output of the state variable
Returns
SL_RTL_ERROR_SUCCESS if successful