Metadata-Version: 2.3
Name: whitebox-plugin-device-insta360
Version: 0.1.41
Summary: A plugin for whitebox to interface with Insta360 cameras
License: GNU Affero General Public License v3
Author: Milos
Author-email: hello@klined.org
Requires-Python: >=3.14.0
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Requires-Dist: insta360 (>=0.1.21,<0.2.0)
Description-Content-Type: text/markdown

# Whitebox Plugin - Insta360 Camera Support

This is a plugin for [whitebox](https://gitlab.com/whitebox-aero) that enables support for Insta360 cameras
using the [insta360 library](https://gitlab.com/whitebox-aero/insta360).

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](https://docs.whitebox.aero/plugin_guide/#independent-frontend-packages),
then restart backend workers and reload the browser as described in
[frontend installation and recovery](https://docs.whitebox.aero/plugin_guide/#frontend-installation-failure-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](https://docs.whitebox.aero/development_guide/#editable-plugin-sessions):
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](https://docs.whitebox.aero/plugin_guide/#testing-python-code)
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](https://docs.whitebox.aero/development_guide/#maintained-built-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](https://mkdocstrings.github.io/griffe/docstrings/#google-style)
   should be used for all functions and classes.

