Skip to main content

mouse-pupil-analysis

Agent Collab Treaty adopted DOI

Pupil analysis pipeline demo

Left: confidence-colored pupil mask and estimated center. Right: pupil diameter, center, and speed over time.

Measure mouse pupil diameter from a video or a folder of frames, in one command. A trained UNet ships inside the package, so there is no model to download. It targets the low-contrast, low-resolution frames that rodent eye cameras actually produce. With --calculate_velocity, it also tracks pupil center, speed, and per-frame segmentation quality.

The model predicts a pupil mask and a circle around it. It keeps whole blobs with at least 20% of their area inside the circle and measures diameter from their combined area.

Contents

Install

pip install mouse-pupil-analysis

Python 3.10 or newer. The trained checkpoint ships with the package, so that is the entire install. See Installation options if you need a particular PyTorch CPU or accelerator build.

Usage

Analyze a video:

run-pupil-analysis --video_path movie.avi

Or analyze a folder of PNG frames:

run-pupil-analysis --image_dir movie_frames/

To save confidence overlays on the original images:

run-pupil-analysis --video_path data/mouse1.avi --output_mask_dir data/predicted_masks_mouse1

The model has two heads; the collapsible examples below show how to inspect each head separately or both together.

Inspect the segmentation output

Inspect the segmentation head before geometry-based component selection:

run-pupil-analysis --image_dir movie_frames/ --output_mask_dir results/mask_overlays/ --raw-segmentation

Open results/mask_overlays/ to examine the visible-pupil mask. The overlay colors show the segmentation probabilities above the calibrated threshold. The center marker is calculated from the segmentation.

Inspect the geometry head independently

Save just the predicted circle and center using the packaged two-head model:

run-pupil-analysis --image_dir movie_frames/ --output_mask_dir results/geometry_overlays/ --geometry-head-only

Open results/geometry_overlays/ to see the yellow circle and center on each frame resized and padded to 148 x 148. This view shows the geometry prediction without segmentation colors or a segmentation-derived center marker. The circle describes the visible-pupil region learned during training. This flag changes overlays only; the usual CSV and plot still report segmentation-based measurements. Python callers can pass geometry_head_only=True to analyze_frames or analyze_video.

Show both heads, the retained mask, and discarded blobs

Save a combined diagnostic overlay using the packaged model:

run-pupil-analysis \
  --image_dir movie_frames/ \
  --output_mask_dir results/all_heads/ \
  --show-all-heads \
  --mask_transparency 0.35

All threshold-passing segmentation pixels keep their usual yellow-orange-red confidence colors, including blobs removed during selection. The geometry circle and center keep the same yellow styling as --geometry-head-only. A thin, translucent white dashed contour marks the retained mask. Everything uses the same full-image resize and padding as the model input; no source crop is taken.

Geometry-based component selection runs by default. --show-all-heads changes the overlay only; the dashed contour identifies the final mask used for diameter and tracking while the other blobs remain visible for inspection. Add --raw-segmentation to bypass selection; all threshold-passing regions are then retained and outlined.

Custom checkpoints can be supplied with --checkpoint. Legacy mask-only checkpoints still support ordinary inference, but cannot show a geometry output. For custom training output named all_data_geometry.pth, threshold calibration is read from all_data.json in the same directory. Use --pred_thresh to override it.

To track the pupil center and its speed:

run-pupil-analysis \
  --video_path movie.avi \
  --calculate_velocity \
  --acquisition_fps 33.3333333333

Velocity timing. With video input, --acquisition_fps is optional: when it is omitted, the program uses the frame rate encoded in the video. A PNG directory has no such metadata, so velocity mode requires --acquisition_fps and otherwise reports an error. For scientifically meaningful speeds, always provide the camera's actual acquisition rate; a video header may not represent experimental time.

Video frames are sampled at 5 fps by default; velocity mode analyzes every encoded frame instead. Inference uses CUDA when available.

