untitled

TrackThemColors specs

Starting the video flow.

In order to access the video stream, the Xtra has to establish a connection with the video capture device and allocate memory. None of the other methods in this Xtra will work without calling the InitVideo() first. You should call the InitVideo() method only once, and be sure to call CleanUp() before you leave.

The InitVideo(TrackObj, Width, height, source) method takes four arguments:

TrackObj - The instance number returned from New().

Height - defines the height in Pixels of the video frame you want.

Width - defines the width in Pixels of the video frame you want.

source - defines the video digitizer that will be used. In most cases use 1. If you have more than one video digitezers installed in your computer (for example an AV board and a connectix camera) than you can specify 2 for the second 3 for the third... If you specify a number larger than the number of video digitizers in the computer it will default to the first.

The smaller the video frame the better the performance of the Xtra.

Stopping the video flow.

Once you are done tracking, you should call the CleanUp() method. Do not attempt to call InitVideo() again without calling the CleanUp() first.

The CleanUp(TrackObj) method takes one argument.

TrackObj - The instance number returned from New().

Opening the Video Settings dialog box

To open the standard Video Settings dialog box which allows you to change the video source or change the parameters for your camera, use the VideoSettings() method. This is very useful for changing the brightness, saturation and contrast of the video to create better conditions for the tracking.
The VideoSettings(TrackObj) takes one argument.

TrackObj - The instance number returned from New().

Viewing the video source on stage

To View the video source on the screen you should call ShowVideo()

The ShowVideo(TrackObj) method takes three arguments.

TrackObj - The instance number returned from New().

horizontal - The location in pixels of the left side of the frame.

vertical - The location in pixels of the top of the frame.

Please note that the ShowVideo() method should be called repeatedly, to get a continuously changing display of the video source.

The ShowVideo() method returns a list containing 3 numbers.

[red, green, blue] these numbers are the color value of the Pixel directly under the mouse the numbers go from 0 - 255 . This feature is useful for determining the color value of specific elements in the video, in order to track them later.

Grabbing a video frame to a cast member

You can use the Xtra to grab frames from the video to a cast member. This is useful for creating background images for visualizing the tracking and for other purposes.

To grab a video frame to a cast member use the GrabToCast() method.

The GrabToCast (TrackObj, CastMemberNum) takes two parameters.

TrackObj - The instance number returned from New().

CastMemberNum - The number of the cast member to which you wish to grab the frame. (Have an Image cast member waiting in that location)

Tracking the brightest point

To track the brightest point in the video source, call the FollowOneLight() method.
The FollowOneLight(TrackObj) method takes one argument.

TrackObj - The instance number returned from New().

The FollowOneLight() method returns a list containing 2 numbers [Horizontal, Vertical].

Horizontal. The horizontal placement, in pixels, of the brightest point . The value of this number is between 0 and the width of the video source as defined in the InitVideo() method

Vertical. The vertical placement, in pixels, of the brightest point . The value of this number is between 0 and the height of the video source as defined in the InitVideo() method.

Tracking multiple locations of a specific color.

To track more than one point of a specific color you should call the FollowThisColorPoints() method
The FollowThisColorPoints(TrackObj, tolerance, size, red, green, blue) takes seven arguments.

TrackObj - The instance number returned from New().

tolerance - A number between 0 and 765 defining how close does a pixel in the video have to be in order to be considered a match. (the larger the number the more points will be returned)

Size - A number defining how far can two points be from each other and still be considered as one point (the larger the number the less points will be returned)

red - An integer between 0-255 defining the red value of the color to be tracked.

green - An integer between 0-255 defining the green value of the color to be tracked.

blue - an integer between 0-255 defining the blue value of the color to be tracked.

The FollowThisColorPoints() method returns a list containing two numbers for each point found. [Horizontal, Vertical, Horizontal, Vertical...].

Horizontal. The horizontal location, in pixels, of the point . The value of this number is between 0 and the width of the video source as defined in the InitVideo() method.

