blinklinmult.registry

Where published weights live, and what each model expects at its input.

One table, MODELS, describing every shipped model: which file holds its weights, how crops must be normalised for it, and the operating point fitted for turning its scores into blink events.

The normalisation entry is the reason this table exists rather than a set of constants scattered across the model classes. The 1.x networks were trained on ImageNet-standardised crops and BlinkCNN on plain /255; applying the wrong convention costs accuracy without raising anything, so the value has to travel with the model id rather than be assumed by the caller.

Attributes

HF_MODEL_REPO

Public Hugging Face repository holding the published weights.

IMAGENET_MEAN

ImageNet channel means -- the 1.x normalisation.

IMAGENET_STD

ImageNet channel standard deviations -- the 1.x normalisation.

UNIT_MEAN

crops are already /255, so nothing is subtracted.

UNIT_STD

v2's normalisation. See UNIT_MEAN.

V1_FEATURE_ORDER

How to reorder a v2 feature vector into the 1.x layout.

MODELS

Every shipped model, keyed by id.

Classes

ModelSpec

Everything needed to run one published model.

Functions

spec(→ ModelSpec)

Look up one model's specification.

Module Contents

blinklinmult.registry.HF_MODEL_REPO = 'fodorad/blink_detection'

Public Hugging Face repository holding the published weights.

blinklinmult.registry.IMAGENET_MEAN: tuple[float, float, float] = (0.485, 0.456, 0.406)

ImageNet channel means – the 1.x normalisation.

blinklinmult.registry.IMAGENET_STD: tuple[float, float, float] = (0.229, 0.224, 0.225)

ImageNet channel standard deviations – the 1.x normalisation.

blinklinmult.registry.UNIT_MEAN: tuple[float, float, float] = (0.0, 0.0, 0.0)

crops are already /255, so nothing is subtracted.

Type:

v2’s normalisation

blinklinmult.registry.UNIT_STD: tuple[float, float, float] = (1.0, 1.0, 1.0)

v2’s normalisation. See UNIT_MEAN.

blinklinmult.registry.V1_FEATURE_ORDER: tuple[tuple[int, int], ...] = ((157, 160), (0, 157))

How to reorder a v2 feature vector into the 1.x layout.

blinklinmult-union was trained on [head_pose(3), landmarks(142), iris(10), diameters(2), eyelid(2), ear(1)] – head pose first. The v2 schema puts head pose last. These slices, concatenated in order, convert one to the other.

Measured on an rn30 window with an annotated blink: feeding the v2 order gives a peak probability of 0.0002 (the model never fires), and the v1 order with the same standardisation gives 0.91, bracketing the annotated frames.

class blinklinmult.registry.ModelSpec[source]

Everything needed to run one published model.

Parameters:

  • model_id (str) – Short selector, e.g. "blinkcnn".

  • filename (str) – Its weight file in HF_MODEL_REPO.

  • generation (str) – Which body of work produced the weights – "paper" for the 1.x publication, "v2" for the current rewrite. Provenance only; it does not decide how the file is loaded. See runtime.

  • runtime (str) –

    What loads and executes the file – "onnx" for a frozen graph run through onnxruntime, "pytorch" for a checkpoint rebuilt into an Module.

    Separate from generation on purpose. The two partitions coincided while every 1.x model was ONNX and every v2 model was torch, and one field answered both questions. blinkcnn shipping in both runtimes ends that: it is generation="v2" either way, and only runtime says which loader to call.

  • mean (tuple[float, float, float]) – Per-channel mean to subtract.

  • std (tuple[float, float, float]) – Per-channel divisor.

  • image_size (int) – Crop side the model was trained on.

  • window (int | None) – Frames per window the model was trained on, or None for the frame-wise models, which score each frame alone and accept any length. The 1.x sequence models were trained on 15-frame (~0.5 s) windows and degrade markedly when given longer ones – see the note on MODELS.

  • needs_features (bool) – Whether it also takes the 160-d descriptor stream.

  • standardise_features (bool) – Whether that stream must be z-scored with corpus-wide statistics before use. The 1.x two-stream model was trained on standardised descriptors, and feeding it raw ones leaves its logits saturated near -9.9 – it silently never fires.

  • threshold (float) – Score above which a run counts as a blink. The 1.x models carry the plain 0.5 default rather than a fitted value – see the note on MODELS.

  • low_ratio (float | None) – Hysteresis low threshold as a fraction of threshold; None for a single cut.

  • description (str) – One line for a UI or a model card.

blinklinmult.registry.MODELS: dict[str, ModelSpec]

Every shipped model, keyed by id.

blinklinmult.registry.spec(model_id: str) → ModelSpec[source]

Look up one model’s specification.

Parameters:

model_id (str) – A key of MODELS.

Returns:

Its entry.

Return type:

ModelSpec

Raises:

KeyError – If the id is not registered.