Show all command-line options
Flag Description
--video_path Input video. Frames are extracted automatically before analysis. Mutually exclusive with --image_dir.
--image_dir Input directory of existing PNG frames, used instead of a video.
--out_dir Where to write extracted frames. Defaults to <video_stem>_frames/ next to the video.
--result_dir Where to write the CSV and plot. Defaults to <video_stem>_result/ for video input and <image_dir>_result/ for --image_dir.
--output_mask_dir Save translucent confidence-heatmap overlays for threshold-passing pupil pixels. Yellow is closest to the prediction threshold, orange is intermediate, and red is near-perfect confidence.
--pred_thresh Override the pixel-confidence threshold with a value strictly between 0 and 1. The packaged model uses 0.525. Custom checkpoints use their calibration metadata, then a threshold in the filename, then 0.7 as a fallback. Increase it to reduce foreground; decrease it to include more.
--prefer_central_component Deprecated. Retained for compatibility with the legacy fixed-image-center selector and emits a warning when used. Omit it to use the default geometry selection with two-head checkpoints.
--prefer_geometry_component Keep every whole segmentation blob with at least 20% of its area inside the predicted circle. May retain multiple blobs or return an empty mask. Requires a two-head checkpoint; enabled by default. Mutually exclusive with --prefer_central_component. Also accepts --prefer-geometry-component.
--raw-segmentation Disable geometry component selection to inspect the thresholded segmentation head directly. Python API: prefer_geometry_component=False. Also accepts --raw_segmentation.
--show-all-heads Show all segmentation blobs in their usual confidence colors and the yellow geometry circle/center. A subtle white dashed contour marks the retained mask. Requires --output_mask_dir; changes overlays only. Also accepts --show_all_heads.
--geometry-head-only Draw only the yellow geometry circle and center in overlays. Requires --output_mask_dir and a two-head checkpoint; mutually exclusive with --show-all-heads. Changes overlays only. Also accepts --geometry_head_only; Python API: geometry_head_only=True.
--mask_transparency Blend weight of the heatmap color over the source image in overlays (default 0.05). Higher values are more saturated.
--extraction_fps Frames per second to extract from the video (default 5). If extracting at this rate would exceed --max_frames, the rate is automatically reduced so that --max_frames frames are extracted.
--max_frames Cap on frames extracted from a video (default 10000). Useful for long recordings.
--calculate_velocity Analyze every encoded source frame and append pupil-center, speed, and segmentation-quality fields and plot panels to the analysis outputs.
--acquisition_fps Actual experimental sampling rate used for timestamps and velocity. Required with --image_dir in velocity mode; defaults to the video header rate for video input.
--checkpoint Path to a custom model checkpoint. Defaults to the packaged checkpoint with the highest IoU encoded in its filename.
--batch_size Inference batch size (default 32).
--num_workers Dataloader worker processes (default: up to 4, capped by CPU count). Use 0 to load frames in the main process, which is often faster for short recordings.

To extract PNG frames from a video without analyzing them:

extract-frames --video_path data/mouse1.avi --out_dir data/frames_mouse1

Output

Results land next to the input by default, in <video_stem>_result/ for a video and <image_dir>_result/ for a frame directory. For example,

movie.avi
movie_frames/
    movie_00001.png
    movie_00002.png
    ...
movie_result/
    movie_pupil_analysis.csv
    movie_pupil_analysis.png

The result files contain:

File Contents
*_pupil_analysis.csv The per-frame table, columns below.
*_pupil_analysis.png Frame-indexed diameter plot with valid/warning/invalid points. Velocity mode adds center, speed, and a dedicated quality-control panel.
Mask images in --output_mask_dir Optional. Confidence heatmaps over threshold-passing pupil pixels: yellow near the threshold, orange intermediate, red near-certain. A thin center cross is cyan when accepted and yellow when rejected. With --show-all-heads, all blobs remain visible in the same confidence colors, with the geometry circle/center and a dashed contour of the retained mask.

Segmentation visibility and quality are written for every run. Timestamp, center, speed, and tracking_status are added in velocity mode:

Column Meaning
image_name Source image. The number in a generated name is the one-based source-frame index.
estimated_pupil_diameter Equivalent-circle diameter, sqrt(4 / pi * area), in the 148 x 148 model image.
pupil_diameter_input_pixels The same diameter at the scale of the image you supplied.
pupil_visibility visible, not_detected, uncertain, or partially_visible_or_uncertain. Shape-based uncertainty does not claim to reconstruct a pupil hidden by the eyelid.
segmentation_status Diameter-only status: valid, warning, or invalid.
quality_reason Which check flagged or rejected the segmentation.
timestamp_seconds Derived from the source-frame index and --acquisition_fps.
center_x_pixels, center_y_pixels Pupil center in input-image pixels; x increases right, y increases down.
speed_pixels_per_second Center speed, in input-image pixels per second.
tracking_status valid, warning, or invalid.

No column is calibrated; see the FAQ before comparing recordings. Segmentation-to-velocity method documents how the center and quality fields are derived.

