Mosaic panorama

Reels recorded by a Mosaic six-camera head, uploaded as the camera wrote them: one folder per reel at the bucket root, holding the six camera videos, camera_info.json, the unit's calibration file named after its serial number, frame_times.csv and route_frame_synced.gpx. We stitch the panoramas; deliver nothing stitched.

Each reel folder becomes one set, named after the folder.

Folder layout#

<dataset bucket>/
├── reel_0003_20230621-092716/
│   ├── segment0000_cam0.mp4      one video per camera, cam0 to cam5
│   ├── segment0000_cam1.mp4
│   ├── …
│   ├── segment0000_cam5.mp4
│   ├── camera_info.json
│   ├── SN-0223-2-0148.json       the calibration of the unit that shot the reel
│   ├── frame_times.csv
│   ├── route_frame_synced.gpx
│   └── route.gpx                 optional, not read
└── reel_0004_20230621-103012/
    └── …

Upload each reel folder as the camera wrote it, directly at the root of the bucket. A reel folder's name starts with reel_; keep the camera's name. Folders with other names are not read.

A long reel split into segments (segment0000_…, segment0001_…) needs all six videos of every segment. A numbered suffix that a download added to a video's name (segment0000_cam3-002.mp4) is fine; two files for one camera are not.

Encrypted reels cannot be processed: record with encryption off.

Calibration#

Every reel carries the calibration of the unit that shot it, named after that unit's serial number: SN-0223-2-0148.json for the camera whose camera_info.json says "serial_number": "0223-2-0148". Export it from the unit; one from another unit is refused, even of the same model, because each head's lenses sit a little differently.

Video#

The six videos as the camera recorded them: H.264, 8-bit, one track each. Do not re-encode or trim them; every camera's video must hold the same frames.

Positions and times#

The reel's position comes from the camera's own GPS receiver (gps_info.mode INTERNAL in camera_info.json). Reels positioned by an INS (a Meridian 2 trajectory) are not processed yet.

The videos, frame_times.csv and route_frame_synced.gpx must count the same frames. Heights are the GPX ele, height above mean sea level, as the receiver gives it.

The camera receiver's position is good to a metre or two, and it does not measure the head's attitude: the panoramas are level and face the way the car drove.

Heading#

How the head is turned on the roof is measured from the reel itself, on straight stretches driven at 3 m/s or more. A reel with almost no straight driving (a car park, a single tight loop) takes the direction measured on the delivery's other reels from the same camera. Do not turn the head on the roof between reels you deliver together without recording a straight stretch in each.

Every reel is checked before anything is processed — its small files and each video's index, not its frames:

• The delivery holds at least one reel folder (reel_…) at the root, and each holds camera_info.json, frame_times.csv, route_frame_synced.gpx and one video per camera, segmentNNNN_cam0.mp4 to segmentNNNN_cam5.mp4, for every segment.
• camera_info.json reads, names the camera's serial number, and says the reel was positioned by the camera's own receiver (gps_info.mode INTERNAL). Reels with an INS trajectory are not processed yet.
• The reel is not encrypted (settings.encrypted in camera_info.json): an encrypted reel cannot be decoded.
• The reel holds SN-<serial>.json for the serial in camera_info.json, and it is that unit's: six cameras cam0 to cam5, each an equidistant fisheye with finite values and a rotation for R, calibrated on frames the size of its video. A camera_calibration.json from another unit beside it is ignored.
• Each video is a whole MP4 file with one H.264 track, 8-bit, its frames stored in the order they are shown, and the six videos of a segment hold the same number of frames of one size. Only each file's index is read, not its frames.
• The videos' frames, the rows of frame_times.csv and the points of route_frame_synced.gpx are the same number, and the route's points are frames 0, 1, 2, … in order, each with a position and a height.
• Every frame is later than the one before it, and was taken after 2015 and not in the future. The first and last frame's days are the dataset's acquisition dates.
• The route lies where the dataset's coordinate reference system is used (its area of use, with 5% to spare). A reel driven in London does not fit a dataset in a Florida CRS.
• More than 1% of the frames have no 3D fix, or an hdop above 5: those panoramas may be placed metres off. (a warning, not an error)
• A frame lies more than 40 m from the frame before it, further than the car can have driven. (a warning, not an error)
• The reel has fewer than 10 frame pairs on a straight at 3 m/s or more, so how the head was turned on the roof cannot be measured from it. The reel then takes the direction measured on the delivery's other reels from the same camera, and without one it is not processed. (a warning, not an error)

Coordinate reference system#

The route is GPS latitude and longitude. Create the dataset in a coordinate reference system used where the reels were driven: British National Grid in Great Britain, a state plane or UTM zone in the United States. A reel driven outside it is refused.

Ingest parameters#

What you get back#

• One 13504 × 6752 equirectangular panorama per frame, under panorama/jpg/<reel>/, placed where the frame was taken.
• The panoramas blurred, when anonymisation is auto_anonymise.

The reel's first frame, taken as recording starts, is usually all white; it gets no panorama.

Common failures#