PointCloud.h File Reference

Public API for libpointcloud. More...

Go to the source code of this file.

Data Structures
struct	pointcloud_context
	Camera video frame and viewport info. More...
struct	pointcloud_matrix_4x4
	A 4x4 matrix of floats. More...
struct	pointcloud_vector_2
	2D point. More...
struct	pointcloud_vector_3
	3D point. More...
struct	pointcloud_point_cloud
	A point cloud, i.e. More...
struct	pointcloud_image_target
	A target image. More...
struct	pointcloud_image_targets
	A list of target images. More...

Enumerations
enum	pointcloud_state {   POINTCLOUD_NOT_CREATED, POINTCLOUD_WAITING_FOR_CAMERA_FRAMES, POINTCLOUD_IDLE, POINTCLOUD_INITIALIZING,   POINTCLOUD_TRACKING_SLAM_MAP, POINTCLOUD_RELOCALIZING, POINTCLOUD_LOOKING_FOR_IMAGES, POINTCLOUD_TRACKING_IMAGES }
	System state codes. More...
enum	pointcloud_video_format { POINTCLOUD_RGB_565, POINTCLOUD_NV21, POINTCLOUD_BGRA_8888, POINTCLOUD_GRAY_8 }
	Camera video formats. More...

Functions
void	pointcloud_create (int viewport_width, int viewport_height, int video_width, int video_height, pointcloud_video_format video_format, const char *device, const char *app_key)
	Initialize the pointcloud system.
void	pointcloud_destroy ()
	Destroy the pointcloud system.
void	pointcloud_on_camera_frame (char *data, double timestamp)
	Analyze a camera frame.
void	pointcloud_on_accelerometer_update (float x, float y, float z, double timestamp)
	Notify the system of accelerometer data updates.
void	pointcloud_on_device_motion_update (float x, float y, float z, float rot_x, float rot_y, float rot_z, float g_x, float g_y, float g_z, double timestamp)
	Notify the system of user acceleration, rotation rate and gravity updates.
void	pointcloud_start_slam ()
	Start the initialization process.
void	pointcloud_reset ()
	Stop tracking or initialization and reset to an idle state.
void	pointcloud_enable_map_expansion ()
	Enabling map expansion will create an expanding SLAM map.
void	pointcloud_disable_map_expansion ()
	Stops any ongoing map expansion.
void	pointcloud_add_image_target (const char *image_id, const char *file_path, float physical_width, float physical_height)
	Add a reference image to the system.
void	pointcloud_remove_image_target (const char *image_id)
	Remove a reference image from the system.
void	pointcloud_activate_image_target (const char *image_id)
	Activate a reference image.
void	pointcloud_deactivate_image_target (const char *image_id)
	Deactivate a reference image.
void	pointcloud_save_current_map (const char *file_path)
	Save the current 3d map to disk.
void	pointcloud_load_map (const char *file_path)
	Load a 3d map from disk.
pointcloud_context	pointcloud_get_context ()
	Get the viewport and video context.
pointcloud_state	pointcloud_get_state ()
	Get the current system state.
int	pointcloud_get_point_cloud_revision ()
	Get the current revision of the point cloud.
int	pointcloud_point_cloud_size ()
	Get number of points in the point cloud.
pointcloud_point_cloud *	pointcloud_get_points ()
	Get a copy of the point cloud used when tracking.
void	pointcloud_destroy_point_cloud (pointcloud_point_cloud *points)
	Destroy a point cloud copy.
pointcloud_matrix_4x4	pointcloud_get_camera_matrix ()
	Get a copy of the current camera matrix.
pointcloud_matrix_4x4	pointcloud_get_camera_pose ()
	Get a copy of the current camera pose matrix.
pointcloud_vector_3	pointcloud_get_gravity_vector ()
	Get a vector representing the gravity direction.
pointcloud_image_targets	pointcloud_get_tracked_images ()
	Get the currently tracked images.
pointcloud_matrix_4x4	pointcloud_get_frustum (float near, float far)
	Get a OpenGL compatible view frustum matrix.
pointcloud_vector_3	pointcloud_video_to_camera (float x, float y)
	Unproject a 2d video coordinate to a camera relative 3d coordinate.
pointcloud_vector_2	pointcloud_camera_to_video (float x, float y, float z)
	Project a camera relative 3d coordinate to a 2d video coordinate.
pointcloud_vector_3	pointcloud_camera_to_map (float x, float y, float z)
	Transform a 3d coordinate relative to the current camera into a map 3d coordinate.
pointcloud_vector_3	pointcloud_map_to_camera (float x, float y, float z)
	Transform a map 3d coordinate into a coordinate relative to the current camera.
