From cd0ebbf536726a20285bdca4575283be87c2583c Mon Sep 17 00:00:00 2001 From: Wolfgang Hess Date: Wed, 21 Dec 2016 16:21:43 +0100 Subject: [PATCH] Add the configuration doc and an update script. (#172) --- docs/source/configuration.rst | 478 ++++++++++++++++++++++++++++ docs/source/index.rst | 2 + scripts/update_configuration_doc.py | 139 ++++++++ 3 files changed, 619 insertions(+) create mode 100644 docs/source/configuration.rst create mode 100755 scripts/update_configuration_doc.py diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst new file mode 100644 index 0000000..cde6d63 --- /dev/null +++ b/docs/source/configuration.rst @@ -0,0 +1,478 @@ +.. Copyright 2016 The Cartographer Authors + +.. Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + +============= +Configuration +============= + +.. DO NOT EDIT! This documentation is AUTOGENERATED, please edit .proto files as +.. needed and run scripts/update_configuration_doc.py. + +cartographer.common.proto.CeresSolverOptions +-------------------------------------------- + +bool use_nonmonotonic_steps + Configure the Ceres solver. See the Ceres documentation for more + information: https://code.google.com/p/ceres-solver/ + +int32 max_num_iterations + Not yet documented. + +int32 num_threads + Not yet documented. + + +cartographer.kalman_filter.proto.PoseTrackerOptions +--------------------------------------------------- + +double position_model_variance + Model variances depend linearly on time. + +double orientation_model_variance + Not yet documented. + +double velocity_model_variance + Not yet documented. + +double imu_gravity_time_constant + Time constant for the orientation moving average based on observed gravity + via linear acceleration. + +double imu_gravity_variance + Not yet documented. + +int32 num_odometry_states + Maximum number of previous odometry states to keep. + + +cartographer.mapping.proto.MapBuilderOptions +-------------------------------------------- + +bool use_trajectory_builder_2d + Not yet documented. + +mapping_2d.proto.LocalTrajectoryBuilderOptions trajectory_builder_2d_options + Not yet documented. + +bool use_trajectory_builder_3d + Not yet documented. + +mapping_3d.proto.LocalTrajectoryBuilderOptions trajectory_builder_3d_options + Not yet documented. + +int32 num_background_threads + Number of threads to use for background computations. + +SparsePoseGraphOptions sparse_pose_graph_options + Not yet documented. + + +cartographer.mapping.proto.SparsePoseGraphOptions +------------------------------------------------- + +int32 optimize_every_n_scans + Online loop closure: If positive, will run the loop closure while the map + is built. + +mapping.sparse_pose_graph.proto.ConstraintBuilderOptions constraint_builder_options + Options for the constraint builder. + +mapping.sparse_pose_graph.proto.OptimizationProblemOptions optimization_problem_options + Options for the optimization problem. + +int32 max_num_final_iterations + Number of iterations to use in 'optimization_problem_options' for the final + optimization. + +double global_sampling_ratio + Rate at which we sample a single trajectory's scans for global + localization. + + +cartographer.mapping.sparse_pose_graph.proto.ConstraintBuilderOptions +--------------------------------------------------------------------- + +double sampling_ratio + A constraint will be added if the proportion of added constraints to + potential constraints drops below this number. + +double max_constraint_distance + Threshold for poses to be considered near a submap. + +sensor.proto.AdaptiveVoxelFilterOptions adaptive_voxel_filter_options + Voxel filter used to compute a sparser point cloud for matching. + +double min_score + Threshold for the scan match score below which a match is not considered. + Low scores indicate that the scan and map do not look similar. + +double global_localization_min_score + Threshold below which global localizations are not trusted. + +double lower_covariance_eigenvalue_bound + Lower bound for covariance eigenvalues to limit the weight of matches. + +bool log_matches + If enabled, logs information of loop-closing constraints for debugging. + +mapping_2d.scan_matching.proto.FastCorrelativeScanMatcherOptions fast_correlative_scan_matcher_options + Options for the internally used scan matchers. + +mapping_2d.scan_matching.proto.CeresScanMatcherOptions ceres_scan_matcher_options + Not yet documented. + +mapping_3d.scan_matching.proto.FastCorrelativeScanMatcherOptions fast_correlative_scan_matcher_options_3d + Not yet documented. + +mapping_3d.scan_matching.proto.CeresScanMatcherOptions ceres_scan_matcher_options_3d + Not yet documented. + + +cartographer.mapping.sparse_pose_graph.proto.OptimizationProblemOptions +----------------------------------------------------------------------- + +double huber_scale + Scaling parameter for Huber loss function. + +double acceleration_weight + Scaling parameter for the IMU acceleration term. + +double rotation_weight + Scaling parameter for the IMU rotation term. + +double consecutive_scan_translation_penalty_factor + Penalty factors for changes to the relative pose between consecutive scans. + +double consecutive_scan_rotation_penalty_factor + Not yet documented. + +bool log_solver_summary + If true, the Ceres solver summary will be logged for every optimization. + +common.proto.CeresSolverOptions ceres_solver_options + Not yet documented. + + +cartographer.mapping_2d.proto.LaserFanInserterOptions +----------------------------------------------------- + +double hit_probability + Probability change for a hit (this will be converted to odds and therefore + must be greater than 0.5). + +double miss_probability + Probability change for a miss (this will be converted to odds and therefore + must be less than 0.5). + +bool insert_free_space + If 'false', free space will not change the probabilities in the occupancy + grid. + + +cartographer.mapping_2d.proto.LocalTrajectoryBuilderOptions +----------------------------------------------------------- + +float laser_min_range + Laser returns outside these ranges will be dropped. + +float laser_max_range + Not yet documented. + +float laser_min_z + Not yet documented. + +float laser_max_z + Not yet documented. + +float laser_missing_echo_ray_length + Laser returns beyond 'laser_max_range' will be inserted with this length as + empty space. + +float laser_voxel_filter_size + Voxel filter that gets applied to the horizontal laser immediately after + cropping. + +bool use_online_correlative_scan_matching + Whether to solve the online scan matching first using the correlative scan + matcher to generate a good starting point for Ceres. + +sensor.proto.AdaptiveVoxelFilterOptions adaptive_voxel_filter_options + Voxel filter used to compute a sparser point cloud for matching. + +scan_matching.proto.RealTimeCorrelativeScanMatcherOptions real_time_correlative_scan_matcher_options + Not yet documented. + +scan_matching.proto.CeresScanMatcherOptions ceres_scan_matcher_options + Not yet documented. + +mapping_3d.proto.MotionFilterOptions motion_filter_options + Not yet documented. + +double imu_gravity_time_constant + Time constant in seconds for the orientation moving average based on + observed gravity via the IMU. It should be chosen so that the error + 1. from acceleration measurements not due to gravity (which gets worse when + the constant is reduced) and + 2. from integration of angular velocities (which gets worse when the + constant is increased) is balanced. + +int32 num_odometry_states + Maximum number of previous odometry states to keep. + +mapping_2d.proto.SubmapsOptions submaps_options + Not yet documented. + +bool use_imu_data + True if IMU data should be expected and used. + + +cartographer.mapping_2d.proto.SubmapsOptions +-------------------------------------------- + +double resolution + Resolution of the map in meters. + +double half_length + Half the width/height of each submap, its "radius". + +int32 num_laser_fans + Number of scans before adding a new submap. Each submap will get twice the + number of scans inserted: First for initialization without being matched + against, then while being matched. + +bool output_debug_images + If enabled, submap%d.png images are written for debugging. + +LaserFanInserterOptions laser_fan_inserter_options + Not yet documented. + + +cartographer.mapping_2d.scan_matching.proto.CeresScanMatcherOptions +------------------------------------------------------------------- + +double occupied_space_weight + Scaling parameters for each cost functor. + +double translation_weight + Not yet documented. + +double rotation_weight + Not yet documented. + +double covariance_scale + Scale applied to the covariance estimate from Ceres. + +common.proto.CeresSolverOptions ceres_solver_options + Configure the Ceres solver. See the Ceres documentation for more + information: https://code.google.com/p/ceres-solver/ + + +cartographer.mapping_2d.scan_matching.proto.FastCorrelativeScanMatcherOptions +----------------------------------------------------------------------------- + +double linear_search_window + Minimum linear search window in which the best possible scan alignment + will be found. + +double angular_search_window + Minimum angular search window in which the best possible scan alignment + will be found. + +int32 branch_and_bound_depth + Number of precomputed grids to use. + + +cartographer.mapping_2d.scan_matching.proto.RealTimeCorrelativeScanMatcherOptions +--------------------------------------------------------------------------------- + +double linear_search_window + Minimum linear search window in which the best possible scan alignment + will be found. + +double angular_search_window + Minimum angular search window in which the best possible scan alignment + will be found. + +double translation_delta_cost_weight + Weights applied to each part of the score. + +double rotation_delta_cost_weight + Not yet documented. + + +cartographer.mapping_3d.proto.KalmanLocalTrajectoryBuilderOptions +----------------------------------------------------------------- + +bool use_online_correlative_scan_matching + Whether to solve the online scan matching first using the correlative scan + matcher to generate a good starting point for Ceres. + +mapping_2d.scan_matching.proto.RealTimeCorrelativeScanMatcherOptions real_time_correlative_scan_matcher_options + Not yet documented. + +kalman_filter.proto.PoseTrackerOptions pose_tracker_options + Not yet documented. + +double odometer_translational_variance + Not yet documented. + +double odometer_rotational_variance + Not yet documented. + + +cartographer.mapping_3d.proto.LaserFanInserterOptions +----------------------------------------------------- + +double hit_probability + Probability change for a hit (this will be converted to odds and therefore + must be greater than 0.5). + +double miss_probability + Probability change for a miss (this will be converted to odds and therefore + must be less than 0.5). + +int32 num_free_space_voxels + Up to how many free space voxels are updated for scan matching. + 0 disables free space. + + +cartographer.mapping_3d.proto.LocalTrajectoryBuilderOptions +----------------------------------------------------------- + + +cartographer.mapping_3d.proto.MotionFilterOptions +------------------------------------------------- + +double max_time_seconds + Threshold above which a new scan is inserted based on time. + +double max_distance_meters + Threshold above which a new scan is inserted based on linear motion. + +double max_angle_radians + Threshold above which a new scan is inserted based on rotational motion. + + +cartographer.mapping_3d.proto.OptimizingLocalTrajectoryBuilderOptions +--------------------------------------------------------------------- + +double high_resolution_grid_weight + Not yet documented. + +double low_resolution_grid_weight + Not yet documented. + +double velocity_weight + Not yet documented. + +double translation_weight + Not yet documented. + +double rotation_weight + Not yet documented. + +double odometry_translation_weight + Not yet documented. + +double odometry_rotation_weight + Not yet documented. + + +cartographer.mapping_3d.proto.SubmapsOptions +-------------------------------------------- + +double high_resolution + Resolution of the 'high_resolution' map in meters used for local SLAM and + loop closure. + +double high_resolution_max_range + Maximum range to filter the point cloud to before insertion into the + 'high_resolution' map. + +double low_resolution + Resolution of the 'low_resolution' version of the map in meters used for + local SLAM only. + +int32 num_laser_fans + Number of scans before adding a new submap. Each submap will get twice the + number of scans inserted: First for initialization without being matched + against, then while being matched. + +LaserFanInserterOptions laser_fan_inserter_options + Not yet documented. + + +cartographer.mapping_3d.scan_matching.proto.CeresScanMatcherOptions +------------------------------------------------------------------- + +double translation_weight + Scaling parameters for each cost functor. + +double rotation_weight + Not yet documented. + +double covariance_scale + Scale applied to the covariance estimate from Ceres. + +bool only_optimize_yaw + Whether only to allow changes to yaw, keeping roll/pitch constant. + +common.proto.CeresSolverOptions ceres_solver_options + Configure the Ceres solver. See the Ceres documentation for more + information: https://code.google.com/p/ceres-solver/ + + +cartographer.mapping_3d.scan_matching.proto.FastCorrelativeScanMatcherOptions +----------------------------------------------------------------------------- + +int32 branch_and_bound_depth + Number of precomputed grids to use. + +int32 full_resolution_depth + Number of full resolution grids to use, additional grids will reduce the + resolution by half each. + +int32 rotational_histogram_size + Number of histogram buckets for the rotational scan matcher. + +double min_rotational_score + Minimum score for the rotational scan matcher. + +double linear_xy_search_window + Linear search window in the plane orthogonal to gravity in which the best + possible scan alignment will be found. + +double linear_z_search_window + Linear search window in the gravity direction in which the best possible + scan alignment will be found. + +double angular_search_window + Minimum angular search window in which the best possible scan alignment + will be found. + + +cartographer.sensor.proto.AdaptiveVoxelFilterOptions +---------------------------------------------------- + +float max_length + 'max_length' of a voxel edge. + +float min_num_points + If there are more points and not at least 'min_num_points' remain, the + voxel length is reduced trying to get this minimum number of points. + +float max_range + Points further away from the origin are removed. + + diff --git a/docs/source/index.rst b/docs/source/index.rst index a25917b..85b8904 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -20,6 +20,8 @@ Cartographer :maxdepth: 2 :hidden: + configuration + `Cartographer`_ is a system that provides real-time simultaneous localization and mapping (`SLAM`_) in 2D and 3D across multiple platforms and sensor configurations. diff --git a/scripts/update_configuration_doc.py b/scripts/update_configuration_doc.py new file mode 100755 index 0000000..c20de12 --- /dev/null +++ b/scripts/update_configuration_doc.py @@ -0,0 +1,139 @@ +#!/usr/bin/python3 +# -*- coding: utf-8 -*- + +# Copyright 2016 The Cartographer Authors +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +"""A dumb configuration.rst generator that relies on source comments.""" + +import io +import os + +TARGET = 'docs/source/configuration.rst' +ROOT = 'cartographer' +PREFIX = """.. Copyright 2016 The Cartographer Authors + +.. Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + +============= +Configuration +============= + +.. DO NOT EDIT! This documentation is AUTOGENERATED, please edit .proto files as +.. needed and run scripts/update_configuration_doc.py. + +""" +SUFFIX = """ +""" +NODOC = 'Not yet documented.' + +def GenerateDocumentation(output_dict, proto_file_name): + copyright = True + message = None + content = []; + package = None + multiline = None + print("Reading '%s'..." % proto_file_name) + for line in io.open(proto_file_name, encoding='UTF-8'): + line = line.strip() + if copyright: + if not line.startswith('//'): + copyright = False + continue + if package is None: + if line.startswith('package'): + assert line[-1] == ';' + package = line[7:-1].strip() + continue + if line.startswith('//'): + content_line = line[2:].strip() + if not content_line.startswith('NEXT ID:'): + content.append(content_line) + continue + if message is None: + if line.startswith('message') and line.endswith('Options {'): + message = package + '.' + line[7:-1].strip() + print(" Found '%s'." % message) + assert message not in output_dict + message_list = [message, '=' * len(message), ''] + output_dict[message] = message_list + message_list.extend(content) + content = [] + continue + elif line.endswith('}'): + message_list.extend(content) + content = [] + message_list = None + message = None + else: + assert not line.startswith('required') + if multiline is None: + if line.startswith('optional'): + multiline = line + else: + continue + else: + multiline += ' ' + line + if not multiline.endswith(';'): + continue + assert len(multiline) < 200 + option = multiline[8:-1].strip().rstrip('0123456789').strip() + assert option.endswith('=') + option = option[:-1].strip(); + print(" Option '%s'." % option) + multiline = None + message_list.append(option) + if len(content) == 0: + content.append(NODOC) + for option_description_line in content: + message_list.append(' ' + option_description_line) + content = [] + message_list.append('') + + +def GenerateDocumentationRecursively(output_file, root): + """Recursively generates documentation, sorts and writes it.""" + output_dict = {} + for root, dirs, files in os.walk(root): + for name in files: + if name.endswith('.proto'): + path = os.path.join(root, name) + assert not os.path.islink(path) + GenerateDocumentation(output_dict, path) + + output = ['\n'.join(doc) for key, doc in sorted(list(output_dict.items()))] + print('\n\n'.join(output), file=output_file) + + +def main(): + assert not os.path.islink(TARGET) and os.path.isfile(TARGET) + assert not os.path.islink(ROOT) and os.path.isdir(ROOT) + output_file = io.open(TARGET, mode='w', encoding='UTF-8', newline='\n') + output_file.write(PREFIX) + GenerateDocumentationRecursively(output_file, ROOT) + output_file.write(SUFFIX) + output_file.close() + + +if __name__ == "__main__": + main()