Camera module API
Accessing cameras
The number of cameras being passed into the node can be found:
num= pfpy.getNumCameras()
print("node is reading", num, "cameras")
Generally, this is the same as the number of inputs the node has. A reference to an existing camera can be obtained as follows:
c= pfpy.getCameraRef(input)
where input is an integer indicating which input to fetch a camera from, in the range 0 to N-1 inclusive, where N is the number of cameras returned by pfpy.getNumCameras(). Note that if a node input exists but does not have a camera passed to it, the getCameraRef function may return a null value.
By calling the Camera API functions described below, camera data can be modified before being passed down-stream. The internal camera can be copied and freed as follows:
c= pfpy.getCameraRef(0)
cc= c.copy()
# do stuff to modify c
cc.freeCopy()
Copying a camera in this way allows original camera data to be read from the copy, regardless of how the actual camera is then modified by the script. An example of this copying process in action is given in the filterTracks.py example script.
Creating new cameras
To create a new camera, use the new function:
c= pfpy.Camera.new(output, name)
This will create a new camera with the specified name ready to be modified in the script and then passed down-stream through the numbered output connector. An example is given below:
c= pfpy.Camera.new(0, 'myCamera')
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 camera. If a frame number is specified, only keys at that frame will be removed.
Example:
c= pfpy.getCameraRef(0)
c.removeKeys()
c1= pfpy.getCameraRef(1)
c1.removeKeys(11)
c1.removeKeys(12)
Command:
fixRotationFlips()
Parameters:
none
Description:
Prevents Euler angles flipping by +/- 360 degrees
Example:
c= pfpy.getCameraRef(0)
c.fixRotationFlips()
Command:
isKeyed(frame)
Parameters:
integer frame number
Description:
Returns true if the camera is keyed at a particular frame
Example:
c= pfpy.getCameraRef(0)
if c.isKeyed(10) :
# do something
Command:
isTracked(frame)
Parameters:
integer frame number
Description:
Returns true if the camera is tracked at a particular frame.
Example:
c= pfpy.getCameraRef(0)
if c.isTracked(10) :
# do something
Command:
getName()
Parameters:
none
Description:
Returns the camera name
Example:
c= pfpy.getCameraRef(0)
print("Camera is named", c.getName())
Command:
setName(name)
Parameters:
string camera name
Description:
Sets the camera name to the string
Example:
c= pfpy.getCameraRef(0)
c.setName("myName")
Command:
getFrameRate()
Parameters:
none
Description:
Returns the camera's frame rate, measured in frames-per-second.
Example:
c= pfpy.getCameraRef(0)
print("frame rate is", c.getFrameRate())
Command:
setFrameRate(rate)
Parameters:
floating point frame rate
Description:
Set the camera frame rate.
Example:
c= pfpy.getCameraRef(0)
c.setFrameRate(30.0)
Command:
getExport()
Parameters:
none
Description:
Returns True if the camera has been flagged for export by an Export node. Note that cameras are flagged for export by default
Example:
c= pfpy.getCameraRef(0)
print("Export camera: ", c.getExport())
Command:
setExport(state)
Parameters:
boolean state
Description:
Flag the camera for export or not. Note that cameras are flagged for export by default
Example:
c= pfpy.getCameraRef(0)
c.setExport(False)
Command:
getInPoint()
Parameters:
none
Description:
Returns the camera in point
Example:
c= pfpy.getCameraRef(0)
print("in point is", c.getInPoint())
Command:
setInPoint(frame)
Parameters:
integer frame number
Description:
Set the camera in point to the frame number.
Example:
c= pfpy.getCameraRef(0)
c.setInPoint(10)
Command:
getOutPoint()
Parameters:
none
Description:
Returns the camera out point
Example:
c= pfpy.getCameraRef(0)
print("out point is", c.getOutPoint())
Command:
setOutPoint(frame)
Parameters:
integer frame number
Description:
Set the camera out point to the frame number
Example:
c= pfpy.getCameraRef(0)
c.setOutPoint(90)
Command:
getPixelAspect()
Parameters:
none
Description:
Returns the camera pixel aspect ratio.
Example:
c= pfpy.getCameraRef(0)
print("pixel aspect is", c.getPixelAspect())
Command:
setPixelAspect(value)
Parameters:
floating point value
Description:
Set the camera pixel aspect ratio to the value.
Example:
c= pfpy.getCameraRef(0)
c.setPixelAspect(1.422222)
Command:
getSensorWidth(units)
Parameters:
string units 'cm' for centimeters, 'in' for inches, 'mm' for millimeters.
Description:
Returns the camera sensor width in the specified units
Example:
c= pfpy.getCameraRef(0)
print("sensor width is", c.getSensorWidth('mm'), "millimeters")
Command:
setSensorWidth(value, units)
Parameters:
floating point value, string units 'cm' for centimeters, 'in' for inches, 'mm' for millimeters
Description:
Set the camera film sensor width to thespecified value
Example:
c= pfpy.getCameraRef(0)
c.setSensorWidth(22.2, 'mm')
Command:
getSensorHeight(units)
Parameters:
string units 'cm' for centimeters, 'in' for inches, 'mm' for millimeters.
Description:
Returns the camera sensor height in the specified units
Example:
c= pfpy.getCameraRef(0)
print("sensor height is", c.getSensorHeight('mm'), "millimeters")
Command:
setSensorHeight(value, units)
Parameters:
floating point value, string units 'cm' for centimeters, 'in' for inches, 'mm' for millimeters
Description:
Set the camera sensor height to the specified value.
Example:
c= pfpy.getCameraRef(0)
c.setSensorHeight(14.8, 'mm')
Command:
getFocalType()
Parameters:
none
Description:
Returns a string containing the current camera focal type, 'constant' for constant focal, 'variable' for variable focal.
Example:
c= pfpy.getCameraRef(0)
print("camera focal type is", c.getFocalType())
Command:
setFocalType(type)
Parameters:
string type, 'constant' for constant focal, 'variable' for variable focal.
Description:
Set the camera focal type to either constant or variable.
Example:
c= pfpy.getCameraRef(0)
c.setFocalLength(1, 45.0, 'mm')
c.setFocalStatus('known')
c.setFocalType('constant')
Command:
getFocalStatus()
Parameters:
none
Description:
Returns a string containing the camera focal status, 'unknown' for unknown focal, 'known' for known focal, 'initialized' for initialized focal.
Example:
c= pfpy.getCameraRef(0)
print("camera focal status is", c.getFocalStatus())
Command:
setFocalStatus(status)
Parameters:
string status, 'unknown' for unknown focal, 'known' for known focal, 'initialized' for initialized focal
Description:
Set the camera focal status.
Example:
c= pfpy.getCameraRef(0)
c.setFocalLength(1, 45.0, 'mm')
c.setFocalStatus('known')
c.setFocalType('constant')
Command:
getFocalLength(frame, units)
Parameters:
integer frame number
string units, 'mm' for millimeters, 'cm' for centimeters, 'in' for inches, 'pix' for pixels
Description:
Returns the camera focal length at the frame in the desired units.
Example:
c= pfpy.getCameraRef(0)
print("focal at frame 30 is", c.getFocalLength(30, 'mm'), "millimeters")
Command:
setFocalLength(frame, value, units)
Parameters:
integer frame number
floating point value
string units, 'mm' for millimeters, 'cm' for centimeters, in' for inches, 'pix' for pixels
Description:
Set the camera focal length at the frame to the desired value.
Example:
c= pfpy.getCameraRef(0)
c.setFocalLength(1, 35.0, 'mm')
Command:
getMinFocalLength(units)
Parameters:
string units, 'mm' for millimeters, 'cm' for centimeters, in' for inches, 'pix' for pixels
Description:
Returns the minimum camera focal length (from the focal range) in the desired units.
Example:
c= pfpy.getCameraRef(0)
print("focal range is", c.getMinFocalLength('mm'), "to", c.getMaxFocalLength('mm'), "millimeters")
Command:
setMinFocalLength(value, units)
Parameters:
floating point value
string units, 'mm' for millimeters, 'cm' for centimeters, in' for inches, 'pix' for pixels
Description:
Set the minimum camera focal length (from the focal range) to the desired value.
Example:
c= pfpy.getCameraRef(0)
c.setMinFocalLength(10.0, 'mm')
c.setMaxFocalLength(30.0, 'mm')
Command:
getMaxFocalLength(units)
Parameters:
string units, 'mm' for millimeters, 'cm' for centimeters, in' for inches, 'pix' for pixels
Description:
Returns the maximum camera focal length (from the focal range) in the desired units.
Example:
c= pfpy.getCameraRef(0)
print("focal range is", c.getMinFocalLength('mm'), "to", c.getMaxFocalLength('mm'), "millimeters")
Command:
setMaxFocalLength(value, units)
Parameters:
floating point value
string units, 'mm' for millimeters, 'cm' for centimeters, in' for inches, 'pix' for pixels
Description:
Set the maximum camera focal length (from the focal range) to the desired value.
Example:
c= pfpy.getCameraRef(0)
c.setMinFocalLength(10.0, 'mm')
c.setMaxFocalLength(30.0, 'mm')
Command:
getHorizontalFOV(frame, units)
Parameters:
integer frame number
string units, 'deg' for degrees, 'rad' for radians.
Description:
Returns the horizontal camera field of view at the frame number.
Example:
c= pfpy.getCameraRef(0)
print("field of view is", c.getHorizontalFOV(1, 'deg'), "by", c.getVerticalFOV(1, 'deg'))
Command:
setHorizontalFOV(frame, value, units)
Parameters:
integer frame number
floating point value
string units, 'deg' for degrees, 'rad' for radians
Description:
Set the horizontal camera field of view at the frame number to the desired value.
Example:
c= pfpy.getCameraRef(0)
c.setHorizontalFOV(1, 40.0, 'deg')
c.setVerticalFOV(1, 30.0, 'deg')
Command:
getVerticalFOV(frame, units)
Parameters:
integer frame number
string units, 'deg' for degrees, 'rad' for radians.
Description:
Returns the vertical camera field of view at the frame number.
Example:
c= pfpy.getCameraRef(0)
print("field of view is", c.getHorizontalFOV(1, 'deg'), "by", c.getVerticalFOV(1, 'deg'))
Command:
setVerticalFOV(frame, value, units)
Parameters:
integer frame number
floating point value
string units, 'deg' for degrees, 'rad' for radians
Description:
Set the vertical camera field of view at the frame number to the desired value.
Example:
c= pfpy.getCameraRef(0)
c.setHorizontalFOV(1, 40.0, 'deg')
c.setVerticalFOV(1, 30.0, 'deg')
Command:
getFrameRectangle()
Parameters:
none
Description:
Returns the pixel coordinates of the image rectangle viewed by the camera.
Example:
c= pfpy.getCameraRef(0)
r= c.getFrameRect()
print("frame is", r[0], r[1], "to", r[2], r[3])
Command:
getFrameWidth()
Parameters:
none
Description:
Returns the width of the image rectangle viewed by the camera
Example:
c= pfpy.getCameraRef(0)
print("frame is", c.getFrameWidth(), "by", c.getFrameHeight())
Command:
getFrameHeight()
Parameters:
none
Description:
Returns the height of the image rectangle viewed by the camera
Example:
c= pfpy.getCameraRef(0)
print("frame is", c.getFrameWidth(), "by", c.getFrameHeight())
Command:
getPrincipalPoint()
Parameters:
none
Description:
Returns the principal point of the camera (i.e. the image centre)
Example:
c= pfpy.getCameraRef(0)
p= c.getPrincipalPoint()
print("principal point is", c[0], ",", c[1])
Command:
getScale(frame)
Parameters:
integer frame number
Description:
Returns the camera scale transformation at the frame
Example:
c= pfpy.getCameraRef(0)
print("scale at frame 20 is", c.getScale(20))
Command:
setScale(frame, value)
Parameters:
integer frame number
floating point value
Description:
Sets the camera scale at the frame to the desired value
Example:
c= pfpy.getCameraRef(0)
c.setScale(20, 0.5)
Command:
getTranslation(frame)
Parameters:
integer frame number
Description:
Returns the X, Y, Z camera translation at the frame
Example:
c= pfpy.getCameraRef(0)
t= c.getTranslation(20)
print("translation at frame 20 is", t[0], t[1], t[2])
Command:
setTranslation(frame, value)
Parameters:
integer frame number
floating point tuple of values
Description:
Sets the X, Y, Z camera translation at the frame.
Example:
c= pfpy.getCameraRef(0)
c.setScale(10, 1.0)
c.setTranslation(10, 0.5, 0.7, -0.3)
c.setEulerRotation(10, 0.0, 0.0, 10.0, 'zxy')
Command:
getEulerRotation(frame, order)
Parameters:
integer frame number
string order, 'xyz', 'zxy' or 'yxz'
Description:
Returns the X, Y, Z camera Euler rotations (in degrees and in the specified axis order) at the frame
Example:
c= pfpy.getCameraRef(0)
e= c.getEulerRotation(20, 'xyz')
print("euler rotation at frame 20 is", e[0], e[1], e[2])
Command:
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 camera Euler rotations (in degrees and in the specified axis order) at the frame.
Example:
c= pfpy.getCameraRef(0)
c.setScale(10, 1.0)
c.setTranslation(10, 0.5, 0.7, -0.3)
c.setEulerRotation(10, 0.0, 0.0, 10.0, 'zxy')
Command:
getQuaternionRotation(frame)
Parameters:
integer frame number
Description:
Returns the X, Y, Z, W camera quaternion rotation at the frame
Example:
c= pfpy.getCameraRef(0)
q= c.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 camera quaternion rotation at the frame.
Example:
c= pfpy.getCameraRef(0)
c.setScale(10, 1.0)
c.setTranslation(10, 0.5, 0.7, -0.3)
c.setQuaternionRotation(10, 0.0, 0.0, 0.0, 1.0)
Command:
getLookAt(frame)
Parameters:
integer frame number
Description:
Returns the X, Y, Z camera look-at position, and roll, for the frame
Example:
c= pfpy.getCameraRef(0)
l= c.getLookAt(20)
print("looking at", l[0], l[1], l[2])
print("roll is", l[3])
Command:
setLookAt(frame, value, roll)
Parameters:
integer frame number
floating point tuple of values
floating point roll angle
Description:
Sets the X, Y, Z camera look-at position and roll for the frame.
Example:
c= pfpy.getCameraRef(0)
c.setScale(10, 1.0)
c.setTranslation(10, 0.5, 0.7, -0.3)
c.setLookAt(10, 0.0, 0.0, 0.0, 10.0)
Command:
getXAxis(frame)
Parameters:
integer frame number
Description:
Returns the camera's X axis direction (right vector)
Example:
c= pfpy.getCameraRef(0)
x= c.getXAxis(10)
y= c.getYAxis(10)
z= c.getZAxis(10)
print("x axis is", x[0],x[1],x[2])
print("y axis is", y[0],y[1],y[2])
print("z axis is", z[0],z[1],z[2])
Command:
getYAxis(frame)
Parameters:
integer frame number
Description:
Returns the camera's Y axis direction (up vector)
Example:
c= pfpy.getCameraRef(0)
x= c.getXAxis(10)
y= c.getYAxis(10)
z= c.getZAxis(10)
print("x axis is", x[0],x[1],x[2])
print("y axis is", y[0],y[1],y[2])
print("z axis is", z[0],z[1],z[2])
Command:
getZAxis(frame)
Parameters:
integer frame number
Description:
Returns the camera's Z axis direction (view vector)
Example:
c= pfpy.getCameraRef(0)
x= c.getXAxis(10)
y= c.getYAxis(10)
z= c.getZAxis(10)
print("x axis is", x[0],x[1],x[2])
print("y axis is", y[0],y[1],y[2])
print("z axis is", z[0],z[1],z[2])
Command:
project(frame, point)
Parameters:
integer frame number and a floating point tuple
Description:
Projects the 3D point into the camera at the specified frame, returning a pixel coordinate.
Example:
# fetch the first camera
c= pfpy.getCameraRef(0)
# fetch the first tracker
t= pfpy.getTrackerRef(0)
# fetch the 3D tracker position
pos= t.getSolvedPos()
# project into the camera at frame 10
proj= c.project(10, pos)
print("projection is", proj[0],proj[1])
Command:
inFront(frame, point)
Parameters:
integer frame number and a floating point tuple
Description:
Returns True if the 3D point is infront of the camera in the specified frame.
Example:
# fetch the first camera
c= pfpy.getCameraRef(0)
# fetch the first tracker
t= pfpy.getTrackerRef(0)
# fetch the 3D tracker position
pos= t.getSolvedPos()
# is this point infront of the camera in frame 10?
infr= c.inFront(10, pos)
print("infront is", infr)