ReconstructMe SDK  2.6.43-0
Real-time 3D reconstruction engine
Marker Detection

6DOF marker detection More...

reme_error_t reme_marker_detector_create (reme_context_t c, reme_sensor_t s, reme_marker_detector_t *md)
 Create a new marker detector. More...
 
reme_error_t reme_marker_detector_destroy (reme_context_t c, reme_marker_detector_t *md)
 Destroy a previously created marker detector object. More...
 
reme_error_t reme_marker_detector_bind_options (reme_context_t c, reme_marker_detector_t md, reme_options_t o)
 Access the marker detection options. More...
 
reme_error_t reme_marker_detector_apply_options (reme_context_t c, reme_marker_detector_t md, reme_options_t o)
 Apply marker detection options. More...
 
reme_error_t reme_marker_detector_find (reme_context_t c, reme_marker_detector_t md, int *nmarkers)
 Detect markers in sensor image. More...
 
reme_error_t reme_marker_detector_get_position (reme_context_t c, reme_marker_detector_t md, int index, float *coordinates)
 Get position of the i-th marker detected. More...
 
reme_error_t reme_marker_detector_get_class_id (reme_context_t c, reme_marker_detector_t md, int index, int *id)
 Get the class-id of the i-th marker detected. More...
 
reme_error_t reme_marker_detector_draw_info (reme_context_t c, reme_marker_detector_t md, int index, reme_image_t image)
 Draw marker info. More...
 
reme_error_t reme_marker_detector_generate_template_image (reme_context_t c, reme_marker_detector_t md, int marker_id, reme_image_t image)
 Get a marker template image that can be used for printing. More...
 

Detailed Description

6DOF marker detection

The Marker Detection module is able to detect planar fiducial markers in RGB/GRAY images of the sensor. A marker, like the one below, is a special planar object placed in the view of the camera that has a couple of unique features:

fiducial_marker.png
Fiducial Marker

Markers can be used in varios ways. For one they can be used to interactively position the reconstruction volume in the real world. See example_reconstructmesdk_marker.cpp

Besides a position (reme_marker_detector_get_position) each marker encodes a class-id. There are up to 1024 different markers and each marker carries its own class id (reme_marker_detector_get_class_id). The class id can be used to adapt program behaviour based on the marker shown. For metric pose estimation you need to set the correct printed size of the marker (reme_marker_detector_bind_options).

The canonical coordinate system of the marker is shown in the image below. When printed and laid on floor, positive z-axis points towards the ceiling, positive x-axis to the right and positive y-axis to the top of the marker. The origin of the coordinate system is in the center of the marker.

fiducial_marker_coordinate_system.png
Fiducial Marker Coordinate System

The fiducial markers supported are based on ARUCO style markers. Although we use the design of the ARUCO markers, our implementation deviates significantly from the proposed one.

Function Documentation

◆ reme_marker_detector_create()

reme_error_t reme_marker_detector_create ( reme_context_t  c,
reme_sensor_t  s,
reme_marker_detector_t md 
)

Create a new marker detector.

Parameters
cA valid context object
sA valid sensor object to work on
mdA pointer to receive the created marker detector object handle.
Return values
REME_ERROR_SUCCESSOn success
REME_ERROR_UNSPECIFIEDOn failure
Examples:
example_reconstructmesdk_marker.cpp.

◆ reme_marker_detector_destroy()

reme_error_t reme_marker_detector_destroy ( reme_context_t  c,
reme_marker_detector_t md 
)

Destroy a previously created marker detector object.

Parameters
cA pointer to a valid context object
mdA mutable pointer to a valid marker detector handle to destroy
Return values
REME_ERROR_SUCCESSOn success
REME_ERROR_UNSPECIFIEDOn failure

◆ reme_marker_detector_bind_options()

reme_error_t reme_marker_detector_bind_options ( reme_context_t  c,
reme_marker_detector_t  md,
reme_options_t  o 
)

Access the marker detection options.

Associated Protocol Buffers Specification
// Marker detection options
message marker_detection_options {
// Marker side length in world units
optional float marker_size = 1 [default = 90];
// If enabled the marker found in the AUX frame is mapped / corrected using depth information.
// Requires a AUX to depth mapping enabled at sensor level.
optional bool map_to_depth = 2 [default = true];
}

Use reme_marker_detector_apply_options to apply value changes.

Parameters
cA valid context object
mdA valid marker detector object
oA valid options binding object
Return values
REME_ERROR_SUCCESSOn success
REME_ERROR_UNSPECIFIEDOn failure
Examples:
example_reconstructmesdk_marker.cpp.