Vertical. The vertical placement, in pixels, of the point . The value of this number is between 0 and the height of the video source as defined in the InitVideo() method.

Tracking many specific colors

To track specific colors of interest in the video source use the FollowMyColors() method. this method will look for the points in the video most similar to the colors you define.

The FollowMyColors(TrackObj, How Many, Colorstring) takes three arguments

TrackObj - The instance number returned from New().

HowMany - a number defining the number of colors you are interested in tracking.

ColorString - a string containing the color values of the colors you wish to track. For each color you must attach it's value in red green and blue. Since the Xtra expects a string you must use NumToChar() to convert your numbers into characters. For example to track the color Red (255,0,0)
use:
put NumToChar(255) into ColorString
put NumToChar(255) after ColorString
put NumToChar(255) after ColorString

all the values for all the colors must be appended into one long string.

The FollowMyColors() method returns a list containing two numbers for each color tracked in the order you specified them. [Horizontal, Vertical, Horizontal, Vertical...].

Horizontal. The horizontal location, in pixels, of the pixel closest to the color you requested . The value of this number is between 0 and the width of the video source as defined in the InitVideo() method.

Vertical. The vertical location, in pixels, of the pixel closest to the color you requested. The value of this number is between 0 and the height of the video source as defined in the InitVideo() method.

Be sure to specify all the color values for the number of colors you asked to be tracked. The maximum number of colors that can be successfully tracked is not set and changes from machine to machine. I have successfully tracked 17 different colors.

Tracking change in the video over time

To track changes in the video between frames, use the FollowTheChange() method. This method looks for differences between the current frame and either the previous frame or a reference frame. A typical application for a reference frame would be to make a reference frame of an empty room and then any person or object would be considered change, even if they are not moving. If in the same environment you would track change from frame to frame, only objects that are in motion would show up.

The FollowTheChange(TrackObj, change, fromRefrence, padding) takes four parameter:

TrackObj - The instance number returned from New().

change - A number between 0 - 442 . The xtra will not consider as change any difference under the specified value.(The smaller the number the more sensitive to change the result).

fromRefrence - 0 -compare this frame to the previous frame. 1 - Compare this frame to a reference frame (use Remember() to define a reference frame, see below) .

padding - a number defining the padding around each pixel of change. Adding padding reduces the number of rects returned and reduces noise)

The FollowTheChange method groups neighboring pixels into rects and returns the rects in a list: [rect1, rect2, rect3...] with as many rects as were found in the video.

Following patterns in the video - Overview.

To follow patterns in the video, use the FollowAreas() method. Sometimes it is useful to track not a particular color , but a particular arrangement of pixels (an eye, ear, car). To do so you must supply the Xtra with a reference frame to compare using the Remember() method, then you need to specify the location ,in the reference frame, of the patterns you are looking for, and finally you should specify an area in which to look for the pattern (it is important to specify a small area to search for both speed and reliability).

Creating a reference frame for pattern and change tracking

When the patterns you want to track are in the frame call remember() the Xtra then takes a frame of the video and stores it in memory for reference . The Remember(TrackObj) method takes one parameter.

TrackObj - The instance number returned from New().

This is a good time to also grab a frame to a cast member for you to use as a reference by using GrabToCast() (see details above)

Following patterns

Now you can start calling the FollowAreas().The FollowAreas(TrackObj, RectList) takes two parameters.

TrackObj - The instance number returned from New().

RectList - A list of pairs of rects , each pair defining the rect of the pattern you are looking for and the rect of the area to search.[pattern1 rect, search1 rect, patern2 rect, search2 rect....]
each pattern rect must be accompanied by a search rect. you are not limited by the amount of patterns to look for .

The FollowAreas() method returns a list with 3 items per pattern [Horizontal1, Vertical1, Match1, Horizontal2, Vertical2, Match2...]

Horizontal. The horizontal location, in pixels, of the center of area that best matches the pattern. The value of this number is between 0 and the width of the video source as defined in the InitVideo() method.

