Fove SDK  v0.16.0
Public Member Functions | List of all members
fove.headset.Headset Class Reference

Class that manages accesses to headsets. More...

Inheritance diagram for fove.headset.Headset:
Inheritance graph
[legend]
Collaboration diagram for fove.headset.Headset:
Collaboration graph
[legend]

Public Member Functions

def __init__ (self, capabilities)
 Defines a headset with the given capabilities. More...
 
def __enter__ (self)
 Creates and tries to connect to the headset. More...
 
def __exit__ (self, _e_type, _e_val, _traceback)
 Frees resources used by a headset object, including memory and sockets. More...
 
def checkEyesClosed (self)
 Returns eyes that are closed. More...
 
def checkEyesTracked (self)
 Returns eyes that are being tracked. More...
 
def checkSoftwareVersions (self)
 Checks whether the client can run against the installed version of the FOVE SDK. More...
 
def createCompositor (self)
 Returns a compositor interface from the given headset. More...
 
def ensureEyeTrackingCalibration (self)
 Starts eye tracking calibration if not already calibrated. More...
 
def getEyeToHeadMatrices (self)
 Gets the matrices to convert from eye- to head-space coordintes. More...
 
def getGazeConvergence (self)
 Gets eye convergence data. More...
 
def getGazeVectors (self)
 Gets each eye's current gaze vector. More...
 
def getGazeVectors2d (self)
 Gets the user's 2D gaze position on the screens seen through the HMD's lenses. More...
 
def getHardwareInfo (self)
 Gets the information about the hardware information. More...
 
def getIOD (self)
 Gets interocular distance in meters. More...
 
def getLatestPose (self)
 Gets the pose of the head-mounted display. More...
 
def getProjectionMatricesLH (self, zNear, zFar)
 Gets the valoues of passed-in left-handed 4x4 projection matrices. More...
 
def getProjectionMatricesRH (self, zNear, zFar)
 Gets the valoues of passed-in right-handed 4x4 projection matrices. More...
 
def getRawProjectionValues (self)
 Gets values for the view frustum of both eyes at 1 unit away. More...
 
def getResearchHeadset (self, capabilities)
 Converts an existing headset object into a research headset. More...
 
def getSoftwareVersions (self)
 Gets the information about the current software versions. More...
 
def isEyeTrackingCalibrated (self)
 Checks if eye tracking has been calibrated. More...
 
def isEyeTrackingCalibrating (self)
 Checks if eye tracking is in the process of calibration. More...
 
def isEyeTrackingEnabled (self)
 Checks if eye tracking hardware has started. More...
 
def isEyeTrackingReady (self)
 Checks if eye tracking is actively tracking an eye - or eyes. More...
 
def isHardwareConnected (self)
 Checks whether the headset is connected or not. More...
 
def isHardwareReady (self)
 Checks whether the headset hardware has started. More...
 
def isMotionReady (self)
 Checks if motion tracking hardware has started. More...
 
def isPositionReady (self)
 Checks if position tracking hardware has started. More...
 
def startEyeTrackingCalibration (self, restartIfRunning)
 Starts eye tracking calibration. More...
 
def stopEyeTrackingCalibration (self)
 Stops eye tracking calibration. More...
 
def tareOrientationSensor (self)
 Tares the orientation of the headset. More...
 
def tarePositionSensors (self)
 Tares the position of the headset. More...
 
def waitForNextEyeFrame (self)
 Waits for next camera frame and associated eye tracking info becomes available. More...
 

Detailed Description

Class that manages accesses to headsets.

All Headset-related API requests will be done through an instance of this class.

The class provides Headset.__enter__ and Headset.__exit__ methods that do relevant resource managements, so the typical use of this class would be as follows:

with Headset(ClientCapabilities.Gaze + ClientCapabilities.Orientation) as headset:
# use headset
pass

Constructor & Destructor Documentation

◆ __init__()

def fove.headset.Headset.__init__ (   self,
  capabilities 
)

