blinklinmult.data.stills

Derive single frames from windowed corpora, for the frame-wise model.

BlinkCNN classifies one eye crop at a time, so it can train on any annotated frame — the still corpora, and equally the video corpora with their time dimension ignored. Rather than build a second set of HDF5 files, this module reduces an already-built window to its individual frames at load time: the same bytes serve both the sequence models and the frame-wise one.

Balancing. Sampled as they fall, video frames are overwhelmingly open-eyed — a blink occupies a handful of frames per second of recording. Training on that distribution teaches “predict open”, which scores well on accuracy and detects nothing. Every closed-eye frame is therefore kept and the open-eye frames are subsampled to StillConfig.open_to_closed, giving a set comparable to CEW’s natural 1193/1232.

Determinism. The subsample is drawn once, at construction, from a seeded generator. Two runs with the same seed see the same frames, and a frame’s identity does not change between epochs.

Attributes

logger

Module-level logger.

MASK_SUFFIX

Suffix OmniLoader appends to a key to name its validity mask.

CLOSED_THRESHOLD

Eye-state value above which a frame counts as closed.

Exceptions

StillsError

Raised when a windowed corpus cannot be reduced to frames.

Classes

StillConfig

How to draw single frames from windowed samples.

StillFramesDataset

A windowed corpus served one frame at a time.

Module Contents

blinklinmult.data.stills.logger

Module-level logger.

blinklinmult.data.stills.MASK_SUFFIX = '_mask'

Suffix OmniLoader appends to a key to name its validity mask.

blinklinmult.data.stills.CLOSED_THRESHOLD = 0.5

Eye-state value above which a frame counts as closed.

The targets are written as floats so a corpus may express uncertainty, but the balancing only needs the two classes.

exception blinklinmult.data.stills.StillsError

Bases: RuntimeError

Raised when a windowed corpus cannot be reduced to frames.

Initialize self. See help(type(self)) for accurate signature.

class blinklinmult.data.stills.StillConfig

How to draw single frames from windowed samples.

Parameters:

  • stride (int) – Keep every Nth frame of a window. Consecutive frames of a recording are near-identical, so taking all of them inflates the corpus without adding information. Closed-eye frames ignore the stride — they are too scarce to thin.

  • open_to_closed (float) – Open-eye frames to keep per closed-eye frame. 1.0 balances the classes. Raise it to keep more negatives.

  • seed (int) – Seed for the open-eye subsample.

__post_init__() → None

Validate the configuration.

Raises:

StillsError – If a value is out of range.

class blinklinmult.data.stills.StillFramesDataset(dataset: omniloader.loader.SizedDataset, config: StillConfig, name: str, balance: bool = True)

A windowed corpus served one frame at a time.

Each item is a window collapsed to a single timestep: every sequence-valued key is indexed at the chosen frame and re-wrapped with a length-1 time axis, so the sample satisfies the same schema as a natively still corpus.

Parameters:

  • dataset (SizedDataset) – The corpus’s split, yielding windowed samples.

  • config (StillConfig) – Sampling and balancing settings.

  • name (str) – Corpus name, for log lines and error messages.

  • balance (bool) – Subsample open-eye frames. Left off for evaluation splits, which must be scored on the real class distribution.

Raises:

StillsError – If the corpus does not annotate eye state, or no frame survives selection.

__len__() → int

Number of frames served.

Returns:

Frame count.

Return type:

int

__getitem__(index: int) → dict

Return one frame as a single-timestep sample.

Parameters:

index (int) – Position within the selected frames.

Returns:

The window’s keys, each reduced to its chosen frame and given a length-1 time axis.

Return type:

dict