AVISION

Before any code, one question asked the right way: what does a blind person actually need — not what can computer vision detect. Someone navigating without sight continuously runs four questions: Can I move forward? How far before I react? What direction is safe? Is something changing fast? Human vision answers these subconsciously; A-Vision compresses that continuous stream into sparse, prioritized, actionable audio. That framing is the difference between building a camera that talks and building a system that guides.

Most assistive-vision projects fail not because the CV is bad but because the output overwhelms the person. Every spoken word occupies mental CPU the user needs for walking — cognitive overload is the silent killer. A-Vision is built on 'Silence by Default': it speaks only when warranted, in tiered tones — CRITICAL 2000Hz (danger in the bottom 15% of frame, stop now), WARNING 1000Hz (obstacle in bottom 40%, slow and react), INFO low tone (ambient). No narration, no 'a chair on the left'. A second sense, not a translator.

Every decision traces to one line: the system must never surprise the user. When a new feature trades against predictable, trustworthy behavior, predictability wins. False negatives are dangerous (a missed obstacle); false positives are merely annoying — so the system is tuned conservative. Under compute pressure it degrades gracefully: OCR drops first, object semantics second, and ground detection plus obstacle alerts never drop. The same discipline aerospace, automotive and medical devices use, applied to a C++ codebase that runs on a phone.

The codebase splits into two layers with a hard boundary. The Core ('the Brain', src/core/) is pure C++17 + OpenCV with zero OS dependencies — it only understands frames and events: the graph engine, geometry, distance, risk, temporal smoothing, free-space and edge-safety modules. The Platform ('the Body', src/platform/) is thin OS adapters implementing just two interfaces, ICamera and IAudio — desktop, Android JNI, iOS Objective-C++, and a headless embedded runner. Porting means writing a new shell; the Core is untouched and behavior stays identical.

Modules don't run in hardcoded order. Each registers as an IModule node with declared dependencies, and the engine builds a DAG from modules.json, flattening it with Kahn's topological sort. Temporal never runs before Object feeds it detections; PathGuidance never runs before FreeSpace computes sectors; adding a module is a JSON change, not a code change. Execution Gates go further — if an upstream module's confidence clears a threshold (geometry > 0.85, path clearly safe), the downstream neural net is skipped. Dynamic power management, not just optimization.

Detection accuracy isn't the system's most important property — ground detection is. A blind user needs to know if they can step forward before knowing what is blocking them. Every frame, in under 10ms with no neural network: Canny edge detection finds floor/wall/curb boundaries, a pixel-density heuristic counts edges in the bottom-center safe zone, and contour filtering ignores sub-1000px noise and distant top-half objects. Deterministic, fast, always on — the life-safety layer that never drops.

The Object engine wraps OpenCV DNN behind a factory keyed on a ModelType enum (SSD-MobileNet at 300×300, YOLOv8 at 640×640, NMS at 0.45) running ~5 FPS, with the Temporal module bridging to 30 FPS smoothness via IoU tracking and linear velocity interpolation. Monocular MiDaS depth runs in a background std::future, updating the depth map at 1 FPS while the main safety loop runs at 30 — so depth inference never blocks an obstacle alert.

Beyond real-time navigation, two ONNX-backed CLI tools ship in v1.2: MobileSAM segmentation (ViT encoder + Transformer decoder for Segment Anything, interactive click or box prompts, falling back to cv::grabCut) and Big-LaMa inpainting (large-mask generative fill that removes objects by hallucinating background, falling back to cv::inpaint). Both are deterministic given the same input, and both keep classical fallbacks so a missing model never breaks the tool.

Decided at the design table, not after a benchmark. At 30 FPS each frame has a 33ms budget; even on perfect 5G a cloud round-trip costs 80–150ms with unbounded jitter — you can't schedule collision avoidance around 'hopefully the network is fast'. The cloud never touches the main loop; it's optional for model-weight downloads, async route planning and opt-in analytics. Lose connectivity in an elevator or basement and the system degrades to the geometry layer and stays safe. No frames ever leave the device — assistive tech, not surveillance.

Because the Core has zero OS dependencies, porting is: copy src/core/ into the target project, write the bridge (VisionBridge.cpp for Android NDK is committed; VisionBridge.mm for iOS), and implement ICamera + IAudio. The same Core compiles unchanged on Windows, Linux, Android NDK, iOS and ARM. v1.5 also added an FTXUI-powered AVisionConfig TUI that validates the whole dependency graph before the compiler runs — toggle modules, check models, hit F1 to build; vcpkg manifest mode makes the chain reproducible from a fresh clone.

The original design log draws one distinction that governs everything: not 'look what OpenCV can do' but 'look what a human can do again'. A-Vision isn't a computer-vision showcase — it's a human-capability restoration system that happens to use CV as its mechanism. A system built to impress optimizes for benchmarks and feature lists; a system built to restore independence optimizes for trust — for 'I can walk to the kitchen at night without being afraid', for 'I know it won't lie to me'. Every execution gate and every silent frame serves that one goal.