Defines a headset with the given capabilities.

This does not automatically create or connect to the headset. For that, the user has to call Headset.__enter__ (and call Headset.__exit__ when the headset is no longer needed) but consider using the with statement instead of manually calling them.

Parameters
capabilitiesThe desired capabilities (Gaze, Orientation, Position). For multiple capabilities, use arithmetic operators as in: ClientCapabilities.Gaze + ClientCapabilities.Position.
See also
Headset.__enter__

Member Function Documentation

◆ __enter__()

def fove.headset.Headset.__enter__ (   self)

Creates and tries to connect to the headset.

The result headset should be destroyed using Headset.__exit__ when no longer needed, but consider using the with statement instead of manually calling it.

Returns
A Headset object where the handle to the newly created headset is written upon success
Exceptions
RuntimeErrorWhen failed to create a headset
See also
Headset.__exit__

◆ __exit__()

def fove.headset.Headset.__exit__ (   self,
  _e_type,
  _e_val,
  _traceback 
)

Frees resources used by a headset object, including memory and sockets.

Upon return, this headset instance, and any research headsets from it, should no longer be used.

See also
Headset.__enter__

◆ isHardwareConnected()

def fove.headset.Headset.isHardwareConnected (   self)

Checks whether the headset is connected or not.

Returns
True if an HMD is known to be connected, False otherwise (including the case when any error detected that might make the query result unreliable).
See also
Headset.createHeadset

◆ isHardwareReady()

def fove.headset.Headset.isHardwareReady (   self)

Checks whether the headset hardware has started.

Returns
True if the hardware for the requested capabilities has started, False otherwise (including the case when any error detected that might make the query result unreliable)

◆ checkSoftwareVersions()

def fove.headset.Headset.checkSoftwareVersions (   self)

Checks whether the client can run against the installed version of the FOVE SDK.

Returns
capi.ErrorCode.None_ if this client is compatible with the currently running service
Exceptions
RuntimeErrorif not compatible with the currently running service

◆ getSoftwareVersions()

def fove.headset.Headset.getSoftwareVersions (   self)

Gets the information about the current software versions.

Allows you to get detailed information about the client and runtime versions. Instead of comparing software versions directly, you should simply call Headset.checkSoftwareVersions to ensure that the client and runtime are compatible.

Returns
information about the current software versions, or None in case of API failure.

◆ getHardwareInfo()

def fove.headset.Headset.getHardwareInfo (   self)

Gets the information about the hardware information.

Allows you to get serial number, manufacturer, and model name of the headset.

Returns
information about the hardware, or None in case of API failure.

◆ waitForNextEyeFrame()

def fove.headset.Headset.waitForNextEyeFrame (   self)

Waits for next camera frame and associated eye tracking info becomes available.

Allows you to sync your eye tracking loop to the actual eye-camera loop. On each loop, you would first call this blocking function to wait for a new frame and then proceed to consume eye tracking info accociated with the frame.

Returns
(bool, Optional[bool])
The first return value is True if it successfully synced with the camera frames; otherwise it is False.
When the first return value is False, the second return value indicates whether the error is permanent: i.e. it is False when the call to an internal API has just timed out and retry on the client side might be useful; it is otherwise True, e.g. if the Gaze capability was not registered.

◆ getGazeVectors()

def fove.headset.Headset.getGazeVectors (   self)

Gets each eye's current gaze vector.

Note: the underlying API in fove.capi allows one to get only one of the two (left/right) gaze vectors, but here both vectors will always be returned.

Returns
(Optional[capi.GazeVector], Optional[capi.GazeVector])
left eye gaze vector, or None in case of API failure
right eye gaze vector, or None in case of API failure

◆ getGazeVectors2d()

def fove.headset.Headset.getGazeVectors2d (   self)

Gets the user's 2D gaze position on the screens seen through the HMD's lenses.

The use of lenses and distortion correction creates a screen in front of each eye. This function returns 2D vectors representing where on each eye's screen the user is looking.

