Tracker module API
Accessing trackers
The number of trackers being passed into the node can be found:
num= pfpy.getNumTrackers()
print("node is reading", num, "trackers")
A reference to an existing tracker can be obtained as follows:
t= pfpy.getTrackerRef(index, input)
where index is an integer indicating which tracker to read in the range 0 and N-1 inclusive, where N is the number of trackers returned by pfpy.getNumTrackers(). The input parameter is optional, but when present specifies the input number for which tracker data is required. When the input parameter is not present, tracker data will be obtained for the first input (zero).
By calling the Tracker API functions described below, tracker data can be modified before being passed down-stream. The internal tracker can be copied and freed as follows:
t= pfpy.getTrackerRef(index)
tt= t.copy()
# do stuff
tt.freeCopy()
Copying a tracker in this way allows original tracker data to be read from the copy, regardless of how the actual tracker is then modified by the script. An example of this copying process in action is given in the filterTracks.py example script.
Creating new trackers
To create a new tracker, use the new function:
t= pfpy.Tracker.new(name)
This will create a new tracker with the specified name ready to be modified in the script and then passed down-stream.
API functions
Examples of these functions in use are provided by the python scripts available in the exports, macros and nodes installation folders.
getName()
Parameters:
none
Description:
Returns the tracker name
Example:
t= pfpy.getTrackerRef(0)
print("Tracker is named", t.getName())
Command:
setName(name)
Parameters:
string: tracker name
Description:
Sets the tracker name to the string
Example:
t= pfpy.getTrackerRef(0)
t.setName("myName")
Command:
getGroup()
Parameters:
none
Description:
Returns the index number of the tracking group containing this tracker. The main camera group has an index of zero.
Example:
t= pfpy.getTrackerRef(0)
print("Tracker group number is", t.getGroup())
Command:
setGroup(index)
Parameters:
integer: index number
Description:
Sets the group index number for the tracker. The main camera group has an index of zero.
Example:
t= pfpy.getTrackerRef(0)
# place this tracker in the first object group
t.setGroup(1)
Command:
getSelected()
Parameters:
none
Description:
Returns true if the tracker was selected
Example:
t= pfpy.getTrackerRef(0)
print("Tracker selection is ", t.getSelected())
Command:
setSelected(state)
Parameters:
boolean: state
Description:
Selects or de-selects the tracker
Example:
t= pfpy.getTrackerRef(0)
t.setSelected(True)
Command:
getColour()
Parameters:
none
Description:
Returns an R G B tuple containing the 8-bit (0 to 255) display colour for the tracker
Example:
t= pfpy.getTrackerRef(0)
print("Tracker colour is ", t.getColour())
Command:
setColour(colour)
Parameters:
integer: colour tuple
Description:
Sets the display colour for the tracker to 8-bit R G B values.
Example:
t= pfpy.getTrackerRef(0)
t.setColour(255, 0, 0)
Command:
getTracked(frame)
Parameters:
integer: frame
Description:
Returns true if the tracker was tracked in the frame
Example:
t= pfpy.getTrackerRef(0)
print("Tracked in frame zero: ", t.getTracked(0))
Command:
setTracked(frame, state)
Parameters:
integer: frame and boolean state
Description:
Sets the track state in the specified frame
Example:
t= pfpy.getTrackerRef(0)
# flag as "tracked" in frame 10
t.setTracked(10, True)
Command:
getKeyed(frame)
Parameters:
integer: frame
Description:
Returns true if the tracker was keyed in the frame
Example:
t= pfpy.getTrackerRef(0)
print("Keyed in frame zero: ", t.getKeyed(0))
Command:
setKeyed(frame, state)
Parameters:
integer: frame and boolean state
Description:
Sets the key state in the specified frame
Example:
t= pfpy.getTrackerRef(0)
# flag as "keyed" in frame 10
t.setKeyed(10, True)
Command:
getTrackPosition(frame)
Parameters:
integer: frame
Description:
Returns the X Y tracker position in the frame (measured in pixels, with the origin at the bottom-left corner of the image)
Example:
t= pfpy.getTrackerRef(0)
print("Position in frame 10 is: ", t.getTrackPosition(10))
Command:
setTrackPositon(frame, value)
Parameters:
integer: frame
floating point: values
Description:
Sets the X Y tracker position in the frame (measured in pixels, with the origin at the bottom-left corner of the image)
Example:
t= pfpy.getTrackerRef(0)
t.setTrackPosition(10, 200.0, 150.0)
Command:
getTrackScore(frame)
Parameters:
integer: frame
Description:
Returns the tracker matching score in the frame, in the range 0.0 to 1.0, where 1.0 indicates a perfect match
Example:
t= pfpy.getTrackerRef(0)
print("Matching score in frame 10 is: ", t.getTrackScore(10))
Command:
setTrackScore(frame, value)
Parameters:
integer: frame
floating point: value
Description:
Sets the tracker matching score in the frame, in the range 0.0 to 1.0, where 1.0 indicates a perfect match
Example:
t= pfpy.getTrackerRef(0)
t.setTrackScore(10, 0.95)
Command:
getRelativeSearch()
Parameters:
none
Description:
Returns the coordinates of the relative search rectangle around the tracker (minx, miny, maxx, maxy), measured in pixels, with the origin point at the tracker position.
Example:
t= pfpy.getTrackerRef(0)
s= t.getRelativeSearch()
print("Search from", s[0],s[1], "to", s[2],s[3])
Command:
setRelativeSearch(value)
Parameters:
floating point: values
Description:
Sets the coordinates of the relative search rectangle around the tracker (minx, miny, maxx, maxy), measured in pixels, with the origin point at the tracker position.
Example:
t= pfpy.getTrackerRef(0)
# set search from (-10,5) to (+6,+8)
t.setRelativeSearch(-10, -5, 6, 8)
Command:
getRelativeWindow()
Parameters:
none
Description:
Returns the coordinates of the relative tracker window (minx, miny, maxx, maxy), measured in pixels, with the origin point at the tracker position.
Example:
t= pfpy.getTrackerRef(0)
s= t.getRelativeWindow()
print("Window from", s[0],s[1], "to", s[2],s[3])
Command:
setRelativeWindow(value)
Parameters:
floating point: values
Description:
Sets the coordinates of the relative tracker window (minx, miny, maxx, maxy), measured in pixels, with the origin point at the tracker position.
Example:
t= pfpy.getTrackerRef(0)
# set window from (-5,5) to (+8,+8)
t.setRelativeWindow(-5, -5, 8, 8)
Command:
validPosition(frame)
Parameters:
integer: frame
Description:
Returns true if the tracker position is valid at a frame. For a tracker position to be valid, the following statements must be true:
1. The frame number is within the in/out range</li>
2. The tracker is not hidden at the frame</li>
3. The tracker is not trimmed at the frame</li>
Example:
t= pfpy.getTrackerRef(0)
firstFrame= t.getInPoint()
lastFrame= t.getOutPoint()
print("tracker in frame: ", firstFrame)
print("tracker out frame: ", lastFrame)
for f in range(firstFrame, lastFrame+1, 1) :
if (t.validPosition(f)) :
print("valid position at frame: ", f, t.getTrackPosition(f))
Command:
getHidden(frame)
Parameters:
integer: frame
Description:
Returns true if a tracker is hidden at the frame
Example:
t= pfpy.getTrackerRef(0)
print("Hidden in frame 10: ", t.getHidden(10))
Command:
setHidden(frame, state)
Parameters:
integer: frame
boolean: state
Description:
Sets the hide state at a frame
Example:
t= pfpy.getTrackerRef(0)
t.setHidden(10, True)
print("Hidden in frame 10 should be true: ", t.getHidden(10))
Command:
getActive()
Parameters:
none
Description:
Returns true if the tracker has been activated in a camera solver before being passed into the Python node. Note that trackers are active by default, so this will only return False if the tracker has been de-activated.
Example:
t= pfpy.getTrackerRef(0)
print("Tracker is active: ", t.getActive())
Command:
setActive(state)
Parameters:
boolean: state
Description:
Flags the tracker as active in a camera solve or not. Note that trackers are active by default.
Example:
t= pfpy.getTrackerRef(0)
# deactivate the tracker in down-stream camera solvers
t.setActive(False)
Command:
getExport()
Parameters:
none
Description:
Returns true if the tracker has been flagged for export by an Export node. Note that trackers are flagged for export by default.
Example:
t= pfpy.getTrackerRef(0)
print("Export tracker: ", t.getExport())
Command:
setExport(state)
Parameters:
boolean: state
Description:
Flag the tracker for export or not. Note that trackers are flagged for export by default.
Example:
t= pfpy.getTrackerRef(0)
t.setExport(False)
Command:
getAuto()
Parameters:
none
Description:
Returns true if the tracker was generated using automatic feature tracking.
Example:
t= pfpy.getTrackerRef(0)
print("Tracker is auto: ", t.getAuto())
Command:
setAuto(state)
Parameters:
boolean: state
Description:
Flags the tracker as an automatically generated feature or not.
Example:
t= pfpy.getTrackerRef(0)
# flag as an auto-tracker
t.setAuto(True)
Command:
getHardConstraint()
Parameters:
none
Description:
Returns true if the tracker was flagged as a hard constraint in a camera solver.
Example:
t= pfpy.getTrackerRef(0)
print("Tracker is hard constraint: ", t.getHardConstraint())
Command:
setHardConstraint(state)
Parameters:
boolean: state
Description:
Flags the tracker as a hard constraint for a camera solver.
Example:
t= pfpy.getTrackerRef(0)
# set the tracker as a hard constraint
t.setHardConstraint(true)
Command:
getLocked()
Parameters:
none
Description:
Returns true if the tracker was locked in the UI.
Example:
t= pfpy.getTrackerRef(0)
print("Tracker is locked: ", t.getLocked())
Command:
setLocked(state)
Parameters:
boolean: state
Description:
Lock or unlock the tracker in the UI.
Example:
t= pfpy.getTrackerRef(0)
# lock the tracker
t.setLocked(False)
Command:
getSolved()
Parameters:
none
Description:
Returns true if the tracker has a solved 3D position.
Example:
t= pfpy.getTrackerRef(0)
print("Tracker is solved: ", t.getSolved())
Command:
setSolved(state)
Parameters:
boolean: state
Description:
Set the solve state for a tracker
Example:
t= pfpy.getTrackerRef(0)
# flag the tracker as solved
t.setSolved(True)
t.setSolvedPos(-8.764, 1.225, -6.335)
Command:
getSolvedPos(frame)
Parameters:
integer: frame number (optional)
Description:
Returns the solved 3D tracker position. If a frame number is supplied, the 3D tracker position at that frame is returned
Example:
t0= pfpy.getTrackerRef(0)
a= t0.getSolvedPos()
print("solved pos is", a[0],a[1],a[2])
t1. pfpy.getTrackerRef(1)
b= t1.getSolvedPos(10)
print("solved pos in frame 10 is", b[0],b[1],b[2])
Command:
setSolvedPos(x, y, z)
Parameters:
floating point: X Y and Z coordinates
Description:
Set the solved 3D tracker position
Example:
t= pfpy.getTrackerRef(0)
# flag the tracker as solved
t.setSolved(True)
t.setSolvedPos(-8.764, 1.225, -6.335)
Command:
getSurvey()
Parameters:
none
Description:
Returns true if the tracker has a surveyed 3D position.
Example:
t= pfpy.getTrackerRef(0)
print("Tracker is surveyed: ", t.getSurvey())
Command:
setSurvey(state)
Parameters:
boolean: state
Description:
Set the survey state for a tracker
Example:
t= pfpy.getTrackerRef(0)
# create survey coordinates
t.setSurvey(True)
t.setSurveyPos(-8.764, 1.225, -6.335)
t.setSurveyUncertainty(0.01)
Command:
getSurveyPos(frame)
Parameters:
integer: frame number (optional)
Description:
Returns the surveyed 3D tracker position. If a frame number is supplied, the 3D tracker position at that frame is returned
Example:
t0= pfpy.getTrackerRef(0)
a= t0.getSurveyPos()
print("survey pos is", a[0],a[1],a[2])
t1. pfpy.getTrackerRef(1)
b= t1.getSurveyPos(10)
print("survey pos in frame 10 is", b[0],b[1],b[2])
Command:
setSurveyPos(x, y, z)
Parameters:
floating point: X Y and Z coordinates
Description:
Set the surveyed 3D tracker position
Example:
t= pfpy.getTrackerRef(0)
# flag the tracker as surveyed
t.setSurvey(True)
t.setSurveyPos(-8.764, 1.225, -6.335)
t.setSurveyUncertainty(0.01)
Command:
getSurveyUncertainty()
Parameters:
none
Description:
Returns the uncertainty of the survey position.
Example:
t= pfpy.getTrackerRef(0)
print("Survey uncertainty: ", t.getSurveyUncertainty())
Command:
setSurveyUncertainty(value)
Parameters:
floating point: value
Description:
Set the survey position uncertainty.
Example:
t= pfpy.getTrackerRef(0)
# create survey coordinates
t.setSurvey(True)
t.setSurveyPos(-8.764, 1.225, -6.335)
t.setSurveyUncertainty(0.01)
Command:
getWeight()
Parameters:
none
Description:
Returns the tracker weight, as used by the camera solver. By default, trackers have a weight of 1.0.
Example:
t= pfpy.getTrackerRef(0)
print("Tracker weight is ", t.getWeight())
Command:
setWeight(value)
Parameters:
floating point: value
Description:
Set the tracker weight, as used by the camera solver. By default, trackers have a weight of 1.0.
Example:
t= pfpy.getTrackerRef(0)
t.setWeight(0.5)
Command:
getInitialisedDistance()
Parameters:
none
Description:
Returns the initialised tracker distance specified in a camera solver. If a tracker does not have an initialised distance, this will return -1.0.
Example:
t= pfpy.getTrackerRef(0)
print("Tracker distance, uncertainty is ", t.getInitialisedDistance(), t.getInitialisedUncertainty())
Command:
setInitialisedDistance(value)
Parameters:
floating point: value
Description:
Set the initialised distance for a tracker. Setting this to a negative number will remove the initialised distance value from the tracker.
Example:
t= pfpy.getTrackerRef(0)
t.setInitialisedDistance(10.0)
t.setInitialisedUncertainty(0.5)
Command:
getInitialisedUncertainty()
Parameters:
none
Description:
Returns the initialised distance uncertainty specified in a camera solver. If a tracker does not have an initialised uncertainty, this will return -1.0.
Example:
t= pfpy.getTrackerRef(0)
print("Tracker distance, uncertainty is ", t.getInitialisedDistance(), t.getInitialisedUncertainty())
Command:
setInitialisedUncertainty(value)
Parameters:
floating point: value
Description:
Set the initialised distance uncertainty for a tracker. Setting this to a negative number will remove the initialised uncertainty value from the tracker.
Example:
t= pfpy.getTrackerRef(0)
t.setInitialisedDistance(10.0)
t.setInitialisedUncertainty(0.5)
Command:
getInPoint()
Parameters:
none
Description:
Returns the frame number for the tracker in-point.
Example:
t= pfpy.getTrackerRef(0)
print("Tracker in/out is ", t.getInPoint(), t.getOutPoint())
Command:
setInPoint(frame)
Parameters:
integer: frame number
Description:
Set the tracker in-point to the specified frame number
Example:
t= pfpy.getTrackerRef(0)
t.setInPoint(1)
t.setOutPoint(20)
Command:
getOutPoint()
Parameters:
none
Description:
Returns the frame number for the tracker out-point.
Example:
t= pfpy.getTrackerRef(0)
print("Tracker in/out is ", t.getInPoint(), t.getOutPoint())
Command:
setOutPoint(frame)
Parameters:
integer: frame number
Description:
Set the tracker out-point to the specified frame number
Example:
t= pfpy.getTrackerRef(0)
t.setInPoint(1)
t.setOutPoint(20)
Command:
getPointColour()
Parameters:
none
Description:
Returns the 3D point colour for the tracker as three integers in the range [0..255].
Example:
t= pfpy.getTrackerRef(0)
col= t.getPointColour()
print("Red is ", col[0])
print("Green is ", col[1])
print("Blue is ", col[2])
Command:
setPointColour(red, green, blue)
Parameters:
integer: colour values in the range [0..255]
Description:
Set the 3D point colour for the tracker.
Example:
t= pfpy.getTrackerRef(0)
t.setPointColour(84, 128, 256)