Getting Started

Your very first steps with ReconstructMe SDK

This page familiarizes you with the structure of the API. First, we lay down the system requirements. Next, we skim over the basic interfaces provided by the API and explain what their purpose is and how they interact with each other. We will then move on to setting up a new C/C++ project and finally implement our first 3D real-time reconstruction example.

System Requirements

ReconstructMe requires specific hardware to provide real-time reconstruction experience. It makes heavy use of the computational power of modern graphic cards. In order to experience real-time reconstruction, we recommend a decent graphics card, both AMD and NVIDIA will work. We don't make any specific recommendations, but the graphic cards we are currently developing on are

• AMD Radeon HD 6850
• NVIDIA GeForce GTX 560

Additionally we have created a device compatibility matrix that you might find helpful. It contains user-experience reports.

You will also need a RGB-D sensor to perform real-time reconstruction. The following sensors are supported

• PrimeSense Carmine 1.08, Carmine 1.09, Capri
• Microsoft Kinect for Windows
• Microsoft Kinect for XBox
• Asus Xtion Pro Live (RGB and Depth)
• Asus Xtion Pro (Depth only)

ReconstructMe currently runs on Windows Vista/7/8 32bit and 64bit operating systems. ReconstructMe SDK is compiled against Visual Studio 10 and targets 32bit mode.

Note that ReconstructMe uses OpenCL. We recommend that you update your display and/or CPU drivers to the latest version: Here are links to NVIDIA, AMD and INTEL.

Interface Overview

The Context interface provides object life-time management and maintains the communication with a computation device (GPU, CPU). Every program needs at least one instance of it. The Sensor interface provides access to 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 reconstruction volume.

By default all interfaces created come with sensible default values. To adjust or access those settings, you can use the generic Options interface, which can be bound to any parameter set through so called binder-methods. All available binders are listed on the Options Bindings page.

ReconstructMe API comes with inline visualization utilities available via the Viewing interface. These utilities are meant for debugging purposes and not for a production ready applications, since their implementation is layed out for general purpose, not performance.

For testing purposes ReconstructMe API a Recorder interface to stream Sensor to disk. This data can later be replayed using a special file sensor from the Sensor.

To improve the accuracy of your sensor, ReconstructMe API provides you with the Calibration interface. It allows you to estimate the intrinsic camera parameters (such as focal length, principal point and distortions). These parameters can later be used for reconstruction to compensate errors.

When running ReconstructMe SDK in commercial mode, you need to authenticate using License functionality.

Compiling and Linking

In order to use ReconstructMe API successfully from within your project, add the following line to the compiler's include directories

%REME_ROOT_DIRECTORY%/inc 

In case you are using Visual Studio, you might want to modify the above line to

$(REME_ROOT_DIRECTORY)/inc 

This will allow the Intellisense of Visual Studio to work properly. The REME_ROOT_DIRECTORY environment variable is set by the ReconstructMe SDK installer to point to the root directory of the last installed version.

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, to copy the files locally when redistributing your application.

Compiling and Linking using 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})

One-Minute Example

Now that your project is setup we can move on to your first example application. The example shows how to perform real-time reconstruction using a single sensor. Besides, built-in real-time visualization and surface visualization is used. The final mesh is saved in PLY format. This example omits error handling for clarity purposes. See Error Handling for a catch up on this.

First, include the necessary headers

#include <reconstructmesdk/reme.h>

Inside your main method add the following code

  // 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);
  reme_sensor_set_prescan_position(c, s, REME_SENSOR_POSITION_INFRONT);

  // For debugging purposes open a viewer for tracking the reconstruction process.
  reme_viewer_t viewer;
  reme_viewer_create_image(c, "This is ReconstructMe SDK", &viewer);

  reme_image_t volume, aux;
  reme_image_create(c, &volume);
  reme_image_create(c, &aux);

  reme_viewer_add_image(c, viewer, aux);
  reme_viewer_add_image(c, viewer, 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_sensor_get_image(c, s, REME_IMAGE_AUX, aux);
    reme_sensor_get_image(c, s, REME_IMAGE_VOLUME, volume);
    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);

  printf("Now generating the mesh.\n");
  printf("Note that this will take at least 20 seconds without a valid license.\n");  
  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);

  // Print pending errors
  reme_context_print_errors(c);

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

More examples can be found at the examples page.