pointcloud_vector_2	pointcloud_video_to_viewport (float x, float y)
	Transform a 2d video coordinate to a 2d viewport coordinate.
pointcloud_vector_2	pointcloud_viewport_to_video (float x, float y)
	Transform a 2d viewport coordinate to a 2d video coordinate.

Detailed Description

Public API for libpointcloud.

Copyright 2012 13th Lab AB. All rights reserved.

The terms and condition for libpointcloud can be found in the LICENSE folder of the libpointcloud download, or at http://developer.pointcloud.io/sdk/termsofuse

Enumeration Type Documentation

enum pointcloud_state

System state codes.

Enumerator:

POINTCLOUD_NOT_CREATED	System not created: pointcloud_create() has not been called yet.
POINTCLOUD_WAITING_FOR_CAMERA_FRAMES	No valid camera frames have been received in pointcloud_on_camera_frame().
POINTCLOUD_IDLE	System is ready and waiting for instructions.
POINTCLOUD_INITIALIZING	SLAM intitialization process is running.
POINTCLOUD_TRACKING_SLAM_MAP	System is tracking a SLAM map.
POINTCLOUD_RELOCALIZING	Tracking is lost, trying to relocalize.
POINTCLOUD_LOOKING_FOR_IMAGES	Looking for images.
POINTCLOUD_TRACKING_IMAGES	Tracking images.

enum pointcloud_video_format

Camera video formats.

Enumerator:

POINTCLOUD_RGB_565	16 bit RGB 565
POINTCLOUD_NV21	12 bit NV21 Planar YUV 4:2:0
POINTCLOUD_BGRA_8888	32 bit RGBA 8888
POINTCLOUD_GRAY_8	8 bit grayscale

Function Documentation

void pointcloud_create	(	int	viewport_width,
		int	viewport_height,
		int	video_width,
		int	video_height,
		pointcloud_video_format	video_format,
		const char *	device,
		const char *	app_key
	)

Initialize the pointcloud system.

This needs to be done before calling any other methods.

Parameters

viewport_width	The width of the viewport the camera frame is projected on
viewport_height	The height of the viewport the camera frame is projected on
video_width	The width of a camera frame
video_height	The height of a camera frame
video_format	The format of the camera frame data
device	The device type
app_key	The developer key for the application. This is generated on http://developer.pointcloud.io and is specific to each application using PointCloud SDK

void pointcloud_on_camera_frame	(	char *	data,
		double	timestamp
	)

Analyze a camera frame.

Call this on on each frame.

Parameters

data	The camera frame pixel data
timestamp	Timestamp (in seconds) of video frame

void pointcloud_on_accelerometer_update	(	float	x,
		float	y,
		float	z,
		double	timestamp
	)

Notify the system of accelerometer data updates.

Parameters

x,y,z	The acceleration
timestamp	Timestamp (in seconds) of acceleration update

void pointcloud_on_device_motion_update	(	float	x,
		float	y,
		float	z,
		float	rot_x,
		float	rot_y,
		float	rot_z,
		float	g_x,
		float	g_y,
		float	g_z,
		double	timestamp
	)

Notify the system of user acceleration, rotation rate and gravity updates.

Parameters

x,y,z	The user acceleration
rot_x,rot_y,rot_z	The rotation rate
g_x,g_y,g_z	The gravity direction
timestamp	Timestamp (in seconds) of device motion update

void pointcloud_start_slam

(

)

Start the initialization process.

The user should move the device slowly left/right, up/down, in/out until a SLAM map has been created.

void pointcloud_reset

(

)

Stop tracking or initialization and reset to an idle state.

This will destroy the current point cloud.

void pointcloud_enable_map_expansion

(

)

Enabling map expansion will create an expanding SLAM map.

This way you can initialize a SLAM map from an image target. This is enabled by default when pointcloud_start_slam() is called.

void pointcloud_disable_map_expansion

(

)

Stops any ongoing map expansion.

Freezes the current map.

void pointcloud_add_image_target	(	const char *	image_id,
		const char *	file_path,
		float	physical_width,
		float	physical_height
	)

Add a reference image to the system.

Note that you need to activate the image (pointcloud_activate_image_target) if you want the system to detect it. The physical size of the reference image will define the scale of the SLAM coordinates.

Parameters

image_id	user-defined image id
file_path	path to the file containing the image model
physical_width,physical_height	physical size of the image. Only one of these parameters need to be defined (the other can be set to 0).

void pointcloud_remove_image_target

(

const char *

image_id

)

Remove a reference image from the system.

Parameters

image_id

user-defined image id

