Skip to content
KanadeKPublic

About

Exact local-first optimizer for camera filters and step-up rings.

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

RingRoute

Find the cheapest exact camera-filter and step-up-ring kit across every lens in your bag.

CI Live workbench Release License: MIT Node 22+

中文说明 · Try the workbench · Schema · Troubleshooting

RingRoute browser workbench

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.

Quick start

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.json

Start the browser workbench:

npm run build
npm start

Then 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.json

CLI

ringroute 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.json

The last command intentionally succeeds at schema validation; plan then exits with INFEASIBLE because a larger lens cannot use a smaller filter.

Catalog in 60 seconds

{
  "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.

What “optimal” means

RingRoute first minimizes purchase cost, then purchased item count, then total selected weight, then stable item IDs. It:

  1. enumerates every compatible filter plus bounded ring path for each lens requirement;
  2. searches combinations while charging the selected item union once;
  3. prunes only branches that cannot beat the current complete plan;
  4. returns optimal only 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.

Failure codes and repair

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.

Acceptance gate

A clean checkout is accepted with:

npm ci --ignore-scripts
npm run check

npm 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:assets

Expected 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.

Scope and physical safety

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.

Project docs

MIT © 2026 KanadeK

About

Exact local-first optimizer for camera filters and step-up rings.

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages