Ocumen I/O - Python API
This page outlines the Python API for Tobii Ocumen I/O.
API Overview
Functions
Freestanding callables inside the module.
- init_logging - Initializes logging.
- process_log_messages - Process all outstanding log messages.
- version_ocumen_io_api - Returns the version of the used Ocumen IO API.
- version_ocumen_recording - Returns the version of the Ocumen recording format.
- matrix4_from_translation - Create a Matrix 4x4 with scale 1 translated to the given coordinates.
- matrix4_from_translation_rotation - Create a Matrix 4x4 with scale 1 from the given translation, rotation.
- matrix4_invert - Inverts a matrix, returning
NaN
s if not possible. - quaternion_from_angle_axis - Create a quaternion from the given angle around an axis.
Classes
Methods operating on common state.
- WorldView - Provides a view of an recording like Ocumen Studio.
- for_user ctor - Creates a view for the given user UUID.
- scrub_to - View the world as it appeared at the given time.
- collider_poses - Returns poses for all colliders at this time.
- entity_labels - Returns labels for each known entity at this time.
- gaze_binocular - Returns binocular (left / right) gaze data at this time.
- gaze_pupil_size - Returns pupil sizes at this time.
- gaze_convergence_distance - Returns the gaze convergence distance at this time.
- gaze_entrance_pupil - Returns the entrance pupil position at this time.
- frame_number - Returns the game’s frame number at this time.
- looked_at - Perform a raycast / ‘gaze to object’ test with the user’s gaze.
- WorldWriter - Creates
.ocumen
recordings.- from_uri ctor - Creates a recorder from a URI.
- from_callback ctor - Creates a sans-io recorder.
- handle_io - Writes cached data to files, network, a device …
- flush - Writes all outstanding data to the device.
- frame_number - Stores the frame number for a user at a given time.
- headset_camera - Stores the head set camera pose for a user at a given time.
- headset_views - Stores the head set stereo view matrices for a user at a given time.
- headset_projections - Stores the head set stereo projection matrices for a user at a given time.
- gaze_combined - Stores ‘combined’ gaze for a user at a given time.
- gaze_binocular - Stores binocular gaze for a user at a given time.
- gaze_eye_tracker_device_time - Stores the eye tracker’s device time stamp for a user at a given time.
- gaze_convergence_distance - Stores the gaze convergence distance for a user at a given time.
- gaze_position_guide - Stores gaze position guidance for a user at a given time.
- gaze_pupil_size_absolute - Stores absolute pupil size information for a user at a given time.
- gaze_entrance_pupil - Stores entrance pupil data for a user at a given time.
- gaze_blink_state - Stores blink state data for a user at a given time.
- instance_lifetime - Stores data whether objects / colliders are alive or not for a user at a given time.
- object_poses - Stores object poses for a user at a given time.
- object_meshes - Stores object meshes (geometry) for a user at a given time.
- mesh_data - Stores object mesh data for a user at a given time.
- entity_label - Stores an entity label for a user at a given time.
- collider_geometries - Stores simplified collider geometries for a user at a given time.
- collider_poses - Stores collider poses for a user at a given time.
- gizmos_3d - Stores debug gizmos for a user at a given time.
- image - Stores image data for a user at a given time.
- controller_button_state - Stores controller button state for a user at a given time.
- controller_poses - Stores controller poses for a user at a given time.
- video_frame - Stores a (rendered and compressed) video frame for a user at a given time.
- generic_descriptor - Obtains a low-level track handle to store custom data.
- generic_data - Store custom data for a track handle.
- WorldReader - Wraps a
WorldConnector
and provides methods to read XR events.- from_connector ctor - Creates a new reader from a connector.
- read_incremental - Read all (newly) available data.
- set_error_callback - Sets a callback invoked on read errors.
- tracked_data - Lists all track types known to exist in this recording.
- tracked_well_knowns - List generic handles and their type information.
- tracked_well_knowns_info - Returns meta data for track handles.
- list_users - Lists all users present in this recording.
- latest_meshes_for - Lists the latest available mesh data for a user in a time range.
- latest_entity_labels_for - Lists the latest entity labels for a user in a time range.
- latest_instance_lifetime_for - Lists the latest instance lifetime information for a user in a time range.
- latest_object_poses_for - Lists the latest object poses for a user in a time range.
- latest_object_meshes_for - Lists the latest object meshes for a user in a time range.
- latest_frame_numbers_for - Lists the latest frame number for a user in a time range.
- latest_headset_camera_for - Lists the latest headset camera pose for a user in a time range.
- latest_headset_projections_for - Lists the latest headset stereo projections for a user in a time range.
- latest_headset_views_for - Lists the latest headset stereo view matrices for a user in a time range.
- latest_gaze_combined_for - Returns the latest combined gaze for a user in a time range.
- latest_gaze_binocular_for - Returns the latest binocular gaze for a user in a time range.
- latest_gaze_device_time_for - Returns the latest eye tracking device data for a user in a time range.
- latest_gaze_convergence_distance_for - Returns the latest convergence distance for a user in a time range.
- latest_gaze_position_guide_for - Returns the latest position guide information for a user in a time range.
- latest_gaze_pupil_size_abs_for - Returns the latest pupil size absolute for a user in a time range.
- latest_gaze_blink_state_for - Returns the latest blink state for a user in a time range.
- latest_gaze_entrance_pupil_for - Returns the latest entrance pupil for a user in a time range.
- latest_collider_geometries_for - Lists the latest collider shapes for a user in a time range.
- latest_collider_poses_for - Lists the latest collider poses for a user in a time range.
- latest_gizmos_3d_for - Lists the latest debug gizmos for a user in a time range.
- image - Lists the latest image data for a user in a time range.
- latest_controller_button_states_for - Lists the latest controller button states for a user in a time range.
- latest_controller_poses_for - Lists the latest controller poses for a user in a time range.
- video_frames_meta - Returns the latest video frame descriptors for a user in a time range.
- video_frames - Lists the latest video frames for a user in a time range.
- video_frame_single_only - Returns the latest video frame for a user in a time range.
- video_frame_init_packet - Returns the latest video init packet for a user in a time range.
- generic_descriptor - Returns a specific generic descriptor.
- generic_count - Counts how many elements are available for the given descriptor.
- generic_data - Loads data for a generic descriptor.
- recording_information - Return common recording information.
- track_times - Lists all times for which data is available given a certain entry.
- WorldConnector - Handles stream endpoint connections to something speaking “Ocumen”.
- from_file ctor - Opens a file endpoint at the given path, e.g.,
/tmp/file.ocumen
orC:\file.ocumen
. - from_multiple_files ctor - Loads multiple recordings as one.
- from_network ctor - Opens a network endpoint at the given TCP address, e.g.,
127.0.0.1:6677
. - connection_state - Returns if all headers have been loaded from the network stream.
- app_version - Returns the application version embedded in this endpoint.
- stream_version - Returns the stream version of this endpoint.
- check_compatible - Check if the endpoint is compatible with this version.
- from_file ctor - Opens a file endpoint at the given path, e.g.,
- MultipleFiles - Helper for loading combined (stacked) recordings.
Enums
Groups of related constants.
- BlinkStatePerEye - Describes the openness of an eye in discrete steps. What exactly constitues
- ColliderType - The type of collider used in the game engine.
- ConnectionReadyState - Encodes if a (remote) connection is ready.
- CoordinateSystem - Gaze and similar data is usually recorded relative to the eye tracker. However, some
- FrameType - Describes what information a frame contains.
- ImageFormat - Video format of this frame.
- LogLevel - Log level for Ocumen functions.
- LookedAtWith - Specified with which eye(s) the hit test should be performed.
- ShapeType - How shape data is to be interpreted.
- TrackedData - Represents a ‘well known track’ contained in an Ocumen recording.
- VideoFormat - The video format of this frame.
- VideoTrack - The video format of this frame.
- WellKnownType - Some types are ‘well known’, that is, they have a definitive bit representation
- XRInputDevice - Which controller is being described.
Data Structs
Composite data used by functions and methods.
- BinocularGaze - Gaze rays for the left and right eye.
- BlinkState - Encodes blink states for each eye.
- CameraPose - View matrices of the combined camera sitting between both eyes.
- ColliderPose - Where in world space a collider resides.
- ColliderShape - Describes the shape of a collider.
- ColorRGB - Encodes a single color value in 8 bit RGB.
- CombinedGaze - Ray of a fictional, combined cyclops eye.
- ControllerButtonState - Described button states for a controller.
- ControllerPose - Where in world space a controller is.
- ConvergenceDistance - Closest distance of gaze convergence.
- Descriptor - Helper to request a descriptor from the recording library.
- EntityFrameTransform - Holds an update for a geometry’s transform. Usually given every frame.
- EntityLabel - Maps an entity ID to an ASCII label.
- EntityLabelID - Type-helper to store and retrieve labels for entities.
- EntrancePupilData - Entrance pupil data.
- EyeTrackerDeviceTimestamp - Timestamp reported by the eye tracker according to its own clock.
- FrameDimension - Dimension of the video frame in pixels.
- FrameMeta - Meta data about a video frame / packet when passing the packet around.
- Gizmo3D - Helper that can be attached to scenes to debug or visualize certain properties.
- ImageData - Image descriptor and data pointers.
- ImageDescriptor - Describes the data of a single video frame, as provided by encoderlib.
- InstanceLifetime - Holds information whether an entity is enabled.
- LogMessage - A single message recorded by our library.
- LoggerConfiguration - Configures how logging should be handled.
- Matrix4f32 - A 4x4 transformation matrix.
- Mesh - Identifies a series of vertices and indices describing an object.
- ObjectMesh - Links an object with a mesh.
- ObjectPose - Keeps pose data (translation, rotation, scale) for an object.
- Point2f32 - A point in 2D space.
- Point3f32 - A point in 3D space.
- PositionGuide - The 2D position of the eyes in the headset.
- PupilSizeAbsolute - Pupil diameter in millimeters for both eyes.
- PupilSizePerEye - Pupil diameter for the eye
- Quaternionf32 - A quaternion we use for vector operations.
- Rayf32 - A ray with an origin and direction.
- RecordingInformation - Recording meta data.
- Shape - A simple geometry expressable with just 3 points.
- StereoProjections - Projection matrices used for rendering.
- StereoViews - View matrices of each eye, i.e., where each eye / camera is in world space.
- TimeValueBinocularGaze - Contains a single value and its time.
- TimeValueBlinkState - Contains a single value and its time.
- TimeValueCombinedGaze - Contains a single value and its time.
- TimeValueConvergenceDistance - Contains a single value and its time.
- TimeValueEntrancePupilData - Contains a single value and its time.
- TimeValueEyeTrackerDeviceTimestamp - Contains a single value and its time.
- TimeValuePositionGuide - Contains a single value and its time.
- TimeValuePupilSizeAbsolute - Contains a single value and its time.
- TimesValuesCameraPose - Maps a series of values to corresponding times.
- TimesValuesColliderPose - Maps a series of values to corresponding times.
- TimesValuesColliderShape - Maps a series of values to corresponding times.
- TimesValuesGizmo3D - Maps a series of values to corresponding times.
- TimesValuesInstanceLifetime - Maps a series of values to corresponding times.
- TimesValuesObjectMesh - Maps a series of values to corresponding times.
- TimesValuesObjectPose - Maps a series of values to corresponding times.
- TimesValuesStereoProjections - Maps a series of values to corresponding times.
- TimesValuesStereoViews - Maps a series of values to corresponding times.
- TimesValuesu32 - Maps a series of values to corresponding times.
- TrackHandle - File-descriptor-like handle for one stream of data inside a recording.
- TrackedWellKnownInfo - Describes a track.
- UserAtTime - Specifies a user ID and associated time stamp in our API.
- UserInTimeRange - Specifies a user ID and associated time range in our API.
- Vector3f32 - A 3-dimensional vector.
- Version - Encodes a version number for our products, like
2.0.1
. - VideoFrame - Holds video meta information and actual video data.
- VideoFrameDescriptor - Describes the data of a single video frame, as provided by encoderlib.
- WellKnownTypedTrack - Maps a descriptor handle.
- SliceCameraPose - A pointer and length of un-owned elements.
- SliceColliderPose - A pointer and length of un-owned elements.
- SliceColliderShape - A pointer and length of un-owned elements.
- SliceControllerButtonState - A pointer and length of un-owned elements.
- SliceControllerPose - A pointer and length of un-owned elements.
- SliceEntityLabel - A pointer and length of un-owned elements.
- SliceGizmo3D - A pointer and length of un-owned elements.
- SliceImageData - A pointer and length of un-owned elements.
- SliceInstanceLifetime - A pointer and length of un-owned elements.
- SliceMesh - A pointer and length of un-owned elements.
- SliceObjectMesh - A pointer and length of un-owned elements.
- SliceObjectPose - A pointer and length of un-owned elements.
- SliceStereoProjections - A pointer and length of un-owned elements.
- SliceStereoViews - A pointer and length of un-owned elements.
- SliceTrackedData - A pointer and length of un-owned elements.
- SliceTrackedWellKnownInfo - A pointer and length of un-owned elements.
- SliceVector3f32 - A pointer and length of un-owned elements.
- SliceVideoFrame - A pointer and length of un-owned elements.
- SliceWellKnownTypedTrack - A pointer and length of un-owned elements.
- Slicei32 - A pointer and length of un-owned elements.
- Slicei64 - A pointer and length of un-owned elements.
- Sliceu32 - A pointer and length of un-owned elements.
- Sliceu64 - A pointer and length of un-owned elements.
- Sliceu8 - A pointer and length of un-owned elements.
- OptionBinocularGaze - A boolean flag and optionally data.
- OptionConvergenceDistance - A boolean flag and optionally data.
- OptionEntrancePupilData - A boolean flag and optionally data.
- OptionPupilSizeAbsolute - A boolean flag and optionally data.
- OptionTimeValueBinocularGaze - A boolean flag and optionally data.
- OptionTimeValueBlinkState - A boolean flag and optionally data.
- OptionTimeValueCombinedGaze - A boolean flag and optionally data.
- OptionTimeValueConvergenceDistance - A boolean flag and optionally data.
- OptionTimeValueEntrancePupilData - A boolean flag and optionally data.
- OptionTimeValueEyeTrackerDeviceTimestamp - A boolean flag and optionally data.
- OptionTimeValuePositionGuide - A boolean flag and optionally data.
- OptionTimeValuePupilSizeAbsolute - A boolean flag and optionally data.
- OptionVideoFrame - A boolean flag and optionally data.
- OptionVideoFrameDescriptor - A boolean flag and optionally data.
- Optionu32 - A boolean flag and optionally data.
Data Structs
BinocularGaze
Gaze rays for the left and right eye.
Coordinates in here are local space of the eye tracker, relative to a fictional
reference point between the eyes. To transform them to world space you need to use
the CameraPose
struct.
Fields
- left - Gaze origin and direction of the left eye.
- right - Gaze origin and direction of the right eye.
Definition
class BinocularGaze(ctypes.Structure):
_fields_ = [
("left", Rayf32),
("right", Rayf32),
]
def __init__(self, left: Rayf32 = None, right: Rayf32 = None):
...
BlinkState
Encodes blink states for each eye.
Fields
- left - Left eye blink state.
- right - Right eye blink state.
Definition
class BlinkState(ctypes.Structure):
_fields_ = [
("left", ctypes.c_int),
("right", ctypes.c_int),
]
def __init__(self, left: ctypes.c_int = None, right: ctypes.c_int = None):
...
CameraPose
View matrices of the combined camera sitting between both eyes.
Fields
- camera_to_world_matrix - The (assumed by non-existent) place where the camera that sits between both eyes would be. this is local-to-world, use case is to describe where head is; we expect a left-handed coordinate system; with z-axis facing forward (away) from user.
Definition
class CameraPose(ctypes.Structure):
_fields_ = [
("camera_to_world_matrix", Matrix4f32),
]
def __init__(self, camera_to_world_matrix: Matrix4f32 = None):
...
ColliderPose
Where in world space a collider resides.
Fields
- collider_id -
- frame_transform -
Definition
class ColliderPose(ctypes.Structure):
_fields_ = [
("collider_id", ctypes.c_uint64),
("frame_transform", EntityFrameTransform),
]
def __init__(self, collider_id: int = None, frame_transform: EntityFrameTransform = None):
...
ColliderShape
Describes the shape of a collider.
Fields
- collider_id - The transform this belongs to.
- object_id - The root object this collider refers to (e.g., in case this came from a collider attached to a nested transform).
- collider_type - The type of collider, e.g. physical or trigger.
- shape - Actual shape of the collider.
Definition
class ColliderShape(ctypes.Structure):
_fields_ = [
("collider_id", ctypes.c_uint64),
("object_id", ctypes.c_uint64),
("collider_type", ctypes.c_int),
("shape", Shape),
]
def __init__(self, collider_id: int = None, object_id: int = None, collider_type: ctypes.c_int = None, shape: Shape = None):
...
ColorRGB
Encodes a single color value in 8 bit RGB.
Fields
- r - Red value between
0
and255
. - g - Green value between
0
and255
. - b - Blue value between
0
and255
.
Definition
class ColorRGB(ctypes.Structure):
_fields_ = [
("r", ctypes.c_uint8),
("g", ctypes.c_uint8),
("b", ctypes.c_uint8),
]
def __init__(self, r: int = None, g: int = None, b: int = None):
...
CombinedGaze
Ray of a fictional, combined cyclops eye.
Some eye trackers can use internal sensor information to compute a combined gaze signal optimized for interaction purposes. Combining gaze usually acts as a spatially filtered signal with integrated error compensation, which can be better suited for medium to long range non-scientific use cases.
Coordinates in here are local space of the eye tracker, relative to a fictional
reference point between the eyes. To transform them to world space you need to use
the CameraPose
struct.
Fields
- gaze - The combined gaze ray.
Definition
class CombinedGaze(ctypes.Structure):
_fields_ = [
("gaze", Rayf32),
]
def __init__(self, gaze: Rayf32 = None):
...
ControllerButtonState
Described button states for a controller.
As of now, these buttons follow Unity’s XR Input specification
Fields
- device - The device described by this controller state.
- primary_button - See Unity XR Input specification.
- primary_touch - See Unity XR Input specification.
- primary_2d_axis_click - See Unity XR Input specification.
- primary_2d_axis_touch - See Unity XR Input specification.
- secondary_button - See Unity XR Input specification.
- secondary_touch - See Unity XR Input specification.
- secondary_2d_axis_click - See Unity XR Input specification.
- secondary_2d_axis_touch - See Unity XR Input specification.
- trigger_button - See Unity XR Input specification.
- grip_button - See Unity XR Input specification.
- menu_button - See Unity XR Input specification.
Definition
class ControllerButtonState(ctypes.Structure):
_fields_ = [
("device", ctypes.c_int),
("primary_button", ctypes.c_bool),
("primary_touch", ctypes.c_bool),
("primary_2d_axis_click", ctypes.c_bool),
("primary_2d_axis_touch", ctypes.c_bool),
("secondary_button", ctypes.c_bool),
("secondary_touch", ctypes.c_bool),
("secondary_2d_axis_click", ctypes.c_bool),
("secondary_2d_axis_touch", ctypes.c_bool),
("trigger_button", ctypes.c_bool),
("grip_button", ctypes.c_bool),
("menu_button", ctypes.c_bool),
]
def __init__(self, device: ctypes.c_int = None, primary_button: bool = None, primary_touch: bool = None, primary_2d_axis_click: bool = None, primary_2d_axis_touch: bool = None, secondary_button: bool = None, secondary_touch: bool = None, secondary_2d_axis_click: bool = None, secondary_2d_axis_touch: bool = None, trigger_button: bool = None, grip_button: bool = None, menu_button: bool = None):
...
ControllerPose
Where in world space a controller is.
Fields
- device - The device described.
- transform - World space position of the device.
Definition
class ControllerPose(ctypes.Structure):
_fields_ = [
("device", ctypes.c_int),
("transform", EntityFrameTransform),
]
def __init__(self, device: ctypes.c_int = None, transform: EntityFrameTransform = None):
...
ConvergenceDistance
Closest distance of gaze convergence.
Distance here is relative to a fictional reference point between the eyes,
equivalent to the world position of the CameraPose
struct.
Fields
- distance_m - Distance in meters to the reference points where closest convergence occurs.
Definition
class ConvergenceDistance(ctypes.Structure):
_fields_ = [
("distance_m", ctypes.c_float),
]
def __init__(self, distance_m: float = None):
...
Descriptor
Helper to request a descriptor from the recording library.
Fields
- cls - The class of data to describe, any ASCII string up to 32 bytes, e.g.,
gameobject
. - prop - The property of data to describe, any ASCII string up to 32 bytes, e.g.,
color
. - entity_id - The entity to describe.
- user - The user for which this data is tracked.
- len - Low-level
sizeof
byte length of a single tracked element. - well_known_type - What type of data is tracked.
Definition
class Descriptor(ctypes.Structure):
_fields_ = [
("cls", ctypes.POINTER(ctypes.c_char)),
("prop", ctypes.POINTER(ctypes.c_char)),
("entity_id", ctypes.c_uint64),
("user", ctypes.c_uint64),
("len", ctypes.c_uint16),
("well_known_type", ctypes.c_int),
]
def __init__(self, cls: str = None, prop: str = None, entity_id: int = None, user: int = None, len: int = None, well_known_type: ctypes.c_int = None):
...
EntityFrameTransform
Holds an update for a geometry’s transform. Usually given every frame.
Fields
- local_to_world_matrix - This matrix is used to transform gaze data from the object’s local space to world space.
Definition
class EntityFrameTransform(ctypes.Structure):
_fields_ = [
("local_to_world_matrix", Matrix4f32),
]
def __init__(self, local_to_world_matrix: Matrix4f32 = None):
...
EntityLabel
Maps an entity ID to an ASCII label.
Fields
- meta - Label meta data.
- label - NUL-terminated ASCII pointer with label.
Definition
class EntityLabel(ctypes.Structure):
_fields_ = [
("meta", EntityLabelID),
("label", ctypes.POINTER(ctypes.c_char)),
]
def __init__(self, meta: EntityLabelID = None, label: str = None):
...
EntityLabelID
Type-helper to store and retrieve labels for entities.
Fields
- entity -
- label_len - When setting a label this field will be ignored, when retrieving a label it will contain the string length including the terminating NUL.
Definition
class EntityLabelID(ctypes.Structure):
_fields_ = [
("entity", ctypes.c_uint64),
("label_len", ctypes.c_uint32),
]
def __init__(self, entity: int = None, label_len: int = None):
...
EntrancePupilData
Entrance pupil data.
Fields
- left - Left eye data.
- right - Right eye data.
Definition
class EntrancePupilData(ctypes.Structure):
_fields_ = [
("left", Vector3f32),
("right", Vector3f32),
]
def __init__(self, left: Vector3f32 = None, right: Vector3f32 = None):
...
EyeTrackerDeviceTimestamp
Timestamp reported by the eye tracker according to its own clock.
Fields
- timestamp - Timestamp reported by the device.
Definition
class EyeTrackerDeviceTimestamp(ctypes.Structure):
_fields_ = [
("timestamp", ctypes.c_uint64),
]
def __init__(self, timestamp: int = None):
...
FrameDimension
Dimension of the video frame in pixels.
Fields
- width - Width in pixels.
- height - Height in pixels.
Definition
class FrameDimension(ctypes.Structure):
_fields_ = [
("width", ctypes.c_uint32),
("height", ctypes.c_uint32),
]
def __init__(self, width: int = None, height: int = None):
...
FrameMeta
Meta data about a video frame / packet when passing the packet around.
Fields
- frame_type - What the encoded packet describes.
- frame_id - (Usually sequential) number starting at 0, increased each frame.
- depends_on - Some frames might depend on other frames for display. If set this indicates which.
- rendered_time - The time in micro seconds a packet was originally rendered in the game engine when a copy of this frame was taken and sent to the encoder.
Definition
class FrameMeta(ctypes.Structure):
_fields_ = [
("frame_type", ctypes.c_int),
("frame_id", ctypes.c_uint32),
("depends_on", Optionu32),
("rendered_time", ctypes.c_int64),
]
def __init__(self, frame_type: ctypes.c_int = None, frame_id: int = None, depends_on: Optionu32 = None, rendered_time: int = None):
...
Gizmo3D
Helper that can be attached to scenes to debug or visualize certain properties.
Fields
- gizmo_id - Entity ID of this gizmo.
- simple_geometry - Shape in Ocumen Studio.
- frame_transform - World position of the gizmo.
- color - Color to show.
Definition
class Gizmo3D(ctypes.Structure):
_fields_ = [
("gizmo_id", ctypes.c_uint64),
("simple_geometry", Shape),
("frame_transform", EntityFrameTransform),
("color", ColorRGB),
]
def __init__(self, gizmo_id: int = None, simple_geometry: Shape = None, frame_transform: EntityFrameTransform = None, color: ColorRGB = None):
...
ImageData
Image descriptor and data pointers.
Fields
- descriptor - Describes what is encoded in the slice.
- data - Actual image data.
Definition
class ImageData(ctypes.Structure):
_fields_ = [
("descriptor", ImageDescriptor),
("data", Sliceu8),
]
def __init__(self, descriptor: ImageDescriptor = None, data: Sliceu8 = None):
...
ImageDescriptor
Describes the data of a single video frame, as provided by encoderlib.
Fields
- track - Track of embedded image information.
- format - Format of the data buffer.
- dimensions - Width and height of the image.
- image_data_length - Length of the encoded image.
Definition
class ImageDescriptor(ctypes.Structure):
_fields_ = [
("track", ctypes.c_uint8),
("format", ctypes.c_int),
("dimensions", FrameDimension),
("image_data_length", ctypes.c_uint32),
]
def __init__(self, track: int = None, format: ctypes.c_int = None, dimensions: FrameDimension = None, image_data_length: int = None):
...
InstanceLifetime
Holds information whether an entity is enabled.
An entity is enabled (i.e., visibile and participating in the scene) by default. Instances can be disabled when they disapper in the game, e.g., the underlying object is deleted.
Fields
- instance_id - Instance described.
- enabled - Whether instance is alive or not.
Definition
class InstanceLifetime(ctypes.Structure):
_fields_ = [
("instance_id", ctypes.c_uint64),
("enabled", ctypes.c_bool),
]
def __init__(self, instance_id: int = None, enabled: bool = None):
...
LogMessage
A single message recorded by our library.
Fields
- level - The level of the message.
- message - ASCII encoded actual message.
- file - Our source file where this message originated from.
- line - Line number where this message originated from.
Definition
class LogMessage(ctypes.Structure):
_fields_ = [
("level", ctypes.c_int),
("message", ctypes.POINTER(ctypes.c_char)),
("file", ctypes.POINTER(ctypes.c_char)),
("line", ctypes.c_uint32),
]
def __init__(self, level: ctypes.c_int = None, message: str = None, file: str = None, line: int = None):
...
LoggerConfiguration
Configures how logging should be handled.
Fields
- log_level - The minimal log level to log.
- max_log_wait_ms - When initializing the logger, with a previous logger present, how long shall we try to wait replacing the previous logger if it is locked.
Definition
class LoggerConfiguration(ctypes.Structure):
_fields_ = [
("log_level", ctypes.c_int),
("max_log_wait_ms", ctypes.c_uint32),
]
def __init__(self, log_level: ctypes.c_int = None, max_log_wait_ms: int = None):
...
Matrix4f32
A 4x4 transformation matrix.
Fields
- m - Array member elements in column major order.
Definition
class Matrix4f32(ctypes.Structure):
_fields_ = [
("m", ctypes.c_float * 16),
]
def __init__(self, m = None):
...
Mesh
Identifies a series of vertices and indices describing an object.
Fields
- mesh_id - Mesh ID described.
- vertices - List of vertices making up the mesh.
- indices - Triangle indices of the used vertices.
Definition
class Mesh(ctypes.Structure):
_fields_ = [
("mesh_id", ctypes.c_uint64),
("vertices", SliceVector3f32),
("indices", Slicei32),
]
def __init__(self, mesh_id: int = None, vertices: SliceVector3f32 = None, indices: Slicei32 = None):
...
ObjectMesh
Links an object with a mesh.
Fields
- object_id - Object ID linked to a mesh ID.
- mesh_id - Mesh ID of this object.
Definition
class ObjectMesh(ctypes.Structure):
_fields_ = [
("object_id", ctypes.c_uint64),
("mesh_id", ctypes.c_uint64),
]
def __init__(self, object_id: int = None, mesh_id: int = None):
...
ObjectPose
Keeps pose data (translation, rotation, scale) for an object.
Fields
- object_id - Object ID described here.
- frame_transform - The object’s pose.
Definition
class ObjectPose(ctypes.Structure):
_fields_ = [
("object_id", ctypes.c_uint64),
("frame_transform", EntityFrameTransform),
]
def __init__(self, object_id: int = None, frame_transform: EntityFrameTransform = None):
...
Point2f32
A point in 2D space.
Fields
- x - x component.
- y - y component.
Definition
class Point2f32(ctypes.Structure):
_fields_ = [
("x", ctypes.c_float),
("y", ctypes.c_float),
]
def __init__(self, x: float = None, y: float = None):
...
Point3f32
A point in 3D space.
Fields
- x - x component.
- y - y component.
- z - z component.
Definition
class Point3f32(ctypes.Structure):
_fields_ = [
("x", ctypes.c_float),
("y", ctypes.c_float),
("z", ctypes.c_float),
]
def __init__(self, x: float = None, y: float = None, z: float = None):
...
PositionGuide
The 2D position of the eyes in the headset.
Fields
- left - X and Y position of left eye.
- right - X and Y position of right eye.
Definition
class PositionGuide(ctypes.Structure):
_fields_ = [
("left", Point2f32),
("right", Point2f32),
]
def __init__(self, left: Point2f32 = None, right: Point2f32 = None):
...
PupilSizeAbsolute
Pupil diameter in millimeters for both eyes.
Fields
- left - Left eye pupil diameter.
- right - Right eye pupil diameter.
Definition
class PupilSizeAbsolute(ctypes.Structure):
_fields_ = [
("left", PupilSizePerEye),
("right", PupilSizePerEye),
]
def __init__(self, left: PupilSizePerEye = None, right: PupilSizePerEye = None):
...
PupilSizePerEye
Pupil diameter for the eye
Fields
- size_mm - Pupil diameter in millimeters for the eye.
Definition
class PupilSizePerEye(ctypes.Structure):
_fields_ = [
("size_mm", ctypes.c_float),
]
def __init__(self, size_mm: float = None):
...
Quaternionf32
A quaternion we use for vector operations.
Fields
- s -
- v -
Definition
class Quaternionf32(ctypes.Structure):
_fields_ = [
("s", ctypes.c_float),
("v", Vector3f32),
]
def __init__(self, s: float = None, v: Vector3f32 = None):
...
Rayf32
A ray with an origin and direction.
Fields
- origin - Origin of the ray.
- direction - Direction of the ray.
Definition
class Rayf32(ctypes.Structure):
_fields_ = [
("origin", Point3f32),
("direction", Vector3f32),
]
def __init__(self, origin: Point3f32 = None, direction: Vector3f32 = None):
...
RecordingInformation
Recording meta data.
Fields
- duration - How long the recording lasted.
- first - The first observed time stamp in the recoring. Is very likely not 0.
- last - The last observed time stamp in the recoring.
Definition
class RecordingInformation(ctypes.Structure):
_fields_ = [
("duration", ctypes.c_int64),
("first", ctypes.c_int64),
("last", ctypes.c_int64),
]
def __init__(self, duration: int = None, first: int = None, last: int = None):
...
Shape
A simple geometry expressable with just 3 points.
Fields
- shape_type - Defines how [
points
] are to be interpreted. - points - See definition of [
Shape
] for interpretation
Definition
class Shape(ctypes.Structure):
_fields_ = [
("shape_type", ctypes.c_int),
("points", Point3f32 * 3),
]
def __init__(self, shape_type: ctypes.c_int = None, points = None):
...
StereoProjections
Projection matrices used for rendering.
Fields
- left - The applied view projection for the left eye. We expect an OpenGL project matrix for Ocumen Studio to render properly.
- right - The applied view projection for the right eye. We expect an OpenGL project matrix for Ocumen Studio to render properly.
Definition
class StereoProjections(ctypes.Structure):
_fields_ = [
("left", Matrix4f32),
("right", Matrix4f32),
]
def __init__(self, left: Matrix4f32 = None, right: Matrix4f32 = None):
...
StereoViews
View matrices of each eye, i.e., where each eye / camera is in world space.
Fields
- left - Where the left eye actually is, relative to world-space. Use case is to convert world space object coordinates to view space; so this is world-to-camera matrix).
- right - Where the right eye actually is, relative to world-space. Use case is to convert world space object coordinates to view space; so this is world-to-camera matrix).
Definition
class StereoViews(ctypes.Structure):
_fields_ = [
("left", Matrix4f32),
("right", Matrix4f32),
]
def __init__(self, left: Matrix4f32 = None, right: Matrix4f32 = None):
...
TimeValueBinocularGaze
Contains a single value and its time.
Fields
- time - Timestamp of the value, in microseconds.
- value - Actual value at the given time.
Definition
class TimeValueBinocularGaze(ctypes.Structure):
_fields_ = [
("time", ctypes.c_int64),
("value", BinocularGaze),
]
def __init__(self, time: int = None, value: BinocularGaze = None):
...
TimeValueBlinkState
Contains a single value and its time.
Fields
- time - Timestamp of the value, in microseconds.
- value - Actual value at the given time.
Definition
class TimeValueBlinkState(ctypes.Structure):
_fields_ = [
("time", ctypes.c_int64),
("value", BlinkState),
]
def __init__(self, time: int = None, value: BlinkState = None):
...
TimeValueCombinedGaze
Contains a single value and its time.
Fields
- time - Timestamp of the value, in microseconds.
- value - Actual value at the given time.
Definition
class TimeValueCombinedGaze(ctypes.Structure):
_fields_ = [
("time", ctypes.c_int64),
("value", CombinedGaze),
]
def __init__(self, time: int = None, value: CombinedGaze = None):
...
TimeValueConvergenceDistance
Contains a single value and its time.
Fields
- time - Timestamp of the value, in microseconds.
- value - Actual value at the given time.
Definition
class TimeValueConvergenceDistance(ctypes.Structure):
_fields_ = [
("time", ctypes.c_int64),
("value", ConvergenceDistance),
]
def __init__(self, time: int = None, value: ConvergenceDistance = None):
...
TimeValueEntrancePupilData
Contains a single value and its time.
Fields
- time - Timestamp of the value, in microseconds.
- value - Actual value at the given time.
Definition
class TimeValueEntrancePupilData(ctypes.Structure):
_fields_ = [
("time", ctypes.c_int64),
("value", EntrancePupilData),
]
def __init__(self, time: int = None, value: EntrancePupilData = None):
...
TimeValueEyeTrackerDeviceTimestamp
Contains a single value and its time.
Fields
- time - Timestamp of the value, in microseconds.
- value - Actual value at the given time.
Definition
class TimeValueEyeTrackerDeviceTimestamp(ctypes.Structure):
_fields_ = [
("time", ctypes.c_int64),
("value", EyeTrackerDeviceTimestamp),
]
def __init__(self, time: int = None, value: EyeTrackerDeviceTimestamp = None):
...
TimeValuePositionGuide
Contains a single value and its time.
Fields
- time - Timestamp of the value, in microseconds.
- value - Actual value at the given time.
Definition
class TimeValuePositionGuide(ctypes.Structure):
_fields_ = [
("time", ctypes.c_int64),
("value", PositionGuide),
]
def __init__(self, time: int = None, value: PositionGuide = None):
...
TimeValuePupilSizeAbsolute
Contains a single value and its time.
Fields
- time - Timestamp of the value, in microseconds.
- value - Actual value at the given time.
Definition
class TimeValuePupilSizeAbsolute(ctypes.Structure):
_fields_ = [
("time", ctypes.c_int64),
("value", PupilSizeAbsolute),
]
def __init__(self, time: int = None, value: PupilSizeAbsolute = None):
...
TimesValuesCameraPose
Maps a series of values to corresponding times.
Both slices are guaranteed to be of equal length and meant to be walked in lock step.
Fields
- times - Timestamp in microseconds.
- values - Values at the times above.
Definition
class TimesValuesCameraPose(ctypes.Structure):
_fields_ = [
("times", Slicei64),
("values", SliceCameraPose),
]
def __init__(self, times: Slicei64 = None, values: SliceCameraPose = None):
...
TimesValuesColliderPose
Maps a series of values to corresponding times.
Both slices are guaranteed to be of equal length and meant to be walked in lock step.
Fields
- times - Timestamp in microseconds.
- values - Values at the times above.
Definition
class TimesValuesColliderPose(ctypes.Structure):
_fields_ = [
("times", Slicei64),
("values", SliceColliderPose),
]
def __init__(self, times: Slicei64 = None, values: SliceColliderPose = None):
...
TimesValuesColliderShape
Maps a series of values to corresponding times.
Both slices are guaranteed to be of equal length and meant to be walked in lock step.
Fields
- times - Timestamp in microseconds.
- values - Values at the times above.
Definition
class TimesValuesColliderShape(ctypes.Structure):
_fields_ = [
("times", Slicei64),
("values", SliceColliderShape),
]
def __init__(self, times: Slicei64 = None, values: SliceColliderShape = None):
...
TimesValuesGizmo3D
Maps a series of values to corresponding times.
Both slices are guaranteed to be of equal length and meant to be walked in lock step.
Fields
- times - Timestamp in microseconds.
- values - Values at the times above.
Definition
class TimesValuesGizmo3D(ctypes.Structure):
_fields_ = [
("times", Slicei64),
("values", SliceGizmo3D),
]
def __init__(self, times: Slicei64 = None, values: SliceGizmo3D = None):
...
TimesValuesInstanceLifetime
Maps a series of values to corresponding times.
Both slices are guaranteed to be of equal length and meant to be walked in lock step.
Fields
- times - Timestamp in microseconds.
- values - Values at the times above.
Definition
class TimesValuesInstanceLifetime(ctypes.Structure):
_fields_ = [
("times", Slicei64),
("values", SliceInstanceLifetime),
]
def __init__(self, times: Slicei64 = None, values: SliceInstanceLifetime = None):
...
TimesValuesObjectMesh
Maps a series of values to corresponding times.
Both slices are guaranteed to be of equal length and meant to be walked in lock step.
Fields
- times - Timestamp in microseconds.
- values - Values at the times above.
Definition
class TimesValuesObjectMesh(ctypes.Structure):
_fields_ = [
("times", Slicei64),
("values", SliceObjectMesh),
]
def __init__(self, times: Slicei64 = None, values: SliceObjectMesh = None):
...
TimesValuesObjectPose
Maps a series of values to corresponding times.
Both slices are guaranteed to be of equal length and meant to be walked in lock step.
Fields
- times - Timestamp in microseconds.
- values - Values at the times above.
Definition
class TimesValuesObjectPose(ctypes.Structure):
_fields_ = [
("times", Slicei64),
("values", SliceObjectPose),
]
def __init__(self, times: Slicei64 = None, values: SliceObjectPose = None):
...
TimesValuesStereoProjections
Maps a series of values to corresponding times.
Both slices are guaranteed to be of equal length and meant to be walked in lock step.
Fields
- times - Timestamp in microseconds.
- values - Values at the times above.
Definition
class TimesValuesStereoProjections(ctypes.Structure):
_fields_ = [
("times", Slicei64),
("values", SliceStereoProjections),
]
def __init__(self, times: Slicei64 = None, values: SliceStereoProjections = None):
...
TimesValuesStereoViews
Maps a series of values to corresponding times.
Both slices are guaranteed to be of equal length and meant to be walked in lock step.
Fields
- times - Timestamp in microseconds.
- values - Values at the times above.
Definition
class TimesValuesStereoViews(ctypes.Structure):
_fields_ = [
("times", Slicei64),
("values", SliceStereoViews),
]
def __init__(self, times: Slicei64 = None, values: SliceStereoViews = None):
...
TimesValuesu32
Maps a series of values to corresponding times.
Both slices are guaranteed to be of equal length and meant to be walked in lock step.
Fields
- times - Timestamp in microseconds.
- values - Values at the times above.
Definition
class TimesValuesu32(ctypes.Structure):
_fields_ = [
("times", Slicei64),
("values", Sliceu32),
]
def __init__(self, times: Slicei64 = None, values: Sliceu32 = None):
...
TrackHandle
File-descriptor-like handle for one stream of data inside a recording.
For example user3.object3.world_pos
would have its own handle.
Descriptor handles are ephemeral and are only valid during a recording or query session. For example, when a recording is reloaded, previously returned descriptors will not necessarily match the reloaded data streams.
Fields
- size_of - Len in bytes of the type described.
- _unused1 - Special flags for later use.
- _unused2 - Special flags for later use.
- id - ID of this descriptor.
Definition
class TrackHandle(ctypes.Structure):
_fields_ = [
("size_of", ctypes.c_uint16),
("_unused1", ctypes.c_uint8),
("_unused2", ctypes.c_uint8),
("id", ctypes.c_uint32),
]
def __init__(self, size_of: int = None, _unused1: int = None, _unused2: int = None, id: int = None):
...
TrackedWellKnownInfo
Describes a track.
Fields
- cls - Class name, e.g.,
eeg
. - prop - Property name, e.g.,
ch
- entity - Entity ID.
- user - User of that track.
Definition
class TrackedWellKnownInfo(ctypes.Structure):
_fields_ = [
("cls", ctypes.POINTER(ctypes.c_char)),
("prop", ctypes.POINTER(ctypes.c_char)),
("entity", ctypes.c_uint64),
("user", ctypes.c_uint64),
]
def __init__(self, cls: str = None, prop: str = None, entity: int = None, user: int = None):
...
UserAtTime
Specifies a user ID and associated time stamp in our API.
Fields
- user_id - User ID described.
- time - Time stamp in microseconds of the event described.
Definition
class UserAtTime(ctypes.Structure):
_fields_ = [
("user_id", ctypes.c_uint64),
("time", ctypes.c_int64),
]
def __init__(self, user_id: int = None, time: int = None):
...
UserInTimeRange
Specifies a user ID and associated time range in our API.
Fields
- user_id - User ID described.
- first_inclusive - Inclusive time range start in microseconds.
- last_inclusive - Inclusive time range end in microseconds.
Definition
class UserInTimeRange(ctypes.Structure):
_fields_ = [
("user_id", ctypes.c_uint64),
("first_inclusive", ctypes.c_int64),
("last_inclusive", ctypes.c_int64),
]
def __init__(self, user_id: int = None, first_inclusive: int = None, last_inclusive: int = None):
...
Vector3f32
A 3-dimensional vector.
Fields
- x - x component.
- y - y component.
- z - z component.
Definition
class Vector3f32(ctypes.Structure):
_fields_ = [
("x", ctypes.c_float),
("y", ctypes.c_float),
("z", ctypes.c_float),
]
def __init__(self, x: float = None, y: float = None, z: float = None):
...
Version
Encodes a version number for our products, like 2.0.1
.
Fields
- major - Major component, e.g.
2
. - minor - Minor component, e.g.
0
. - patch - Patch component, e.g.
1
. - build - Build ID.
Definition
class Version(ctypes.Structure):
_fields_ = [
("major", ctypes.c_uint8),
("minor", ctypes.c_uint8),
("patch", ctypes.c_uint8),
("build", ctypes.c_int64),
]
def __init__(self, major: int = None, minor: int = None, patch: int = None, build: int = None):
...
VideoFrame
Holds video meta information and actual video data.
Fields
- meta - Video meta data.
- data - Encoded video bytes.
Definition
class VideoFrame(ctypes.Structure):
_fields_ = [
("meta", VideoFrameDescriptor),
("data", Sliceu8),
]
def __init__(self, meta: VideoFrameDescriptor = None, data: Sliceu8 = None):
...
VideoFrameDescriptor
Describes the data of a single video frame, as provided by encoderlib.
Fields
- track -
- format -
- dimensions -
- common_meta -
Definition
class VideoFrameDescriptor(ctypes.Structure):
_fields_ = [
("track", ctypes.c_int),
("format", ctypes.c_int),
("dimensions", FrameDimension),
("common_meta", FrameMeta),
]
def __init__(self, track: ctypes.c_int = None, format: ctypes.c_int = None, dimensions: FrameDimension = None, common_meta: FrameMeta = None):
...
WellKnownTypedTrack
Maps a descriptor handle.
Fields
- track_handle - Handle of track described.
- track_type - Type of the handle.
Definition
class WellKnownTypedTrack(ctypes.Structure):
_fields_ = [
("track_handle", TrackHandle),
("track_type", ctypes.c_int),
]
def __init__(self, track_handle: TrackHandle = None, track_type: ctypes.c_int = None):
...
SliceCameraPose
A pointer to an array of data someone else owns which may not be modified.
Fields
- data - Pointer to start of immutable data.
- len - Number of elements.
Definition
class SliceCameraPose(ctypes.Structure):
_fields_ = [
("data", ctypes.POINTER(CameraPose)),
("len", ctypes.c_uint64),
]
def __init__(self, data: ctypes.POINTER(CameraPose) = None, len: int = None):
...
SliceColliderPose
A pointer to an array of data someone else owns which may not be modified.
Fields
- data - Pointer to start of immutable data.
- len - Number of elements.
Definition
class SliceColliderPose(ctypes.Structure):
_fields_ = [
("data", ctypes.POINTER(ColliderPose)),
("len", ctypes.c_uint64),
]
def __init__(self, data: ctypes.POINTER(ColliderPose) = None, len: int = None):
...
SliceColliderShape
A pointer to an array of data someone else owns which may not be modified.
Fields
- data - Pointer to start of immutable data.
- len - Number of elements.
Definition
class SliceColliderShape(ctypes.Structure):
_fields_ = [
("data", ctypes.POINTER(ColliderShape)),
("len", ctypes.c_uint64),
]
def __init__(self, data: ctypes.POINTER(ColliderShape) = None, len: int = None):
...
SliceControllerButtonState
A pointer to an array of data someone else owns which may not be modified.
Fields
- data - Pointer to start of immutable data.
- len - Number of elements.
Definition
class SliceControllerButtonState(ctypes.Structure):
_fields_ = [
("data", ctypes.POINTER(ControllerButtonState)),
("len", ctypes.c_uint64),
]
def __init__(self, data: ctypes.POINTER(ControllerButtonState) = None, len: int = None):
...
SliceControllerPose
A pointer to an array of data someone else owns which may not be modified.
Fields
- data - Pointer to start of immutable data.
- len - Number of elements.
Definition
class SliceControllerPose(ctypes.Structure):
_fields_ = [
("data", ctypes.POINTER(ControllerPose)),
("len", ctypes.c_uint64),
]
def __init__(self, data: ctypes.POINTER(ControllerPose) = None, len: int = None):
...
SliceEntityLabel
A pointer to an array of data someone else owns which may not be modified.
Fields
- data - Pointer to start of immutable data.
- len - Number of elements.
Definition
class SliceEntityLabel(ctypes.Structure):
_fields_ = [
("data", ctypes.POINTER(EntityLabel)),
("len", ctypes.c_uint64),
]
def __init__(self, data: ctypes.POINTER(EntityLabel) = None, len: int = None):
...
SliceGizmo3D
A pointer to an array of data someone else owns which may not be modified.
Fields
- data - Pointer to start of immutable data.
- len - Number of elements.
Definition
class SliceGizmo3D(ctypes.Structure):
_fields_ = [
("data", ctypes.POINTER(Gizmo3D)),
("len", ctypes.c_uint64),
]
def __init__(self, data: ctypes.POINTER(Gizmo3D) = None, len: int = None):
...
SliceImageData
A pointer to an array of data someone else owns which may not be modified.
Fields
- data - Pointer to start of immutable data.
- len - Number of elements.
Definition
class SliceImageData(ctypes.Structure):
_fields_ = [
("data", ctypes.POINTER(ImageData)),
("len", ctypes.c_uint64),
]
def __init__(self, data: ctypes.POINTER(ImageData) = None, len: int = None):
...
SliceInstanceLifetime
A pointer to an array of data someone else owns which may not be modified.
Fields
- data - Pointer to start of immutable data.
- len - Number of elements.
Definition
class SliceInstanceLifetime(ctypes.Structure):
_fields_ = [
("data", ctypes.POINTER(InstanceLifetime)),
("len", ctypes.c_uint64),
]
def __init__(self, data: ctypes.POINTER(InstanceLifetime) = None, len: int = None):
...
SliceMesh
A pointer to an array of data someone else owns which may not be modified.
Fields
- data - Pointer to start of immutable data.
- len - Number of elements.
Definition
class SliceMesh(ctypes.Structure):
_fields_ = [
("data", ctypes.POINTER(Mesh)),
("len", ctypes.c_uint64),
]
def __init__(self, data: ctypes.POINTER(Mesh) = None, len: int = None):
...
SliceObjectMesh
A pointer to an array of data someone else owns which may not be modified.
Fields
- data - Pointer to start of immutable data.
- len - Number of elements.
Definition
class SliceObjectMesh(ctypes.Structure):
_fields_ = [
("data", ctypes.POINTER(ObjectMesh)),
("len", ctypes.c_uint64),
]
def __init__(self, data: ctypes.POINTER(ObjectMesh) = None, len: int = None):
...
SliceObjectPose
A pointer to an array of data someone else owns which may not be modified.
Fields
- data - Pointer to start of immutable data.
- len - Number of elements.
Definition
class SliceObjectPose(ctypes.Structure):
_fields_ = [
("data", ctypes.POINTER(ObjectPose)),
("len", ctypes.c_uint64),
]
def __init__(self, data: ctypes.POINTER(ObjectPose) = None, len: int = None):
...
SliceStereoProjections
A pointer to an array of data someone else owns which may not be modified.
Fields
- data - Pointer to start of immutable data.
- len - Number of elements.
Definition
class SliceStereoProjections(ctypes.Structure):
_fields_ = [
("data", ctypes.POINTER(StereoProjections)),
("len", ctypes.c_uint64),
]
def __init__(self, data: ctypes.POINTER(StereoProjections) = None, len: int = None):
...
SliceStereoViews
A pointer to an array of data someone else owns which may not be modified.
Fields
- data - Pointer to start of immutable data.
- len - Number of elements.
Definition
class SliceStereoViews(ctypes.Structure):
_fields_ = [
("data", ctypes.POINTER(StereoViews)),
("len", ctypes.c_uint64),
]
def __init__(self, data: ctypes.POINTER(StereoViews) = None, len: int = None):
...
SliceTrackedData
A pointer to an array of data someone else owns which may not be modified.
Fields
- data - Pointer to start of immutable data.
- len - Number of elements.
Definition
class SliceTrackedData(ctypes.Structure):
_fields_ = [
("data", ctypes.POINTER(ctypes.c_int)),
("len", ctypes.c_uint64),
]
def __init__(self, data: ctypes.POINTER(ctypes.c_int) = None, len: int = None):
...
SliceTrackedWellKnownInfo
A pointer to an array of data someone else owns which may not be modified.
Fields
- data - Pointer to start of immutable data.
- len - Number of elements.
Definition
class SliceTrackedWellKnownInfo(ctypes.Structure):
_fields_ = [
("data", ctypes.POINTER(TrackedWellKnownInfo)),
("len", ctypes.c_uint64),
]
def __init__(self, data: ctypes.POINTER(TrackedWellKnownInfo) = None, len: int = None):
...
SliceVector3f32
A pointer to an array of data someone else owns which may not be modified.
Fields
- data - Pointer to start of immutable data.
- len - Number of elements.
Definition
class SliceVector3f32(ctypes.Structure):
_fields_ = [
("data", ctypes.POINTER(Vector3f32)),
("len", ctypes.c_uint64),
]
def __init__(self, data: ctypes.POINTER(Vector3f32) = None, len: int = None):
...
SliceVideoFrame
A pointer to an array of data someone else owns which may not be modified.
Fields
- data - Pointer to start of immutable data.
- len - Number of elements.
Definition
class SliceVideoFrame(ctypes.Structure):
_fields_ = [
("data", ctypes.POINTER(VideoFrame)),
("len", ctypes.c_uint64),
]
def __init__(self, data: ctypes.POINTER(VideoFrame) = None, len: int = None):
...
SliceWellKnownTypedTrack
A pointer to an array of data someone else owns which may not be modified.
Fields
- data - Pointer to start of immutable data.
- len - Number of elements.
Definition
class SliceWellKnownTypedTrack(ctypes.Structure):
_fields_ = [
("data", ctypes.POINTER(WellKnownTypedTrack)),
("len", ctypes.c_uint64),
]
def __init__(self, data: ctypes.POINTER(WellKnownTypedTrack) = None, len: int = None):
...
Slicei32
A pointer to an array of data someone else owns which may not be modified.
Fields
- data - Pointer to start of immutable data.
- len - Number of elements.
Definition
class Slicei32(ctypes.Structure):
_fields_ = [
("data", ctypes.POINTER(ctypes.c_int32)),
("len", ctypes.c_uint64),
]
def __init__(self, data: ctypes.POINTER(ctypes.c_int32) = None, len: int = None):
...
Slicei64
A pointer to an array of data someone else owns which may not be modified.
Fields
- data - Pointer to start of immutable data.
- len - Number of elements.
Definition
class Slicei64(ctypes.Structure):
_fields_ = [
("data", ctypes.POINTER(ctypes.c_int64)),
("len", ctypes.c_uint64),
]
def __init__(self, data: ctypes.POINTER(ctypes.c_int64) = None, len: int = None):
...
Sliceu32
A pointer to an array of data someone else owns which may not be modified.
Fields
- data - Pointer to start of immutable data.
- len - Number of elements.
Definition
class Sliceu32(ctypes.Structure):
_fields_ = [
("data", ctypes.POINTER(ctypes.c_uint32)),
("len", ctypes.c_uint64),
]
def __init__(self, data: ctypes.POINTER(ctypes.c_uint32) = None, len: int = None):
...
Sliceu64
A pointer to an array of data someone else owns which may not be modified.
Fields
- data - Pointer to start of immutable data.
- len - Number of elements.
Definition
class Sliceu64(ctypes.Structure):
_fields_ = [
("data", ctypes.POINTER(ctypes.c_uint64)),
("len", ctypes.c_uint64),
]
def __init__(self, data: ctypes.POINTER(ctypes.c_uint64) = None, len: int = None):
...
Sliceu8
A pointer to an array of data someone else owns which may not be modified.
Fields
- data - Pointer to start of immutable data.
- len - Number of elements.
Definition
class Sliceu8(ctypes.Structure):
_fields_ = [
("data", ctypes.POINTER(ctypes.c_uint8)),
("len", ctypes.c_uint64),
]
def __init__(self, data: ctypes.POINTER(ctypes.c_uint8) = None, len: int = None):
...
OptionBinocularGaze
Option type containing boolean flag and maybe valid data.
Fields
- t - Element that is maybe valid.
- is_some - Byte where
1
means elementt
is valid.
Definition
class OptionBinocularGaze(ctypes.Structure):
_fields_ = [
("t", BinocularGaze),
("is_some", ctypes.c_uint8),
]
def __init__(self, t: BinocularGaze = None, is_some: int = None):
...
OptionConvergenceDistance
Option type containing boolean flag and maybe valid data.
Fields
- t - Element that is maybe valid.
- is_some - Byte where
1
means elementt
is valid.
Definition
class OptionConvergenceDistance(ctypes.Structure):
_fields_ = [
("t", ConvergenceDistance),
("is_some", ctypes.c_uint8),
]
def __init__(self, t: ConvergenceDistance = None, is_some: int = None):
...
OptionEntrancePupilData
Option type containing boolean flag and maybe valid data.
Fields
- t - Element that is maybe valid.
- is_some - Byte where
1
means elementt
is valid.
Definition
class OptionEntrancePupilData(ctypes.Structure):
_fields_ = [
("t", EntrancePupilData),
("is_some", ctypes.c_uint8),
]
def __init__(self, t: EntrancePupilData = None, is_some: int = None):
...
OptionPupilSizeAbsolute
Option type containing boolean flag and maybe valid data.
Fields
- t - Element that is maybe valid.
- is_some - Byte where
1
means elementt
is valid.
Definition
class OptionPupilSizeAbsolute(ctypes.Structure):
_fields_ = [
("t", PupilSizeAbsolute),
("is_some", ctypes.c_uint8),
]
def __init__(self, t: PupilSizeAbsolute = None, is_some: int = None):
...
OptionTimeValueBinocularGaze
Option type containing boolean flag and maybe valid data.
Fields
- t - Element that is maybe valid.
- is_some - Byte where
1
means elementt
is valid.
Definition
class OptionTimeValueBinocularGaze(ctypes.Structure):
_fields_ = [
("t", TimeValueBinocularGaze),
("is_some", ctypes.c_uint8),
]
def __init__(self, t: TimeValueBinocularGaze = None, is_some: int = None):
...
OptionTimeValueBlinkState
Option type containing boolean flag and maybe valid data.
Fields
- t - Element that is maybe valid.
- is_some - Byte where
1
means elementt
is valid.
Definition
class OptionTimeValueBlinkState(ctypes.Structure):
_fields_ = [
("t", TimeValueBlinkState),
("is_some", ctypes.c_uint8),
]
def __init__(self, t: TimeValueBlinkState = None, is_some: int = None):
...
OptionTimeValueCombinedGaze
Option type containing boolean flag and maybe valid data.
Fields
- t - Element that is maybe valid.
- is_some - Byte where
1
means elementt
is valid.
Definition
class OptionTimeValueCombinedGaze(ctypes.Structure):
_fields_ = [
("t", TimeValueCombinedGaze),
("is_some", ctypes.c_uint8),
]
def __init__(self, t: TimeValueCombinedGaze = None, is_some: int = None):
...
OptionTimeValueConvergenceDistance
Option type containing boolean flag and maybe valid data.
Fields
- t - Element that is maybe valid.
- is_some - Byte where
1
means elementt
is valid.
Definition
class OptionTimeValueConvergenceDistance(ctypes.Structure):
_fields_ = [
("t", TimeValueConvergenceDistance),
("is_some", ctypes.c_uint8),
]
def __init__(self, t: TimeValueConvergenceDistance = None, is_some: int = None):
...
OptionTimeValueEntrancePupilData
Option type containing boolean flag and maybe valid data.
Fields
- t - Element that is maybe valid.
- is_some - Byte where
1
means elementt
is valid.
Definition
class OptionTimeValueEntrancePupilData(ctypes.Structure):
_fields_ = [
("t", TimeValueEntrancePupilData),
("is_some", ctypes.c_uint8),
]
def __init__(self, t: TimeValueEntrancePupilData = None, is_some: int = None):
...
OptionTimeValueEyeTrackerDeviceTimestamp
Option type containing boolean flag and maybe valid data.
Fields
- t - Element that is maybe valid.
- is_some - Byte where
1
means elementt
is valid.
Definition
class OptionTimeValueEyeTrackerDeviceTimestamp(ctypes.Structure):
_fields_ = [
("t", TimeValueEyeTrackerDeviceTimestamp),
("is_some", ctypes.c_uint8),
]
def __init__(self, t: TimeValueEyeTrackerDeviceTimestamp = None, is_some: int = None):
...
OptionTimeValuePositionGuide
Option type containing boolean flag and maybe valid data.
Fields
- t - Element that is maybe valid.
- is_some - Byte where
1
means elementt
is valid.
Definition
class OptionTimeValuePositionGuide(ctypes.Structure):
_fields_ = [
("t", TimeValuePositionGuide),
("is_some", ctypes.c_uint8),
]
def __init__(self, t: TimeValuePositionGuide = None, is_some: int = None):
...
OptionTimeValuePupilSizeAbsolute
Option type containing boolean flag and maybe valid data.
Fields
- t - Element that is maybe valid.
- is_some - Byte where
1
means elementt
is valid.
Definition
class OptionTimeValuePupilSizeAbsolute(ctypes.Structure):
_fields_ = [
("t", TimeValuePupilSizeAbsolute),
("is_some", ctypes.c_uint8),
]
def __init__(self, t: TimeValuePupilSizeAbsolute = None, is_some: int = None):
...
OptionVideoFrame
Option type containing boolean flag and maybe valid data.
Fields
- t - Element that is maybe valid.
- is_some - Byte where
1
means elementt
is valid.
Definition
class OptionVideoFrame(ctypes.Structure):
_fields_ = [
("t", VideoFrame),
("is_some", ctypes.c_uint8),
]
def __init__(self, t: VideoFrame = None, is_some: int = None):
...
OptionVideoFrameDescriptor
Option type containing boolean flag and maybe valid data.
Fields
- t - Element that is maybe valid.
- is_some - Byte where
1
means elementt
is valid.
Definition
class OptionVideoFrameDescriptor(ctypes.Structure):
_fields_ = [
("t", VideoFrameDescriptor),
("is_some", ctypes.c_uint8),
]
def __init__(self, t: VideoFrameDescriptor = None, is_some: int = None):
...
Optionu32
Option type containing boolean flag and maybe valid data.
Fields
- t - Element that is maybe valid.
- is_some - Byte where
1
means elementt
is valid.
Definition
class Optionu32(ctypes.Structure):
_fields_ = [
("t", ctypes.c_uint32),
("is_some", ctypes.c_uint8),
]
def __init__(self, t: int = None, is_some: int = None):
...
Enums
BlinkStatePerEye
Describes the openness of an eye in discrete steps. What exactly constitues and open or closed eye is hardware specific.
Variants
- Invalid - Eye state was invalid, e.g., could not be measured.
- Open - Eye is open.
- Closed - Eye is closed.
Definition
class BlinkStatePerEye:
Invalid = 0
Open = 1
Closed = 2
ColliderType
The type of collider used in the game engine.
Variants
- Physical - A collider participating in physical hit tests.
- Trigger - A mostly semantic collider for activating things.
Definition
class ColliderType:
Physical = 1
Trigger = 2
ConnectionReadyState
Encodes if a (remote) connection is ready.
Variants
- NotReady - We have received no (the most common case), or less than ~8 bytes or so, which is the minimum needed to identify whether we speak the right protocol.
- HeadersReady - Headers have been read and are available.
Definition
class ConnectionReadyState:
NotReady = 0
HeadersReady = 1
CoordinateSystem
Gaze and similar data is usually recorded relative to the eye tracker. However, some applications benefit from using world space coordinates instead.
Variants
- World -
- Head -
Definition
class CoordinateSystem:
World = 0
Head = 1
FrameType
Describes what information a frame contains.
Variants
- Unknown - Frame type we don’t handle just yet.
- Init - Init frames must always be sent into the decoder as the first frame
- KeyFrame - Keyframes are fully self-contained and can be submitted standalone (they still require an Init frame to be sent first)
- DependsOnPrior - A frame depending on a previously submitted frame.
Definition
class FrameType:
Unknown = 0
Init = 1
KeyFrame = 2
DependsOnPrior = 3
ImageFormat
Video format of this frame.
Variants
- Unknown - Should not be used.
- RawMonochromeU8 - 8 bit row major with
0
being black and255
white.
Definition
class ImageFormat:
Unknown = 0
RawMonochromeU8 = 1
LogLevel
Log level for Ocumen functions.
Variants
- Off -
- Error -
- Warn -
- Info -
- Debug -
- Trace -
Definition
class LogLevel:
Off = 0
Error = 1
Warn = 2
Info = 3
Debug = 4
Trace = 5
LookedAtWith
Specified with which eye(s) the hit test should be performed.
Variants
- LeftEye -
- RightEye -
- EitherEye -
- BothEyes -
Definition
class LookedAtWith:
LeftEye = 0
RightEye = 1
EitherEye = 2
BothEyes = 3
ShapeType
How shape data is to be interpreted.
Variants
- Point -
points.0
is the point. - Line -
points.0
is the start of the line,points.1
is the end of the line. - Triangle - Trivial.
- AABB -
points.0
is one corner,point.1
the opposite corner, both must reside on the XY plane.points.0
is center,point.1
the diameter along the in x/y/z axis. - Sphere -
points.0
is center,point.1
the diameter as (d,d,d)
Definition
class ShapeType:
Point = 1
Line = 2
Triangle = 3
AABB = 5
Sphere = 6
TrackedData
Represents a ‘well known track’ contained in an Ocumen recording.
Variants
- CameraPose - Pose of the world camera.
- StereoViews - View matrices of the stereo cameras.
- StereoProjections - Projection matrices of the stereo cameras.
- FrameNumber - Game engine counter of drawn frame.
- GazeDeviceTime - Timestamp when the data was captured using the eye trackers clock
- GazeCombined - Combined gaze rays.
- GazeBinocular - Binocular gaze rays.
- GazeConvergenceDistance - Convergence distance for the gaze rays.
- GazePositionGuide - Describes users pupil position in relation to the optical axis.
- GazePupilSize - Size of the pupil.
- GazeBlinkState - Is user blinking or not.
- GazeEntrancePupil - Position of the entrance pupil.
- Objects - Objects and their poses.
- Meshes - Mesh data.
- Colliders - Colliders and their poses.
- Images - Images from various sources.
- Gizmos - User defined gizmos for debugging and scientific analysis.
- Videos - Video tracks, such as rendered GPU output.
- ControllerPose - Poses of connected and enabled XR controllers
- ControllerButtons - Boolean button states for XR controllers
Definition
class TrackedData:
CameraPose = 0
StereoViews = 1
StereoProjections = 2
FrameNumber = 3
GazeDeviceTime = 4
GazeCombined = 5
GazeBinocular = 6
GazeConvergenceDistance = 7
GazePositionGuide = 8
GazePupilSize = 9
GazeBlinkState = 10
GazeEntrancePupil = 11
Objects = 12
Meshes = 13
Colliders = 14
Images = 15
Gizmos = 16
Videos = 17
ControllerPose = 18
ControllerButtons = 19
VideoFormat
The video format of this frame.
Variants
- Unknown -
- CommonVideoH264v1 -
Definition
class VideoFormat:
Unknown = 0
CommonVideoH264v1 = 1
VideoTrack
The video format of this frame.
Variants
- Unknown -
- RenderedGame -
Definition
class VideoTrack:
Unknown = 0
RenderedGame = 1
WellKnownType
Some types are ‘well known’, that is, they have a definitive bit representation Ocumen knowns about, which can be used for visualization purposes (e.g., graphs).
Variants
- Unknown - The default representation.
- F32 - This is an IEEE
float
(f32) value.
Definition
class WellKnownType:
Unknown = 0
F32 = 1
XRInputDevice
Which controller is being described.
Variants
- Unknown - An unknown controller we could not resolve. This should not be used unless you ran into errors resolving a controller.
- Left - Left hand.
- Right - Right hand.
- Gamepad - Mostly pose-less game pad.
- Other - A user-defined controller.
Definition
class XRInputDevice:
Unknown = 0
Left = 1
Right = 2
Gamepad = 3
Other = 4
Functions
init_logging
Initializes logging.
If you want log messages this should be called exactly once, as early as possible. Otherwise log messages inside the library will not be recorded.
Definition
def init_logging(config: LoggerConfiguration):
...
process_log_messages
Process all outstanding log messages.
The provided callback will be invoked with all outstanding log messages that have occurred since the last invocation.
Definition
def process_log_messages(f):
...
version_ocumen_io_api
Returns the version of the used Ocumen IO API.
This version determines the library layer encoding actual VR scenes. If you have a mismatching data versions some field might be missing or wrong.
Most users should simply call connector.check_compatible()
to perform compatibility checks.
Definition
def version_ocumen_io_api() -> Version:
...
version_ocumen_recording
Returns the version of the Ocumen recording format.
This version determines how packets are transmitted ‘over the wire’. Mismatching low-level versions means recordings simply cannot be opened.
Most users should simply call connector.check_compatible()
to perform compatibility checks.
Definition
def version_ocumen_recording() -> Version:
...
matrix4_from_translation
Create a Matrix 4x4 with scale 1 translated to the given coordinates.
Definition
def matrix4_from_translation(x: float, y: float, z: float) -> Matrix4f32:
...
matrix4_from_translation_rotation
Create a Matrix 4x4 with scale 1 from the given translation, rotation.
Definition
def matrix4_from_translation_rotation(translation: ctypes.POINTER(Vector3f32), rotation: ctypes.POINTER(Quaternionf32)) -> Matrix4f32:
...
matrix4_invert
Inverts a matrix, returning NaN
s if not possible.
Definition
def matrix4_invert(original: ctypes.POINTER(Matrix4f32)) -> Matrix4f32:
...
quaternion_from_angle_axis
Create a quaternion from the given angle around an axis.
Definition
def quaternion_from_angle_axis(angle_deg: float, axis: ctypes.POINTER(Vector3f32)) -> Quaternionf32:
...
Services
WorldView ctor
Provides a view of an recording like Ocumen Studio.
A world view is a ‘view’ into a recorded session (‘world’) that contains a simple API to select a point in time and query the world state for that moment.
for_user ctor
Creates a view for the given user UUID.
The parameter user
should correspond to the user you want to query.
Safety
Parameter user
must not be 0
.
Definition
class WorldView:
@staticmethod
def for_user(user: int) -> WorldView:
...
scrub_to
View the world as it appeared at the given time.
The reader
must be an initialized WorldReader
instance, and time
a valid time stamp in
that recording.
After this method returns all other methods return data as present at this point in time.
Definition
class WorldView:
def scrub_to(self, reader: ctypes.c_void_p, time: int):
...
collider_poses
Returns poses for all colliders at this time.
Safety
The returned slice is only valid until your next Ocumen I/O call.
Definition
class WorldView:
def collider_poses(self, ) -> SliceColliderPose:
...
entity_labels
Returns labels for each known entity at this time.
Safety
The returned slice is only valid until your next Ocumen I/O call. In addition, you must NOT copy the returned slice, as each element also contains pointers to temporary memory. Instead, simply process the slice before your next call.
Definition
class WorldView:
def entity_labels(self, ) -> SliceEntityLabel:
...
gaze_binocular
Returns binocular (left / right) gaze data at this time.
Definition
class WorldView:
def gaze_binocular(self, system: ctypes.c_int) -> OptionBinocularGaze:
...
gaze_pupil_size
Returns pupil sizes at this time.
Definition
class WorldView:
def gaze_pupil_size(self, ) -> OptionPupilSizeAbsolute:
...
gaze_convergence_distance
Returns the gaze convergence distance at this time.
Definition
class WorldView:
def gaze_convergence_distance(self, ) -> OptionConvergenceDistance:
...
gaze_entrance_pupil
Returns the entrance pupil position at this time.
Definition
class WorldView:
def gaze_entrance_pupil(self, ) -> OptionEntrancePupilData:
...
frame_number
Returns the game’s frame number at this time.
Definition
class WorldView:
def frame_number(self, ) -> Optionu32:
...
looked_at
Perform a raycast / ‘gaze to object’ test with the user’s gaze.
The provided parameter is governed by enum LookedAtWith
and can be used to
specify what test to perform, e.g., whether either eye is sufficient, or if
both eyes need to hit. The returned slice contains the ColliderID
of each hit
collider.
Safety
The returned slice is only valid until your next Ocumen I/O call.
Definition
class WorldView:
def looked_at(self, with_eye: ctypes.c_int) -> Sliceu64:
...
WorldWriter ctor
Creates .ocumen
recordings.
Correctness
Unless otherwise stated all functions must be invoked with strictly increasing time stamps per type.
For example, once you have written a frame number for time 100
, you may only write another frame number
for time 101
or later. Failure to follow this rule will lead to unpredictable (‘invalid’) recordings that
visualize or report arbitrary query results.
This restriction holds ‘per type’, and other types are unaffected. For example, once you have written
frame number for time 100
, you may write a head pose for time 200
and then another frame number
for time 150
.
However, for most efficient recordings we recommend to minimize time jumps even between tracks.
from_uri ctor
Creates a recorder from a URI.
If the URI contains :
it is treated as an ip:port
to bind to, otherwise as a path
in the local file system.
Network Streaming
Since it is easier to connect to a mobile headset from a PC than the other way around,
the WorldWriter
opens a port on the given interface, therefore acting as a server!
Definition
class WorldWriter:
@staticmethod
def from_uri(uri: str) -> WorldWriter:
...
from_callback ctor
Creates a sans-io recorder.
When data is available the writer will invoke the given callback with a byte slice, which can then transmit the slice over network, bluetooth, … to another endpoint where it can be opened and read.
Definition
class WorldWriter:
@staticmethod
def from_callback(callback) -> WorldWriter:
...
handle_io
Writes cached data to files, network, a device …
Most data when passed to Ocumen I/O will be cached and compressed first before written to the underlying device. This function is where both a ‘check for sufficient data’ is performed and possibly executed.
Wheter data is actually written is unspecified, but depends on
- the serialization profile (a realtime profile is selected for network targets, while a high-compression profile is selected for storage targets),
- the size of the backing data struct,
- the number of entries.
This function differs from flush
in that it is more performant, but does not guarantee
that all data is written.
Definition
class WorldWriter:
def handle_io(self, ):
...
flush
Writes all outstanding data to the device.
Most users will not need to call this as flushing is handled transparently. A notable exception is towards the end of a session when you expect the application to be suddenly shut down.
Definition
class WorldWriter:
def flush(self, ):
...
frame_number
Stores the frame number for a user at a given time.
Definition
class WorldWriter:
def frame_number(self, user: UserAtTime, data: ctypes.POINTER(ctypes.c_uint32)):
...
headset_camera
Stores the head set camera pose for a user at a given time.
Definition
class WorldWriter:
def headset_camera(self, user: UserAtTime, data: ctypes.POINTER(CameraPose)):
...
headset_views
Stores the head set stereo view matrices for a user at a given time.
Definition
class WorldWriter:
def headset_views(self, user: UserAtTime, data: ctypes.POINTER(StereoViews)):
...
headset_projections
Stores the head set stereo projection matrices for a user at a given time.
Definition
class WorldWriter:
def headset_projections(self, user: UserAtTime, data: ctypes.POINTER(StereoProjections)):
...
gaze_combined
Stores ‘combined’ gaze for a user at a given time.
Definition
class WorldWriter:
def gaze_combined(self, user: UserAtTime, data: ctypes.POINTER(CombinedGaze)):
...
gaze_binocular
Stores binocular gaze for a user at a given time.
Definition
class WorldWriter:
def gaze_binocular(self, user: UserAtTime, data: ctypes.POINTER(BinocularGaze)):
...
gaze_eye_tracker_device_time
Stores the eye tracker’s device time stamp for a user at a given time.
Definition
class WorldWriter:
def gaze_eye_tracker_device_time(self, user: UserAtTime, data: ctypes.POINTER(EyeTrackerDeviceTimestamp)):
...
gaze_convergence_distance
Stores the gaze convergence distance for a user at a given time.
Definition
class WorldWriter:
def gaze_convergence_distance(self, user: UserAtTime, data: ctypes.POINTER(ConvergenceDistance)):
...
gaze_position_guide
Stores gaze position guidance for a user at a given time.
Definition
class WorldWriter:
def gaze_position_guide(self, user: UserAtTime, data: ctypes.POINTER(PositionGuide)):
...
gaze_pupil_size_absolute
Stores absolute pupil size information for a user at a given time.
Definition
class WorldWriter:
def gaze_pupil_size_absolute(self, user: UserAtTime, data: ctypes.POINTER(PupilSizeAbsolute)):
...
gaze_entrance_pupil
Stores entrance pupil data for a user at a given time.
Definition
class WorldWriter:
def gaze_entrance_pupil(self, user: UserAtTime, data: ctypes.POINTER(EntrancePupilData)):
...
gaze_blink_state
Stores blink state data for a user at a given time.
Definition
class WorldWriter:
def gaze_blink_state(self, user: UserAtTime, data: ctypes.POINTER(BlinkState)):
...
instance_lifetime
Stores data whether objects / colliders are alive or not for a user at a given time.
Definition
class WorldWriter:
def instance_lifetime(self, user: UserAtTime, slice: SliceInstanceLifetime | ctypes.Array[InstanceLifetime]):
...
object_poses
Stores object poses for a user at a given time.
Definition
class WorldWriter:
def object_poses(self, user: UserAtTime, slice: SliceObjectPose | ctypes.Array[ObjectPose]):
...
object_meshes
Stores object meshes (geometry) for a user at a given time.
Definition
class WorldWriter:
def object_meshes(self, user: UserAtTime, slice: SliceObjectMesh | ctypes.Array[ObjectMesh]):
...
mesh_data
Stores object mesh data for a user at a given time.
At the time of writing, by convention, only the first stored mesh per object is evaluated. If you store more than one mesh per object the behavior of Ocumen Studio is unspecified.
Definition
class WorldWriter:
def mesh_data(self, user: UserAtTime, mesh: int, vertices: SliceVector3f32 | ctypes.Array[Vector3f32], indices: Slicei32 | ctypes.Array[ctypes.c_int32]):
...
entity_label
Stores an entity label for a user at a given time.
Definition
class WorldWriter:
def entity_label(self, user: UserAtTime, entity: EntityLabelID, label: str):
...
collider_geometries
Stores simplified collider geometries for a user at a given time.
Definition
class WorldWriter:
def collider_geometries(self, user: UserAtTime, slice: SliceColliderShape | ctypes.Array[ColliderShape]):
...
collider_poses
Stores collider poses for a user at a given time.
Definition
class WorldWriter:
def collider_poses(self, user: UserAtTime, slice: SliceColliderPose | ctypes.Array[ColliderPose]):
...
gizmos_3d
Stores debug gizmos for a user at a given time.
Definition
class WorldWriter:
def gizmos_3d(self, user: UserAtTime, slice: SliceGizmo3D | ctypes.Array[Gizmo3D]):
...
image
Stores image data for a user at a given time.
Definition
class WorldWriter:
def image(self, user: UserAtTime, image: ctypes.POINTER(ImageDescriptor), data: Sliceu8 | ctypes.Array[ctypes.c_uint8]):
...
controller_button_state
Stores controller button state for a user at a given time.
Definition
class WorldWriter:
def controller_button_state(self, user: UserAtTime, slice: SliceControllerButtonState | ctypes.Array[ControllerButtonState]):
...
controller_poses
Stores controller poses for a user at a given time.
Definition
class WorldWriter:
def controller_poses(self, user: UserAtTime, slice: SliceControllerPose | ctypes.Array[ControllerPose]):
...
video_frame
Stores a (rendered and compressed) video frame for a user at a given time.
Definition
class WorldWriter:
def video_frame(self, user_id: int, frame_data: ctypes.POINTER(VideoFrameDescriptor), data: Sliceu8 | ctypes.Array[ctypes.c_uint8]):
...
generic_descriptor
Obtains a low-level track handle to store custom data.
Definition
class WorldWriter:
def generic_descriptor(self, request: Descriptor, handle: ctypes.POINTER(TrackHandle)):
...
generic_data
Store custom data for a track handle.
Definition
class WorldWriter:
def generic_data(self, handle: TrackHandle, times: Slicei64 | ctypes.Array[ctypes.c_int64], data: ctypes.c_void_p):
...
WorldReader ctor
Wraps a WorldConnector
and provides methods to read XR events.
This is the main service to read Ocumen recordings. It knows about all concepts encoded in a recording and provides low-to-midlevel helper functions to extract event data.
Depending on your use case the methods in here might be enough, or you have to pass this world reader to various utils that can help you extract specific ‘views of the world’ more efficiently.
from_connector ctor
Creates a new reader from a connector.
After calling this method the provided connector is invalidated and must not be reused.
Definition
class WorldReader:
@staticmethod
def from_connector(connector: ctypes.c_void_p) -> WorldReader:
...
read_incremental
Read all (newly) available data.
Ocumen streams can be read from any I/O, including offline recordings from disks and live streaming from networks. This function tries to read and parse all data that is availble so far. When reading from disk it usually needs to be called once, when streaming live data from network it makes sense to call this function a few times every second.
Ultimately, this function is what makes ’new data appear’. If you open any data source
and never call read_incremental
the recording will look empty.
Definition
class WorldReader:
def read_incremental(self, ):
...
set_error_callback
Sets a callback invoked on read errors.
As errors are rare and primariliy related to corrupt recordings, and to simplify regular calls, most methods return data instead of error codes. When such an error occurs they will return empty options or slices, and the callback provided here is invoked instead.
Definition
class WorldReader:
def set_error_callback(self, error_callback, error_ctx: ctypes.c_void_p):
...
tracked_data
Lists all track types known to exist in this recording.
Definition
class WorldReader:
def tracked_data(self, user: int) -> SliceTrackedData:
...
tracked_well_knowns
List generic handles and their type information.
Definition
class WorldReader:
def tracked_well_knowns(self, user: int) -> SliceWellKnownTypedTrack:
...
tracked_well_knowns_info
Returns meta data for track handles.
Definition
class WorldReader:
def tracked_well_knowns_info(self, handle: TrackHandle, user: int) -> SliceTrackedWellKnownInfo:
...
list_users
Lists all users present in this recording.
Definition
class WorldReader:
def list_users(self, ) -> Sliceu64:
...
latest_meshes_for
Lists the latest available mesh data for a user in a time range.
Definition
class WorldReader:
def latest_meshes_for(self, meta: UserInTimeRange) -> SliceMesh:
...
latest_entity_labels_for
Lists the latest entity labels for a user in a time range.
Definition
class WorldReader:
def latest_entity_labels_for(self, meta: UserInTimeRange) -> SliceEntityLabel:
...
latest_instance_lifetime_for
Lists the latest instance lifetime information for a user in a time range.
Definition
class WorldReader:
def latest_instance_lifetime_for(self, meta: UserInTimeRange) -> TimesValuesInstanceLifetime:
...
latest_object_poses_for
Lists the latest object poses for a user in a time range.
Definition
class WorldReader:
def latest_object_poses_for(self, meta: UserInTimeRange) -> TimesValuesObjectPose:
...
latest_object_meshes_for
Lists the latest object meshes for a user in a time range.
Definition
class WorldReader:
def latest_object_meshes_for(self, meta: UserInTimeRange) -> TimesValuesObjectMesh:
...
latest_frame_numbers_for
Lists the latest frame number for a user in a time range.
Definition
class WorldReader:
def latest_frame_numbers_for(self, meta: UserInTimeRange) -> TimesValuesu32:
...
latest_headset_camera_for
Lists the latest headset camera pose for a user in a time range.
Definition
class WorldReader:
def latest_headset_camera_for(self, meta: UserInTimeRange) -> TimesValuesCameraPose:
...
latest_headset_projections_for
Lists the latest headset stereo projections for a user in a time range.
Definition
class WorldReader:
def latest_headset_projections_for(self, meta: UserInTimeRange) -> TimesValuesStereoProjections:
...
latest_headset_views_for
Lists the latest headset stereo view matrices for a user in a time range.
Definition
class WorldReader:
def latest_headset_views_for(self, meta: UserInTimeRange) -> TimesValuesStereoViews:
...
latest_gaze_combined_for
Returns the latest combined gaze for a user in a time range.
Definition
class WorldReader:
def latest_gaze_combined_for(self, meta: UserInTimeRange) -> OptionTimeValueCombinedGaze:
...
latest_gaze_binocular_for
Returns the latest binocular gaze for a user in a time range.
Definition
class WorldReader:
def latest_gaze_binocular_for(self, meta: UserInTimeRange) -> OptionTimeValueBinocularGaze:
...
latest_gaze_device_time_for
Returns the latest eye tracking device data for a user in a time range.
Definition
class WorldReader:
def latest_gaze_device_time_for(self, meta: UserInTimeRange) -> OptionTimeValueEyeTrackerDeviceTimestamp:
...
latest_gaze_convergence_distance_for
Returns the latest convergence distance for a user in a time range.
Definition
class WorldReader:
def latest_gaze_convergence_distance_for(self, meta: UserInTimeRange) -> OptionTimeValueConvergenceDistance:
...
latest_gaze_position_guide_for
Returns the latest position guide information for a user in a time range.
Definition
class WorldReader:
def latest_gaze_position_guide_for(self, meta: UserInTimeRange) -> OptionTimeValuePositionGuide:
...
latest_gaze_pupil_size_abs_for
Returns the latest pupil size absolute for a user in a time range.
Definition
class WorldReader:
def latest_gaze_pupil_size_abs_for(self, meta: UserInTimeRange) -> OptionTimeValuePupilSizeAbsolute:
...
latest_gaze_blink_state_for
Returns the latest blink state for a user in a time range.
Definition
class WorldReader:
def latest_gaze_blink_state_for(self, meta: UserInTimeRange) -> OptionTimeValueBlinkState:
...
latest_gaze_entrance_pupil_for
Returns the latest entrance pupil for a user in a time range.
Definition
class WorldReader:
def latest_gaze_entrance_pupil_for(self, meta: UserInTimeRange) -> OptionTimeValueEntrancePupilData:
...
latest_collider_geometries_for
Lists the latest collider shapes for a user in a time range.
Definition
class WorldReader:
def latest_collider_geometries_for(self, meta: UserInTimeRange) -> TimesValuesColliderShape:
...
latest_collider_poses_for
Lists the latest collider poses for a user in a time range.
Definition
class WorldReader:
def latest_collider_poses_for(self, meta: UserInTimeRange) -> TimesValuesColliderPose:
...
latest_gizmos_3d_for
Lists the latest debug gizmos for a user in a time range.
Definition
class WorldReader:
def latest_gizmos_3d_for(self, meta: UserInTimeRange) -> TimesValuesGizmo3D:
...
image
Lists the latest image data for a user in a time range.
Definition
class WorldReader:
def image(self, meta: UserInTimeRange, track: int) -> SliceImageData:
...
latest_controller_button_states_for
Lists the latest controller button states for a user in a time range.
Definition
class WorldReader:
def latest_controller_button_states_for(self, meta: UserInTimeRange) -> SliceControllerButtonState:
...
latest_controller_poses_for
Lists the latest controller poses for a user in a time range.
Definition
class WorldReader:
def latest_controller_poses_for(self, meta: UserInTimeRange) -> SliceControllerPose:
...
video_frames_meta
Returns the latest video frame descriptors for a user in a time range.
Definition
class WorldReader:
def video_frames_meta(self, meta: UserAtTime, track: ctypes.c_int) -> OptionVideoFrameDescriptor:
...
video_frames
Lists the latest video frames for a user in a time range.
Definition
class WorldReader:
def video_frames(self, meta: UserAtTime, track: ctypes.c_int) -> SliceVideoFrame:
...
video_frame_single_only
Returns the latest video frame for a user in a time range.
Definition
class WorldReader:
def video_frame_single_only(self, meta: UserAtTime, track: ctypes.c_int) -> OptionVideoFrame:
...
video_frame_init_packet
Returns the latest video init packet for a user in a time range.
Definition
class WorldReader:
def video_frame_init_packet(self, user_id: int, track: ctypes.c_int) -> OptionVideoFrame:
...
generic_descriptor
Returns a specific generic descriptor.
Definition
class WorldReader:
def generic_descriptor(self, cls: str, prop: str, id: int, user: int, handle: ctypes.POINTER(TrackHandle)):
...
generic_count
Counts how many elements are available for the given descriptor.
Definition
class WorldReader:
def generic_count(self, handle: TrackHandle, first_inclusive: int, last_inclusive: int, count: ctypes.POINTER(ctypes.c_uint32)):
...
generic_data
Loads data for a generic descriptor.
Definition
class WorldReader:
def generic_data(self, handle: TrackHandle, first_inclusive: int, last_inclusive: int, times: SliceMuti64 | ctypes.Array[ctypes.c_int64], data: ctypes.c_void_p):
...
recording_information
Return common recording information.
Definition
class WorldReader:
def recording_information(self, ) -> RecordingInformation:
...
track_times
Lists all times for which data is available given a certain entry.
Definition
class WorldReader:
def track_times(self, user_id: int, times: ctypes.c_int) -> Slicei64:
...
WorldConnector ctor
Handles stream endpoint connections to something speaking “Ocumen”.
Use this class to open a file or network connection and verify whether
the endpoint has the right version. Once the connection is established
pass it to a WorldReader
.
from_file ctor
Opens a file endpoint at the given path, e.g., /tmp/file.ocumen
or C:\file.ocumen
.
Definition
class WorldConnector:
@staticmethod
def from_file(uri: str) -> WorldConnector:
...
from_multiple_files ctor
Loads multiple recordings as one.
Ocumen support overlaying multiple recordings into one, e.g., when dealing with multiple users, or when loading a recording and additional scientific annotations generated by Python.
Definition
class WorldConnector:
@staticmethod
def from_multiple_files(sources: ctypes.c_void_p) -> WorldConnector:
...
from_network ctor
Opens a network endpoint at the given TCP address, e.g., 127.0.0.1:6677
.
If the additional parameter mirror_copy
is given the network stream will also be stored
in the specified file.
Definition
class WorldConnector:
@staticmethod
def from_network(uri: str, mirror_copy: str) -> WorldConnector:
...
connection_state
Returns if all headers have been loaded from the network stream.
Definition
class WorldConnector:
def connection_state(self, ready_state: ctypes.POINTER(ctypes.c_int)):
...
app_version
Returns the application version embedded in this endpoint.
In most cases this should be Piglet with a version matching this library.
Definition
class WorldConnector:
def app_version(self, version: ctypes.POINTER(Version)):
...
stream_version
Returns the stream version of this endpoint.
Definition
class WorldConnector:
def stream_version(self, version: ctypes.POINTER(Version)):
...
check_compatible
Check if the endpoint is compatible with this version.
When they are compatible the function silently passes, if they are incompatible an error code is returned, translated to an exception in Python or C#.
Definition
class WorldConnector:
def check_compatible(self, ):
...
MultipleFiles ctor
Helper for loading combined (stacked) recordings.
new ctor
Create a new stacked recording handler.
Definition
class MultipleFiles:
@staticmethod
def new() -> MultipleFiles:
...
add_file
Add a file to a stack.
Definition
class MultipleFiles:
def add_file(self, source: str):
...