Add replay API example (SpectacularAI#37)

Author: pekkaran

cpp/offline/README.md

@@ -1,8 +1,8 @@
-# SpectacularAI offline example
+# Spectacular AI main API example
 
-This example shows how to run basic stereo VIO using offline data.
+This example shows how to run basic stereo VIO using offline data to mimic real-time use case. Functions in the main header `spectacularAI/vio.hpp` are used primarily.
 
-* Supported platform: Linux
+* Tested platforms: Linux
 * Dependencies: CMake, FFmpeg (for video input)
 
 ## Setup
@@ -70,4 +70,5 @@ For the included libraries, see
 * [lodepng](https://lodev.org/lodepng/): `lodepng/LICENSE`
 
 For access to the C++ SDK, contact us at <https://www.spectacularai.com/#contact>.
+
 Available for multiple OSes and CPU architectures.

cpp/replay/CMakeLists.txt

@@ -0,0 +1,10 @@
+cmake_minimum_required(VERSION 3.3)
+
+project(spectacularAI_replay_example)
+
+add_executable(replay replay.cpp)
+
+find_package(spectacularAI REQUIRED)
+
+target_link_libraries(replay PRIVATE spectacularAI::spectacularAI)
+target_include_directories(replay PRIVATE ".")

cpp/replay/README.md

@@ -0,0 +1,61 @@
+# Spectacular AI Replay API example
+
+This example shows how to replay recordings created using Spectacular AI SDK. The header `spectacularAI/replay.hpp` is primarily used.
+
+* Tested platforms: Linux
+* Dependencies: CMake, FFmpeg (for video input)
+
+## Setup
+
+* Install the Spectacular AI SDK
+* Build this example using CMake:
+
+```
+mkdir target
+cd target
+cmake -DspectacularAI_DIR=<path/to/spectacularai-sdk/lib/cmake/spectacularAI> ..
+make
+```
+
+The `-DspectacularAI_DIR` option is not needed is you have used `sudo make install` for the SDK.
+
+## Usage
+
+In the target folder, run `./replay -i path/to/data -o out.jsonl`, where
+
+* `-i` specifies the input folder, see details below.
+* `-o` specifies output JSONL file.
+
+See the source code for more options. Input data is read from a given folder with the following hierarchy:
+
+```
+├── calibration.json
+├── vio_config.yaml
+├── data.jsonl
+├── data.mp4
+└── data2.mp4
+```
+
+when using video files. And if instead using PNG images:
+
+```
+├── calibration.json
+├── vio_config.yaml
+├── data.jsonl
+├── frames1
+│   ├── 00000000.png
+│   ├── 00000001.png
+│   ├── ...
+│   └── 00000600.png
+└── frames2
+    ├── 00000000.png
+    ├── 00000001.png
+    ├── ...
+    └── 00000600.png
+```
+
+## Copyright
+
+For access to the C++ SDK, contact us at <https://www.spectacularai.com/#contact>.
+
+Available for multiple OSes and CPU architectures.

cpp/replay/replay.cpp

@@ -0,0 +1,84 @@
+#include <cassert>
+#include <chrono>
+#include <fstream>
+#include <iostream>
+#include <memory>
+#include <sstream>
+
+#include <spectacularAI/vio.hpp>
+#include <spectacularAI/replay.hpp>
+
+const std::string SEPARATOR = "/";
+
+std::string readFileToString(const std::string &filename) {
+    std::ifstream f(filename);
+    std::ostringstream oss;
+    oss << f.rdbuf();
+    return oss.str();
+}
+
+bool fileExists(const std::string &filePath) {
+    std::ifstream dataFile(filePath);
+    return dataFile.is_open();
+}
+
+int main(int argc, char *argv[]) {
+    std::vector<std::string> arguments(argv, argv + argc);
+    std::unique_ptr<std::ofstream> outputFile;
+    std::string inputFolder;
+    std::string userConfigurationYaml;
+    bool realtime = false;
+    bool print = false;
+    for (size_t i = 1; i < arguments.size(); ++i) {
+        const std::string &argument = arguments.at(i);
+        if (argument == "-o") {
+            outputFile = std::make_unique<std::ofstream>(arguments.at(++i));
+            assert(outputFile->is_open());
+        }
+        else if (argument == "-i") inputFolder = arguments.at(++i);
+        else if (argument == "-c") userConfigurationYaml = readFileToString(arguments.at(++i));
+        else if (argument == "--realtime") realtime = true;
+        else if (argument == "--print") print = true;
+    }
+    if (inputFolder.empty()) {
+        std::cout << "Please specify input directory using `-i`."<< std::endl;
+        return 0;
+    }
+
+    std::ostringstream configurationYaml;
+    std::string dataConfigurationYamlPath = inputFolder + SEPARATOR + "vio_config.yaml";
+    if (fileExists(dataConfigurationYamlPath)) {
+        // Vio::Builder::setConfigurationYAML overwrites the configuration in the data
+        // directory, but in most cases that configuration is needed for the best VIO
+        // performance, so we concatenate our changes to it.
+        configurationYaml << readFileToString(dataConfigurationYamlPath) << std::endl;
+    }
+    // The `processingQueueSize` option makes the data input wait for VIO to finish to
+    // avoid dropping frames. It should not be used in real-time scenarios.
+    configurationYaml << "processingQueueSize: 0\n";
+    configurationYaml << userConfigurationYaml;
+
+    // The Replay API builder takes as input the main API builder as a way to share
+    // configuration methods.
+    spectacularAI::Vio::Builder vioBuilder = spectacularAI::Vio::builder()
+        .setConfigurationYAML(configurationYaml.str());
+
+    std::unique_ptr<spectacularAI::Replay> replay
+        = spectacularAI::Replay::builder(inputFolder, vioBuilder).build();
+    replay->setPlaybackSpeed(realtime ? 1.0 : -1.0);
+
+    replay->setOutputCallback([&](spectacularAI::VioOutputPtr vioOutput) {
+        if (outputFile) *outputFile << vioOutput->asJson().c_str() << std::endl;
+        if (print) std::cout << vioOutput->asJson().c_str() << std::endl;
+    });
+
+    const auto t0 = std::chrono::steady_clock::now();
+
+    replay->runReplay();
+
+    const auto time = std::chrono::duration<double, std::milli>(
+        std::chrono::steady_clock::now() - t0).count();
+    printf("Replay took %.2fs\n", 1e-3 * time);
+
+    return 0;
+}