Complex identification: the field guide

The one-page working reference. The concept page explains why it works this way and the authoring page covers building a pack from scratch; this page is what you keep open while running one. Examples use the shipped garden-survey pack.

The mental model, in six steps

1. Detect. Every sampled frame is scanned: the wide-net model pass proposes codeable things with boxes, and free geometric detectors add candidates the model misses (thin linear features especially).
2. Track. Proposals are followed across frames. One physical thing = one track, however many frames it appears in. Code flip-flop within a family never splits a track.
3. Funnel. Free checks decide what deserves a paid call: an area floor, shape routing for thin candidates, sheet screening for unproposed regions, the registry gates run on proposals, and tracks cluster into whole features.
4. Confirm. Each feature gets ONE model call with its best views, the stage-1 proposal, and a verdict expected: confirm, reclassify with a reason, or withdraw.
5. Gate. The answer passes the deterministic gates: enum lock, legality, surface, region, host, channel, extent, residual, readings, grade lookup. Anything contradictory is kept and flagged to review, never dropped, never silently accepted.
6. Record. Instances project to records per each code's record mode; the report collapses runs to start-finish, the portal layer keeps every frame.

One sentence: the model sees, the standard decides, and everything doubtful goes to review with its reason attached.

Commands

# codebook lifecycle
neuraframe codebook                  # what pack is set, and the reuse setting
neuraframe codebook check DIR        # validate a pack: every problem listed, nothing silent
sudo neuraframe codebook use DIR     # set the pack
sudo neuraframe codebook off
neuraframe codebook reuse on|off     # reuse gate while coding (default off)

# the runner
neuraframe codebook run --input FILE_OR_FRAMEDIR --out DIR [--config run.json] [--stub]
neuraframe codebook run --help       # every run-block knob as a --flag

--stub runs the whole spine with zero model calls. Use it before every live run and after any pack edit. A folder of ordered frames works as input too. Common overrides (flags win over the config file):

--sample-fps 4                       # examine more frames per second (0 = every frame)
--start-ms 60000 --end-ms 120000     # code one window of the footage
--equirect off                       # flat footage instead of 360
--detector local                     # free detection instead of the model wide net
--residual-pass on                   # second look after masking confirmed findings
--workers 8                          # concurrent confirmation calls

The pack: seven files, all yours

my_pack/
  manifest.json    the domain tables: context, bands, legality, regions, hosts, readings, surfaces
  registry.json    every code: family, mode, grading, evidence, hosts, regions, floors
  rules.md         domain knowledge, rides on EVERY model call
  detect.md        task framing for the wide-net pass (used verbatim)
  confirm.md       task framing for the confirmation pass (used verbatim)
  notes.md         optional standing site guidance, appended to confirmations
  excluded.json    codes out of scope for this deployment

Edits to the .md files apply on the next run, no rebuild. After editing the .json files, run check, then use again.

A registry entry, every key that matters

{"code": "WGD", "title": "Growth, dense run",
 "family": "growth",              groups codes for tracking and remap; families never merge
 "record_mode": "EXTENSIVE",      SINGULAR point | EXTENSIVE run | REPEATED per host |
                                  PROMOTABLE point-that-can-become-run | STATE reader
 "graded": true, "band_set": "A",
 "grading": {"ornamental": {"type": "threshold", "rules": [
     {"band": "<=10", "grade": 2}, ...]}},   per context column; fixed or threshold
 "expected_region": "ground",     geometric legality, checked against OUR tracked position
 "evidence_primary": "L",         L structure | C colour | T rate and motion
 "requires_host": ["stake"],      what must independently exist nearby (manifest hosts says how)
 "state_trigger": "survey_start", STATE only: survey_start (always exists, anchored at start)
                                  | on_change (exists ONLY at a transition; absent is normal)
 "residual_code": true,           a last-resort bucket: rejections required, downgrades logged
 "min_extent": {"min_sightings": 6, "min_clock_span_hours": 3},  extent floor, BOTH must hold
 "anchored": true,                survey structure from the job header, never inferred from imagery
 "position_constraint": "survey_boundary",   may only exist at the survey start or end
 "clock_applicable": false,       occupies the full view; a position-localised candidate is not it
 "fields": {"cont": "-"}}         cont "-" forbids a run for this code

Rule of thumb: the model only ever answers what a camera can see (a code, a band, real or not, a note, declared readings). Everything else in the entry is deterministic engine work.

The manifest tables, what each does

run config: the four blocks

One JSON (--config): run (sampling, detection, funnel, tracking - also CLI flags), coder (endpoint, dossier, location, channels), records (projection and verification thresholds), context (the job facts). The Vision CLI reference documents every knob; the ones you will actually reach for:

Outputs

The review queue, decoded

The review queue is the recode workbench: everything the engine kept but would not certify, each with its reason. What the reasons mean:

The numbers to watch

• The funnel line - raw detections, past the floor, tracks, screened, pregated, features, confirm calls. Where the money went.
• not_a_finding rate - under ~20% is healthy. High means incoherent dossiers or a leaking funnel, not a careful model.
• The conversion table - proposed vs recorded, per code. A code proposed hundreds of times and recorded zero is a systematic override, not a series of judgments.
• code_mix - the top code's share of findings. Most findings on one code is a degenerate distribution whichever code it is.
• Portal sanity - sighting counts equal portal rows, exactly; the run warns if not.
• Clean-scene calibration - run footage with nothing in it; the target is zero emissions, and everything emitted is a false positive by construction.

Recipes

• Flat (non-360) footage: --equirect off, and consider coder.location_mode: "grid".
• Cheaper pass: --detector local --sample-fps 1. Less accurate; the funnel still runs.
• Something got missed: check the review queue first (it is usually there), then the conversion table, then --residual-pass on for overlapping conditions.
• The model keeps confusing two codes: add a discriminator line to rules.md. It rides on every call, next run, no rebuild.
• Tune a floor or threshold: registry min_extent, the run-block knobs, the records thresholds - all policy, all yours. Re-run check after registry edits.
• One-off site guidance: point coder.notes_file at a text file for that job.
• Prove a fresh install, free: python3 vision/nf_codebook_board.py runs the mechanism board; --stub proves your pack and config end to end.