| Name | pysurvive JSON |
| Version |
1.1.21
JSON |
| download |
| home_page | https://github.com/cntools/libsurvive |
| Summary | Libsurvive is a set of tools and libraries that enable 6 dof tracking on lighthouse and vive based systems that is completely open source and can run on any device. It currently supports both SteamVR 1.0 and SteamVR 2.0 generation of devices and should support any tracked object commercially available. |
| upload_time | 2023-03-11 08:30:00 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | |
| license | MIT |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
|
| coveralls test coverage |
No coveralls.
|
# libsurvive [](https://github.com/cntools/libsurvive/actions/workflows/cmake.yml)[](https://github.com/cntools/libsurvive/actions/workflows/build_nuget.yml)[](https://github.com/cntools/libsurvive/actions/workflows/build_wheels.yml)
Libsurvive is a set of tools and libraries that enable 6 dof tracking on
[lighthouse and vive](https://en.wikipedia.org/wiki/HTC_Vive) based systems that is completely open source and can run
on any device. It currently supports both SteamVR 1.0 and SteamVR 2.0 generation of devices and should support any tracked
object commercially available.
Since the focus is on tracking; it does not independently run the HMD. For an open souce stack that does that see [monado](https://monado.freedesktop.org/)
Most of the development is discussed on Discord. [Join the chat and discussion in our discord!](https://discordapp.com/invite/7QbCAGS). There is also a [matrix bridge](https://app.element.io/#/room/#libsurvive-main:matrix.org) available to join the discussion.
An example application is libsurvive running the controllers and HMD in Godot:
[](https://www.youtube.com/watch?v=yC75XknKTo0)
Table of Contents
=================
* [Quick start](#quick-start)
* [Debian](#debian)
* [Windows](#windows)
* [Current Status](#current-status)
* [Roadmap](#roadmap)
* [Getting Started](#getting-started)
* [Calibration](#calibration)
* [Visualization](#visualization)
* [libsurvive Tools](#libsurvive-tools)
* [Using libsurvive in your own application](#using-libsurvive-in-your-own-application)
* [Lower level API](#lower-level-api)
* [High level API](#high-level-api)
* [Python Bindings](#python-bindings)
* [C# Bindings](#c-bindings)
* [Data recording](#data-recording)
* [Normal recording](#normal-recording)
* [Raw USB recording](#raw-usb-recording)
* [Common command line flags](#common-command-line-flags)
* [Drivers](#drivers)
* [Custom Drivers](#custom-drivers)
* [FAQ](#faq)
* [Addendum and notes](#addendum-and-notes)
# Quick start
## Debian
```
git clone git@github.com:cntools/libsurvive.git --recursive
cd libsurvive
sudo cp ./useful_files/81-vive.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules && udevadm trigger
sudo apt-get install build-essential zlib1g-dev libx11-dev libusb-1.0-0-dev freeglut3-dev liblapacke-dev libopenblas-dev libatlas-base-dev cmake
make
```
Plug in a headset / tracker / controller / etc and run:
```
./bin/survive-cli
```
This should calibrate and display your setup.
For visualization, you can either download a binary of [websocketd](https://github.com/joewalnes/websocketd/releases/) or enable the experimental apt source and use `sudo apt install websocketd`. After which you can run:
```
./bin/survive-websocketd & xdg-open ./tools/viz/index.html
```
[](https://www.youtube.com/watch?v=l4doRSXM0tU)
## Windows
If you have `cmake` installed on your path you can simply run the `make.ps1` script by right clicking it and seleting `Run with PowerShell`.
A more manual approach is to open CMakeLists file in something like [CMake GUI](https://cmake.org/runningcmake/) to build
from source using one of the visual studio generators. This will also let you set various build options. The build uses NuGet
to get the [necessary development dependencies](https://www.nuget.org/packages/lapacke/). After you generate the project, open the
solution in visual studio and run build all.
[Websocketd](http://websocketd.com/) should work the same with with the visualization tool; assuming you put it somewhere in the system path. In the build binary folder (`./build-win/Release` if you built from `make.ps1`) there should be a `survive-websocketd.ps1` which can be ran as a PowerShell file.
Probably the easiest way to get started with libsurvive on windows is to check out the [release binaries](https://github.com/cntools/libsurvive/releases).
# Current Status
The tracking and device enumeration work fairly well at this point; but there isn't an extremely large testing base and
the tools aren't as polished as the comparable ones bundled in SteamVR. Work is ongoing to quantify how accurate the
tracking is and to improve the user experience.
# Roadmap
A very loose collection of things that are on the short term agenda:
- Dynamic correction of calibration. This would detect and silently recalibrate lighthouses that might have moved. The
end goal is to have a system where the user is never aware of any calibration requirements.
- An android binary / port
- Hard numbers on the accuracy and precision of libsurvive as a tracking system. If anyone wants to contribute time testing
on a CNC please get in our [discord](https://discordapp.com/invite/7QbCAGS)
- Better handling of data starvation -- if the USB or radio connection stutters too long, the tracking will occasionally
glitch out for a brief period.
- Use something like usbmon for windows
# Getting Started
If you followed the quick start guide, you'll notice that the first thing you must do (for linux) is install udev rules:
```
sudo cp ./useful_files/81-vive.rules to /etc/udev/rules.d/
sudo udevadm control --reload-rules && udevadm trigger
```
This allows one to use those devices without having root. No such steps are necessary in windows.
After that, when you run `survive-cli` or `survive-websocketd` it should recognize any plugged in vive devices and start
calibrating and tracking those devices.
**Important: Close SteamVR for best results. Depending on the system, libsurvive
will either cause SteamVR to lose connection to the device or will compete for bandwidth with it**
## Calibration
Calibration is the process which establishes where the lighthouses are set up in relation to the tracked objects. The
first time you run libsurvive, it can take up to ten seconds to communicate with the lighthouses and figure out where
they are.
Calibration will continuously integrate objects data so long as they are momentarily stationary. Due to this, you might notice lighthouses shift slighty while it gets a good lock. Subsequent runs should shift much less.
Once you do this one time, it is saved in `config.json` in `XDG_CONFIG_HOME/libsurvive`. If you delete this file, it will simply
recalibrate; but it is faster to use the `--force-calibrate` flag. Some drivers change the name of this file -- notably recordings will instead use `<event_file>.json`.
If you have a large space, and you can not centrally locate a single device to 'see' all lighthouses, you can calibrate
a few lighthouses and move the tracked object into the field of view of the uncalibrated lighthouse while keeping it in
view of at least one of the calibrated ones. Set it down so it doesn't move; and the remaining lighthouse(s) should now
calibrate.
**Important: Resetting calibration automatically when a lighthouse is moved is being planned on but is not currently
available. If one of the calibrated lighthouses are moved, you either have to redo calibration by deleting the config.json
file or passing `--force-calibrate` into any of the libsurvive tools.**
## Visualization
The main visualization tool is a THREE.js page which is fed data through (websocketd)[http://websocketd.com/]. To use
this tool, run `survive-websocketd [options]` and open a web browser to `./tools/viz/index.html` from the root of the
cloned repo.
## libsurvive Tools
- `survive-cli` - This is the main command line interface to the library; really just a very thin wrapper around the library.
- `survive-websocketd` - A script which runs `survive-cli` through `websocketd` with all the appropriate flags set.
- `sensors-readout` - Display raw sensor information in a ncurses display
## Using libsurvive in your own application
### Lower level API
This section is mainly concerned about *consuming* data from the library; for information on how to *provide* data, see
the [drivers section](https://github.com/cntools/libsurvive/#drivers).
The main way to extend and use libsurvive is to use the various callbacks exposed by the library to get information from
the system. Use of libsurvive in this way is recommended if you need access to all data going in -- IMU data, individual
light data, and/or final pose data. However care needs to be taken to not bog down the system. In general these callbacks
are invoked from the thread collecting the data; so if you have unnecessary delays in processing data will be dropped
which will cause poor tracking performance.
The full list of hooks is [here](https://github.com/cntools/libsurvive/blob/master/include/libsurvive/survive_hooks.h).
The function types are [here](https://github.com/cntools/libsurvive/blob/master/include/libsurvive/survive_types.h#L168).
You install your custom hook via:
`<hook-name>_process_func survive_install_<hook-name>_fn(SurviveContext *ctx, <hook-name>_process_func fbp);`
This returns the previously set function for that particular hook; which you can choose to call in your own callback. This
is somewhat more cumbersome than just having the callbacks return `true` or `false`; but allows the flexibility to call
the previously defined function before or after your code, or not at all.
These hooks are used internally within libsurvive; if you provide a hook and do not either call the previously defined or
default function, some data will not make it to the posers.
`SurviveContext` and `SurviveObject` both have a `user_ptr` variable which is zero initialized and not used internally,
and is meant to be set by library consumers for their own purposes. This allows you to install the hook, and not resort
to using globals.
These interfaces are relatively stable, but aren't guaranteed to not change.
Have a look at the other libsurvive tools a the top level of the repository for example usage of the lower level API:
- survive-cli.c
- sensors-readout.c
- simple_pose_test.c
### High level API
The high level `Simple` API is recommended for applications which just need position and velocity data as fast as they
can process that data. It has a few main advantages:
- User code runs in it's own thread; so you can't starve libsurvive of data
- Much more insulated against lower level API changes; so you can upgrade libsurvive versions more easily
The main loop logic tends to look like this in `C`:
```C
while (survive_simple_wait_for_update(actx) && keepRunning) {
for (const SurviveSimpleObject *it = survive_simple_get_next_updated(actx); it != 0;
it = survive_simple_get_next_updated(actx)) {
SurvivePose pose;
uint32_t timecode = survive_simple_object_get_latest_pose(it, &pose);
printf("%s %s (%u): %f %f %f %f %f %f %f\n", survive_simple_object_name(it),
survive_simple_serial_number(it), timecode, pose.Pos[0], pose.Pos[1], pose.Pos[2], pose.Rot[0],
pose.Rot[1], pose.Rot[2], pose.Rot[3]);
}
}
```
Example code for the application interface can be found in [api_example.c](https://github.com/cntools/libsurvive/blob/master/api_example.c).
The full header for the simpler API is available [here](https://github.com/cntools/libsurvive/blob/master/include/libsurvive/survive_api.h).
### Python Bindings
Python bindings are available for python3 on windows and linux through https://pypi.org/project/pysurvive/. You can
install them with
```
pip install pysurvive
```
To build the python bindings, run `python setup.py install` in the repo root. This should install the `pysurvive` package.
An example which streams poses out as they come in:
```
import pysurvive
import sys
actx = pysurvive.SimpleContext(sys.argv)
for obj in actx.Objects():
print(obj.Name())
while actx.Running():
updated = actx.NextUpdated()
if updated:
print(updated.Name(), updated.Pose())
```
There are more examples in `./bindings/python`.
### C# Bindings
The C# bindings wrap both the low level access API and the higher level simpler to use API. It is recommended to use the
higher level API since the low level one relies heavily on callbacks and marshalling makes working with it prone to
errors that are not always easy to solve.
Standard binaries are available at https://www.nuget.org/packages/libsurvive.net/. You can install them for a given
C# project through the visual studio nuget manager tool.
Build the solution [here](https://github.com/cntools/libsurvive/tree/master/bindings/cs) with either visual studio or by
running something like
```
dotnet build -c Release
```
from a terminal to generate the binary `libsurvive.net.dll`. This works in linux as well as windows; but the
filename still ends in `dll`. When you run against this binary, `libsurvive.so` needs to either be in the same directory
(with desired plugins), or on the system path.
The high level api is exposed through the `libsurvive.SurviveAPI` object. It's use is pretty easy; it can just poll for
updates to object positions or button events as in the [Demo project](https://github.com/cntools/libsurvive/tree/master/bindings/cs/Demo/Program.cs):
```cs
using libsurvive;
using System;
namespace Demo
{
class Program
{
static void Main() {
string[] args = System.Environment.GetCommandLineArgs();
var api = new SurviveAPI(args);
while (api.WaitForUpdate()) {
SurviveAPIOObject obj;
while ((obj = api.GetNextUpdated()) != null) {
Console.WriteLine(obj.Name + ": " + obj.LatestPose);
}
}
api.Close();
}
}
}
```
It's also meant to be easy to integrate into code bases based on frame updates; such as in the [Unity example](https://github.com/cntools/libsurvive/blob/master/bindings/cs/UnityViewer/Assets/SurviveObject.cs):
```cs
// Update is called once per frame
void Update() {
var updated = survive?.GetNextUpdated();
if (updated == null)
return;
var updatedObject = getObject(updated.Name);
Vector3 newPosition = Vector3.zero;
Quaternion newRotation = Quaternion.identity;
SurvivePose pose = updated.LatestPose;
newPosition.x = (float) pose.Pos[0];
newPosition.y = (float) pose.Pos[1];
newPosition.z = (float) pose.Pos[2];
newRotation.w = (float) pose.Rot[0];
newRotation.x = (float) pose.Rot[1];
newRotation.y = (float) pose.Rot[2];
newRotation.z = (float) pose.Rot[3];
updatedObject.transform.localPosition = newPosition;
updatedObject.transform.localRotation = newRotation;
}
```
[](https://www.youtube.com/watch?v=FiRLrWWOhLg&feature=youtu.be)
## Data recording
There are a lot of things that can go wrong to give bad tracking or calibration results, and given the wide variety of
devices, configurations and use cases, it's extremely helpful when trying to resolve bugs if there is a data recording
of the bug. This also can get added to our CI system to have automatic testing against that use case.
There are two mechanisms available for recording data: `--record` and `--usbmon-record`.
`--record` is available in every installation, and less setup to use so for pure tracking issues this is usually the
approach to take. However, if the issue is in parsing and understanding the low level data packes from the tracked device,
the `--usbmon-record` option might be more helpful.
### Normal recording
When running any of the libsurvive tools, pass in `--record <filename>.rec.gz`. This will create a data log of everything
the system sees as it runs in that file. This records a large amount of data, so if it is allowed to run for a long time
that file might get very large.
To playback that file, run:
`./survive-cli --playback <filename>.rec.gz`
### Raw USB recording
Occasionally, when dealing with new hardware or certain types of bugs that cause an issue in the USB layer, it is necessary to have a raw capture of the USB data seen / sent. The USBMON driver lets you do this.
Currently this driver is only available on linux and you must have libpcap installed -- `sudo apt install libpcap-dev`. You also need the `usbmon` kernel module installed; but many linux flavors come with that built in.
To start usbmon and prepare it for use for all users, run:
```
sudo modprobe usbmon
sudo setfacl -m u:$USER:r /dev/usbmon* # In sensitive environments, you can run survive-cli with sudo instead.
```
To capture usb data, run:
```
./survive-cli --usbmon-record <filename>.pcap.gz --htcvive <additional options>`
```
You can run that playback with:
```
./survive-cli --usbmon-playback <filename>.pcap.gz [--playback-factor x] <additional options>`
```
If you are sending this file for analysis, note that you need the accompanying `*.usbdevs` file with it to be useful. If you follow the `*.pcap.gz` convention, run something like
```
zip logs.zip *.pcap* config.json
```
and post the `logs.zip` to an issue or to discord.
This driver specifically only captures devices on a white list of VR equipment; but if you don't want to publish raw USB
data to the internet, ask in discord for who to send it to in a private message.
## Common command line flags
Libsurvive is very configurable, and contains a lot of command line options depending on the drivers and options given
at build time.
It's recommended that you install the bash completion for libsurvive if you are working with the command line options:
`sudo cp survive_autocomplete.sh /etc/bash_completion.d/`.
The most useful command line option for debugging is `--v` -- this sets the reporting level. This verbosity level roughly follows this guideline:
- `--v 10` - Statistics and information displayed either at the start or end of the application.
- `--v 100` - Information displayed at many common points while tracking
- `--v 150` - Information displayed for almost every pose output
- `--v 250` - Information displayed for almost all light data event in the system
- `--v 1000` - Everything.
Running at higher verbosity (>100) will make the visualization tool sluggish.
`--force-calibrate`: This reruns calibration but reuses OOTX; which makes it much faster to run.
`--playback-factor`: When playing back a recording, this will speed up the playback (0 is run everything as fast as possible) or slow it down (2 takes twice as much time)
`--lighthouse-gen`: Force the system to use a particular generation of lighthouse. Right now, sometimes the system misidentified lighthouse 1 (The purely square base stations) for lighthouse 2 (The rounded face base stations) or vice versa. As we find these cases, we are fixing them but this lets a misbehaving system be useful in the meantime.
# Drivers
These are the different drivers for providing information into libsurvive. All of them are encapsulated in the `src` directory
with a `driver_` prefix. Each driver can be specified with a `--<driver-name>` flag. You can disable a default driver (eg, `htcvive`) with
`--no-<driver-name>`.
- `htcvive` - This is the main driver which provides data via USB connection to vive hardware.
- `simulator` - This simulates a device floating around while providing realistic light / IMU data into libsurvive. Useful
for testing different features.
- `playback` - The playback driver is what enables record/playback functionality. It replays a file into the various data points.
- `usbmon` - USBmon can be ran concurrent with steamvr to allow both systems to use the tracked object data.
- `openvr` - This driver exposes external poses and velocities and can be ran with `usbmon` to compare the two systems.
## Custom Drivers
Integrating a driver is meant to be relatively straight forward and the above mentioned ones are good references for how
to do it.
The general approach is to compile to a shared object / DLL with the name of `driver_<name>.so` in the plugins folder.
The internals of libsurvive enumerate these plugins and run libsurvive registered function from the form:
```C
int DriverRegExample(SurviveContext *ctx) {
if(...error...) {
return SURVIVE_DRIVER_ERROR;
}
return SURVIVE_DRIVER_NORMAL;
}
REGISTER_LINKTIME(DriverRegExample)
```
It isn't necessary for a driver to register anything else; but to be integrated into libsurvive the driver must either
expose a poll / close function or a thread / close function.
The simpliest approach is a poll driver:
```void survive_add_driver(SurviveContext *ctx, void *user_ptr, DeviceDriverCb poll, DeviceDriverCb close)```
The poll function is called continuously while the system is running; and the close function is called at
shutdown.
More versatile is a threaded driver:
```bool *survive_add_threaded_driver(SurviveContext *ctx, void *driver_data, const char *name, void *(routine)(void *), DeviceDriverCb close);```
This starts a thread with the given function and name.
In the threaded driver case, when accessing any members of `SurviveContext` or `SurviveObject`, you
must lock and release around that access with the following functions:
```
void survive_get_ctx_lock(SurviveContext *ctx);
void survive_release_ctx_lock(SurviveContext *ctx);
```
Improper locking or unlocking can result in race conditions or dead locks.
Within either the threaded function or the polling function, it is then up to the driver to call the appropriate
hook functions with whatever data they are exposing. Generally the driver will also call `survive_create_device`
and only concern itself with that device. More than one driver can be running at a time; but they all assume the same
lighthouse configuration.
A good example of this in action is `driver_simulator.c` which calls various light data and IMU callbacks
with a custom `SurviveObject` type. `driver_openvr.cc` demonstrates how to incorporate external position data into the
library.
# FAQ
Other projects using libsurvive
* The [Monado OpenXR runtime](https://monado.freedesktop.org/) uses libsurvive as one of its HMD and controller drivers.
* OpenXR applications that run on Monado include the [OpenXR plugin for Godot 3.x](https://github.com/GodotVR/godot_openxr)
* There is a very unofficial (and not upstreamable) [OpenHMD/libsurvive fork](https://github.com/ChristophHaag/OpenHMD/commits/libsurvive2) that adds a libsurvive driver.
* This OpenHMD/libsurvive fork can be plugged into [SteamVR-OpenHMD](https://github.com/ChristophHaag/SteamVR-OpenHMD) or used natively with the [OpenHMD plugin for Godot 3.x](https://github.com/BastiaanOlij/godot_openhmd).
## Addendum and notes
Thanks to Mr. Faul for our logo!
Special thanks to @nairol for an extreme amount of detail in reverse engineering the existing HTC Vive system on his https://github.com/nairol/LighthouseRedox project.
Raw data
{
"_id": null,
"home_page": "https://github.com/cntools/libsurvive",
"name": "pysurvive",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "",
"author_email": "",
"download_url": "",
"platform": null,
"description": "# libsurvive [](https://github.com/cntools/libsurvive/actions/workflows/cmake.yml)[](https://github.com/cntools/libsurvive/actions/workflows/build_nuget.yml)[](https://github.com/cntools/libsurvive/actions/workflows/build_wheels.yml)\n\n\n\n\nLibsurvive is a set of tools and libraries that enable 6 dof tracking on \n[lighthouse and vive](https://en.wikipedia.org/wiki/HTC_Vive) based systems that is completely open source and can run \non any device. It currently supports both SteamVR 1.0 and SteamVR 2.0 generation of devices and should support any tracked\nobject commercially available. \n\nSince the focus is on tracking; it does not independently run the HMD. For an open souce stack that does that see [monado](https://monado.freedesktop.org/)\n\nMost of the development is discussed on Discord. [Join the chat and discussion in our discord!](https://discordapp.com/invite/7QbCAGS). There is also a [matrix bridge](https://app.element.io/#/room/#libsurvive-main:matrix.org) available to join the discussion. \n\nAn example application is libsurvive running the controllers and HMD in Godot:\n[](https://www.youtube.com/watch?v=yC75XknKTo0)\n\n\nTable of Contents\n=================\n\n * [Quick start](#quick-start)\n * [Debian](#debian)\n * [Windows](#windows)\n * [Current Status](#current-status)\n * [Roadmap](#roadmap)\n * [Getting Started](#getting-started)\n * [Calibration](#calibration)\n * [Visualization](#visualization)\n * [libsurvive Tools](#libsurvive-tools)\n * [Using libsurvive in your own application](#using-libsurvive-in-your-own-application)\n * [Lower level API](#lower-level-api)\n * [High level API](#high-level-api)\n * [Python Bindings](#python-bindings)\n * [C# Bindings](#c-bindings)\n * [Data recording](#data-recording)\n * [Normal recording](#normal-recording)\n * [Raw USB recording](#raw-usb-recording)\n * [Common command line flags](#common-command-line-flags)\n * [Drivers](#drivers)\n * [Custom Drivers](#custom-drivers)\n * [FAQ](#faq)\n * [Addendum and notes](#addendum-and-notes)\n\n# Quick start\n\n## Debian\n```\ngit clone git@github.com:cntools/libsurvive.git --recursive\ncd libsurvive\nsudo cp ./useful_files/81-vive.rules /etc/udev/rules.d/\nsudo udevadm control --reload-rules && udevadm trigger\nsudo apt-get install build-essential zlib1g-dev libx11-dev libusb-1.0-0-dev freeglut3-dev liblapacke-dev libopenblas-dev libatlas-base-dev cmake\nmake\n```\n\nPlug in a headset / tracker / controller / etc and run:\n```\n./bin/survive-cli\n```\n\nThis should calibrate and display your setup. \n\nFor visualization, you can either download a binary of [websocketd](https://github.com/joewalnes/websocketd/releases/) or enable the experimental apt source and use `sudo apt install websocketd`. After which you can run:\n\n```\n./bin/survive-websocketd & xdg-open ./tools/viz/index.html\n```\n\n[](https://www.youtube.com/watch?v=l4doRSXM0tU)\n\n## Windows\n\nIf you have `cmake` installed on your path you can simply run the `make.ps1` script by right clicking it and seleting `Run with PowerShell`.\n\nA more manual approach is to open CMakeLists file in something like [CMake GUI](https://cmake.org/runningcmake/) to build\nfrom source using one of the visual studio generators. This will also let you set various build options. The build uses NuGet \nto get the [necessary development dependencies](https://www.nuget.org/packages/lapacke/). After you generate the project, open the\nsolution in visual studio and run build all. \n\n[Websocketd](http://websocketd.com/) should work the same with with the visualization tool; assuming you put it somewhere in the system path. In the build binary folder (`./build-win/Release` if you built from `make.ps1`) there should be a `survive-websocketd.ps1` which can be ran as a PowerShell file. \n\nProbably the easiest way to get started with libsurvive on windows is to check out the [release binaries](https://github.com/cntools/libsurvive/releases).\n\n# Current Status\n\nThe tracking and device enumeration work fairly well at this point; but there isn't an extremely large testing base and \nthe tools aren't as polished as the comparable ones bundled in SteamVR. Work is ongoing to quantify how accurate the \ntracking is and to improve the user experience. \n\n# Roadmap\n\nA very loose collection of things that are on the short term agenda:\n\n- Dynamic correction of calibration. This would detect and silently recalibrate lighthouses that might have moved. The \nend goal is to have a system where the user is never aware of any calibration requirements. \n- An android binary / port\n- Hard numbers on the accuracy and precision of libsurvive as a tracking system. If anyone wants to contribute time testing\non a CNC please get in our [discord](https://discordapp.com/invite/7QbCAGS)\n- Better handling of data starvation -- if the USB or radio connection stutters too long, the tracking will occasionally\nglitch out for a brief period. \n- Use something like usbmon for windows\n\n# Getting Started\n\nIf you followed the quick start guide, you'll notice that the first thing you must do (for linux) is install udev rules:\n\n```\nsudo cp ./useful_files/81-vive.rules to /etc/udev/rules.d/\nsudo udevadm control --reload-rules && udevadm trigger\n```\n\nThis allows one to use those devices without having root. No such steps are necessary in windows. \n\nAfter that, when you run `survive-cli` or `survive-websocketd` it should recognize any plugged in vive devices and start\ncalibrating and tracking those devices. \n\n**Important: Close SteamVR for best results. Depending on the system, libsurvive\nwill either cause SteamVR to lose connection to the device or will compete for bandwidth with it**\n\n## Calibration\n\nCalibration is the process which establishes where the lighthouses are set up in relation to the tracked objects. The\nfirst time you run libsurvive, it can take up to ten seconds to communicate with the lighthouses and figure out where \nthey are. \n\nCalibration will continuously integrate objects data so long as they are momentarily stationary. Due to this, you might notice lighthouses shift slighty while it gets a good lock. Subsequent runs should shift much less. \n\nOnce you do this one time, it is saved in `config.json` in `XDG_CONFIG_HOME/libsurvive`. If you delete this file, it will simply\nrecalibrate; but it is faster to use the `--force-calibrate` flag. Some drivers change the name of this file -- notably recordings will instead use `<event_file>.json`. \n\nIf you have a large space, and you can not centrally locate a single device to 'see' all lighthouses, you can calibrate\na few lighthouses and move the tracked object into the field of view of the uncalibrated lighthouse while keeping it in\nview of at least one of the calibrated ones. Set it down so it doesn't move; and the remaining lighthouse(s) should now\ncalibrate. \n\n**Important: Resetting calibration automatically when a lighthouse is moved is being planned on but is not currently \navailable. If one of the calibrated lighthouses are moved, you either have to redo calibration by deleting the config.json\nfile or passing `--force-calibrate` into any of the libsurvive tools.**\n\n\n## Visualization\n\nThe main visualization tool is a THREE.js page which is fed data through (websocketd)[http://websocketd.com/]. To use\nthis tool, run `survive-websocketd [options]` and open a web browser to `./tools/viz/index.html` from the root of the\ncloned repo. \n\n\n\n## libsurvive Tools\n\n- `survive-cli` - This is the main command line interface to the library; really just a very thin wrapper around the library.\n- `survive-websocketd` - A script which runs `survive-cli` through `websocketd` with all the appropriate flags set.\n- `sensors-readout` - Display raw sensor information in a ncurses display\n\n## Using libsurvive in your own application\n\n### Lower level API\n\nThis section is mainly concerned about *consuming* data from the library; for information on how to *provide* data, see\nthe [drivers section](https://github.com/cntools/libsurvive/#drivers).\n\nThe main way to extend and use libsurvive is to use the various callbacks exposed by the library to get information from\nthe system. Use of libsurvive in this way is recommended if you need access to all data going in -- IMU data, individual\nlight data, and/or final pose data. However care needs to be taken to not bog down the system. In general these callbacks\nare invoked from the thread collecting the data; so if you have unnecessary delays in processing data will be dropped \nwhich will cause poor tracking performance. \n\nThe full list of hooks is [here](https://github.com/cntools/libsurvive/blob/master/include/libsurvive/survive_hooks.h). \nThe function types are [here](https://github.com/cntools/libsurvive/blob/master/include/libsurvive/survive_types.h#L168). \n\nYou install your custom hook via:\n\n`<hook-name>_process_func survive_install_<hook-name>_fn(SurviveContext *ctx, <hook-name>_process_func fbp);`\n\nThis returns the previously set function for that particular hook; which you can choose to call in your own callback. This\nis somewhat more cumbersome than just having the callbacks return `true` or `false`; but allows the flexibility to call\nthe previously defined function before or after your code, or not at all. \n\nThese hooks are used internally within libsurvive; if you provide a hook and do not either call the previously defined or\ndefault function, some data will not make it to the posers. \n\n`SurviveContext` and `SurviveObject` both have a `user_ptr` variable which is zero initialized and not used internally, \nand is meant to be set by library consumers for their own purposes. This allows you to install the hook, and not resort \nto using globals. \n\nThese interfaces are relatively stable, but aren't guaranteed to not change. \n\nHave a look at the other libsurvive tools a the top level of the repository for example usage of the lower level API:\n- survive-cli.c\n- sensors-readout.c\n- simple_pose_test.c\n\n### High level API\n\nThe high level `Simple` API is recommended for applications which just need position and velocity data as fast as they\ncan process that data. It has a few main advantages:\n\n- User code runs in it's own thread; so you can't starve libsurvive of data\n- Much more insulated against lower level API changes; so you can upgrade libsurvive versions more easily\n\nThe main loop logic tends to look like this in `C`:\n\n```C\nwhile (survive_simple_wait_for_update(actx) && keepRunning) {\n for (const SurviveSimpleObject *it = survive_simple_get_next_updated(actx); it != 0;\n it = survive_simple_get_next_updated(actx)) {\n SurvivePose pose;\n uint32_t timecode = survive_simple_object_get_latest_pose(it, &pose);\n printf(\"%s %s (%u): %f %f %f %f %f %f %f\\n\", survive_simple_object_name(it),\n survive_simple_serial_number(it), timecode, pose.Pos[0], pose.Pos[1], pose.Pos[2], pose.Rot[0],\n pose.Rot[1], pose.Rot[2], pose.Rot[3]);\n }\n}\n```\n\nExample code for the application interface can be found in [api_example.c](https://github.com/cntools/libsurvive/blob/master/api_example.c).\n\nThe full header for the simpler API is available [here](https://github.com/cntools/libsurvive/blob/master/include/libsurvive/survive_api.h). \n\n### Python Bindings\n\nPython bindings are available for python3 on windows and linux through https://pypi.org/project/pysurvive/. You can \ninstall them with\n\n```\npip install pysurvive\n```\n\nTo build the python bindings, run `python setup.py install` in the repo root. This should install the `pysurvive` package.\n\nAn example which streams poses out as they come in:\n\n```\nimport pysurvive\nimport sys\n\nactx = pysurvive.SimpleContext(sys.argv)\n\nfor obj in actx.Objects():\n print(obj.Name())\n\nwhile actx.Running():\n updated = actx.NextUpdated()\n if updated:\n print(updated.Name(), updated.Pose())\n```\n\nThere are more examples in `./bindings/python`.\n\n### C# Bindings\n\nThe C# bindings wrap both the low level access API and the higher level simpler to use API. It is recommended to use the\nhigher level API since the low level one relies heavily on callbacks and marshalling makes working with it prone to \nerrors that are not always easy to solve. \n\nStandard binaries are available at https://www.nuget.org/packages/libsurvive.net/. You can install them for a given\nC# project through the visual studio nuget manager tool.\n\nBuild the solution [here](https://github.com/cntools/libsurvive/tree/master/bindings/cs) with either visual studio or by\nrunning something like\n\n```\ndotnet build -c Release\n```\n\nfrom a terminal to generate the binary `libsurvive.net.dll`. This works in linux as well as windows; but the \nfilename still ends in `dll`. When you run against this binary, `libsurvive.so` needs to either be in the same directory\n(with desired plugins), or on the system path. \n\nThe high level api is exposed through the `libsurvive.SurviveAPI` object. It's use is pretty easy; it can just poll for\nupdates to object positions or button events as in the [Demo project](https://github.com/cntools/libsurvive/tree/master/bindings/cs/Demo/Program.cs):\n\n```cs\nusing libsurvive;\nusing System;\n\nnamespace Demo\n{\n \n class Program\n {\n\t\tstatic void Main() {\n\t\t\tstring[] args = System.Environment.GetCommandLineArgs();\n\t\t\tvar api = new SurviveAPI(args);\n\n\t\t\twhile (api.WaitForUpdate()) {\n\t\t\t\tSurviveAPIOObject obj;\n\t\t\t\twhile ((obj = api.GetNextUpdated()) != null) {\n\t\t\t\t\tConsole.WriteLine(obj.Name + \": \" + obj.LatestPose);\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tapi.Close();\n\t\t}\n\t}\n}\n\n```\n\nIt's also meant to be easy to integrate into code bases based on frame updates; such as in the [Unity example](https://github.com/cntools/libsurvive/blob/master/bindings/cs/UnityViewer/Assets/SurviveObject.cs):\n\n```cs\n// Update is called once per frame\nvoid Update() {\n var updated = survive?.GetNextUpdated();\n\n if (updated == null)\n return;\n\n var updatedObject = getObject(updated.Name);\n\n Vector3 newPosition = Vector3.zero;\n Quaternion newRotation = Quaternion.identity;\n SurvivePose pose = updated.LatestPose;\n newPosition.x = (float) pose.Pos[0];\n newPosition.y = (float) pose.Pos[1];\n newPosition.z = (float) pose.Pos[2];\n newRotation.w = (float) pose.Rot[0];\n newRotation.x = (float) pose.Rot[1];\n newRotation.y = (float) pose.Rot[2];\n newRotation.z = (float) pose.Rot[3];\n updatedObject.transform.localPosition = newPosition;\n updatedObject.transform.localRotation = newRotation;\n}\n```\n\n[](https://www.youtube.com/watch?v=FiRLrWWOhLg&feature=youtu.be)\n\n## Data recording\n\nThere are a lot of things that can go wrong to give bad tracking or calibration results, and given the wide variety of \ndevices, configurations and use cases, it's extremely helpful when trying to resolve bugs if there is a data recording \nof the bug. This also can get added to our CI system to have automatic testing against that use case. \n\nThere are two mechanisms available for recording data: `--record` and `--usbmon-record`. \n\n`--record` is available in every installation, and less setup to use so for pure tracking issues this is usually the \napproach to take. However, if the issue is in parsing and understanding the low level data packes from the tracked device,\nthe `--usbmon-record` option might be more helpful. \n\n### Normal recording\n\nWhen running any of the libsurvive tools, pass in `--record <filename>.rec.gz`. This will create a data log of everything\nthe system sees as it runs in that file. This records a large amount of data, so if it is allowed to run for a long time\nthat file might get very large. \n\nTo playback that file, run:\n\n`./survive-cli --playback <filename>.rec.gz`\n\n### Raw USB recording\n\nOccasionally, when dealing with new hardware or certain types of bugs that cause an issue in the USB layer, it is necessary to have a raw capture of the USB data seen / sent. The USBMON driver lets you do this.\n\nCurrently this driver is only available on linux and you must have libpcap installed -- `sudo apt install libpcap-dev`. You also need the `usbmon` kernel module installed; but many linux flavors come with that built in. \n\nTo start usbmon and prepare it for use for all users, run:\n\n```\nsudo modprobe usbmon\nsudo setfacl -m u:$USER:r /dev/usbmon* # In sensitive environments, you can run survive-cli with sudo instead.\n```\n\nTo capture usb data, run:\n\n```\n./survive-cli --usbmon-record <filename>.pcap.gz --htcvive <additional options>` \n```\n\nYou can run that playback with:\n```\n./survive-cli --usbmon-playback <filename>.pcap.gz [--playback-factor x] <additional options>` \n```\n\nIf you are sending this file for analysis, note that you need the accompanying `*.usbdevs` file with it to be useful. If you follow the `*.pcap.gz` convention, run something like\n\n```\nzip logs.zip *.pcap* config.json\n```\n\nand post the `logs.zip` to an issue or to discord. \n\nThis driver specifically only captures devices on a white list of VR equipment; but if you don't want to publish raw USB\ndata to the internet, ask in discord for who to send it to in a private message. \n\n## Common command line flags\n\nLibsurvive is very configurable, and contains a lot of command line options depending on the drivers and options given\nat build time. \n\nIt's recommended that you install the bash completion for libsurvive if you are working with the command line options:\n\n`sudo cp survive_autocomplete.sh /etc/bash_completion.d/`.\n\nThe most useful command line option for debugging is `--v` -- this sets the reporting level. This verbosity level roughly follows this guideline:\n\n- `--v 10` - Statistics and information displayed either at the start or end of the application.\n- `--v 100` - Information displayed at many common points while tracking\n- `--v 150` - Information displayed for almost every pose output\n- `--v 250` - Information displayed for almost all light data event in the system\n- `--v 1000` - Everything. \n\nRunning at higher verbosity (>100) will make the visualization tool sluggish. \n\n`--force-calibrate`: This reruns calibration but reuses OOTX; which makes it much faster to run. \n\n`--playback-factor`: When playing back a recording, this will speed up the playback (0 is run everything as fast as possible) or slow it down (2 takes twice as much time)\n\n`--lighthouse-gen`: Force the system to use a particular generation of lighthouse. Right now, sometimes the system misidentified lighthouse 1 (The purely square base stations) for lighthouse 2 (The rounded face base stations) or vice versa. As we find these cases, we are fixing them but this lets a misbehaving system be useful in the meantime. \n\n# Drivers\n\nThese are the different drivers for providing information into libsurvive. All of them are encapsulated in the `src` directory\nwith a `driver_` prefix. Each driver can be specified with a `--<driver-name>` flag. You can disable a default driver (eg, `htcvive`) with\n`--no-<driver-name>`.\n\n- `htcvive` - This is the main driver which provides data via USB connection to vive hardware.\n- `simulator` - This simulates a device floating around while providing realistic light / IMU data into libsurvive. Useful\nfor testing different features.\n- `playback` - The playback driver is what enables record/playback functionality. It replays a file into the various data points.\n- `usbmon` - USBmon can be ran concurrent with steamvr to allow both systems to use the tracked object data. \n- `openvr` - This driver exposes external poses and velocities and can be ran with `usbmon` to compare the two systems.\n\n## Custom Drivers\n\nIntegrating a driver is meant to be relatively straight forward and the above mentioned ones are good references for how \nto do it. \n\nThe general approach is to compile to a shared object / DLL with the name of `driver_<name>.so` in the plugins folder. \nThe internals of libsurvive enumerate these plugins and run libsurvive registered function from the form:\n\n```C\nint DriverRegExample(SurviveContext *ctx) {\n if(...error...) {\n return SURVIVE_DRIVER_ERROR;\n }\n return SURVIVE_DRIVER_NORMAL;\n}\nREGISTER_LINKTIME(DriverRegExample)\n```\n\nIt isn't necessary for a driver to register anything else; but to be integrated into libsurvive the driver must either\nexpose a poll / close function or a thread / close function.\n\nThe simpliest approach is a poll driver:\n\n```void survive_add_driver(SurviveContext *ctx, void *user_ptr, DeviceDriverCb poll, DeviceDriverCb close)```\n\nThe poll function is called continuously while the system is running; and the close function is called at\nshutdown. \n\nMore versatile is a threaded driver:\n\n```bool *survive_add_threaded_driver(SurviveContext *ctx, void *driver_data, const char *name, void *(routine)(void *), DeviceDriverCb close);```\n\nThis starts a thread with the given function and name. \n\nIn the threaded driver case, when accessing any members of `SurviveContext` or `SurviveObject`, you\n must lock and release around that access with the following functions:\n\n```\nvoid survive_get_ctx_lock(SurviveContext *ctx);\nvoid survive_release_ctx_lock(SurviveContext *ctx);\n```\n\nImproper locking or unlocking can result in race conditions or dead locks. \n\nWithin either the threaded function or the polling function, it is then up to the driver to call the appropriate\nhook functions with whatever data they are exposing. Generally the driver will also call `survive_create_device` \nand only concern itself with that device. More than one driver can be running at a time; but they all assume the same\nlighthouse configuration. \n\nA good example of this in action is `driver_simulator.c` which calls various light data and IMU callbacks\nwith a custom `SurviveObject` type. `driver_openvr.cc` demonstrates how to incorporate external position data into the \nlibrary. \n\n\n# FAQ\n\nOther projects using libsurvive\n\n * The [Monado OpenXR runtime](https://monado.freedesktop.org/) uses libsurvive as one of its HMD and controller drivers.\n * OpenXR applications that run on Monado include the [OpenXR plugin for Godot 3.x](https://github.com/GodotVR/godot_openxr)\n * There is a very unofficial (and not upstreamable) [OpenHMD/libsurvive fork](https://github.com/ChristophHaag/OpenHMD/commits/libsurvive2) that adds a libsurvive driver.\n * This OpenHMD/libsurvive fork can be plugged into [SteamVR-OpenHMD](https://github.com/ChristophHaag/SteamVR-OpenHMD) or used natively with the [OpenHMD plugin for Godot 3.x](https://github.com/BastiaanOlij/godot_openhmd).\n\n## Addendum and notes\n\nThanks to Mr. Faul for our logo!\nSpecial thanks to @nairol for an extreme amount of detail in reverse engineering the existing HTC Vive system on his https://github.com/nairol/LighthouseRedox project.\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Libsurvive is a set of tools and libraries that enable 6 dof tracking on lighthouse and vive based systems that is completely open source and can run on any device. It currently supports both SteamVR 1.0 and SteamVR 2.0 generation of devices and should support any tracked object commercially available.",
"version": "1.1.21",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "648a5d31d95ea550397cb47bc8157db7677faac23de06e17126cefb2979c1642",
"md5": "18fa14b59692d2682e658ea2234607a7",
"sha256": "6608a34e4afabdd3fce17fec84ad2efc169b0e2e2a79f833af65aaa55c18a5b6"
},
"downloads": -1,
"filename": "pysurvive-1.1.21-cp310-cp310-win_amd64.whl",
"has_sig": false,
"md5_digest": "18fa14b59692d2682e658ea2234607a7",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": null,
"size": 1420191,
"upload_time": "2023-03-11T08:30:00",
"upload_time_iso_8601": "2023-03-11T08:30:00.025670Z",
"url": "https://files.pythonhosted.org/packages/64/8a/5d31d95ea550397cb47bc8157db7677faac23de06e17126cefb2979c1642/pysurvive-1.1.21-cp310-cp310-win_amd64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "749d82daf4a3e743717090a30df0fa9b10a0f1c5db3e1fc8ffb42a48a9565241",
"md5": "d205cd92d7b21782078984ea3d66366d",
"sha256": "52b77d085132b99cfc0f556fe3f0d6b8d360e672bb0d824f6c2cc89478944011"
},
"downloads": -1,
"filename": "pysurvive-1.1.21-cp36-cp36m-win_amd64.whl",
"has_sig": false,
"md5_digest": "d205cd92d7b21782078984ea3d66366d",
"packagetype": "bdist_wheel",
"python_version": "cp36",
"requires_python": null,
"size": 1420165,
"upload_time": "2023-03-11T08:30:02",
"upload_time_iso_8601": "2023-03-11T08:30:02.842090Z",
"url": "https://files.pythonhosted.org/packages/74/9d/82daf4a3e743717090a30df0fa9b10a0f1c5db3e1fc8ffb42a48a9565241/pysurvive-1.1.21-cp36-cp36m-win_amd64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2112ae7809759f5adf6a485c79c7b74a67411696fe9e009ce80b4b573a564349",
"md5": "11988ba7e97154ad563b76c2ef24c464",
"sha256": "8972474435611442eb80c0e81bdfbd427cdb74b13e1fc54e732f269a2982a236"
},
"downloads": -1,
"filename": "pysurvive-1.1.21-cp37-cp37m-win_amd64.whl",
"has_sig": false,
"md5_digest": "11988ba7e97154ad563b76c2ef24c464",
"packagetype": "bdist_wheel",
"python_version": "cp37",
"requires_python": null,
"size": 1420172,
"upload_time": "2023-03-11T08:30:04",
"upload_time_iso_8601": "2023-03-11T08:30:04.652350Z",
"url": "https://files.pythonhosted.org/packages/21/12/ae7809759f5adf6a485c79c7b74a67411696fe9e009ce80b4b573a564349/pysurvive-1.1.21-cp37-cp37m-win_amd64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8b68b27147ff891121b9f188daba6399a5ae3cd17438e73ebf477491513b778a",
"md5": "a641c50327e1ddeb18b906c045c4c7bc",
"sha256": "e0d3bfe855a87a1f677743000858597e5cb1065eb0f51a4ee0d50c87f8552234"
},
"downloads": -1,
"filename": "pysurvive-1.1.21-cp38-cp38-win_amd64.whl",
"has_sig": false,
"md5_digest": "a641c50327e1ddeb18b906c045c4c7bc",
"packagetype": "bdist_wheel",
"python_version": "cp38",
"requires_python": null,
"size": 1420174,
"upload_time": "2023-03-11T08:30:05",
"upload_time_iso_8601": "2023-03-11T08:30:05.958419Z",
"url": "https://files.pythonhosted.org/packages/8b/68/b27147ff891121b9f188daba6399a5ae3cd17438e73ebf477491513b778a/pysurvive-1.1.21-cp38-cp38-win_amd64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "bbba8f15517ff4e6302fe8520ff1f9856aba65df6b36674d03176ffc8963cc69",
"md5": "92d7efd03df4467310f68c106eead966",
"sha256": "3ffe465492275a2ae0ba9c0f86a02179c0d6e3a83896b5a923a9dab6f349b274"
},
"downloads": -1,
"filename": "pysurvive-1.1.21-cp39-cp39-win_amd64.whl",
"has_sig": false,
"md5_digest": "92d7efd03df4467310f68c106eead966",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": null,
"size": 1420172,
"upload_time": "2023-03-11T08:30:07",
"upload_time_iso_8601": "2023-03-11T08:30:07.820604Z",
"url": "https://files.pythonhosted.org/packages/bb/ba/8f15517ff4e6302fe8520ff1f9856aba65df6b36674d03176ffc8963cc69/pysurvive-1.1.21-cp39-cp39-win_amd64.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-03-11 08:30:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "cntools",
"github_project": "libsurvive",
"travis_ci": true,
"coveralls": false,
"github_actions": true,
"lcname": "pysurvive"
}
