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_reasonand the stage that excluded it.
Where it lives
Section titled “Where it lives”| Run | File |
|---|---|
mvis cam | detections.mvisdb in the run folder (-o). Clearing the run folder keeps it |
mvis cam-imu | One 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.
Read it from Python
Section titled “Read it from Python”from mvis.mvisdb.manager import DatabaseManager
db = DatabaseManager()path = "results/run/detections.mvisdb"print(db.capture_info(path)) # name and hashes of the recordingprint(db.runs(path)) # the runs stored, oldest firstcapture = 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.
The object model
Section titled “The object model”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
On-disk form
Section titled “On-disk form”The same structure is stored in four groups of tables:
| Group | Tables | Notes |
|---|---|---|
| Meta | schema_meta | Schema version and when the file was created |
| Capture core | capture, camera, imu / imu_meas, board / board_pt, rig, stereo_pair, and the observations frame → board_detection → detection | Corner 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, extrinsic | The 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_frame | state_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.