\r \r

Kami Image Search\r

\r

Search your camera's visual history with natural language.\r \r Monitor your camera feed, capture frames automatically, and retrieve matching images by simply describing what you're looking for. Powered by the Kamivision cloud API for AI description and embedding generation.\r \r

Features\r

\r

• 🔍 Natural language image search\r
• 📸 Automatic frame capture from video streams\r
• 🧠 AI-powered image description (Kamivision API)\r
• 📁 Manual image import (JPEG / PNG / BMP / WebP)\r
• 🔁 Built-in duplicate frame detection\r
• ⏱ Time-range filtering\r
• 🏠 Designed for Kami SmartHome ecosystem\r \r

Scenarios\r

\r

• Doorstep delivery verification\r
• Home activity review\r
• Pet or child monitoring playback\r
• Batch photo indexing and retrieval\r \r

Installation\r

\r

bash setup.sh\r
```\r
\r
Checks for `python3` and `ffmpeg`, creates `.venv/`, and installs `opencv-python-headless`, `numpy`, `requests`, `Pillow`, `faiss-cpu`. Idempotent.\r
\r
## Prerequisites\r
\r
- `python3` and `python3-venv` installed\r
- `ffmpeg` installed (setup.sh will attempt to install it)\r
- `image_config.json` configured with your stream URL and Kamivision API key\r
- RTSP/RTMP camera online and reachable (for capture mode)\r
\r
## Kamivision API Key Setup\r
\r
This skill requires a `KAMIVISION_API_KEY` to access the Kamivision cloud API. The key is NOT included in the skill package — you must provide your own.\r
\r
**Ask the user: Do you already have a `KAMIVISION_API_KEY`?**\r
\r
- **Yes** → Enter the key directly. It will be saved to `image_config.json`.\r
- **No** → Please register at [Kamivision Flow](https://kamiclaw-skill.kamihome.com/) to obtain your API key, then come back and enter it.\r
\r
## Parameter Confirmation\r
\r
Before running, confirm these key settings in `image_config.json`:\r
\r
| Parameter | Default | Description |\r
|-----------|---------|-------------|\r
| `STREAM_URL` | — | RTSP/RTMP/HTTP camera stream URL |\r
| `DEVICE_ID` | `CAM-001` | Camera device identifier |\r
| `KAMIVISION_API_KEY` | — | Your Kamivision API key |\r
| `CAPTURE_INTERVAL` | `10` | Seconds between frame captures |\r
| `SIMILARITY_THRESHOLD` | `0.35` | Search similarity threshold (0.0–1.0) |\r
| `SEARCH_TOP_K` | `5` | Max results per search |\r
| `TIME_ZONE_OFFSET` | `0` | UTC offset in hours for local time display (e.g. `-12` for UTC+12, `8` for UTC+8) |\r
\r
**Ask the user: do any parameters need to be changed?**\r
\r
## Usage\r
\r
### Start Capture\r
\r
```bash\r
.venv/bin/python image_search.py --start-capture\r
```\r
\r
### Stop Capture\r
\r
```bash\r
.venv/bin/python image_search.py --stop-capture\r
```\r
\r
### Check Status\r
\r
```bash\r
.venv/bin/python image_search.py --status\r
```\r
\r
### Import Images\r
\r
```bash\r
# Single image\r
.venv/bin/python image_search.py --import /path/to/photo.jpg --json\r
\r
# Entire directory (recursive)\r
.venv/bin/python image_search.py --import /path/to/photos/ --json\r
```\r
\r
### Search\r
\r
```bash\r
.venv/bin/python image_search.py --search "keys on the table" --json\r
```\r
\r
### Search with Time Range\r
\r
```bash\r
.venv/bin/python image_search.py \\r
  --search "person in blue jacket" \\r
  --time-start 1754538000 --time-end 1754541600 \\r
  --json\r
```\r
\r
## Output (stdout JSON)\r
\r
```json\r
{\r
  "status": "ok",\r
  "query": "keys on the table",\r
  "count": 1,\r
  "results": [\r
    {\r
      "image_name": "CAM-001_1754538507.jpg",\r
      "image_path": "/opt/image_data/CAM-001/20250815/CAM-001_1754538507.jpg",\r
      "description": "A set of keys and a wallet on a table",\r
      "timestamp": 1754538507,\r
      "time": "2025-08-15 10:00:07 AM",\r
      "score": 0.7823\r
    }\r
  ]\r
}\r
```\r
\r
## Exit Codes\r
\r
| Code | Meaning |\r
|------|---------|\r
| `0` | Success |\r
| `1` | Error (config issue, stream failure, API error, runtime exception) |\r
\r
## Troubleshooting\r
\r
- `bash: .venv/bin/python: No such file or directory` → Run `bash setup.sh`\r
- `OpenCV cannot open stream` → Check camera is online and `STREAM_URL` is correct\r
- `Kamivision API error` → Verify `KAMIVISION_API_KEY` and network connectivity\r
- `Unsupported file format` → Only JPEG, PNG, BMP, WebP are supported\r
- `No search results` → Ensure images have been captured/imported; try lowering `SIMILARITY_THRESHOLD`\r
- `FAISS index load failed` → Index may be corrupted; system rebuilds automatically, re-import data if needed\r