termux-vision 1.4.6 → 1.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +304 -319
- package/README.pypi.md +132 -121
- package/bin/cli.js +51 -51
- package/lib/vlm.js +349 -349
- package/package.json +55 -55
package/README.pypi.md
CHANGED
|
@@ -1,121 +1,132 @@
|
|
|
1
|
-
# Termux-Vision: On-Device Computer Vision & Multimodal VLM Framework
|
|
2
|
-
|
|
3
|
-
[](https://pypi.org/project/termux-vision/)
|
|
4
|
-
[](https://pypi.org/project/termux-vision/)
|
|
5
|
-
[](https://www.npmjs.com/package/termux-vision)
|
|
6
|
-
[](https://github.com/uno-km/termux-vision)
|
|
7
|
-
|
|
8
|
-
> **Native On-Device Computer Vision & Multimodal Vision-Language Model (VLM) Runtime for Android Termux via Direct Bionic libc & Vulkan Compute Acceleration.**
|
|
9
|
-
> *Zero PRoot. Zero Virtualization. 100% Native ARMv8.2-A NEON SIMD & Hardware GPU Offloading.*
|
|
10
|
-
|
|
11
|
-
---
|
|
12
|
-
|
|
13
|
-
## 1. Overview & Key Capabilities
|
|
14
|
-
|
|
15
|
-
`termux-vision` is an enterprise-grade, on-device multimodal vision inference and spatial computing framework engineered specifically for mobile Android devices. Operating directly against Android's native Bionic libc ABI and host Vulkan compute drivers, `termux-vision` eliminates heavyweight desktop dependencies (OpenCV, TorchVision) and enables high-throughput visual question answering, OCR image captioning, and classical feature extraction directly on edge hardware.
|
|
16
|
-
|
|
17
|
-
* **
|
|
18
|
-
* **
|
|
19
|
-
* **
|
|
20
|
-
* **
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
```
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
```
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
```bash
|
|
47
|
-
|
|
48
|
-
```
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
```
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
|
73
|
-
|
|
|
74
|
-
| `-
|
|
75
|
-
| `--
|
|
76
|
-
| `--
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
1
|
+
# Termux-Vision: On-Device Computer Vision & Multimodal VLM Framework
|
|
2
|
+
|
|
3
|
+
[](https://pypi.org/project/termux-vision/)
|
|
4
|
+
[](https://pypi.org/project/termux-vision/)
|
|
5
|
+
[](https://www.npmjs.com/package/termux-vision)
|
|
6
|
+
[](https://github.com/uno-km/termux-vision)
|
|
7
|
+
|
|
8
|
+
> **Native On-Device Computer Vision & Multimodal Vision-Language Model (VLM) Runtime for Android Termux via Direct Bionic libc & Vulkan Compute Acceleration.**
|
|
9
|
+
> *Zero PRoot. Zero Virtualization. 100% Native ARMv8.2-A NEON SIMD & Hardware GPU Offloading.*
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## 1. Overview & Key Capabilities
|
|
14
|
+
|
|
15
|
+
`termux-vision` is an enterprise-grade, on-device multimodal vision inference and spatial computing framework engineered specifically for mobile Android devices. Operating directly against Android's native Bionic libc ABI and host Vulkan compute drivers, `termux-vision` eliminates heavyweight desktop dependencies (OpenCV, TorchVision) and enables high-throughput visual question answering, OCR image captioning, and classical feature extraction directly on edge hardware.
|
|
16
|
+
|
|
17
|
+
* **100% Vulkan GPU Compute Canny (`0.23 ms`)**: Chains 3-pass SPIR-V compute shaders entirely within VRAM using `vkCmdPipelineBarrier`, achieving 834x acceleration over Python without CPU memory roundtrips.
|
|
18
|
+
* **Ultra-Fast ARM64 NEON C++ Kernel (`3.02 ms`)**: Permanently eliminates trigonometric `atan2f` via tangent ratio bit quantization and 1-byte direction buffers.
|
|
19
|
+
* **Prebuilt-Asset-First Idempotent Installer (`0.005s Skip`)**: Automatically provisions verified precompiled ARM64 native binaries in 2 seconds from official releases, guaranteeing zero-build instant skip if assets already exist.
|
|
20
|
+
* **5-Backend Unified CLI Standard**: Enforces `['auto', 'gpu', 'vulkan', 'opencl', 'cpu']` and convenience flags (`--gpu`, `--cpu`, `--opencl`) across all subcommands.
|
|
21
|
+
* **Zero-Deception Fail-Fast Gatekeeper**: Strictly rejects defective text-only binaries lacking `--mmproj` (`E015`) and corrupted weights (`E014`).
|
|
22
|
+
* **Full-Layer GPU Offloading (-ngl 99)**: Dispatches all 99 transformer layers and cross-attention vision projections directly to device GPU VRAM (**0.00 MiB CPU mapped VRAM**).
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
## 2. Installation Guide
|
|
27
|
+
|
|
28
|
+
### 2.1 Python Package Installation (PyPI)
|
|
29
|
+
```bash
|
|
30
|
+
pip install --upgrade pip setuptools wheel
|
|
31
|
+
pip install termux-vision
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
### 2.2 Prebuilt Native Engine Provisioning (Idempotent 0.005s)
|
|
35
|
+
```bash
|
|
36
|
+
# Automatically download & unpack verified ARM64 prebuilt assets
|
|
37
|
+
termux-vision install
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
### 2.3 Direct GitHub Releases Wheel Asset
|
|
41
|
+
```bash
|
|
42
|
+
pip install https://github.com/uno-km/termux-vision/releases/download/v1.5.0/termux_vision-1.5.0-py3-none-any.whl
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
### 2.4 One-Line Bootstrap Installer
|
|
46
|
+
```bash
|
|
47
|
+
curl -sL https://raw.githubusercontent.com/uno-km/termux-vision/main/install.sh | bash
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
---
|
|
51
|
+
|
|
52
|
+
## 3. GPU Hardware Acceleration (`ameva-runtime`)
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
pip install termux-vision ameva-runtime termux-llamacpp
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
### Silicon Architecture Support Status
|
|
59
|
+
* **Qualcomm Adreno GPU (Snapdragon 8 Elite / Adreno 830, Adreno 7xx, Adreno 650)**: Production Verified & Supported (Full 25/25 layer GPU offloading, 15.00 tok/s on Moondream2 1.8B f16, SPIR-V JIT patch, KGSL watchdog defense via `GGML_VULKAN_SKIP_CHECKS="999999999"`).
|
|
60
|
+
* **ARM Mali GPU (Mali-G78, Mali-G68, etc.)**: Production Verified & Supported (Pure GPU offloading, 0.00 MiB CPU Mapped VRAM, MMVQ tuning via `--tune-mali`).
|
|
61
|
+
* **Samsung Xclipse GPU (Xclipse 920 / 940 - AMD RDNA)**: Under Active Engineering (In Progress / 개발 진행 중).
|
|
62
|
+
|
|
63
|
+
Run hardware diagnostics:
|
|
64
|
+
```bash
|
|
65
|
+
termux-vision doctor
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
---
|
|
69
|
+
|
|
70
|
+
## 4. Standardized CLI & Parameter Matrix
|
|
71
|
+
|
|
72
|
+
| Parameter | Alias | Default | Description |
|
|
73
|
+
| :--- | :--- | :--- | :--- |
|
|
74
|
+
| `-b, --backend` | `-d, --device` | `auto` | Compute acceleration backend: <code>auto</code>, <code>gpu</code>, <code>vulkan</code>, <code>opencl</code>, <code>cpu</code> |
|
|
75
|
+
| `--gpu` / `--cpu` / `--opencl` | *N/A* | *None* | Convenience shorthand flags for backend routing |
|
|
76
|
+
| `-i, --image` | `--image-path` | *Required* | Path to input image (`.png`, `.jpg`, `.webp`) |
|
|
77
|
+
| `-p, --prompt` | *N/A* | `"Describe this image"` | Multimodal text instruction query |
|
|
78
|
+
| `-m, --model` | *N/A* | `smolvlm-500m` | GGUF language model path or catalog identifier |
|
|
79
|
+
| `--mmproj` | *N/A* | *Auto-paired* | Vision projector GGUF model path (`mmproj-*.gguf`) |
|
|
80
|
+
| `-n, --max-tokens` | `--n-predict` | `150` | Maximum number of generated tokens |
|
|
81
|
+
| `-c, --ctx-size` | `--ctx` | `2048` | Context window size |
|
|
82
|
+
| `-t, --threads` | *N/A* | `auto` | Number of CPU execution threads |
|
|
83
|
+
| `-q, --quality` | *N/A* | `optimal` | 4-tier resolution preset: `fast` (384px), `optimal` (768px), `high` (1280px), `original` (1:1) |
|
|
84
|
+
| `--tune-mali` | *N/A* | `False` | Enable ARM Mali GPU MMVQ tuning (`GGML_VK_FORCE_MMVQ=1`) |
|
|
85
|
+
| `--json` | *N/A* | `False` | Emit machine-readable JSON benchmark telemetry |
|
|
86
|
+
|
|
87
|
+
### CLI Example
|
|
88
|
+
```bash
|
|
89
|
+
# 100% Vulkan GPU Canny Edge Detection (0.23 ms)
|
|
90
|
+
termux-vision canny photo.jpg -o edges.png --gpu --low 40 --high 120
|
|
91
|
+
|
|
92
|
+
# GPU-Accelerated Multimodal VLM Inference
|
|
93
|
+
termux-vision vlm photo.jpg -d gpu --tune-mali -p "What objects are visible?"
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
---
|
|
97
|
+
|
|
98
|
+
## 5. Python SDK Quickstart
|
|
99
|
+
|
|
100
|
+
```python
|
|
101
|
+
import termux_vision as tv
|
|
102
|
+
|
|
103
|
+
# 1. 100% Vulkan GPU Canny Edge Detection (0.23ms) or NEON CPU (3.02ms)
|
|
104
|
+
image = tv.io.load_image("document.jpg")
|
|
105
|
+
grayscale = tv.transforms.to_grayscale(image)
|
|
106
|
+
edges = tv.cv.canny(grayscale, low_threshold=40, high_threshold=120, backend="auto")
|
|
107
|
+
tv.io.save_image(edges, "edges.png")
|
|
108
|
+
|
|
109
|
+
# 2. On-Device Multimodal VLM Inference
|
|
110
|
+
with tv.vlm.load("smolvlm-500m", device="gpu") as engine:
|
|
111
|
+
result = engine.describe("document.jpg", prompt="Summarize this document.", quality="optimal")
|
|
112
|
+
print(f"TPS: {result.metrics.tokens_per_second:.2f} tok/s | Output: {result.text}")
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
---
|
|
116
|
+
|
|
117
|
+
## 6. Real-World Benchmarks & Hardware Scorecard
|
|
118
|
+
|
|
119
|
+
| Target Device | SoC & GPU | Algorithm / Model | Mode | Execution / Generation | VRAM Overhead | Status / Speedup |
|
|
120
|
+
| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
|
|
121
|
+
| **Samsung Galaxy S25** | Snapdragon 8 Elite / Adreno 830 | **100% Vulkan GPU Canny** | **GPU (VRAM Chain)** | **0.23 ms (Min 0.18 ms)** | **0.00 MiB CPU VRAM** | **834x Speedup** |
|
|
122
|
+
| **Samsung Galaxy S20** | Snapdragon 865 / Kryo 585 | **ARM64 NEON C++ Canny** | **CPU (NEON SIMD)** | **3.02 ms** | **1.0 MB Buffer** | **Zero atan2f** |
|
|
123
|
+
| **Samsung Galaxy S25** | Snapdragon 8 Elite / Adreno 830 | **Moondream2 1.8B f16** | **GPU (Vulkan 25/25)** | **15.00 tok/s** | **2,706.00 MiB VRAM** | **Verified (Full GPU)** |
|
|
124
|
+
| **Samsung Galaxy S21 5G** | Exynos 2100 / Mali-G78 | SmolVLM-500M-Instruct | **GPU (Vulkan)** | **12.65 tok/s** | **1,059.02 MiB VRAM** | **+58.9% vs CPU** |
|
|
125
|
+
| Samsung Galaxy S21 5G | Exynos 2100 / 8-Core CPU | SmolVLM-500M-Instruct | CPU (NEON) | 7.96 tok/s | 0.00 MiB GPU VRAM | Baseline |
|
|
126
|
+
| **Samsung Galaxy A35 5G** | Exynos 1380 / Mali-G68 | SmolVLM-500M-Instruct | **GPU (Vulkan)** | **5.47 tok/s** | **1,059.02 MiB VRAM** | **+55.8% vs CPU** |
|
|
127
|
+
| Samsung Galaxy A35 5G | Exynos 1380 / 8-Core CPU | SmolVLM-500M-Instruct | CPU (NEON) | 3.51 tok/s | 0.00 MiB GPU VRAM | Baseline |
|
|
128
|
+
|
|
129
|
+
---
|
|
130
|
+
|
|
131
|
+
## 7. License
|
|
132
|
+
Licensed under the Apache-2.0 License. Copyright (c) 2026 Eunho Kim ([@uno-km](https://github.com/uno-km)) & AOSF.
|
package/bin/cli.js
CHANGED
|
@@ -1,51 +1,51 @@
|
|
|
1
|
-
#!/usr/bin/env node
|
|
2
|
-
/**
|
|
3
|
-
* AMEVA Standard Node.js CLI Runner for termux_vision.
|
|
4
|
-
* Automatically resolves Python 3 environment and dispatches to python -m termux_vision.
|
|
5
|
-
*/
|
|
6
|
-
const fs = require('fs');
|
|
7
|
-
const { spawn, execSync } = require('child_process');
|
|
8
|
-
|
|
9
|
-
function findPython() {
|
|
10
|
-
if (process.env.PYTHON && fs.existsSync(process.env.PYTHON)) {
|
|
11
|
-
return process.env.PYTHON;
|
|
12
|
-
}
|
|
13
|
-
const termuxBin = '/data/data/com.termux/files/usr/bin/python3';
|
|
14
|
-
if (fs.existsSync(termuxBin)) {
|
|
15
|
-
return termuxBin;
|
|
16
|
-
}
|
|
17
|
-
const termuxBinAlt = '/data/data/com.termux/files/usr/bin/python';
|
|
18
|
-
if (fs.existsSync(termuxBinAlt)) {
|
|
19
|
-
return termuxBinAlt;
|
|
20
|
-
}
|
|
21
|
-
const candidates = ['python3', 'python'];
|
|
22
|
-
for (const cmd of candidates) {
|
|
23
|
-
try {
|
|
24
|
-
const checkCmd = process.platform === 'win32' ? `where ${cmd}` : `command -v ${cmd}`;
|
|
25
|
-
const res = execSync(checkCmd, { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
|
|
26
|
-
if (res) return cmd;
|
|
27
|
-
} catch (_) {}
|
|
28
|
-
}
|
|
29
|
-
return 'python3';
|
|
30
|
-
}
|
|
31
|
-
|
|
32
|
-
const pythonBin = findPython();
|
|
33
|
-
const args = ['-m', 'termux_vision', ...process.argv.slice(2)];
|
|
34
|
-
|
|
35
|
-
const child = spawn(pythonBin, args, {
|
|
36
|
-
stdio: 'inherit',
|
|
37
|
-
env: process.env
|
|
38
|
-
});
|
|
39
|
-
|
|
40
|
-
child.on('error', (err) => {
|
|
41
|
-
console.error(`[${'termux_vision'}] Failed to spawn python process (${pythonBin}):`, err.message);
|
|
42
|
-
process.exit(1);
|
|
43
|
-
});
|
|
44
|
-
|
|
45
|
-
child.on('exit', (code, signal) => {
|
|
46
|
-
if (signal) {
|
|
47
|
-
process.kill(process.pid, signal);
|
|
48
|
-
} else {
|
|
49
|
-
process.exit(code || 0);
|
|
50
|
-
}
|
|
51
|
-
});
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* AMEVA Standard Node.js CLI Runner for termux_vision.
|
|
4
|
+
* Automatically resolves Python 3 environment and dispatches to python -m termux_vision.
|
|
5
|
+
*/
|
|
6
|
+
const fs = require('fs');
|
|
7
|
+
const { spawn, execSync } = require('child_process');
|
|
8
|
+
|
|
9
|
+
function findPython() {
|
|
10
|
+
if (process.env.PYTHON && fs.existsSync(process.env.PYTHON)) {
|
|
11
|
+
return process.env.PYTHON;
|
|
12
|
+
}
|
|
13
|
+
const termuxBin = '/data/data/com.termux/files/usr/bin/python3';
|
|
14
|
+
if (fs.existsSync(termuxBin)) {
|
|
15
|
+
return termuxBin;
|
|
16
|
+
}
|
|
17
|
+
const termuxBinAlt = '/data/data/com.termux/files/usr/bin/python';
|
|
18
|
+
if (fs.existsSync(termuxBinAlt)) {
|
|
19
|
+
return termuxBinAlt;
|
|
20
|
+
}
|
|
21
|
+
const candidates = ['python3', 'python'];
|
|
22
|
+
for (const cmd of candidates) {
|
|
23
|
+
try {
|
|
24
|
+
const checkCmd = process.platform === 'win32' ? `where ${cmd}` : `command -v ${cmd}`;
|
|
25
|
+
const res = execSync(checkCmd, { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
|
|
26
|
+
if (res) return cmd;
|
|
27
|
+
} catch (_) {}
|
|
28
|
+
}
|
|
29
|
+
return 'python3';
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
const pythonBin = findPython();
|
|
33
|
+
const args = ['-m', 'termux_vision', ...process.argv.slice(2)];
|
|
34
|
+
|
|
35
|
+
const child = spawn(pythonBin, args, {
|
|
36
|
+
stdio: 'inherit',
|
|
37
|
+
env: process.env
|
|
38
|
+
});
|
|
39
|
+
|
|
40
|
+
child.on('error', (err) => {
|
|
41
|
+
console.error(`[${'termux_vision'}] Failed to spawn python process (${pythonBin}):`, err.message);
|
|
42
|
+
process.exit(1);
|
|
43
|
+
});
|
|
44
|
+
|
|
45
|
+
child.on('exit', (code, signal) => {
|
|
46
|
+
if (signal) {
|
|
47
|
+
process.kill(process.pid, signal);
|
|
48
|
+
} else {
|
|
49
|
+
process.exit(code || 0);
|
|
50
|
+
}
|
|
51
|
+
});
|