meyelens.meye

class meyelens.meye.Meye(model=None)[source]

Bases: object

Pupil segmentation and basic shape extraction using a pre-trained neural network.

This class loads a Keras/TensorFlow segmentation model and exposes a predict() method that:

  1. converts the input frame to grayscale (if needed)

  2. resizes it to the model input size (hardcoded to 128x128 in this implementation)

  3. runs inference to obtain a pupil mask

  4. optionally performs morphological post-processing to isolate the pupil region

  5. optionally fits an ellipse to estimate major/minor diameters and orientation

model_path

Path to the Keras model file used for inference.

Type:

str or pathlib.Path

model

Loaded Keras model.

Type:

tensorflow.keras.Model

requiredFrameSize

Expected model input frame size (height, width) derived from the model input. Note: this implementation still resizes to 128x128 in predict().

Type:

tuple[int, int]

centroid

Centroid (row, col) of the largest detected pupil region after post-processing. Set to (np.nan, np.nan) when no pupil is found.

Type:

tuple[float, float] or float

pupil_size

Number of non-zero pixels in the resized pupil mask (in the original image size).

Type:

float

major_diameter

Major axis length from an ellipse fit (in pixels), if available.

Type:

float

minor_diameter

Minor axis length from an ellipse fit (in pixels), if available.

Type:

float

orientation

Ellipse orientation angle (degrees), if available.

Type:

float

Notes

  • This class prints GPU availability on initialization (no logging).

  • The model is assumed to return two outputs (mask, info). Only mask is used.

  • Coordinate conventions:

    • centroid from skimage.measure.regionprops() is (row, col).

    • the recorders write centroid as (x=col, y=row) by swapping indices.

predict(img, post_proc: bool = True, morph: bool = True, fill_ellipse: bool = False)[source]

Predict a pupil mask and centroid from an input image.

Parameters:

  • img (numpy.ndarray) – Input frame, grayscale (H, W) or BGR (H, W, 3).

  • post_proc (bool, optional) – If True, apply morphProcessing() to binarize, keep the largest connected component, and perform morphological closing. If False, the raw network output is used and centroid is set to (0, 0).

  • morph (bool, optional) – If True, attempt ellipse fitting on the post-processed mask to estimate major/minor diameters and orientation.

  • fill_ellipse (bool, optional) – If True, replace the mask with a filled ellipse fitted to the contour (useful for smoothing irregular segmentations).

Returns:

  • pupil_resized (numpy.ndarray) – Processed pupil mask resized back to the original image size. Pixel values are 0/255 when post-processing is enabled.

  • centroid (tuple[float, float]) – Centroid of the detected pupil region in (row, col) format.

Notes

  • The model input is normalized to [0, 1] and shaped as (1, H, W, 1).

  • This implementation resizes inputs to 128x128 regardless of requiredFrameSize.

morphProcessing(sourceImg, thr: float = 0.8)[source]

Post-process the raw model output to isolate the pupil region.

Steps

  1. Threshold the model output at thr

  2. Label connected components

  3. Keep only the largest component

  4. Apply morphological closing with an elliptical kernel

param sourceImg:

Raw model output mask (float array in [0, 1]).

type sourceImg:

numpy.ndarray

param thr:

Threshold used to binarize the mask.

type thr:

float, optional

returns:

  • morph (numpy.ndarray) – Post-processed binary mask as uint8 with values 0 or 255.

  • centroid (tuple[float, float]) – Centroid of the largest component in (row, col) format. Returns (np.nan, np.nan) if no component is found.

static fit_ellipse_and_fill(mask)[source]

Fit an ellipse to the pupil mask and return a filled ellipse mask.

Parameters:

mask (numpy.ndarray) – Binary mask (uint8) typically with values 0/255.

Returns:

New mask where the pupil is represented by a filled ellipse (0/255). If ellipse fitting is not possible, returns the input mask.

Return type:

numpy.ndarray

Notes

  • Uses the convex hull of the largest contour to stabilize ellipse fitting.

  • OpenCV requires at least 5 points to fit an ellipse.

static overlay_roi(mask, roi, ratios=(0.7, 0.3))[source]

Overlay a pupil mask over a region of interest (ROI) image.

Parameters:

  • mask (numpy.ndarray) – Binary mask to overlay (expected 0/255).

  • roi (numpy.ndarray) – Base image (typically BGR) to overlay on.

  • ratios (tuple[float, float], optional) – Blending ratios for (roi, mask_color) passed to cv2.addWeighted().

Returns:

Blended image for visualization.

Return type:

numpy.ndarray

static mask2color(mask, channel: int = 1)[source]

Convert a single-channel mask into a 3-channel color image.

Parameters:

  • mask (numpy.ndarray) – 2D mask.

  • channel (int, optional) – Channel to place the mask in: - 0: red - 1: green - 2: blue

Returns:

3-channel image with the mask in the selected channel.

Return type:

numpy.ndarray

preview(cam)[source]

Run a real-time preview loop showing pupil segmentation overlay.

Parameters:

cam (Camera) – Camera instance providing frames via Camera.get_frame().

Return type:

None

Notes

Press “q” in the preview window to exit.

class meyelens.meye.MeyeRecorder(cam_ind=0, model=None, show_preview=False, filename='meye', folder_path='Data', sep=';')[source]

Bases: object

Synchronous frame-by-frame recorder using Meye and FileWriter.

This recorder captures frames from a Camera, runs pupil detection, and writes one line per frame to a semicolon-separated text file.

