Lens Distortion module API
Accessing lens distortion models
The number of lens distortion models being passed into the node is the same as the number of cameras, and can be found as follows:
num= pfpy.getNumCameras()
print("node is reading", num, "cameras and lenses")
A reference to an existing lens object can be obtained as follows:
l= pfpy.getLensRef(input)
where input is an integer indicating which input to fetch a lens from, in the range 0 to N-1 inclusive, where N is the number returned by pfpy.getNumCameras().
By calling the Lens API functions described below, lens data can be access and modified before being passed down-stream.
The internal lens object can be copied and freed as follows:
l= pfpy.getLensRef(0)
lc= l.copy()
# do stuff
lc.freeCopy()
Copying a lens in this way allows original data to be read from the copy, regardless of how the actual lens is then modified by the script. An example of this copying process in action is given in the filterTracks.py example script.
Creating new lenses
To create a new lens, use the new function:
l= pfpy.Lens.new(output, name)
This will create a new lens with Standard
distortion model and 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:
l= pfpy.Lens.new(0, 'myLens')
API functions
Examples of these functions in use are provided by the python scripts available in the exports, macros and nodes installation folders.
removeKeys()
Parameters:
none
Description:
Remove keyed parameter values from the lens. Can only be done for the Standard
distortion model.
Example:
l= pfpy.getLensRef(0)
l.removeKeys()
getName()
Parameters:
none
Description:
Returns the name of the lens
Example:
l= pfpy.getLensRef(0)
print("lens name is", l.getName())
setName(name)
Parameters:
string lens name
Description:
Set the lens name to the string
Example:
l= pfpy.getLensRef(0)
l.setName("myLens")
getModel()
Parameters:
none
Description:
Returns the name of the distortion model:
Standard
: refers to the standard single-parameter distortion model used for automatic lens distortion correction. This is the only model from which lens distortion parameters can be read or modified.Spherical
: the spherical lens model available in the Movie Camera Presets (this also refers to the normal lens model available in the Photo Camera Presets.Anamorphic
: the anamorphic lens model available in the Movie Camera Presets.Wide Angle
: the wide-angle lens model provided by the Photo Camera Presets.Pre-Corrected
: the pre-corrected lens model provided by the Photo Camera Presets.External ST Map
: lens distortion is provided by an external ST-Map, loaded in the Clip Input or Photo Input nodes.
Example:
l= pfpy.getLensRef(0)
print("lens model is", l.getModel())
getConstant()
Parameters:
none
Description:
Returns a boolean indicating whether distortion is constant throughout the clip
Example:
l= pfpy.getLensRef(0)
print("constant distortion= ", l.getConstant())
setConstant(boolean)
Parameters:
boolean flag
Description:
Indicate that the distortion coefficients should be constant throughout the clip. Once distortion is flagged as constant, all keyframes will be removed as soon as a distortion coefficient is set using setDistortion().
Example:
l= pfpy.getLensRef(0)
l.setConstant(True)
l.setDistortion(10.0, 0.05)
getSqueeze()
Parameters:
none
Description:
Returns the anamorphic squeeze value (can only be read for the Anamorphic
distortion model)
Example:
l= pfpy.getLensRef(0)
print("squeeze is", l.getSqueeze())
getCentre(focal)
Parameters:
floating point focal length, measured in millimetres
Description:
Returns the centre of lens distortion (as a fraction of frame size) at a particular focal length.
Example:
l= pfpy.getLensRef(0)
# fetch distortion centre at 10mm focal length
c= l.getCentre(10.0)
print("centre is", c[0], ",", c[1])
setCentre(focal, x, y)
Parameters:
floating point focal length (measured in millimetres), floating point x and y fractions
Description:
Set the centre of lens distortion(as a fraction of frame size) at a particular focal length. Can only be set for the Standard
distortion model.
Example:
l= pfpy.getLensRef(0)
# set the lens centre to (0.5, 0.5) at 10mm focal length
l.setCentre(10.0, 0.5, 0.5)
getDistortion(focal)
Parameters:
floating point focal length, measured in millimetres
Description:
Returns the lens distortion coefficient at a particular focal length. Can only be read for the Standard
distortion model.
Example:
l= pfpy.getLensRef(0)
# fetch distortion coefficient at 10mm focal length
print("coefficient is", l.getDistortion(10.0))
setDistortion(focal, value)
Parameters:
floating point focal length (measured in millimetres), floating point value
Description:
Set the distortion coefficient at a particular focal length. Can only be set for the Standard
distortion model.
Example:
l= pfpy.getLensRef(0)
# set the distortion coefficient at 10mm focal length
l.setDistortion(10.0, 0.07)
undistortPoint(frame, focal, inWidth, inHeight, x, y)
Parameters:
integer frame number
floating point focal length (measured in millimetres)
integer inWidth and inHeight, corresponding to the resolution of the original distorted clip
floating point x and y pixel coordinates
Description:
Calculate the undistorted coordinates corresponding to a distorted pixel (use undistortSTPoint for ST-maps)
Example:
# fetch the camera, lens model and source clip
cam= pfpy.getCameraRef(0)
lens= pfpy.getLensRef(0)
clip= pfpy.getClipRef(0, True)
# fetch the original (distorted) frame size
inWidth= clip.getFrameWidth()
inHeight= clip.getFrameHeight()
print('in size= %d'%inWidth+' x %d'%inHeight)
# fetch the focal length at frame 10
frame= 10
focal= cam.getFocalLength(frame, 'mm')
print("focal=", focal,"mm")
x= 100.0
y= 75.0
# undistort pixel (100, 75)
pt= lens.undistortPoint(frame, focal, inWidth, inHeight, x, y)
print('%f'%x+', %f'%y+' undistorts to %f'%(pt[0])+', %f'%(pt[1]))
# re-distort these coordinates to get back to (100, 75)
orig= lens.distortPoint(frame, focal, inWidth, inHeight, pt[0], pt[1])
print('%f'%(pt[0])+', %f'%(pt[1])+' distorts back to %f'%(orig[0])+', %f'%(orig[1]))
distortPoint(frame, focal, inWidth, inHeight, x, y)
Parameters:
integer frame number
floating point focal length (measured in millimetres)
integer inWidth and inHeight, corresponding to the resolution of the original distorted clip
floating point x and y pixel coordinates
Description:
Calculate the distorted coordinates corresponding to an undistorted pixel (use distortSTPoint for ST-maps)
Example:
# fetch the camera, lens model and source clip
cam= pfpy.getCameraRef(0)
lens= pfpy.getLensRef(0)
clip= pfpy.getClipRef(0, True)
# fetch the original (distorted) frame size
inWidth= clip.getFrameWidth()
inHeight= clip.getFrameHeight()
print('in size= %d'%inWidth+' x %d'%inHeight)
# fetch the focal length at frame 10
frame= 10
focal= cam.getFocalLength(frame, 'mm')
print("focal=", focal,"mm")
x= 100.0
y= 75.0
# undistort pixel (100, 75)
pt= lens.undistortPoint(frame, focal, inWidth, inHeight, x, y)
print('%f'%x+', %f'%y+' undistorts to %f'%(pt[0])+', %f'%(pt[1]))
# re-distort these coordinates to get back to (100, 75)
orig= lens.distortPoint(frame, focal, inWidth, inHeight, pt[0], pt[1])
print('%f'%(pt[0])+', %f'%(pt[1])+' distorts back to %f'%(orig[0])+', %f'%(orig[1]))
undistortSTPoint(frame, inWidth, inHeight, x, y)
Parameters:
integer frame number
integer inWidth and inHeight, corresponding to the resolution of the original distorted clip
floating point x and y pixel coordinates
Description:
Calculate the undistorted coordinates corresponding to a distorted pixel using an ST-Map
Example:
# fetch the lens model and source clip
lens= pfpy.getLensRef(0)
clip= pfpy.getClipRef(0, True)
# fetch the original (distorted) frame size
inWidth= clip.getFrameWidth()
inHeight= clip.getFrameHeight()
print('in size= %d'%inWidth+' x %d'%inHeight)
frame= 10
x= 100.0
y= 75.0
# undistort pixel (100, 75)
pt= lens.undistortSTPoint(frame, inWidth, inHeight, x, y)
print('%f'%x+', %f'%y+' undistorts to %f'%(pt[0])+', %f'%(pt[1]))
# re-distort these coordinates to get back to (100, 75)
orig= lens.distortSTPoint(frame, inWidth, inHeight, pt[0], pt[1])
print('%f'%(pt[0])+', %f'%(pt[1])+' distorts back to %f'%(orig[0])+', %f'%(orig[1]))
distortPoint(frame, inWidth, inHeight, x, y)
Parameters:
integer frame number
integer inWidth and inHeight, corresponding to the resolution of the original distorted clip
floating point x and y pixel coordinates
Description:
Calculate the distorted coordinates corresponding to an undistorted pixel using an ST-Map
Example:
# fetch the lens model and source clip
lens= pfpy.getLensRef(0)
clip= pfpy.getClipRef(0, True)
# fetch the original (distorted) frame size
inWidth= clip.getFrameWidth()
inHeight= clip.getFrameHeight()
print('in size= %d'%inWidth+' x %d'%inHeight)
frame= 10
x= 100.0
y= 75.0
# undistort pixel (100, 75)
pt= lens.undistortSTPoint(frame, inWidth, inHeight, x, y)
print('%f'%x+', %f'%y+' undistorts to %f'%(pt[0])+', %f'%(pt[1]))
# re-distort these coordinates to get back to (100, 75)
orig= lens.distortSTPoint(frame, inWidth, inHeight, pt[0], pt[1])
print('%f'%(pt[0])+', %f'%(pt[1])+' distorts back to %f'%(orig[0])+', %f'%(orig[1]))