Calibration

Provides intrinsic camera calibration. More...

Typedefs
typedef int	reme_calibrator_t
	Handle referencing a calibrator. More...
reme_error_t	reme_calibrator_create (reme_context_t c, reme_calibrator_t *cb)
	Create a new calibration object. More...
reme_error_t	reme_calibrator_destroy (reme_context_t c, reme_calibrator_t *cb)
	Destroy a previously created calibrator object. More...
reme_error_t	reme_calibrator_bind_options (reme_context_t c, reme_calibrator_t cb, reme_options_t o)
	Access the calibration options. More...
reme_error_t	reme_calibrator_add_image (reme_context_t c, reme_calibrator_t cb, reme_image_t i)
	Add a new image of the calibration target. More...
reme_error_t	reme_calibrator_get_detection_image (reme_context_t c, reme_calibrator_t cb, reme_image_t i)
	Receives the result image of the last image added. More...
reme_error_t	reme_calibrator_calibrate (reme_context_t c, reme_calibrator_t cb, float *reprojection_error=0)
	Calibrate using the images added before. More...
reme_error_t	reme_calibrator_bind_intrinsics (reme_context_t c, reme_calibrator_t cb, reme_options_t o)
	Access the calibration results. More...

Detailed Description

Provides intrinsic camera calibration.

This modules provides methods to estimate the intrinsic sensor parameters. The basic workflow to calibrate your sensor and use the estimate values to correct distortion is

• Estimate Parameters
  • Create a new reme_calibrator_t (reme_calibrator_create).
  • Modify its settings to reflect your calibration target dimensions (reme_calibrator_bind_options).
  • Use the calibrator object to process images of the calibration target (reme_calibrator_add_image). These images should either come from a real-world Sensor or loaded from disk using Image interface. When run using a real-world sensor, you should use a valid commercial license, because otherwise the text overlay limits the accuracy of the chessboard detection achieved.
  • Estimate intrinsic camera parameters based on images added (reme_calibrator_calibrate).
  • Access calibration results (reme_calibrator_bind_intrinsics) and create a new sensor configuration file.
• Use estimated Parameters
  • Open sensor with previously calculated intrinsics.

Note that various sensors support different video streams (depth, color, ir). The calibration module performs an intrinsic calibration of one of them. Since release 2.0 by default the alignment of depth and color streams is set to true. This means, that when you want to calibrate the depth, you should actually calibrate color as all depth values will be mapped internally to this video-stream.

The example below illustrates calibrating a real-world sensor

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

    // Create a license object
    reme_license_t l;
    reme_license_create(c, &l);
    reme_error_t e = reme_license_authenticate(c, l, "license.txt.sgn");

    if (e == REME_ERROR_SUCCESS) {
        puts("Now running in commercial mode");
    } else {
        puts("Failed to authenticate.");
    }

    // Create a new sensor with default intrinsics
    reme_sensor_t s;
    reme_sensor_create(c, "openni", false, &s);

    // Use the RGB stream as AUX image type

    reme_options_t o_cfg;
    reme_options_create(c, &o_cfg);
    reme_sensor_bind_camera_options(c, s, o_cfg);

    // Switch IR stream on.
    reme_options_set(c, o_cfg, "aux_stream.type", "STREAM_COLOR");

    // Open sensor
    reme_sensor_open(c, s);

    // Create a calibrator using standard settings (A3 chessboard 10x7)
    reme_calibrator_t calib;
    reme_calibrator_create(c, &calib);

    // We visualize two images, the auxilary image and the last detection result
    reme_viewer_t viewer;
    reme_viewer_create_image(c, "This is ReconstructMeSDK", &viewer);

    reme_image_t imgs[2];
    reme_image_create(c, &imgs[0]);
    reme_image_create(c, &imgs[1]);

    reme_viewer_add_image(c, viewer, imgs[0]);
    reme_viewer_add_image(c, viewer, imgs[1]);

    bool continue_grabbing = true;

    while (continue_grabbing && REME_SUCCESS(reme_sensor_grab(c, s))) {
        // Prepare image and update content
        reme_sensor_prepare_image(c, s, REME_IMAGE_AUX);
        reme_sensor_get_image(c, s, REME_IMAGE_AUX, imgs[0]);

        // Keyboard handling
        if (_kbhit()) {
            char k = _getch();
            switch (k) {

            // Key 's' tries to find the calibration target in the current image
            case 's': {
                reme_calibrator_add_image(c, calib, imgs[0]);
                reme_calibrator_get_detection_image(c, calib, imgs[1]);
                break;
            }

            // Key 'c' saves the volume content to disk
            case 'c' : {
                continue_grabbing = false;
                break;
            }

            }
        }

        // Update the viewer
        reme_viewer_update(c, viewer);

    } // end of grabbing loop

    // Actual calibration step

    float accuracy;
    if (REME_SUCCESS(reme_calibrator_calibrate(c, calib, &accuracy))) {
        printf("Reprojection error: %f pixels \n", accuracy);

        // Generate a new sensor config using the new intrinsic values
        reme_options_t o, o_intr, o_intr_new;

        reme_options_create(c, &o);
        reme_options_create(c, &o_intr);
        reme_options_create(c, &o_intr_new);

        // Get the current camera configuration
        reme_sensor_bind_camera_options(c, s, o);
        reme_options_bind_message(c, o, "aux_stream.intrinsics", o_intr);

        // Get the result of the calibration
        reme_calibrator_bind_intrinsics(c, calib, o_intr_new);

        // Copy over
        reme_options_copy(c, o_intr_new, o_intr);

        // Save new config to file
        reme_options_save_to_file(c, o, "calibrated_sensor.txt");
    } else {
        puts("Calibration failed");
    }

