## Purpose
This repository is a Rust port of the C++ SupeRANSAC library located in `superansac_c++/`.
Our new port is called `inlier`; use this name when it make sense.
The primary goal is to provide a safe, idiomatic, and well-tested Rust implementation of the unified RANSAC pipeline for:
- Homography estimation
- Fundamental matrix estimation
- Essential matrix estimation
- Absolute pose estimation
- Rigid 3D–3D transformation estimation
The Rust crate should eventually expose a clean, ergonomic API comparable to the Python bindings described in `superansac_c++/README.md`, while not being bound to Python.
## High-level Architecture (Target)
Mirror the C++ library’s conceptual modules as Rust modules/crates:
- `camera` – camera models and intrinsics handling
- `data` – data abstractions for correspondences and related types
- `models` – geometric models (homography, F/F/E matrices, poses, transforms)
- `estimators` – minimal and non-minimal solvers per model
- `samplers` – RANSAC sampling strategies
- `scoring` – inlier scoring / robust loss handling
- `local_optimization` – LO strategies (graph-cut, IRLS, LSQ, etc.)
- `inlier_selection` – e.g. space-partitioning RANSAC selector
- `termination` – stopping criteria
- `settings` – configuration of the RANSAC pipeline
- `statistics` / `utils` – math helpers, random generators, shared utilities
- `core` – the SupeRANSAC pipeline orchestration (Rust equivalent of `SupeRansac::run`)
## Porting Strategy
1. **Start with core types and math utilities** that have minimal dependencies (settings, enums, basic data types, utilities).
2. **Define the central Rust pipeline type** (e.g. `SuperRansac` struct) and traits for sampler, estimator, scoring, etc.
3. **Incrementally port individual components** (samplers, scoring, estimators, termination, local optimization), one module at a time.
4. **After each module**, add unit tests and small integration tests that:
- Reproduce behavior on small synthetic data.
- Where feasible, compare against precomputed “golden” results dumped from the original C++ implementation.
5. **Add high-level APIs** for each of the primary estimation tasks (homography, fundamental, essential, absolute, rigid transform) once enough building blocks are in place.
Always prefer small, composable steps that can be validated in isolation.
## Testing & Verification
- For each ported component:
- Add unit tests in Rust (`tests/` or per-module `mod tests`) validating expected invariants and edge cases.
- Where realistic, leverage data from `superansac_c++/examples` and `superansac_c++/tests` to cross-check outputs.
- Add higher-level integration tests once a minimal end-to-end pipeline exists for at least one model (homography is a good first candidate).
## Conventions
- **Language**: Rust 2024 edition (see `Cargo.toml`).
- **Style**: Follow `rustfmt` defaults and idiomatic Rust naming:
- Types: `UpperCamelCase`
- Traits: `UpperCamelCase`
- Functions, methods, variables, modules: `snake_case`
- **Error handling**: Prefer `Result<T, E>` over panics; keep panics for programmer errors and invariant violations only.
- **Allocation & performance**:
- Avoid unnecessary heap allocations in hot loops (mirroring the C++ implementation’s performance-conscious design).
- Reuse buffers where appropriate.
## Agent Instructions (for AI / automated assistants)
- **Respect the checklist** in `docs/PORTING_CHECKLIST.md`:
- Do not jump ahead of the current phase unless explicitly requested.
- Update task statuses in that document when completing work.
- **Make small, reviewable changes**:
- Keep patches focused (one conceptual change per commit/patch).
- Prefer incremental enhancements over large refactors.
- **Tests first mentality**:
- When adding a new module, add at least minimal tests in the same patch.
- Do not significantly change behavior without extending or adjusting tests.
- **Documentation**:
- Update or add doc comments when introducing new public APIs.
- Leave short rationale comments when porting subtle numerical/algorithmic details from C++.
When in doubt, mirror behavior of the existing C++ implementation in `superansac_c++/` first, then iterate towards more idiomatic Rust in later passes.