cv-backend-spec: record the planar-homography pose ambiguity as an open question
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 11
- Forks
- 3
- Avg merge
- 12h 19m
- Merged PRs (30d)
- 26
Description
Summary
poseFromHomography returns exactly one Pose. A planar homography
decomposition is fundamentally two-fold ambiguous (Faugeras & Lustman);
ADR-0001 currently resolves that ambiguity above the contract, in the
tracker (IPPE, "two candidates") — which is where it already correctly
belongs per the ADR's own division of labour. This issue exists to record
the open question of whether that stays true, not to propose a signature
change yet.
Why
ADR-0001 point 3 draws the line explicitly: "work on tens of points ...
lives in the tracker" — pose disambiguation over one homography's two
solutions is exactly that shape of work (small, per-frame, needs temporal or
application context to pick a winner), not the "work proportional to the
pixels of a whole frame" that belongs in the backend. poseFromHomography
itself is documented as "pure geometry" with no notion of previous frames to
disambiguate against (packages/cv-backend-spec/src/cv_backend.ts:348-354)
— correctly so, since the contract is stateless.
The gap the ADR notes is narrower than "the contract is missing a feature":
it is that a second poseFromHomography implementation (PureCV), built
from scratch, could reasonably return either root of the ambiguity with no
contract text saying which — or whether returning the same one as
jsfeatNext is even guaranteed. That is untested today because there is
exactly one implementation.
Proposal
No signature change proposed here. Two options to weigh once a second
poseFromHomography implementation exists (recorded for that future
discussion, not decided now):
(a) Leave Pose exactly as-is, and add non-normative doc text stating
which root a backend should prefer when the two are numerically
distinguishable (e.g. "the one with positive depth" — the conventional
disambiguating criterion when the plane's true side is known), so
cross-backend behaviour converges without a type change.
(b) Add an optional second field carrying the other root:
export interface Pose {
R: Mat3;
t: Vec3;
good: boolean;
/**
* The homography decomposition's other geometrically valid root, when
* the two are numerically distinct — omitted when they coincide or the
* backend does not disambiguate. Lets a caller with temporal context
* (the tracker) choose between them; every reader of only `R`/`t`/`good`
* is unaffected.
*/
alternate?: Omit<Pose, "alternate">; // NEW, optional
}
Negotiation/compatibility
(a) has zero type-level footprint — documentation only, cannot break
anything. (b) is additive: alternate is optional, so the sole existing
implementation (cv-backend-jsfeatnext's poseFromHomography,
packages/cv-backend-jsfeatnext/src/jsfeatnext_backend.ts:538-554) and
every current reader keep compiling and behaving identically with it
omitted. Nothing in nft-tracker's current M1 tracker reads a Pose field
it wouldn't still have.
Out of scope
- Implementing IPPE anywhere — ADR-0001 M3, already scheduled,
contract-independent either way. - Choosing between (a) and (b). This issue is explicitly a placeholder for
that decision, appropriate once M3 or a second backend makes the
ambiguity concrete rather than hypothetical. - Any change to
poseFromHomography's signature today.
Related
- ADR-0001 point 3 (division of labour) and M3 (IPPE + One Euro filter).
- Contract:
packages/cv-backend-spec/src/cv_backend.ts(Pose,
poseFromHomography). - Reference: Faugeras & Lustman, Motion and Structure from Motion in a
Piecewise Planar Environment, IJPRAI 1988 — the classical two-fold planar
homography decomposition ambiguity IPPE also addresses.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with ADR-0001 points 3 and M3, then read packages/cv-backend-spec/src/cv_backend.ts:348-354 and packages/cv-backend-jsfeatnext/src/jsfeatnext_backend.ts:538-554. No implementation is requested now; this is complete when the ambiguity policy is decided and recorded after a second backend or M3 makes the question concrete.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- backend-api-design, documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100