Metadata-Version: 2.3
Name: whitebox-plugin-device-insta360
Version: 0.1.40
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

Simply install the plugin to whitebox:

```
poetry add whitebox-plugin-device-insta360
```

## Adding Plugin to Whitebox Locally (For Development)

1. Set up whitebox locally.
2. Clone this repository.
3. Add plugin to whitebox using the following command: `poetry add -e path/to/plugin.`
4. Run the whitebox server.

## Running Plugin Tests Locally

1. Ensure you have the plugin installed in whitebox like mentioned above.
2. Run the tests: `make test`.

## 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.