The vectors are normalized in the range [-1, 1] along both X and Y axes such that the following points are true:

  • Center: (0, 0)
  • Bottom-Left: (-1, -1)
  • Top-Right: (1, 1)
Returns
(Optional[capi.Vec2], Optional[capi.Vec2])
left eye gaze point in the HMD's virtual screen space
right eye gaze point in the HMD's virtual screen space

◆ getGazeConvergence()

def fove.headset.Headset.getGazeConvergence (   self)

Gets eye convergence data.

Returns
the convergence data, or None in case of API failure

◆ checkEyesClosed()

def fove.headset.Headset.checkEyesClosed (   self)

Returns eyes that are closed.

Returns
eyes that are closed encoded as capi.Eye, or None in case of API failure

◆ checkEyesTracked()

def fove.headset.Headset.checkEyesTracked (   self)

Returns eyes that are being tracked.

Returns
eyes that are being tracked encoded as capi.Eye, or None in case of API failure

◆ isEyeTrackingEnabled()

def fove.headset.Headset.isEyeTrackingEnabled (   self)

Checks if eye tracking hardware has started.

Returns
whether eye tracking hardware has started, or None in case of API failure

◆ isEyeTrackingCalibrated()

def fove.headset.Headset.isEyeTrackingCalibrated (   self)

Checks if eye tracking has been calibrated.

Returns
whether eye tracking hardware has been calibrated, or None in case of API failure

◆ isEyeTrackingCalibrating()

def fove.headset.Headset.isEyeTrackingCalibrating (   self)

Checks if eye tracking is in the process of calibration.

Returns
whether eye tracking is in the process of calibration, or None in case of API failure

◆ isEyeTrackingReady()

def fove.headset.Headset.isEyeTrackingReady (   self)

Checks if eye tracking is actively tracking an eye - or eyes.

Returns
whether eye tracking is active, or None in case of API failure

◆ isMotionReady()

def fove.headset.Headset.isMotionReady (   self)

Checks if motion tracking hardware has started.

Returns
whether motion tracking hardware has started, or None in case of API failure

◆ tareOrientationSensor()

def fove.headset.Headset.tareOrientationSensor (   self)

Tares the orientation of the headset.

Returns
None

◆ isPositionReady()

def fove.headset.Headset.isPositionReady (   self)

Checks if position tracking hardware has started.

Returns
whether position tracking hardware has started, or None in cased of API failure

◆ tarePositionSensors()

def fove.headset.Headset.tarePositionSensors (   self)

Tares the position of the headset.

Returns
None

◆ getLatestPose()

def fove.headset.Headset.getLatestPose (   self)

Gets the pose of the head-mounted display.

Returns
Current pose of the head-mounted display, or None in case of API failure

◆ getProjectionMatricesLH()

def fove.headset.Headset.getProjectionMatricesLH (   self,
  zNear,
  zFar 
)

Gets the valoues of passed-in left-handed 4x4 projection matrices.

Gets 4x4 projection matrices for both eyes using near and far planes in a left-handed coordinate system.

Note: the underlying API in fove.capi allows one to get only one of the two (left/right) projection matrices, but here both matrices will always be returned.

Parameters
zNearThe near plane in float, Range: from 0 to zFar
zFarThe far plane in float, Range: from zNear to infinity
Returns
(Optional[capi.Matrix44], Optional[capi.Matrix44])
left 4x4 projection matrix (left-handed), or None in case of API failure
right 4x4 projection matrix (left-handed), or None in case of APi failure

◆ getProjectionMatricesRH()

def fove.headset.Headset.getProjectionMatricesRH (   self,
  zNear,
  zFar 
)

Gets the valoues of passed-in right-handed 4x4 projection matrices.

Gets 4x4 projection matrices for both eyes using near and far planes in a right-handed coordinate system.

Note: the underlying API in fove.capi allows one to get only one of the two (left/right) projection matrices, but here both matrices will always be returned.

