[SymForce-External] Misc docs, CMake, and packaging fixes

- CMake now fails if reading the version or generating the manifest
  fails
- Fixed skymarshal package classifiers
- Fixes #136
- Fixes broken link to paper and broken anchors in the README
- Fixes #141
- Clean up sidebar (no redundant link to home, bigger section titles)
- Consolidate tutorial symlinks into one symlink to a
  notebooks/tutorials directory
- Add READMEs for examples, do some cleanup there
- Rename 2d triangulation example to 2d localization, since I think
  that's more fitting?

I've gone ahead and republished the docs with the stylesheet fixes here, since that's just an immediate improvement IMO

Closes #148

GitOrigin-RevId: a4278b2638efa1dc8a0d2f49cce04df0428b180d

Author: aaron-skydio

CMakeLists.txt

@@ -191,8 +191,16 @@ else()
   execute_process(
     COMMAND ${SYMFORCE_PYTHON} -c "from _version import version; print(version, end='')"
     WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}/symforce
+    RESULT_VARIABLE STATUS
     OUTPUT_VARIABLE SYMFORCE_VERSION
+    ERROR_VARIABLE SYMFORCE_VERSION_STDERR
   )
+  if(STATUS AND NOT STATUS EQUAL 0)
+    message(FATAL_ERROR
+      "Failed getting symforce version with exit code ${STATUS} and output ${SYMFORCE_VERSION}, stderr ${SYMFORCE_VERSION_STDERR}"
+    )
+  endif()
+
   file(WRITE
     ${CMAKE_CURRENT_BINARY_DIR}/lcmtypes/python2.7/setup.py
     "
@@ -290,7 +298,16 @@ if(SYMFORCE_GENERATE_MANIFEST)
                                 --binary_output_dir "${CMAKE_BINARY_DIR}"
                                 # TODO(aaron): Put this somewhere smarter
                                 --manifest_path ${CMAKE_CURRENT_SOURCE_DIR}/build/manifest.json
+      RESULT_VARIABLE STATUS
+      OUTPUT_VARIABLE GENERATE_MANIFEST_OUTPUT
+      ERROR_VARIABLE GENERATE_MANIFEST_OUTPUT
     )
+
+    if(STATUS AND NOT STATUS EQUAL 0)
+      message(FATAL_ERROR
+        "Failed generating manifest with exit code ${STATUS} and output ${GENERATE_MANIFEST_OUTPUT}"
+      )
+    endif()
   endfunction()
 
   generate_manifest()

Makefile

@@ -168,7 +168,7 @@ PY_EXTENSION_MODULE_PATH?=$(BUILD_DIR)/pybind
 
 docs_html: docs_apidoc
 	export PYTHONPATH=$(PY_EXTENSION_MODULE_PATH):$(PYTHONPATH); \
-	SYMFORCE_LOGLEVEL=WARNING $(PYTHON) -m sphinx -b html docs $(DOCS_DIR) -j $$(nproc)
+	SYMFORCE_LOGLEVEL=WARNING $(PYTHON) -m sphinx -b html docs $(DOCS_DIR) -j auto
 	mkdir $(DOCS_DIR)/docs
 	ln -s ../_static $(DOCS_DIR)/docs/static
 

README.md

