ReconstructMe SDK Documentation

Introduction

The ReconstructMe SDK provides methods and types to control the real-time 3D reconstruction process. ReconstructMe SDK targets simple applications as well as multi-sensor reconstruction processes.

Design Goals

These are the design goals we set for ReconstructMe SDK

• easy-to-use A generic and consistent SDK allows you grasp the concepts quickly and develop your first reconstruction application within minutes.
• easy-to-integrate The SDK has pure C-based API without additional compile time dependencies. Interopability with other languages is easly possible.
• high-performance The SDK is designed to provide a maximum performance for a smooth reconstruction experience.

Design Overview

The Context interface provides object life-time management and communication with a computation device (GPU, CPU). Every program needs at least one instance of it. The Sensor interface provides access to 3d image data of the real world. This data is fed into a Volume where the actual reconstruction happens. The Surface interface allows the extraction of 3D triangle meshes from the volume. Each object offers a set of specific options, which can be controlled using the Options interface.

ReconstructMe SDK comes with inline visualization utilities available via the Viewing interface. Additionally, the Recorder interface provides methods to stream Sensor data to disk. The streamed data can later be replayed using a file sensor.

Commerical license authentication is provided through the License functionality.

Example

Here is an introductary example on how to use ReconstructMe SDK. First, include the necessary headers

#include <reconstructmesdk/reme.h>

Next, use its functionality

  // Create a new context
  reme_context_t c;
  reme_context_create(&c);

  // Compile for OpenCL device using defaults
  reme_context_compile(c);
  
  // Create a new volume
  reme_volume_t v;
  reme_volume_create(c, &v);
  
  // Create a new sensor. Tries multiple backends using default
  // sensor configurations, returns the first working one. By default 
  // each sensor works on the first volume created.
  reme_sensor_t s;
  reme_sensor_create(c, "openni;mskinect;file", true, &s);
  reme_sensor_open(c, s);

  // For debugging purposes open a viewer for tracking the reconstruction process.
  // This will create a two-sided viewer showing the video stream and the current
  // reconstruction from the sensor point of view.
  reme_viewer_t viewer;
  reme_viewer_create_image(c, "This is ReconstructMe SDK", &viewer);
  reme_viewer_add_image(c, viewer, s, REME_IMAGE_DEPTH);
  reme_viewer_add_image(c, viewer, s, REME_IMAGE_VOLUME);

  // Perform reconstruction until no more frames are left
  int time = 0;
  while (time < 200 && REME_SUCCESS(reme_sensor_grab(c, s))) {

    // Prepare image and depth data
    reme_sensor_prepare_images(c, s);

    // Try to determine updated sensor position.
    // On succes, update volume, otherwise move to a recovery position
    // and wait for the tracking to start again.
    if (REME_SUCCESS(reme_sensor_track_position(c, s))) {
      
      // Update volume with depth data from the 
      // current sensor perspective
      reme_sensor_update_volume(c, s);

    }

    // Update the viewer
    reme_viewer_update(c, viewer);
    time += 1;
  }

  // Close and destroy the sensor, it is not needed anymore
  reme_sensor_close(c, s);
  reme_sensor_destroy(c, &s);

  // Create a new surface
  reme_surface_t m;
  reme_surface_create(c, &m);
  reme_surface_generate(c, m, v);
  reme_surface_save_to_file(c, m, "test.ply");
  
  // Visualize resulting surface
  reme_viewer_t viewer_surface;
  reme_viewer_create_surface(c, m, "This is ReconstructMeSDK", &viewer_surface);
  reme_viewer_wait(c, viewer_surface);

  reme_surface_destroy(c, &m);

  // Make sure to release all memory acquired
  reme_context_destroy(&c);

More examples can be found at the examples page.

Compiling and Linking

C/C++ Projects

The ReconstructMe SDK installer set the environment variable REME_ROOT_DIRECTORY to point to the main SDK directory. In order to compile successfully, you need to add

%REME_ROOT_DIRECTORY%/inc 

to the compiler's include directories. Next, for the linking step you need to tell the linker to link against

%REME_ROOT_DIRECTORY%/lib/LibReconstructMeSDK.lib 

in all configuration modes (debug, release). For the execution step you need to copy the content of

%REME_ROOT_DIRECTORY%/bin/ 

to your application's start directory (i.e the directory where your .exe is located). In case you allowed the installer to modify your PATH environment variable, you can skip this step, as windows will find the required dynamic link libraries in the installation path. Remember though, that you copy the files locally when redistributing your application.

CMake

For CMake users we ship package configuration files in

%REME_ROOT_DIRECTORY%/cmake 

A sample application using it can be found in

%REME_ROOT_DIRECTORY%/cmake/CMakeLists.txt 

The content of this file is shown here for convenience.

#
# Example CMakeLists.txt showing how to use
# ReconstructMe SDK with CMake.
#
# ReconstructMe SDK provides the required package
# configuration files in its cmake subdirectory. The
# installer adds a ReconstructMeSDK_DIR environment
# variable which is used by CMake find_package command
# to find the package.
#
# Christoph Heindl, PROFACTOR GmbH, 2012
#

cmake_minimum_required(VERSION 2.8)

# Find the ReconstructMe SDK
find_package(ReconstructMeSDK)

# Add necessary ReconstructMe SDK include directories
include_directories(${RECONSTRUCTMESDK_INCLUDE_DIRS})

# Create a sample application
add_executable(ReconstructMeDemo main.cpp)

# Make sure to link against the required libraries
target_link_libraries(ReconstructMeDemo ${RECONSTRUCTMESDK_LIBRARIES})

Memory Management Rules

The lifetime of pointers provided by the ReconstructMe SDK or to the ReconstructMe SDK is subject to the following rules

• in-parameters must be allocated and freed by the caller.
• out-parameters must not be freed by the caller. Unless otherwise stated the life-time of an out-parameter ends when a new ReconstructMe SDK function is called.

Thread Safety

In general each instance of a reme_context_t object has to be called by a single thread.

Support

Besides this documentation we have openend up a developer forum to discuss SDK relevant topics. Join the discussion at

https://groups.google.com/forum/#!forum/reconstructmesdk

Version

This documentation is generated for ReconstructMe SDK 1.0.726-75385.