Parameters
zNearThe near plane in float, Range: from 0 to zFar
zFarThe far plane in float, Range: from zNear to infinity
Returns
(Optional[capi.Matrix44], Optional[capi.Matrix44])
left 4x4 projection matrix (left-handed), or None in case of API failure
right 4x4 projection matrix (left-handed), or None in case of API failure

◆ getRawProjectionValues()

def fove.headset.Headset.getRawProjectionValues (   self)

Gets values for the view frustum of both eyes at 1 unit away.

Gets values for the view frustum of the specified eye at 1 unit away. Please multiply them by zNear to convert to your correct frustum near-plane. Either outLeft or outRight may be nullptr to only write the other struct, however setting both to nullptr is considered and error and the function will return Fove_ErrorCode::API_NullOutPointersOnly.

Returns
(Optional[capi.ProjectionParams],Optional[capi.ProjectionParams])
the struct describing the left camera projection parameters, or None in case of API failure
the struct describing the right camera projection parameters, or None in case of API failure

◆ getEyeToHeadMatrices()

def fove.headset.Headset.getEyeToHeadMatrices (   self)

Gets the matrices to convert from eye- to head-space coordintes.

This is simply a translation matrix that returns +/- IOD/2

Returns
(Optional[capi.Matrix44], Optional[capi.Matrix44])
the matrix describing left-eye transform data, or None in case of API failure
the matrix describing right-eye transform data, or None in case of API failure

◆ getIOD()

def fove.headset.Headset.getIOD (   self)

Gets interocular distance in meters.

This is an estimation of the distance between centers of the left and right eyeballs. Half of the IOD can be used to displace the left and right cameras for stereoscopic rendering. We recommend calling this each frame when doing stereoscoping rendering. Future versions of the FOVE service may update the IOD during runtime as needed.

Returns
A floating point value describing the IOD, or None in case of API failure

◆ ensureEyeTrackingCalibration()

def fove.headset.Headset.ensureEyeTrackingCalibration (   self)

Starts eye tracking calibration if not already calibrated.

Does nothing if the user is already calibrated. Does nothing if the calibration is currently running. All eye tracking content should call this before using the gaze to ensure that there's a valid calibration. After calling this, content should periodically poll for Headset.isEyeTrackingCalibrating to become false, so as to ensure that the content is not updating while obscured by the calibrator

Returns
True if the request has been successfully made, None otherwise.

◆ startEyeTrackingCalibration()

def fove.headset.Headset.startEyeTrackingCalibration (   self,
  restartIfRunning 
)

Starts eye tracking calibration.

Parameters
restartIfRunningIf True, this will cause the calibration to restart if it's already running. Otherwise this will do nothing if eye tracking calibration is currently running.
Returns
True if the request has been successfully made, None otherwise.

◆ stopEyeTrackingCalibration()

def fove.headset.Headset.stopEyeTrackingCalibration (   self)

Stops eye tracking calibration.

Returns
True if the request has been successfully made, None otherwise.

◆ createCompositor()

def fove.headset.Headset.createCompositor (   self)

Returns a compositor interface from the given headset.

Each call to this function creates a new object. Once Compositor.__enter__ is called on the object, it should be destroyed with Compositor.__exit__.

It is fine to call this function multiple times with the same headset. It is ok for the compositor to outlive the headset passed in.

See also
Compositor
Compositor.__enter__
Compositor.__exit__

◆ getResearchHeadset()

def fove.headset.Headset.getResearchHeadset (   self,
  capabilities 
)

Converts an existing headset object into a research headset.

The research API does not provide backwards or forwards compatibility with different FOVE runtimes. Do not release general purpose software using this API, this is meant for researcher user in a controlled environment (lab). The result ResearchHeadset is destroyed when the input headset object is destroyed. There is no destroy/free function for the research headset specifically.

Parameters
capsThese capabilities are automatically passed to ResearchHeadset_registerCapabilities so as to avoid an extra call
outHeadsetA pointer where the address of the newly created research headset object will be written upon success