Vertical. The vertical location, in pixels, of the center of area that best matches the pattern. The value of this number is between 0 and the height of the video source as defined in the InitVideo() method.

Match. A number between 0- 765 defining the confidence the software has in the match it has found (the lower the better). you should monitor this number and only use results that have a low match number.

Tracking in 3D - Overview

The Xtra allows you to track objects in 3D. This means that the Xtra will return the position of the tracked object in X, Y, Z coordinates.
In order for the software to successfully track an object, three conditions must be filled
A. the tracked object must be of sufficient size . This is of course relative to the magnification (zoom) of the video, however bear in mind that in order for the software to be able to track the distance of an object it must occupy at least a few pixels on the screen. In my experience an object the size of a ping-pong ball will work well for distances up to 70 inches, and an object the size of a tennis ball will work for larger distances.
B. the object must be significantly brighter than the background. a light bulb or a strong LED inside a ping pong ball is good (try adjusting the brightness and contrast using VideoSettings().
C. The software must be calibrated to return accurate coordinates. See Calibrate3D() below.

Calibrating the 3D Tracking

In order to calibrate the software you must call the Calibrate3D() method.

The Calibrate3D(TrackObj, Brightness , BallSize, Distance) takes 4 arguments:

TrackObj - The instance number returned from New().

Brightness - A number between 0 and 765 defining the minimum brightness of a pixel to be considered part of the tracked object. (be sure to specify the same number in the FollowOneBigLight() method !)

BallSize - A float describing the size (in the real world) of the tracked object. you may use any measurement units you like (Inch, Millimeter, centimeter, Feet) But be aware that you must use the same units for the Distance (see below).

Distance - A float describing the distance (in the real world) of the tracked object from the camera in the time of calibration. you should use the same measurement units you used in BallSize.

The Calibrate3D() method returns a list with 1 item in it which is a float that contains the factor that is the result of the calibration. you do not need to do anything with this value.

Tracking one big bright object in 3D

To track an object in three dimensions you call the FollowOneBigLight() method.

The FollowOneBigLight(TrackObj, Brightness ) method takes two arguments.

TrackObj - The instance number returned from New().

Brightness - A number between 0 and 765 defining the minimum brightness of a pixel to be considered part of the tracked object. (be sure to specify the same number in the Calibrate3D() method)

The FollowOneBigLight() returns a list with 7 items.[Left , Top, Right, Bottom, X, Y, Z]

Left - An integer defining the distance in pixels of the left side of the light object from the left of the video frame.

Top - An integer defining the distance in pixels of the top of the light object from the top of the video frame.

Right - An integer defining the distance in pixels of the right side of the light object from the left side of the video frame.

Bottom - An integer defining the distance in pixels of the bottom of the light object from the top of the video frame.

X coordinate - a float defining the horizontal distance (in the real world) of the tracked object from the center of the camera view. (the units are the units used in Calibrate3D().)

Y coordinate - a float defining the vertical distance (in the real world) of the tracked object from the center of the camera view. (the units are the units used in Calibrate3D().)

Z coordinate - a float defining the distance (in the real world) of the tracked object from the camera. (the units are the units used in Calibrate3D().)

Setting video parameters directly:

Sometimes you may want to set atributes of the video without opening the video settings dialog box . You can do that with the SetPararms() method.

The SetParams(TrackObj,input,hue,saturation,brightness,contrast,sharpness) method takes 7 arguments:

TrackObj - The instance number returned from New().

input - 1 or zero . 0 for composite video input. 1 for S-Video input. Not all video grabbers support this paramater. If you wish to leave the hue untouched set this argument to -1

hue - a number between 0 and 65536 defining the hue of the video. A setting of 32768 is 180 degrees which is the normal setting. If you wish to leave the hue untouched set this argument to -1. Not all video grabbers support this paramater.

saturation - a number between 0 and 65536 defining the saturation of the video. A setting of 32768 is the normal setting. If you wish to leave the saturation untouched set this argument to -1. Not all video grabbers support this paramater.

brightness - a number between 0 and 65536 defining the brightness of the video. A setting of 32768 is the normal setting. If you wish to leave the brightness untouched set this argument to -1. Not all video grabbers support this paramater.

contrast - a number between 0 and 65536 defining the contrast of the video. A setting of 32768 the normal setting. If you wish to leave the contrast untouched set this argument to -1. Not all video grabbers support this paramater.

sharpness - a number between 0 and 65536 defining the sharpness of the video. A setting of 32768 the normal setting. If you wish to leave the sharpness untouched set this argument to -1. Not all video grabbers support this paramater.

Getting video parameters directly

Sometimes you may want to get atributes of the video without opening the video settings dialog box . You can do that with the SetPararms() method. this is handy for saving the settings for future use.

The GetParams(TrackObj) method takes one argument

TrackObj - The instance number returned from New().

The GetParams() method returns a list with 6 items : [input,hue,saturation,brightness,contrast,sharpness]

input - 1 or zero . 0 for composite video input. 1 for S-Video input. Not all video grabbers support this paramater.

hue - a number between 0 and 65536 defining the hue of the video. A setting of 32768 is 180 degrees which is the normal setting. Not all video grabbers support this paramater.

saturation - a number between 0 and 65536 defining the saturation of the video. A setting of 32768 is the normal setting. Not all video grabbers support this paramater.

brightness - a number between 0 and 65536 defining the brightness of the video. A setting of 32768 is the normal setting. Not all video grabbers support this paramater.

contrast - a number between 0 and 65536 defining the contrast of the video. A setting of 32768 the normal setting. Not all video grabbers support this paramater.

sharpness - a number between 0 and 65536 defining the sharpness of the video. A setting of 32768 the normal setting. Not all video grabbers support this paramater.

Getting a hold of the pixels in the video:

Sometimes you might want to get a hold on the actual pixels of the video frame. This is useful for analyzing the colors and for creating any other tracking method that is not supplied by the Xtra. Getting the pixels into director is surprisingly fast, and you should not hesitate to ask for thousands of points at a time. There are two methods that send back pixel colors are GetColors() and GetAllColors().

The GetColors() method lets you define the points you are interested in and returns the colors of those points.

The GetColors(TrackObj, points) takes two arguments:

TrackObj - The instance number returned from New().

points - A list of points to be returned [point1, point2, point3...]

The GetColors() method returns a list with the following sequence : [red1, green1, blue1, horizontal1, vertical1, red2, green2, blue2, horizontal2, vertical2...]

red -the red component of the pixel 0-255.
green -the green component of the pixel 0-255.
blue -the blue component of the pixel 0-255.

horizontal - the horizontal location of the pixel - this is an echo of the argument you sent as a point .

vertical - the vertical location of the pixel - this is an echo of the argument you sent as a point .

The GetAllColors lets get a large amount of pixels fast. You define an area and the Xtra returns all the pixels in that area. This method is faster than GetColors() but the results are not formatted as conveniently.

The GetAllColors(TrackObj, area) takes two arguments:

TrackObj - The instance number returned from New().

area - a rect of the area of interest.

The GetAllColors() method returns a list of colors in the following sequence [red1, green1, blue1, red2, green2, blue2, red3, green3, blue3...]

red -the red component of the pixel 0-255.
green -the green component of the pixel 0-255.
blue -the blue component of the pixel 0-255.

using these results is not that straight forward.

Say you want to receive all the pixels from an area at the upper left corner of the video . Say the rect you are defining is rect(0,0,100,100).

Therefore your call will look like this :
put GetAllColors(TrackObj, rect(0,0,100,100)) into TheResult

therefor the Xtra will return a list with 3 X 100 x 100 =30,000 items

Than say you want to see the color of pixel 10 - horizontal , 50 - vertical .

Set TheWidth = 100 -- remember we asked for a 100*100 rect
set PixelH = 10 -- our pixels horizontal location
Set PixelV = 50 -- our pixels vertical location

Set OurPixel = PixelH *3 + PixelV *TheWidth
set red =getat (theresult , OurPixel )
set green =getat (theresult , OurPixel +1)
set blue =getat (theresult , OurPixel +2)

This looks complicated but you only have to figure it out once...

	TrackThemColors specs
	Starting the video flow. In order to access the video stream, the Xtra has to establish a connection with the video capture device and allocate memory. None of the other methods in this Xtra will work without calling the InitVideo() first. You should call the InitVideo() method only once, and be sure to call CleanUp() before you leave. The InitVideo(TrackObj, Width, height, source) method takes four arguments: TrackObj - The instance number returned from New(). Height - defines the height in Pixels of the video frame you want. Width - defines the width in Pixels of the video frame you want. source - defines the video digitizer that will be used. In most cases use 1. If you have more than one video digitezers installed in your computer (for example an AV board and a connectix camera) than you can specify 2 for the second 3 for the third... If you specify a number larger than the number of video digitizers in the computer it will default to the first. The smaller the video frame the better the performance of the Xtra. Stopping the video flow. Once you are done tracking, you should call the CleanUp() method. Do not attempt to call InitVideo() again without calling the CleanUp() first. The CleanUp(TrackObj) method takes one argument. TrackObj - The instance number returned from New(). Opening the Video Settings dialog box To open the standard Video Settings dialog box which allows you to change the video source or change the parameters for your camera, use the VideoSettings() method. This is very useful for changing the brightness, saturation and contrast of the video to create better conditions for the tracking. The VideoSettings(TrackObj) takes one argument. TrackObj - The instance number returned from New(). Viewing the video source on stage To View the video source on the screen you should call ShowVideo() The ShowVideo(TrackObj) method takes three arguments. TrackObj - The instance number returned from New(). horizontal - The location in pixels of the left side of the frame. vertical - The location in pixels of the top of the frame. Please note that the ShowVideo() method should be called repeatedly, to get a continuously changing display of the video source. The ShowVideo() method returns a list containing 3 numbers. [red, green, blue] these numbers are the color value of the Pixel directly under the mouse the numbers go from 0 - 255 . This feature is useful for determining the color value of specific elements in the video, in order to track them later. Grabbing a video frame to a cast member You can use the Xtra to grab frames from the video to a cast member. This is useful for creating background images for visualizing the tracking and for other purposes. To grab a video frame to a cast member use the GrabToCast() method. The GrabToCast (TrackObj, CastMemberNum) takes two parameters. TrackObj - The instance number returned from New(). CastMemberNum - The number of the cast member to which you wish to grab the frame. (Have an Image cast member waiting in that location) Tracking the brightest point To track the brightest point in the video source, call the FollowOneLight() method. The FollowOneLight(TrackObj) method takes one argument. TrackObj - The instance number returned from New(). The FollowOneLight() method returns a list containing 2 numbers [Horizontal, Vertical]. Horizontal. The horizontal placement, in pixels, of the brightest point . The value of this number is between 0 and the width of the video source as defined in the InitVideo() method Vertical. The vertical placement, in pixels, of the brightest point . The value of this number is between 0 and the height of the video source as defined in the InitVideo() method. Tracking multiple locations of a specific color. To track more than one point of a specific color you should call the FollowThisColorPoints() method The FollowThisColorPoints(TrackObj, tolerance, size, red, green, blue) takes seven arguments. TrackObj - The instance number returned from New(). tolerance - A number between 0 and 765 defining how close does a pixel in the video have to be in order to be considered a match. (the larger the number the more points will be returned) Size - A number defining how far can two points be from each other and still be considered as one point (the larger the number the less points will be returned) red - An integer between 0-255 defining the red value of the color to be tracked. green - An integer between 0-255 defining the green value of the color to be tracked. blue - an integer between 0-255 defining the blue value of the color to be tracked. The FollowThisColorPoints() method returns a list containing two numbers for each point found. [Horizontal, Vertical, Horizontal, Vertical...]. Horizontal. The horizontal location, in pixels, of the point . The value of this number is between 0 and the width of the video source as defined in the InitVideo() method. Vertical. The vertical placement, in pixels, of the point . The value of this number is between 0 and the height of the video source as defined in the InitVideo() method. Tracking many specific colors To track specific colors of interest in the video source use the FollowMyColors() method. this method will look for the points in the video most similar to the colors you define. The FollowMyColors(TrackObj, How Many, Colorstring) takes three arguments TrackObj - The instance number returned from New(). HowMany - a number defining the number of colors you are interested in tracking. ColorString - a string containing the color values of the colors you wish to track. For each color you must attach it's value in red green and blue. Since the Xtra expects a string you must use NumToChar() to convert your numbers into characters. For example to track the color Red (255,0,0) use: put NumToChar(255) into ColorString put NumToChar(255) after ColorString put NumToChar(255) after ColorString all the values for all the colors must be appended into one long string. The FollowMyColors() method returns a list containing two numbers for each color tracked in the order you specified them. [Horizontal, Vertical, Horizontal, Vertical...]. Horizontal. The horizontal location, in pixels, of the pixel closest to the color you requested . The value of this number is between 0 and the width of the video source as defined in the InitVideo() method. Vertical. The vertical location, in pixels, of the pixel closest to the color you requested. The value of this number is between 0 and the height of the video source as defined in the InitVideo() method. Be sure to specify all the color values for the number of colors you asked to be tracked. The maximum number of colors that can be successfully tracked is not set and changes from machine to machine. I have successfully tracked 17 different colors. Tracking change in the video over time To track changes in the video between frames, use the FollowTheChange() method. This method looks for differences between the current frame and either the previous frame or a reference frame. A typical application for a reference frame would be to make a reference frame of an empty room and then any person or object would be considered change, even if they are not moving. If in the same environment you would track change from frame to frame, only objects that are in motion would show up. The FollowTheChange(TrackObj, change, fromRefrence, padding) takes four parameter: TrackObj - The instance number returned from New(). change - A number between 0 - 442 . The xtra will not consider as change any difference under the specified value.(The smaller the number the more sensitive to change the result). fromRefrence - 0 -compare this frame to the previous frame. 1 - Compare this frame to a reference frame (use Remember() to define a reference frame, see below) . padding - a number defining the padding around each pixel of change. Adding padding reduces the number of rects returned and reduces noise) The FollowTheChange method groups neighboring pixels into rects and returns the rects in a list: [rect1, rect2, rect3...] with as many rects as were found in the video. Following patterns in the video - Overview. To follow patterns in the video, use the FollowAreas() method. Sometimes it is useful to track not a particular color , but a particular arrangement of pixels (an eye, ear, car). To do so you must supply the Xtra with a reference frame to compare using the Remember() method, then you need to specify the location ,in the reference frame, of the patterns you are looking for, and finally you should specify an area in which to look for the pattern (it is important to specify a small area to search for both speed and reliability). Creating a reference frame for pattern and change tracking When the patterns you want to track are in the frame call remember() the Xtra then takes a frame of the video and stores it in memory for reference . The Remember(TrackObj) method takes one parameter. TrackObj - The instance number returned from New(). This is a good time to also grab a frame to a cast member for you to use as a reference by using GrabToCast() (see details above) Following patterns Now you can start calling the FollowAreas().The FollowAreas(TrackObj, RectList) takes two parameters. TrackObj - The instance number returned from New(). RectList - A list of pairs of rects , each pair defining the rect of the pattern you are looking for and the rect of the area to search.[pattern1 rect, search1 rect, patern2 rect, search2 rect....] each pattern rect must be accompanied by a search rect. you are not limited by the amount of patterns to look for . The FollowAreas() method returns a list with 3 items per pattern [Horizontal1, Vertical1, Match1, Horizontal2, Vertical2, Match2...] Horizontal. The horizontal location, in pixels, of the center of area that best matches the pattern. The value of this number is between 0 and the width of the video source as defined in the InitVideo() method. Vertical. The vertical location, in pixels, of the center of area that best matches the pattern. The value of this number is between 0 and the height of the video source as defined in the InitVideo() method. Match. A number between 0- 765 defining the confidence the software has in the match it has found (the lower the better). you should monitor this number and only use results that have a low match number. Tracking in 3D - Overview The Xtra allows you to track objects in 3D. This means that the Xtra will return the position of the tracked object in X, Y, Z coordinates. In order for the software to successfully track an object, three conditions must be filled A. the tracked object must be of sufficient size . This is of course relative to the magnification (zoom) of the video, however bear in mind that in order for the software to be able to track the distance of an object it must occupy at least a few pixels on the screen. In my experience an object the size of a ping-pong ball will work well for distances up to 70 inches, and an object the size of a tennis ball will work for larger distances. B. the object must be significantly brighter than the background. a light bulb or a strong LED inside a ping pong ball is good (try adjusting the brightness and contrast using VideoSettings(). C. The software must be calibrated to return accurate coordinates. See Calibrate3D() below. Calibrating the 3D Tracking In order to calibrate the software you must call the Calibrate3D() method. The Calibrate3D(TrackObj, Brightness , BallSize, Distance) takes 4 arguments: TrackObj - The instance number returned from New(). Brightness - A number between 0 and 765 defining the minimum brightness of a pixel to be considered part of the tracked object. (be sure to specify the same number in the FollowOneBigLight() method !) BallSize - A float describing the size (in the real world) of the tracked object. you may use any measurement units you like (Inch, Millimeter, centimeter, Feet) But be aware that you must use the same units for the Distance (see below). Distance - A float describing the distance (in the real world) of the tracked object from the camera in the time of calibration. you should use the same measurement units you used in BallSize. The Calibrate3D() method returns a list with 1 item in it which is a float that contains the factor that is the result of the calibration. you do not need to do anything with this value. Tracking one big bright object in 3D To track an object in three dimensions you call the FollowOneBigLight() method. The FollowOneBigLight(TrackObj, Brightness ) method takes two arguments. TrackObj - The instance number returned from New(). Brightness - A number between 0 and 765 defining the minimum brightness of a pixel to be considered part of the tracked object. (be sure to specify the same number in the Calibrate3D() method) The FollowOneBigLight() returns a list with 7 items.[Left , Top, Right, Bottom, X, Y, Z] Left - An integer defining the distance in pixels of the left side of the light object from the left of the video frame. Top - An integer defining the distance in pixels of the top of the light object from the top of the video frame. Right - An integer defining the distance in pixels of the right side of the light object from the left side of the video frame. Bottom - An integer defining the distance in pixels of the bottom of the light object from the top of the video frame. X coordinate - a float defining the horizontal distance (in the real world) of the tracked object from the center of the camera view. (the units are the units used in Calibrate3D().) Y coordinate - a float defining the vertical distance (in the real world) of the tracked object from the center of the camera view. (the units are the units used in Calibrate3D().) Z coordinate - a float defining the distance (in the real world) of the tracked object from the camera. (the units are the units used in Calibrate3D().) Setting video parameters directly: Sometimes you may want to set atributes of the video without opening the video settings dialog box . You can do that with the SetPararms() method. The SetParams(TrackObj,input,hue,saturation,brightness,contrast,sharpness) method takes 7 arguments: TrackObj - The instance number returned from New(). input - 1 or zero . 0 for composite video input. 1 for S-Video input. Not all video grabbers support this paramater. If you wish to leave the hue untouched set this argument to -1 hue - a number between 0 and 65536 defining the hue of the video. A setting of 32768 is 180 degrees which is the normal setting. If you wish to leave the hue untouched set this argument to -1. Not all video grabbers support this paramater. saturation - a number between 0 and 65536 defining the saturation of the video. A setting of 32768 is the normal setting. If you wish to leave the saturation untouched set this argument to -1. Not all video grabbers support this paramater. brightness - a number between 0 and 65536 defining the brightness of the video. A setting of 32768 is the normal setting. If you wish to leave the brightness untouched set this argument to -1. Not all video grabbers support this paramater. contrast - a number between 0 and 65536 defining the contrast of the video. A setting of 32768 the normal setting. If you wish to leave the contrast untouched set this argument to -1. Not all video grabbers support this paramater. sharpness - a number between 0 and 65536 defining the sharpness of the video. A setting of 32768 the normal setting. If you wish to leave the sharpness untouched set this argument to -1. Not all video grabbers support this paramater. Getting video parameters directly Sometimes you may want to get atributes of the video without opening the video settings dialog box . You can do that with the SetPararms() method. this is handy for saving the settings for future use. The GetParams(TrackObj) method takes one argument TrackObj - The instance number returned from New(). The GetParams() method returns a list with 6 items : [input,hue,saturation,brightness,contrast,sharpness] input - 1 or zero . 0 for composite video input. 1 for S-Video input. Not all video grabbers support this paramater. hue - a number between 0 and 65536 defining the hue of the video. A setting of 32768 is 180 degrees which is the normal setting. Not all video grabbers support this paramater. saturation - a number between 0 and 65536 defining the saturation of the video. A setting of 32768 is the normal setting. Not all video grabbers support this paramater. brightness - a number between 0 and 65536 defining the brightness of the video. A setting of 32768 is the normal setting. Not all video grabbers support this paramater. contrast - a number between 0 and 65536 defining the contrast of the video. A setting of 32768 the normal setting. Not all video grabbers support this paramater. sharpness - a number between 0 and 65536 defining the sharpness of the video. A setting of 32768 the normal setting. Not all video grabbers support this paramater. Getting a hold of the pixels in the video: Sometimes you might want to get a hold on the actual pixels of the video frame. This is useful for analyzing the colors and for creating any other tracking method that is not supplied by the Xtra. Getting the pixels into director is surprisingly fast, and you should not hesitate to ask for thousands of points at a time. There are two methods that send back pixel colors are GetColors() and GetAllColors(). The GetColors() method lets you define the points you are interested in and returns the colors of those points. The GetColors(TrackObj, points) takes two arguments: TrackObj - The instance number returned from New(). points - A list of points to be returned [point1, point2, point3...] The GetColors() method returns a list with the following sequence : [red1, green1, blue1, horizontal1, vertical1, red2, green2, blue2, horizontal2, vertical2...] red -the red component of the pixel 0-255. green -the green component of the pixel 0-255. blue -the blue component of the pixel 0-255. horizontal - the horizontal location of the pixel - this is an echo of the argument you sent as a point . vertical - the vertical location of the pixel - this is an echo of the argument you sent as a point . The GetAllColors lets get a large amount of pixels fast. You define an area and the Xtra returns all the pixels in that area. This method is faster than GetColors() but the results are not formatted as conveniently. The GetAllColors(TrackObj, area) takes two arguments: TrackObj - The instance number returned from New(). area - a rect of the area of interest. The GetAllColors() method returns a list of colors in the following sequence [red1, green1, blue1, red2, green2, blue2, red3, green3, blue3...] red -the red component of the pixel 0-255. green -the green component of the pixel 0-255. blue -the blue component of the pixel 0-255. using these results is not that straight forward. Say you want to receive all the pixels from an area at the upper left corner of the video . Say the rect you are defining is rect(0,0,100,100). Therefore your call will look like this : put GetAllColors(TrackObj, rect(0,0,100,100)) into TheResult therefor the Xtra will return a list with 3 X 100 x 100 =30,000 items Than say you want to see the color of pixel 10 - horizontal , 50 - vertical . Set TheWidth = 100 -- remember we asked for a 100100 rect set PixelH = 10 -- our pixels horizontal location Set PixelV = 50 -- our pixels vertical location Set OurPixel = PixelH 3 + PixelV *TheWidth set red =getat (theresult , OurPixel ) set green =getat (theresult , OurPixel +1) set blue =getat (theresult , OurPixel +2) This looks complicated but you only have to figure it out once...