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:

• from a software point of view it is easily detectable,
• allows the estimation of camera pose with respect to the marker frame and
• does not need dense 3d data for pose estimation.

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

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

c	A valid context object
s	A valid sensor object to work on
md	A pointer to receive the created marker detector object handle.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On 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

c	A pointer to a valid context object
md	A mutable pointer to a valid marker detector handle to destroy

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On 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

c	A valid context object
md	A valid marker detector object
o	A valid options binding object

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On 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

c	A valid context object
md	A valid marker detector object
o	A valid options binding object

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On 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

c	A valid context object
md	A valid marker detector object
nmarkers	Number of markers found

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On 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

c	A valid context object
md	A valid marker detector object
index	Marker index
coordinates	A constant pointer to constant Transform data.

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On 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

c	A valid context object
md	A valid marker detector object
index	Marker index
id	Marker class id

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On 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

c	A valid context object
md	A valid marker detector object
index	Marker index
image	Image to draw to

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On 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.

    reme_context_t c;
    reme_context_create(&c);

    // 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.
    reme_marker_detector_t md = -1;
    reme_marker_detector_generate_template_image(c, md, 213, marker);

    // Save image for later printing.
    reme_image_save_to_file(c, marker, "marker_213.png");

    // Display marker inline for debugging purposes.
    reme_viewer_t v;
    reme_viewer_create_image(c, "Marker Viewer", &v);
    reme_viewer_add_image(c, v, marker);
    reme_viewer_update(c, v);
    reme_viewer_wait(c, v);

Parameters

c	A valid context object
md	A not necessarily valid marker detector object
marker_id	Marker 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.
image	Image to generate marker template to (3 channels / 1 byte per channel RGB).

Return values

REME_ERROR_SUCCESS	On success
REME_ERROR_UNSPECIFIED	On failure

Examples:

example_reconstructmesdk_marker.cpp.