Toolkit for SeaClips 🚢⛵🌊🎬

SeaClips is a video-based maritime obstacle detection dataset. The dataset and its documentation can be found here 🤗. This repository provides a toolkit to demonstrate how the dataset can be used and to provide a light-weight package for easy integration into other projects.

Updates ⭐

• [11/27/2025] Release of toolkit for SeaClips.

Installation 🔌

You can install the toolkit as a package, which allows an easy integration of the dataset into your projects.

Using pip

Install directly from GitHub:

pip install git+https://github.com/SEA-AI/SeaClips

To install a specific branch or tag:

pip install git+https://github.com/SEA-AI/SeaClips@v1.0.0

Using uv

If you're using uv, you can install with:

uv pip install git+https://github.com/SEA-AI/SeaClips

Or add it to your project:

uv add git+https://github.com/SEA-AI/SeaClips

Usage 🧰

The following examples demonstrate how to load the dataset, filter samples, visualize frames, and integrate SeaClips with PyTorch.

Preliminary: Downloading the dataset

The dataset can be found here 🤗. Download the folder SeaClips.zip and extract it to your desired filepath. The variable seaclips_path in the following examples should point towards this extracted folder, e.g., seaclips_path="/path/to/SeaClips".

The toolkit package consists of three main components:

• SeaClipsDataset
• SeaClipsVisualizer
• seaclips_collate_fn

from seaclips import SeaClipsConfig, SeaClipsDataset, seaclips_collate_fn

SeaClipsDataset

The class SeaClipsDataset loads the dataset and allows for basic usage and more advanced filtering.

See examples

Basic

Load a dataset split and retrieve a single sample.

seaclips_path = "..."
split = "..." # "train", "val", or "test"

config = SeaClipsConfig(
  root_dir=seaclips_path,
  split=split,
  load_annotations=True,
  load_reference_frames=True, # set to False to load no reference frames
  ref_frame_range=[-10, 10] # reference frames' offset (in number of frames)
)
dataset = SeaClipsDataset(config)
sample = dataset[0]
print(sample)

SeaClipsSample(
  image=<PIL.Image.Image image mode=RGB size=1200x960 at 0x74AE7244B2F0>,
  image_info={...},
  annotations=[...],
  video_info={...},
  reference_frames=[...]
)

Filtering by category

Select frames containing objects from specific categories.

selected_frames = dataset.filter_by_category(category_ids=[1, 2])
sample = dataset[selected_frames[0]] # get the first sample that has annotations with either category with index 1 or 2

Filtering by metadata

Filter frames according to video-level properties (e.g., weather, sea state).

selected_frames = dataset.filter_by_metadata(weather="rainy", sea_state="smooth")
sample = dataset[selected_frames[0]] # get the first sample with rainy weather and a smooth sea state

Getting first-k frames of a video

Retrieve a fixed number of consecutive frames from a given video.

selected_frames = dataset.get_video_frames(video_id=3, first_k_frames=5) # len(selected_frames) = 5
sample = selected_frames[0] # first frame of video with index 3

SeaClipsVisualizer

The class SeaClipsVisualizer provides convenience methods for inspecting the dataset.

See examples

Basic

Show single sample with annotations and metadata.

import matplotlib.pyplot as plt

visualizer = SeaClipsVisualizer(dataset)

visualizer.show_sample(idx=0, show_labels=True, show_metadata=True)
plt.show()

Video

Show frames of a specific video.

visualizer.show_video_sequence(video_id=1, num_frames=5, start_frame=0, show_labels=True)
plt.show()

Dataset exploration

Show grid of random samples.

visualizer.show_grid(num_samples=9, show_labels=True)
plt.show()

Temporal context

Show sample with its reference frames.

visualizer.show_sample_with_references(idx=50, show_labels=True, highlight_current=True)
plt.show()

seaclips_collate_fn

The function seaclips_collate_fn allows to easily load an SeaClipsDataset instance with a torch.utils.data.DataLoader.

See examples

from torch.utils.data import DataLoader

loader = DataLoader(
    dataset,
    batch_size=4,
    shuffle=False,
    num_workers=2,
    collate_fn=seaclips_collate_fn,
)

for batch_idx, batch in enumerate(loader):
    images = batch.images  # (B, C, H, W), normalized pixels to range [0, 1]
    annotations = batch.annotations  # List of B annotation lists
    ref_frames = batch.reference_frames
    ref_images = ref_frames.images  # (B, N_ref, C, H, W)

License

The code is licensed under the Apache License 2.0. Please note that the dataset itself has a separate license, as can be seen here 🤗.

Citation 📖

If you use the dataset, please cite it as:

@InProceedings{SeaClips,
  title={SeaClips: A Video Dataset for Maritime Object Detection.},
  author={Denk, Franziska and Rankl, Christian and Almouahed, Shaban and Moser, David and Sablatnig, Robert},
  booktitle={Winter Conference on Applications of Computer Vision (WACV)},
  year=2026
}