If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/gaoxiang12/slambook shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 2y ago

• 16 active contributors
• Distributed ownership (top contributor 45% of recent commits)
• MIT licensed
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ No CI workflows detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live gaoxiang12/slambook repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/gaoxiang12/slambook.

What it runs against: a local clone of gaoxiang12/slambook — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in gaoxiang12/slambook | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 808 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of gaoxiang12/slambook. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/gaoxiang12/slambook.git
#   cd slambook
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of gaoxiang12/slambook and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "gaoxiang12/slambook(\\.git)?\\b" \\
  && ok "origin remote is gaoxiang12/slambook" \\
  || miss "origin remote is not gaoxiang12/slambook (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "ch10/g2o_custombundle/g2o_bundle.cpp" \\
  && ok "ch10/g2o_custombundle/g2o_bundle.cpp" \\
  || miss "missing critical file: ch10/g2o_custombundle/g2o_bundle.cpp"
test -f "ch10/ceres_custombundle/ceresBundle.cpp" \\
  && ok "ch10/ceres_custombundle/ceresBundle.cpp" \\
  || miss "missing critical file: ch10/ceres_custombundle/ceresBundle.cpp"
test -f "ch11/pose_graph_g2o_SE3.cpp" \\
  && ok "ch11/pose_graph_g2o_SE3.cpp" \\
  || miss "missing critical file: ch11/pose_graph_g2o_SE3.cpp"
test -f "ch12/loop_closure.cpp" \\
  && ok "ch12/loop_closure.cpp" \\
  || miss "missing critical file: ch12/loop_closure.cpp"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 808 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~778d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/gaoxiang12/slambook"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Slambook is a comprehensive C++ codebase accompanying the textbook '14 Lectures on Visual SLAM: From Theory to Practice' (2017). It implements visual Simultaneous Localization and Mapping (SLAM) from first principles, covering rigid body motion, feature-based odometry, direct methods, bundle adjustment, loop closure detection, and dense reconstruction using libraries like Ceres, g2o, and DBoW3. Chapter-based monorepo: ch2–ch13 directories contain topic-specific C++ implementations; ch10 (backend optimization) has two separate implementations via ceres_custombundle/ and g2o_custombundle/ with shared common/ code for BALProblem, BundleParams, and projection utilities. 3rdparty/ holds all external dependency tarballs. Project code segregated in project/ directory rather than ch9.

Computer vision students, SLAM researchers, and roboticists learning visual SLAM theory and implementation. Readers of the original Gao Xiang textbook who want to understand and modify working SLAM code end-to-end, or developers building robotic navigation systems.

Educational but dated: published in 2017 with no recent commits visible in the file structure. The author released Slambook 2 (slambook2) in August 2019 with better Ubuntu 18.04 support and new features; this original version is stable but not actively maintained. No test suite or CI configuration evident in the repo.

Single-author maintenance risk with no activity post-2017. Heavy dependency on external libraries (Eigen, Sophus, Ceres, g2o, OpenCV, Pangolin, DBow3) requiring manual compilation from tarballs in 3rdparty/. Ubuntu 16.04-era build configuration may fail on modern systems. No continuous integration, unit tests, or issue tracking automation visible. Recommend using Slambook 2 for new projects.

No active development—this is a static educational snapshot frozen at 2017 publication. Slambook 2 (gaoxiang12/slambook2) is the maintained successor. The English translation (gaoxiang12/slambook-en) is also available but this original ch1–ch13 structure is in legacy status.

git clone https://github.com/gaoxiang12/slambook.git
cd slambook
# Extract dependencies (requires manual compilation)
cd 3rdparty
tar -xzf Sophus.tar.gz && tar -xzf g2o.tar.gz && tar -xzf ceres-solver.tar.gz && tar -xzf Pangolin.tar.gz && tar -xzf DBow3.tar.gz
# Build a specific chapter (e.g., ch3 for Eigen basics)
cd ../ch3 && mkdir build && cd build && cmake .. && make

Daily commands: CMake-based: cd ch<N> && mkdir build && cd build && cmake .. && make. Each chapter has independent CMakeLists.txt. No single 'main' entry point—run individual chapter executables after build. Examples: ./ch7_vo_mono for monocular odometry, ./ceresBundle in ch10/ceres_custombundle for bundle adjustment.