Python API

Everything the CLI does is available from Python, which is usually more convenient inside a notebook or a larger analysis script. The returned result includes a DataFrame, so there is no need to read the CSV back in.

from mouse_pupil_analysis import analyze_video

result = analyze_video("data/mouse1.avi")
print(result.analysis_table.head())
print(result.csv_path, result.plot_path)

Velocity mode and every CLI flag are keyword arguments:

result = analyze_video(
    "data/mouse1.avi",
    calculate_velocity=True,
    acquisition_fps=33.3333333333,
    output_mask_dir="data/masks_mouse1",
)

usable = result.analysis_table.query("tracking_status != 'invalid'")
print(f"{len(usable)} of {len(result.analysis_table)} frames usable")

To start from frames you already extracted, use analyze_frames instead:

from mouse_pupil_analysis import analyze_frames

result = analyze_frames(
    "data/mouse1_frames",
    calculate_velocity=True,
    acquisition_fps=97,
)

result is an AnalysisResult with these fields:

Field Description
analysis_table The same compact table written to CSV, as a DataFrame.
csv_path, plot_path Locations of the written outputs.
prediction_threshold The explicit or checkpoint-calibrated threshold actually used.
segmentation_dataframe Detailed per-frame component and visibility evidence for every run.
tracking_dataframe Detailed per-frame quality evidence in velocity mode, otherwise None. Retains raw centers, component areas, confidence, circularity, and temporal-area calculations that the compact table omits.
image_frames Frame metadata linking each image name to its source-frame index.

For repeated runs with shared settings, build an AnalysisConfig once and pass it to run_analysis:

from pathlib import Path

from mouse_pupil_analysis import AnalysisConfig, run_analysis

for video in Path("data").glob("*.avi"):
    run_analysis(AnalysisConfig(video_path=video, pred_thresh=0.75))

Library code logs rather than prints, so it stays quiet by default. To see the same progress messages the CLI shows:

import logging
logging.basicConfig(level=logging.INFO)

Sample data

A clone of the repository carries real images and hand-labeled masks under sample_data/, so you can exercise the whole pipeline before pointing it at your own recordings:

git clone https://github.com/yzhaoinuw/mouse-pupil-analysis.git
cd mouse-pupil-analysis

run-pupil-analysis \
  --image_dir sample_data/velocity_frames \
  --result_dir results/sample_velocity \
  --output_mask_dir results/sample_velocity/overlays \
  --calculate_velocity \
  --acquisition_fps 97

Those are 31 consecutive frames acquired at 97 Hz. The fixture also holds full-size frames from two recordings and labeled image/mask pairs arranged by recording session. The sample-data guide covers the fixture-specific commands and provenance.

Installation options

Virtual environments

Recommended but not required, for example with Miniconda:

conda create -n mouse_pupil_analysis python=3.12
conda activate mouse_pupil_analysis
pip install mouse-pupil-analysis

PyTorch builds

PyTorch installation depends on your operating system and hardware. To choose a CPU-only or accelerated build, use the official PyTorch selector first, then install this package with pip install mouse-pupil-analysis. The pipeline uses CUDA when torch.cuda.is_available(); otherwise it runs on the CPU.

FAQ

The pupil mask looks wrong. What do I check first?

Start with framing. The eye should be roughly centered and fill most of the frame. Every image is resized with its aspect ratio preserved and center-padded to the model's 148 x 148 input, so crop a wide scene with a small eye before analyzing it. If the framing is right, write the confidence overlays and look at them:

run-pupil-analysis --video_path movie.avi --output_mask_dir movie_overlays

Ordinary overlays shade the retained pupil pixels, from yellow (just over the threshold) through orange to red (near-certain). Use --show-all-heads to compare the predicted circle and retained contours with discarded blobs. Inference normally uses the calibration stored with the checkpoint. If the mask spills past the pupil, override it with a higher --pred_thresh; if it catches only part of the pupil, try a lower value.

The packaged model was trained on 615 labeled pairs with auxiliary pupil center and radius supervision. It predicts the visible-pupil mask at a calibrated threshold of 0.525.

Overlay PNGs show the entire input image resized with its aspect ratio preserved and padded to 148 x 148, matching the model input. Segmentation, geometry, and the retained contour share these coordinates; no source-image crop is taken.

pupil_visibility and the status/reason columns flag empty, border-touching, or low-circularity masks. Mean segmentation confidence remains in the detailed diagnostics without a rejection or warning threshold. A narrow visible sliver may be marked partially_visible_or_uncertain; a fully hidden pupil is not reconstructed.

