Reading DWVO Recordings

.dwvo is DWE’s multi-camera recording container, produced when you record in Discovery. The payload is MJPEG, so every frame in the file is already a complete JPEG — playback is a single cv2.imdecode, and export is a byte copy with no re-encoding or quality loss.

Recording DWVO in Discovery

New to DWVO? Start here to stream and record .dwvo files.

DWE.ai | header: nCameras, width, height, pixelFormat, fps | ext data
block:   uint32 timestamp | per camera: busID\0, uint32 length, JPEG bytes
block:   ...

Prerequisites

Python (version 3.x)
opencv-python, numpy, and pillow
A .dwvo recording — the examples below use test.dwvo

Setup

Clone the OpenCV Guides repository and open the folder for this guide, then create a virtual environment and install the dependencies:

git clone https://github.com/DeepWaterExploration/opencv-guides.git
cd opencv-guides/4-dwvo-read/python

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

git clone https://github.com/DeepWaterExploration/opencv-guides.git
cd opencv-guides\4-dwvo-read\python

python3 -m venv venv
venv\Scripts\activate
pip install -r requirements.txt

Playback

main.py decodes every camera and shows them side by side in one OpenCV window.

python main.py test.dwvo
python main.py test.dwvo --fps 60 --loop

Argument / key
`--fps N`	Playback rate. Defaults to the header’s fps.
`--loop`	Restart at the end of the file.
`space`	Pause / resume.
`q` / `esc`	Quit.

Playback is anchored to a fixed schedule: if decoding falls a full frame behind, that frame is dropped rather than shown late, so the video stays at wall-clock speed.

Export to JPEGs

Because DWVO already stores MJPEG, export.py copies each frame straight to disk — no decode, no quality loss.

python export.py file.dwvo output-folder

# keep every fifth frame
python export.py file.dwvo output-folder --step 5

Argument
`--step N`	Keep every Nth frame.
`--start-frame N`	First output index, to continue numbering from an earlier sequence.

Output is one directory per camera, numbered KITTI-style:

out/
  image_0/000000.jpg, 000001.jpg, ...
  image_1/000000.jpg, 000001.jpg, ...
  times.txt

Lossless PNG (KITTI dataset)

dwvo_to_kitti.py produces the same layout but decodes through Pillow so it can emit lossless PNG. Use it when a downstream tool won’t accept JPEG; otherwise export.py is faster.

python dwvo_to_kitti.py test.dwvo out          # PNG
python dwvo_to_kitti.py test.dwvo out --jpeg   # same zero-copy JPEG as export.py

Reading DWVO programmatically

In dwvo.py, DWVOReader iterates timestamp blocks, DWVOWriter writes them, and combine_dwvos() concatenates recordings that share a header.

from pathlib import Path
from dwvo import DWVOReader

with DWVOReader(Path("test.dwvo")) as reader:
    print(reader.header.n_cameras, reader.header.width, reader.header.height)
    for block in reader.iter_blocks():
        for frame in block.video_frames:   # one per camera
            frame.bus_id, frame.data       # "0" / "1", raw JPEG bytes

FAQ

Why is the video slower than what I recorded?

In Discovery, some cameras require setting the FPS manually. If it was set to 30 FPS while the video was streamed at 60 FPS, the .dwvo file records 30 FPS in its metadata and tells applications to read at 30 FPS. Override it at playback with --fps.

Further information

For additional details, examples in other languages, and the full source of the scripts above, see the OpenCV Guides repository.

OpenCV Guides Repository

DWVO reader, playback, export, and KITTI conversion source.

Recording DWVO in Discovery

​Prerequisites

​Setup

​Playback

​Export to JPEGs

​Lossless PNG (KITTI dataset)

​Reading DWVO programmatically

​FAQ

​Further information

OpenCV Guides Repository

Prerequisites

Setup

Playback

Export to JPEGs

Lossless PNG (KITTI dataset)

Reading DWVO programmatically

FAQ

Further information