Mavis API

Mavis API

The API for communicating with mavis is available through mavisclient.dll. The function prototypes and data-type definitions that mavisclient.dll uses are in maviscomm.h. For a description of each mavis capability and an explanation of how to use it, see Mavis Capabilities.

Function Summary

int getFrame(BYTE * buf, int nBytes)
             Gets the next video frame

int getFrameSize(FrameSize_t * pfs)
             Gets the video-frame dimensions

int getTiltAngle(double * pAngle)
             Retrieves the value mavis is currently using for camera tilt angle

int locateHLines(int d, HLineOrder_t ordering, HLineMetadata_t * phlm)
             Locates line segments that are horizontal in 3D space

int lookOnce(ObjID_t objId, ObjLoc_t * pObjLoc)
             Captures one video frame and examines it for the requested object

int nextLine(HLine_t * pLine)
             Retrieves data for one 3D line segment

int setTiltAngle(double angle)
             Updates the value for camera tilt angle in mavis

int startLookUntilSighted(ObjID_t objId, ObjLoc_t * pObjLoc, DWORD timeout)
             Repeats lookOnce() without returning until the object is sighted or a stop condition is met

int startRawFeed()
             Toggles live frame feed on

int stopLookUntilSighted()
             Forces a return from startLookUntilSighted()

int stopRawFeed()
             Toggles live frame feed off

Data Type Summary

DataRange_t struct
             High and low values for a result

FrameSize_t struct
             Video-frame dimensions

HLine_t struct
             Information about one H-Line

HLineOrder_t enum
             Tells mavis how to order the list of H-Lines

HLineMetadata_t struct
             Metadata about the H-Line analysis

HLineType_t enum
             The type of H-Line

ObjID_t enum
             Predefined IDs for hardcoded objects

ObjLoc_t struct
             The result of looking for an object

Function Detail

getFrame

int getFrame(BYTE * buf, int nBytes)

Gets the next video frame.

This function and getFrameSize() are provided so video data can be forwarded from mavis to another application without having to close mavis. Call getFrameSize() first to get the video-frame dimensions. Then allocate a buffer of size FrameSize_t.nBufSize for the frame data.

The format for frame data is a packed byte array. There are three bytes per pixel. The first byte is the blue value, second is green, third is red. Pixels are ordered row by row, starting at the bottom of the image. This is how video frames arrive from framecap. They're passed on unaltered for speed and to conserve shared memory. The utility library bmpUtils.dll, provided in the mavis download, has a function for expanding the packed video data into an RGB array.

Parameters:

BYTE * buf
buffer to hold the bitmap data for the video frame

int nBytes
buffer size

Returns:

-1 if an error occurred
0 otherwise

getFrameSize

int getFrameSize(FrameSize_t * pfs)

Gets the video-frame dimensions.

This function and getFrame() are provided so video data can be forwarded from mavis to another application without having to close mavis.

Parameters:

FrameSize_t * pfs
video-frame dimensions

Returns:

-1 if an error occurred
0 otherwise

getTiltAngle

int getTiltAngle(double * pAngle)

Retrieves the value mavis is currently using for camera tilt angle.

Mavis uses this value to compute distances.

Parameters:

double * pAngle
the tilt angle

Returns:

-1 if an error occurred
0 otherwise

locateHLines

int locateHLines(int d, HLineOrder_t ordering, HLineMetadata_t * phlm)

Locates line segments that are horizontal in 3D space.

The first call to this function should use d=0. Subsequent calls with a non-zero value for d tell mavis to use the current frame plus the previous frame to compute distances to matching line segments. To start a new series, pass d=0 again. When this method returns from any call except the first in a series, the fields in HLineMetadata_t will be set.

Data for individual line segments are retrieved by calling nextLine().

Parameters:

int d
distance traveled since the previous frame, in mm

HLineOrder_t ordering
specifies the order in which lines are to be returned by nextLine()

HLineMetadata_t * phlm
results from mavis

Returns:

-1 if an error occurred
0 otherwise

lookOnce

int lookOnce(ObjID_t objId, ObjLoc_t * pObjLoc)

Captures one video frame and examines it for the requested object.

Parameters:

ObjID_t objId
ID of the object to look for

ObjLoc_t * pObjLoc
results from mavis

Returns:

-1 if an error occurred
0 otherwise

nextLine

int nextLine(HLine_t * pLine)

Retrieves data for one 3D line segment.

Each time it's called, this function fetches data for the next 3D line segment and returns the number of line segments remaining. After the last line segment has been fetched, subsequent calls return -1, and the last line segment's data are repeated.

Parameters:

