Group module API
Accessing groups
The number of groups being passed into the node can be found:
num= pfpy.getNumGroups()
print("node is reading", num, "groups")
A reference to an existing group can be obtained as follows:
c= pfpy.getGroupRef(input)
where input is an integer indicating which input to fetch a group from, in the range 0 to N-1 inclusive, where N is the number of groups as returned by pfpy.getNumGroups().
By calling the Group API functions described below, group data can be modified before being passed down-stream. The internal group can be copied and freed as follows:
g= pfpy.getGroupRef(0)
gc= g.copy()
# do stuff
gc.freeCopy()
Copying a group in this way allows original group data to be read from the copy, regardless of how the actual group is then modified by the script. An example of this copying process in action is given in the filterTracks.py example script.
Creating new groups
To create a new group, use the new function:
g= pfpy.Group.new(name)
This will create a new group with the specified name ready to be modified in the script. An example is given below:
g= pfpy.Group.new('myGroup')
API functions
Examples of these functions in use are provided by the python scripts available in the exports, macros and nodes installation folders.
Command:
removeKeys(frame)
Parameters:
integer frame number (optional)
Description:
Removes keyed parameter values from the group. If a frame number is specified, only keys at that frame will be removed.
Example:
g= pfpy.getGroupRef(0)
g.removeKeys()
g1= pfpy.getGroupRef(1)
g1.removeKeys(11)
g1.removeKeys(12)
fixRotationFlips()
Parameters:
none
Description:
Prevents Euler angles flipping by +/- 360 degrees
Example:
g= pfpy.getGroupRef(0)
g.fixRotationFlips()
isCameraGroup()
Parameters:
none
Description:
Returns true if the trackers stored in the group were used for estimating camera motion
Example:
g= pfpy.getGroupRef(0)
if g.isCameraGroup() :
# do something
getNumTrackers()
Parameters:
none
Description:
Returns the number of trackers stored in the group
Example:
g= pfpy.getGroupRef(0)
print("First group has", g.getNumTrackers(), "trackers")
getTrackerRef(index, input)
Parameters:
integer tracker index, optional integer input number
Description:
Returns a reference to a tracker in the group. The index must be between zero and N-1 inclusive, where N is the number returned by getNumTrackers(). See the documentation on the Tracker module for more details. 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).
Example:
g= pfpy.getGroupRef(0)
# get a reference to the first tracker
t= g.getTrackerRef(0)
print("First tracker name is", t.getName())
isKeyed(frame)
Parameters:
integer frame number
Description:
Returns true if the group is keyed at a particular frame
Example:
g= pfpy.getGroupRef(0)
if g.isKeyed(10) :
# do something
isTracked(frame)
Parameters:
integer frame number
Description:
Returns true if the group is tracked at a particular frame.
Example:
g= pfpy.getGroupRef(0)
if g.isTracked(10) :
# do something
getName()
Parameters:
none
Description:
Returns the group name
Example:
g= pfpy.getGroupRef(0)
print("Group is named", g.getName())
setName(name)
Parameters:
string group name
Description:
Sets the group name to the string
Example:
g= pfpy.getGroupRef(0)
g.setName("myName")
getInPoint()
Parameters:
none
Description:
Returns the group in point
Example:
g= pfpy.getGroupRef(0)
print("in point is", g.getInPoint())
setInPoint(frame)
Parameters:
integer frame number
Description:
Set the group in point to the frame number.
Example:
g= pfpy.getGroupRef(0)
g.setInPoint(10)
getOutPoint()
Parameters:
none
Description:
Returns the group out point
Example:
g= pfpy.getGroupRef(0)
print("out point is", g.getOutPoint())
setOutPoint(frame)
Parameters:
integer frame number
Description:
Set the group out point to the frame number
Example:
g= pfpy.getGroupRef(0)
g.setOutPoint(90)
getScale(frame)
Parameters:
integer frame number
Description:
Returns the group scale transformation at the frame
Example:
g= pfpy.getGroupRef(0)
print("scale at frame 20 is", g.getScale(20))
setScale(frame, value)
Parameters:
integer frame number
floating point value
Description:
Sets the group scale at the frame to the desired value
Example:
g= pfpy.getGroupRef(0)
g.setScale(20, 0.5)
getTranslation(frame)
Parameters:
integer frame number
Description:
Returns the X, Y, Z group translation at the frame
Example:
g= pfpy.getGroupRef(0)
t= c.getTranslation(20)
print("translation at frame 20 is", t[0], t[1], t[2])
setTranslation(frame, value)
Parameters:
integer frame number
floating point tuple of values
Description:
Sets the X, Y, Z group translation at the frame.
Example:
g= pfpy.getGroupRef(0)
g.setScale(10, 1.0)
g.setTranslation(10, 0.5, 0.7, -0.3)
g.setEulerRotation(10, 0.0, 0.0, 10.0, 'zxy')
getEulerRotation(frame, order)
Parameters:
integer frame number
string order, 'xyz', 'zxy' or 'yxz'
Description:
Returns the X, Y, Z group Euler rotations (in degrees and in the specified axis order) at the frame
Example:
g= pfpy.getGroupRef(0)
e= c.getEulerRotation(20, 'xyz')
print("euler rotation at frame 20 is", e[0], e[1], e[2])
setEulerRotation(frame, value, order)
Parameters:
integer frame number
floating point tuple of values
string order, 'xyz', 'zxy' or 'yxz'
Description:
Sets the X, Y, Z group Euler rotations (in degrees and in the specified axis order) at the frame.
Example:
g= pfpy.getGroupRef(0)
g.setScale(10, 1.0)
g.setTranslation(10, 0.5, 0.7, -0.3)
g.setEulerRotation(10, 0.0, 0.0, 10.0, 'zxy')
Command:
getQuaternionRotation(frame)
Parameters:
integer frame number
Description:
Returns the X, Y, Z, W group quaternion rotation at the frame
Example:
g= pfpy.getGroupRef(0)
q= g.getQuaternionRotation(20)
print("quaternion at frame 20 is", q[0], q[1], q[2], q[3])
Command:
setQuaternionRotation(frame, value)
Parameters:
integer frame number
floating point quad of values
Description:
Sets the X, Y, Z, W group quaternion rotation at the frame.
Example:
g= pfpy.getGroupRef(0)
g.setScale(10, 1.0)
g.setTranslation(10, 0.5, 0.7, -0.3)
g.setQuaternionRotation(10, 0.0, 0.0, 0.0, 1.0)