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

You will also need a RGB-D sensor to perform real-time reconstruction. We've assembled a list of supported sensors plus reviews for your convenience.

ReconstructMe currently runs on Windows Vista/7/8/10 64bit operating systems. ReconstructMe SDK is compiled against Visual Studio 10 and targets 64bit mode. Since ReconstructMe SDK is plain C, integration into other versions of Visual Studio or languages is easily possible.

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

Architecture x64

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

%REMEx64_ROOT_DIRECTORY%/inc 

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

$(REMEx64_ROOT_DIRECTORY)/inc 

This will allow the Intellisense of Visual Studio to work properly. The REMEx64_ROOT_DIRECTORY environment variable is set by the ReconstructMe x64 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

%REMEx64_ROOT_DIRECTORY%/lib/LibReconstructMeSDK.lib 

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

%REMEx64_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

Architecture x64

For CMake users we ship package configuration files in

%REMEx64_ROOT_DIRECTORY%/cmake 

A sample application using it can be found in

%REMEx64_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, 2014
#

cmake_minimum_required(VERSION 2.8)

# Find the ReconstructMe SDK
if (${CMAKE_CL_64})
    find_package(ReconstructMeSDKx64)
else ()
    find_package(ReconstructMeSDK)
endif ()

# 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);
    reme_context_set_log_callback(c, reme_default_log_callback, 0);

    // 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, "librealsense", 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);

    // Reconstruct until viewer is closed, or grabbing fails. Note that
    // aborting reconstruction just because a single grab failed is not good stlye.
    // You should allow for multiple grab attempts.
    printf("Starting reconstruction. Close the viewer window to stop.\n");
    bool viewer_done = false;
    while (!viewer_done && 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);
        reme_viewer_is_closed(c, viewer, &viewer_done);
    }

    // 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);

    // 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.