Playback & exporting with the VolSnap Application

VolSnap is a mixed mode (GUI & CLI) application that can play recording files and export them. Using the GUI mode is mostly used for visualizing the captured data, seeing the files’ metadata, and saving distinct frames of color, depth and pointcloud data. On the other hand, the CLI mode is used for batch exporting purposes, essentially dumping the whole sequence in various formats.

Graphical User Interface (GUI) Mode

VolSnap can be run in GUI mode to playback and inspect recorded files. After starting the application its main window opens, prompting the user to drag and drop files, resulting in a window like this.

Hereafter we break down and analyze the functionalities of each widget.

Files’ playback and saving options are possible through the Control_Panel widget, which is located at the bottom of the VolSnap window.

Functionalities:

Starts streams playback.
Stops streams playback.
Pauses streams playback.
Next/previous frame buttons.
Frames dumping options, which expands as:
- with the user able to select which data to export to the disk:
  - color,
  - depth,
  - pointclouds,
  - colored pointclouds,
  as well as the exporting sampling period (i.e. save every T frames). Calibrated pointclouds option applies the calibration transformation to the saved pointclouds and should be used only if the streams were calibrated prior to recording see Calibration.
  Please note that the destination of the exported files is the source directory of the input files when using the GUI mode.
Rotates all streams 90 degrees counter-clockwise for visualization purposes.
Undistorts the `color` and `depth` streams, **if** distortion coefficients are present in files. Highly recommended for Kinect 4 Azure devices, which have very wide lenses.
Display basic stream info:

The Synchronization Widget is responsible for the temporal grouping of the recorded frames. The operation starts when the button is pressed. ATTENTION: APPLICATION MAY SEEM TO NOT RESPOND, DO NOT TERMINATE IT, IT IS OPERATING.

There are 2 synchronization policies implemented and presented below.

Global Synchronization

Global synchronization is the by-default operation mode of the synchronization module. It groups frames so that the minimum and the maximum timestamp difference in a group is not bigger than .

FPS Synchronization

FPS synchronization makes a group of frames that have the smallest deviation in terms of timestamps and subsequentially greedily groups all next frames taking into account frame drops (if no streams dropped frames, group all next frames).

Frame loss is based on the normal frame rate conditioned by the parameter which is the nominal fps of the recording.

Once synchronization is complete, a new option is made availabe , that toggles synchronized playback. Additionally, a qualitative result of the synchronization result is presented:

which shows every frame’s timestamps for each stream, distincted by color, as dots. The more collinear are the dots in the vertical axis, the more precise is the synchronization.

Command Line Interface (CLI) Mode

When dealing with multiple recordings, or batched operations are required, CLI mode should be used.

Multiview player. Manage your .cdv files easily.
Usage: volsnap.exe [OPTIONS]

Options:
  -h,--help                                                   Print this help message and exit
  -g,--gui                                                    Flag for GUI mode.
  -f,--files TEXT ...                                         Input recordings.
  -o,--output TEXT                                            Output path.
  --force_creation Requires: -o,--output Excludes: -g,--gui   Force output path creation.
  --fps_sync Excludes: -g,--gui                               Use fps to compute synchronization threshold.
  --fps INT Excludes: -g,--gui                                Nominal FPS of the recordings files (default: 30)
  --threshold INT Excludes: -g,--gui                          Temporal offset that used for grouping frames. (default: 16 ms)
  --depth Excludes: -g,--gui                                  Toggle depth dumping.
  --color Excludes: -g,--gui                                  Toggle color dumping.
  --pcloud Excludes: -g,--gui                                 Toggle pointcloud dumping.
  --color_pcloud Excludes: -g,--gui                           Toggle colored point cloud dumping.
  --is_pcloud_calibrated Excludes: -g,--gui                   Dump spatially aligned point clouds (implies calibrated recordings).
  --show_progress Excludes: -g,--gui                          Toggle exporting progress bar.
  --undistort Excludes: -g,--gui                              Toggle undistortion of both color and depth data.
  --synchronize Excludes: -g,--gui                            Toggle dumping of sychronized data.
  --sample_freq INT Excludes: -g,--gui                        Exporting frequency, i.e. save every "sample_freq" frames. (default: 1)

As with GUI mode, CLI mode has the same functionality from the commandline with arguments described above.

Example

volsnap.exe ^
--files ^
RecordingsPath\KA03.cdv ^
RecordingsPath\KA04.cdv ^
RecordingsPath\KA05.cdv ^
RecordingsPath\KA06.cdv ^
RecordingsPath\KAX1.cdv ^
RecordingsPath\KAX2.cdv ^
--force_creation ^
--output ^
OutputPath ^
--depth --color --pcloud --color_pcloud --is_pcloud_calibrated ^
--undistort --sample_freq 60 --show_progress --synchronize

The above snippet with imports files specified by the --files arguments, --synchronizes the frames into groups and samples every --sample_freq (60) groups in order to --undistort frames, and save --depth --color and calibrated (--is_pcloud_calibrated) --pcloud --color_pcloud into the --output directory with is created --force_creation. Finally it also shows the progress of the exporting operation (--show_progress).