psychopy.tools.viewtools
¶Tools for working with view projections for 2 and 3D rendering.
computeFrustum (scrWidth, scrAspect, scrDist) 
Calculate frustum parameters. 
generalizedPerspectiveProjection (…[, …]) 
Generalized derivation of projection and view matrices based on the physical configuration of the display system. 
orthoProjectionMatrix (left, right, bottom, …) 
Compute an orthographic projection matrix with provided frustum parameters. 
perspectiveProjectionMatrix (left, right, …) 
Compute an perspective projection matrix with provided frustum parameters. 
lookAt (eyePos, centerPos, upVec) 
Create a transformation matrix to orient towards some point. 
pointToNdc (wcsPos, viewMatrix, projectionMatrix) 
Map the position of a point in world space to normalized device coordinates/space. 
psychopy.tools.viewtools.
computeFrustum
(scrWidth, scrAspect, scrDist, convergeOffset=0.0, eyeOffset=0.0, nearClip=0.01, farClip=100.0)¶Calculate frustum parameters. If an eye offset is provided, an asymmetric frustum is returned which can be used for stereoscopic rendering.
Parameters: 


Returns:  Namedtuple with frustum parameters. Can be directly passed to glFrustum (e.g. glFrustum(*f)). 
Return type:  Frustum 
Notes
The view point must be transformed for objects to appear correctly. Offsets in the Xdirection must be applied +/ eyeOffset to account for interocular separation. A transformation in the Zdirection must be applied to account for screen distance. These offsets MUST be applied to the MODELVIEW matrix, not the PROJECTION matrix! Doing so may break lighting calculations.
Examples
Creating a frustum and setting a window’s projection matrix:
scrWidth = 0.5 # screen width in meters
scrAspect = win.size[0] / win.size[1]
scrDist = win.scrDistCM * 100.0 # monitor setting, can be anything
frustum = viewtools.computeFrustum(scrWidth, scrAspect, scrDist)
# convert frustum to projection matrix
win.projectionMatrix = viewtools.perspectiveProjectionMatrix(*frustum)
# set your view matrix to account for the screen distance!!!
win.applyEyeTransform() # call before drawing
Offaxis frustums for stereo rendering:
# compute view matrix for each eye, these value usually don't change
eyeOffset = (0.035, 0.035) # +/ IOD / 2.0
leftProjMatrix = viewtools.perspectiveProjectionMatrix(
viewtools.computeFrustum(
scrWidth, scrAspect, scrDist, eyeOffset[0]))
rightProjMatrix = viewtools.computeFrustum(
viewtools.computeFrustum(
scrWidth, scrAspect, scrDist, eyeOffset[1]))
# ... after calling 'setBuffer('left')' ...
win.projectionMatrix = leftProjMatrix
# setup your view matrix accordingly, must account for screen distance
# and eye offset
win.applyViewTransform() # call before drawing
# do the same for 'setBuffer('right')' using the other matrix ...
psychopy.tools.viewtools.
generalizedPerspectiveProjection
(posBottomLeft, posBottomRight, posTopLeft, eyePos, nearClip=0.01, farClip=100.0)¶Generalized derivation of projection and view matrices based on the physical configuration of the display system.
This implementation is based on Robert Kooima’s ‘Generalized Perspective Projection’ (see http://csc.lsu.edu/~kooima/articles/genperspective/) method.
Parameters: 


Returns:  The 4x4 projection and view matrix. 
Return type: 
Notes
The resulting projection frustums are offaxis relative to the center of the display. The returned matrices are rowmajor. Values are floats with 32bits of precision stored as a contiguous (Corder) array.
psychopy.tools.viewtools.
orthoProjectionMatrix
(left, right, bottom, top, nearClip, farClip)¶Compute an orthographic projection matrix with provided frustum parameters.
Parameters: 


Returns:  4x4 projection matrix 
Return type:  ndarray 
Notes
The returned matrix is rowmajor. Values are floats with 32bits of precision stored as a contiguous (Corder) array.
psychopy.tools.viewtools.
perspectiveProjectionMatrix
(left, right, bottom, top, nearClip, farClip)¶Compute an perspective projection matrix with provided frustum parameters. The frustum can be asymmetric.
Parameters: 


Returns:  4x4 projection matrix 
Return type:  ndarray 
Notes
The returned matrix is rowmajor. Values are floats with 32bits of precision stored as a contiguous (Corder) array.
psychopy.tools.viewtools.
lookAt
(eyePos, centerPos, upVec)¶Create a transformation matrix to orient towards some point. Based on the same algorithm as ‘gluLookAt’. This does not generate a projection matrix, but rather the matrix to transform the observer’s view in the scene.
For more information see: https://www.khronos.org/registry/OpenGLRefpages/gl2.1/xhtml/gluLookAt.xml
Parameters: 


Returns:  4x4 view matrix 
Return type:  ndarray 
Notes
The returned matrix is rowmajor. Values are floats with 32bits of precision stored as a contiguous (Corder) array.
psychopy.tools.viewtools.
pointToNdc
(wcsPos, viewMatrix, projectionMatrix)¶Map the position of a point in world space to normalized device coordinates/space.
Parameters:  

Returns:  3x1 vector of normalized device coordinates with type ‘float32’ 
Return type:  ndarray 
Notes
The point is not visible, falling outside of the viewing frustum, if the returned coordinates fall outside of 1 and 1 along any dimension.
In the rare instance the point falls directly on the eye in world space where the frustum converges to a point (singularity), the divisor will be zero during perspective division. To avoid this, the divisor is ‘bumped’ to machine epsilon for the ‘float32’ type.
This function assumes the display area is rectilinear. Any distortion or warping applied in normalized device or viewport space is not considered.
Examples