mouse-pupil-analysis
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_fpsis 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_fpsand 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.