just-ba 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (140) hide show
  1. just_ba-0.1.0/.gitignore +10 -0
  2. just_ba-0.1.0/CMakeLists.txt +114 -0
  3. just_ba-0.1.0/PKG-INFO +63 -0
  4. just_ba-0.1.0/README.md +174 -0
  5. just_ba-0.1.0/api/CMakeLists.txt +18 -0
  6. just_ba-0.1.0/api/include/jba/covariance.h +45 -0
  7. just_ba-0.1.0/api/include/jba/export.h +48 -0
  8. just_ba-0.1.0/api/include/jba/refine.h +101 -0
  9. just_ba-0.1.0/api/include/jba/report.h +53 -0
  10. just_ba-0.1.0/api/src/covariance.cpp +66 -0
  11. just_ba-0.1.0/api/src/export.cpp +208 -0
  12. just_ba-0.1.0/api/src/refine.cpp +375 -0
  13. just_ba-0.1.0/api/src/report.cpp +180 -0
  14. just_ba-0.1.0/api/src/solve.cpp +192 -0
  15. just_ba-0.1.0/backends/cpu/CMakeLists.txt +3 -0
  16. just_ba-0.1.0/backends/cpu/internal/jba/cpu/backend.h +46 -0
  17. just_ba-0.1.0/backends/cpu/internal/jba/cpu/cost.h +11 -0
  18. just_ba-0.1.0/backends/cpu/internal/jba/cpu/depth.h +26 -0
  19. just_ba-0.1.0/backends/cpu/internal/jba/cpu/parallel.h +133 -0
  20. just_ba-0.1.0/backends/cpu/internal/jba/cpu/priors.h +45 -0
  21. just_ba-0.1.0/backends/cpu/internal/jba/cpu/reprojection.h +37 -0
  22. just_ba-0.1.0/backends/cpu/internal/jba/cpu/system.h +275 -0
  23. just_ba-0.1.0/backends/cpu/src/backend.cpp +1006 -0
  24. just_ba-0.1.0/backends/cpu/src/cost.cpp +33 -0
  25. just_ba-0.1.0/backends/cpu/src/system.cpp +757 -0
  26. just_ba-0.1.0/backends/cuda/CMakeLists.txt +16 -0
  27. just_ba-0.1.0/backends/cuda/internal/jba/cuda/backend.h +34 -0
  28. just_ba-0.1.0/backends/cuda/kernels/prelude.cuh +36 -0
  29. just_ba-0.1.0/backends/cuda/src/backend.cu +360 -0
  30. just_ba-0.1.0/backends/gpu/CMakeLists.txt +5 -0
  31. just_ba-0.1.0/backends/gpu/internal/jba/gpu/backend.h +79 -0
  32. just_ba-0.1.0/backends/gpu/internal/jba/gpu/device.h +143 -0
  33. just_ba-0.1.0/backends/gpu/internal/jba/gpu/layout.h +205 -0
  34. just_ba-0.1.0/backends/gpu/kernels/solver.inc +1075 -0
  35. just_ba-0.1.0/backends/gpu/src/backend.cpp +1026 -0
  36. just_ba-0.1.0/backends/metal/CMakeLists.txt +30 -0
  37. just_ba-0.1.0/backends/metal/internal/jba/metal/backend.h +23 -0
  38. just_ba-0.1.0/backends/metal/internal/jba/metal/reprojection.h +31 -0
  39. just_ba-0.1.0/backends/metal/kernels/layout_sizes.metal +15 -0
  40. just_ba-0.1.0/backends/metal/kernels/prelude.metal +25 -0
  41. just_ba-0.1.0/backends/metal/kernels/reprojection.metal +42 -0
  42. just_ba-0.1.0/backends/metal/src/backend.mm +260 -0
  43. just_ba-0.1.0/backends/metal/src/reprojection.mm +136 -0
  44. just_ba-0.1.0/backends/webgpu/CMakeLists.txt +43 -0
  45. just_ba-0.1.0/backends/webgpu/internal/jba/webgpu/backend.h +40 -0
  46. just_ba-0.1.0/backends/webgpu/kernels/linearize.wgsl +91 -0
  47. just_ba-0.1.0/backends/webgpu/kernels/solver.wgsl +1263 -0
  48. just_ba-0.1.0/backends/webgpu/src/backend.cpp +651 -0
  49. just_ba-0.1.0/bindings/python/CMakeLists.txt +64 -0
  50. just_ba-0.1.0/bindings/python/README.md +43 -0
  51. just_ba-0.1.0/bindings/python/build_info.py.in +6 -0
  52. just_ba-0.1.0/bindings/python/just_ba/__init__.py +187 -0
  53. just_ba-0.1.0/bindings/python/just_ba/_nvidia.py +68 -0
  54. just_ba-0.1.0/bindings/python/just_ba/py.typed +0 -0
  55. just_ba-0.1.0/bindings/python/requirements.txt +3 -0
  56. just_ba-0.1.0/bindings/python/src/module.cpp +801 -0
  57. just_ba-0.1.0/bindings/python/tests/scene.py +92 -0
  58. just_ba-0.1.0/bindings/python/tests/test_bindings.py +423 -0
  59. just_ba-0.1.0/bindings/wasm/CMakeLists.txt +32 -0
  60. just_ba-0.1.0/bindings/wasm/src/main.cpp +117 -0
  61. just_ba-0.1.0/bindings/wasm/web/index.html +162 -0
  62. just_ba-0.1.0/cli/CMakeLists.txt +2 -0
  63. just_ba-0.1.0/cli/main.cpp +236 -0
  64. just_ba-0.1.0/cmake/EmbedText.cmake +19 -0
  65. just_ba-0.1.0/core/CMakeLists.txt +10 -0
  66. just_ba-0.1.0/core/include/jba/camera_model.h +52 -0
  67. just_ba-0.1.0/core/include/jba/initialize.h +53 -0
  68. just_ba-0.1.0/core/include/jba/loss.h +69 -0
  69. just_ba-0.1.0/core/include/jba/manhattan.h +66 -0
  70. just_ba-0.1.0/core/include/jba/priors.h +58 -0
  71. just_ba-0.1.0/core/include/jba/problem.h +188 -0
  72. just_ba-0.1.0/core/include/jba/problem_io.h +18 -0
  73. just_ba-0.1.0/core/include/jba/solver.h +229 -0
  74. just_ba-0.1.0/core/internal/jba/backend.h +60 -0
  75. just_ba-0.1.0/core/internal/jba/geometry.h +139 -0
  76. just_ba-0.1.0/core/internal/jba/trust_region.h +24 -0
  77. just_ba-0.1.0/core/src/camera_model.cpp +208 -0
  78. just_ba-0.1.0/core/src/initialize.cpp +555 -0
  79. just_ba-0.1.0/core/src/manhattan.cpp +293 -0
  80. just_ba-0.1.0/core/src/priors.cpp +88 -0
  81. just_ba-0.1.0/core/src/problem_io.cpp +719 -0
  82. just_ba-0.1.0/core/src/solver.cpp +293 -0
  83. just_ba-0.1.0/core/src/trust_region.cpp +138 -0
  84. just_ba-0.1.0/packaging/fetch_cuda.py +112 -0
  85. just_ba-0.1.0/packaging/repair_windows.py +27 -0
  86. just_ba-0.1.0/packaging/variant.py +69 -0
  87. just_ba-0.1.0/pyproject.toml +72 -0
  88. just_ba-0.1.0/residuals/CMakeLists.txt +3 -0
  89. just_ba-0.1.0/residuals/generated/cpu/depth_generated.h +288 -0
  90. just_ba-0.1.0/residuals/generated/cpu/directions_generated.h +168 -0
  91. just_ba-0.1.0/residuals/generated/cpu/priors_generated.h +730 -0
  92. just_ba-0.1.0/residuals/generated/cpu/reprojection_generated.h +847 -0
  93. just_ba-0.1.0/residuals/generated/cuda/reprojection.cuh +847 -0
  94. just_ba-0.1.0/residuals/generated/metal/reprojection.metal.h +848 -0
  95. just_ba-0.1.0/residuals/generated/wgsl/reprojection.wgsl +796 -0
  96. just_ba-0.1.0/residuals/symbolic/depth.py +65 -0
  97. just_ba-0.1.0/residuals/symbolic/directions.py +69 -0
  98. just_ba-0.1.0/residuals/symbolic/emit.py +216 -0
  99. just_ba-0.1.0/residuals/symbolic/generate.py +163 -0
  100. just_ba-0.1.0/residuals/symbolic/priors.py +121 -0
  101. just_ba-0.1.0/residuals/symbolic/reprojection.py +153 -0
  102. just_ba-0.1.0/residuals/symbolic/requirements.txt +2 -0
  103. just_ba-0.1.0/tests/CMakeLists.txt +123 -0
  104. just_ba-0.1.0/tests/ceres/CMakeLists.txt +150 -0
  105. just_ba-0.1.0/tests/ceres/ceres_reference.cpp +752 -0
  106. just_ba-0.1.0/tests/ceres/ceres_reference.h +191 -0
  107. just_ba-0.1.0/tests/ceres/ceres_solve.cpp +120 -0
  108. just_ba-0.1.0/tests/ceres/parity.cpp +244 -0
  109. just_ba-0.1.0/tests/ceres/test_ceres_covariance.cpp +142 -0
  110. just_ba-0.1.0/tests/ceres/test_ceres_level1.cpp +293 -0
  111. just_ba-0.1.0/tests/check.h +49 -0
  112. just_ba-0.1.0/tests/fd.h +53 -0
  113. just_ba-0.1.0/tests/gpu_cases.cmake +97 -0
  114. just_ba-0.1.0/tests/gpu_check.cpp +238 -0
  115. just_ba-0.1.0/tests/make_problem.cpp +386 -0
  116. just_ba-0.1.0/tests/real/test_captures.py +126 -0
  117. just_ba-0.1.0/tests/scene.cpp +676 -0
  118. just_ba-0.1.0/tests/scene.h +114 -0
  119. just_ba-0.1.0/tests/synthetic.h +165 -0
  120. just_ba-0.1.0/tests/test_bal.cpp +76 -0
  121. just_ba-0.1.0/tests/test_covariance.cpp +77 -0
  122. just_ba-0.1.0/tests/test_direction_jacobians.cpp +186 -0
  123. just_ba-0.1.0/tests/test_export.cpp +153 -0
  124. just_ba-0.1.0/tests/test_geometry.cpp +229 -0
  125. just_ba-0.1.0/tests/test_manhattan.cpp +206 -0
  126. just_ba-0.1.0/tests/test_metal_reprojection.cpp +105 -0
  127. just_ba-0.1.0/tests/test_prior_jacobians.cpp +273 -0
  128. just_ba-0.1.0/tests/test_problem_io.cpp +325 -0
  129. just_ba-0.1.0/tests/test_public_headers.cpp +23 -0
  130. just_ba-0.1.0/tests/test_refine.cpp +375 -0
  131. just_ba-0.1.0/tests/test_reprojection_jacobians.cpp +190 -0
  132. just_ba-0.1.0/tests/test_solver.cpp +404 -0
  133. just_ba-0.1.0/tests/to_colmap.cpp +141 -0
  134. just_ba-0.1.0/third_party/ceres/build.cmake +114 -0
  135. just_ba-0.1.0/third_party/webgpu/.gitignore +2 -0
  136. just_ba-0.1.0/tracks/CMakeLists.txt +4 -0
  137. just_ba-0.1.0/tracks/include/jba/tracks.h +79 -0
  138. just_ba-0.1.0/tracks/include/jba/triangulation.h +54 -0
  139. just_ba-0.1.0/tracks/src/tracks.cpp +222 -0
  140. just_ba-0.1.0/tracks/src/triangulation.cpp +186 -0
