Vision CLI reference
Every vision command and every knob in one place: the vision command set, the continuous video knobs, the codebook command set, and the complete run configuration for complex identification. Settings apply after a service restart; batch runs read them at launch.
neuraframe vision
neuraframe vision # status: mode, threshold, match paths, continuous knobs neuraframe vision on | off neuraframe vision mode off|exact|near|scene|continuous neuraframe vision threshold N # near-match strictness, 0..100 (default 90) neuraframe vision field dotted.path # where the image travels in your JSON requests neuraframe vision match p1,p2,... # which request paths are vision (default /v1/vision, /predict, /infer, /detect, /classify) neuraframe vision boxes dotted.path|off # your detector's detections list: enables the region path neuraframe vision box_format xyxy_abs|xyxy_norm|xywh_abs|xywh_norm|cxcywh_abs|cxcywh_norm neuraframe vision box_key name # the box field inside each detection (default box) neuraframe vision memory # the visual workspace: what it knows, what it avoided sending
Modes: exact reuses byte-identical repeats only; near reuses near-duplicate scenes at the model's own answer; scene reuses per entity and region (a moved, rotated, scaled or relit thing is reused; a material change never silently); continuous treats ordered frames as one connected experience. Near and above need numpy and Pillow; the CLI says so if they are missing.
neuraframe vision continuous (the video knobs)
neuraframe vision continuous # list every knob with current value and default neuraframe vision continuous KEY VALUE # set one
| Knob | Default | What it does |
|---|---|---|
equirect | off | 360 / equirectangular video: the frame wraps left to right. |
lookahead_frames | 0 | Prerecorded look-ahead: wait up to N frames for a better view before calling the model (0 = decide live). |
max_ai_calls | 0 | Hard cap on model calls per stream (0 = unlimited). |
max_full_frame_calls | 0 | Hard cap on whole-frame escalations per stream (0 = unlimited). |
minimum_track_frames | 2 | Persistence gate: a feature must persist N frames before it is classified. Raise to suppress moving background; lower to react faster. |
miss_to_close | 12 | Frames a thing may be missing before its track closes (occlusion and leave-and-return tolerance). |
confidence_threshold | 0.75 | Confidence at which a track's label is finalised. |
min_classify_area_frac | 0.01 | Ignore specks smaller than this fraction of the frame. |
urgent_area_frac | 0.12 | Live: a sudden change at least this fraction of the frame escalates at once. |
keep_best_view_images | on | Keep each tracked thing's best-view image for read-back (off saves memory on very long live streams). |
fast_memory | on | Bounded visual-memory search plus consolidation: measured identical decisions to the linear memory, with flat cost as the store grows. Applies to scene AND continuous. |
colour | on | Opponent-colour identity: a hue swap can never silently reuse, and an object at the exact background brightness is still seen. Only ever adds a call. Scene and continuous. |
motion | on | Motion recovery on sequences: a camouflaged mover invisible to single-frame appearance is still found. Only ever adds an escalation. Scene and continuous. |
use_edges | off | Edge ridge splitting: separates touching objects on piecewise-flat scenes, but over-segments texture, hence off by default. Scene and continuous. |
Live streams go through the gateway with an X-NeuraFrame-Stream header; a video file or frame folder uses the shipped runner vision/nf_continuous.py.
neuraframe codebook
neuraframe codebook # current pack + reuse setting neuraframe codebook check DIR # validate a pack; every problem listed neuraframe codebook use DIR | off neuraframe codebook reuse on|off # reuse gate while coding (default off) neuraframe codebook run --input F --out D [--config J] [--stub] [flags...]
codebook run: the complete configuration
Four blocks in one JSON file (--config). The run block's keys are also command-line flags (--sample-fps and so on, via run --help); the other blocks live in the file. Every run writes the configuration in force into its output, so two runs are always comparable.
run: sampling, detection, tracking
| Key | Default | What it does |
|---|---|---|
sample_fps | 2.0 | Frames per second sampled from the footage. 0 = every frame. |
start_ms / end_ms | 0 / 0 | Clip window (0 end = to the end). |
max_frames | 0 | Hard cap on frames processed (0 = no cap). |
detector | local | local: free contrast/colour detection. model: propose-then-confirm (a wide-net model pass per frame, then dossier confirmation): the accuracy architecture, one call per sampled frame on top of one per finding. |
equirect | off | 360 / equirectangular footage: track association measures distance ACROSS the left-right seam, so a thing leaving one edge re-enters the other as the same thing. Turn on for 360 video (clock locations are seam-correct either way). |
scale_px | 1280 | Frames are downscaled to this longest side before analysis (0 = native). Locations are fractions, so nothing downstream changes. |
min_area | 60 | Smallest component that can be an entity (absolute pixels at analysis scale). |
min_area_frac | 0.0005 | The area floor as a FRACTION of frame area (0.05%); the real floor is the larger of the two, so it survives a resolution change. Detection noise and codeable regions separate almost perfectly by area on most rigs: calibrate once by splitting your detections into proposed vs un-proposed and putting the floor between the populations. 0 disables. |
max_entities | 12 | Entities per frame (local detector). |
use_motion | off | Motion recovery for camouflaged movers. Off in the batch runner (expensive at video resolution); turn on when movers hide against their background. |
use_edges | off | Edge ridge splitting. Separates touching objects on flat scenes; over-segments texture, hence off. |
use_l_detector | on | The flat-fielded luminance channel also runs as a detector and unions its candidates: features that lighting flattened out of the colour imagery are found. Image transforms are cheap; model calls are not. |
use_ridge_detector | on | Ridge (dark-line) response on the luminance channel proposes LINEAR features geometrically, with no model call. A wide-net proposer sees what is big and obvious and is blind to thin linear features; they are found by shape instead, at working resolution. |
route_linear | on | Shape routing for un-proposed regions: long-and-thin candidates skip sheet screening (a hairline is a few pixels wide and cannot survive a downscaled contact sheet) and go straight to a confirmation dossier with linear framing. Linear candidates are also exempt from the area floor - a line is judged by length, not area. |
linear_aspect_min / linear_min_long_px | 4.0 / 100 | What counts as linear: at least this elongated, and at least this long (analysis-scale pixels). |
residual_pass | off | Subtract-what's-confirmed second look for overlapping conditions: masks each confirmed finding's box-and-time extent and codes what remains. Strictly additive, one extra pass, priced as a second detection sweep. |
require_proposal | on | Model detector only: a track must carry a stage-1 proposed code to earn a confirmation dossier. An un-proposed region has no hypothesis to test and is invisible to every cheap gate; it never gets a paid call of its own. |
screen_unproposed | on | Un-proposed regions are batch-SCREENED instead of discarded: one call per numbered sheet of crops, each answered code-or-none; coded crops promote into the confirm pass, the rest leave the funnel (their per-frame annotations remain). Never one call per blob. |
screen_batch | 12 | Crops per screening sheet. |
pregates | on | The registry gates run on the PROPOSAL before any call: legality, region-vs-location, host requirements, channel evidence. Gates on the answer catch mistakes; gates on the proposal prevent the call. Pre-gated candidates go to the review queue marked pregate_, at zero spend, and the post-answer gates still run on everything that is called. |
cluster_features | on | Tracks cluster into candidate FEATURES before dossiers - tight on clock, generous on time. A feature inherits every member sighting, matching near-miss blips are absorbed as sightings, and run-mode records report start-finish. Never across evidence shape (linear vs area), never across defect class, and STATE codes never cluster (their instances are value samples; the change between them is the record). One dossier per feature, views sampled across its whole span. |
residual_review_votes | 5 | A residual (catch-all) answer overriding a specific stage-1 proposal with at least this many frame votes routes to review instead of certifying. Downgrade events are logged with both codes either way, and residual answers always require explicit rejections of the specific alternatives. |
cluster_run_clock_span | 2 | The tight axis: members of a run-capable feature must be within this many clock positions (wrap-aware). A band genuinely wrapping around grows by chaining through adjacent members; unrelated material five positions away never merges in one jump. Point-like codes stay at 1. Dossier coherence is what this protects - a rising not_a_finding rate is the tell that it is set too loose. |
feature_gap_ms | 4000 | The generous axis: a feature extends in time for as long as gaps stay under this window, however long it runs. Keep equal to records.merge_gap_ms: it is the same physical-identity constant. |
save_portal | on | Write portal.jsonl: one row per FRAME per coded feature, every row carrying the full schema (feature_id, frame_ref, that frame's own clock span, a relation - "within" a continuous condition, "at" a point one - and a feature block with record_mode, anchor, and sighting_count). No ranges, no start/finish, no run shapes: those belong to the report layer. The run checks the sanity identity every time: sighting counts must equal the row count exactly. |
match_min_sim | 62 | Perceptual-code similarity (0..100) to associate a detection to a track (local detector; the model detector associates by proposed code + proximity). |
match_max_dist | 0.22 | Max centre distance (frame fraction) to associate. |
match_yaw_weight / match_pitch_weight | 2.0 / 0.5 | Equirect only: anisotropic association. On unwrapped 360 footage the horizontal axis IS the clock position and barely moves as the camera approaches, while the vertical axis sweeps fastest right at closest approach - so the metric is tight in yaw and generous in pitch. 1.0 / 1.0 restores the isotropic distance; ignored when equirect is off. |
track_forget_ms | 2500 | A track unseen this long is closed. |
min_seen | 2 | Persistence gate: sightings needed to qualify for coding (singles go to review, never silently dropped). |
best_views_kept | 8 | Candidate views kept per track, scored by sharp_weight / size_weight / glare_penalty. |
workers | 4 | Concurrent confirmation calls (each finding is independent). |
save_dossiers / save_annotations | on / on | Keep the dossier images and the per-frame layer-1 annotations. |
price_in / price_out | 0 / 0 | Your model price per 1M tokens; when set, the cost block also shows dollars. |
coder: the model call and the dossier
| Key | Default | What it does |
|---|---|---|
url, key_file, model | - | The endpoint (OpenAI-style chat completions or your gateway), your key file, the model name. |
views_per_dossier | 4 | How many frames of the same finding ride together in ONE confirmation call: the multi-view evidence a single frame cannot give. The dossier takes the spread: first sight, closest look, last sight. |
burn_boxes / burn_labels | on / on | Draw the box and the location label on each view. |
max_view_px | 640 | Views are downscaled to fit (longest side) before composing. |
jpeg_quality | 88 | Dossier image quality. |
location_mode | clock | clock (angle around the frame centre, for unwrapped 360) | grid (3x3 zones) | none. With center_x/center_y, clock_offset_deg, roll_deg, and roll_file (per-frame roll telemetry, JSONL). |
notes_file | - | Per-job operator notes, appended to confirmations after the pack's notes.md. |
timeout_s / retries / max_output_tokens | 60 / 3 / 1200 | Transport behaviour. Parameter quirks are adapted, refusals are flagged answers, the real HTTP error is surfaced. |
require_real_check | on | Ask real-vs-artifact explicitly on every confirmation. |
channels | auto | auto hands the model the L (structure) and C (chroma) renders of the closest view beside the natural images, so a code is judged in the channel where its evidence lives. off sends natural images only. With channel_cfg overrides and the suspect_l_max / suspect_c_min thresholds for the structural-code-with-chroma-only-support check. |
constrained_codes | off | The model answers the code as the item NUMBER in the allowed list instead of spelling it, so transposition between similar codes becomes structurally impossible. |
note_max_chars | 240 | Length cap on the model's note. |
stub | off | No model calls; deterministic answers prove the whole spine free. |
records: projection and verification
| Key | Default | What it does |
|---|---|---|
min_seen | 2 | Sightings needed to reach the report (below = review). |
merge_gap_ms | 4000 | Same code, same place, within this gap = one physical thing. |
merge_location | on | Require location agreement (clock equal or adjacent, zone equal) to merge. |
run_gap_ms | 3000 | EXTENSIVE: sightings closer than this chain into one run. |
continuous_threshold_ms | 5000 | PROMOTABLE: a point persisting past this becomes a run. |
state_min_band_step | 1 | STATE: band steps a value must move to re-record. |
state_min_reading_delta | 20 | STATE: how far a numeric reading must move to re-record. |
artifact_min_scene_drift / artifact_ratio | 0.02 / 0.25 | The camera-locked artifact test: runs only when the scene is genuinely moving; a detection drifting below the ratio of scene drift is withdrawn. |
host_window_ms / host_clock_adjacent | 8000 / on | The host gate: a code asserting a host structure needs a qualifying record within this window, at the same or an adjacent clock. |
infer_context | on | When a legality-driving context field is unknown, the record set itself is checked for internal consistency against the pack's legality tables: a record whose family is illegal under the value the rest of the set clearly implies is flagged to review as a contradiction. A flag, never a block (inference can be wrong); never runs when the field is supplied. |
infer_context_min_records | 5 | Records needed before the inference has an opinion. |
context: the survey facts
Free-form keys matched against the pack's context_fields: they select grading columns, arm legality gates, and fill the record's assumed_defaults when omitted. What belongs here is defined by your codebook: see Codebook authoring.