• README.md — Essential overview explaining this is code from "14 Lectures on Visual SLAM" book; describes chapter organization and licensing under MIT
• ch10/g2o_custombundle/g2o_bundle.cpp — Core bundle adjustment implementation using g2o library; demonstrates pose graph optimization which is central to SLAM backend
• ch10/ceres_custombundle/ceresBundle.cpp — Alternative bundle adjustment implementation using Ceres solver; shows custom cost functions for camera pose and landmark optimization
• ch11/pose_graph_g2o_SE3.cpp — Pose graph optimization using SE(3) Lie groups; demonstrates loop closure and pose graph construction for backend optimization
• ch12/loop_closure.cpp — Loop closure detection implementation using DBoW3 vocabulary tree; critical for place recognition in SLAM systems
• ch10/g2o_custombundle/g2o_bal_class.h — g2o vertex and edge definitions for bundle adjustment problem; defines the optimization variables and constraints
• ch13/dense_RGBD/CMakeLists.txt — Build configuration for dense RGBD reconstruction module; shows dependency setup for point cloud and depth processing

Add a new bundle adjustment cost function

1. Create a new header file in ch10/ceres_custombundle/ with a custom cost function struct inheriting from ceres::CostFunction (ch10/ceres_custombundle/SnavelyReprojectionError.h)
2. Define operator() with template parameters for automatic differentiation using ceres::jet types (ch10/ceres_custombundle/SnavelyReprojectionError.h)
3. Register the cost function in ceresBundle.cpp using ceres::CostFunctionToFunctor wrapper (ch10/ceres_custombundle/ceresBundle.cpp)
4. Add residual block to problem using problem->AddResidualBlock() with your new cost function (ch10/ceres_custombundle/ceresBundle.cpp)

Add a new pose graph constraint (edge) in g2o

1. Define a new edge class inheriting from g2o::BaseBinaryEdge in ch10/g2o_custombundle/g2o_bal_class.h (ch10/g2o_custombundle/g2o_bal_class.h)
2. Implement computeError() to calculate the measurement error between two poses or pose and landmark (ch10/g2o_custombundle/g2o_bal_class.h)
3. Add the edge to the optimizer in g2o_bundle.cpp using optimizer.addEdge() after creating vertices (ch10/g2o_custombundle/g2o_bundle.cpp)

Extend loop closure detection with custom descriptor matching

1. Load or train a new vocabulary using feature descriptors in ch12/feature_training.cpp (ch12/feature_training.cpp)
2. Modify loop_closure.cpp to use DBoW3::Database for querying similar keyframes (ch12/loop_closure.cpp)
3. Implement geometric verification (epipolar constraint check) before adding loop closure edge (ch12/loop_closure.cpp)

Add new RGBD processing stage for dense reconstruction

1. Create new .cpp file in ch13/dense_RGBD/ directory for your processing stage (e.g., depth_filtering.cpp) (ch13/dense_RGBD/CMakeLists.txt)
2. Load color and depth images using data layout in ch13/dense_RGBD/data/color/ and data/depth/ (ch13/dense_RGBD/data/pose.txt)
3. Register executable in CMakeLists.txt and link against PCL/OpenCV libraries (ch13/dense_RGBD/CMakeLists.txt)

• g2o (General Graph Optimization) — Specialized library for pose graph optimization and bundle adjustment; enables efficient nonlinear least-squares solving on factor graphs with SE(3) and other manifolds
• Ceres Solver — Alternative automatic differentiation framework for bundle adjustment; provides gradient-free optimization through automatic derivatives and robust loss functions
• Sophus (Lie Groups) — Enables proper handling of rotation and SE(3) pose manifolds; avoids gimbal lock and singularities inherent in Euler angles
• DBoW3 (Vocabulary Tree) — Scalable loop closure detection via visual vocabulary; trades precision for speed in large-scale place recognition
• Pangolin — 3D visualization framework for rendering camera trajectories, point clouds, and pose graph structure during and after SLAM execution

• Separate g2o and Ceres implementations for bundle adjustment (ch10/g2o_custombundle vs ch10/ceres_custombundle)

  • Why: Educational purpose; allows comparison of different optimization paradigms and libraries
  • Consequence: Code duplication and maintenance burden; learners can choose preferred optimization framework but must maintain two codebases

• Bundle adjustment applied post-hoc to image sequence rather than real-time incremental filtering

  • Why: Batch processing simpler to understand and debug; enables optimal global solution
  • Consequence: Not suitable for real-time SLAM; high latency between image capture and pose refinement

• Loop closure uses vocabulary-based heuristic before geometric verification

  • Why: Reduces computational cost of pairwise image matching from O(n²) to O(log n)
  • Consequence: False positives possible; requires secondary geometric validation with epipolar constraints

• Dense reconstruction (ch13) operates on RGBD input rather than monocular depth prediction

  • Why: Simplifies depth estimation; avoids depth prediction network complexity
  • Consequence: Requires depth camera hardware; not applicable to monocular-only setups

• Real-time SLAM execution on embedded devices
• Monocular depth estimation without ground truth depth
• Multi-sensor fusion (IMU, LiDAR) beyond RGBD
• Dynamic scene handling or moving object segmentation

