From c10aa878e2ff1ba14926415e1ee717cefbad1c7b Mon Sep 17 00:00:00 2001 From: Martin Pecka Date: Thu, 12 Dec 2024 23:43:47 +0100 Subject: [PATCH] Fixed README rendering on ROS Wiki. --- compass_conversions/README.md | 35 ++++++++----------- compass_msgs/README.md | 4 +-- magnetometer_compass/README.md | 62 +++++++++++++-------------------- magnetometer_pipeline/README.md | 12 +++---- 4 files changed, 46 insertions(+), 67 deletions(-) diff --git a/compass_conversions/README.md b/compass_conversions/README.md index 77c4c9a..575d2cd 100644 --- a/compass_conversions/README.md +++ b/compass_conversions/README.md @@ -26,10 +26,10 @@ The converter accepts several parameters that modify its behavior: - `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". + 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. + 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. @@ -39,7 +39,7 @@ The converter accepts several parameters that modify its behavior: A [message filter](https://wiki.ros.org/message_filters) `Subscriber` that subscribes any of the supported azimuth representations ( [Azimuth](https://docs.ros.org/en/api/compass_msgs/html/msg/Azimuth.html), -[QuaternionsStamped](https://docs.ros.org/en/api/geometry_msgs/html/msg/QuaternionStamped.html), +[QuaternionStamped](https://docs.ros.org/en/api/geometry_msgs/html/msg/QuaternionStamped.html), [PoseWithCovarianceStamped](https://docs.ros.org/en/api/geometry_msgs/html/msg/PoseWithCovarianceStamped.html), [Imu](https://docs.ros.org/en/api/sensor_msgs/html/msg/Imu.html), ) and converts it to [Azimuth](https://docs.ros.org/en/api/compass_msgs/html/msg/Azimuth.html). @@ -101,38 +101,31 @@ The nodelet can also be launched as a standalone node using `rosrun compass_conv #### Published topics: - `~azimuth_out` or `~azimuth_out/SUFFIX`: The transformed azimuth. If `~target_append_suffix` is true, the variant - with topic name suffix will be used (e.g. `~azimuth_out/mag/enu/deg`). - The type of the published message is determined by `~target_type`. + with topic name suffix will be used (e.g. `~azimuth_out/mag/enu/deg`). The type of the published message is + determined by `~target_type`. #### Parameters: - `~queue_size` (int, default 10): Queue size for the subscribers and publishers. - `~target_unit` (str, 'deg' or 'rad', default: no change): Angular unit to be used in the transformed messages. - `~target_orientation` (str, 'enu' or 'ned', default: no change): ENU or NED orientation to be used in the - transformed messages. + transformed messages. - `~target_reference` (str, 'magnetic', 'geographic' or 'UTM', default: no change): North reference to be used in the - transformed messages. + transformed messages. - `~target_type` (str, 'azimuth', 'quaternion', 'pose' or 'imu', default 'azimuth'): The Type of output messages. - `~target_append_suffix` (bool, default false): If true, the output topic will be suffixed with a metadata-based - string. + string. - `~target_frame` (str, default: no change): TF frame to transform the messages to. Please note that frames that are - too "titled" from gravity will not make much sense. + too "titled" from gravity will not make much sense. - `~subscribe_fix` (bool, default true): Whether to subscribe `fix` topic. In some cases, you don't need it. - `~subscribe_utm` (bool, default true): Whether to subscribe `utm_zone` topic. It is fully optional. - `~input_orientation` (str, 'enu' or 'ned', default: unspecified): ENU or NED orientation to be used to interpret - input messages (in case orientation cannot be - derived either from message contents or topic - name). + input messages (in case orientation cannot be derived either from message contents or topic name). - `~input_reference` (str, 'magnetic', 'geographic' or 'UTM', default: no change): North reference to be used to - interpret input messages (in case - reference cannot be derived either - from message contents or topic - name). + interpret input messages (in case reference cannot be derived either from message contents or topic name). - `~input_variance` (double, optional, rad^2): If specified, this variance will be used in the output messages - if variance cannot be determined from the input messages (e.g. for - `QuaternionStamped`). + if variance cannot be determined from the input messages (e.g. for `QuaternionStamped`). - `~strict` (bool, default true): If true, conversions between magnetic and geographic North will fail if the used - magnetic model is used outside its declared bounds of validity (mostly year and - altitude). + magnetic model is used outside its declared bounds of validity (mostly year and altitude). - All parameters consumed by `CompassConverter` (most interesting are `initial_lat`, `initial_lon`, that can relieve - this nodelet from subscribing `fix` topic, if you know the approximate coordinates in advance). \ No newline at end of file + this nodelet from subscribing `fix` topic, if you know the approximate coordinates in advance). \ No newline at end of file diff --git a/compass_msgs/README.md b/compass_msgs/README.md index e705c4b..a76bf02 100644 --- a/compass_msgs/README.md +++ b/compass_msgs/README.md @@ -16,9 +16,9 @@ meaning of each message: - `UNIT_RAD`: `azimuth` field is in radians and `variance` in rad^2 - `orientation` - `ORIENTATION_ENU`: The azimuth is measured in East-North-Up frame. Azimuth 0 thus points to the East and increases - counter-clockwise. + counter-clockwise. - `ORIENTATION_NED`: The azimuth is measured in North-East-Down frame. Azimuth 0 thus points to the North and - increases clockwise. + increases clockwise. - `reference`: Which North reference is used. - `REFERENCE_MAGNETIC`: Magnetic North. - `REFERENCE_GEOGRAPHIC`: Geographic North. diff --git a/magnetometer_compass/README.md b/magnetometer_compass/README.md index e9c48af..b8cffb2 100644 --- a/magnetometer_compass/README.md +++ b/magnetometer_compass/README.md @@ -17,14 +17,14 @@ So that you know what output is the right for you. ### Orientation - NED (North-East-Down): Azimuth will be 0 pointing to north, and increases clockwise. This is consistent with the - azimuth used in cartography and by tourists. + azimuth used in cartography and by tourists. - ENU (East-North-Up): Azimuth will be 0 pointing to east, and increases counter-clockwise. This is consistent with - REP-103 and robot_localization package. + REP-103 and robot_localization package. ### References for north - Magnetic: points towards the magnetic north of Earth (travels in time). - Geographic ("true"): points towards the geographic Earth (i.e. the WGS84 North Pole). It is static in time. - UTM: points in the north direction on the cartesian UTM grid (similar to Geographic, but it can slightly diverge - at the edges of UTM maps). You probably want this azimuth reference for navigation tasks in UTM coordinates. + at the edges of UTM maps). You probably want this azimuth reference for navigation tasks in UTM coordinates. Magnetic azimuth can be computed directly from the magnetometer and IMU orientation. To compute the other two references, you need to provide the latitude, longitude, altitude and time in addition to the magnetometer and @@ -42,22 +42,20 @@ may be required to re-estimate the bias from time to time even during runtime. ### Subscribed topics - `imu/data` (`sensor_msgs/Imu`): Output from an IMU or an orientation filtering algorithm. It should have valid - contents of `orientation` and at least roll and pitch should be estimated as - well as possible (relative to the gravity vector). These messages should come at - the same rate as the magnetometer data (or faster). + contents of `orientation` and at least roll and pitch should be estimated as well as possible (relative to the + gravity vector). These messages should come at the same rate as the magnetometer data (or faster). - `imu/mag` (`sensor_msgs/MagneticField`): 3-axis magnetometer raw measurements (bias not removed) (disabled by param - `~subscribe_mag_unbiased`). + `~subscribe_mag_unbiased`). - `imu/mag_bias` (`sensor_msgs/MagneticField`): Bias of the magnetometer. This value will be subtracted from the - incoming magnetometer measurements. Messages on this topic do not - need to come repeatedly if the bias does not change. Disabled by - param `~subscribe_mag_unbiased`. + incoming magnetometer measurements. Messages on this topic do not need to come repeatedly if the bias does not + change. Disabled by param `~subscribe_mag_unbiased`. - `imu/mag_unbiased` (`sensor_msgs/MagneticField`): 3-axis magnetometer unbiased measurements (enabled by param - `~subscribe_mag_unbiased`). + `~subscribe_mag_unbiased`). - `gps/fix` (`sensor_msgs/NavSatFix`, optional): GPS fix messages from which the latitude, longitude, altitude and - current year can be read. These are further used to compute - magnetic declination and UTM grid convergence factor if requested. + current year can be read. These are further used to compute magnetic declination and UTM grid convergence factor if + requested. - TF: This node requires a (usually static) transform between `~frame` and the frame ID of the IMU and magnetometer - messages. + messages. ### Published topics (see above for explanation) - `imu/mag_unbiased` (`sensor_msgs/MagneticField`, enabled by param `~publish_mag_unbiased`, off by default): @@ -135,7 +133,7 @@ may be required to re-estimate the bias from time to time even during runtime. Such configuration is invalid and the node will not start. - `~frame` (string, default `base_link`): Frame into which the IMU and magnetometer data should be transformed. - `~low_pass_ratio` (double, default 0.95): The azimuth is filtered with a low-pass filter. This sets its - aggressivity (0 means raw measurements, 1 means no updates). + aggressivity (0 means raw measurements, 1 means no updates). - `~initial_mag_bias_x` (double, no default, optional): Magnetometer bias in the X axis. - `~initial_mag_bias_y` (double, no default, optional): Magnetometer bias in the Y axis. - `~initial_mag_bias_z` (double, no default, optional): Magnetometer bias in the Z axis. @@ -146,9 +144,8 @@ may be required to re-estimate the bias from time to time even during runtime. - `~initial_alt` (double, default 0): Altitude in meters (it is usually okay to omit it and use the default). - `~initial_year` (int, no default, optional): If set, overrides the current time for declination computation. - `~magnetic_declination` (double, no default, optional, radians): If this parameter is set, the magnetic models are - ignored and this value for declination is forced. - This can be useful either if you know the value - in advance or in simulation. + ignored and this value for declination is forced. This can be useful either if you know the value in advance or in + simulation. - `~utm_grid_convergence` (double, no default, optional, radians): If set, forces this value of UTM grid convergence. - `~magnetic_models_path` (string, defaults to a pre-installed directory): Path where WMM magnetic models can be found. If set to empty string, the models will be searched in a default folder of GeographicLib. Environment variables @@ -168,14 +165,12 @@ This node visualizes `Azimuth` messages in RViz converting them to a pose. ### Subscribed topics - `~azimuth` (multiple types supported): The azimuth to visualize. Any type supported by compass_conversions package - can be used: `compass_msgs/Azimuth`, `geometry_msgs/Quaternion`, - `geometry_msgs/PoseWithCovarianceStamped` or `sensor_msgs/Imu`. If other - types than `compass_msgs/Azimuth` are used, either the resolved topic name - must contain the azimuth type identification (e.g. end with `mag/enu/imu`), - or you must provide parameters `~input_reference` and `~input_orientation`. + can be used: `compass_msgs/Azimuth`, `geometry_msgs/Quaternion`, `geometry_msgs/PoseWithCovarianceStamped` or + `sensor_msgs/Imu`. If other types than `compass_msgs/Azimuth` are used, either the resolved topic name must contain + the azimuth type identification (e.g. end with `mag/enu/imu`), or you must provide parameters `~input_reference` and + `~input_orientation`. - `gps/fix` (`sensor_msgs/NavSatFix`, optional): GPS fix messages from which the latitude, longitude, altitude and - current year can be read. These are further used to compute - magnetic declination and UTM grid convergence factor. + current year can be read. These are further used to compute magnetic declination and UTM grid convergence factor. - `utm_zone` (`std_msgs/Int32`, optional): Optional UTM zone updates. ### Published topics @@ -191,22 +186,15 @@ This node visualizes `Azimuth` messages in RViz converting them to a pose. If set to empty string, the models will be searched in a default folder of GeographicLib. Environment variables `GEOGRAPHICLIB_MAGNETIC_PATH` or `GEOGRAPHICLIB_DATA` influence the location of this folder. - `magnetic_model` (string, optional): If set, forces using the given WMM model instead of determining the proper - one by year. Example value is "wmm2020". + 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 determined UTM zone will be used for all future - conversions. +- `keep_utm_zone` (bool, default true): If true, the first 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. - `~input_orientation` (str, 'enu' or 'ned', default: unspecified): ENU or NED orientation to be used to interpret - input messages (in case orientation cannot be - derived either from message contents or topic - name). + input messages (in case orientation cannot be derived either from message contents or topic name). - `~input_reference` (str, 'magnetic', 'geographic' or 'UTM', default: no change): North reference to be used to - interpret input messages (in case - reference cannot be derived either - from message contents or topic - name). + interpret input messages (in case reference cannot be derived either from message contents or topic name). - `~input_variance` (double, optional, rad^2): If specified, this variance will be used in the output messages - if variance cannot be determined from the input messages (e.g. for - `QuaternionStamped`). + if variance cannot be determined from the input messages (e.g. for `QuaternionStamped`). diff --git a/magnetometer_pipeline/README.md b/magnetometer_pipeline/README.md index a7df18b..15838fe 100644 --- a/magnetometer_pipeline/README.md +++ b/magnetometer_pipeline/README.md @@ -15,10 +15,8 @@ may be required to re-estimate the bias from time to time even during runtime. ### Subscribed topics - `imu/mag` (`sensor_msgs/MagneticField`): 3-axis magnetometer measurements (bias not removed). - `imu/mag_bias` (`sensor_msgs/MagneticField`): Bias of the magnetometer. This value will be subtracted from the - incoming magnetometer measurements. Messages on this topic do not - need to come repeatedly if the bias does not change. The - `magnetic_field_covariance` field can be "misused" to carry a 3x3 - bias scaling matrix. + incoming magnetometer measurements. Messages on this topic do not need to come repeatedly if the bias does not + change. The `magnetic_field_covariance` field can be "misused" to carry a 3x3 bias scaling matrix. ### Published topics (see above for explanation) - `imu/mag_unbiased` (`sensor_msgs/MagneticField`): The magnetic field measurement with bias removed. @@ -48,20 +46,20 @@ Magnetometer bias estimation node. ### Provided services - `calibrate_magnetometer` (`std_srvs/Trigger`): Call this service to start bias estimation. Rotate the robot in as much - axes as possible during the calibration. + axes as possible during the calibration. ### Parameters - `~measuring_time` (double, default 30 s): How long should the bias estimation phase be. - `~2d_mode` (bool, default true): If true, the calibration expects motion in only 2 axes instead of 3. - `~2d_mode_ignore_axis` ('X', 'Y' or 'Z', default autodetect): If you know which magnetometer local axis will not be - used in 2D calibration, you can set it here. + used in 2D calibration, you can set it here. - `~load_from_params` (bool, default false): If true, initial bias estimate will be loaded from ROS params. - `magnetometer_bias_x` (double, default 0.0): The initial bias estimate for X axis (if `~load_from_params` is true). - `magnetometer_bias_y` (double, default 0.0): The initial bias estimate for Y axis (if `~load_from_params` is true). - `magnetometer_bias_z` (double, default 0.0): The initial bias estimate for Z axis (if `~load_from_params` is true). - `~load_from_file` (bool, default true): If true, the initial bias estimate will be loaded from - `~/.ros/magnetometer_calib.yaml`. + `~/.ros/magnetometer_calib.yaml`. - `~calibration_file_path` (str, default `~/.ros/magnetometer_calib.yaml`): Path to the calibration file. - `~save_to_file` (bool, default true): If true, the last estimated bias will be saved to the calibration file.