metaio::IUnifeyeMobile Class Reference

The interface for all AR mobile systems. More...

#include <AS_IUnifeyeMobile.h>

List of all members.

Public Types
typedef void(*	m_pErrorCallbackfunc )(std::string, std::string)
	Function definition for the error callback.
typedef void(*	onAnimationEnd )(metaio::IUnifeyeMobileGeometry *, std::string, void *)
	Function definition for animation callback.
Public Member Functions
virtual bool	activateCamera (int index)=0
	Disabled, since his does not fully work on android.
virtual metaio::IUnifeyeBillboardGroup *	createBillboardGroup (float nearValue, float farValue)=0
	Creates or gets the billboard group object.
virtual void	displayRenderingFrameRateCounter (const bool display)=0
	Draws the current FPS on the screen.
virtual void	displayTrackingFrameRateCounter (const bool display)=0
	Draws the current tracking frame rate.
virtual void	freezeTracking ()=0
	Freeze tracking.
virtual Vector3d	get3DPositionFromScreenCoordinates (int cosID, const Vector2d &point)=0
	Converts screen coordinates to a 3D point on the XY plane.
virtual std::string	getCoordinateSystemName (int cosID)=0
	Get the name of a coordinate system if it has one (can be set via tracking data XML file).
virtual bool	getCosRelation (int baseCos, int relativeCos, metaio::Pose &relation)=0
	Measures the spatial relationship between two coordinate systems.
virtual metaio::IUnifeyeMobileGeometry *	getGeometryFromScreenCoordinates (int x, int y, const bool useTriangleTest=false)=0
	Determines the 3D geometry that is located at given screen coordinates.
virtual std::vector < metaio::IUnifeyeMobileGeometry * >	getLoadedGeometries ()=0
	Get the vector containing all loaded geometries.
virtual int	getNumberOfDefinedCoordinateSystems ()=0
	Get number of currently defined coordinate systems.
virtual int	getNumberOfValidCoordinateSystems ()=0
	Get number of currently tracked coordinate systems.
virtual void	getProjectionMatrix (float *matrix)=0
	Allows to get the OpenGL projection matrix retrieved from camera-calibration.
virtual float	getRendererFrameRate ()=0
	Get the current rendering frame rate.
virtual Vector2d	getScreenCoordinatesFrom3DPosition (int cosID, const Vector3d &point)=0
	*
virtual ImageStruct	getScreenshot ()=0
	Take a screenshot and put it into a ImageStruct.
virtual std::string	getSupportedCameraFormats ()=0
	Get the supported formats for the running video camera.
virtual float	getTrackingFrameRate ()=0
	Get the current tracking frame rate.
virtual metaio::Pose	getTrackingValues (int cosID)=0
	Allows to get the state of the tracking system for a given coordinate system.
virtual void	getTrackingValues (int cosID, float *matrix, bool preMultiplyWithStandardViewMatrix=true)=0
	Allows to get the state of the tracking system for a given coordinate system.
virtual std::vector< metaio::Pose >	getValidTrackingValues ()=0
	Get the poses of all tracked coordinate systems.
virtual bool	isOpticalTracking ()=0
	returns if current sensor is an optical tracker
virtual metaio::IUnifeyeMobileGeometry *	loadGeometry (const std::string &geoUrl)=0
	Load a 3D model from a given file.
virtual metaio::IUnifeyeMobileGeometry *	loadImageBillboard (const std::string &texturePath)=0
	Create a new image billboard object from an image file.
