Metadata-Version: 2.4
Name: orbbec-astra-raw
Version: 0.2.0
Summary: Unofficial pure-Python driver for the Orbbec Astra Pro IR/depth sensor
Project-URL: Homepage, https://github.com/chintan-27/orbbec-astra-raw
Project-URL: Issues, https://github.com/chintan-27/orbbec-astra-raw/issues
License: MIT
License-File: LICENSE
Keywords: astra,depth,driver,ir,lidar,orbbec,usb
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Video :: Capture
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.9
Requires-Dist: numpy>=1.21
Requires-Dist: pyusb>=1.2
Provides-Extra: all
Requires-Dist: opencv-python>=4.5; extra == 'all'
Requires-Dist: pillow>=9.0; extra == 'all'
Provides-Extra: image
Requires-Dist: pillow>=9.0; extra == 'image'
Provides-Extra: viewer
Requires-Dist: opencv-python>=4.5; extra == 'viewer'
Description-Content-Type: text/markdown

# orbbec-astra-raw

Unofficial pure-Python driver for the **Orbbec Astra Pro** IR / depth sensor.

Works without the broken OpenNI2 / pyorbbecsdk stack. Reverse-engineered from
raw USB traffic. No compiled extensions, no kernel drivers.

## Supported hardware

| Device | VID:PID |
|--------|---------|
| Orbbec Astra Pro depth/IR sensor | `2BC5:0403` |

The color camera (`2BC5:0501`) is a standard UVC webcam — accessed via `read_color()`
(requires `opencv-python`).

## Install

```bash
# Core library only (numpy arrays, no viewer)
pip install orbbec-astra-raw

# With live viewer (requires OpenCV)
pip install orbbec-astra-raw[viewer]
```

## Quick start

```python
from astra_raw import AstraIRCamera

with AstraIRCamera() as cam:
    ir    = cam.read_ir()        # (480, 640) uint16 — raw Y11 values
    depth = cam.read_depth_mm()  # (480, 640) float32 — millimetres (0 = invalid)
    color = cam.read_color()     # (480, 640, 3) uint8 BGR, or None if unavailable
```

## CLI

```bash
# Live three-panel viewer: Depth | IR | Color
astra-ir-view

# Save one IR frame to PNG
astra-ir-save frame.png

# Dump one raw frame payload to binary
astra-ir-dump frame.bin
```

### Viewer keys

| Key | Action |
|-----|--------|
| `q` | quit |
| `s` | save depth / IR / color PNGs to `/tmp/` |
| `g` / `h` | IR gamma down / up |
| `j` / `k` | IR lo-percentile down / up |
| `n` / `m` | IR hi-percentile down / up |
| `u` | toggle median blur |
| `c` | toggle CLAHE |
| `t` | toggle temporal smoothing on depth |
| `p` | toggle speckle filter on depth |

## API

```python
from astra_raw import AstraIRCamera, decode_y11_msb, parse_packet_stream

cam = AstraIRCamera()
cam.open()

ir    = cam.read_ir()           # (480, 640) uint16
depth = cam.read_depth_mm()     # (480, 640) float32 mm
raw   = cam.read_raw_group()    # bytes — undecoded Y11 payload

cam.close()

# Lower-level helpers
groups = parse_packet_stream(blob)   # {gid: [(seq, payload), ...]}
vals   = decode_y11_msb(payload)     # 1-D uint16 array
```

## OS notes

| Platform | Status |
|----------|--------|
| macOS (Apple Silicon) | works without sudo |
| Linux | requires a udev rule for non-root USB access |
| Windows | requires Zadig to bind WinUSB to `2BC5:0403` |

### Linux udev rule

```
# /etc/udev/rules.d/99-orbbec-astra.rules
SUBSYSTEM=="usb", ATTRS{idVendor}=="2bc5", ATTRS{idProduct}=="0403", MODE="0666"
```

Then: `sudo udevadm control --reload && sudo udevadm trigger`

### Windows

One-time setup (requires admin, then normal user access forever after):

```powershell
# In an elevated PowerShell prompt:
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\scripts\install_winusb.ps1
```

The script downloads Zadig, opens it for you, and confirms the install.
After that, unplug/replug the camera and use `astra-ir-view` as a normal user.

Alternatively, run [Zadig](https://zadig.akeo.ie/) manually, select **Orbbec Astra Pro** (PID 0403), and install **WinUSB**.

## How it works

The sensor streams 3072-byte packets on USB bulk endpoint `0x81`. Each packet
has a 12-byte header (`magic` + `seq` + `gid`) followed by 3060 bytes of Y11
payload. Grouping 137 packets by their `gid` field assembles one frame.

The payload is decoded as 11-bit MSB-first (big-endian bit order) samples,
reshaped to 1280x240, center-cropped to 640x240, and resized to 640x480.

Depth is estimated as `K / disparity` where `K = 342 000`
(focal-length x baseline x sub-pixel-factor for this sensor).

## License

MIT