@@ -45,7 +45,7 @@ SymForce is developed and maintained by [Skydio](https://skydio.com/). It is use
  + Embedded-friendly C++ generation of templated Eigen code with zero dynamic memory allocation
  + Highly performant, modular, tested, and extensible code
 
-### Read the paper: https://arxiv.org/abs/2204.07889
+### Read the paper: <a href="https://arxiv.org/abs/2204.07889">https://arxiv.org/abs/2204.07889</a>
 
 SymForce was published to [RSS 2022](https://roboticsconference.org/). Please cite it as follows:
 
@@ -73,7 +73,7 @@ Verify the installation in Python:
 >>> geo.Rot3()
 ```
 
-This installs pre-compiled C++ components of SymForce on Linux and Mac using pip wheels, but does not include C++ headers. If you want to compile against C++ SymForce types (like `sym::Optimizer`), you currently need to [build from source](#build-from-source).
+This installs pre-compiled C++ components of SymForce on Linux and Mac using pip wheels, but does not include C++ headers. If you want to compile against C++ SymForce types (like `sym::Optimizer`), you currently need to <a href="#build-from-source">build from source</a>.
 
 # Tutorial
 
@@ -86,7 +86,7 @@ The robot measures:
 
 The robot's heading angle is defined counter-clockwise from the x-axis, and its relative bearing measurements are defined from the robot's forward direction:
 
-<img alt="Robot 2D Triangulation Figure" src="docs/static/images/robot_2d_triangulation/robot_2d_triangulation_figure.png" width="350px"/>
+<img alt="Robot 2D Localization Figure" src="docs/static/images/robot_2d_localization/problem_setup.png" width="350px"/>
 
 ## Explore the math
 
@@ -228,7 +228,7 @@ for i in range(num_poses - 1):
 
 Here is a visualization of the structure of this factor graph:
 
-<img alt="Robot 2D Triangulation Factor Graph" src="docs/static/images/robot_2d_triangulation/robot_2d_triangulation_factor_graph.png" width="600px"/>
+<img alt="Robot 2D Localization Factor Graph" src="docs/static/images/robot_2d_localization/factor_graph.png" width="600px"/>
 
 ## Solve the problem
 
@@ -271,12 +271,12 @@ Let's visualize what the optimizer did. The orange circles represent the fixed l
 circles represent the robot, and the dotted lines represent the bearing measurements.
 
 ```python
-from symforce.examples.robot_2d_triangulation.plotting import plot_solution
+from symforce.examples.robot_2d_localization.plotting import plot_solution
 plot_solution(optimizer, result)
 ```
-<img alt="Robot 2D Triangulation Solution" src="docs/static/images/robot_2d_triangulation/robot_2d_triangulation_iterations.gif" width="600px"/>
+<img alt="Robot 2D Localization Solution" src="docs/static/images/robot_2d_localization/iterations.gif" width="600px"/>
 
-All of the code for this example can also be found in `symforce/examples/robot_2d_triangulation`.
+All of the code for this example can also be found in `symforce/examples/robot_2d_localization`.
 
 ## Symbolic vs Numerical Types
 
@@ -520,7 +520,7 @@ To learn more, visit the SymForce tutorials [here](https://symforce.org/#guides)
 
 # Build from Source
 
-SymForce requires Python 3.8 or later. We strongly suggest creating a virtual python environment.
+SymForce requires Python 3.8 or later. The build is currently tested on Linux and macOS, SymForce on Windows is untested (see [#145](https://github.com/symforce-org/symforce/issues/145)).  We strongly suggest creating a virtual python environment.
 
 Install the `gmp` package with one of:
 ```bash
@@ -540,7 +540,7 @@ The recommended way to build and install SymForce if you only plan on making Pyt
 pip install -e .
 ```
 
-This will build the C++ components of SymForce, but you won't be able to run `pip install -e .` repeatedly if you need to rebuild C++ code.  If you're changing C++ code and rebuilding, you should build with CMake directly as described [below](#build-with-cmake).
+This will build the C++ components of SymForce, but you won't be able to run `pip install -e .` repeatedly if you need to rebuild C++ code.  If you're changing C++ code and rebuilding, you should build with CMake directly as described <a href="#build-with-cmake">below</a>.
 
 `pip install .` will not install pinned versions of SymForce's dependencies, it'll install any compatible versions.  It also won't install all packages required to run all of the SymForce tests and build all of the targets (e.g. building the docs or running the linters).  If you want all packages required for that, you should `pip install .[dev]` instead (or one of the other groups of extra requirements in our `setup.py`).  If you additionally want pinned versions of our dependencies, which are the exact versions guaranteed by CI to pass all of our tests, you can install them from `pip install -r dev_requirements.txt`.
 

docs/conf.py

@@ -59,6 +59,10 @@
     "myst_parser",
 ]
 
+# This doesn't seem to fix things, but would be good to fix - currently you have to manually write
+# anchor links in html
+myst_heading_anchors = 3
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 

docs/development.rst

@@ -1,5 +1,6 @@
-Development
-===========
+Development Guide
+=================
+
 Guide for how to build, configure, and develop SymForce.
 
 .. contents:: :local:

docs/examples

@@ -0,0 +1 @@
+../symforce/examples

docs/index.rst

@@ -4,56 +4,62 @@ SymForce Home
 .. include:: ../README.md
    :parser: myst_parser.sphinx_
 
-.. toctree::
-   :caption: Pages
-   :hidden:
-
-   self
-   development
-
-.. toctree::
-   :caption: Tutorials
-   :hidden:
-
-   notebooks/sympy_tutorial
-   notebooks/geometry_tutorial
-   notebooks/ops_tutorial
-   notebooks/cameras_tutorial
-   notebooks/values_tutorial
-   notebooks/codegen_tutorial
-   notebooks/optimization_tutorial
-   notebooks/epsilon_tutorial
-
 Guides
 ======
 
 :doc:`development`
     How to build, configure, and develop
 
-:doc:`notebooks/sympy_tutorial`
+:doc:`tutorials/sympy_tutorial`
     Basic introduction to SymPy
 
-:doc:`notebooks/geometry_tutorial`
+:doc:`tutorials/geometry_tutorial`
     Introductory guide to doing math and geometry
 
-:doc:`notebooks/ops_tutorial`
+:doc:`tutorials/ops_tutorial`
     Introductory guide to using Ops in symforce
 
-:doc:`notebooks/cameras_tutorial`
+:doc:`tutorials/cameras_tutorial`
     Introductory guide to using camera models
 
-:doc:`notebooks/values_tutorial`
+:doc:`tutorials/values_tutorial`
     How to structure large groups of symbols and expressions
 
-:doc:`notebooks/codegen_tutorial`
+:doc:`tutorials/codegen_tutorial`
     How to generate functions from symbolic expressions
 
-:doc:`notebooks/optimization_tutorial`
+:doc:`tutorials/optimization_tutorial`
     Basic example of using generated code to do optimization
 
-:doc:`notebooks/epsilon_tutorial`
+:doc:`tutorials/epsilon_tutorial`
     Guide to how Epsilon is used to prevent singularities
 
+.. toctree::
+   :hidden:
+
+   development
+
+.. toctree::
+   :caption: Tutorials
+   :hidden:
+
+   tutorials/sympy_tutorial
+   tutorials/geometry_tutorial
+   tutorials/ops_tutorial
+   tutorials/cameras_tutorial
+   tutorials/values_tutorial
+   tutorials/codegen_tutorial
+   tutorials/optimization_tutorial
+   tutorials/epsilon_tutorial
+
+.. toctree::
+   :caption: Examples
+   :hidden:
+   :glob:
+   :titlesonly:
+
+   examples/*/README
+
 .. _api-reference:
 .. toctree::
     :hidden:

docs/notebooks/cameras_tutorial.ipynb

@@ -10,3 +10,17 @@ section#symforce-home h1 {
 div.sphinxsidebarwrapper h3:first-of-type {
   display: none;
 }
+
+/**
+ * Fix for:
+ * https://github.com/symforce-org/symforce/issues/141
+ * https://github.com/bitprophet/alabaster/issues/181
+ */
+dl.py {
+    margin-bottom: 15px;
+}
+
+div.sphinxsidebarwrapper p.caption span.caption-text {
+  font-size: 140%;
+  font-weight: bold;
+}

docs/notebooks/codegen_tutorial.ipynb

@@ -0,0 +1 @@
+../notebooks/tutorials

docs/notebooks/epsilon_tutorial.ipynb

@@ -0,0 +1,18 @@
+Bundle Adjustment
+=================
+
+[Source on GitHub](https://github.com/symforce-org/symforce/tree/main/symforce/examples/bundle_adjustment)
+
+This example demonstrates bundle adjustment of camera extrinsics and landmarks using factors built into SymForce.  This particular example is set up so that the number of cameras and landmarks is unknown at code generation time and can be changed at runtime; in contrast, the `Fixed Size Bundle Adjustment` example shows how fixing the number of cameras or landmarks at codegen time can be more efficient.
+
+We randomly generate a set of camera poses and feature correspondences with noise and some outliers, and perform bundle adjustment with feature reprojection residuals and pose priors.
+
+## Files:
+
+### `build_example_state.*`:
+
+Utilities for building up the problem, by randomly sampling camera poses and feature correspondences, and perturbing initial guesses.  This is all returned in the form of a `Values` produced by the `BuildValues` function.
+
+### `run_bundle_adjustment.cc`
+
+This is the C++ file that actually runs the optimization.  It builds up the `Values` for the problem, builds a factor graph, and performs bundle adjustment.  See the comments there for more information.

docs/notebooks/geometry_tutorial.ipynb

@@ -0,0 +1,26 @@
+Fixed Size Bundle Adjustment
+============================
+
+[Source on GitHub](https://github.com/symforce-org/symforce/tree/main/symforce/examples/bundle_adjustment_fixed_size)
+
+This example demonstrates bundle adjustment of camera extrinsics and landmarks using factors built into SymForce.  This particular example is set up so that the number of cameras and landmarks is set at code generation time; in contrast, the `Bundle Adjustment` example shows how to make them configurable at runtime.  Fixing the size of the problem at generation time can produce significantly more efficient linearization functions, because common subexpression elimination can be applied across multiple factors.  For instance, multiple factors that reproject different features into the same cameras will often share computation.
+
+We randomly generate a set of camera poses and feature correspondences with noise and some outliers, and perform bundle adjustment with feature reprojection residuals and pose priors.
+
+## Files:
+
+### `build_example_state.*`:
+
+Utilities for building up the problem, by randomly sampling camera poses and feature correspondences, and perturbing initial guesses.  This is all returned in the form of a `Values` produced by the `BuildValues` function.
+
+### `build_values.py`:
+
+Builds a symbolic Python `Values` with all of the variables in the problem.  This is used to build up the symbolic problem in `generate_fixed_problem.py`.
+
+### `generate_fixed_problem.py`:
+
+This actually defines the fixed-size problem, taking the `Values` built by `build_values.py` and constructing all of the residuals.  We can then generate the entire problem into C++, with common subexpression elimination running across the entire problem together.  The `FixedBundleAdjustmentProblem.generate` method is called by `test/symforce_examples_bundle_adjustment_fixed_size_codegen_test.py` to actually generate the linearization function in `gen`.
+
+### `run_bundle_adjustment.cc`
+
+This is the C++ file that actually runs the optimization.  It builds up the `Values` for the problem and builds a factor graph.  In this example, the C++ optimization consists of one `sym::Factor`, with a single generated linearization function that contains all of the symbolic residuals.

docs/notebooks/ops_tutorial.ipynb

@@ -0,0 +1,29 @@
+Bundle-Adjustment-in-the-Large
+======================================
+
+[Source on GitHub](https://github.com/symforce-org/symforce/tree/main/symforce/examples/bundle_adjustment_in_the_large)
+
+This example demonstrates bundle adjustment of camera extrinsics and intrinsics, as well as 3D landmark positions, for a Structure-from-Motion problem.  The example isn't particularly optimized for performance, but demonstrates the simplest way to set this up with SymForce.
+
+We use the Bundle-Adjustment-in-the-Large dataset, as described here: https://grail.cs.washington.edu/projects/bal/
+
+Feature correspondences have already been selected, and we're given initial guesses for all of the variables; our only task is to perform bundle adjustment.
+
+The camera model is a simple polynomial model, and each image is assumed to be captured by a different camera with its own intrinsics.
+
+Ceres and GTSAM also have reference implementations for this dataset, see [here](https://github.com/ceres-solver/ceres-solver/blob/master/examples/simple_bundle_adjuster.cc) for Ceres and [here](https://github.com/devbharat/gtsam/blob/master/examples/SFMExample_bal.cpp) for GTSAM.
+
+## Files:
+
+### `download_dataset.py`:
+
+Script to download the dataset files into the `./data` folder, run this first if you'd like to run the example
+
+### `bundle_adjustment_in_the_large.py`
+
+Defines the symbolic residual function for the reprojection error factor, and a function to generate the symbolic factor into C++.  The `generate` function is called by `symforce/test/symforce_examples_bundle_adjustment_in_the_large_codegen_test.py` to generate everything in the `gen` directory.
+
+### `bundle_adjustment_in_the_large.cc`
+
+This is the C++ file that actually runs the optimization.  It loads a dataset, builds a factor graph,
+and performs bundle adjustment.  See the comments there for more information.

docs/notebooks/optimization_tutorial.ipynb

@@ -16,8 +16,14 @@
 
 using namespace sym::Keys;
 
+/**
+ * Create a `sym::Factor` for the reprojection residual, attached to the given camera and point
+ * variables.  It's also attached to fixed entries in the Values for the pixel measurement and the
+ * constant EPSILON.
+ */
 sym::Factord MakeFactor(int camera, int point, int pixel) {
   return sym::Factord::Hessian(sym::SnavelyReprojectionFactor<double>,
+                               /* all_keys = */
                                {
                                    sym::Key::WithSuper(CAM_T_WORLD, camera),
                                    sym::Key::WithSuper(INTRINSICS, camera),
@@ -33,6 +39,9 @@ sym::Factord MakeFactor(int camera, int point, int pixel) {
                                });
 }
 
+/**
+ * A struct to represent the problem definition
+ */
 struct Problem {
   std::vector<sym::Factord> factors;
   sym::Valuesd values;
@@ -102,14 +111,23 @@ Problem ReadProblem(const std::string& filename) {
   return {std::move(factors), std::move(values), num_cameras, num_points, num_observations};
 }
 
+/**
+ * Example usage: `bundle_adjustment_in_the_large_example data/problem-21-11315-pre.txt`
+ */
 int main(int argc, char** argv) {
   sym::internal::SetLogLevel("info");
 
   SYM_ASSERT(argc == 2);
+
+  // Read the problem from disk, and create the Values and factors
   const auto problem = ReadProblem(argv[1]);
 
+  // Create a copy of the Values - we'll optimize this one in place
   sym::Valuesd optimized_values = problem.values;
+
+  // Optimize
   sym::Optimizerd optimizer{sym::DefaultOptimizerParams(), std::move(problem.factors)};
   const auto stats = optimizer.Optimize(&optimized_values);
+
   spdlog::info("Finished in {} iterations", stats.iterations.size());
 }