ingenuitas/SimpleCV — pull request #156 by jayrambhia (2012-07-14 07:28:41+00:00)
Title: Tracking

Tracking Features implemented.

# track
def track(self, method, ts=None, img=None, bb=None, num_frames=3):
===========================
#### HOW TO:

ts = img.track("camshift", img=img1, bb=bb)

Tracking object contains the bounding box, and image. Here TrackSet is returned.
TrackSet will contain CAMShift.

Now,
There's no need to provide image and the bounding box as it takes the image and bounding box from the last Tracking element of TrackSet list.

ts = new_img.track("camshift", ts)
The new Tracking feature will be appended to the given TrackSet and TrackSet will be returned.

### Use in a loop:

img = cam.getImage()
ts = img.track("camshift", img=img0, bb=bb)
While (some_condition_here):
img = cam.getImage()
ts = img.track("camshift", ts)
Another easy way

ts = []
while (some_condition_here):
img = cam.getImage()
ts = img.track("camshift", ts, img0, bb)

now here in first loop iteration since the provided TrackSet **ts** is **empty**, img0 and bb will be **considered**. New Tracking object will be added in ts (TrackSet) in the first iteration.
After first iteration, since the provide TrackSet **ts** is **not empty**, the previous image frames and bounding box will be taken from the give TrackSet **ts**. img0 and bb will be **ignored**.

### Don't like loops. Use a list of Images.

ts = []
imgs = [img1, img2, img3, ..., imgN]
ts = img0.track("camshift", ts, imgs, bb)

All the provided images will be tracked in the given order. When the first image is being tracked, the provided bounding box bb will be used. For the rest of the images, the bounding box from the Tracking object from the TrackSet ts will be used.

# Tracking
Tracking class is the base of tracking. All different tracking algorithm return different classes but they all belong to the Tracking class. All the common attributes are kept in this class. Tracking class is derived from SimpleCV Feature class.

### Some Important Features:

#### areaRatio
areaRatio is the ratio of the size of the current bounding box to the size of the initial (first) bounding box.

#### vel
The difference between the co-ordinates of the center of the object in consecutive frames. The other/previous Tracking object is taken from the TrackSet which this Tracking object belongs to.
(pixels/frame)

#### rt_vel
The difference between the co-ordinates of the center of the object in consecutive frames. The other/previous Tracking object is taken from the TrackSet which this Tracking object belongs to.
(pixels/second)

#### time
Return the time when this Tracking object was created. (in seconds)

#### draw
Draw the center of the object on the Image.

#### drawBB
Draw the bounding box over the object on the Image.

#### showCoordinates
This method will draw the center co-ordinates of the object in text on the image. eg.

x = 45 y = 68

#### showSizeRatio

This method will draw the sizeRatio of the object in text on image. eg.

size = 0.8

#### showPixelVelocity

This method will draw the pixel velocity(pixels/frame) of the object in text on the image. eg.

Vx = 1.59 Vy = -1.32
pixel/frames

#### showPixelVelocityRT

This method will draw the pixel velocity(pixels/second) of the object in text on the image. eg.

Vx = 20.34 Vy = -10.45
pixel/second

# TrackSet

TrackSet is a class extended from SimpleCV FeatureSet which is in turn extended from Python's list.
So, TrackSet has all the properties of a list as well as all the properties of FeatureSet.

### Some Important Features:

#### append:
To append in a list, list has it's own built-in function **append**. But here I have defined append as a method of TrackSet class. When appending Tracking feature in TrackSet, I want to calculate the size ratio, pixel velocity, etc and for that I need to access the previous Tracking feature of the TrackSet. There was no other plausible solution. Hence I created a method in TrackSet named **append**. I calculate size ratio, pixel velocity, etc and then append Tracking feature to TrackSet.

def append(self, f):
list.append(self,f)
ts = self
f.sizeRatio = float(ts[-1].area)/float(ts[0].area)
f.vel = self.__pixelVelocity()
f.rt_vel = self.__pixleVelocityRealTime()

#### processTrack

processTrack lets user use user defined function on the entire imageset.

def foo(img):
return img.meanColor()

mean_color_list = ts.processTrack(foo)
This example will return a list of mean colors of all the images in the TrackSet.

#### drawPath
Draw the complete path traced by the center of the object on current frame.

#### trackLength
Get number of tracked frames

#### trackImages
Get all the tracked images in a list

#### BBTrack
Get all the bounding box in a list

#### areaRatio
This will return a numpy array of all the areaRatio of Tracking object present in the TrackSet.

#### pixelVelocity
This will return a numpy array of all the pixelVelocity of Tracking object present in the TrackSet.

#### pixelVelocityRealTime
This will return a numpy array of all the pixelVelocityRT of Tracking object present in the TrackSet.

#### showCoordinates
This method will draw the current center co-ordinates of the object in text on the current image frame. eg.

x = 45 y = 68

#### showSizeRatio

This method will draw the current sizeRatio of the object in text on the current image frame. eg.

size = 0.8

#### showPixelVelocity

This method will draw the current pixel velocity(pixels/frame) of the object in text on the current image frame. eg.

Vx = 1.59 Vy = -1.32
pixel/frames

#### showPixelVelocityRT

This method will draw the current pixel velocity(pixels/second) of the object in text on the current image frame. eg.

Vx = 20.34 Vy = -10.45
pixel/second