Repository avatar
Other Tools
v0.1.0
active

glassweave

io.github.raydeoliveira/glassweave

Eye-tracked glasses-free 3D display CLI & MCP server with DDC/CI switching and shaders.

Documentation

GlassWeave

Cross-OS eye-tracked glasses-free 3D CLI and stdio MCP server for Samsung Odyssey 3D, Acer SpatialLabs, ASUS Spatial Vision, and Lenovo ThinkVision 27 3D (869,584 bytes / 849 KB stripped macOS arm64 binary, zero external runtime dependencies).

What It Does and Does Not Do

CapabilityStatusNotes / Requirements
4-vendor optical table (vendors)SupportedSamsung Odyssey 3D, Acer SpatialLabs, ASUS Spatial Vision, Lenovo ThinkVision 27 3D + <config-dir>/vendors.json overrides
DDC/CI & USB-HID lens switching (switch, restore)SupportedVESA DDC/CI (0x37, 0x6E/0x6F, 0x51, 0x50 XOR) via isolated IOAVService* SPI (dlsym) + IOHIDDevice; #if os(Linux) /dev/i2c-* & /dev/hidraw* via CGlassWeaveLinux
UVC eye tracking (track)SupportedmacOS AVFoundation + Vision VNDetectFaceLandmarksRequest (requires Camera TCC permission); #if os(Linux) V4L2 probe; --eye-coords, stdin JSONL, GLASSWEAVE_UVC_TRACE, --fixture
Eye-tracked lenticular shaders (weave, calibrate)SupportedRuntime-compiled Metal MSL (lenticular, row-interlaced, col-interlaced, checkerboard, full-sbs, half-sbs, tab, dubois-anaglyph), shaders/lenticular.glsl, shaders/lenticular.wgsl, CPU parity oracle
Proprietary vendor firmware opcodesHonest limitVendor 3D lens-toggle VCP/HID registers are undocumented publicly; clean-room defaults are provided and overridable via --config-dir <dir>/vendors.json. Always test with --dry-run first

Install & Uninstall

# Build from source (Commercial or OSS edition)
cd projects/glassweave

# Or via Homebrew tap:
brew install raydeoliveira/tap/glassweave

To uninstall:

brew uninstall glassweave
rm -rf ~/.config/glassweave

Quick Start (Human + --json Agent Usage)

$ glassweave --version
glassweave 0.1.0 (commercial, arm64)

$ glassweave probe --fixture samsung-odyssey-3d --json
{"data":{"cameras":[{"id":"sim-uvc-0","is_external":true,"name":"Simulated UVC Eye Tracker (fixture:samsung-odyssey-3d)"}],"display_identity":{"manufacturer_code":"samsung","monitor_name":"Odyssey 3D G90XF","product_id_hex":"7412","vendor_id_hex":"4c2d"},"displays":[{"lens_mode":"2d","model":"Odyssey 3D G90XF","product_id_hex":"7412","vendor":"samsung","vendor_id_hex":"4c2d"}]},"error":null,"ok":true,"schema_version":1}

$ glassweave switch --mode 3d --fixture samsung --snapshot-dir /tmp/gw-snap --dry-run --json
{"data":{"applied":false,"confirmed":false,"display":{"lens_mode":"2d","model":"Odyssey 3D G90XF","product_id_hex":"7412","vendor":"samsung","vendor_id_hex":"4c2d"},"dry_run":true,"interrupted":false,"note":"Dry-run plan for Odyssey 3D G90XF: 2d -> 3d via ddc.","planned_frame_hex":"51 84 03 ea 00 01 53","previous_mode":"2d","rolled_back":false,"snapshot_path":"/tmp/gw-snap/lens_snapshot_4c2d_7412.json","target_mode":"3d","transport":"ddc","verified":false},"error":null,"ok":true,"schema_version":1}

# UNIX composability: pipe calibrate optical_profile into eye-tracked weave
$ glassweave calibrate --vendor samsung --json \
  | glassweave weave --input frame_sbs.png --output woven.png --eye-coords 0,0,650,63,0,650 --dry-run --from-json - --json

Safety & Rollback

  • Pre-switch snapshot: Persists lens_snapshot_<vid>_<pid>.json atomically before any DDC/CI or USB-HID write, rejecting symbolic links via lstat (exit 4).
  • Non-TTY protection: Refuses mutating switch calls in non-interactive pipelines without --yes (exit 2).
  • 15s auto-revert & signals: Installs non-restarting sigaction (sa_flags = 0) on SIGINT and SIGTERM during poll(); unconfirmed 3D mode reverts to 2d on timeout (exit 1) or signal (exit 130).
  • Explicit restore: glassweave restore --vendor <name> reverts to 2d without requiring a Pro license.
  • OS Permissions: USB-HID requires macOS Input Monitoring; live UVC tracking requires Camera permission (System Settings -> Privacy & Security). Denied permissions return exit 4.

Exit Codes & Discovery

  • 0: Success
  • 1: Runtime failure or confirmation timeout rollback
  • 2: Invalid usage, NaN/Inf/bounds error, non-TTY without --yes, or upstream --from-json ok: false
  • 3: Supported 3D display or UVC camera unavailable (default when no physical hardware is attached and no --fixture/--sim is given)
  • 4: OS TCC permission denied or symlink rejected
  • 130: SIGINT/SIGTERM received after automatic rollback to 2d

Run glassweave --help for human CLI usage, glassweave --describe for the JSON capability manifest, or glassweave mcp for stdio JSON-RPC 2.0 MCP tools.

License & Security

MCPB
https://github.com/raydeoliveira/glassweave/releases/download/v0.1.0/glassweave-0.1.0-macos-arm64.mcpb
Install Command
# mcpb: https://github.com/raydeoliveira/glassweave/releases/download/v0.1.0/glassweave-0.1.0-macos-arm64.mcpb