-
Notifications
You must be signed in to change notification settings - Fork 7
Expand file tree
/
Copy pathdatabase.html
More file actions
241 lines (222 loc) · 16.8 KB
/
database.html
File metadata and controls
241 lines (222 loc) · 16.8 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="./">
<head>
<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Database Format — COLMAP 4.1.0.dev0 | 43dd3bb2 (2026-03-16) documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=03e43079" />
<link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=9edc463e" />
<link rel="stylesheet" type="text/css" href="_static/custom.css?v=6631871d" />
<script src="_static/jquery.js?v=5d32c60e"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="_static/documentation_options.js?v=f343b570"></script>
<script src="_static/doctools.js?v=fd6eb6e6"></script>
<script src="_static/sphinx_highlight.js?v=6ffebe34"></script>
<script src="_static/js/theme.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Camera Models" href="cameras.html" />
<link rel="prev" title="Feature Extraction and Matching" href="features.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="index.html" class="icon icon-home">
COLMAP
</a>
<div class="version">
4.1.0.dev0 | 43dd3bb2 (2026-03-16)
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="install.html">Installation</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial.html">Tutorial</a></li>
<li class="toctree-l1"><a class="reference internal" href="concepts.html">Key Concepts</a></li>
<li class="toctree-l1"><a class="reference internal" href="features.html">Feature Extraction and Matching</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Database Format</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#rigs-and-sensors">Rigs and Sensors</a></li>
<li class="toctree-l2"><a class="reference internal" href="#rigs-and-frames">Rigs and Frames</a></li>
<li class="toctree-l2"><a class="reference internal" href="#cameras-and-images">Cameras and Images</a></li>
<li class="toctree-l2"><a class="reference internal" href="#keypoints-and-descriptors">Keypoints and Descriptors</a></li>
<li class="toctree-l2"><a class="reference internal" href="#matches-and-two-view-geometries">Matches and two-view geometries</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="cameras.html">Camera Models</a></li>
<li class="toctree-l1"><a class="reference internal" href="rigs.html">Rig Support</a></li>
<li class="toctree-l1"><a class="reference internal" href="format.html">Output Format</a></li>
<li class="toctree-l1"><a class="reference internal" href="datasets.html">Datasets</a></li>
<li class="toctree-l1"><a class="reference internal" href="gui.html">Graphical User Interface</a></li>
<li class="toctree-l1"><a class="reference internal" href="cli.html">Command-line Interface</a></li>
<li class="toctree-l1"><a class="reference internal" href="pycolmap/index.html">PyCOLMAP</a></li>
<li class="toctree-l1"><a class="reference internal" href="faq.html">Frequently Asked Questions</a></li>
<li class="toctree-l1"><a class="reference internal" href="changelog.html">Changelog</a></li>
<li class="toctree-l1"><a class="reference internal" href="contribution.html">Contribution</a></li>
<li class="toctree-l1"><a class="reference internal" href="license.html">License</a></li>
<li class="toctree-l1"><a class="reference internal" href="bibliography.html">Bibliography</a></li>
<li class="toctree-l1"><a class="reference internal" href="legacy.html">Legacy Documentations</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">COLMAP</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item active">Database Format</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/database.rst.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="database-format">
<span id="id1"></span><h1>Database Format<a class="headerlink" href="#database-format" title="Link to this heading"></a></h1>
<p>COLMAP stores all extracted information in a single SQLite database file. The
database can be accessed with the database management toolkit in the COLMAP GUI,
the provided C++ database API (see <code class="docutils literal notranslate"><span class="pre">src/colmap/scene/database.h</span></code>), or using
Python with pycolmap.</p>
<p>The database contains the following tables:</p>
<ul class="simple">
<li><p>rigs</p></li>
<li><p>cameras</p></li>
<li><p>frames</p></li>
<li><p>images</p></li>
<li><p>keypoints</p></li>
<li><p>descriptors</p></li>
<li><p>matches</p></li>
<li><p>two_view_geometries</p></li>
</ul>
<p>To initialize an empty SQLite database file with the required schema, you can
either create a new project in the GUI or run the <code class="docutils literal notranslate"><span class="pre">colmap</span> <span class="pre">database_creator</span></code> command.</p>
<section id="rigs-and-sensors">
<h2>Rigs and Sensors<a class="headerlink" href="#rigs-and-sensors" title="Link to this heading"></a></h2>
<p>The relation between rigs and sensors (cameras, etc.) is 1-to-N with one sensor
being chosen as the reference sensor to define the origin of the rig. Each sensor
must only be part of one rig.</p>
</section>
<section id="rigs-and-frames">
<h2>Rigs and Frames<a class="headerlink" href="#rigs-and-frames" title="Link to this heading"></a></h2>
<p>The relation between rigs and frames is 1-to-N, where a frame defines a specific
instance of the rig with all or a subset of sensors exposed at the same time.</p>
</section>
<section id="cameras-and-images">
<h2>Cameras and Images<a class="headerlink" href="#cameras-and-images" title="Link to this heading"></a></h2>
<p>The relation between cameras and images is 1-to-N. This has important
implications for Structure-from-Motion, since one camera shares the same
intrinsic parameters (focal length, principal point, distortion, etc.), while
every image has separate extrinsic parameters (orientation and location).</p>
<p>The intrinsic parameters of cameras are stored as contiguous binary blobs in
<code class="docutils literal notranslate"><span class="pre">float64</span></code>, ordered as specified in <code class="docutils literal notranslate"><span class="pre">src/colmap/sensor/models.h</span></code>. COLMAP only
uses cameras that are referenced by images, all other cameras are ignored.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">name</span></code> column in the images table is the unique relative path in the image
folder. As such, the database file and image folder can be moved to different
locations, as long as the relative folder structure is preserved.</p>
<p>When manually inserting images and cameras into the database, make sure
that all identifiers are positive and non-zero, i.e. <code class="docutils literal notranslate"><span class="pre">image_id</span> <span class="pre">></span> <span class="pre">0</span></code>
and <code class="docutils literal notranslate"><span class="pre">camera_id</span> <span class="pre">></span> <span class="pre">0</span></code>.</p>
</section>
<section id="keypoints-and-descriptors">
<h2>Keypoints and Descriptors<a class="headerlink" href="#keypoints-and-descriptors" title="Link to this heading"></a></h2>
<p>The detected keypoints are stored as row-major <code class="docutils literal notranslate"><span class="pre">float32</span></code> binary blobs, where the
first two columns are the X and Y locations in the image, respectively. COLMAP
uses the convention that the upper left image corner has coordinate <code class="docutils literal notranslate"><span class="pre">(0,</span> <span class="pre">0)</span></code> and
the center of the upper left most pixel has coordinate <code class="docutils literal notranslate"><span class="pre">(0.5,</span> <span class="pre">0.5)</span></code>. If the
keypoints have 4 columns, then the feature geometry is a similarity and the
third column is the scale and the fourth column the orientation of the feature
(according to SIFT conventions). If the keypoints have 6 columns, then the
feature geometry is an affinity and the last 4 columns encode its affine shape
(see <code class="docutils literal notranslate"><span class="pre">src/colmap/feature/types.h</span></code> for details).</p>
<p>The extracted descriptors are stored as row-major binary blobs, where each row
describes the feature appearance of the corresponding entry in the keypoints
table. The data type and dimensionality depend on the feature extractor:</p>
<ul class="simple">
<li><p><strong>SIFT</strong>: <code class="docutils literal notranslate"><span class="pre">uint8</span></code> descriptors with 128 dimensions (128 bytes per feature).</p></li>
<li><p><strong>ALIKED</strong>: <code class="docutils literal notranslate"><span class="pre">float32</span></code> descriptors with 128 dimensions (512 bytes per feature).</p></li>
</ul>
<p>The <code class="docutils literal notranslate"><span class="pre">cols</span></code> column in the descriptors table specifies the number of bytes per
descriptor row. For <code class="docutils literal notranslate"><span class="pre">uint8</span></code> descriptors, this equals the descriptor dimension.
For <code class="docutils literal notranslate"><span class="pre">float32</span></code> descriptors, this equals <code class="docutils literal notranslate"><span class="pre">4</span> <span class="pre">*</span> <span class="pre">dimension</span></code>.</p>
<p>In both tables, the <code class="docutils literal notranslate"><span class="pre">rows</span></code> table specifies the number of detected features per
image, while <code class="docutils literal notranslate"><span class="pre">rows=0</span></code> means that an image has no features. For feature matching
and geometric verification, every image must have a corresponding keypoints and
descriptors entry. Note that only vocabulary tree matching with fast spatial
verification requires meaningful values for the local feature geometry, i.e.,
only X and Y must be provided and the other keypoint columns can be set to zero.
The rest of the reconstruction pipeline only uses the keypoint locations.</p>
</section>
<section id="matches-and-two-view-geometries">
<h2>Matches and two-view geometries<a class="headerlink" href="#matches-and-two-view-geometries" title="Link to this heading"></a></h2>
<p>Feature matching stores its output in the <code class="docutils literal notranslate"><span class="pre">matches</span></code> table and geometric
verification in the <code class="docutils literal notranslate"><span class="pre">two_view_geometries</span></code> table. COLMAP only uses the data in
<code class="docutils literal notranslate"><span class="pre">two_view_geometries</span></code> for reconstruction. Every entry in the two tables stores
the feature matches between two unique images, where the <code class="docutils literal notranslate"><span class="pre">pair_id</span></code> is the
row-major, linear index in the upper-triangular match matrix, generated as
follows:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">image_ids_to_pair_id</span><span class="p">(</span><span class="n">image_id1</span><span class="p">,</span> <span class="n">image_id2</span><span class="p">):</span>
<span class="k">if</span> <span class="n">image_id1</span> <span class="o">></span> <span class="n">image_id2</span><span class="p">:</span>
<span class="k">return</span> <span class="mi">2147483647</span> <span class="o">*</span> <span class="n">image_id2</span> <span class="o">+</span> <span class="n">image_id1</span>
<span class="k">else</span><span class="p">:</span>
<span class="k">return</span> <span class="mi">2147483647</span> <span class="o">*</span> <span class="n">image_id1</span> <span class="o">+</span> <span class="n">image_id2</span>
</pre></div>
</div>
<p>and image identifiers can be uniquely determined from the <code class="docutils literal notranslate"><span class="pre">pair_id</span></code> as:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">pair_id_to_image_ids</span><span class="p">(</span><span class="n">pair_id</span><span class="p">):</span>
<span class="n">image_id2</span> <span class="o">=</span> <span class="n">pair_id</span> <span class="o">%</span> <span class="mi">2147483647</span>
<span class="n">image_id1</span> <span class="o">=</span> <span class="p">(</span><span class="n">pair_id</span> <span class="o">-</span> <span class="n">image_id2</span><span class="p">)</span> <span class="o">/</span> <span class="mi">2147483647</span>
<span class="k">return</span> <span class="n">image_id1</span><span class="p">,</span> <span class="n">image_id2</span>
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">pair_id</span></code> enables efficient database queries, as the matches tables may
contain several hundred millions of entries. This scheme limits the maximum
number of images in a database to 2147483647 (maximum value of signed 32-bit
integers), i.e. <code class="docutils literal notranslate"><span class="pre">image_id</span></code> must be smaller than 2147483647.</p>
<p>The binary blobs in the matches tables are row-major <code class="docutils literal notranslate"><span class="pre">uint32</span></code> matrices, where
the left column are zero-based indices into the features of <code class="docutils literal notranslate"><span class="pre">image_id1</span></code> and the
second column into the features of <code class="docutils literal notranslate"><span class="pre">image_id2</span></code>. The column <code class="docutils literal notranslate"><span class="pre">cols</span></code> must be 2 and
the <code class="docutils literal notranslate"><span class="pre">rows</span></code> column specifies the number of feature matches.</p>
<p>The F, E, H blobs in the <code class="docutils literal notranslate"><span class="pre">two_view_geometries</span></code> table are stored as 3x3 matrices
in row-major <code class="docutils literal notranslate"><span class="pre">float64</span></code> format. The meaning of the <code class="docutils literal notranslate"><span class="pre">config</span></code> values are documented
in the <code class="docutils literal notranslate"><span class="pre">src/colmap/estimators/two_view_geometry.h</span></code> source file.</p>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="features.html" class="btn btn-neutral float-left" title="Feature Extraction and Matching" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="cameras.html" class="btn btn-neutral float-right" title="Camera Models" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>© Copyright 2025, Johannes L. Schoenberger.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>