Calibration

Provides intrinsic camera calibration. More...

Typedefs
typedef int	reme_calibrator_t
	Handle referencing a calibrator.
reme_error_t	reme_calibrator_create (reme_context_t c, reme_calibrator_t *cb)
	Create a new calibration object.
reme_error_t	reme_calibrator_destroy (reme_context_t c, reme_calibrator_t *cb)
	Destroy a previously created calibrator object.
reme_error_t	reme_calibrator_bind_options (reme_context_t c, reme_calibrator_t cb, reme_options_t o)
	Access the calibration options.
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.
reme_error_t	reme_calibrator_update_detection_image (reme_context_t c, reme_calibrator_t cb, reme_image_t i)
	Receives the result image of the last image added.
reme_error_t	reme_calibrator_calibrate (reme_context_t c, reme_calibrator_t cb, float *reprojection_error=0)
	Calibrate using the images added before.
reme_error_t	reme_calibrator_bind_intrinsics (reme_context_t c, reme_calibrator_t cb, reme_options_t o)
	Access the calibration results.

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
  • Enable enable_distortion_correction (reme_context_bind_compile_options) in case you intend to use radial and tangential distortion terms.
  • Open sensor with previously calculated intrinsics.

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_license_authenticate(c, l, "license.txt.sgn");

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

  // We by either enabling IR stream or RGB (default) for REME_IMAGE_AUX we
  // can choose the camera to calibrate.

  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, "enable_rgb", "false");
  reme_options_set(c, o_cfg, "enable_ir", "true");
  reme_options_set(c, o_cfg, "enable_ir_projector", "false");
  // Increase contrast of the image. We've found that good values are 
  //  - Kinect for Windows: around 40 with projector turned off
  //  - Kinect for XBox, Xtion: around 4 with projector covered
  reme_options_set(c, o_cfg, "ir_alpha", "40");

  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_update_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_update_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, "depth_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);

    // Reset the flags we pulled in before
    reme_options_set(c, o_cfg, "enable_rgb", "true");
    reme_options_set(c, o_cfg, "enable_ir", "false");
    reme_options_set(c, o_cfg, "enable_ir_projector", "true");

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

Typedef Documentation

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_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_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_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 = false];
  // Set k3 to zero. This is recommended except for fisheye lenses
  optional bool zero_k3 = 7 [default = true];
}

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_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_error_t reme_calibrator_update_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_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_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 {

  // Camera matrix
  optional double fx = 1 [default = 571.26];
  optional double fy = 2 [default = 571.26];
  optional double cx = 3 [default = 320];
  optional double cy = 4 [default = 240];
  
  // Radial distortion coefficients
  // Set to zero to disable certain calculations
  optional double k1 = 5 [default = 0];
  optional double k2 = 6 [default = 0];
  optional double k3 = 7 [default = 0];
  
  // Tangential distortion coefficients
  // Set to zero to disable certain calculations
  optional double p1 = 8 [default = 0];
  optional double p2 = 9 [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.