 |
PFTrack Documentation | Python Node API |
Lens Distortion module API
Accessing lens distortion models | Creating new lenses | API functionsAccessing 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 coefficients 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.
Command:
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()
Command:
getName()
Parameters:
none
Description:
Returns the name of the lens
Example:
l= pfpy.getLensRef(0)
print("lens name is", l.getName())
Command:
setName(name)
Parameters:
string lens name
Description:
Set the lens name to the string
Example:
l= pfpy.getLensRef(0)
l.setName("myLens")
Command:
getModel()
Parameters:
none
Description:
Returns the name of the distortion model:
- Standard: refers to the standard two-parameter distortion model used for measured and 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())
Command:
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())
Command:
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)
Command:
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())
Command:
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])
Command:
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 Simple 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)
Command:
getK1(focalmm)
Parameters:
floating point focal length, measured in millimetres
Description:
Returns the k1 distortion coefficient at a particular focal length. Can only be read for the Standard distortion model.
Example:
l= pfpy.getLensRef(0)
# fetch k1 distortion coefficient at 10mm focal length
print("coefficient is", l.getK1(10.0))
Command:
setK1(focalmm, value)
Parameters:
floating point focal length (measured in millimetres), floating point value
Description:
Set the k1 coefficient at a particular focal length. Can only be set for the Standard distortion model.
Example:
l= pfpy.getLensRef(0)
# set the k1 distortion coefficient at 10mm focal length
l.setK1(10.0, 0.07)
Command:
getK2(focalmm)
Parameters:
floating point focal length, measured in millimetres
Description:
Returns the k2 distortion coefficient at a particular focal length. Can only be read for the Standard distortion model.
Example:
l= pfpy.getLensRef(0)
# fetch k2 distortion coefficient at 10mm focal length
print("coefficient is", l.getK2(10.0))
Command:
setK2(focalmm, value)
Parameters:
floating point focal length (measured in millimetres), floating point value
Description:
Set the k2 coefficient at a particular focal length. Can only be set for the Standard distortion model.
Example:
l= pfpy.getLensRef(0)
# set the k2 distortion coefficient at 10mm focal length
l.setK2(10.0, 0.13)
Command:
undistortPoint(focalmm, invfocusm, x, y)
Parameters:
floating point focal length (measured in millimetres)
floating point inverse focus distance (measured in meters)
floating point x and y distorted pixel coordinates
Description:
Calculate the undistorted coordinates corresponding to a distorted pixel (use undistortSTPointFrame for ST-maps). Please note: due to the need to numerically invert some of the more advanced lens models, undistorting and then re-distorting a coordinate may not exactly match the original values. Typically, differences are only a fraction of a pixel and should not cause any visual issues.
Example:
# fetch the lens model
lens= pfpy.getLensRef(0)
# set the focal length and inverse focus distance
focalmm= 45.0
focusm= 5.0
print("focal=", focal,"mm")
print("focus=", focus,"m")
x= 100.0
y= 75.0
# undistort pixel (100, 75)
pt= lens.undistortPoint(focalmm, 1.0/focusm, 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(focalm, 1.0/focusm, pt[0], pt[1])
print('%f'%(pt[0])+', %f'%(pt[1])+' distorts back to %f'%(orig[0])+', %f'%(orig[1]))
Command:
distortPoint(focal, invfocus, x, y)
Parameters:
floating point focal length (measured in millimetres)
floating point inverse focus distance (measured in meters)
floating point x and y undistorted pixel coordinates
Description:
Calculate the distorted coordinates corresponding to an undistorted pixel (use distortSTPointFrame for ST-maps). Please note: due to the need to numerically invert some of the more advanced lens models, undistorting and then re-distorting a coordinate may not exactly match the original values. Typically, differences are only a fraction of a pixel and should not cause any visual issues.
Example:
# fetch the lens model
lens= pfpy.getLensRef(0)
# set the focal length and inverse focus distance
focalmm= 45.0
focusm= 5.0
print("focal=", focal,"mm")
print("focus=", focus,"m")
x= 100.0
y= 75.0
# undistort pixel (100, 75)
pt= lens.undistortPoint(focalmm, 1.0/focusm, 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(focalm, 1.0/focusm, pt[0], pt[1])
print('%f'%(pt[0])+', %f'%(pt[1])+' distorts back to %f'%(orig[0])+', %f'%(orig[1]))
Command:
undistortPointFrame(frame, x, y)
Parameters:
integer frame number
floating point x and y distorted pixel coordinates
Description:
Calculate the undistorted coordinates corresponding to a distorted pixel using the current camera (use undistortSTPointFrame for ST-maps). Please note: due to the need to numerically invert some of the more advanced lens models, undistorting and then re-distorting a coordinate may not exactly match the original values. Typically, differences are only a fraction of a pixel and should not cause any visual issues.
Example:
# fetch the lens model
lens= pfpy.getLensRef(0)
x= 100.0
y= 75.0
# undistort pixel (100, 75)
pt= lens.undistortPointFrame(frame, 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.distortPointFrame(frame, pt[0], pt[1])
print('%f'%(pt[0])+', %f'%(pt[1])+' distorts back to %f'%(orig[0])+', %f'%(orig[1]))
Command:
distortPointFrame(frame, x, y)
Parameters:
integer frame number
floating point x and y undistorted pixel coordinates
Description:
Calculate the distorted coordinates corresponding to an undistorted pixel using the current camera (use distortSTPointFrame for ST-maps). Please note: due to the need to numerically invert some of the more advanced lens models, undistorting and then re-distorting a coordinate may not exactly match the original values. Typically, differences are only a fraction of a pixel and should not cause any visual issues.
Example:
# fetch the lens model
lens= pfpy.getLensRef(0)
x= 100.0
y= 75.0
# undistort pixel (100, 75)
pt= lens.undistortPointFrame(frame, 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.distortPointFrame(frame, pt[0], pt[1])
print('%f'%(pt[0])+', %f'%(pt[1])+' distorts back to %f'%(orig[0])+', %f'%(orig[1]))
Command:
undistortSTPoint(frame, x, y)
Parameters:
integer frame number
floating point x and y distorted pixel coordinates
Description:
Calculate the undistorted coordinates corresponding to a distorted pixel using the ST-Map for the frame (Please note: due to the need to numerically invert the ST-map, undistorting and then re-distorting a coordinate may not exactly match the original values. Typically, differences are only a fraction of a pixel and should not cause any visual issues).
Example:
# fetch the lens model
lens= pfpy.getLensRef(0)
frame= 10
x= 100.0
y= 75.0
# undistort pixel (100, 75)
pt= lens.undistortSTPointFra,e(frame, 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.distortSTPointFrame(frame, pt[0], pt[1])
print('%f'%(pt[0])+', %f'%(pt[1])+' distorts back to %f'%(orig[0])+', %f'%(orig[1]))
Command:
distortPointFrame(frame, x, y)
Parameters:
integer frame number
floating point x and y undfistorted pixel coordinates
Description:
Calculate the distorted coordinates corresponding to an undistorted pixel using the ST-Map for the frame (Please note: due to the need to numerically invert the ST-map, undistorting and then re-distorting a coordinate may not exactly match the original values. Typically, differences are only a fraction of a pixel and should not cause any visual issues).
Example:
# fetch the lens model
lens= pfpy.getLensRef(0)
frame= 10
x= 100.0
y= 75.0
# undistort pixel (100, 75)
pt= lens.undistortSTPointFra,e(frame, 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.distortSTPointFrame(frame, pt[0], pt[1])
print('%f'%(pt[0])+', %f'%(pt[1])+' distorts back to %f'%(orig[0])+', %f'%(orig[1]))