virtual bool	loadStandardCameraCalibration (const std::string &calibrationFile)=0
	Load standard camera calibration (as e.g.
virtual void	render (void)=0
	Performs the rendering of the scene.
virtual int	saveScreenshot (const std::string filename)=0
	Save screenshot to file.
virtual bool	setCameraFormat (int cameraFormatIndex)=0
	Sets a camera format for the running video camera.
virtual void	setCameraRotation (const int rotation)=0
	Rotates the camera image.
virtual void	setImage (const ImageStruct &image)=0
	Set an image as source from memory.
virtual void	setImageSource (const std::string &source)=0
	Set an image file as image source.
virtual void	setLLAObjectRenderingLimits (int nearLimit, int farLimit)=0
	Set the rendering limits for geometries with LLA coordinates.
virtual void	setRendererClippingPlaneLimits (float nearCP, float farCP)=0
	Sets the near and far clipping plane of the renderer.
virtual void	setSeeThrough (bool seeThrough)=0
	Toggle seethrough state of the background image.
virtual void	setSensorAccelerometer (const Vector3d &values)=0
	Tells unifeye the current accelerometer values.
virtual void	setSensorCompassAngle (float angle)=0
	Tells unifeye the current compass orientation.
virtual void	setSensorLLA (const LLACoordinate &currentPosition)=0
	Tells unifeye the current position.
virtual bool	setTrackingData (const std::string &trackingDataFile)=0
	Load a tracking configuration file.
virtual void	stopCamera ()=0
	Deactivate capturing on a camera.
virtual void	unfreezeTracking ()=0
	Un-freeze tracking.
virtual void	unloadGeometry (metaio::IUnifeyeMobileGeometry *geometry)=0
	Unload geometry with given scene ID.

---

Detailed Description

The interface for all AR mobile systems.

Date:

01-03-2009

License

This code is the property of the metaio GmbH (www.metaio.com). It is absolutely not free to be used, copied or be modified without prior written permission from metaio GmbH. The code is provided "as is" with no expressed or implied warranty. The author accepts no liability if it causes any damage to your computer, or any harm at all.

---

Member Typedef Documentation

typedef void(* metaio::IUnifeyeMobile::m_pErrorCallbackfunc)(std::string, std::string)

Function definition for the error callback.

See also:

registerErrorCallback

typedef void(* metaio::IUnifeyeMobile::onAnimationEnd)(metaio::IUnifeyeMobileGeometry *, std::string, void *)

Function definition for animation callback.

See also:

registerOnAnimationEndCallback

Parameters:

IUnifeyeMobileGeometry*	The geometry
string	Animation name
void*	context pointer

---

Member Function Documentation

virtual bool metaio::IUnifeyeMobile::activateCamera

(

int

index

)

[pure virtual]

Disabled, since his does not fully work on android.

the get last captured image.

You can get the last capture image. The image will have the dimensions of the current capture resolution.

Note: you must copy the ImageStuct::buffer, if you need it for later.

Returns:

image structure containing the image Activate capturing on a camera.

Use this to start capturing on the given camera.

Parameters:

index

The index of the camera to activate (zero based).

See also:

The index of a camera is obtained by a call to getNumberOfCamsAvailable().

You can deactivate the capturing again with stopCamera()

Returns:

true if successful, false otherwise.

virtual metaio::IUnifeyeBillboardGroup* metaio::IUnifeyeMobile::createBillboardGroup	(	float	nearValue,
		float	farValue
	)		[pure virtual]

Creates or gets the billboard group object.

Calling this function the first time will create a billboard group. Calling it again, will return the previously created object.

A billboard group takes a set of billboards and reorders them in space. All billboards within the set are placed in space relative to each other. First the billboard distance to the global origin (3d camera position) is adjusted (in the range [nearValue, farValue]; see parameters) and then the billboards are arranged in clip space that they don't overlap anymore.

Parameters:

nearValue	The minimum billboard-to-camera distance a billboard can have.
farValue	The maximum billboard-to-camera distance a billboard can have

Returns:

pointer to the new group

virtual void metaio::IUnifeyeMobile::displayRenderingFrameRateCounter

(

const bool

display

)

[pure virtual]

Draws the current FPS on the screen.

Note:

Make sure you have loaded a bitmap font before.

Parameters:

display

true if you want to enable this feature

Returns:

void

virtual void metaio::IUnifeyeMobile::displayTrackingFrameRateCounter

(

const bool

display

)

[pure virtual]

Draws the current tracking frame rate.

Note:

Make sure you have loaded a bitmap font before.

Parameters:

display

true, to enable this feature

Returns:

void

virtual void metaio::IUnifeyeMobile::freezeTracking

(

)

[pure virtual]

Freeze tracking.

Freezes the current tracking. The current tracking will be disabled and reduces CPU load. The previous tracking values will be repeated.

See also:

unfreezeTracking

virtual Vector3d metaio::IUnifeyeMobile::get3DPositionFromScreenCoordinates	(	int	cosID,
		const Vector2d &	point
	)		[pure virtual]

Converts screen coordinates to a 3D point on the XY plane.

Parameters:

cosID	coordinate system to use
point	the screen coordinate to use

Returns:

Translation containing x,y,z of the resulting 3D point

virtual std::string metaio::IUnifeyeMobile::getCoordinateSystemName

(

int

cosID

)

[pure virtual]

Get the name of a coordinate system if it has one (can be set via tracking data XML file).

Use this to find out the given name of a coordinate system according to it's ID.

Parameters:

cosID

ID of the according coordinate system.

Returns:

The name of a coordinate system.

virtual bool metaio::IUnifeyeMobile::getCosRelation	(	int	baseCos,
		int	relativeCos,
		metaio::Pose &	relation
	)		[pure virtual]

Measures the spatial relationship between two coordinate systems.

This function calculates the spatial relationship between the two given coordinate systems.

Parameters:

	baseCos	ID of coordinate system to measure from (one based).
	relativeCos	ID of coordinate system to measure to (one based).
[out]	relation	between the given baseCOS and the relativeCOS

Returns:

true if the relation could be calculated, false otherwise (e.g. if one cos did not track)

virtual metaio::IUnifeyeMobileGeometry* metaio::IUnifeyeMobile::getGeometryFromScreenCoordinates	(	int	x,
		int	y,
		const bool	useTriangleTest = false
	)		[pure virtual]

Determines the 3D geometry that is located at given screen coordinates.

Parameters:

x	x component of the screen-coordinate.
y	y component of the screen-coordinate.
useTriangleTest	Set to true if you want to perform a collision test on each triangle. Otherwise the collision check will be performed against to Bounding Box of a geometry

Returns:

the geometry, 0 if no 3D model is located at the given coordinates

virtual std::vector<metaio::IUnifeyeMobileGeometry*> metaio::IUnifeyeMobile::getLoadedGeometries

(

)

[pure virtual]

Get the vector containing all loaded geometries.

This function returns a vector containing pointers to all loaded 3D geometries.

See also:

loadGeometry to load a geometry

Returns:

vector containing pointers to all geometries

virtual int metaio::IUnifeyeMobile::getNumberOfDefinedCoordinateSystems

(

)

[pure virtual]

Get number of currently defined coordinate systems.

Use this to find out the number of coordinate systems that are currently defined.

Returns:

The number of defined COSes.

virtual int metaio::IUnifeyeMobile::getNumberOfValidCoordinateSystems

(

)

[pure virtual]

Get number of currently tracked coordinate systems.

Use this to find out the number of coordinate systems that are currently tracked.

Returns:

The number of tracked COSes.

virtual void metaio::IUnifeyeMobile::getProjectionMatrix

(

float *

matrix

)

[pure virtual]

Allows to get the OpenGL projection matrix retrieved from camera-calibration.

The values can be used to set OpenGL projection matrix such that rendered geometry will e.g. be placed on a marker/NFT-target

Parameters:

matrix

An array that will carry 16 float values forming a matrix after the execution

See also:

setStandardCameraCalibration

virtual float metaio::IUnifeyeMobile::getRendererFrameRate

(

)

[pure virtual]

Get the current rendering frame rate.

The methods returns the frame rendering performance as number of frames per second.

Returns:

the mean rendering performance as frames per second for the last 25 frames

virtual Vector2d metaio::IUnifeyeMobile::getScreenCoordinatesFrom3DPosition	(	int	cosID,
		const Vector3d &	point
	)		[pure virtual]

*

Converts a given 3D point to screen coordinates

Parameters:

cosID	coordinate system to use
point	the 3D point to convert

Returns:

a two component vector containing the screen coordinates

virtual ImageStruct metaio::IUnifeyeMobile::getScreenshot

(

)

[pure virtual]

Take a screenshot and put it into a ImageStruct.

This function works also on Android, but you don't have access to the buffer of the ImageStruct. Use saveScreenshot instead

Note, you need to free the memory assigned to ImageStruct

Returns:

returns a ImageStruct contaning the Image

virtual std::string metaio::IUnifeyeMobile::getSupportedCameraFormats

(

)

[pure virtual]

Get the supported formats for the running video camera.

Note, that in case of DirectShow cameras, the list may not contain all possible resolutions and frame rates, as, depending on the DirectShow driver/capture filter, resolution and framerate may be altered in discrete steps from a minimum up to a maximum value. For DirectShow cameras it is best to use showPinPropertiesOnActivatedCamera() to show and alter the formats supported by the camera.

Returns:

A string containing all supported formats as "0: 320x240_RGB565 ..."

See also:

getCurrentCameraFormat

setCameraFormat

virtual float metaio::IUnifeyeMobile::getTrackingFrameRate

(

)

[pure virtual]

Get the current tracking frame rate.

The methods returns the frame processing performance as number of frames per second.

Returns:

the mean processing performance as frames per second for the last 25 frames

virtual metaio::Pose metaio::IUnifeyeMobile::getTrackingValues

(

int

cosID

)

[pure virtual]

Allows to get the state of the tracking system for a given coordinate system.

Parameters:

cosID

The id of the coordinate system, the values should be retrieved for (one based).

Returns:

A Pose structure containing the tracking values for the cos

virtual void metaio::IUnifeyeMobile::getTrackingValues	(	int	cosID,
		float *	matrix,
		bool	preMultiplyWithStandardViewMatrix = true
	)		[pure virtual]

Allows to get the state of the tracking system for a given coordinate system.

The values can be used to set OpenGL ModelView matrix such that rendered geometry will e.g. be placed on a marker/NFT-target. If setCameraRotation() was used, this method will return a accordingly rotated matrix.

Parameters:

cosID	The id of the coordinate system, the values should be retrieved for (one based).
matrix	An array that will carry 16 float values forming a matrix after the execution
preMultiplyWithStandardViewMatrix	bool specifying if model matrix should be pre-multiplied with metaio's standard ViewMatrix to finally form a ModelView matrix for OpenGL

virtual std::vector< metaio::Pose > metaio::IUnifeyeMobile::getValidTrackingValues

(

)

[pure virtual]

Get the poses of all tracked coordinate systems.

Returns:

std::vector<metaio::Pose> the valid poses

virtual bool metaio::IUnifeyeMobile::isOpticalTracking

(

)

[pure virtual]

returns if current sensor is an optical tracker

Returns:

true if current sensor is an optical tracker

virtual metaio::IUnifeyeMobileGeometry* metaio::IUnifeyeMobile::loadGeometry

(

const std::string &

geoUrl

)

[pure virtual]

Load a 3D model from a given file.

This function loads a 3D geometry from the given file. You can unload the geometry again with unloadGeometry(). Supported 3D formats are OBJ and MD2. To add shadow to an MD2 model, you can place a shadow model (i.e. a plane with a transparent PNG texture) into the same directory as the MD2 model, having the same filename with '_shadow' attached. (e.g. model.md2 + model_shadow.md2)

See also:

unloadGeometry to unload a geometry.

Parameters:

geoUrl

path to the geometry file.

Returns:

Pointer to the geometry. 0 If not successful.

virtual metaio::IUnifeyeMobileGeometry* metaio::IUnifeyeMobile::loadImageBillboard

(

const std::string &

texturePath

)

[pure virtual]

Create a new image billboard object from an image file.

Parameters:

texturePath

the path to the billboard

Returns:

new geometry instance for the object

virtual bool metaio::IUnifeyeMobile::loadStandardCameraCalibration

(

const std::string &

calibrationFile

)

[pure virtual]

Load standard camera calibration (as e.g.

created by Sextant).

Parameters:

calibrationFile

Full path to the calibration file.

Returns:

true if successful, false otherwise

virtual void metaio::IUnifeyeMobile::render

(

void

)

[pure virtual]

Performs the rendering of the scene.

This method is usually called from the application loop. It takes care of capturing, tracking and rendering.

virtual int metaio::IUnifeyeMobile::saveScreenshot

(

const std::string

filename

)

[pure virtual]

Save screenshot to file.

Currently BMP file type is supported.

Parameters:

filename

the filename to store the image

Returns:

int 0 if everything went fine

virtual bool metaio::IUnifeyeMobile::setCameraFormat

(

int

cameraFormatIndex

)

[pure virtual]

Sets a camera format for the running video camera.

Parameters:

cameraFormatIndex

the index of the desired camera format as determined by getSupportedCameraFormats

Returns:

true if successful, false otherwise.

See also:

getSupportedCameraFormats()

getCurrentCameraFormat()

virtual void metaio::IUnifeyeMobile::setCameraRotation

(

const int

rotation

)

[pure virtual]

Rotates the camera image.

This function is needed for some phones, which have the camera built in rotated, like the TG01

The parameter can be 0: no rotation, display as it is 1: rotate by 90 degrees (e.g. TG01) 2: rotate by 180 degrees 3: rotate by 270 degrees

Note: This function is not supported yet for pixmap textures.

Parameters:

rotation

Returns:

void

virtual void metaio::IUnifeyeMobile::setImage

(

const ImageStruct &

image

)

[pure virtual]

Set an image as source from memory.

This method is used to set the image source for optical tracking.

Parameters:

image

the image structure containing the image data

virtual void metaio::IUnifeyeMobile::setImageSource

(

const std::string &

source

)

[pure virtual]

Set an image file as image source.

This method is used to set the image source for display and (optical) tracking. The image source can be any string representing a fully qualified path to an image file e.g. "c:\image\1.jpg"

Parameters:

source

A fully qualified path to an image file.

virtual void metaio::IUnifeyeMobile::setLLAObjectRenderingLimits	(	int	nearLimit,
		int	farLimit
	)		[pure virtual]

Set the rendering limits for geometries with LLA coordinates.

The near limit will ensure that all objects closer than this limit are pushed back to the near limit. The far limit will ensure that all objects farther away than this limit are pulled forward to the far limit.

This is especially helpful for billboards. The same limits are also applied to 3D content, but in this case 10*farLimit;

Parameters:

nearLimit	the near limit or 0 to disable
farLimit	the far limit or 0 disable

See also:

setLLALimitsEnabled

virtual void metaio::IUnifeyeMobile::setRendererClippingPlaneLimits	(	float	nearCP,
		float	farCP
	)		[pure virtual]

Sets the near and far clipping plane of the renderer.

Parameters:

nearCP	near clipping plane in millimeters.
farCP	far clipping plane in millimeters.

virtual void metaio::IUnifeyeMobile::setSeeThrough

(

bool

seeThrough

)

[pure virtual]

Toggle seethrough state of the background image.

Use this if you want the background image not being displayed. "seethrough" means that you see through, i.e. do not see, the background image. This is useful e.g. when setting an OpenGL view transparent and overlaying it on another view.

Parameters:

seeThrough

Whether seethrough should be enabled (1) or not (0).

virtual void metaio::IUnifeyeMobile::setSensorAccelerometer

(

const Vector3d &

values

)

[pure virtual]

Tells unifeye the current accelerometer values.

These need to be set for GPS, Compass, Sensor sources.

Parameters:

values

the current accelerometer values

virtual void metaio::IUnifeyeMobile::setSensorCompassAngle

(

float

angle

)

[pure virtual]

Tells unifeye the current compass orientation.

In order to use GPS based sensor sources Unifeye needs to know the current compass angle. This method has to be used to update the current compass orientation in Unifeye.

Parameters:

angle

the current compass angle. The value 0 means the device is pointed toward true north, 90 means it is pointed due east, 180 means it is pointed due south, and so on. A negative value indicates that the heading could not be determined.

virtual void metaio::IUnifeyeMobile::setSensorLLA

(

const LLACoordinate &

currentPosition

)

[pure virtual]

Tells unifeye the current position.

In order to use GPS based sensor sources Unifeye needs to know the current position. This method has to be used to update the current GPS position in Unifeye

Parameters:

currentPosition

the current LLA position

virtual bool metaio::IUnifeyeMobile::setTrackingData

(

const std::string &

trackingDataFile

)

[pure virtual]

Load a tracking configuration file.

Use this to configure the tracking world including sensors, sensor parameters and coordinate systems.

Parameters:

trackingDataFile

Fully qualified path of the file that should be loaded.

Returns:

true, if successful. false otherwise

virtual void metaio::IUnifeyeMobile::stopCamera

(

)

[pure virtual]

Deactivate capturing on a camera.

Use this to stop capturing on the current camera.

See also:

Start capturing using activateCamera ( index )

virtual void metaio::IUnifeyeMobile::unfreezeTracking

(

)

[pure virtual]

Un-freeze tracking.

Un-freezes the current tracking. The current tracking will be enabled again.

See also:

freezeTracking

virtual void metaio::IUnifeyeMobile::unloadGeometry

(

metaio::IUnifeyeMobileGeometry *

geometry

)

[pure virtual]

Unload geometry with given scene ID.

Use this function if you want to unload a geometry. If you do not want to unload the geometry but hide it, use setVisible() instead.

Parameters:

geometry

ID of the geometry to be unloaded.

See also:

loadGeometry to load geometries.

setVisible in case you want to hide a geometry.