bbsolver

bbsolver is a standalone C++ solver for reducing dense sampled animation into sparse editable keyframes inside an explicit error budget. It handles scalar, vector, spatial, and path-heavy workflows, including fixed and variable-topology Shape Path data, while keeping the host integration contract JSON-only.

What it does

• Reads dense evaluated samples from a host application.
• Writes sparse editable key bundles back to the host.
• Preserves an explicit property-unit or screen-pixel tolerance.
• Supports scalar, vector, separated-position, motion-path, and Shape Path flows.
• Emits progress, diagnostics, cancellation, and verification output for host applications.

bbsolver is not a generic sample decimator. The normal solve path accepts an output only when reconstructed values stay within the configured accuracy budget.

Use cases

These examples show the kinds of dense animation data bbsolver is designed to turn back into editable keyframes.

Expression Bake + Vertex Optimization

Expression-driven stable-topology path animation is optimized while preserving the path shape within tolerance.

ik-expression-driven-path-optimization-stable-topology.mp4

Rig Bake + Unparent

Parented/rigged Position motion is sampled in context, solved, written back, and unparented.

duik-walkcycle-solve-unparent.mp4

Motion Sketch Cleanup

Dense hand-drawn Position samples become a cleaner keyed motion path.

motion-sketch-path-optimization.mp4

Quickstart

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j

./build/bbsolver solve \
  examples/json/minimal_scalar.bbsm.json \
  /tmp/minimal_scalar.bbky.json
./build/bbsolver verify \
  /tmp/minimal_scalar.bbky.json \
  examples/json/minimal_scalar.bbsm.json

Windows:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release -j

.\build\Release\bbsolver.exe solve `
  examples\json\minimal_scalar.bbsm.json `
  $env:TEMP\minimal_scalar.bbky.json
.\build\Release\bbsolver.exe verify `
  $env:TEMP\minimal_scalar.bbky.json `
  examples\json\minimal_scalar.bbsm.json

See docs/QUICKSTART.md and examples/json/README.md for the full smoke loop.

Integration surface

The stable host contract is:

1. Sample host animation into SampleBundle JSON.
2. Run bbsolver solve input.bbsm.json output.bbky.json.
3. Read KeyBundle JSON.
4. Write keys back to the host.
5. Optionally run bbsolver verify output.bbky.json input.bbsm.json.

The public protocol is JSON-only via:

• schemas/sample_bundle.schema.json
• schemas/key_bundle.schema.json

The CMake package exports bbsolver::bbsolver for the CLI and bbsolver::core for tightly controlled embedding/tests. See docs/INTEGRATION_MAP.md, docs/SOLVER_CLI.md, and docs/PACKAGING.md.

Repository layout

bbsolver/
|-- CMakeLists.txt
|-- CMakePresets.json
|-- README.md
|-- LICENSE
|-- CHANGELOG.md
|-- CONTRIBUTING.md
|-- SECURITY.md
|-- cmake/
|-- include/bbsolver/
|-- src/
|-- schemas/
|-- examples/
|   |-- json/
|   |-- after-effects/
|   `-- blender/
|-- docs/
|-- tests/
|-- scripts/
|-- third_party/
|-- .github/
`-- research/
    |-- README.md
    |-- RESULTS.md
    |-- corpus/
    |-- results/
    |-- reproducibility/
    |-- fixtures/
    |-- case_studies/
    |-- external_runners/
    |-- media/
    `-- archive/

research/ contains the paper/reproducibility corpus, result figures, supplementary tables, external baseline runners, demo links, and archived design material. It is not required to build or integrate the solver and is not installed as part of the solver package.

Examples

• examples/json/: small runnable SampleBundle inputs.
• examples/after-effects/: ExtendScript/ScriptUI sampling, CLI invocation, KeyBundle parsing, and writeback example.
• examples/blender/: Blender-oriented integration material.

Build and test

Requirements: CMake 3.20+, a C++17 compiler, and platform build tools. The build resolves Ceres, Eigen, oneTBB, and nlohmann/json through installed package configs, pinned upstream downloads, or hash-locked fallback archives in third_party/archive/.

cmake -S . -B build -DBBSOLVER_BUILD_TESTS=ON
cmake --build build -j
ctest --test-dir build --output-on-failure -j 8

Normal CI and local unit runs do not build paper/research corpus tests. Enable them explicitly when validating the research artifact:

cmake -S . -B build-research \
  -DCMAKE_BUILD_TYPE=Release \
  -DBBSOLVER_BUILD_TESTS=ON \
  -DBBSOLVER_ENABLE_RESEARCH_TESTS=ON
cmake --build build-research -j
ctest --test-dir build-research -L research --output-on-failure

Run the standalone package validator before releases:

python3 scripts/validate_standalone_package.py

Documentation

• docs/QUICKSTART.md
• docs/INTEGRATION_MAP.md
• docs/SOLVER_CLI.md
• docs/API_REFERENCE.md
• docs/AE_SCRIPTUI_HARNESS.md
• docs/USER_GUIDE.md
• docs/TUNING_GUIDE.md
• docs/DP_ALGORITHM.md
• docs/PATH_HANDLING.md
• docs/PACKAGING.md
• docs/DEVELOPER_GUIDE.md
• docs/TEST_CATALOG.md
• docs/RELEASE_PROCESS.md

Research artifact and benchmarks

In a source checkout, the paper/research artifact lives under research/. Binary release archives and installed CMake packages do not include this directory; use the GitHub source tree or a dedicated research artifact release asset for those files. Start with research/README.md and research/RESULTS.md.

Historical FlatBuffers schema sketches, if needed for provenance, live under research/archive/flatbuffers-protocol/. They are not part of the build, package, CLI, runtime IO, or public C++ headers.

License

MIT. See LICENSE.