aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorJustin Berger <j.david.berger@gmail.com>2018-04-02 16:38:04 -0600
committerJustin Berger <j.david.berger@gmail.com>2018-04-02 16:39:11 -0600
commit0f5bf3c2f9fd7481d6b3c7c5364a08fe3ecdb2fb (patch)
tree33bf02cd36539a87148953764d79d914f13adc0f /docs
parent83d304551bb0052f6b67365c558ea6d825585e39 (diff)
downloadlibsurvive-0f5bf3c2f9fd7481d6b3c7c5364a08fe3ecdb2fb.tar.gz
libsurvive-0f5bf3c2f9fd7481d6b3c7c5364a08fe3ecdb2fb.tar.bz2
Added documentation about writing a poser
Diffstat (limited to 'docs')
-rw-r--r--docs/writing_a_poser.md66
1 files changed, 66 insertions, 0 deletions
diff --git a/docs/writing_a_poser.md b/docs/writing_a_poser.md
new file mode 100644
index 0000000..ac450e3
--- /dev/null
+++ b/docs/writing_a_poser.md
@@ -0,0 +1,66 @@
+# How to write a poser
+
+Posers in libsurvive serve two related purposes:
+
+1) If the lighthouse position isn't known, solve for them.
+2) If the lighthouse position is known, solve for the position of objects in the scene.
+
+To do this, a poser is given a variety of different signals about the current state of the input.
+
+# Registering a Poser
+
+In an effort to decouple posers from the underlying mechanics, posers are registered through a link-time
+constructor. Make a function in the following form:
+
+```
+#include "survive.h"
+
+int PoserMyPoser(SurviveObject *so, PoserData *pd) {
+ switch (pd->pt) {
+ case POSERDATA_LIGHT: {
+ PoserDataLight *lightData = (PoserDataLight *)pd;
+ return -1;
+ }
+ case POSERDATA_FULL_SCENE: {
+ PoserDataFullScene pdfs = (PoserDataFullScene *)(pd);
+ return -1;
+ }
+ case POSERDATA_IMU: {
+ PoserDataIMU *imuData = (PoserDataIMU *)pd;
+ return -1;
+ }
+ return -1;
+}
+
+REGISTER_LINKTIME(PoserMyPoser);
+
+```
+
+Note that the prefix of the function MUST be "Poser" for it to work.
+
+Now compile it into the shared object, and it will be one of the poser options available.
+
+## Input to a poser
+
+`PoserData` is a tagged union that contains the new input to the poser. See above for how to get the concrete
+types for each type of event.
+
+If you don't handle a given input, return -1. If you do, return a 0. If you have a more specific
+error number, you can return that as well.
+
+## Output from a poser
+
+To report an objects location for any one of the events above, call the function
+
+`PoserData_poser_raw_pose_func`. See the documentation in poser.h for more info.
+
+To report an initial solution to the lighthouse solution, call the function `PoserData_lighthouse_pose_func`. Again,
+see documention in poser.h
+
+## Calibration data
+
+Note that by default, no angle data is presented in a calibrated fashion. Depending on your use case, you
+may want to treat the data by grouping X, Y pairs and trying to undistort them. You can do this with the library
+function `survive_apply_bsd_calibration` from `survive_reproject.h`. Please understand though that this is, at best, an
+approximation and can be far off if the angle values are too spread out in time.
+