Skip to content

The capture database

Use this page to understand the .mvisdb file behind every MVIS run: what it holds, where it lives and how to read it.

A .mvisdb file is one SQLite database per recording. It has two parts:

  • Capture core: the expensive data, board detections and the full IMU streams. It is written once and then sealed with a hash of its contents.
  • Run overlay: one per run (run_id), written by each solve. It records what the run used, why it left the rest out, and every estimate.

What this gives you:

  • Detection runs once. A second solve of the same frames with the same board reuses the sealed core, whatever its solve settings.
  • Deleting a run deletes its whole overlay and leaves the core alone.
  • Every result can say why. Each frame, board pose and corner the solve left out carries an exclude_reason and the stage that excluded it.
RunFile
mvis camdetections.mvisdb in the run folder (-o). Clearing the run folder keeps it
mvis cam-imuOne file per recording in input.cache_dir. Without cache_dir there is no cache

The cache is keyed on the recording (source, topics or folders, time window) and the board definition, including the detector settings. Two runs that read different topics or windows of one bag never share an entry.

from mvis.mvisdb.manager import DatabaseManager
db = DatabaseManager()
path = "results/run/detections.mvisdb"
print(db.capture_info(path)) # name and hashes of the recording
print(db.runs(path)) # the runs stored, oldest first
capture = db.load(path, run_id=db.latest_solved_run_id(path))
print(len(capture.streams), "cameras,", len(capture.imus), "IMUs")

load returns one MVISDatabase with that run’s overlay folded into the objects, so pipeline code never sees SQL. Any SQLite client can also open the file directly.

This is the in-memory structure. There is one MVISDatabase per recording, with one run’s overlay folded in as flags.

How to read the diagram:

  • Notes are on the right.
  • ⟨derived⟩ fields are computed, never stored.
  • PK marks the primary key, the field that identifies each entry.
  • Amber field names are the run’s flags and results, stored in the overlay.
MVISDatabase                            one capture: a live run, or one read back with DatabaseManager().load(path, run_id)
├─ streams: list[CameraStream]              PK camera_id — the number you wrote in the YAML
│   ├─ camera_id · topic · source_type · source_path
│   ├─ info: CameraInfo
│   │     name · shutter · readout_s · rolling_mode
│   │     intrinsics · distortion · camera_model · resolution · calib_provenance
│   │     ⟨derived⟩ stereo_pair · projection · distortion_kind · is_fisheye
│   └─ frames: list[FrameData]              PK frame_id · UNIQUE (camera_id, timestamp)
│       ├─ frame_id · camera_id · timestamp
│       ├─ is_motion_still · is_selected_to_use
│       ├─ ⟨derived⟩ is_valid_to_use = OR over every group below
│       └─ board_detections: list[BoardDetection]   ONE PER BOARD SEEN · PK (frame_id, board_id)
│           ├─ board_id
│           ├─ ⟨derived⟩ n_detections · n_tags · detect_status
│           ├─ pose_cam_to_board: PoseCamToBoard{T, source} · is_valid_to_use
│           ├─ ⟨derived⟩ is_selected_to_use = frame.selected AND own selection
│           └─ detections: list[TagDetection]       PK (frame_id, board_id, point_id)
│               ├─ point_id · uv · detector_emission_order
│               ├─ ⟨derived⟩ tag_id · corner_id · row = int(uv[1])
│               ├─ is_valid · is_selected · exclude_reason
│               └─ residual: Residual{residual_px, ⟨derived⟩ residual_source}
├─ boards: dict[int, Board]                 Board = {BoardInfo, [BoardPt]}
│   ├─ info: BoardInfo   board_type · rows · cols · cell_size_m · gap_m · tag_family · start_id · corners_per_tag · config_hash
│   │                     ⟨derived⟩ is_kalibr_tag · num_tags · num_points
│   └─ board_pts: list[BoardPt]   board_pt_id · board_pt_3d · info: BoardPtInfo{tag_id, corner_id}
├─ imus: list[ImuStream]                    PK imu_id — the position in imu_topics
│   ├─ info: ImuInfo     name · topic · frequency_hz · gyro_unit · accel_unit · gyro_only
│   │                     gyro_noise · gyro_bias_noise · accel_noise · accel_bias_noise
│   │                     intrinsics: ImuIntrinsics{xi24, model} · td_gyro_to_accel_s · calib_provenance   ⟨derived⟩ role
│   └─ meas: ImuMeasurements   t_gyro · gyro · t_accel · accel   ⟨derived⟩ synchronized
├─ rig: Rig   base_camera_id · base_imu_id · sync_kind · sync_tolerance_s
│                ⟨derived, per run⟩ reference_stream = (imu, base_imu_id) if cam_imu else (cam, base_camera_id)
├─ estimate_states: EstimateStates | None   this run’s estimates, read from the run overlay
│     reference_stream: (cam, base_camera_id) | (imu, base_imu_id)   the stream the states follow: camera in camera-only runs, base IMU in camera–IMU runs
│     state_hz                                     rate of the states (Hz)
│     base_state: CamOnly{t, T_cam_to_board (F,7)} | CamImu{t, T_imu_to_world (K,7), v, b_g, b_a}
│     sensor_states[]: SensorState                 one per sensor — reference included (its factor_hz, relative = None)
│        sensor · factor_hz · relative{T_x_to_ref · td_x_to_ref_s · provenance}
│        · intrinsics: Camera{fxfycxcy · dist · model · readout · provenance} | Imu{xi24 · model · provenance}
│     boards[board_id]: T_board_to_world (7,)      one per board — camera–IMU only
│     world_frame                                  the gravity-aligned world frame; none in camera-only runs, where the board is the reference
└─ run_id: int | None                        every run field above resolves against this

The same structure is stored in four groups of tables:

GroupTablesNotes
Metaschema_metaSchema version and when the file was created
Capture corecapture, camera, imu / imu_meas, board / board_pt, rig, stereo_pair, and the observations frame → board_detection → detectionCorner and IMU arrays are packed float64 blobs. Sealed once capture.content_hash is set
Run overlay (per run_id)run; the selection: frame_status, board_detection_status, detection_status; the results: result_camera, result_imu, extrinsicThe selection tables store only rows that differ from “selected and valid”. extrinsic holds every camera–camera, camera–IMU and IMU–IMU transform with its T, time offset and sigmas
Trajectory (camera–IMU runs)estimate_meta, state_knot / state_var, frame_bracket, world_framestate_knot / state_var: the state timeline and its variables. frame_bracket: which two states bracket each frame, and where. world_frame: the gravity-aligned world

Every overlay table uses ON DELETE CASCADE: deleting a run row deletes all of its overlay rows.

The status tables mirror the core tables one for one. That keeps two things cheap: recording each selection decision as it is made, and checking the stored flags against the data the solve used.