[kalwalt]

Design and implementation plan for the FREAK descriptor (#80). Docs only, no code.

• Design: docs/superpowers/specs/2026-10-30-freak-design.md. Decisions F1–F6:
  • F1: pattern points are computed on demand, so OpenCV's 8.5 MB table is not ported.
  • F2: border keypoints are dropped as OpenCV drops them. corners is compacted in place, and describe returns the kept count.
  • F3: all four OpenCV parameters are exposed as options.
  • F4: the ground truth is the same as TEBLID's.
  • F5: the angle is OpenCV's, in (−180°, 180°]. FREAK-then-TEBLID diverges from OpenCV on negative angles, and this is documented.
  • F6: freak.cpp is BSD-3-Clause (EPFL), not Apache-2.0. Its notice ships verbatim as LICENSES/BSD-3-Clause-FREAK.txt.
• Plan: docs/superpowers/plans/2026-10-30-freak.md, in 7 tasks: fixtures, tables and licence, engine, wiring, bench, example, docs.

The implementation will follow in its own PR.

Refs #80

🤖 Generated with Claude Code

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

Tip of the day

💡 Did you know, you can route each severity your way: inline, summary, both, or drop

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[qodo-free-for-open-source-projects]

PR Summary by Qodo

Document FREAK descriptor design and implementation plan

📝 Documentation 🕐 20-40 Minutes

AI Description

• Define OpenCV-compatible FREAK behavior, including border filtering, angle handling, and memory
 limits.
• Plan seven implementation tasks covering fixtures, licensing, the descriptor engine, integration,
 benchmarks, and examples.
• Defer code and runtime behavior changes to a separate PR.

Diagram

graph TD
  A["Image and keypoints"] --> B["Integral image"] --> C{"Border filter"} -->|kept| D["On-demand samples"] --> E["Orientation and bits"] --> F["Descriptor rows"]
  C -->|dropped| G["Skip keypoint"]
  C -->|compacts| H["Kept keypoints"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Cache sampled patterns per call

• ➕ Could reduce repeated sampling work for keypoints sharing a scale and orientation.
• ➕ Can retain bit-exact samples without a persistent multi-megabyte table.
• ➖ Adds cache complexity and memory use.
• ➖ The benefit is unmeasured until the planned benchmarks run.

Recommendation: Keep on-demand sampling as the implementation baseline: it satisfies the explicit memory constraint without changing OpenCV's pattern. The plan already permits a per-call cache if benchmarks justify it; retain the pinned parity fixtures as the acceptance gate.

Files changed (2) +470 / -0

Documentation (2) +470 / -0

2026-10-30-freak.mdLay out seven tasks for implementing and validating FREAK +247/-0

Lay out seven tasks for implementing and validating FREAK

• Adds a staged plan for OpenCV fixtures, pair tables and BSD licensing, the descriptor engine, public exports, benchmarks, an example, and final documentation. Specifies parity and property tests, review risks, and checks required during the future implementation.

docs/superpowers/plans/2026-10-30-freak.md

2026-10-30-freak-design.mdSpecify FREAK compatibility decisions and public API +223/-0

Specify FREAK compatibility decisions and public API

• Defines the proposed descriptor contract, including in-place keypoint compaction, OpenCV angle semantics, four options, and on-demand pattern computation. Records numerical parity requirements, fixture coverage, licensing obligations, and downstream adapter considerations.

docs/superpowers/specs/2026-10-30-freak-design.md