The output columns are:

  • time (seconds since start)

  • x, y (centroid coordinates; written as col, row)

  • pupil (mask area in pixels)

  • major_diameter, minor_diameter, orientation (ellipse fit; may be NaN)

  • trg1 … trg9 (user-defined trigger values)

Parameters:

  • cam_ind (int, optional) – Camera index passed to Camera.

  • model (str or pathlib.Path or None, optional) – Path to the Keras model file. If None, the packaged model is used.

  • show_preview (bool, optional) – If True, display an overlay window during recording.

  • filename (str, optional) – Base filename used by FileWriter (timestamp is added automatically).

  • folder_path (str, optional) – Output folder where the text file is created.

  • sep (str, optional) – Column separator used in the output file.

Notes

This recorder writes synchronously to disk at each save_frame() call.

start() → None[source]

Start recording and initialize the output file.

Return type:

None

preview() → None[source]

Open a live preview window (segmentation overlay).

Return type:

None

save_frame(trg1=0, trg2=0, trg3=0, trg4=0, trg5=0, trg6=0, trg7=0, trg8=0, trg9=0) → None[source]

Capture one frame, run pupil detection, and append a row to the output file.

Parameters:

  • trg1 (int, optional) – Trigger values to save alongside the measurements.

  • trg2 (int, optional) – Trigger values to save alongside the measurements.

  • trg3 (int, optional) – Trigger values to save alongside the measurements.

  • trg4 (int, optional) – Trigger values to save alongside the measurements.

  • trg5 (int, optional) – Trigger values to save alongside the measurements.

  • trg6 (int, optional) – Trigger values to save alongside the measurements.

  • trg7 (int, optional) – Trigger values to save alongside the measurements.

  • trg8 (int, optional) – Trigger values to save alongside the measurements.

  • trg9 (int, optional) – Trigger values to save alongside the measurements.

Return type:

None

get_data()[source]

Capture one frame and return instantaneous pupil metrics.

Returns:

Dictionary containing:

  • centroid: (x, y) as (col, row)

  • size: pupil mask area in pixels

  • major_diameter: ellipse major axis in pixels (or NaN)

  • minor_diameter: ellipse minor axis in pixels (or NaN)

  • orientation: ellipse angle (degrees) (or NaN)

Return type:

dict

stop() → None[source]

Stop recording and close the output file.

Return type:

None

close() → None[source]

Release the camera resource.

Return type:

None

close_all() → None[source]

Stop recording and release all resources (file + camera).

Return type:

None

class meyelens.meye.MeyeAsyncRecorder(cam_ind=0, model=None, show_preview=False, path_to_file='Data', filename='meye', buffer_size=100, sep=';', cam_crop=None)[source]

Bases: object

Asynchronous frame-by-frame recorder using Meye and BufferedFileWriter.

This recorder is similar to MeyeRecorder, but data rows are queued in memory and written to disk by a background thread, reducing I/O latency inside tight loops.

Parameters:

  • cam_ind (int, optional) – Camera index passed to Camera.

  • model (str or pathlib.Path or None, optional) – Path to the Keras model file. If None, the packaged model is used.

  • show_preview (bool, optional) – If True, display an overlay window during recording.

  • path_to_file (str, optional) – Output folder where the text file is created.

  • filename (str, optional) – Base filename used by BufferedFileWriter (timestamp is added automatically).

  • buffer_size (int, optional) – Queue size for BufferedFileWriter. When full, new rows are discarded and a warning is printed by the writer (no logging).

  • sep (str, optional) – Column separator used in the output file.

  • cam_crop (list[int] or tuple[int, int, int, int] or None, optional) – Crop passed to Camera (implementation-dependent).

Notes

You must call stop() (or close_all()) to flush remaining queued data.

start(metadata=None) → None[source]

Start recording and initialize the asynchronous output writer.

Parameters:

metadata (dict or None, optional) – Metadata passed to BufferedFileWriter and written as comment lines at the top of the file.

Return type:

None

preview() → None[source]

Open a live preview window (segmentation overlay).

Return type:

None

save_frame(trg1=0, trg2=0, trg3=0, trg4=0, trg5=0, trg6=0, trg7=0, trg8=0, trg9=0) → None[source]

Capture one frame, run pupil detection, and queue a row for disk writing.

Parameters:

  • trg1 (int, optional) – Trigger values to save alongside the measurements.

  • trg2 (int, optional) – Trigger values to save alongside the measurements.

  • trg3 (int, optional) – Trigger values to save alongside the measurements.

  • trg4 (int, optional) – Trigger values to save alongside the measurements.

  • trg5 (int, optional) – Trigger values to save alongside the measurements.

  • trg6 (int, optional) – Trigger values to save alongside the measurements.

  • trg7 (int, optional) – Trigger values to save alongside the measurements.

  • trg8 (int, optional) – Trigger values to save alongside the measurements.

  • trg9 (int, optional) – Trigger values to save alongside the measurements.

Return type:

None

get_data()[source]

Capture one frame and return instantaneous pupil metrics.

Returns:

Dictionary containing:

  • centroid: (x, y) as (col, row)

  • size: pupil mask area in pixels

  • major_diameter: ellipse major axis in pixels (or NaN)

  • minor_diameter: ellipse minor axis in pixels (or NaN)

  • orientation: ellipse angle (degrees) (or NaN)

Return type:

dict

stop() → None[source]

Stop recording and close the output file (flushes queued data).

Return type:

None

close() → None[source]

Release the camera resource.

Return type:

None

close_all() → None[source]

Stop recording and release all resources (writer + camera).

Return type:

None