Find the cheapest exact camera-filter and step-up-ring kit across every lens in your bag.
中文说明 · Try the workbench · Schema · Troubleshooting
Buying the cheapest route for each lens independently can cost more overall. RingRoute enumerates compatible filter/ring routes and minimizes the union of gear you need to buy. A filter or ring reused by seven routes is charged once.
It is a real, local-first optimizer—not a catalog mockup:
- exact bounded search with deterministic tie-breaks;
- shared-item pricing and owned-gear reuse;
- explicit lens-to-filter ring routes;
- strict versioned JSON and stable failure codes;
- the same dependency-free solver in the CLI and browser;
- no uploads, accounts, analytics, or runtime dependencies.
Node.js 22 or newer is required.
git clone https://github.com/KanadeK/ringroute.git
cd ringroute
npm ci --ignore-scripts
node bin/ringroute.js plan examples/creator-kit.jsonStart the browser workbench:
npm run build
npm startThen open http://127.0.0.1:4173/. The hosted workbench is available at kanadek.github.io/ringroute.
Install the packaged CLI from the v0.1.0 Release:
npm install --global https://github.com/KanadeK/ringroute/releases/download/v0.1.0/ringroute-0.1.0.tgz
ringroute plan examples/creator-kit.jsonringroute plan <catalog.json> [--format text|json] [--html <report.html>]
ringroute validate <catalog.json>
ringroute --help
ringroute --version
The committed creator example proves a plan for three lenses and three filter types:
Purchase: 17,300 USD minor units · 3 items · 64 g added
Buy:
- 58-67: 58 to 67mm brass step-up ring
- cpl-82: 82mm circular polarizer
- mist-82: 82mm diffusion filter
Owned and reused:
- 67-82: 67 to 82mm brass step-up ring
- nd-82: 82mm six-stop ND
Machine and shareable outputs:
ringroute plan examples/creator-kit.json --format json
ringroute plan examples/creator-kit.json --html plan.html
ringroute validate examples/infeasible.jsonThe last command intentionally succeeds at schema validation; plan then exits with INFEASIBLE because a larger lens cannot use a smaller filter.
{
"schemaVersion": 1,
"currency": "USD",
"lenses": [
{
"id": "portrait",
"name": "85mm prime",
"threadMm": 67,
"maxRings": 1,
"requires": ["cpl"]
}
],
"filters": [
{
"id": "cpl-82",
"type": "cpl",
"name": "82mm CPL",
"threadMm": 82,
"priceMinor": 12900,
"weightG": 35,
"owned": false
}
],
"rings": [
{
"id": "67-82",
"name": "67 to 82mm step-up ring",
"fromMm": 67,
"toMm": 82,
"priceMinor": 1200,
"weightG": 9,
"owned": true
}
],
"options": { "maxSearchStates": 250000 }
}Prices are integer minor currency units. Rings must strictly increase diameter; RingRoute never invents a step-down route. Unknown fields fail schema v1 validation so a typo cannot silently change a purchase plan. See the complete schema and input caps.
RingRoute first minimizes purchase cost, then purchased item count, then total selected weight, then stable item IDs. It:
- enumerates every compatible filter plus bounded ring path for each lens requirement;
- searches combinations while charging the selected item union once;
- prunes only branches that cannot beat the current complete plan;
- returns
optimalonly after the bounded search is exhausted.
If maxSearchStates is exhausted first, the process fails with SEARCH_LIMIT; it never labels an incumbent or heuristic as optimal. Read the algorithm note for the proof boundary.
| Code | CLI exit | Meaning | Repair |
|---|---|---|---|
VALIDATION_ERROR |
2 | Invalid JSON, strict-schema mismatch, unsafe display text, or unreadable input | Run ringroute validate FILE; fix the named JSON path, remove unknown fields, and retry. |
INFEASIBLE |
3 | At least one lens/filter requirement has no compatible route | Add a same/larger filter, add explicit increasing rings, or raise that lens's maxRings, then rerun plan. |
SEARCH_LIMIT |
4 | The proof budget ended before exhaustive completion | Remove dominated catalog choices or deliberately raise options.maxSearchStates; rerun and require exit 0 before using the plan. |
| unexpected | 1 | Filesystem/runtime failure | Confirm Node 22+, file permissions, and a clean install; rerun npm ci --ignore-scripts && npm run check. |
More symptoms and copy-ready recovery commands are in Troubleshooting.
A clean checkout is accepted with:
npm ci --ignore-scripts
npm run checknpm run check runs the test/coverage gate, builds the Pages workbench, exercises the real CLI, writes and inspects an HTML report, packs the npm archive, installs that archive into a temporary project, and proves the installed package reproduces the committed example.
To inspect release assets locally:
npm run release:assetsExpected files appear in ignored release/: the installable .tgz, example JSON plan, standalone HTML report, and one checksum manifest.
CI runs the same gate on Windows and Linux with Node 22 and 24. Tag pushes run it again before GitHub Release creation.
RingRoute optimizes the catalog and constraints you supply. It does not predict vignetting, hood clearance, thread quality, or safe stacking for a specific lens/filter combination. Step-up practice is grounded in general guidance from B&H and NiSi, but every assembled route must be physically tested before a shoot.
- Schema v1
- Exact-search design
- Selection research
- Architecture decisions
- Troubleshooting
- Contributing
- Security
- Changelog
MIT © 2026 KanadeK
