compass_conversions

This package contains utilities for converting between the various parametrizations of Azimuth messages.

See readme of the compass stack for definitions of the terms used in this readme.

C++ Libraries

compass_conversions::CompassConverter

Helper for direct conversions between parametrizations.

Conversions between different references (e.g. Mag North to True North) require a NavSatFix with the corresponding absolute pose.

Conversions involving UTM can receive a Int32 parameter that forces the use of a specific UTM zone instead of the default one.

The converter accepts several parameters that modify its behavior:

• magnetic_declination (double, radians, optional): If set, forces this value of magnetic declination.
• utm_grid_convergence (double, radians, optional): If set, forces this value of UTM grid convergence.
• magnetic_models_path (string, default "$PACKAGE/data/magnetic"): Path where WMM magnetic models can be found.
• magnetic_model (string, optional): If set, forces using the given WMM model instead of determining the proper one by year. Example value is “wmm2020”.
• utm_zone (int, optional): If set, forces using this UTM zone instead of determining the proper one.
• keep_utm_zone (bool, default true): If true, the first automatically determined UTM zone will be used for all future conversions.
• initial_lat (double, degrees, optional): If set, use this latitude before the first navsat pose is received.
• initial_lon (double, degrees, optional): If set, use this longitude before the first navsat pose is received.
• initial_alt (double, meters, optional): If set, use this altitude before the first navsat pose is received.

compass_conversions::UniversalAzimuthSubscriber

A message filter Subscriber that subscribes any of the supported azimuth representations ( Azimuth, QuaternionStamped, PoseWithCovarianceStamped, Imu, ) and converts it to Azimuth.

Some parameters might be needed for the conversion, and you can either supply them as arguments of the Subscriber, or they can be autodetected from the topic name (if it follows the output of topic names module in this package).

compass_conversions::CompassFilter

A message filter that converts incoming Azimuth messages to a specified parametrization. It can also handle a second input with NavSatFix messages to allow converting between different references. It also handles a third input with Int32 messages to allow forcing a specific UTM zone.

Example usage:

message_filters::Subscriber azimuthInput(...);
message_filters::Subscriber fixInput(...);
compass_conversions::CompassFilter filter(log, nullptr, azimuthInput, fixInput,
  compass_msgs::Azimuth::UNIT_RAD, compass_msgs::Azimuth::ORIENTATION_ENU,
  compass_msgs::Azimuth::REFERENCE_GEOGRAPHIC);
filter.registerCallback([](const compass_msgs::AzimuthConstPtr& msg) {
  ...  // Handle the data
});

compass_conversions/tf2_compass_msgs.h

When you include this file, tf2::convert() and similar functions will gain the ability to transform Azimuth messages.

compass_conversions/topic_names.h

Functions that assign topic names (or suffixes) to various parametrizations and representations of azimuths. These unique topic name suffixes can be used to add important metadata to messages that do not carry them inside.

Nodelets

compass_conversions/compass_transformer

This nodelet subscribes to incoming azimuth messages (using the UniversalAzimuthSubscriber described above), transforms them into a different parametrization (using CompassFilter), transforms them into a different TF frame (using tf2_compass_msgs.h) and publishes them in the desired parametrization and representation (possibly using CompassConverter to do the conversion).

The nodelet can also be launched as a standalone node using rosrun compass_conversions compass_transformer.

Subscribed topics:

• ~azimuth_in (compass_msgs/Azimuth or geometry_msgs/QuaternionStamped or geometry_msgs/PoseWithCovarianceStamped or sensor_msgs/Imu): The input azimuth. The name of the topic (if you remap it) can be used to autodetect some metadata for the conversion.
• fix (sensor_msgs/NavSatFix): GNSS fix messages that can be used to determine some parameters for the conversion.
• utm_zone (std_msgs/Int32): Optional messages with forced UTM zone.
• TF (only if ~target_frame is nonempty)

File truncated at 100 lines see the full file

Changelog for package compass_conversions

2.0.3 (2024-12-20)

2.0.2 (2024-12-20)

• Fixed README rendering on ROS Wiki.
• Contributors: Martin Pecka

2.0.1 (2024-12-12)

• Fixed license issues preventing bloom-release.
• Fixed documentation generation.
• Contributors: Martin Pecka

2.0.0 (2024-12-12)

• Restructured the repo, created compass_conversions, magnetic_model and magnetometer_pipeline packages.
• Contributors: Martin Pecka

1.0.3 (2023-07-12 15:43)

1.0.2 (2023-07-12 15:26)

1.0.1 (2023-06-19)