Dependency hell: Sophus, g2o, Ceres, and Pangolin must be manually compiled from tarballs in 3rdparty/—no vcpkg, conan, or apt integration. Some tarballs may require Ubuntu 16.04-era libraries; modern Ubuntu (20.04+) may have incompatible system Eigen, OpenCV versions causing linker conflicts. ch10/g2o_custombundle includes a custom g2o_viewer.patch that may fail to apply. BAL dataset download links in ch10 may be dead. No documentation on required CUDA version if building Ceres with GPU support. CMAKE_BUILD_TYPE defaults may not be set, resulting in unoptimized Debug builds.

• Bundle Adjustment — Central optimization problem in ch10: jointly refining camera poses and 3D landmark positions by minimizing reprojection error across all views; foundation of visual SLAM backends
• Lie Groups and Lie Algebras (SE(3), so(3)) — ch4 core: compact representation of rigid body transformations (rotation + translation) and their infinitesimal generators; enables efficient parameterization and local linearization in optimization
• Feature-Based Visual Odometry (EPnP, Essential Matrix) — ch7 method: tracks feature correspondences across frames and solves 6-DoF pose via Essential matrix factorization and PnP; foundation before backend optimization in ch10
• Direct (Photometric) Odometry — ch8 alternative: minimizes raw pixel intensity residuals instead of feature reprojection; enables dense reconstruction and works in low-texture scenes where features fail
• Factor Graphs and Pose Graphs — ch11 backend: g2o abstraction encoding SLAM as a bipartite graph of variables (poses, landmarks) and factors (odometry, loop closure constraints); enables incremental and batch optimization
• Bag-of-Words Loop Closure Detection (DBoW3) — ch12 mechanism: creates visual vocabulary from keyframe descriptors and detects revisited locations via string matching; closes loops and corrects drift
• Semi-Dense Depth Estimation (REMODE, Octomap) — ch13 output: probabilistic depth inference from photometric consistency across frames; enables dense 3D reconstruction and volumetric occupancy maps for navigation

• gaoxiang12/slambook2 — Official successor (2019+) with improved Ubuntu 18.04+ support, new chapters, better build integration, and active maintenance—recommended for new learners
• gaoxiang12/slambook-en — English translation of the original Slambook chapters; same code, different documentation language
• raulmur/ORB-SLAM2 — Production-grade feature-based SLAM system; implements monocular and stereo odometry/mapping similar to ch7–ch10 but with loop closure and real-time performance
• ceres-solver/ceres-solver — Core optimization library used throughout ch6, ch10; understanding Ceres API deeply helps modify bundle adjustment and cost functions
• RainerKuemmerle/g2o — Core factor graph and pose graph library used in ch10–ch11; native implementation of optimization backend for loop closure and global BA

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add CMake dependency verification and automated build validation workflow

The repo contains multiple independent CMake projects (ch10/ceres_custombundle, ch10/g2o_custombundle, ch11) with compressed 3rdparty dependencies (DBow3.tar.gz, Pangolin.tar.gz, Sophus.tar.gz, ceres-solver.tar.gz, g2o.tar.gz). Currently there's no CI workflow to verify that these builds work correctly across different systems. A GitHub Actions workflow would catch build failures early and ensure contributors don't break the build system, particularly when updating CMakeLists.txt files or dependency versions.

