Metadata-Version: 2.4
Name: supercamera
Version: 0.1.0
Summary: Python driver for USB endoscopes using the supercamera/useeplus protocol (Oasis, Depstech, etc.)
Project-URL: Homepage, https://github.com/Revise-Robotics/supercamera-endoscope
Project-URL: Issues, https://github.com/Revise-Robotics/supercamera-endoscope/issues
Author: g
License-Expression: MIT
Keywords: borescope,camera,endoscope,oasis,opencv,supercamera,usb,useeplus
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Video :: Capture
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.8
Requires-Dist: pyusb>=1.2.0
Provides-Extra: all
Requires-Dist: numpy; extra == 'all'
Requires-Dist: opencv-python; extra == 'all'
Requires-Dist: pillow; extra == 'all'
Provides-Extra: opencv
Requires-Dist: numpy; extra == 'opencv'
Requires-Dist: opencv-python; extra == 'opencv'
Provides-Extra: validate
Requires-Dist: pillow; extra == 'validate'
Description-Content-Type: text/markdown

# supercamera

Python driver for USB endoscopes that use the **supercamera / useeplus protocol** — the cheap endoscopes sold under brands like Oasis, Depstech, and others that only work with the "UseeePlus" mobile app.

These devices don't implement standard UVC, so they won't show up as webcams. This package talks to them directly over USB and gives you JPEG frames or numpy arrays.

## Supported devices

| USB ID | Device name | Chip |
|--------|-------------|------|
| `2ce3:3828` | supercamera (Geek szitman) | Common |
| `0329:2022` | supercamera (variant) | Common |

Check yours with `lsusb` (Linux) or `system_profiler SPUSBDataType` (macOS).

## Install

```bash
pip install supercamera
```

For OpenCV/numpy support (`.read()` returns numpy arrays):

```bash
pip install supercamera[opencv]
```

## Usage

### Python API

```python
from supercamera import Camera

# Like cv2.VideoCapture
with Camera() as cam:
    ret, frame = cam.read()  # numpy array (BGR), requires opencv
    # or
    jpeg_bytes = cam.read_jpeg()  # raw JPEG, no extra deps
```

### Multiple cameras

```python
from supercamera import Camera, list_devices

list_devices()       # returns list of CameraInfo with bus/address
Camera(index=0)      # first camera
Camera(index=1)      # second camera
```

Note: these devices often share the same serial number, so use `index` or `bus`/`address` to distinguish them.

### CLI

```bash
supercamera --list       # list connected cameras
supercamera              # capture one frame
supercamera -n 10        # capture 10 frames
supercamera -i 1         # use second camera
supercamera --show       # live view (requires opencv-python)
```

### Frame validation

```python
from supercamera import is_valid_jpeg
is_valid_jpeg(jpeg_bytes)  # True/False (uses Pillow full decode if available)
```

### OpenCV pipeline example

```python
import cv2
from supercamera import Camera

cam = Camera()
while True:
    ret, frame = cam.read()
    if not ret:
        continue
    gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
    cv2.imshow("endoscope", gray)
    if cv2.waitKey(1) & 0xFF == ord("q"):
        break
cam.release()
```

## How it works

These endoscopes use a proprietary USB protocol (`com.useeplus.protocol`) instead of UVC. The driver:

1. Claims USB interfaces, sends magic init (`ff 55 ff 55 ee 10`) and connect command (`bb aa 05 00 00`)
2. Reads bulk USB packets containing JPEG-encoded 640x480 frames
3. Properly resets the device on disconnect so it's ready for the next session

Resolution is **640x480** regardless of what the product listing claims.

## Testing

Plug in one or both cameras, then:

```bash
python test_camera.py
```

Runs: device listing, single capture, 3x reconnect (no replug), OpenCV read, and two-camera simultaneous capture (if two connected).

## Platform notes

- **macOS**: Works out of the box. No kernel extensions needed.
- **Linux**: Works. You may need a udev rule for non-root access:
  ```bash
  echo 'SUBSYSTEM=="usb", ATTR{idVendor}=="2ce3", ATTR{idProduct}=="3828", MODE="0666"' | \
    sudo tee /etc/udev/rules.d/99-supercamera.rules
  sudo udevadm control --reload-rules
  ```
- **Windows**: Should work with [libusb](https://libusb.info/) + [Zadig](https://zadig.akeo.ie/) driver. Untested.

## Credits

Protocol reverse-engineered by:
- [hbens/geek-szitman-supercamera](https://github.com/hbens/geek-szitman-supercamera) (C++ PoC, CC0)
- [MAkcanca/useeplus-linux-driver](https://github.com/MAkcanca/useeplus-linux-driver) (Linux kernel driver)

## License

MIT
