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
//! Multi-view 3D reconstruction on top of [`pixelmap`].
//!
//! Given three or more photos of a static scene taken with one camera, this crate computes
//! dense correspondence between every pair of them with pixelmap, recovers where each
//! photo was taken from, and fuses the result into a single mesh. `pixelmap_model_3d`
//! lifts one mapping between two photos into a surface; this crate registers every view
//! into one frame so that their surfaces agree.
//!
//! # Quick start
//!
//! Hand over the photos, say how much effort to spend, and follow along:
//!
//! ```no_run
//! use std::sync::Arc;
//! use pixelmap::{Photo, Quality};
//! use pixelmap_multiview::{Event, Flow, Focal, Options};
//!
//! # fn photos() -> Vec<Arc<Photo>> { Vec::new() }
//! let photos = photos();
//! let options = Options::new()
//! .quality(Quality::Medium)
//! .focal(Focal::Equivalent35mm(28.0));
//!
//! let model = pixelmap_multiview::run(&photos, &options, &mut |event: Event| {
//! println!("{}: {}", event.stage(), event.message());
//! Flow::Continue(())
//! })?;
//!
//! println!("{} triangles", model.mesh.triangles.len());
//! # Ok::<(), pixelmap_multiview::Error>(())
//! ```
//!
//! With the `threads` feature, `Job` runs that on a worker thread and hands back a
//! channel of events, a [`Status`] to poll, and a way to stop it.
//!
//! # Stages
//!
//! In order: pairwise correspondence with pixelmap, the relative pose of each pair, points
//! followed across views, every camera placed in one frame, bundle adjustment, a dense
//! depth map per view, fusion into one [`Mesh`], and colour from the photos. [`Stage`]
//! names them; every [`Event`] says which one it came from.
//!
//! # Feedback while it runs
//!
//! One pixelmap solve per pair of photos is the bulk of the work, so a run is minutes long
//! for a handful of photos and the caller hears about it throughout. [`Event`] carries
//! data rather than prose — which pair is being mapped, how far through it, why one was
//! rejected — so that showing progress never means parsing a sentence. The event that
//! finishes a pair carries that pair's [`PairMap`], the raw correspondence grid, for a
//! caller that wants to show the match as it is found.
//!
//! Returning [`Flow::Break`](std::ops::ControlFlow::Break) stops the run, which then
//! returns [`Error::Cancelled`]. A stop takes effect at the next checkpoint: within
//! pairwise correspondence that is one pixelmap schedule step, elsewhere it is prompt.
//!
//! # Design rules
//!
//! - **No I/O, no platform.** Photos come in as RGBA buffers and a mesh goes out.
//! Decoding, EXIF and resizing are the caller's job, which keeps the crate buildable for
//! `wasm32-unknown-unknown`.
//! - **One type per coordinate space.** See [`PhotoPx`], [`Norm`], [`World`].
//! - **Deterministic.** Every random choice draws from a generator derived from a single
//! seed, as pixelmap's own solver does, so any run can be replayed exactly.
//! - **Fail loudly.** Each stage has exit criteria. A run that cannot produce a correct
//! model returns an [`Error`] naming the stage and the reason, rather than a
//! plausible-looking wrong model.
//!
//! # Dependencies in the API
//!
//! Positions, normals and poses are [`nalgebra`] types, and photos, quality and
//! correspondences are [`pixelmap`] types. Both crates are re-exported, so
//! `pixelmap_multiview::nalgebra` and `pixelmap_multiview::pixelmap` are always the versions
//! this crate was built against. A new major version of either is a breaking change here.
//!
//! # Feature flags
//!
//! - **`parallel`** *(default)* — passed through to pixelmap. Turn it off for wasm.
//! - **`threads`** *(default)* — `Job`, which runs a reconstruction on a worker thread.
//! Turn it off for wasm, which has no threads to hand out; [`run`] works there and is
//! what `Job` drives underneath.
pub use nalgebra;
pub use pixelmap;
// The stages themselves. Hidden rather than private, and hidden rather than published:
// the stage tests check one stage at a time against synthetic ground truth and, being
// integration tests, can only reach public paths. Keeping them out of the documentation
// says what `pub` alone does not — that these are the parts most likely to change as the
// geometry is tuned, and that nothing outside this repository should build on them. The
// types a caller actually names are re-exported below. `pixelmap` marks its benchmark
// harness the same way, for the same reason.
// Scenes with known geometry, rendered and matched exactly. For this crate's tests, not
// for building on.
// Plumbing that nothing outside the crate needs to name. What a caller uses from these is
// re-exported below.
pub use ;
pub use Error;
pub use ;
pub use MIN_VIEWS;
pub use PairLookup;
pub use Mesh;
pub use ;
pub use ;
pub use ;
pub use Pose;
pub use DropReason;
pub use Texture;
pub use Degeneracy;
pub use ;
pub use ;
// Reached through `Model::diagnostics`, so they have to be nameable.
pub use Report as AdjustmentReport;
pub use ;
pub use ;
pub use Track;