sleap-io
A standalone Python library and CLI for working with animal pose tracking data. Read, write, convert, and manipulate pose data across formats with minimal dependencies.
Complements the core SLEAP package but does not include labeling, training, or inference.
Documentation | Examples | CLI Reference
Features
- Multi-format I/O -- Read and write SLEAP, NWB, COCO, DeepLabCut, Ultralytics YOLO, JABS, Label Studio, CSV, Analysis HDF5, AlphaTracker, and LEAP formats
- CLI tools -- Inspect, convert, render, and transform data from the command line (
sio show,sio convert,sio render,sio transform) - Rendering -- Produce publication-quality videos and images with pose overlays, customizable colors, markers, and presets
- Transforms -- Crop, scale, rotate, pad, and flip videos with automatic coordinate adjustment
- Merging -- Combine annotations from multiple sources with flexible matching strategies
- Codecs -- Convert to/from NumPy arrays, DataFrames (pandas/polars), and dictionaries
- Video I/O -- Read any video format via pluggable backends (FFMPEG, OpenCV, PyAV) with a NumPy-like interface
- Lazy loading -- Load large SLP files up to 90x faster by deferring object creation
- Remote URLs -- Load
.slpfiles directly fromhttps://,s3://,gs://, andaz://URLs with lazy range-based reads and optional persistent caching - Dataset splits -- Create train/val/test splits and export to formats like Ultralytics YOLO
Installation
Quick start (no install needed)
Run CLI commands instantly with uvx:
uvx sleap-io show labels.slp
uvx sleap-io convert -i labels.slp -o labels.nwb
Install as CLI tool
uv tool install "sleap-io[all]"
sio show labels.slp
Install as Python library
pip install "sleap-io[all]"
# or: uv add "sleap-io[all]"
# or: conda install -c conda-forge sleap-io
From source
pip install "sleap-io[all] @ git+https://github.com/talmolab/sleap-io.git@main"
Optional extras
Video support works out of the box via imageio-ffmpeg. Optional extras provide faster backends and additional format support:
| Extra | Purpose |
|---|---|
opencv |
Faster video backend |
pyav |
Alternative video backend |
mat |
LEAP .mat file support |
polars |
Fast DataFrame operations |
all |
All of the above |
Development
git clone https://github.com/talmolab/sleap-io.git && cd sleap-io
uv sync --all-extras
See CONTRIBUTING.md for more details.
Usage
CLI
# Inspect a labels file
sio show labels.slp
# Convert between formats
sio convert -i labels.slp -o labels.nwb
# Render video with pose overlays
sio render -i predictions.slp -o output.mp4
# Transform (scale, crop, rotate) with coordinate adjustment
sio transform labels.slp --scale 0.5 -o scaled.slp
Python
Load and convert between formats
import sleap_io as sio
labels = sio.load_file("predictions.slp")
labels.save("predictions.nwb")
Format is auto-detected from the extension. See supported formats.
Convert to NumPy arrays
labels = sio.load_file("predictions.slp")
trx = labels.numpy() # (n_frames, n_tracks, n_nodes, 2)
trx_with_scores = labels.numpy(return_confidence=True) # (n_frames, n_tracks, n_nodes, 3)
Create labels from scratch
import sleap_io as sio
import numpy as np
skeleton = sio.Skeleton(
nodes=["head", "thorax", "abdomen"],
edges=[("head", "thorax"), ("thorax", "abdomen")]
)
instance = sio.Instance.from_numpy(
points=np.array([[10.2, 20.4], [5.8, 15.1], [0.3, 10.6]]),
skeleton=skeleton
)
video = sio.load_video("test.mp4")
lf = sio.LabeledFrame(video=video, frame_idx=0, instances=[instance])
labels = sio.Labels(videos=[video], skeletons=[skeleton], labeled_frames=[lf])
labels.save("labels.slp")
Render poses
labels = sio.load_file("predictions.slp")
labels.render("output.mp4") # Full video
labels.render("preview.mp4", preset="preview") # Fast 0.25x preview
sio.render_image(labels[0], "frame.png") # Single frame
Merge annotations
base = sio.load_file("manual_annotations.slp")
predictions = sio.load_file("predictions.slp")
base.merge(predictions)
base.save("merged.slp")
Create training splits
labels = sio.load_file("labels.slp")
labels.make_training_splits(n_train=0.8, n_val=0.1, n_test=0.1, save_dir="splits/", seed=42)
See the Examples page for more recipes including NWB export, video re-encoding, skeleton replacement, path fixing, and YOLO/COCO export.
Support
For technical inquiries, please open an Issue.
For general SLEAP usage, see sleap.ai.
License
BSD 3-Clause License. See LICENSE for details.
Release files for sleap-io 0.9.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| sleap_io-0.9.2.tar.gz | 1.1 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| sleap_io-0.9.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 2.3 MB
Release files / sleap_io-0.9.2.tar.gz
| Download URL | sleap_io-0.9.2.tar.gz |
|---|---|
| Size | 1.1 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ac44fed48ac7c1ae2d7e86067ae8685ec66c9798ecdfe20534144e741793ae7e
|
|
BLAKE2b-256 checksum How to use checksums |
277c860c645a412ee242e44477d513d424bc7fc32427688d041cc57637921675
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.32 {"installer":{"name":"uv","version":"0.11.32","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"22.04","id":"jammy","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / sleap_io-0.9.2-py3-none-any.whl
| Download URL | sleap_io-0.9.2-py3-none-any.whl |
|---|---|
| Size | 1.2 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5428958b3405da4d352e48a7e20ad8c6b6e7897d70c1a609be5ae515c094bcd6
|
|
BLAKE2b-256 checksum How to use checksums |
5c21149175c76be19bfadeb90c4bba3e275539d9c17251f7a0f5f874797afe00
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.32 {"installer":{"name":"uv","version":"0.11.32","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"22.04","id":"jammy","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
