main
sleap_io.io.main
¶
This module contains high-level wrappers for utilizing different I/O backends.
Functions:
Name | Description |
---|---|
load_file |
Load a file and return the appropriate object. |
load_jabs |
Read JABS-style predictions from a file and return a |
load_labelstudio |
Read Label Studio-style annotations from a file and return a |
load_nwb |
Load an NWB dataset as a SLEAP |
load_skeleton |
Load skeleton(s) from a JSON or YAML file. |
load_slp |
Load a SLEAP dataset. |
load_video |
Load a video file. |
save_file |
Save a file based on the extension. |
save_jabs |
Save a SLEAP dataset to JABS pose file format. |
save_labelstudio |
Save a SLEAP dataset to Label Studio format. |
save_nwb |
Save a SLEAP dataset to NWB format. |
save_skeleton |
Save skeleton(s) to a JSON or YAML file. |
save_slp |
Save a SLEAP dataset to a |
save_video |
Write a list of frames to a video file. |
load_file(filename, format=None, **kwargs)
¶
Load a file and return the appropriate object.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
filename
|
str | Path
|
Path to a file. |
required |
format
|
Optional[str]
|
Optional format to load as. If not provided, will be inferred from the file extension. Available formats are: "slp", "nwb", "labelstudio", "jabs" and "video". |
None
|
Returns:
Type | Description |
---|---|
Union[Labels, Video]
|
A |
Source code in sleap_io/io/main.py
def load_file(
filename: str | Path, format: Optional[str] = None, **kwargs
) -> Union[Labels, Video]:
"""Load a file and return the appropriate object.
Args:
filename: Path to a file.
format: Optional format to load as. If not provided, will be inferred from the
file extension. Available formats are: "slp", "nwb", "labelstudio", "jabs"
and "video".
Returns:
A `Labels` or `Video` object.
"""
if isinstance(filename, Path):
filename = filename.as_posix()
if format is None:
if filename.endswith(".slp"):
format = "slp"
elif filename.endswith(".nwb"):
format = "nwb"
elif filename.endswith(".json"):
format = "json"
elif filename.endswith(".h5"):
format = "jabs"
else:
for vid_ext in Video.EXTS:
if filename.endswith(vid_ext):
format = "video"
break
if format is None:
raise ValueError(f"Could not infer format from filename: '{filename}'.")
if filename.endswith(".slp"):
return load_slp(filename, **kwargs)
elif filename.endswith(".nwb"):
return load_nwb(filename, **kwargs)
elif filename.endswith(".json"):
return load_labelstudio(filename, **kwargs)
elif filename.endswith(".h5"):
return load_jabs(filename, **kwargs)
elif format == "video":
return load_video(filename, **kwargs)
load_jabs(filename, skeleton=None)
¶
Read JABS-style predictions from a file and return a Labels
object.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
filename
|
str
|
Path to the jabs h5 pose file. |
required |
skeleton
|
Optional[Skeleton]
|
An optional |
None
|
Returns:
Type | Description |
---|---|
Labels
|
Parsed labels as a |
Source code in sleap_io/io/main.py
def load_jabs(filename: str, skeleton: Optional[Skeleton] = None) -> Labels:
"""Read JABS-style predictions from a file and return a `Labels` object.
Args:
filename: Path to the jabs h5 pose file.
skeleton: An optional `Skeleton` object.
Returns:
Parsed labels as a `Labels` instance.
"""
return jabs.read_labels(filename, skeleton=skeleton)
load_labelstudio(filename, skeleton=None)
¶
Read Label Studio-style annotations from a file and return a Labels
object.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
filename
|
str
|
Path to the label-studio annotation file in JSON format. |
required |
skeleton
|
Optional[Union[Skeleton, list[str]]]
|
An optional |
None
|
Returns:
Type | Description |
---|---|
Labels
|
Parsed labels as a |
Source code in sleap_io/io/main.py
def load_labelstudio(
filename: str, skeleton: Optional[Union[Skeleton, list[str]]] = None
) -> Labels:
"""Read Label Studio-style annotations from a file and return a `Labels` object.
Args:
filename: Path to the label-studio annotation file in JSON format.
skeleton: An optional `Skeleton` object or list of node names. If not provided
(the default), skeleton will be inferred from the data. It may be useful to
provide this so the keypoint label types can be filtered to just the ones in
the skeleton.
Returns:
Parsed labels as a `Labels` instance.
"""
return labelstudio.read_labels(filename, skeleton=skeleton)
load_nwb(filename)
¶
Load an NWB dataset as a SLEAP Labels
object.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
filename
|
str
|
Path to a NWB file ( |
required |
Returns:
Type | Description |
---|---|
Labels
|
The dataset as a |
load_skeleton(filename)
¶
Load skeleton(s) from a JSON or YAML file.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
filename
|
str | Path
|
Path to a skeleton JSON or YAML file. |
required |
Returns:
Type | Description |
---|---|
Union[Skeleton, List[Skeleton]]
|
A single |
Notes
This function loads skeletons from standalone files. JSON files use the jsonpickle format, while YAML files use a simplified human-readable format. The format is detected based on the file extension.
Source code in sleap_io/io/main.py
def load_skeleton(filename: str | Path) -> Union[Skeleton, List[Skeleton]]:
"""Load skeleton(s) from a JSON or YAML file.
Args:
filename: Path to a skeleton JSON or YAML file.
Returns:
A single `Skeleton` or list of `Skeleton` objects.
Notes:
This function loads skeletons from standalone files. JSON files use the
jsonpickle format, while YAML files use a simplified human-readable format.
The format is detected based on the file extension.
"""
if isinstance(filename, Path):
filename = str(filename)
# Detect format based on extension
if filename.lower().endswith((".yaml", ".yml")):
# YAML format
with open(filename, "r") as f:
yaml_data = f.read()
decoder = SkeletonYAMLDecoder()
return decoder.decode(yaml_data)
else:
# JSON format (default)
with open(filename, "r") as f:
json_data = f.read()
decoder = SkeletonDecoder()
return decoder.decode(json_data)
load_slp(filename, open_videos=True)
¶
Load a SLEAP dataset.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
filename
|
str
|
Path to a SLEAP labels file ( |
required |
open_videos
|
bool
|
If |
True
|
Returns:
Type | Description |
---|---|
Labels
|
The dataset as a |
Source code in sleap_io/io/main.py
def load_slp(filename: str, open_videos: bool = True) -> Labels:
"""Load a SLEAP dataset.
Args:
filename: Path to a SLEAP labels file (`.slp`).
open_videos: If `True` (the default), attempt to open the video backend for
I/O. If `False`, the backend will not be opened (useful for reading metadata
when the video files are not available).
Returns:
The dataset as a `Labels` object.
"""
return slp.read_labels(filename, open_videos=open_videos)
load_video(filename, **kwargs)
¶
Load a video file.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
filename
|
str
|
The filename(s) of the video. Supported extensions: "mp4", "avi", "mov", "mj2", "mkv", "h5", "hdf5", "slp", "png", "jpg", "jpeg", "tif", "tiff", "bmp". If the filename is a list, a list of image filenames are expected. If filename is a folder, it will be searched for images. |
required |
Returns:
Type | Description |
---|---|
Video
|
A |
Source code in sleap_io/io/main.py
def load_video(filename: str, **kwargs) -> Video:
"""Load a video file.
Args:
filename: The filename(s) of the video. Supported extensions: "mp4", "avi",
"mov", "mj2", "mkv", "h5", "hdf5", "slp", "png", "jpg", "jpeg", "tif",
"tiff", "bmp". If the filename is a list, a list of image filenames are
expected. If filename is a folder, it will be searched for images.
Returns:
A `Video` object.
"""
return Video.from_filename(filename, **kwargs)
save_file(labels, filename, format=None, verbose=True, **kwargs)
¶
Save a file based on the extension.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
labels
|
Labels
|
A SLEAP |
required |
filename
|
str | Path
|
Path to save labels to. |
required |
format
|
Optional[str]
|
Optional format to save as. If not provided, will be inferred from the file extension. Available formats are: "slp", "nwb", "labelstudio" and "jabs". |
None
|
verbose
|
bool
|
If |
True
|
Source code in sleap_io/io/main.py
def save_file(
labels: Labels,
filename: str | Path,
format: Optional[str] = None,
verbose: bool = True,
**kwargs,
):
"""Save a file based on the extension.
Args:
labels: A SLEAP `Labels` object (see `load_slp`).
filename: Path to save labels to.
format: Optional format to save as. If not provided, will be inferred from the
file extension. Available formats are: "slp", "nwb", "labelstudio" and
"jabs".
verbose: If `True` (the default), display a progress bar when embedding frames
(only applies to the SLP format).
"""
if isinstance(filename, Path):
filename = str(filename)
if format is None:
if filename.endswith(".slp"):
format = "slp"
elif filename.endswith(".nwb"):
format = "nwb"
elif filename.endswith(".json"):
format = "labelstudio"
elif "pose_version" in kwargs:
format = "jabs"
if format == "slp":
save_slp(labels, filename, verbose=verbose, **kwargs)
elif format == "nwb":
save_nwb(labels, filename, **kwargs)
elif format == "labelstudio":
save_labelstudio(labels, filename, **kwargs)
elif format == "jabs":
pose_version = kwargs.pop("pose_version", 5)
root_folder = kwargs.pop("root_folder", filename)
save_jabs(labels, pose_version=pose_version, root_folder=root_folder)
else:
raise ValueError(f"Unknown format '{format}' for filename: '{filename}'.")
save_jabs(labels, pose_version, root_folder=None)
¶
Save a SLEAP dataset to JABS pose file format.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
labels
|
Labels
|
SLEAP |
required |
pose_version
|
int
|
The JABS pose version to write data out. |
required |
root_folder
|
Optional[str]
|
Optional root folder where the files should be saved. |
None
|
Note
Filenames for JABS poses are based on video filenames.
Source code in sleap_io/io/main.py
def save_jabs(labels: Labels, pose_version: int, root_folder: Optional[str] = None):
"""Save a SLEAP dataset to JABS pose file format.
Args:
labels: SLEAP `Labels` object.
pose_version: The JABS pose version to write data out.
root_folder: Optional root folder where the files should be saved.
Note:
Filenames for JABS poses are based on video filenames.
"""
jabs.write_labels(labels, pose_version, root_folder)
save_labelstudio(labels, filename)
¶
Save a SLEAP dataset to Label Studio format.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
labels
|
Labels
|
A SLEAP |
required |
filename
|
str
|
Path to save labels to ending with |
required |
save_nwb(labels, filename, append=True)
¶
Save a SLEAP dataset to NWB format.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
labels
|
Labels
|
A SLEAP |
required |
filename
|
str
|
Path to NWB file to save to. Must end in |
required |
append
|
bool
|
If |
True
|
See also: nwb.write_nwb, nwb.append_nwb
Source code in sleap_io/io/main.py
def save_nwb(labels: Labels, filename: str, append: bool = True):
"""Save a SLEAP dataset to NWB format.
Args:
labels: A SLEAP `Labels` object (see `load_slp`).
filename: Path to NWB file to save to. Must end in `.nwb`.
append: If `True` (the default), append to existing NWB file. File will be
created if it does not exist.
See also: nwb.write_nwb, nwb.append_nwb
"""
if append and Path(filename).exists():
nwb.append_nwb(labels, filename)
else:
nwb.write_nwb(labels, filename)
save_skeleton(skeleton, filename)
¶
Save skeleton(s) to a JSON or YAML file.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
skeleton
|
Union[Skeleton, List[Skeleton]]
|
A single |
required |
filename
|
str | Path
|
Path to save the skeleton file. |
required |
Notes
This function saves skeletons in either JSON or YAML format based on the file extension. JSON files use the jsonpickle format compatible with SLEAP, while YAML files use a simplified human-readable format.
Source code in sleap_io/io/main.py
def save_skeleton(skeleton: Union[Skeleton, List[Skeleton]], filename: str | Path):
"""Save skeleton(s) to a JSON or YAML file.
Args:
skeleton: A single `Skeleton` or list of `Skeleton` objects to save.
filename: Path to save the skeleton file.
Notes:
This function saves skeletons in either JSON or YAML format based on the
file extension. JSON files use the jsonpickle format compatible with SLEAP,
while YAML files use a simplified human-readable format.
"""
if isinstance(filename, Path):
filename = str(filename)
# Detect format based on extension
if filename.lower().endswith((".yaml", ".yml")):
# YAML format
encoder = SkeletonYAMLEncoder()
yaml_data = encoder.encode(skeleton)
with open(filename, "w") as f:
f.write(yaml_data)
else:
# JSON format (default)
encoder = SkeletonEncoder()
json_data = encoder.encode(skeleton)
with open(filename, "w") as f:
f.write(json_data)
save_slp(labels, filename, embed=False, verbose=True)
¶
Save a SLEAP dataset to a .slp
file.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
labels
|
Labels
|
A SLEAP |
required |
filename
|
str
|
Path to save labels to ending with |
required |
embed
|
bool | str | list[tuple[Video, int]] | None
|
Frames to embed in the saved labels file. One of If If If This argument is only valid for the SLP backend. |
False
|
verbose
|
bool
|
If |
True
|
Source code in sleap_io/io/main.py
def save_slp(
labels: Labels,
filename: str,
embed: bool | str | list[tuple[Video, int]] | None = False,
verbose: bool = True,
):
"""Save a SLEAP dataset to a `.slp` file.
Args:
labels: A SLEAP `Labels` object (see `load_slp`).
filename: Path to save labels to ending with `.slp`.
embed: Frames to embed in the saved labels file. One of `None`, `True`,
`"all"`, `"user"`, `"suggestions"`, `"user+suggestions"`, `"source"` or list
of tuples of `(video, frame_idx)`.
If `False` is specified (the default), the source video will be restored
if available, otherwise the embedded frames will be re-saved.
If `True` or `"all"`, all labeled frames and suggested frames will be
embedded.
If `"source"` is specified, no images will be embedded and the source video
will be restored if available.
This argument is only valid for the SLP backend.
verbose: If `True` (the default), display a progress bar when embedding frames.
"""
return slp.write_labels(filename, labels, embed=embed, verbose=verbose)
save_video(frames, filename, fps=30, pixelformat='yuv420p', codec='libx264', crf=25, preset='superfast', output_params=None)
¶
Write a list of frames to a video file.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
frames
|
ndarray | Video
|
Sequence of frames to write to video. Each frame should be a 2D or 3D numpy array with dimensions (height, width) or (height, width, channels). |
required |
filename
|
str | Path
|
Path to output video file. |
required |
fps
|
float
|
Frames per second. Defaults to 30. |
30
|
pixelformat
|
str
|
Pixel format for video. Defaults to "yuv420p". |
'yuv420p'
|
codec
|
str
|
Codec to use for encoding. Defaults to "libx264". |
'libx264'
|
crf
|
int
|
Constant rate factor to control lossiness of video. Values go from 2 to 32, with numbers in the 18 to 30 range being most common. Lower values mean less compressed/higher quality. Defaults to 25. No effect if codec is not "libx264". |
25
|
preset
|
str
|
H264 encoding preset. Defaults to "superfast". No effect if codec is not "libx264". |
'superfast'
|
output_params
|
list | None
|
Additional output parameters for FFMPEG. This should be a list of
strings corresponding to command line arguments for FFMPEG and libx264. Use
|
None
|
See also: sio.VideoWriter
Source code in sleap_io/io/main.py
def save_video(
frames: np.ndarray | Video,
filename: str | Path,
fps: float = 30,
pixelformat: str = "yuv420p",
codec: str = "libx264",
crf: int = 25,
preset: str = "superfast",
output_params: list | None = None,
):
"""Write a list of frames to a video file.
Args:
frames: Sequence of frames to write to video. Each frame should be a 2D or 3D
numpy array with dimensions (height, width) or (height, width, channels).
filename: Path to output video file.
fps: Frames per second. Defaults to 30.
pixelformat: Pixel format for video. Defaults to "yuv420p".
codec: Codec to use for encoding. Defaults to "libx264".
crf: Constant rate factor to control lossiness of video. Values go from 2 to 32,
with numbers in the 18 to 30 range being most common. Lower values mean less
compressed/higher quality. Defaults to 25. No effect if codec is not
"libx264".
preset: H264 encoding preset. Defaults to "superfast". No effect if codec is not
"libx264".
output_params: Additional output parameters for FFMPEG. This should be a list of
strings corresponding to command line arguments for FFMPEG and libx264. Use
`ffmpeg -h encoder=libx264` to see all options for libx264 output_params.
See also: `sio.VideoWriter`
"""
if output_params is None:
output_params = []
with video_writing.VideoWriter(
filename,
fps=fps,
pixelformat=pixelformat,
codec=codec,
crf=crf,
preset=preset,
output_params=output_params,
) as writer:
for frame in frames:
writer(frame)