Typedef Documentation

reme_calibrator_t

typedef int reme_calibrator_t

Handle referencing a calibrator.

Calibration determines a sensors' intrinsic parameters. Besides the focal length and principal point, also the radial and tangential distortion parameters are calculated. For this to work one has to specify a set of images of a known calibration target. Currently the common chessboard target is supported.

Function Documentation

reme_calibrator_create()

reme_error_t reme_calibrator_create	(	reme_context_t	c,
		reme_calibrator_t *	cb
	)

Create a new calibration object.

Parameters

c	A valid context object
cb	A pointer that will receive the handle of the created calibration object

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_calibration.cpp.

reme_calibrator_destroy()

reme_error_t reme_calibrator_destroy	(	reme_context_t	c,
		reme_calibrator_t *	cb
	)

Destroy a previously created calibrator object.

Parameters

c	A pointer to a valid context object
cb	A mutable pointer to a valid calibrator handle to destroy

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

reme_calibrator_bind_options()

reme_error_t reme_calibrator_bind_options	(	reme_context_t	c,
		reme_calibrator_t	cb,
		reme_options_t	o
	)

Access the calibration options.

Associated Protocol Buffers Specification

// Calibration options for chessboards
message calibration_options {
  // Number of inner corners in the width direction
  optional int32 inner_count_width = 1 [default = 10];
  // Number of inner corners in the height direction
  optional int32 inner_count_height = 2 [default = 7];
  // Length of a single square side. Defaults are are in mm for default A3 checkerboard.
  optional float length_square_side = 3 [default = 33.876];
  // Number of pixels to use when refining corners in the width direction
  optional int32 refine_width = 4 [default = 5];
  // Number of pixels to use when refining corners in the height direction
  optional int32 refine_height = 5 [default = 5];
  // Assume no tangential distortions
  optional bool zero_tangential = 6 [default = true];
  // Assume no lower order radial distortions
  optional bool zero_radial_k1k2 = 7 [default = true];
  // Assume no higher order radial distortions
  optional bool zero_radial_k3 = 8 [default = true];
}

The calibration options are applied when the first image is added (reme_calibrator_add_image).

Parameters

c	A valid context object
cb	A valid calibration object
o	A valid options binding object

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

reme_calibrator_add_image()

reme_error_t reme_calibrator_add_image	(	reme_context_t	c,
		reme_calibrator_t	cb,
		reme_image_t	i
	)

Add a new image of the calibration target.

To receive the best results

• Make sure the calibration target covers most of the image.
• Make sure to supply images taken from different angles.
• Supply between 10 - 20 images.

Parameters

c	A valid context object
cb	A valid calibration object
i	A valid image object

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_NO_CALIBRATION_TARGET	When the calibration target was not found in the image supplied.
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_calibration.cpp.

reme_calibrator_get_detection_image()

reme_error_t reme_calibrator_get_detection_image	(	reme_context_t	c,
		reme_calibrator_t	cb,
		reme_image_t	i
	)

Receives the result image of the last image added.

Parameters

c	A valid context object
cb	A valid calibration object
i	A valid image object

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_calibration.cpp.

reme_calibrator_calibrate()

reme_error_t reme_calibrator_calibrate	(	reme_context_t	c,
		reme_calibrator_t	cb,
		float *	reprojection_error = 0
	)

Calibrate using the images added before.

The result of a successful calibration is are new intrinsic settings. Use

Parameters

c	A valid context object
cb	A valid calibration object
reprojection_error	If not null, the reprojection error of the calibration.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_calibration.cpp.

reme_calibrator_bind_intrinsics()

reme_error_t reme_calibrator_bind_intrinsics	(	reme_context_t	c,
		reme_calibrator_t	cb,
		reme_options_t	o
	)

Access the calibration results.

The results are provided as a new intrincis options set.

Associated Protocol Buffers Specification

package LibRGBDSensor;

// Camera intrinsics
message intrinsics {

  // Image size this intrinsics applies to.
  optional int32 width = 1 [default = 640];
  optional int32 height = 2 [default = 480];

  // Camera matrix
  optional double fx = 3 [default = 571.26];
  optional double fy = 4 [default = 571.26];
  optional double cx = 5 [default = 320];
  optional double cy = 6 [default = 240];
  
  // Radial distortion coefficients
  // Set to zero to disable certain calculations
  optional double k1 = 7 [default = 0];
  optional double k2 = 8 [default = 0];
  optional double k3 = 9 [default = 0];
  
  // Tangential distortion coefficients
  // Set to zero to disable certain calculations
  optional double p1 = 10 [default = 0];
  optional double p2 = 11 [default = 0];
  
}

Parameters

c	A valid context object
cb	A valid calibration object
o	A valid options binding object

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_calibration.cpp.