◆ reme_marker_detector_apply_options()

reme_error_t reme_marker_detector_apply_options ( reme_context_t  c,
reme_marker_detector_t  md,
reme_options_t  o 
)

Apply marker detection options.

Causes all marker detection options to be applied at marker detector.

Parameters
cA valid context object
mdA valid marker detector object
oA valid options binding object
Return values
REME_ERROR_SUCCESSOn success
REME_ERROR_UNSPECIFIEDOn failure
Examples:
example_reconstructmesdk_marker.cpp.

◆ reme_marker_detector_find()

reme_error_t reme_marker_detector_find ( reme_context_t  c,
reme_marker_detector_t  md,
int *  nmarkers 
)

Detect markers in sensor image.

Attempts to find markers in sensor image. First the aux image is used to estimate marker positions, then if applicable, the position is corrected using the depth image.

In order to detect markers successfully the entire marker needs to be visible in the image and no edges or borders should be covered.

Parameters
cA valid context object
mdA valid marker detector object
nmarkersNumber of markers found
Return values
REME_ERROR_SUCCESSOn success
REME_ERROR_UNSPECIFIEDOn failure
Examples:
example_reconstructmesdk_marker.cpp.

◆ reme_marker_detector_get_position()

reme_error_t reme_marker_detector_get_position ( reme_context_t  c,
reme_marker_detector_t  md,
int  index,
float *  coordinates 
)

Get position of the i-th marker detected.

The position returned is the marker pose with respect to the sensor coordinate frame. The canoncical marker coordinate system is constructed as follows:

  • origin is in the center of the marker
  • z-axis points upwards (i.e to the ceiling if laid on the floor)
  • x-axis orthogonal to z-axis and depends on the in-plane marker rotation
  • y-axis orthogonal to z-axis and depends on the in-plane marker rotation
Parameters
cA valid context object
mdA valid marker detector object
indexMarker index
coordinatesA constant pointer to constant Transform data.
Return values
REME_ERROR_SUCCESSOn success
REME_ERROR_UNSPECIFIEDOn failure
Examples:
example_reconstructmesdk_marker.cpp.

◆ reme_marker_detector_get_class_id()

reme_error_t reme_marker_detector_get_class_id ( reme_context_t  c,
reme_marker_detector_t  md,
int  index,
int *  id 
)

Get the class-id of the i-th marker detected.

The class-id corresponds is a number that is encoded in the inner square of the marker. It allows one to differentiate between varios markers.

Parameters
cA valid context object
mdA valid marker detector object
indexMarker index
idMarker class id
Return values
REME_ERROR_SUCCESSOn success
REME_ERROR_UNSPECIFIEDOn failure

◆ reme_marker_detector_draw_info()

reme_error_t reme_marker_detector_draw_info ( reme_context_t  c,
reme_marker_detector_t  md,
int  index,
reme_image_t  image 
)

Draw marker info.

The class-id corresponds is a number that is encoded in the inner square of the marker. It allows one to differentiate between varios markers.

Parameters
cA valid context object
mdA valid marker detector object
indexMarker index
imageImage to draw to
Return values
REME_ERROR_SUCCESSOn success
REME_ERROR_UNSPECIFIEDOn failure
Examples:
example_reconstructmesdk_marker.cpp.

◆ reme_marker_detector_generate_template_image()

reme_error_t reme_marker_detector_generate_template_image ( reme_context_t  c,
reme_marker_detector_t  md,
int  marker_id,
reme_image_t  image 
)

Get a marker template image that can be used for printing.

The class-id corresponds is a number that is encoded in the inner square of the marker. It allows one to differentiate between varios markers.

The following example shows its usage.

// Image to hold marker template image
reme_image_t marker;
reme_image_create(c, &marker);
// Marker detector that supplies template image. Note that
// the marker detector need to be a valid one.
// Save image for later printing.
reme_image_save_to_file(c, marker, "marker_213.png");
// Display marker inline for debugging purposes.
reme_viewer_create_image(c, "Marker Viewer", &v);
reme_viewer_add_image(c, v, marker);
Parameters
cA valid context object
mdA not necessarily valid marker detector object
marker_idMarker id to generate image for. Valid values range between 1 and 1023. Please note that only non-symmetric marker images should be used for detection.
imageImage to generate marker template to (3 channels / 1 byte per channel RGB).
Return values
REME_ERROR_SUCCESSOn success
REME_ERROR_UNSPECIFIEDOn failure
Examples:
example_reconstructmesdk_marker.cpp.