Whitebox Plugin - Insta360 Camera Support

This is a plugin for whitebox that enables support for Insta360 cameras using the insta360 library.

Live X4 preview sessions publish transient, non-persistent gravity observations for the matching device_connection_<id> stream. Raw X4 acceleration maps to the right-handed Three.js leveling-root frame (+X world, viewer-left with the current +Z camera target; +Y up; +Z target-forward) as (ay, ax, az), is confidence-gated and EMA-filtered on every eligible sample. This Device calibration is distinct from ThreeJS's private, unchanged source-to-SphereGeometry projection basis (x, y, z) -> (z, y, -x). Gyroscope values are not integrated and no yaw is inferred.

Live publication is uncapped by default, with no intentional rate delay. Set WHITEBOX_INSTA360_LEVELING_MAX_HZ in Whitebox's container environment to a positive finite number (fractional Hz supported) to limit publication using monotonic elapsed time. Missing or 0 means uncapped; negative, nonfinite, empty or malformed values fail daemon startup with a configuration error, as do nonzero values too small to represent as a floating-point rate. Restart the daemon after changing its environment; recreate its container when changing Compose environment values.

This is a maximum publication cadence, not guaranteed sensor or render FPS. Filtering is independent of the cap. Delivery keeps only the latest pending trusted value, replacing obsolete observations during rate waits or slow sends rather than replaying a backlog. A replacement stream generation discards retired pending data and starts a new cadence with an immediate first publication. Video remains independently transported; this does not imply video-frame synchronization or camera-equivalent stabilization.

Installation

Install a compatible regular release in Whitebox's backend Python environment:

poetry add whitebox-plugin-device-insta360

Python installation does not build the frontend. Follow Whitebox's regular installation and explicit core assembly workflow, then restart backend workers and reload the browser as described in frontend installation and recovery. Use the guides from your matching core checkout when working on unpublished changes.

Adding Plugin to Whitebox Locally (For Development)

Clone this repository into the prepared Whitebox development environment. For live frontend changes, follow the explicit editable-session workflow: install only intended owners editable, select this owner in a ready session, and restart Django with development enabled before reloading the browser. An unselected editable frontend blocks browser bootstrap; installing it and starting the server alone is not supported. The same guide explains returning to a saved regular wheel and reassembling before restart.

Running Plugin Tests Locally

The Whitebox backend runner discovers installed Python tests in whitebox_test_plugin_device_insta360; follow the core guide's Python testing instructions and run the backend's make test from /app in its prepared development container. That is distinct from browser frontend admission. From this plugin checkout in the prepared backend development container, make test-frontend runs the owner source suite through core's tooling. Source tests do not prove installed frontend behavior; use the installed application checks for the matched regular installation and assembled application.

Contribution Guidelines

1. Write tests for each new feature.
2. Ensure coverage is 90% or more.
3. Google style docstrings should be used for all functions and classes.