Metadata-Version: 2.4
Name: geodispbench3d
Version: 0.2.0
Summary: Benchmark framework for 3D displacement / optical-flow tools, with Bayesian hyperparameter sweeps and pluggable adapters.
Author-email: Nicholas Meyer <meyernic@ethz.ch>
License: BSD-3-Clause
Project-URL: homepage, https://gseg.igp.ethz.ch/
Project-URL: repository, https://github.com/gseg-ethz/geodispbench3d
Project-URL: issues, https://github.com/gseg-ethz/geodispbench3d/issues
Project-URL: Documentation, https://github.com/gseg-ethz/geodispbench3d/blob/main/docs/source/index.md
Project-URL: Changelog, https://github.com/gseg-ethz/geodispbench3d/blob/main/CHANGELOG.md
Keywords: benchmark,point-cloud,optical-flow,displacement,ax,hydra
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Requires-Python: ~=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy~=2.0
Requires-Dist: pandas
Requires-Dist: pyarrow>=16
Requires-Dist: omegaconf~=2.3
Requires-Dist: hydra-core~=1.3
Requires-Dist: ax-platform<2.0,>=1.3
Provides-Extra: dashboard
Requires-Dist: streamlit~=1.41; extra == "dashboard"
Requires-Dist: altair~=5.4; extra == "dashboard"
Requires-Dist: duckdb~=1.4; extra == "dashboard"
Provides-Extra: f2s3
Requires-Dist: pchandler~=2.1; extra == "f2s3"
Provides-Extra: dev
Requires-Dist: ruff~=0.15; extra == "dev"
Requires-Dist: pyright~=1.1; extra == "dev"
Requires-Dist: pre-commit~=4.3; extra == "dev"
Requires-Dist: pytest~=8.4; extra == "dev"
Requires-Dist: coverage~=7.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx~=8.1; extra == "docs"
Requires-Dist: myst-parser~=4.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme~=3.0; extra == "docs"
Dynamic: license-file

# geodispbench3d

A benchmark framework for 3D displacement / optical-flow tools, with
Bayesian hyperparameter sweeps via [Ax](https://ax.dev) and pluggable
adapters for any tool that can be invoked via CLI or Python.

Ships with two pre-built tool integrations:

- **iof3D** — the optical-flow-on-point-clouds pipeline.
- **F2S3** — feature-to-supervoxel cross-correlation.

Adding a new tool is a YAML-and-glue exercise; see the
[integration guide](docs/integrating/index.md).

## Install

The framework alone (no tool deps):

```bash
pip install geodispbench3d
```

With the iof3D adapter (transitively pulls in iof3D and its dependencies):

```bash
pip install 'geodispbench3d[iof3d]'
```

> **Note:** the `[iof3d]` extra is currently unavailable on public PyPI until
> iof3D is published publicly. The iof3D adapter ships in the wheel but stays
> dormant until then.

With the F2S3 adapter:

```bash
pip install 'geodispbench3d[f2s3]'
```

With the Streamlit dashboard:

```bash
pip install 'geodispbench3d[dashboard]'
```

Combinable: `pip install 'geodispbench3d[f2s3,dashboard]'`.

## Quickstart

```bash
# Run a sweep
geodispbench3d run benchmarks/suites/f2s3_voxel_refine.yaml

# Inspect results
geodispbench3d dashboard --parquet outputs/f2s3_voxel_refine.parquet

# Inspect a metrics file
geodispbench3d list-metrics benchmarks/metrics/pointing_error.yaml
```

See [docs/quickstart.md](docs/quickstart.md) for a five-minute walkthrough,
[docs/concepts.md](docs/concepts.md) for the architecture, and
[docs/integrating/index.md](docs/integrating/index.md) when you want to plug
in your own tool.

## Repository layout

```
src/
├── geodispbench3d/                  framework (no tool deps)
├── geodispbench3d_iof3d/            iof3D adapter (ships in the wheel; dormant until iof3D is public)
└── geodispbench3d_f2s3/             F2S3 adapter (gated by [f2s3] extra)

benchmarks/
├── data/                            ground-truth files
├── datasets/                        dataset YAMLs (tool-agnostic)
├── metrics/                         metric definitions
└── suites/                          composed sweeps you actually run

docs/                                user documentation
examples/                            small synthetic walkthroughs
tests/                               core / iof3d / f2s3 test suites
```

## License

Released under the BSD-3-Clause license — see `LICENSE`.