void pointcloud_activate_image_target

(

const char *

image_id

)

Activate a reference image.

Tell the system to detect and track a reference image.

Parameters

image_id

user-defined image id

void pointcloud_deactivate_image_target

(

const char *

image_id

)

Deactivate a reference image.

Tell the system to stop detecting or tracking a reference image.

Parameters

image_id

user-defined image id

void pointcloud_save_current_map

(

const char *

file_path

)

Save the current 3d map to disk.

Parameters

file_path

path to the file to save the map to

void pointcloud_load_map

(

const char *

file_path

)

Load a 3d map from disk.

Parameters

file_path

path to the file containing the saved map

pointcloud_context pointcloud_get_context

(

)

Get the viewport and video context.

Returns

The viewport and video contex

pointcloud_state pointcloud_get_state

(

)

Get the current system state.

Returns

The current system state

int pointcloud_get_point_cloud_revision

(

)

Get the current revision of the point cloud.

Returns

The current point cloud revision number

int pointcloud_point_cloud_size

(

)

Get number of points in the point cloud.

Returns

The number of points in the point cloud

pointcloud_point_cloud* pointcloud_get_points

(

)

Get a copy of the point cloud used when tracking.

The copy is only valid during tracking or relocalization states. Make sure to do pointcloud_destroy_point_cloud() on the point cloud after you are done using it.

Returns

A copy of the point cloud

void pointcloud_destroy_point_cloud

(

pointcloud_point_cloud *

points

)

Destroy a point cloud copy.

This will not affect the internal system point cloud. Always call this after you are finished using a point cloud.

Parameters

points

The point cloud copy to destroy.

pointcloud_matrix_4x4 pointcloud_get_camera_matrix

(

)

Get a copy of the current camera matrix.

The result is only valid during the tracking states. The camera matrix describes the transform from 3D map space to 3D camera space. The camera matrix is the inverse of the camera pose matrix.

Returns

The camera matrix (4x4) represented as an array of 16 floats in column major order

pointcloud_matrix_4x4 pointcloud_get_camera_pose

(

)

Get a copy of the current camera pose matrix.

The matrix is only valid during the tracking states. The camera pose matrix represents the current position and rotation of the device camera in the map space. The camera pose matrix is the inverse of the camera matrix.

Returns

The camera pose matrix (4x4) represented as an array of 16 floats in column major order.

pointcloud_vector_3 pointcloud_get_gravity_vector

(

)

Get a vector representing the gravity direction.

The result is only valid when there is a map.

Returns

the gravity vector

pointcloud_image_targets pointcloud_get_tracked_images

(

)

Get the currently tracked images.

Returns

the currently tracked images, or an empty pointcloud_image_targets if no image is tracked.

pointcloud_matrix_4x4 pointcloud_get_frustum	(	float	near,
		float	far
	)

Get a OpenGL compatible view frustum matrix.

The function calculates a view frustum matrix compatible with the video feed when clipped according to the result of pointcloud_get_video_clipping().

Parameters

near,far

clipping planes

Returns

4x4 column major matrix of floats

pointcloud_vector_3 pointcloud_video_to_camera	(	float	x,
		float	y
	)

Unproject a 2d video coordinate to a camera relative 3d coordinate.

Parameters

x,y	video coordinate

Returns

a unprojected point in camera relative 3d coordinate

pointcloud_vector_2 pointcloud_camera_to_video	(	float	x,
		float	y,
		float	z
	)

Project a camera relative 3d coordinate to a 2d video coordinate.

Parameters

x,y,z

camera relative 3d coordinate

Returns

a projected point in video coordinate

pointcloud_vector_3 pointcloud_camera_to_map	(	float	x,
		float	y,
		float	z
	)

Transform a 3d coordinate relative to the current camera into a map 3d coordinate.

Parameters

x,y,z

camera relative 3d coordinate

Returns

a 3d map coordinate

pointcloud_vector_3 pointcloud_map_to_camera	(	float	x,
		float	y,
		float	z
	)

Transform a map 3d coordinate into a coordinate relative to the current camera.

Parameters

x,y,z

3d map coordinate

Returns

a camera relative 3d coordinate

pointcloud_vector_2 pointcloud_video_to_viewport	(	float	x,
		float	y
	)

Transform a 2d video coordinate to a 2d viewport coordinate.

Parameters

x,y	video coordinate

Returns

a 2d viewport coordinate

pointcloud_vector_2 pointcloud_viewport_to_video	(	float	x,
		float	y
	)

Transform a 2d viewport coordinate to a 2d video coordinate.

Parameters

x,y	2d viewport coordinate

Returns

a 2d video coordinate