• [ ] Create .github/workflows/cmake-build.yml to build ch10/ceres_custombundle, ch10/g2o_custombundle, and ch11 projects
• [ ] Add extraction logic for 3rdparty/*.tar.gz files in the workflow
• [ ] Test on Ubuntu 18.04 (as mentioned in README as a target platform) and verify all CMakeLists.txt files have correct dependency resolution
• [ ] Document in README.md the required system dependencies and build instructions that the CI validates

Create unified CMakeLists.txt for ch11 pose_graph examples with shared configuration

The ch11 directory contains three separate pose graph implementations (pose_graph_g2o_SE3.cpp, pose_graph_g2o_lie_algebra.cpp, pose_graph_gtsam.cpp) sharing common modules (cmake_modules/FindG2O.cmake, FindCholmod.cmake). The CMakeLists.txt currently treats them as independent builds, leading to duplicated find_package() calls and configuration logic. Refactoring would reduce maintenance burden and make it easier for new contributors to add similar examples.

• [ ] Consolidate ch11/CMakeLists.txt to define common dependency variables (G2O_LIBRARIES, CHOLMOD_LIBRARIES) once at the top
• [ ] Create a CMake macro or function for adding pose_graph examples to reduce boilerplate (e.g., add_pose_graph_example(name src_file))
• [ ] Move FindG2O.cmake and FindCholmod.cmake into a central cmake_modules directory if not already shared with other chapters
• [ ] Update ch11/Readme.md to explain the build configuration and how to add new pose graph solver examples

Add build status badges and setup instructions for slambook vs slambook2 migration

The README.md notes that slambook2 is the recommended version for new readers and has better Ubuntu 18.04 support, but provides no clear migration guide or feature comparison. Additionally, there's no automated validation that the code still works with modern dependency versions. Adding a build status badge and clear setup instructions would help users understand the project's maintenance status and reduce confusion about which version to use.

• [ ] Add build status badge to README.md pointing to CI workflow status (after implementing PR #1)
• [ ] Create SETUP.md with platform-specific instructions (Ubuntu 16.04 vs 18.04 vs 20.04) including dependency installation commands for each 3rdparty library
• [ ] Add a 'Migration Guide' section to README.md explaining differences between slambook, slambook2, and slambook-en with links to each repo
• [ ] Document minimum required versions for Eigen, Ceres, g2o, and other major dependencies in SETUP.md

• Add unit tests for ch10/common/BALProblem.cpp: write test cases for parsing BAL problem files, validate pose/point count, and verify reprojection error computation. This would improve code reliability and serve as documentation.
• Create a consolidated CMakeLists.txt at repository root that auto-discovers and builds all chapters, and add pre-build validation scripts (e.g., check Eigen/OpenCV versions) to catch dependency mismatches early.
• Document the BAL dataset format and add a downloader script in ch10/data/; many readers struggle to obtain the problem-16-22106-pre.txt file needed to run bundle adjustment examples.

This is an educational SLAM algorithms codebase from 2017 with moderate security concerns. Primary risks stem from: (1) outdated and unversioned third-party dependencies without integrity verification, (2) lack of modern compiler security flags in CMake configurations, (3) unverified patch file in distribution, and (4) absence of security documentation. As an academic/reference implementation rather than production code, the exposure is limited, but users should be cautious when building on modern systems. The codebase would benefit from dependency management modernization, security hardening of build configurations, and clear security guidelines for contributors and users.

• High · Outdated and Potentially Vulnerable Dependencies — 3rdparty/ directory (DBow3.tar.gz, Pangolin.tar.gz, Sophus.tar.gz, ceres-solver.tar.gz, g2o.tar.gz). The codebase relies on third-party libraries (DBow3, Pangolin, Sophus, ceres-solver, g2o) that are distributed as compressed archives without version pinning or integrity verification. These dependencies may contain known vulnerabilities, especially given the book's 2017 publication date. No lock files or dependency manifest is present to ensure reproducible builds. Fix: 1) Specify exact versions for all dependencies; 2) Use package managers (vcpkg, conan, etc.) instead of manual tar.gz distribution; 3) Implement dependency vulnerability scanning; 4) Add checksums/signatures for downloaded archives; 5) Maintain a DEPENDENCIES.md file with version info and known issues.
• Medium · Potential Use of Outdated Compiler Flags and Build Configurations — ch10/ceres_custombundle/CMakeLists.txt, ch10/g2o_custombundle/CMakeLists.txt, ch11/CMakeLists.txt, ch12/CMakeLists.txt. CMakeLists.txt files across the project (ch10, ch11, ch12) may contain outdated compiler configurations without modern security flags. The project was originally published in 2017, and build systems may lack protections against buffer overflows, format string attacks, and other memory safety issues. Fix: 1) Add compiler security flags (-fstack-protector-strong, -D_FORTIFY_SOURCE=2, -fPIE for position-independent code); 2) Enable warnings as errors (-Werror); 3) Use ASLR and PIE; 4) Regularly audit and update CMake configurations.
• Medium · Unverified Third-Party Patch Application — 3rdparty/g2o_viewer.patch. The file g2o_viewer.patch exists in 3rdparty directory but there is no documentation on its source, verification, or application method. This could allow injection of malicious code during the patching process. Fix: 1) Document the source and purpose of the patch; 2) Include checksums or signatures for the patch; 3) Review patch content for malicious changes; 4) Automate patch application with verification; 5) Maintain patch changelog.
• Low · Missing Security Headers and Documentation — Repository root (README.md, LICENSE). While this is a code repository rather than a web application, there is no security.md or responsible disclosure policy documented. The LICENSE file and README lack security-related guidance for users building and running the code. Fix: 1) Create SECURITY.md with vulnerability reporting procedures; 2) Add security-related build instructions; 3) Document known limitations and security considerations; 4) Provide guidance on building with security flags.
• Low · Potential Data Validation Issues in BAL Problem Loader — ch10/ceres_custombundle/common/BALProblem.cpp, ch10/g2o_custombundle/common/BALProblem.cpp. The BALProblem.cpp files (in both ch10 examples) likely load data from the problem-16-22106-pre.txt file without documented input validation. While this is not directly exploitable in typical SLAM usage, untrusted input files could cause unexpected behavior. Fix: 1) Implement strict input validation for data files; 2) Use safe parsing methods; 3) Add bounds checking; 4) Document expected file format and constraints; 5) Handle malformed input gracefully.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.