 |
ReconstructMe SDK
2.6.43-0
Real-time 3D reconstruction engine
|
Acquire data from real-world sensors or from file streams. More...
Typedefs | |
| typedef int | reme_sensor_t |
| Handle referencing a sensor object. More... | |
| typedef enum _reme_sensor_image_t | reme_sensor_image_t |
| Image type enumeration. More... | |
| typedef enum _reme_sensor_view_t | reme_sensor_view_t |
| Sensor view type. More... | |
| typedef enum _reme_sensor_trackmode_t | reme_sensor_trackmode_t |
| Sensor tracking mode. More... | |
| typedef enum _reme_sensor_trackhint_t | reme_sensor_trackhint_t |
| Sensor tracking hint. More... | |
| typedef enum _reme_sensor_position_t | reme_sensor_position_t |
| Predefined sensor position. More... | |
Detailed Description
Acquire data from real-world sensors or from file streams.
The sensor is responsible for acquiring real world data and feeding it into the reconstruction volume. The life-time of reme_sensor_t sensor is usually the following
- Create a new sensor (reme_sensor_create) using either the backend name or a specific sensor configuration file. Usually this method returns with success when the necessary drivers for the sensor where found. It does usually not mean that the sensor is actually there. We say usually, since you can force a test to open the sensor at this point using the
require_can_openflag. - Modify sensor parameters (reme_sensor_bind_camera_options).
- Open the sensor (reme_sensor_open).
- Work with sensor images (reme_sensor_grab, reme_sensor_prepare_images).
- Close sensor (reme_sensor_close).
- Destroy sensor (reme_sensor_destroy).
The one-minute example illustrates the basic usage.
Typedef Documentation
◆ reme_sensor_t
| typedef int reme_sensor_t |
Handle referencing a sensor object.
A reme_sensor_t represents a RGBD sensor. Associated methods allow to create, open and interact with sensors of various types.
◆ reme_sensor_image_t
| typedef enum _reme_sensor_image_t reme_sensor_image_t |
Image type enumeration.
Each sensor might provide different frame types that are all 2D images. Not all sensors support all frames, or the number of frames supported is configuration dependant.
◆ reme_sensor_view_t
| typedef enum _reme_sensor_view_t reme_sensor_view_t |
Sensor view type.
When dealing with sensor data ReconstructMe offers two types of views. The first view REME_SENSOR_VIEW_RAW corresponds to data passed as raw input to ReconstructMe. The second view type is REME_SENSOR_VIEW_RECONSTRUCTED and corresponds to a synthetic view generated by raytracing the volume from the current sensor to volume position.
The REME_SENSOR_VIEW_RECONSTRUCTED normally is much more smooth and has less holes than REME_SENSOR_VIEW_RAW, but naturally limits data to the size of the reconstruction volume.
◆ reme_sensor_trackmode_t
| typedef enum _reme_sensor_trackmode_t reme_sensor_trackmode_t |
Sensor tracking mode.
Defines the basic tracking strategy to find the sensor position based on current and past sensor data.
◆ reme_sensor_trackhint_t
| typedef enum _reme_sensor_trackhint_t reme_sensor_trackhint_t |
Sensor tracking hint.
Provides optional hints for the sensor tracking module.
◆ reme_sensor_position_t
| typedef enum _reme_sensor_position_t reme_sensor_position_t |
Predefined sensor position.
Determines a predefined sensor position with respect to the current volume. See reme_sensor_get_prescan_position and reme_sensor_set_prescan_position for more information.
Enumeration Type Documentation
◆ _reme_sensor_image_t
| enum _reme_sensor_image_t |
Image type enumeration.
Each sensor might provide different frame types that are all 2D images. Not all sensors support all frames, or the number of frames supported is configuration dependant.
◆ _reme_sensor_view_t
| enum _reme_sensor_view_t |
Sensor view type.
When dealing with sensor data ReconstructMe offers two types of views. The first view REME_SENSOR_VIEW_RAW corresponds to data passed as raw input to ReconstructMe. The second view type is REME_SENSOR_VIEW_RECONSTRUCTED and corresponds to a synthetic view generated by raytracing the volume from the current sensor to volume position.
The REME_SENSOR_VIEW_RECONSTRUCTED normally is much more smooth and has less holes than REME_SENSOR_VIEW_RAW, but naturally limits data to the size of the reconstruction volume.
| Enumerator | |
|---|---|
| REME_SENSOR_VIEW_RAW | Raw data view. |
| REME_SENSOR_VIEW_RECONSTRUCTED | Synthetic raytraced data view. |
◆ _reme_sensor_trackmode_t
Sensor tracking mode.
Defines the basic tracking strategy to find the sensor position based on current and past sensor data.
◆ _reme_sensor_trackhint_t
Sensor tracking hint.
Provides optional hints for the sensor tracking module.
| Enumerator | |
|---|---|
| REME_SENSOR_TRACKHINT_NONE | No hint |
| REME_SENSOR_TRACKHINT_USE_GLOBAL | Temporarily switch to global search until tracking is found again. This hint is automatically cleared when tracking is found. It is a convinient way of letting the tracking module know that tracking should be done using global search until we are sure that tracking is found again. |
| REME_SENSOR_TRACKHINT_DONT_TRACK | Temporarily skip tracking for the current invocation. This is useful to avoid growing code complexity when tracking should not occur in a certain frame. The result of setting this track hint and invoking reme_sensor_track_position is the same as not calling reme_sensor_track_position once. |
◆ _reme_sensor_position_t
Predefined sensor position.
Determines a predefined sensor position with respect to the current volume. See reme_sensor_get_prescan_position and reme_sensor_set_prescan_position for more information.
Function Documentation
◆ reme_sensor_create()
| reme_error_t reme_sensor_create | ( | reme_context_t | c, |
| const char * | driver, | ||
| bool | require_can_open, | ||
| reme_sensor_t * | s | ||
| ) |
Create a new sensor object.
Creates a new sensor. The driver argument specifies which sensor to open. The following sensor drivers are currently available
- mskinect Microsoft Kinect for Windows and Kinect for XBox
- openni Asus Xtion, Asus Xtion Pro Live, Primsense Carmine 1.08, Primesense Carmine 1.09
- librealsense Intel RealSense F200, R200, SR300.
- file A generic file sensor to read previously recorded data
- external A generic external sensor whose data is provided from the caller.
- network A generic network sensor whose data is provided via a TCP/IP network stream.
You might specify a specific driver backend
Alternatively you can specify a list of drivers to test, in which case it will return the first sensor that works.
Or, specify file containing a sensor configuration file (see reme_sensor_bind_camera_options for camera specific options and Accessing and Modifying Options for background information about options)
The drivers will be tested in the given order.
Set require_can_open to true to ensure the created sensor can be created and opened using either the default settings, or if file paths are specifed using the settings specified in the file.
No matter how require_can_open is set the sensor is returned in closed state. Use reme_sensor_open to open it.
- Warning
- require_can_open set to true can lead to longer sensor opening times, because the sensor is tested. If you know what sensor you are opening set it to false.
- require_can_open can lead to deadlocks when using 'mskinect' due to fast opening and closing of the sensor.
- Parameters
-
c A valid context object driver The name of sensor driver to instance a sensor from require_can_open Ensures that the returned sensor can be opened using either the default sensor options. s A pointer that will receive the handle of the created sensor
- Return values
-
REME_ERROR_SUCCESS On success REME_ERROR_UNSPECIFIED On failure
- Examples:
- example_reconstructmesdk_bust.cpp, example_reconstructmesdk_calibration.cpp, example_reconstructmesdk_color_tracking.cpp, example_reconstructmesdk_colorize.cpp, example_reconstructmesdk_csg.cpp, example_reconstructmesdk_image.cpp, example_reconstructmesdk_marker.cpp, example_reconstructmesdk_one_minute.cpp, example_reconstructmesdk_point_and_shoot_with_colors.cpp, example_reconstructmesdk_recorder.cpp, example_reconstructmesdk_recorder_update_fileformat.cpp, example_reconstructmesdk_remote_reconstruction.cpp, example_reconstructmesdk_scan_tilt.cpp, example_reconstructmesdk_sensor.cpp, example_reconstructmesdk_sensor_external.cpp, example_reconstructmesdk_sensor_multi_independent.cpp, example_reconstructmesdk_sensor_printing.cpp, example_reconstructmesdk_sensor_threaded.cpp, example_reconstructmesdk_surface.cpp, and example_reconstructmesdk_volume.cpp.
◆ reme_sensor_destroy()
| reme_error_t reme_sensor_destroy | ( | reme_context_t | c, |
| reme_sensor_t * | s | ||
| ) |
Destroy a previously created sensor object.
- Parameters
-
c A pointer to a valid context object s A mutable pointer to a valid sensor handle to destroy
- Return values
-
REME_ERROR_SUCCESS On success REME_ERROR_UNSPECIFIED On failure
- Examples:
- example_reconstructmesdk_bust.cpp, example_reconstructmesdk_color_tracking.cpp, example_reconstructmesdk_colorize.cpp, example_reconstructmesdk_marker.cpp, example_reconstructmesdk_one_minute.cpp, example_reconstructmesdk_point_and_shoot_with_colors.cpp, example_reconstructmesdk_sensor.cpp, example_reconstructmesdk_sensor_printing.cpp, and example_reconstructmesdk_surface.cpp.
◆ reme_sensor_open()
| reme_error_t reme_sensor_open | ( | reme_context_t | c, |
| reme_sensor_t | s | ||
| ) |
Open a sensor.
Attempts to opens the specified sensor using the specified sensor options.
- Parameters
-
c A valid context object s A valid sensor object
- Return values
-
REME_ERROR_SUCCESS On success REME_ERROR_UNSPECIFIED On failure
- Examples:
- example_reconstructmesdk_bust.cpp, example_reconstructmesdk_calibration.cpp, example_reconstructmesdk_color_tracking.cpp, example_reconstructmesdk_colorize.cpp, example_reconstructmesdk_csg.cpp, example_reconstructmesdk_image.cpp, example_reconstructmesdk_marker.cpp, example_reconstructmesdk_one_minute.cpp, example_reconstructmesdk_point_and_shoot_with_colors.cpp, example_reconstructmesdk_recorder.cpp, example_reconstructmesdk_recorder_update_fileformat.cpp, example_reconstructmesdk_remote_reconstruction.cpp, example_reconstructmesdk_scan_tilt.cpp, example_reconstructmesdk_sensor.cpp, example_reconstructmesdk_sensor_external.cpp, example_reconstructmesdk_sensor_multi_independent.cpp, example_reconstructmesdk_sensor_printing.cpp, example_reconstructmesdk_sensor_threaded.cpp, example_reconstructmesdk_surface.cpp, and example_reconstructmesdk_volume.cpp.
◆ reme_sensor_close()
| reme_error_t reme_sensor_close | ( | reme_context_t | c, |
| reme_sensor_t | s | ||
| ) |
Close a an open sensor.
Indicates that no more grabbing is done from sensor. Re-opening a sensor is possible.
- Parameters
-
c A valid context object s A valid sensor object
- Return values
-
REME_ERROR_SUCCESS On success REME_ERROR_UNSPECIFIED On failure
- Examples:
- example_reconstructmesdk_bust.cpp, example_reconstructmesdk_color_tracking.cpp, example_reconstructmesdk_colorize.cpp, example_reconstructmesdk_marker.cpp, example_reconstructmesdk_one_minute.cpp, example_reconstructmesdk_point_and_shoot_with_colors.cpp, example_reconstructmesdk_sensor.cpp, example_reconstructmesdk_sensor_printing.cpp, and example_reconstructmesdk_surface.cpp.
◆ reme_sensor_set_volume()
| reme_error_t reme_sensor_set_volume | ( | reme_context_t | c, |
| reme_sensor_t | s, | ||
| reme_volume_t | v | ||
| ) |
Set the working volume.
The sensor will use this volume to keep track of its position and it will also update into this volume. By default the sensor is assigned to the first volume available.
- Parameters
-
c A valid context object s A valid sensor object v A valid volume object
- Return values
-
REME_ERROR_SUCCESS On success REME_ERROR_UNSPECIFIED On failure
◆ reme_sensor_set_trackmode()
| reme_error_t reme_sensor_set_trackmode | ( | reme_context_t | c, |
| reme_sensor_t | s, | ||
| reme_sensor_trackmode_t | t | ||
| ) |
Set tracking mode.
Sets the overall tracking strategy. By default REME_SENSOR_TRACKMODE_AUTO is used.
- Parameters
-
c A valid context object s A valid sensor object t A valid tracking mode
- Return values
-
REME_ERROR_SUCCESS On success REME_ERROR_UNSPECIFIED On failure
◆ reme_sensor_set_trackhint()
| reme_error_t reme_sensor_set_trackhint | ( | reme_context_t | c, |
| reme_sensor_t | s, | ||
| reme_sensor_trackhint_t | t | ||
| ) |
Sets a tracking hint.
The tracking hint is an external user supplied information to support the camera tracking module. Any tracking hint given remains active until the next call to reme_sensor_track_position.
Supplying tracking hints becomes useful when the caller has external knowledge unknown to the tracking module. For example the caller might set REME_SENSOR_TRACKHINT_USE_GLOBAL to indicate that the tracking module is should resort to global tracking in the next iteration.
Tracking hints are automatically cleared after the next call to reme_sensor_track_position.
- Parameters
-
c A valid context object s A valid sensor object t A valid tracking hint
- Return values
-
REME_ERROR_SUCCESS On success REME_ERROR_UNSPECIFIED On failure
◆ reme_sensor_bind_camera_options()
| reme_error_t reme_sensor_bind_camera_options | ( | reme_context_t | c, |
| reme_sensor_t | s, | ||
| reme_options_t | o | ||
| ) |
Access the sensor specific options that affect how the camera is opened.
- Associated Protocol Buffers Specification
- Depending on the sensor chosen on create, different specs are needed, since each sensor supports a different set of parameters.
For openni sensors (OpenNI 2.x)
For mskinect sensors
For librealsense sensors
Where LibRealsenseOpts is explained in the docs of reme_sensor_bind_capture_options
For file sensors
For external sensors
For network sensors
Common to almost all configurations (exception: network sensor - here the configuration is transmitted by the streaming service) above is the usage of the LibRGBDSensor.videostream
The referenced LibRGBDSensor.intrinsics has the following layout
- Note
- When radial or tangential distortion parameters are not equal zero a distortion correction will be performed.
- Changing camera options take effect on the next call to reme_sensor_open.
- Parameters
-
c A valid context object s A valid sensor object o A valid options binding object
- Return values
-
REME_ERROR_SUCCESS On success REME_ERROR_UNSPECIFIED On failure
- Examples:
- example_reconstructmesdk_calibration.cpp, example_reconstructmesdk_color_tracking.cpp, example_reconstructmesdk_colorize.cpp, example_reconstructmesdk_csg.cpp, example_reconstructmesdk_point_and_shoot_with_colors.cpp, example_reconstructmesdk_recorder.cpp, example_reconstructmesdk_sensor.cpp, and example_reconstructmesdk_sensor_external.cpp.
◆ reme_sensor_bind_capture_options()
| reme_error_t reme_sensor_bind_capture_options | ( | reme_context_t | c, |
| reme_sensor_t | s, | ||
| reme_options_t | o | ||
| ) |
Access the sensor specific capture options with their current values.
- Associated Protocol Buffers Specification
Depending on the sensor chosen on create, different specs are needed, since each sensor supports a different set of parameters.
For openni sensors
For mskinect sensors
For librealsense sensors
where LibRealsenseOpts is
For file sensors
Common to all configurations above is the frame_info field. It is mendatory for reconstruction and has the following structure
- Note
- The capture options are updated with current value when reme_sensor_bind_capture_options is called.
- Changing capture options without a call to reme_sensor_apply_capture_options has no effect.
- Parameters
-
c A valid context object s A valid sensor object o A valid options binding object
- Return values
-
REME_ERROR_SUCCESS On success REME_ERROR_UNSPECIFIED On failure
◆ reme_sensor_apply_capture_options()
| reme_error_t reme_sensor_apply_capture_options | ( | reme_context_t | c, |
| reme_sensor_t | s, | ||
| reme_options_t | o | ||
| ) |
Apply capture options.
Causes all capture options set to be applied at given sensor. In order to set only specific options, invoke reme_options_clear on the options target before setting the new values. Then invoke reme_sensor_apply_capture_options.
- Parameters
-
c A valid context object s A valid sensor object o A valid options binding object
- Return values
-
REME_ERROR_SUCCESS On success REME_ERROR_UNSPECIFIED On failure
◆ reme_sensor_bind_render_options()
| reme_error_t reme_sensor_bind_render_options | ( | reme_context_t | c, |
| reme_sensor_t | s, | ||
| reme_options_t | o | ||
| ) |
Access the sensor specific render options.
These options define how sensor images are rendered. Use reme_sensor_apply_render_options to apply value changes.
- Associated Protocol Buffers Specification
- // Render optionsmessage render_options {// Color typemessage color4_type {// Red channel [0..1]required float r = 1;// Green channel [0..1]required float g = 2;// Blue channel [0..1]required float b = 3;// Alpha channel [0..1]required float a = 4;}// How shading of the volume image is performed.enum shade_type {// Shade points using Blinn-Phong modellSHADE_PHONG = 0;// Shade points according to normal direction.SHADE_NORMALS = 1;// Colorize pixels using input color. This is only// a valid options if colors are supported.SHADE_COLORS = 2;}// Clear color for volume images.// By default this maps to a dark-gray color.optional color4_type clear_color = 1;// Diffuse color for volume images. Only used// when SHADE_PHONG is enabled.// By default this maps to a pastel-blue color.optional color4_type diffuse_color = 2;// Border color. Defines the color to apply to color borders,// which are found in areas without complete texture/geometry// information.// This color only applies when using SHADE_COLORS.optional color4_type border_color = 3;// Shading mode.optional shade_type shade_mode = 4 [default = SHADE_PHONG];}
- Parameters
-
c A valid context object s A valid sensor object o A valid options binding object
- Return values
-
REME_ERROR_SUCCESS On success REME_ERROR_UNSPECIFIED On failure
◆ reme_sensor_apply_render_options()
| reme_error_t reme_sensor_apply_render_options | ( | reme_context_t | c, |
| reme_sensor_t | s, | ||
| reme_options_t | o | ||
| ) |
Apply render options.
Causes all render options to be applied at given sensor.
- Parameters
-
c A valid context object s A valid sensor object o A valid options binding object
- Return values
-
REME_ERROR_SUCCESS On success REME_ERROR_UNSPECIFIED On failure
◆ reme_sensor_get_position()
| reme_error_t reme_sensor_get_position | ( | reme_context_t | c, |
| reme_sensor_t | s, | ||
| float * | coordinates | ||
| ) |
Get the sensor position with respect to the world coordinate frame.
Initially this is set to identity for all sensors. The position is modified when reme_sensor_track_position succeeds, or reme_sensor_set_position is called.
- Parameters
-
c A valid context object s A valid sensor object coordinates A constant pointer to constant Transform data.
- Return values
-
REME_ERROR_SUCCESS On success REME_ERROR_UNSPECIFIED On failure
◆ reme_sensor_get_recovery_position()
| reme_error_t reme_sensor_get_recovery_position | ( | reme_context_t | c, |
| reme_sensor_t | s, | ||
| float * | coordinates | ||
| ) |
Get the sensor recovery position with respect to the world coordinate frame.
Whenever the sensor cannot find track, it puts itself into recovery pose. It then waits in the recovery pose for tracking to succeed. The recovery pose will be updated during ongoing tracking automatically. I.e when there is sufficient confidence that the last n-frames where tracked successfully, ReconstructMe generates a new recovery pose.
Initially this is set to identity for all sensors. The position is modified when reme_sensor_track_position succeeds several times, or reme_sensor_set_recovery_position is called.
- Parameters
-
c A valid context object s A valid sensor object coordinates A constant pointer to constant Transform data.
- Return values
-
REME_ERROR_SUCCESS On success REME_ERROR_UNSPECIFIED On failure
◆ reme_sensor_get_incremental_position()
| reme_error_t reme_sensor_get_incremental_position | ( | reme_context_t | c, |
| reme_sensor_t | s, | ||
| float * | coordinates | ||
| ) |
Get the incremental movement of the sensor.
When reme_sensor_track_position succeeds this position reflects the movement of the sensor between the last position of the sensor and the current position of the sensor.
- Parameters
-
c A valid context object s A valid sensor object coordinates A constant pointer to pre-allocated Transform data.
- Return values
-
REME_ERROR_SUCCESS On success REME_ERROR_UNSPECIFIED On failure
◆ reme_sensor_get_prescan_position()
| reme_error_t reme_sensor_get_prescan_position | ( | reme_context_t | c, |
| reme_sensor_t | s, | ||
| reme_sensor_position_t | t, | ||
| float * | coordinates | ||
| ) |
Calculate a predefined sensor position with respect to the volume.
This method calculates a sensor position based on the value of reme_sensor_position_t. Depending on the choice of reme_sensor_position_t, this method makes use the the attached volume and/or the last sensor depth-map.
- Note
- This method is deprectated. Use
- reme_sensor_get_prescan_position_infront
- reme_sensor_get_prescan_position_center
- reme_sensor_get_prescan_position_marker instead.
The meaning of reme_sensor_position_t is as follows:
- REME_SENSOR_POSITION_INFRONT Assume without loss of generality that the sensor held horizontally pointing towards the target. Then the position is chosen so that z-axis of the world coordinate is the natural up-direction, the sensor looks towards the positive y-axis of the world coordinate system, the sensor is located at the center of the front face of the reconstruction volume and is moved back (negative y-axis) by 300 units.
- REME_SENSOR_POSITION_CENTER The sensor is placed in the center of the volume.
- REME_SENSOR_POSITION_FLOOR The sensor is placed such that the volume is pinned to the floor according to reme_sensor_find_floor. This type makes use of the current depth-map to determine the floor.
- Parameters
-
c A valid context object s A valid sensor object t Type of predefined position to set coordinates A pointer to pre-allocated Transform data.
- Return values
-
REME_ERROR_SUCCESS On success REME_ERROR_NO_FLOOR If no floor is found in the current sensor's depthmap REME_ERROR_UNSPECIFIED On failure
◆ reme_sensor_get_prescan_position_infront()
| reme_error_t reme_sensor_get_prescan_position_infront | ( | reme_context_t | c, |
| reme_sensor_t | s, | ||
| float | offset, | ||
| float * | coordinates | ||
| ) |
Helper function to calculate a sensor position.
Assume without loss of generality that the sensor held horizontally pointing towards the target. Then the position is chosen so that z-axis of the world coordinate is the natural up-direction, the sensor looks towards the positive y-axis of the world coordinate system, the sensor is located at the center of the front face of the reconstruction volume and is moved back (negative y-axis) by offset units.
- Parameters
-
c A valid context object s A valid sensor object offset Amount of space between sensor and front plane of volume. coordinates A pointer to pre-allocated Transform data.
- Return values
-
REME_ERROR_SUCCESS On success REME_ERROR_UNSPECIFIED On failure
◆ reme_sensor_get_prescan_position_center()
| reme_error_t reme_sensor_get_prescan_position_center | ( | reme_context_t | c, |
| reme_sensor_t | s, | ||
| float * | coordinates | ||
| ) |
Helper function to calculate a sensor position.
Returns a transform that positions the sensor in the center of the volume.
- Parameters
-
c A valid context object s A valid sensor object coordinates A pointer to pre-allocated Transform data.
- Return values
-
REME_ERROR_SUCCESS On success REME_ERROR_UNSPECIFIED On failure
◆ reme_sensor_get_prescan_position_marker()
| reme_error_t reme_sensor_get_prescan_position_marker | ( | reme_context_t | c, |
| reme_sensor_t | s, | ||
| const float * | markerPose, | ||
| float | offset, | ||
| float * | coordinates | ||
| ) |
Helper function to calculate a sensor position.
Returns a transformation that positions the sensor in such a way that the volume is placed centered around the marker volume bottom plane (xy-plane) offset units way from the xy-plane of marker pose. A positive offset will therefore lift the volume above the marker, which can be useful in case you don't want to have data from the plane the marker resides on reconstructed.
- Parameters
-
c A valid context object s A valid sensor object markerPose Position of marker (reme_marker_detector_get_position) or any external coordinate frame. offset Amount of space between bottom plane of volume and marker coordinate system. Positive values will allow you to cut away data from the plane the marker resides in. coordinates A pointer to pre-allocated Transform data.
- Return values
-
REME_ERROR_SUCCESS On success REME_ERROR_UNSPECIFIED On failure
◆ reme_sensor_set_position()
| reme_error_t reme_sensor_set_position | ( | reme_context_t | c, |
| reme_sensor_t | s, | ||
| const float * | coordinates | ||
| ) |
Set the sensor position with respect to the world coordinate frame.
Initially this is set to identity for all sensors.
- Parameters
-
c A valid context object s A valid sensor object coordinates A pointer to constant Transform data.
- Return values
-
REME_ERROR_SUCCESS On success REME_ERROR_UNSPECIFIED On failure
◆ reme_sensor_set_incremental_position()
| reme_error_t reme_sensor_set_incremental_position | ( | reme_context_t | c, |
| reme_sensor_t | s, | ||
| const float * | coordinates | ||
| ) |
Set the incremental movement of the sensor.
Updates the world position of the sensor by the incremental position specified.
- Parameters
-
c A valid context object s A valid sensor object coordinates A pointer to constant Transform data.
- Return values
-
REME_ERROR_SUCCESS On success REME_ERROR_UNSPECIFIED On failure
◆ reme_sensor_set_recovery_position()
| reme_error_t reme_sensor_set_recovery_position | ( | reme_context_t | c, |
| reme_sensor_t | s, | ||
| const float * | coordinates | ||
| ) |
Set the sensor recovery position with respect to the world coordinate frame.
Whenever the sensor cannot find track, it puts itself into recovery pose. It then waits in the recovery pose for tracking to succeed. The recovery pose will be updated during ongoing tracking automatically. I.e when there is sufficient confidence that the last n-frames where tracked successfully, ReconstructMe generates a new recovery pose.
Initially this is set to identity for all sensors. The position is modified when reme_sensor_track_position succeeds several times, or reme_sensor_set_recovery_position is called.
- Parameters
-
c A valid context object s A valid sensor object coordinates A constant pointer to constant Transform data.
- Return values
-
REME_ERROR_SUCCESS On success REME_ERROR_UNSPECIFIED On failure
- Examples:
- example_reconstructmesdk_sensor_printing.cpp.
◆ reme_sensor_set_prescan_position()
| reme_error_t reme_sensor_set_prescan_position | ( | reme_context_t | c, |
| reme_sensor_t | s, | ||
| reme_sensor_position_t | t | ||
| ) |
Position the sensor and volume with respect to each other using a predefined position.
Initially the sensor position is identity for all sensors. By calling this method the sensor position and recovery position change to an auto-calculated sensor position based on the value of reme_sensor_position_t.
This method is considered a helper method consisting of the following steps:
Please refer to reme_sensor_get_prescan_position for an in-depth explanation of reme_sensor_position_t choices.
- Parameters
-
c A valid context object s A valid sensor object t Type of predefined position to set
- Return values
-
REME_ERROR_SUCCESS On success REME_ERROR_NO_FLOOR If no floor is found in the current sensor's depthmap REME_ERROR_UNSPECIFIED On failure
- Examples:
- example_reconstructmesdk_bust.cpp, example_reconstructmesdk_color_tracking.cpp, example_reconstructmesdk_colorize.cpp, example_reconstructmesdk_one_minute.cpp, example_reconstructmesdk_point_and_shoot_with_colors.cpp, example_reconstructmesdk_recorder.cpp, example_reconstructmesdk_remote_reconstruction.cpp, example_reconstructmesdk_scan_tilt.cpp, example_reconstructmesdk_sensor_external.cpp, example_reconstructmesdk_sensor_multi_independent.cpp, example_reconstructmesdk_sensor_threaded.cpp, example_reconstructmesdk_surface.cpp, and example_reconstructmesdk_volume.cpp.
◆ reme_sensor_reset()
| reme_error_t reme_sensor_reset | ( | reme_context_t | c, |
| reme_sensor_t | s | ||
| ) |
Resets the sensor to identity position.
Forces the sensor to loose track.
- Parameters
-
c A valid context object s A valid sensor object
- Return values
-
REME_ERROR_SUCCESS On tracking success or the corresponding volume is empty. REME_ERROR_UNSPECIFIED is returned otherwise.
◆ reme_sensor_get_image()
| reme_error_t reme_sensor_get_image | ( | reme_context_t | c, |
| reme_sensor_t | s, | ||
| reme_sensor_image_t | it, | ||
| reme_image_t | i | ||
| ) |
Get a specific sensor image.
Each sensor might provide different frame types. Not all sensors support all frames, or the number of frames supported is configuration dependant. See reme_sensor_image_t for a complete enumeration of available image types.
- Memory Management Rules Exception
The returned image remains valid until the sensor is destroyed or the dimension of the image changes. The pointer is recycled internally, which means that it will point to different values each time the sensor images are updated.
- Parameters
-
c A valid context object s A valid sensor object it Image type to access i A valid image object to receive image data
- Return values
-
REME_ERROR_SUCCESS On success REME_ERROR_UNSPECIFIED On failure
- Examples:
- example_reconstructmesdk_bust.cpp, example_reconstructmesdk_calibration.cpp, example_reconstructmesdk_color_tracking.cpp, example_reconstructmesdk_colorize.cpp, example_reconstructmesdk_image.cpp, example_reconstructmesdk_marker.cpp, example_reconstructmesdk_one_minute.cpp, example_reconstructmesdk_point_and_shoot_with_colors.cpp, example_reconstructmesdk_recorder.cpp, example_reconstructmesdk_remote_reconstruction.cpp, example_reconstructmesdk_scan_tilt.cpp, example_reconstructmesdk_sensor.cpp, example_reconstructmesdk_sensor_external.cpp, example_reconstructmesdk_sensor_multi_independent.cpp, example_reconstructmesdk_sensor_printing.cpp, example_reconstructmesdk_sensor_threaded.cpp, example_reconstructmesdk_surface.cpp, and example_reconstructmesdk_volume.cpp.
◆ reme_sensor_is_image_supported()
| reme_error_t reme_sensor_is_image_supported | ( | reme_context_t | c, |
| reme_sensor_t | s, | ||
| reme_sensor_image_t | it, | ||
| bool * | result | ||
| ) |
Test if a specific image type is available.
Each sensor might provide different frame types. Not all sensors support all frames, or the number of frames supported is configuration dependant. See reme_sensor_image_t for a complete enumeration of available image types.
- Parameters
-
c A valid context object s A valid sensor object it Image type to access result Whether image type is supported or not.
- Return values
-
REME_ERROR_SUCCESS On success REME_ERROR_UNSPECIFIED On failure
◆ reme_sensor_is_image_updated()
| reme_error_t reme_sensor_is_image_updated | ( | reme_context_t | c, |
| reme_sensor_t | s, | ||
| reme_sensor_image_t | it, | ||
| bool * | result | ||
| ) |
Test if a specific image type was updated since the last call to reme_sensor_prepare_images, reme_sensor_prepare_image.
Sensor implementations are allowed to not provide an updated image for a specific type at all times. Notably is the network sensor and associated streaming service who might opt for sending a color image only every n-th frame to save bandwidth.
- Parameters
-
c A valid context object s A valid sensor object it Image type to access result Whether image type was updated since the last call to reme_sensor_prepare_images, reme_sensor_prepare_image.
- Return values
-
REME_ERROR_SUCCESS On success REME_ERROR_UNSPECIFIED On failure
◆ reme_sensor_get_points()
| reme_error_t reme_sensor_get_points | ( | reme_context_t | c, |
| reme_sensor_t | s, | ||
| reme_sensor_view_t | v, | ||
| const float ** | coordinates, | ||
| int * | length | ||
| ) |
Get points corresponding to the current sensor view.
Depending on the choice of v (reme_sensor_view_t) this returns
- REME_SENSOR_VIEW_RAW the raw sensor points generated from the last invocation of reme_sensor_prepare_images or reme_sensor_prepare_image with argument REME_IMAGE_VOLUME.
- REME_SENSOR_VIEW_RECONSTRUCTED the synthetic raytraced sensor points generated from the last invocation of reme_sensor_prepare_images or reme_sensor_prepare_image with argument REME_IMAGE_VOLUME.
The points are represented as an array of floats where each point consists of 4 coordinates Px Py Pz Pw Px Py Pz Pw ... . The w component is always zero. The i-th point starts at index i * 4 of coordinate array returned.
The number of points returned corresponds to the number of pixels of the native sensor. That is, if your sensor has a resolution of 640x480 (cols x rows) the number of returned normals is 640 * 480. The normals are returned in row-wise order. Those points that do not represent a valid data are marked with a sentinel value (NAN) in their x-coordinate. To access the point corresponding to pixel of row i and column j use i * cols * 4 + j * 4 where cols is the number of pixel columns of the native sensor.
- Parameters
-
c A valid context object s A valid sensor object v view type specification coordinates A mutable pointer to constant point data. length The number of coordinates returned. To get the number of points divide this value by 4.
- Return values
-
REME_ERROR_SUCCESS On success REME_ERROR_UNSPECIFIED On failure
◆ reme_sensor_get_point_normals()
| reme_error_t reme_sensor_get_point_normals | ( | reme_context_t | c, |
| reme_sensor_t | s, | ||
| reme_sensor_view_t | v, | ||
| const float ** | coordinates, | ||
| int * | length | ||
| ) |
Get point normals corresponding to the current sensor view.
Depending on the choice of v (reme_sensor_view_t) this returns
- REME_SENSOR_VIEW_RAW the raw sensor normals generated from the last invocation of reme_sensor_prepare_images or reme_sensor_prepare_image with argument REME_IMAGE_VOLUME.
- REME_SENSOR_VIEW_RECONSTRUCTED the synthetic raytraced sensor normals generated from the last invocation of reme_sensor_prepare_images or reme_sensor_prepare_image with argument REME_IMAGE_VOLUME.
The point normals are represented as an array of floats where each point consists of 4 coordinates Px Py Pz Pw Px Py Pz Pw ... . The w component is always zero. The i-th normal starts at index i * 4 of coordinate array returned.
The number of normals returned corresponds to the number of pixels of the native sensor. That is, if your sensor has a resolution of 640x480 (cols x rows) the number of returned normals is 640 * 480. The normals are returned in row-wise order. Those normals that do not represent a valid data are marked with a sentinel value (NAN) in their x-coordinate. To access the normal corresponding to pixel of row i and column j use i * cols * 4 + j * 4 where cols is the number of pixel columns of the native sensor.
- Parameters
-
c A valid context object s A valid sensor object v view type specification coordinates A mutable pointer to constant normal data. length The number of coordinates returned. To get the number of normals divide this value by 4.
- Return values
-
REME_ERROR_SUCCESS On success REME_ERROR_UNSPECIFIED On failure
◆ reme_sensor_get_point_colors()
| reme_error_t reme_sensor_get_point_colors | ( | reme_context_t | c, |
| reme_sensor_t | s, | ||
| reme_sensor_view_t | v, | ||
| const float ** | channels, | ||
| int * | length | ||
| ) |
Get point colors corresponding to the current sensor view.
Depending on the choice of v (reme_sensor_view_t) this returns
- REME_SENSOR_VIEW_RAW the raw sensor colors generated from the last invocation of reme_sensor_prepare_images or reme_sensor_prepare_image with argument REME_IMAGE_VOLUME.
- REME_SENSOR_VIEW_RECONSTRUCTED the synthetic raytraced sensor colors generated from the last invocation of reme_sensor_prepare_images or reme_sensor_prepare_image with argument REME_IMAGE_VOLUME.
Colors are only available if the current compiled context supports colorization of vertices.
The point colors are represented as an array of floats where each color consists of 4 channels r g b a r g b a ... . The a component is always zero. The i-th color starts at index i * 4 of array returned. The range for each channel is [0..1].
The number of colors returned corresponds to the number of pixels of the native sensor. That is, if your sensor has a resolution of 640x480 (cols x rows) the number of returned colors is 640 * 480. The colors are returned in row-wise order. To access the color corresponding to pixel of row i and column j use i * cols * 4 + j * 4 where cols is the number of pixel columns of the native sensor.
- Parameters
-
c A valid context object s A valid sensor object v view type specification channels A mutable pointer to constant color data. length The number of channels returned. To get the number of colors divide this value by 4.
- Return values
-
REME_ERROR_SUCCESS On success REME_ERROR_NO_COLOR_SUPPORT if no color is available. REME_ERROR_UNSPECIFIED On failure
◆ reme_sensor_get_track_time()
| reme_error_t reme_sensor_get_track_time | ( | reme_context_t | c, |
| reme_sensor_t | s, | ||
| int * | track_time | ||
| ) |
Get the tracking time.
The tracking time corresponds to the number of frames in which tracking succeeded. In case tracking fails the counter gets negative.
- Parameters
-
c A valid context object s A valid sensor object track_time The tracking time
- Return values
-
REME_ERROR_SUCCESS On success REME_ERROR_UNSPECIFIED On failure
◆ reme_sensor_grab()
| reme_error_t reme_sensor_grab | ( | reme_context_t | c, |
| reme_sensor_t | s | ||
| ) |
Trigger frame grabbing.
Provides a synchronization point to trigger image generation of all image types. This method is intended to be fast.
In order to synchronize frame grabbing from multiple sensors, call this method in sequence for each sensor before calling reme_sensor_retrieve.
- Parameters
-
c A valid context object s A valid sensor object
- Return values
-
REME_ERROR_SUCCESS On success REME_ERROR_FAILED_TO_GRAB Failed to grab from sensor. This is not necessarily an error, you might re-try. REME_ERROR_UNSPECIFIED Is returned otherwise.
- Examples:
- example_reconstructmesdk_bust.cpp, example_reconstructmesdk_calibration.cpp, example_reconstructmesdk_color_tracking.cpp, example_reconstructmesdk_colorize.cpp, example_reconstructmesdk_image.cpp, example_reconstructmesdk_marker.cpp, example_reconstructmesdk_one_minute.cpp, example_reconstructmesdk_point_and_shoot_with_colors.cpp, example_reconstructmesdk_recorder.cpp, example_reconstructmesdk_recorder_update_fileformat.cpp, example_reconstructmesdk_remote_reconstruction.cpp, example_reconstructmesdk_scan_tilt.cpp, example_reconstructmesdk_sensor.cpp, example_reconstructmesdk_sensor_external.cpp, example_reconstructmesdk_sensor_multi_independent.cpp, example_reconstructmesdk_sensor_printing.cpp, example_reconstructmesdk_sensor_threaded.cpp, example_reconstructmesdk_surface.cpp, and example_reconstructmesdk_volume.cpp.
◆ reme_sensor_prepare_images()
| reme_error_t reme_sensor_prepare_images | ( | reme_context_t | c, |
| reme_sensor_t | s | ||
| ) |
Retrieve image data corresponding to the previous grab command for further processing.
Updates the internal state of all images and prepares the required data structures on the computation device.
- Parameters
-
c A valid context object s A valid sensor object
- Return values
-
REME_ERROR_SUCCESS On success REME_ERROR_UNSPECIFIED On failure
- Examples:
- example_reconstructmesdk_bust.cpp, example_reconstructmesdk_color_tracking.cpp, example_reconstructmesdk_colorize.cpp, example_reconstructmesdk_marker.cpp, example_reconstructmesdk_one_minute.cpp, example_reconstructmesdk_recorder.cpp, example_reconstructmesdk_scan_tilt.cpp, example_reconstructmesdk_sensor_multi_independent.cpp, example_reconstructmesdk_sensor_printing.cpp, example_reconstructmesdk_sensor_threaded.cpp, example_reconstructmesdk_surface.cpp, and example_reconstructmesdk_volume.cpp.
◆ reme_sensor_prepare_image()
| reme_error_t reme_sensor_prepare_image | ( | reme_context_t | c, |
| reme_sensor_t | s, | ||
| _reme_sensor_image_t | i | ||
| ) |
Retrieve specific image data for subsequent processing.
In case REME_IMAGE_AUX or REME_IMAGE_DEPTH is passed, this method will fetch the data into internal memory. In case REME_IMAGE_VOLUME is passed, the previously prepared REME_IMAGE_DEPTH will be uploaded to the computation device for subsequent processing (reme_sensor_track_position, reme_sensor_update_volume).
This method is especially useful (when compared to reme_sensor_prepare_images) when only depth and image data is required. For example when recording, there is no need for REME_IMAGE_VOLUME and it should be skipped so no time is wasted waiting for the data to be uploaded to the computation device.
- Parameters
-
c A valid context object s A valid sensor object i Image type to prepare
- Return values
-
REME_ERROR_SUCCESS On success REME_ERROR_UNSPECIFIED On failure
- Examples:
- example_reconstructmesdk_calibration.cpp, example_reconstructmesdk_image.cpp, example_reconstructmesdk_point_and_shoot_with_colors.cpp, example_reconstructmesdk_recorder.cpp, example_reconstructmesdk_recorder_update_fileformat.cpp, example_reconstructmesdk_remote_reconstruction.cpp, example_reconstructmesdk_sensor.cpp, and example_reconstructmesdk_sensor_external.cpp.
◆ reme_sensor_track_position()
| reme_error_t reme_sensor_track_position | ( | reme_context_t | c, |
| reme_sensor_t | s | ||
| ) |
Attempts to track the sensor position.
Tries to track the sensor movement by matching the current depth data against the perspective from the last position. Initially the sensor position is the identity position, unless otherwise specified.
The tracking behaviour is affected by the tracking strategy (reme_sensor_set_trackmode) and any external tracking hint (reme_sensor_set_trackhint). Any tracking hint will be cleared after calling this method.
- Parameters
-
c A valid context object s A valid sensor object
- Return values
-
REME_ERROR_SUCCESS On tracking success or the corresponding volume is empty. REME_ERROR_TRACK_LOST When the tracking did not succeed. In this case the sensor is repositioned into latest recovery pose. REME_ERROR_UNSPECIFIED is returned otherwise.
- Examples:
- example_reconstructmesdk_bust.cpp, example_reconstructmesdk_color_tracking.cpp, example_reconstructmesdk_colorize.cpp, example_reconstructmesdk_marker.cpp, example_reconstructmesdk_one_minute.cpp, example_reconstructmesdk_point_and_shoot_with_colors.cpp, example_reconstructmesdk_recorder.cpp, example_reconstructmesdk_remote_reconstruction.cpp, example_reconstructmesdk_scan_tilt.cpp, example_reconstructmesdk_sensor_external.cpp, example_reconstructmesdk_sensor_multi_independent.cpp, example_reconstructmesdk_sensor_printing.cpp, example_reconstructmesdk_sensor_threaded.cpp, example_reconstructmesdk_surface.cpp, and example_reconstructmesdk_volume.cpp.
◆ reme_sensor_update_volume()
| reme_error_t reme_sensor_update_volume | ( | reme_context_t | c, |
| reme_sensor_t | s | ||
| ) |
Update the volume using the current sensor data.
Uses the current sensor position as the perspective to update the volume. If color support is enabled this method will also update the colors. Use reme_sensor_update_volume_selectively to change that behaviour.
- Parameters
-
c A valid context object s A valid sensor object
- Return values
-
REME_ERROR_SUCCESS On success REME_ERROR_UNSPECIFIED On failure
- Examples:
- example_reconstructmesdk_bust.cpp, example_reconstructmesdk_color_tracking.cpp, example_reconstructmesdk_colorize.cpp, example_reconstructmesdk_marker.cpp, example_reconstructmesdk_one_minute.cpp, example_reconstructmesdk_point_and_shoot_with_colors.cpp, example_reconstructmesdk_recorder.cpp, example_reconstructmesdk_scan_tilt.cpp, example_reconstructmesdk_sensor_external.cpp, example_reconstructmesdk_sensor_multi_independent.cpp, example_reconstructmesdk_sensor_printing.cpp, example_reconstructmesdk_sensor_threaded.cpp, example_reconstructmesdk_surface.cpp, and example_reconstructmesdk_volume.cpp.
◆ reme_sensor_update_volume_selectively()
| reme_error_t reme_sensor_update_volume_selectively | ( | reme_context_t | c, |
| reme_sensor_t | s, | ||
| bool | update_surface, | ||
| bool | update_colors | ||
| ) |
Update the volume using the current sensor data selectively.
Uses the current sensor position as the perspective to update the volume.
- Parameters
-
c A valid context object s A valid sensor object update_surface If true updates geometric part of the volume. update_colors If true updates color part of the volume. s A valid sensor object
- Return values
-
REME_ERROR_SUCCESS On success REME_ERROR_NO_COLOR_SUPPORT When update_colors is selected but color support is disabled. REME_ERROR_UNSPECIFIED On failure
◆ reme_sensor_find_floor()
| reme_error_t reme_sensor_find_floor | ( | reme_context_t | c, |
| reme_sensor_t | s, | ||
| float * | coordinates | ||
| ) |
Detect floor plane in current sensor data.
This method attempts to detect the floor plane in the current sensor data. It uses the sensor's depth data from the last invocation of reme_sensor_prepare_images or reme_sensor_prepare_image with REME_IMAGE_DEPTH as input and if successful returns a coordinate system of the floor with respect to the sensor coordinate system.
The algorithm works best when a large portion of the image is covered by floor data and the sensor is held without roll (i.e no rotation around the sensor's z-axis). Note vertical front facing walls can be detected erroneously as floors if the make up the major part of the sensor image.
The floor is returned as a coordinate frame with the following properties:
- the origin is located at the intersection of the sensor view direction and the estimated floor plane
- the z-axis is normal to to the floor plane and points towards the natural ceiling
- the x-axis is aligned with the sensor's x-axis
- the y-axis is formed by the cross product of the former two axes.
- Parameters
-
c A valid context object s A valid sensor object coordinates A constant pointer to constant Transform data.
- Return values
-
REME_ERROR_SUCCESS On success REME_ERROR_NO_FLOOR If no floor is found in the current sensor's depth-map REME_ERROR_UNSPECIFIED On failure