Add the configuration doc and an update script. (#172)

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.
+
+

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.

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()