If a prediction still looks wrong, report a failure case with the original frame, an all-head overlay, the software version, the command and any custom checkpoint, and a short description of the expected visible pupil. Keep the recording/session identifier and frame number so related examples can be grouped when preparing new training data.

How do I improve or fine-tune the model on my data?

Follow the training guide.

What should I pass for --acquisition_fps?

The rate your camera actually acquired at. Velocity mode derives timestamps from the source-frame index and this value, not from the frame rate stored in the video container, which often is not experimental time. With --image_dir there is no container to fall back on, so the flag is required; with --video_path it defaults to the container rate.

Can I compare diameters or speeds between recordings?

Only when the optics and working distance match, or after applying your own per-recording scale factor. Nothing reported here is calibrated, and converting to millimeters needs a scale factor this package cannot infer.

Within the CSV, prefer pupil_diameter_input_pixels. It inverts the resize-and-pad geometry back to the scale of the image you supplied: the source video frame with --video_path, or whatever you prepared with --image_dir. estimated_pupil_diameter is measured in the 148 x 148 model image, so it is not comparable across recordings that differ in resolution or cropping; it is kept for continuity with earlier results. If your frames were already 148 x 148, the two columns are identical. Center and speed use the same input-image scale.

Why are center_x_pixels and speed_pixels_per_second empty for some frames?

Because the pipeline neither publishes nor interpolates values it cannot stand behind. Center and speed are empty when segmentation is rejected, and speed is additionally empty when either adjacent frame is invalid or when the two source frames are not consecutive. A warning frame remains usable, such as a fragmented mask that passes the other quality checks; quality_reason names the check that fired.

Citation

If you use this software in a paper or other scholarly work, please cite the exact version you ran, so your analysis stays reproducible against that code:

Zhao, Y. (2026). mouse-pupil-analysis: Automated mouse pupil segmentation, diameter, and pupil-center velocity analysis using UNet (v0.4.1). https://github.com/yzhaoinuw/mouse-pupil-analysis/releases/tag/v0.4.1

Every release is archived on Zenodo under its own version DOI, added here after archiving completes. The concept DOI in the badge above always resolves to the newest version, so use it only when you mean the project as a whole rather than a specific analysis.

GitHub's "Cite this repository" button generates BibTeX from CITATION.cff, and CHANGELOG.md records what changed between versions.

Development

git clone https://github.com/yzhaoinuw/mouse-pupil-analysis.git
cd mouse-pupil-analysis
pip install -e ".[dev]"

Run the same checks CI runs before submitting a change:

ruff check .
black --check .
pytest

From a source checkout, model training and fine-tuning can also be run with terminal arguments:

python training/run_train.py --help

License

MIT. See LICENSE.

Metadata

Release files for mouse-pupil-analysis 0.4.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mouse-pupil-analysis 0.4.1
File Size Uploaded Provenance Actions
mouse_pupil_analysis-0.4.1.tar.gz 4.1 MB With provenance Details for mouse_pupil_analysis-0.4.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mouse-pupil-analysis 0.4.1
File Interpreter ABI Platform Actions
mouse_pupil_analysis-0.4.1-py3-none-any.whl Python 3 none any Details for mouse_pupil_analysis-0.4.1-py3-none-any.whl

Total release size: 5.9 MB

Release files / mouse_pupil_analysis-0.4.1.tar.gz

Download URL mouse_pupil_analysis-0.4.1.tar.gz
Size 4.1 MB
Tags Source
SHA-256 checksum
How to use checksums
7cd1e37395eb195c5f3e6e726f62de055f29ad93c900454cffe5be4afcd98b49
BLAKE2b-256 checksum
How to use checksums
0f88a1dce95c36660d26464da9766576397838cf8243b0430a03af83615fc4e6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Release files / mouse_pupil_analysis-0.4.1-py3-none-any.whl

Download URL mouse_pupil_analysis-0.4.1-py3-none-any.whl
Size 1.8 MB
Tags Python 3
SHA-256 checksum
How to use checksums
f6029d2f5c28d4c69a23358d1420c57b8ade0f3433e5608c6fc98e230a9f144c
BLAKE2b-256 checksum
How to use checksums
b41c3fa3a3e7bedf90a16efd605d90421a2a818311954e2221504f73f1190314
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Security for mouse-pupil-analysis 0.4.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for mouse_pupil_analysis-0.4.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page