HLine_t * pLine
the line-segment data from mavis

Returns:

the number of line segments remaining, or -1

setTiltAngle

int setTiltAngle(double angle)

Updates the value for camera tilt angle in mavis.

If the camera's tilt angle changes, call this method to tell mavis the camera's new tilt angle. For a camera that's tilted down, tilt angle should be negative. Mavis uses the tilt angle to compute distances.

Parameters:

double angle
the new tilt angle

Returns:

-1 if an error occurred
0 otherwise

startLookUntilSighted

int startLookUntilSighted(ObjID_t objId, ObjLoc_t * pObjLoc, DWORD timeout)

Repeats lookOnce() without returning until the object is sighted or a stop condition is met.

This function blocks until one of the following occurs:
  * The object is sighted
  * Another thread calls stopLookUntilSighted()
  * The timeout interval elapses

Parameters:

ObjID_t objId
ID of the object to look for

ObjLoc_t * pObjLoc
results from mavis

DWORD timeout
timeout interval, in ms. (The Windows value INFINITE can also be used here.)

Returns:

-1 if an error occurred
0 otherwise

startRawFeed

int startRawFeed()

Toggles live frame feed on.

Causes live video feed to display in the visual feedback window on MavisCtl. Calling stopRawFeed() (or sending a command to mavis) will terminate the live feed.

stopLookUntilSighted

int stopLookUntilSighted()

Forces a return from startLookUntilSighted().

Since startLookUntilSighted() blocks, this function must be called from a separate thread.

stopRawFeed

int stopRawFeed()

Toggles live frame feed off.

If live feed hasn't been started, calling this function has no effect.

Data Type Detail

DataRange_t

typedef struct DataRange_t

High and low values for a result.

Fields:

double lo
lower bound for the estimated range of a value

double hi
upper bound for the estimated range of a value

FrameSize_t

typedef struct FrameSize_t

Video-frame dimensions.

Fields:

int height
image height

int width
image width

int nBufSize
number of bytes needed to hold the frame buffer

int nPixels
number of pixels in each frame

HLine_t

typedef struct HLine_t

Information about one H-Line

Fields:

DataRange_t distance
travel distance to line along robot's current path, in mm

DataRange_t height
height of line, in mm

DataRange_t angle
angle robot needs to pivot to be facing the line, in degrees (cw is pos, ccw neg)

HLineType_t lineType
the type of H-Line

double pctError
estimated error based on data's self consistency

BOOL inPathVis
indicates whether the intersection of the line segment with the robot's path was visible in the image

int inPathProb
a likelihood estimate for whether the 3D line segment crosses the robot's path

HLineOrder_t

typedef enum HLineOrder_t

Tells mavis how to order the list of H-Lines.

Elements:

      HL_UNORDERED      =   0
      HL_DISTANCE_LO2HI = 0x1
      HL_DISTANCE_HI2LO = 0x9
      HL_HEIGHT_LO2HI   = 0x3
      HL_HEIGHT_HI2LO   = 0xb

HLineMetadata_t

typedef struct HLineMetadata_t

Metadata about the H-Line analysis

Sometimes it will be possible to estimate whether the robot has pivoted while moving forward. When mavis can make this estimate, it will set the pivotWasEstimated flag and fill the estPivotAmount field.

Fields:

int nLines
number of 3D horizontal line segments located

double quality
quality of the observations - not yet implemented

BOOL pivotWasEstimated
flag for the estPivotAmount field

double estPivotAmount
estimate of robot's pivot error

HLineType_t

typedef enum HLineType_t

The type of H-Line.

In the image, a line will appear as lighter on one side and darker on the other. Only lines that are more horizontal than vertical in the image are considered for H-Lines. So only two line types are needed. GVPOS lines have a positive vertical gradient - they're lighter on top. GVNEG lines are darker on top. This information can be useful for mapping, since it helps distinguish lines from one another.

Elements:

      GVPOS = 0
      GVNEG = 1

ObjID_t

typedef enum ObjID_t

Predefined IDs for hardcoded objects.

Elements:

      INVALID_OBJ_ID  = -1
      HOMEBASE_OBJ_ID =  3
      MOTION_OBJ_ID   =  5

ObjLoc_t

typedef struct ObjLoc_t

The outcome of looking for an object.

Fields:

double angle
heading to reach the object, degrees (cw is pos, ccw neg)

double dist
object's estimated distance from robot, mm

int prob
a confidence level for the sighting (0 means no sighting)

int movFlag
a flag indicating a move is needed for a better view

double movAngle
heading for the move

double movDist
distance to move

Home | Mavis | Mavis Documentation