@@ -0,0 +1,10 @@
1
+ build/
2
+ .venv/
3
+ __pycache__/
4
+ /tests/data/bal/
5
+ .DS_Store
6
+ # Real captures (for example exported by just-ba-match) stay local.
7
+ /tests/data/*.jba
8
+ /tests/data/real/
9
+ dist/
10
+ wheelhouse/
@@ -0,0 +1,114 @@
1
+ cmake_minimum_required(VERSION 3.24)
2
+
3
+ project(just_ba VERSION 0.1.0 DESCRIPTION "Minimal, fast bundle adjustment" LANGUAGES CXX)
4
+
5
+ set(CMAKE_CXX_STANDARD 23) # decision D52; the CUDA sources are C++20 (D113)
6
+ set(CMAKE_CXX_STANDARD_REQUIRED ON)
7
+ set(CMAKE_CXX_EXTENSIONS OFF)
8
+ set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
9
+
10
+ if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
11
+ set(CMAKE_BUILD_TYPE Release CACHE STRING "Build type" FORCE)
12
+ endif()
13
+
14
+ option(JBA_BUILD_WASM "Build the WebAssembly module and demo page (Emscripten only; exploration)" OFF)
15
+ if(EMSCRIPTEN)
16
+ # Native wasm exceptions (every current browser); the library reports errors by throwing.
17
+ add_compile_options(-fwasm-exceptions)
18
+ add_link_options(-fwasm-exceptions)
19
+ set(JBA_BUILD_TESTS OFF CACHE BOOL "" FORCE)
20
+ set(JBA_BUILD_CLI OFF CACHE BOOL "" FORCE)
21
+ endif()
22
+ option(JBA_BUILD_TESTS "Build the tests" ON)
23
+ option(JBA_BUILD_CLI "Build the sample command-line binary" ON)
24
+ option(JBA_WITH_CERES "Build the Ceres reference harness (test-only; see third_party/ceres)" OFF)
25
+ option(JBA_BUILD_PYTHON "Build the Python bindings (needs nanobind; see README)" OFF)
26
+ if(JBA_BUILD_PYTHON)
27
+ set(CMAKE_POSITION_INDEPENDENT_CODE ON) # static libraries linked into the extension
28
+ endif()
29
+ if(APPLE)
30
+ option(JBA_WITH_METAL "Build the Metal backend" ON)
31
+ else()
32
+ set(JBA_WITH_METAL OFF)
33
+ endif()
34
+ option(JBA_WITH_CUDA "Build the CUDA backend (needs the CUDA toolkit, 12 or later)" OFF)
35
+ option(JBA_WITH_WEBGPU "Build the WebGPU backend (exploration; needs Dawn natively, emdawnwebgpu under Emscripten)" OFF)
36
+ option(JBA_WITH_CUDSS "CUDA backend: sparse_schur with NVIDIA cuDSS (needs cuDSS 1.0 or later)" OFF)
37
+ if(JBA_WITH_CUDA)
38
+ # The GPU of the build machine unless the caller lists architectures.
39
+ if(NOT DEFINED CMAKE_CUDA_ARCHITECTURES)
40
+ set(CMAKE_CUDA_ARCHITECTURES native)
41
+ endif()
42
+ enable_language(CUDA)
43
+ # C++20, not the host's C++23: nvcc accepts C++23 only from CUDA 13.3, and the
44
+ # CUDA 12 wheels keep the GPU generations CUDA 13 dropped (D113). The headers the
45
+ # CUDA sources include keep to C++20.
46
+ set(CMAKE_CUDA_STANDARD 20)
47
+ set(CMAKE_CUDA_STANDARD_REQUIRED ON)
48
+ set(CMAKE_CUDA_EXTENSIONS OFF)
49
+ endif()
50
+
51
+ # Packages looked up here, in one directory: cuDSS's package configuration promotes its
52
+ # targets to global scope each time it is read, which CMake allows only in the
53
+ # directory that made them, and a Ceres built with cuDSS (master) reads it again.
54
+ if(JBA_WITH_CUDA AND JBA_WITH_CUDSS)
55
+ find_package(cudss REQUIRED CONFIG)
56
+ endif()
57
+ if(JBA_WITH_CERES)
58
+ # The accuracy reference is 2.2.0 (document 05); another version, such as master
59
+ # (2.3.0) for the GPU speed column, is named here.
60
+ set(JBA_CERES_VERSION 2.2.0 CACHE STRING "Ceres version the reference harness is built against")
61
+ find_package(Ceres ${JBA_CERES_VERSION} EXACT REQUIRED CONFIG)
62
+ endif()
63
+
64
+ add_library(jba_warnings INTERFACE)
65
+ if(MSVC)
66
+ target_compile_options(jba_warnings INTERFACE $<$<COMPILE_LANGUAGE:CXX>:/W4 /permissive- /utf-8>)
67
+ else()
68
+ target_compile_options(jba_warnings INTERFACE $<$<COMPILE_LANGUAGE:CXX,OBJCXX>:-Wall -Wextra -Wpedantic -Wshadow>)
69
+ endif()
70
+
71
+ # Internal headers (D79): the backend interface, the trust-region loop, the geometry
72
+ # helpers and the backends' own headers. They are not in any public include
73
+ # directory; the libraries, the CLI and the tests reach them through this target.
74
+ add_library(jba_internal INTERFACE)
75
+ target_include_directories(jba_internal INTERFACE ${PROJECT_SOURCE_DIR}/core/internal
76
+ ${PROJECT_SOURCE_DIR}/backends/cpu/internal ${PROJECT_SOURCE_DIR}/backends/gpu/internal
77
+ ${PROJECT_SOURCE_DIR}/backends/metal/internal ${PROJECT_SOURCE_DIR}/backends/cuda/internal
78
+ ${PROJECT_SOURCE_DIR}/backends/webgpu/internal)
79
+ target_link_libraries(jba_internal INTERFACE jba_generated_cpu) # the CPU headers include the generated code
80
+
81
+ add_subdirectory(core)
82
+ add_subdirectory(residuals)
83
+ add_subdirectory(backends/cpu)
84
+ add_subdirectory(tracks)
85
+ add_subdirectory(api)
86
+ # The GPU backends' shared host logic is plain C++: built on every platform, with or
87
+ # without a GPU backend, so every compiler CI has sees it (review of milestone 5,
88
+ # finding 7). Only a GPU backend links it.
89
+ add_subdirectory(backends/gpu)
90
+ if(JBA_WITH_METAL)
91
+ add_subdirectory(backends/metal)
92
+ endif()
93
+ if(JBA_WITH_CUDA)
94
+ add_subdirectory(backends/cuda)
95
+ endif()
96
+ if(JBA_WITH_WEBGPU)
97
+ add_subdirectory(backends/webgpu)
98
+ endif()
99
+ if(JBA_BUILD_CLI)
100
+ add_subdirectory(cli)
101
+ endif()
102
+ if(JBA_BUILD_TESTS)
103
+ enable_testing()
104
+ endif()
105
+ if(JBA_BUILD_PYTHON)
106
+ add_subdirectory(bindings/python)
107
+ endif()
108
+ if(JBA_BUILD_WASM)
109
+ add_subdirectory(bindings/wasm)
110
+ endif()
111
+ if(JBA_BUILD_TESTS)
112
+ enable_testing()
113
+ add_subdirectory(tests)
114
+ endif()
just_ba-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,63 @@
1
+ Metadata-Version: 2.4
2
+ Name: just-ba
3
+ Version: 0.1.0
4
+ Summary: Minimal, fast bundle adjustment: CPU, Metal and CUDA backends, pose priors from ARKit and ARCore
5
+ Keywords: bundle adjustment,structure from motion,photogrammetry,ARKit,ARCore
6
+ License-Expression: Apache-2.0
7
+ Classifier: Development Status :: 3 - Alpha
8
+ Classifier: Intended Audience :: Science/Research
9
+ Classifier: Operating System :: MacOS
10
+ Classifier: Operating System :: Microsoft :: Windows
11
+ Classifier: Operating System :: POSIX :: Linux
12
+ Classifier: Programming Language :: C++
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Topic :: Scientific/Engineering :: Image Processing
15
+ Requires-Python: >=3.12
16
+ Requires-Dist: numpy>=1.26
17
+ Provides-Extra: test
18
+ Requires-Dist: pytest; extra == "test"
19
+ Description-Content-Type: text/markdown
20
+
21
+ # just-ba
22
+
23
+ Minimal, fast bundle adjustment, with Python bindings. Its main job is refining
24
+ reconstructions that come with noisy camera poses from ARKit, ARCore or another
25
+ tracker: the tracker's poses become relative or global pose priors, and the
26
+ solver refines poses, points and intrinsics against the keypoint observations.
27
+
28
+ - Backends: CPU (double precision, the reference), Metal on Apple Silicon, CUDA on
29
+ NVIDIA GPUs (single precision on the GPUs).
30
+ - Correctness means agreeing with Ceres Solver on the same problem.
31
+ - Camera models SIMPLE_PINHOLE, PINHOLE, SIMPLE_RADIAL, RADIAL, OPENCV and
32
+ OPENCV_FISHEYE, with COLMAP's parameter order.
33
+ - Priors: relative and global pose priors, gravity, a Manhattan prior from line
34
+ segments, and depth at keypoints.
35
+
36
+ ## Install
37
+
38
+ | Package | Platforms | Backends |
39
+ |---|---|---|
40
+ | `pip install just-ba` | Linux x86_64, macOS arm64 (13 or later), Windows x86_64 | CPU; Metal on macOS |
41
+ | `pip install just-ba-cu12` | Linux x86_64, Windows x86_64 | CPU and CUDA 12 |
42
+ | `pip install just-ba-cu13` | Linux x86_64, Windows x86_64 | CPU and CUDA 13 |
43
+
44
+ Install one of them: all three provide the `just_ba` module. The CUDA packages
45
+ install NVIDIA's cuDSS, cuBLAS and NVRTC from pip and need an NVIDIA driver.
46
+ Python 3.12 or later.
47
+
48
+ ```python
49
+ import just_ba
50
+ print(just_ba.__version__, just_ba.compiled_backends())
51
+ print(just_ba.backend_available(just_ba.Backend.CUDA))
52
+ ```
53
+
54
+ ## Use
55
+
56
+ `just_ba.refine(scene, keypoints, matches=...)` is the main entry point: a
57
+ `Problem` holding the camera and the pose priors, one `(n, 2)` keypoint array per
58
+ image, and pairwise matches `(m, 4)`. `just_ba.poses_from_camera_to_world(T,
59
+ "arkit")` converts ARKit or ARCore camera-to-world matrices to the library's
60
+ poses. `just_ba.solve(problem, options)` solves a `Problem` that already has its
61
+ points and observations.
62
+
63
+ Licence: Apache-2.0.
@@ -0,0 +1,174 @@
1
+ # just-ba
2
+
3
+ A minimal, high-performance bundle adjustment library in C++ with Python bindings,
4
+ for refining reconstructions that come with noisy camera poses from ARKit, ARCore
5
+ or another tracker. Early development: milestones 0 to 4 done, the main use case (`jba::refine`)
6
+ with gravity, the Manhattan prior from line segments, depth at keypoints, covariances
7
+ and export to COLMAP, checked against Ceres and synthetic ground truth, on the CPU and
8
+ on Apple GPUs (Metal) and NVIDIA GPUs (CUDA, milestone 5: met on Linux, Windows check outstanding).
9
+ The plan is in [docs/](docs/README.md).
10
+
11
+ ## Build
12
+
13
+ Needs CMake 3.24 or later and a C++23 compiler. On macOS the Metal backend is built
14
+ by default.
15
+
16
+ ```bash
17
+ cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
18
+ ```
19
+
20
+ ```bash
21
+ cmake --build build --parallel
22
+ ```
23
+
24
+ ```bash
25
+ ctest --test-dir build --output-on-failure
26
+ ```
27
+
28
+ ## Python bindings
29
+
30
+ The bindings use nanobind, needed at build time only, and the stable ABI from
31
+ Python 3.12. Set up a virtual environment with the build and test requirements:
32
+
33
+ ```bash
34
+ uv venv --python 3.12 bindings/python/.venv && uv pip install --python bindings/python/.venv/bin/python -r bindings/python/requirements.txt
35
+ ```
36
+
37
+ ```bash
38
+ cmake -S . -B build -DJBA_BUILD_PYTHON=ON -DPython_EXECUTABLE=$PWD/bindings/python/.venv/bin/python
39
+ ```
40
+
41
+ The package is assembled in `build/bindings/python/just_ba` and tested by `ctest`
42
+ (label `python`). To use it from that build:
43
+
44
+ ```bash
45
+ PYTHONPATH=build/bindings/python bindings/python/.venv/bin/python -c "import just_ba; print(just_ba.CameraModel.OPENCV)"
46
+ ```
47
+
48
+ Or install it like a released package, built through `pyproject.toml`
49
+ (scikit-build-core; CPU, and Metal on macOS):
50
+
51
+ ```bash
52
+ uv pip install --python bindings/python/.venv/bin/python .
53
+ ```
54
+
55
+ `uv build --wheel` writes the wheel to `dist/`; set `MACOSX_DEPLOYMENT_TARGET=13.0`
56
+ on macOS for a wheel that runs on macOS 13 and later.
57
+
58
+ The main entry point is `just_ba.refine(scene, keypoints, matches=...)`: a `Problem`
59
+ holding the camera and the pose priors, one `(n, 2)` keypoint array per image, and
60
+ pairwise matches `(m, 4)`. `just_ba.poses_from_camera_to_world(T, "arkit")` converts
61
+ ARKit or ARCore camera-to-world matrices to the library's poses. Optional inputs:
62
+ gravity priors (`grav_image`, `grav_dir`), line segments for the Manhattan prior
63
+ (`line_image`, `line_xy`, with `RefineOptions.use_manhattan`), and a depth reading per
64
+ keypoint (`refine(..., keypoint_depth=...)`). `just_ba.covariance(problem)` gives pose
65
+ and point covariances; `export_colmap` and `write_result` write the result.
66
+
67
+ ## Reference solver (test-only)
68
+
69
+ Ceres 2.2.0 is built separately, with Eigen only, and never linked into the library.
70
+
71
+ ```bash
72
+ cmake -DPREFIX=$PWD/build/ceres-2.2.0 -P third_party/ceres/build.cmake
73
+ ```
74
+
75
+ ```bash
76
+ python3 tests/data/fetch_bal.py
77
+ ```
78
+
79
+ ```bash
80
+ cmake -S . -B build -DJBA_WITH_CERES=ON -DCMAKE_PREFIX_PATH=$PWD/build/ceres-2.2.0
81
+ ```
82
+
83
+ ## Generated residuals
84
+
85
+ Residuals are written once in `residuals/symbolic/` and emitted for each target
86
+ into `residuals/generated/`, which is checked in. To regenerate:
87
+
88
+ ```bash
89
+ uv venv --python 3.12 residuals/symbolic/.venv && uv pip install --python residuals/symbolic/.venv/bin/python -r residuals/symbolic/requirements.txt
90
+ ```
91
+
92
+ ```bash
93
+ residuals/symbolic/.venv/bin/python residuals/symbolic/generate.py
94
+ ```
95
+
96
+ ## Command line
97
+
98
+ ```bash
99
+ build/cli/just-ba convert-bal problem.txt problem.jba
100
+ ```
101
+
102
+ ```bash
103
+ build/cli/just-ba info problem.jba
104
+ ```
105
+
106
+ ```bash
107
+ build/cli/just-ba solve problem.jba --loss huber:2 --output solved.jba --history history.json
108
+ ```
109
+
110
+ Run `build/cli/just-ba` without arguments for every option.
111
+
112
+ ## GPU backends (Metal, CUDA)
113
+
114
+ The solve can run on the GPU: `SolverOptions::backend = BackendKind::Metal` (Apple
115
+ GPUs) or `BackendKind::Cuda` (NVIDIA GPUs) in C++, `options.backend =
116
+ just_ba.Backend.METAL` or `CUDA` in Python, or:
117
+
118
+ ```bash
119
+ build/cli/just-ba solve problem.jba --backend metal
120
+ ```
121
+
122
+ Both work in single precision on the GPU and take every decision in double on the
123
+ host; their answers agree with the CPU's to single-precision tolerance, not bit for
124
+ bit (document 03, D91). They share one kernel source and one host side (D96). Their
125
+ `sparse_schur` forms the reduced camera system and factorizes it, with Accelerate
126
+ on Metal (its default, D92) and with NVIDIA cuDSS on CUDA when built with it (D98).
127
+ The documentation site is built from `docs-site/` (`docs-site/README.md`).
128
+
129
+ `ctest -L gpu` compares each GPU backend built with the CPU backend on every parity
130
+ problem. `python3 bench/gpu_check.py` runs the whole GPU check by hand: build, GPU and
131
+ Python tests, and the benchmark against this machine's baselines (`bench/README.md`).
132
+
133
+ Metal is built by default on macOS. CUDA needs the CUDA toolkit, 12 or later (the
134
+ CUDA sources are C++20, D113), and is built for the GPU of the build machine unless
135
+ `CMAKE_CUDA_ARCHITECTURES` is set:
136
+
137
+ ```bash
138
+ cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DJBA_WITH_CUDA=ON
139
+ ```
140
+
141
+ For `sparse_schur` on CUDA, add `-DJBA_WITH_CUDSS=ON -Dcudss_DIR=<cuDSS>/lib/cmake/cudss`
142
+ (cuDSS 1.0 or later, NVIDIA's redistributable).
143
+
144
+ ## Parity with Ceres
145
+
146
+ With the reference solver enabled, `build/tests/ceres/jba_parity <problem>` solves
147
+ the same problem with both solvers and checks the agreement (document 05).
148
+
149
+ ## Benchmark
150
+
151
+ `bench/run.py` solves the BAL problems and a few synthetic ones and compares
152
+ iteration counts, final costs and time per iteration with a stored baseline of the
153
+ same machine (`bench/README.md`, D81):
154
+
155
+ ```bash
156
+ python3 bench/run.py --build build --compare bench/baseline/apple-m5pro.json
157
+ ```
158
+
159
+ `--backend metal` benchmarks the Metal backend, and `--ceres` adds Ceres's times
160
+ on the same problems.
161
+
162
+ ## Real captures
163
+
164
+ `tests/real` runs `refine` from Python on every capture file it finds in `tests/data`
165
+ or `tests/data/real` (both git-ignored), or in `JBA_REAL_CAPTURES`, and skips when
166
+ there are none (D78). With the Python bindings built:
167
+
168
+ ```bash
169
+ ctest --test-dir build -L real -V
170
+ ```
171
+
172
+ ## Licence
173
+
174
+ Apache-2.0 (the licence file is added before the repository goes public).
@@ -0,0 +1,18 @@
1
+ # The library's public entry points, above core and the backends (document 03):
2
+ # solve, the residual report, and the refine pipeline. The C-level API will live
3
+ # here too.
4
+ add_library(jba STATIC src/solve.cpp src/report.cpp src/refine.cpp src/covariance.cpp src/export.cpp)
5
+ target_include_directories(jba PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/include)
6
+ target_link_libraries(jba PUBLIC jba_core jba_cpu jba_tracks PRIVATE jba_internal jba_warnings)
7
+ if(JBA_WITH_METAL)
8
+ target_link_libraries(jba PUBLIC jba_metal)
9
+ target_compile_definitions(jba PRIVATE JBA_HAVE_METAL=1)
10
+ endif()
11
+ if(JBA_WITH_WEBGPU)
12
+ target_link_libraries(jba PUBLIC jba_webgpu)
13
+ target_compile_definitions(jba PRIVATE JBA_HAVE_WEBGPU=1)
14
+ endif()
15
+ if(JBA_WITH_CUDA)
16
+ target_link_libraries(jba PUBLIC jba_cuda)
17
+ target_compile_definitions(jba PRIVATE JBA_HAVE_CUDA=1 $<$<BOOL:${JBA_WITH_CUDSS}>:JBA_HAVE_CUDSS=1>)
18
+ endif()
@@ -0,0 +1,45 @@
1
+ #pragma once
2
+
3
+ #include <cstddef>
4
+ #include <cstdint>
5
+ #include <vector>
6
+
7
+ #include "jba/problem.h"
8
+ #include "jba/solver.h"
9
+
10
+ namespace jba {
11
+
12
+ // Uncertainty of a solved problem (document 02, "Uncertainty of the result"): the
13
+ // inverse of the Gauss-Newton system at the current parameters, with the robust
14
+ // losses applied as in the solve, the camera side through the reduced system and
15
+ // points by back substitution. Meaningful as far as the input weights are: with
16
+ // default prior weights the values are relative, not calibrated. They are relative to
17
+ // the gauge the solve used (Covariance::gauge), and in the working frame.
18
+ struct CovarianceOptions {
19
+ std::vector<std::int32_t> points; // points to return, by index
20
+ bool all_points = false; // or every point
21
+ // The reduced system is inverted densely; above this many camera-side unknowns the
22
+ // call is refused (12,000 unknowns, 2,000 images, take about 1 GB).
23
+ std::size_t max_unknowns = 20000;
24
+ };
25
+
26
+ struct Covariance {
27
+ // Per image, 6 x 6 row-major in the pose tangent of D46: rotation (radians, camera
28
+ // axes, R <- Exp(dtheta) R), then translation t. Zeros for images that are not
29
+ // variables, and in held coordinates. For an image whose heading the gauge holds
30
+ // (D83) the rotation block is singular along the vertical in camera axes.
31
+ std::vector<double> pose;
32
+ // Per image, 3 x 3: the camera centre C = -R^T t, working frame, metres.
33
+ std::vector<double> centre;
34
+ // Per requested point, 3 x 3, working frame.
35
+ std::vector<std::int32_t> points;
36
+ std::vector<double> point;
37
+ Gauge gauge; // what was held
38
+ };
39
+
40
+ // Throws std::invalid_argument for an invalid problem, std::runtime_error when the
41
+ // system is singular (a freedom nothing holds) or too large.
42
+ Covariance covariance(const Problem& problem, const SolverOptions& options = {},
43
+ const CovarianceOptions& covariance_options = {});
44
+
45
+ } // namespace jba
@@ -0,0 +1,48 @@
1
+ #pragma once
2
+
3
+ #include <cstdint>
4
+ #include <string>
5
+ #include <vector>
6
+
7
+ #include "jba/covariance.h"
8
+ #include "jba/problem.h"
9
+ #include "jba/report.h"
10
+ #include "jba/tracks.h"
11
+
12
+ namespace jba {
13
+
14
+ // Export of a solved problem (document 01, outputs; D89): COLMAP's text model for
15
+ // interchange, and the library's own problem file with result sections for what
16
+ // COLMAP's format cannot hold.
17
+
18
+ struct ColmapExportOptions {
19
+ // Per image: the NAME column. Empty: "image_000000" and so on.
20
+ std::vector<std::string> image_names;
21
+ // Per intrinsics block: width, height. Empty: 2 cx and 2 cy, rounded up. COLMAP's
22
+ // pixel convention puts the centre of the first pixel at (0.5, 0.5); keypoints
23
+ // and principal points are written as they are, so they should follow it.
24
+ std::vector<std::int32_t> image_size;
25
+ // Per image, 1 to export. Empty: every image with an observation.
26
+ std::vector<char> images;
27
+ // Optional: every keypoint of each image and the keypoint of each observation, so
28
+ // POINTS2D lists all keypoints as COLMAP does (unobserved ones with POINT3D_ID -1).
29
+ // Without them, POINTS2D holds the observations.
30
+ const Keypoints* keypoints = nullptr;
31
+ std::vector<std::int32_t> obs_keypoint;
32
+ std::vector<std::uint8_t> point_color; // 3 per point; empty: grey
33
+ };
34
+
35
+ // Writes cameras.txt, images.txt and points3D.txt into `directory` (which must
36
+ // exist). IDs are indices plus one: camera = intrinsics block, image, point. A point
37
+ // is written when it has an observation in an exported image; its ERROR is the mean
38
+ // reprojection error there. Throws std::runtime_error.
39
+ void export_colmap(const Problem& problem, const std::string& directory, const ColmapExportOptions& options = {});
40
+
41
+ // The problem file of document 11 with `result.*` sections added (any already there
42
+ // are replaced): covariances, the residual report, and the keypoint of each
43
+ // observation, each when given. Sections are listed in document 11. Throws
44
+ // std::runtime_error.
45
+ void write_result(const std::string& path, const Problem& problem, const Covariance* covariance,
46
+ const ResidualReport* report, const std::vector<std::int32_t>* obs_keypoint = nullptr);
47
+
48
+ } // namespace jba
@@ -0,0 +1,101 @@
1
+ #pragma once
2
+
3
+ #include <cstdint>
4
+ #include <vector>
5
+
6
+ #include "jba/initialize.h"
7
+ #include "jba/manhattan.h"
8
+ #include "jba/problem.h"
9
+ #include "jba/report.h"
10
+ #include "jba/solver.h"
11
+ #include "jba/tracks.h"
12
+
13
+ namespace jba {
14
+
15
+ // The main use case end to end (document 01): keypoints, matches (or tracks) and
16
+ // noisy pose priors in, a refined reconstruction out.
17
+ //
18
+ // 1. Starting poses from the priors (initialize_poses); images without priors are
19
+ // left out and reported.
20
+ // 2. Optionally a pose-only solve over the priors. With the Manhattan prior on, the
21
+ // segments are then assigned (and the prior refused where the support test
22
+ // fails), and the pose-only solve is repeated with them, which removes heading
23
+ // drift before anything is triangulated.
24
+ // 3. Rounds of: tracks from the matches with the current poses (stages 1 and 2 of
25
+ // document 04), robust triangulation, solve, removal of outlier observations
26
+ // and weak points, solve again. Each round starts from the previous poses with
27
+ // a tighter triangulation threshold, and segments are assigned again to the
28
+ // current frame with a tighter angle (halved each round, down to
29
+ // manhattan_min_angle_deg).
30
+ struct RefineInput {
31
+ // Camera, pose priors and prior sets, as in a Problem. `poses` may be empty (all
32
+ // identity) or hold starting poses: a relative-prior group's root keeps its pose.
33
+ // Points and observations are ignored.
34
+ Problem scene;
35
+ Keypoints keypoints;
36
+ std::vector<double> keypoint_sigma; // per keypoint, pixels; empty means 1
37
+ // Depth at keypoints (document 02, section 4a): per keypoint, NaN for none; empty
38
+ // means no depth. scene.depth_kind, depth_form, depth_correction and
39
+ // depth_correction_free say what the readings are and what is estimated.
40
+ std::vector<double> keypoint_depth;
41
+ std::vector<double> keypoint_depth_sigma; // per keypoint, metres; empty: the default
42
+ // Either matches (4 values each: image_a, keypoint_a, image_b, keypoint_b) or
43
+ // tracks; tracks take precedence when not empty.
44
+ std::vector<std::int32_t> matches;
45
+ Tracks tracks;
46
+ // Line segments for the Manhattan prior are scene.line_image, line_xy and
47
+ // line_sigma; their axes are assigned by refine.
48
+ };
49
+
50
+ struct RefineOptions {
51
+ SolverOptions solver = [] {
52
+ SolverOptions o;
53
+ o.loss = {LossType::Cauchy, 2.0}; // document 02: reprojection is robust by default
54
+ return o;
55
+ }();
56
+ TrackOptions tracks;
57
+ int rounds = 2;
58
+ bool prior_solve = true; // step 2
59
+ double max_reprojection_error = 4; // pixels; COLMAP's default (document 04)
60
+ double min_tri_angle_deg = 1.5;
61
+ double downweight_threshold = 0.1; // for the report's down-weighted priors
62
+ bool largest_group_only = false; // otherwise every group is solved, each in its own frame
63
+ // An image counts as refined when at least this many inlier observations constrain
64
+ // its pose (COLMAP registers an image from 30 inliers). Images below it are still
65
+ // solved, but their poses come from the priors alone or nearly so (D76).
66
+ int min_observations = 30;
67
+ // Manhattan prior from scene's line segments (document 02, section 5). Opt-in: it
68
+ // is strong, and wrong where the scene is not Manhattan.
69
+ bool use_manhattan = false;
70
+ ManhattanOptions manhattan;
71
+ double manhattan_min_angle_deg = 1;
72
+ };
73
+
74
+ struct RefineResult {
75
+ // Solved problem: poses, points, inlier observations, priors, set transforms, and
76
+ // the losses refine solved with (loss.* sections when written).
77
+ Problem problem;
78
+ std::vector<std::int32_t> obs_keypoint; // keypoint (in its image) of each observation
79
+ std::vector<std::int32_t> group; // per image, from initialize_poses; -1 left out (no prior places it)
80
+ int num_groups = 0;
81
+ // Per image: 1 if it was solved and has at least min_observations inlier
82
+ // observations in `problem`. Images in a group but below that are solved with the
83
+ // rest; their poses follow the priors.
84
+ std::vector<char> refined;
85
+ std::vector<std::int32_t> num_observations; // per image, inlier observations in `problem`
86
+ ResidualReport report;
87
+ std::vector<SolverSummary> summaries; // every solve, in order
88
+ TrackStats track_stats; // of the last round
89
+ std::size_t rejected_observations = 0; // in the last round's filtering
90
+ // Priors of `problem` by their index in the input (priors of images left out are
91
+ // dropped). The report's down-weighted lists are already in input numbering.
92
+ std::vector<std::int32_t> relative_prior_index, global_prior_index, gravity_prior_index;
93
+ // The last assignment of the segments (one entry per input segment; segments of
94
+ // images left out are -1), the frame as solved, and whether the support test
95
+ // accepted the prior. Empty when use_manhattan is off.
96
+ ManhattanAssignment manhattan;
97
+ };
98
+
99
+ RefineResult refine(const RefineInput& input, const RefineOptions& options = {});
100
+
101
+ } // namespace jba
@@ -0,0 +1,53 @@
1
+ #pragma once
2
+
3
+ #include <cstdint>
4
+ #include <vector>
5
+
6
+ #include "jba/problem.h"
7
+ #include "jba/solver.h"
8
+
9
+ namespace jba {
10
+
11
+ // Per-residual diagnostics at the problem's current parameters (document 01,
12
+ // outputs): cost by residual type, reprojection errors, and how much each prior was
13
+ // down-weighted by its robust loss.
14
+ struct ResidualReport {
15
+ // 0.5 * sum rho, with the losses of `options`, by type; their sum is the
16
+ // solver's cost.
17
+ double reprojection_cost = 0;
18
+ double relative_prior_cost = 0;
19
+ double global_prior_cost = 0;
20
+ double gravity_cost = 0;
21
+ double line_cost = 0;
22
+ double depth_cost = 0; // depth readings and the priors on free corrections
23
+
24
+ // Per observation: reprojection error in pixels (not divided by sigma), and
25
+ // whether the point is in front of the camera.
26
+ std::vector<double> reprojection_error;
27
+ std::vector<char> in_front;
28
+
29
+ // Per prior: whitened residual norm (standard deviations) and robust weight
30
+ // rho'(s), 1 for a prior fully trusted, near 0 for one the solve overruled.
31
+ std::vector<double> relative_prior_norm, relative_prior_weight;
32
+ std::vector<double> global_prior_norm, global_prior_weight;
33
+ // Per gravity prior: angle between the measured and the solved gravity direction
34
+ // (radians), and the robust weight.
35
+ std::vector<double> gravity_angle, gravity_weight;
36
+ // Per segment: the angle (radians) by which its assigned axis misses the segment's
37
+ // plane, and the robust weight; NaN and 0 for segments not in the Manhattan term
38
+ // (unassigned, or the term off).
39
+ std::vector<double> line_angle, line_weight;
40
+ // Per observation with a depth reading (NaN elsewhere, weight 0): the refined depth
41
+ // of its point in the camera (as the readings measure it), the corrected reading
42
+ // a d + b, and the robust weight. Applying the image's correction to the whole
43
+ // depth map gives the refined map (document 02).
44
+ std::vector<double> depth_refined, depth_corrected, depth_weight;
45
+
46
+ // Priors whose weight fell below the threshold given to evaluate(): what the
47
+ // caller's cleanup let through (document 02).
48
+ std::vector<std::int32_t> downweighted_relative, downweighted_global, downweighted_gravity;
49
+ };
50
+
51
+ ResidualReport evaluate(const Problem& problem, const SolverOptions& options, double downweight_threshold = 0.1);
52
+
53
+ } // namespace jba