Advanced Parameters & Tuning
Kernel-level tuning, buffer pool sizing, and thread configuration
1. Unified 5-Backend CLI Standard Matrix
termux-vision strictly adheres to the uno-km ecosystem 5-backend standard (auto, gpu, vulkan, opencl, cpu):
| Backend Choice |
Convenience Flag |
Target Microarchitecture |
Technical Mechanics |
auto (Default) | None | All Android SoCs | Probes GPU Vulkan support; if available routes to Vulkan GPU, otherwise falls back to NEON CPU. |
gpu / vulkan | --gpu | Adreno 830, Mali-G78/G68 | 100% End-to-End Vulkan SPIR-V Compute shaders (3-pass VRAM pipeline barrier for CV, -ngl 99 for VLM). |
opencl | --opencl | Qualcomm Adreno 600 (S20) | Adreno OpenCL 2.0 kernel acceleration, avoiding SPIR-V float subnormal quirks. |
cpu | --cpu | 8-Core ARM64 (big.LITTLE) | High-efficiency ARM64 NEON SIMD kernels without trigonometric atan2f; strict 0.00 MiB GPU VRAM. |
2. Subcommand Parameter Matrix
A. Multimodal VLM Inference (termux-vision vlm)
| Flag |
Aliases |
Default |
Description |
-i, --image | --image-path | Required | Path to input image file (PNG, JPG, WebP) |
-p, --prompt | None | "Describe this image" | Multimodal query or instruction prompt |
-m, --model | None | smolvlm-500m | Language model GGUF path or catalog preset ID |
--mmproj | None | Auto-paired | Vision projector GGUF model path (mmproj-*.gguf) |
-b, --backend | -d, --device | auto | Backend acceleration: auto, gpu, vulkan, opencl, cpu |
--gpu / --cpu / --opencl | None | None | Convenience shorthand flags for backend selection |
-n, --max-tokens | --n-predict | 150 | Maximum number of output tokens |
-c, --ctx-size | --ctx | 2048 | Context window size |
-t, --threads | None | auto | Number of CPU execution threads (affinity-aware) |
--image-size | None | None | Explicit resolution scaling (e.g. 224x224, 384x384) |
-q, --quality | None | optimal | 4-tier preset: fast (384px), optimal (768px), high (1280px), original (1:1) |
--tune-mali | None | False | Enable ARM Mali GPU MMVQ optimization (GGML_VK_FORCE_MMVQ=1) |
--json | None | False | Output structured machine-readable JSON metrics |
-v, --verbose | None | False | Print detailed GPU layer offload logs |
B. Classical Canny Edge Detection (termux-vision canny)
| Flag |
Aliases |
Default |
Description |
-i, --image | Positional | Required | Path to input image file |
-o, --output | None | "output_edges.png" | Path to save output binary edge image |
--low | None | 40 | Low hysteresis threshold (0-255) |
--high | None | 120 | High hysteresis threshold (0-255) |
-b, --backend | -d, --device | auto | Execution backend: auto, gpu, vulkan, cpu |
--gpu / --cpu | None | None | Shorthand for 100% Vulkan GPU (0.23ms) vs NEON CPU (3.02ms) |
C. Prebuilt Idempotent Installer (termux-vision install)
| Flag |
Default |
Description |
--force | False | Force download & reinstallation even if valid binaries exist |
--from-source | False | Force compiling native C++ engines locally via clang++ |
--dry-run | False | Inspect install status, missing components and verify prebuilt hash without changes |
--asset-url | Official GitHub Releases | Custom download URL for the prebuilt native archive |
D. Neural Face Detection (termux-vision detect-face)
| Flag |
Aliases |
Default |
Description |
image_path | Positional | Required | Path to input image file (JPEG, PNG, WebP) |
-o, --output | None | "face_crop.jpg" | Path to save primary face crop image |
--backend | None | auto | Detection engine: auto (Neural SSD), neural, haar |
--score-threshold | None | 0.70 | Minimum neural confidence score threshold (0.0 to 1.0) |
--json | None | False | Output structured detection bounding boxes and confidence scores in JSON |
3. Zero-Deception Fail-Fast Diagnostics
| Error Code |
Condition |
Cause |
Fail-Fast Resolution |
E014_VLM_MODEL_CORRUPTED | GGUF < 10 MB or truncated header | Corrupted or incomplete download | Auto-rejects broken files and prompts re-downloading model |
E015_LLAMA_CLI_NO_MMPROJ | llama-cli missing --mmproj | Text-only binary used for VLM | Blocks execution; guides running termux-vision install |
E016_VULKAN_ICD_UNREACHABLE | --backend gpu on unsupported device | No Vulkan 1.1+ ICD driver | Strict error with GPU diagnosis; refuses silent fake execution |
E017_MISSING_MMPROJ | VLM execution without mmproj | Missing vision projector weights | Displays required mmproj download link and file path |