FAQ.md

FAQ

• How can I enable logging?
• How can I control playback?
• How do I run the kinect2 example?
• How do I run the openni2 example?
• Where can I find cubemap images?
• Where can I find volumetric data?

How can I enable logging?

You can enable various log levels through environment variables

• grimoire: RUST_LOG=info,debug
• GStreamer: GST_DEBUG=3, see https://gstreamer.freedesktop.org/data/doc/gstreamer/head/gstreamer/html/gst-running.html

How can I control playback?

• ESC: close the window and exit the application
• F1: toggle play/pause (freezes/unfreezes iTime and iFrame)
• F2: decrement iFrame by 1, and iTime by 16ms, does not increment video or audio
• F3: increment iFrame by 1, and iTime by 16ms, does not decrement video or audio
• F4: reset iTime and iFrame to 0

The controls are mapped to the function keys because I believe that these keys are the least likely to also be used in a shader using the keyboard resource. It is likely that I will make use of the remaning function keys for future features. Users should avoid using the function keys in shaders that require keyboard input.

How do I run the kinect2 example?

Here are the steps I took to use the freenect2src GStreamer element provided by https://github.com/lubosz/gst-plugins-vr on MacOS. Change set: (https://github.com/jshrake/gst-plugins-vr/compare/master...jshrake:grimoire?expand=1)

Build and install libfreenect2 from source:

$ brew install libusb
$ git clone https://github.com/OpenKinect/libfreenect2.git
$ cd libfreenect2
$ cmake -H. -Bbuild -DCMAKE_BUILD_TYPE=Release
$ cmake --build build
$ sudo make -C build install

Build and install my fork of gst-plugins-vr.

$ git clone https://github.com/jshrake/gst-plugins-vr
$ cd gst-plugins-vr
$ git checkout grimoire
$ ./configure
$ make
$ sudo make install

Run the example:

$ LIBFREENECT2_PIPELINE=cl cargo run -- examples/kinect2.glsl

If the cl libfreenect2 pipeline doesn't work, try cpu or cuda. grimoire is currently not compatible with the default gl pipeline.

How do I run the openni2.glsl example?

This shader uses an experimental GStreamer plugin than can cause grimoire to segfault

Here are the steps I took to use the openni2src GStreamer element provided by gst-plugins-bad on MacOS. I forked gst-plugins-bad and made changes to the openni2src element. Note that using this plugin causes grimoire to sefault on TOML configuration changes.

Build and install libfreenect2 from source:

$ brew install libusb
$ git clone https://github.com/OpenKinect/libfreenect2.git
$ cd libfreenect2
$ cmake -H. -Bbuild -DCMAKE_BUILD_TYPE=Release
$ cmake --build build
$ sudo make -C build install

Install openni2 (https://github.com/totakke/homebrew-openni2) and manually create a pkg-config file for libopenni2:

$ brew install openni2
$ vim /usr/local/lib/pkgconfig/libopenni2.pc
prefix=/usr/local
exec_prefix=${prefix}
libdir=${exec_prefix}/lib/ni2
includedir=${prefix}/include/ni2

Name: OpenNI2
Description: A general purpose driver for all OpenNI cameras.
Version: 2.2.0.0
Cflags: -I${includedir}
Libs: -L${libdir} -lOpenNI2 -L${libdir}/OpenNI2/Drivers -lOniFile -lPS1080

Build and install my fork of gst-plugins-bad from source. Ensure that the openni2 plugin builds! If it doesn't, ensure pkg-config --debug libopenni2 returns something sane.

$ git clone https://github.com/jshrake/gst-plugins-bad
$ cd gst-plugins-bad
$ git checkout grimoire-1.14.1
$ ./configure
$ make
$ sudo make install

Run the example:

$ LIBFREENECT2_PIPELINE=cl cargo run -- examples/openni2.glsl

If the cl libfreenect2 pipeline doesn't work, try cpu or cuda. grimoire is currently not compatible with the default gl pipeline.

Where can I find images for cube maps?

http://www.custommapmakers.org/skyboxes.php contains many high resolution skyboxes

Where can I find volumetric data?

You can download datasets from http://schorsch.efi.fh-nuernberg.de/data/volume/. At this time, grimoire does not support loading in the pvm file format. Instead, users will need to download https://sourceforge.net/projects/volren/, build the source, and run a tool that converts the pvm data into a raw format. I was able to successfully build the project and run the tool as follows on MacOS:

$ wget https://downloads.sourceforge.net/project/volren/VIEWER-5.2.zip
$ unzip VIEWER-5.2.zip
$ cd viewer
$ cmake -H. -Bbuild -DCMAKE_BUILD_TYPE=Release
$ cmake --build build
$ wget http://schorsch.efi.fh-nuernberg.de/data/volume/Foot.pvm
$ ./build/tools/pvm2raw Foot.pvm Foot.raw
reading PVM file
found volume with width=256 height=256 depth=256 components=1
and data checksum=4FAD56F0

Take note of width, height, depth, and components values, as you'll need to specify these in the resource configuration.