From c866707013eae921836bbb33da56662be36bbd75 Mon Sep 17 00:00:00 2001 From: Wolfgang Hess Date: Wed, 15 Nov 2017 14:17:33 +0100 Subject: [PATCH] Fix the configuration documentation script. (#679) Fixes #652. Now also includes documentation for one option that was "repeated" and not "optional". --- docs/source/configuration.rst | 148 +++++++++++++++------------- scripts/update_configuration_doc.py | 21 ++-- 2 files changed, 89 insertions(+), 80 deletions(-) diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index bc24457..82439e8 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -33,70 +33,8 @@ int32 num_threads Not yet documented. -cartographer.mapping.proto.MapBuilderOptions -============================================ - -bool use_trajectory_builder_2d - Not yet documented. - -bool use_trajectory_builder_3d - Not yet documented. - -int32 num_background_threads - Number of threads to use for background computations. - -cartographer.mapping.proto.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. - -cartographer.mapping.sparse_pose_graph.proto.ConstraintBuilderOptions constraint_builder_options - Options for the constraint builder. - -double matcher_translation_weight - Weight used in the optimization problem for the translational component of - non-loop-closure scan matcher constraints. - -double matcher_rotation_weight - Weight used in the optimization problem for the rotational component of - non-loop-closure scan matcher constraints. - -cartographer.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. - -bool log_residual_histograms - Whether to output histograms for the pose residuals. - - -cartographer.mapping.proto.TrajectoryBuilderOptions -=================================================== - -cartographer.mapping_2d.proto.LocalTrajectoryBuilderOptions trajectory_builder_2d_options - Not yet documented. - -cartographer.mapping_3d.proto.LocalTrajectoryBuilderOptions trajectory_builder_3d_options - Not yet documented. - -bool pure_localization - Not yet documented. - - -cartographer.mapping.sparse_pose_graph.proto.ConstraintBuilderOptions -===================================================================== +cartographer.mapping.pose_graph.proto.ConstraintBuilderOptions +============================================================== double sampling_ratio A constraint will be added if the proportion of added constraints to @@ -136,8 +74,8 @@ cartographer.mapping_3d.scan_matching.proto.CeresScanMatcherOptions ceres_scan_m Not yet documented. -cartographer.mapping.sparse_pose_graph.proto.OptimizationProblemOptions -======================================================================= +cartographer.mapping.pose_graph.proto.OptimizationProblemOptions +================================================================ double huber_scale Scaling parameter for Huber loss function. @@ -167,6 +105,73 @@ cartographer.common.proto.CeresSolverOptions ceres_solver_options Not yet documented. +cartographer.mapping.proto.MapBuilderOptions +============================================ + +bool use_trajectory_builder_2d + Not yet documented. + +bool use_trajectory_builder_3d + Not yet documented. + +int32 num_background_threads + Number of threads to use for background computations. + +cartographer.mapping.proto.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. + +cartographer.mapping.pose_graph.proto.ConstraintBuilderOptions constraint_builder_options + Options for the constraint builder. + +double matcher_translation_weight + Weight used in the optimization problem for the translational component of + non-loop-closure scan matcher constraints. + +double matcher_rotation_weight + Weight used in the optimization problem for the rotational component of + non-loop-closure scan matcher constraints. + +cartographer.mapping.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. + +bool log_residual_histograms + Whether to output histograms for the pose residuals. + +double global_constraint_search_after_n_seconds + If for the duration specified by this option no global contraint has been + added between two trajectories, loop closure searches will be performed + globally rather than in a smaller search window. + + +cartographer.mapping.proto.TrajectoryBuilderOptions +=================================================== + +cartographer.mapping_2d.proto.LocalTrajectoryBuilderOptions trajectory_builder_2d_options + Not yet documented. + +cartographer.mapping_3d.proto.LocalTrajectoryBuilderOptions trajectory_builder_3d_options + Not yet documented. + +bool pure_localization + Not yet documented. + + cartographer.mapping_2d.proto.LocalTrajectoryBuilderOptions =========================================================== @@ -353,6 +358,9 @@ double imu_gravity_time_constant 2. from integration of angular velocities (which gets worse when the constant is increased) is balanced. +int32 rotational_histogram_size + Number of histogram buckets for the rotational scan matcher. + cartographer.mapping_3d.proto.SubmapsOptions submaps_options Not yet documented. @@ -413,9 +421,12 @@ cartographer.mapping_3d.proto.RangeDataInserterOptions range_data_inserter_optio cartographer.mapping_3d.scan_matching.proto.CeresScanMatcherOptions =================================================================== -double translation_weight +double occupied_space_weight Scaling parameters for each cost functor. +double translation_weight + Not yet documented. + double rotation_weight Not yet documented. @@ -437,9 +448,6 @@ 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. diff --git a/scripts/update_configuration_doc.py b/scripts/update_configuration_doc.py index 9c52c59..920c466 100755 --- a/scripts/update_configuration_doc.py +++ b/scripts/update_configuration_doc.py @@ -103,7 +103,7 @@ def ParseProtoFile(proto_file): # We capture the contents of this message. option_comments = [] - multiline = None + multiline = '' for line in line_iter: line = line.strip() if '}' in line: @@ -116,21 +116,17 @@ def ParseProtoFile(proto_file): option_comments.append(comment) else: assert not line.startswith('required') - if multiline is None: - if line.startswith('optional'): - multiline = line - else: - continue - else: - multiline += ' ' + line + multiline += ' ' + line if not multiline.endswith(';'): continue assert len(multiline) < 200 - option = multiline[8:-1].strip().rstrip('0123456789').strip() + option = multiline[:-1].strip().rstrip('0123456789').strip() assert option.endswith('=') + if option.startswith('repeated'): + option = option[8:] option_type, option_name = option[:-1].strip().split(); print(" Option '%s'." % option_name) - multiline = None + multiline = '' message.AddOption(option_type, option_name, option_comments) option_comments = [] @@ -186,6 +182,11 @@ def GenerateDocumentation(output_file, root): content.extend(preceding_comments) content.append('') for option_type, option_name, option_comments in message.options: + # TODO(whess): For now we exclude InitialTrajectoryPose from the + # documentation. It is documented itself (since it has no Options suffix) + # and is not parsed from the Lua files. + if option_type in ('InitialTrajectoryPose',): + continue content.append( resolver.Resolve(option_type, message.package) + ' ' + option_name) if not option_comments: