psychopy.tools.mathtools.lensCorrection

psychopy.tools.mathtools.lensCorrection(xys, coefK=(1.0,), distCenter=(0.0, 0.0), out=None, dtype=None)[source]

Lens correction (or distortion) using the division model with even polynomial terms.

Calculate new vertex positions or texture coordinates to apply radial warping, such as ‘pincushion’ and ‘barrel’ distortion. This is to compensate for optical distortion introduced by lenses placed in the optical path of the viewer and the display (such as in an HMD).

See references[1]_ for implementation details.

Parameters:
  • xys (array_like) – Nx2 list of vertex positions or texture coordinates to distort. Works correctly only if input values range between -1.0 and 1.0.

  • coefK (array_like or float) – Distortion coefficients K_n. Specifying multiple values will add more polynomial terms to the distortion formula. Positive values will produce ‘barrel’ distortion, whereas negative will produce ‘pincushion’ distortion. In most cases, two or three coefficients are adequate, depending on the degree of distortion.

  • distCenter (array_like, optional) – X and Y coordinate of the distortion center (eg. (0.2, -0.4)).

  • out (ndarray, optional) – Optional output array. Must be same shape and dtype as the expected output if out was not specified.

  • dtype (dtype or str, optional) – Data type for computations can either be ‘float32’ or ‘float64’. If out is specified, the data type of out is used and this argument is ignored. If out is not provided, ‘float64’ is used by default.

Returns:

Array of distorted vertices.

Return type:

ndarray

Notes

  • At this time tangential distortion (i.e. due to a slant in the display) cannot be corrected for.

References

Examples

Creating a lens correction mesh with barrel distortion (eg. for HMDs):

vertices, textureCoords, normals, faces = gltools.createMeshGrid(
    subdiv=11, tessMode='center')

# recompute vertex positions
vertices[:, :2] = mt.lensCorrection(vertices[:, :2], coefK=(5., 5.))

Back to top