pixelmap-multiview-python 0.1.0__cp39-abi3-macosx_10_12_x86_64.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- pixelmap_multiview/__init__.py +353 -0
- pixelmap_multiview/_errors.py +63 -0
- pixelmap_multiview/_events.py +164 -0
- pixelmap_multiview/_io.py +80 -0
- pixelmap_multiview/_model.py +273 -0
- pixelmap_multiview/_pixelmap_multiview.abi3.so +0 -0
- pixelmap_multiview/_pixelmap_multiview.pyi +86 -0
- pixelmap_multiview/py.typed +0 -0
- pixelmap_multiview_python-0.1.0.dist-info/METADATA +186 -0
- pixelmap_multiview_python-0.1.0.dist-info/RECORD +13 -0
- pixelmap_multiview_python-0.1.0.dist-info/WHEEL +4 -0
- pixelmap_multiview_python-0.1.0.dist-info/licenses/LICENSE +21 -0
- pixelmap_multiview_python-0.1.0.dist-info/sboms/pixelmap-multiview-py.cyclonedx.json +2006 -0
|
@@ -0,0 +1,353 @@
|
|
|
1
|
+
"""3D reconstruction from three or more photos.
|
|
2
|
+
|
|
3
|
+
Python bindings for the `pixelmap_multiview <https://crates.io/crates/pixelmap_multiview>`_
|
|
4
|
+
Rust crate. It maps every pair of photos with pixelmap's dense correspondence, works out
|
|
5
|
+
where each photo was taken from, and fuses every view into one textured mesh.
|
|
6
|
+
|
|
7
|
+
>>> import pixelmap_multiview as pmv
|
|
8
|
+
>>> photos, focal = pmv.load_photos(["a.jpg", "b.jpg", "c.jpg"]) # doctest: +SKIP
|
|
9
|
+
>>> model = pmv.reconstruct(photos, focal_35mm=focal) # doctest: +SKIP
|
|
10
|
+
>>> model.save("statue.obj") # doctest: +SKIP
|
|
11
|
+
|
|
12
|
+
Nothing about the result is metric: the distance between the first two cameras is the
|
|
13
|
+
unit of length. A capture that cannot give a trustworthy model raises a
|
|
14
|
+
:class:`ReconstructionError` that names the stage and says what to change about the
|
|
15
|
+
photos, rather than returning a plausible-looking wrong model.
|
|
16
|
+
|
|
17
|
+
Runs are deterministic: the same photos, quality and seed give the same model.
|
|
18
|
+
"""
|
|
19
|
+
|
|
20
|
+
from __future__ import annotations
|
|
21
|
+
|
|
22
|
+
import enum
|
|
23
|
+
from collections.abc import Iterator, Sequence
|
|
24
|
+
from typing import Callable, Optional, Union
|
|
25
|
+
|
|
26
|
+
import numpy as np
|
|
27
|
+
|
|
28
|
+
from . import _pixelmap_multiview
|
|
29
|
+
from ._errors import (
|
|
30
|
+
CancelledError,
|
|
31
|
+
InvalidInputError,
|
|
32
|
+
PixelmapMultiviewError,
|
|
33
|
+
ReconstructionError,
|
|
34
|
+
)
|
|
35
|
+
from ._events import (
|
|
36
|
+
Event,
|
|
37
|
+
Log,
|
|
38
|
+
PairMapped,
|
|
39
|
+
PairProgress,
|
|
40
|
+
PairRejected,
|
|
41
|
+
StageProgress,
|
|
42
|
+
Started,
|
|
43
|
+
Status,
|
|
44
|
+
ViewDropped,
|
|
45
|
+
_event,
|
|
46
|
+
)
|
|
47
|
+
from ._io import load_photos
|
|
48
|
+
from ._model import Intrinsics, Model, PairReport, Pose, Texture
|
|
49
|
+
|
|
50
|
+
__all__ = [
|
|
51
|
+
"reconstruct",
|
|
52
|
+
"Job",
|
|
53
|
+
"load_photos",
|
|
54
|
+
"Quality",
|
|
55
|
+
"Model",
|
|
56
|
+
"Texture",
|
|
57
|
+
"Intrinsics",
|
|
58
|
+
"Pose",
|
|
59
|
+
"PairReport",
|
|
60
|
+
"Event",
|
|
61
|
+
"Started",
|
|
62
|
+
"StageProgress",
|
|
63
|
+
"PairProgress",
|
|
64
|
+
"PairMapped",
|
|
65
|
+
"PairRejected",
|
|
66
|
+
"ViewDropped",
|
|
67
|
+
"Log",
|
|
68
|
+
"Status",
|
|
69
|
+
"PixelmapMultiviewError",
|
|
70
|
+
"InvalidInputError",
|
|
71
|
+
"ReconstructionError",
|
|
72
|
+
"CancelledError",
|
|
73
|
+
"MIN_VIEWS",
|
|
74
|
+
"MIN_DIMENSION",
|
|
75
|
+
"MIN_PAIR_COVERAGE",
|
|
76
|
+
"DEFAULT_MAX_TEXTURE_SIZE",
|
|
77
|
+
"STAGES",
|
|
78
|
+
"__version__",
|
|
79
|
+
]
|
|
80
|
+
|
|
81
|
+
try: # pragma: no cover - trivial, and absent only in a broken install
|
|
82
|
+
from importlib.metadata import version as _version
|
|
83
|
+
|
|
84
|
+
__version__ = _version("pixelmap-multiview-python")
|
|
85
|
+
except Exception: # pragma: no cover
|
|
86
|
+
__version__ = "unknown"
|
|
87
|
+
|
|
88
|
+
#: The fewest photos a reconstruction needs.
|
|
89
|
+
MIN_VIEWS: int = _pixelmap_multiview.MIN_VIEWS
|
|
90
|
+
|
|
91
|
+
#: The smallest photo pixelmap can work with, on each side.
|
|
92
|
+
MIN_DIMENSION: int = _pixelmap_multiview.MIN_DIMENSION
|
|
93
|
+
|
|
94
|
+
#: The fraction of a photo a pair's mapping must cover to count as linking the two.
|
|
95
|
+
MIN_PAIR_COVERAGE: float = _pixelmap_multiview.MIN_PAIR_COVERAGE
|
|
96
|
+
|
|
97
|
+
#: The largest texture atlas a reconstruction produces by default, in pixels on a side.
|
|
98
|
+
DEFAULT_MAX_TEXTURE_SIZE: int = _pixelmap_multiview.DEFAULT_MAX_TEXTURE_SIZE
|
|
99
|
+
|
|
100
|
+
#: The pipeline's stages in the order they run, as ``(name, description)``. ``name`` is
|
|
101
|
+
#: what :attr:`Event.stage` and :attr:`PixelmapMultiviewError.stage` hold.
|
|
102
|
+
STAGES: list[tuple[str, str]] = _pixelmap_multiview.STAGES
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
class Quality(str, enum.Enum):
|
|
106
|
+
"""How much work pixelmap puts into each pair of photos.
|
|
107
|
+
|
|
108
|
+
The dominant cost of a run, since there are N(N-1)/2 pairs. One pair takes roughly
|
|
109
|
+
0.6 s at ``LOW``, 2.3 s at ``MEDIUM`` and 5.8 s at ``HIGH``.
|
|
110
|
+
"""
|
|
111
|
+
|
|
112
|
+
LOW = "low"
|
|
113
|
+
"""Fastest. The default."""
|
|
114
|
+
|
|
115
|
+
MEDIUM = "medium"
|
|
116
|
+
"""Slower, and more accurate."""
|
|
117
|
+
|
|
118
|
+
HIGH = "high"
|
|
119
|
+
"""Slowest, and likely the best result."""
|
|
120
|
+
|
|
121
|
+
def __str__(self) -> str:
|
|
122
|
+
return self.value
|
|
123
|
+
|
|
124
|
+
|
|
125
|
+
QualityArg = Union[Quality, str]
|
|
126
|
+
|
|
127
|
+
|
|
128
|
+
def _quality_name(quality: QualityArg) -> str:
|
|
129
|
+
if isinstance(quality, Quality):
|
|
130
|
+
return quality.value
|
|
131
|
+
if isinstance(quality, str):
|
|
132
|
+
return quality
|
|
133
|
+
raise TypeError(
|
|
134
|
+
f"quality must be a pixelmap_multiview.Quality or one of 'low', 'medium', "
|
|
135
|
+
f"'high', got {type(quality).__name__}"
|
|
136
|
+
)
|
|
137
|
+
|
|
138
|
+
|
|
139
|
+
def _as_image(image, name: str) -> np.ndarray:
|
|
140
|
+
"""Normalises anything array-like into a contiguous ``(H, W, 3|4)`` uint8 array.
|
|
141
|
+
|
|
142
|
+
Accepts NumPy arrays, Pillow images, and anything else ``np.asarray`` understands.
|
|
143
|
+
Grayscale input — ``(H, W)`` or ``(H, W, 1)`` — is broadcast to three channels.
|
|
144
|
+
"""
|
|
145
|
+
array = np.asarray(image)
|
|
146
|
+
|
|
147
|
+
if array.dtype != np.uint8:
|
|
148
|
+
raise ValueError(
|
|
149
|
+
f"{name} must be a uint8 array, got dtype {array.dtype}. "
|
|
150
|
+
f"Scale floating-point images to 0-255 and cast, e.g. "
|
|
151
|
+
f"(img * 255).astype('uint8')."
|
|
152
|
+
)
|
|
153
|
+
|
|
154
|
+
if array.ndim == 2:
|
|
155
|
+
array = array[:, :, np.newaxis]
|
|
156
|
+
if array.ndim != 3:
|
|
157
|
+
raise ValueError(
|
|
158
|
+
f"{name} must have shape (H, W), (H, W, 1), (H, W, 3) or (H, W, 4), "
|
|
159
|
+
f"got {array.shape}"
|
|
160
|
+
)
|
|
161
|
+
if array.shape[2] == 1:
|
|
162
|
+
array = np.repeat(array, 3, axis=2)
|
|
163
|
+
if array.shape[2] not in (3, 4):
|
|
164
|
+
raise ValueError(
|
|
165
|
+
f"{name} must have 1, 3 or 4 channels, got {array.shape[2]} "
|
|
166
|
+
f"(shape {array.shape})"
|
|
167
|
+
)
|
|
168
|
+
|
|
169
|
+
return np.ascontiguousarray(array)
|
|
170
|
+
|
|
171
|
+
|
|
172
|
+
def _arguments(
|
|
173
|
+
photos,
|
|
174
|
+
quality: QualityArg,
|
|
175
|
+
focal_35mm: Optional[float],
|
|
176
|
+
focal_px: Optional[float],
|
|
177
|
+
seed: Optional[int],
|
|
178
|
+
refine_focal: bool,
|
|
179
|
+
max_texture_size: int,
|
|
180
|
+
) -> tuple:
|
|
181
|
+
"""Checks and normalises the arguments :func:`reconstruct` and :class:`Job` share,
|
|
182
|
+
in the order the native functions take them."""
|
|
183
|
+
if isinstance(photos, np.ndarray) and photos.ndim == 4:
|
|
184
|
+
photos = list(photos)
|
|
185
|
+
photos = [_as_image(photo, f"photos[{i}]") for i, photo in enumerate(photos)]
|
|
186
|
+
|
|
187
|
+
if focal_35mm is not None and focal_px is not None:
|
|
188
|
+
raise ValueError("give focal_35mm or focal_px, not both")
|
|
189
|
+
if focal_35mm is not None:
|
|
190
|
+
focal = ("35mm", float(focal_35mm))
|
|
191
|
+
elif focal_px is not None:
|
|
192
|
+
focal = ("pixels", float(focal_px))
|
|
193
|
+
else:
|
|
194
|
+
focal = ("unknown", 0.0)
|
|
195
|
+
if focal[0] != "unknown" and not (np.isfinite(focal[1]) and focal[1] > 0):
|
|
196
|
+
raise ValueError(f"the focal length must be positive, got {focal[1]}")
|
|
197
|
+
|
|
198
|
+
if seed is not None and not (0 <= seed < 2**64):
|
|
199
|
+
raise ValueError(f"seed must fit in an unsigned 64-bit integer, got {seed}")
|
|
200
|
+
if max_texture_size < 1:
|
|
201
|
+
raise ValueError(f"max_texture_size must be positive, got {max_texture_size}")
|
|
202
|
+
|
|
203
|
+
return (
|
|
204
|
+
photos,
|
|
205
|
+
_quality_name(quality),
|
|
206
|
+
focal[0],
|
|
207
|
+
focal[1],
|
|
208
|
+
seed,
|
|
209
|
+
bool(refine_focal),
|
|
210
|
+
int(max_texture_size),
|
|
211
|
+
)
|
|
212
|
+
|
|
213
|
+
|
|
214
|
+
def reconstruct(
|
|
215
|
+
photos: Sequence,
|
|
216
|
+
*,
|
|
217
|
+
quality: QualityArg = Quality.LOW,
|
|
218
|
+
focal_35mm: Optional[float] = None,
|
|
219
|
+
focal_px: Optional[float] = None,
|
|
220
|
+
seed: Optional[int] = None,
|
|
221
|
+
refine_focal: bool = False,
|
|
222
|
+
max_texture_size: int = DEFAULT_MAX_TEXTURE_SIZE,
|
|
223
|
+
on_event: Optional[Callable[[Event], None]] = None,
|
|
224
|
+
) -> Model:
|
|
225
|
+
"""Reconstructs a textured mesh from photos of one scene.
|
|
226
|
+
|
|
227
|
+
Blocks until done, which is seconds for a few small photos and minutes for a
|
|
228
|
+
walk-around of twenty. Use :class:`Job` to run it in the background instead.
|
|
229
|
+
|
|
230
|
+
Args:
|
|
231
|
+
photos: At least :data:`MIN_VIEWS` photos of a static scene, all from one camera
|
|
232
|
+
at one zoom setting and all the same size, each a uint8 array of shape
|
|
233
|
+
``(H, W)``, ``(H, W, 3)`` or ``(H, W, 4)``. Pillow images work directly;
|
|
234
|
+
:func:`load_photos` reads files. Step sideways between shots rather than
|
|
235
|
+
turning on the spot, and let neighbouring photos overlap generously.
|
|
236
|
+
quality: :class:`Quality` preset, or ``"low"``, ``"medium"`` or ``"high"``.
|
|
237
|
+
focal_35mm: The 35 mm-equivalent focal length, as EXIF records it.
|
|
238
|
+
focal_px: The focal length in pixels of the photos as handed in, for a calibrated
|
|
239
|
+
camera. Give at most one of the two. With neither, the focal length is
|
|
240
|
+
guessed and refined during bundle adjustment.
|
|
241
|
+
seed: Seeds every random choice. The default is the crate's fixed seed, so runs
|
|
242
|
+
are reproducible without asking.
|
|
243
|
+
refine_focal: Refine a given focal length during bundle adjustment. Always done
|
|
244
|
+
when none is given.
|
|
245
|
+
max_texture_size: The largest texture atlas to produce, in pixels on a side.
|
|
246
|
+
on_event: Called with an :class:`Event` at every checkpoint. An exception it
|
|
247
|
+
raises stops the run and is re-raised here. Ctrl-C stops the run the same way,
|
|
248
|
+
with or without a callback.
|
|
249
|
+
|
|
250
|
+
Returns:
|
|
251
|
+
A :class:`Model`.
|
|
252
|
+
|
|
253
|
+
Raises:
|
|
254
|
+
InvalidInputError: Too few photos, photos of different sizes, or a photo smaller
|
|
255
|
+
than :data:`MIN_DIMENSION` on a side.
|
|
256
|
+
ReconstructionError: No trustworthy model could be built from these photos. The
|
|
257
|
+
message says why, and what to change.
|
|
258
|
+
ValueError: A photo is not a uint8 array of an accepted shape, or a setting is
|
|
259
|
+
out of range.
|
|
260
|
+
"""
|
|
261
|
+
callback = None
|
|
262
|
+
if on_event is not None:
|
|
263
|
+
|
|
264
|
+
def callback(kind: str, fields: dict) -> None:
|
|
265
|
+
on_event(_event(kind, fields))
|
|
266
|
+
|
|
267
|
+
arguments = _arguments(
|
|
268
|
+
photos, quality, focal_35mm, focal_px, seed, refine_focal, max_texture_size
|
|
269
|
+
)
|
|
270
|
+
return Model(_pixelmap_multiview.run(*arguments, callback))
|
|
271
|
+
|
|
272
|
+
|
|
273
|
+
class Job:
|
|
274
|
+
"""A reconstruction running on a background thread.
|
|
275
|
+
|
|
276
|
+
Follow it by iterating, poll it with :attr:`status`, stop it with :meth:`cancel`, and
|
|
277
|
+
collect the result with :meth:`join`::
|
|
278
|
+
|
|
279
|
+
job = pmv.Job(photos, quality="medium")
|
|
280
|
+
for event in job:
|
|
281
|
+
print(f"{job.status.progress:.0%} {event.message}")
|
|
282
|
+
model = job.join()
|
|
283
|
+
|
|
284
|
+
Takes the same arguments as :func:`reconstruct`, apart from ``on_event``. The photos
|
|
285
|
+
are checked for shape here; anything else wrong with them comes back from
|
|
286
|
+
:meth:`join` as the exception :func:`reconstruct` would have raised.
|
|
287
|
+
|
|
288
|
+
A job that is dropped without being joined is cancelled, rather than leaving a thread
|
|
289
|
+
grinding through a reconstruction nobody is waiting for.
|
|
290
|
+
"""
|
|
291
|
+
|
|
292
|
+
def __init__(
|
|
293
|
+
self,
|
|
294
|
+
photos: Sequence,
|
|
295
|
+
*,
|
|
296
|
+
quality: QualityArg = Quality.LOW,
|
|
297
|
+
focal_35mm: Optional[float] = None,
|
|
298
|
+
focal_px: Optional[float] = None,
|
|
299
|
+
seed: Optional[int] = None,
|
|
300
|
+
refine_focal: bool = False,
|
|
301
|
+
max_texture_size: int = DEFAULT_MAX_TEXTURE_SIZE,
|
|
302
|
+
) -> None:
|
|
303
|
+
arguments = _arguments(
|
|
304
|
+
photos, quality, focal_35mm, focal_px, seed, refine_focal, max_texture_size
|
|
305
|
+
)
|
|
306
|
+
self._inner = _pixelmap_multiview.start(*arguments)
|
|
307
|
+
|
|
308
|
+
def next_event(self, timeout: Optional[float] = None) -> Optional[Event]:
|
|
309
|
+
"""The next event, waiting at most ``timeout`` seconds for it.
|
|
310
|
+
|
|
311
|
+
Returns ``None`` if the time runs out first. Raises ``StopIteration`` once the
|
|
312
|
+
run is over and every event has been read. ``timeout=0`` polls without waiting,
|
|
313
|
+
for a caller with its own event loop to keep turning.
|
|
314
|
+
"""
|
|
315
|
+
described = self._inner.next_event(timeout)
|
|
316
|
+
return None if described is None else _event(*described)
|
|
317
|
+
|
|
318
|
+
def __iter__(self) -> Iterator[Event]:
|
|
319
|
+
"""Every event the run reports, in order, ending when the run does."""
|
|
320
|
+
while True:
|
|
321
|
+
try:
|
|
322
|
+
yield self.next_event()
|
|
323
|
+
except StopIteration:
|
|
324
|
+
return
|
|
325
|
+
|
|
326
|
+
@property
|
|
327
|
+
def status(self) -> Status:
|
|
328
|
+
"""Where the run has got to, whether or not anyone is reading its events."""
|
|
329
|
+
return Status(**self._inner.status())
|
|
330
|
+
|
|
331
|
+
def cancel(self) -> None:
|
|
332
|
+
"""Asks the run to stop, and returns at once.
|
|
333
|
+
|
|
334
|
+
The run ends at its next checkpoint — within a second even at high quality — and
|
|
335
|
+
:meth:`join` then raises :class:`CancelledError`.
|
|
336
|
+
"""
|
|
337
|
+
self._inner.cancel()
|
|
338
|
+
|
|
339
|
+
@property
|
|
340
|
+
def cancelled(self) -> bool:
|
|
341
|
+
"""Whether :meth:`cancel` has been called."""
|
|
342
|
+
return self._inner.cancelled
|
|
343
|
+
|
|
344
|
+
def join(self) -> Model:
|
|
345
|
+
"""Waits for the run to finish and returns its model.
|
|
346
|
+
|
|
347
|
+
Any events not yet read are discarded. Ctrl-C while waiting cancels the run.
|
|
348
|
+
|
|
349
|
+
Raises:
|
|
350
|
+
CancelledError: The run was stopped with :meth:`cancel`.
|
|
351
|
+
InvalidInputError, ReconstructionError: As for :func:`reconstruct`.
|
|
352
|
+
"""
|
|
353
|
+
return Model(self._inner.join())
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
"""The exceptions this package raises.
|
|
2
|
+
|
|
3
|
+
Every one says which stage of the pipeline it came from and why, as attributes, so that a
|
|
4
|
+
caller can act on a failure without parsing its message. The message itself says what to
|
|
5
|
+
change about the photos.
|
|
6
|
+
|
|
7
|
+
The classes live here rather than in the native module because the Rust side constructs
|
|
8
|
+
them by importing this module, and because two base classes is a plain class statement in
|
|
9
|
+
Python.
|
|
10
|
+
"""
|
|
11
|
+
|
|
12
|
+
__all__ = [
|
|
13
|
+
"PixelmapMultiviewError",
|
|
14
|
+
"InvalidInputError",
|
|
15
|
+
"ReconstructionError",
|
|
16
|
+
"CancelledError",
|
|
17
|
+
]
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
class PixelmapMultiviewError(Exception):
|
|
21
|
+
"""Base class for every error raised by :mod:`pixelmap_multiview`.
|
|
22
|
+
|
|
23
|
+
Attributes:
|
|
24
|
+
stage: The stage that failed, one of the names in :data:`STAGES`, such as
|
|
25
|
+
``"registration"``.
|
|
26
|
+
reason: Which failure it was, in snake_case, such as ``"too_few_tracks"`` or
|
|
27
|
+
``"bundle_adjustment"``. Stable across releases for the failures that exist
|
|
28
|
+
today; match on this rather than on the message.
|
|
29
|
+
|
|
30
|
+
Any further keyword arguments are the failure's own details, set as attributes of the
|
|
31
|
+
same name — ``found`` and ``minimum`` for too few photos, ``median_px`` for a bundle
|
|
32
|
+
adjustment that did not converge, and so on. :attr:`details` holds them all.
|
|
33
|
+
"""
|
|
34
|
+
|
|
35
|
+
def __init__(self, message, stage=None, reason=None, **details):
|
|
36
|
+
super().__init__(message)
|
|
37
|
+
self.stage = stage
|
|
38
|
+
self.reason = reason
|
|
39
|
+
self.details = details
|
|
40
|
+
for name, value in details.items():
|
|
41
|
+
setattr(self, name, value)
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
class InvalidInputError(PixelmapMultiviewError, ValueError):
|
|
45
|
+
"""The photos or settings could not be used at all.
|
|
46
|
+
|
|
47
|
+
Too few photos, photos of different sizes, a photo smaller than
|
|
48
|
+
:data:`MIN_DIMENSION`, or an impossible focal length. Also a ``ValueError``, since
|
|
49
|
+
that is what it means.
|
|
50
|
+
"""
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
class ReconstructionError(PixelmapMultiviewError):
|
|
54
|
+
"""The photos were valid, but no trustworthy model could be built from them.
|
|
55
|
+
|
|
56
|
+
The pipeline fails loudly rather than returning a plausible-looking wrong model. The
|
|
57
|
+
message says what to do differently: take the photos closer together, step sideways
|
|
58
|
+
rather than turning on the spot, include things at different distances.
|
|
59
|
+
"""
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
class CancelledError(PixelmapMultiviewError):
|
|
63
|
+
"""The run was stopped by :meth:`Job.cancel`. :attr:`stage` says where."""
|
|
@@ -0,0 +1,164 @@
|
|
|
1
|
+
"""What a running reconstruction reports.
|
|
2
|
+
|
|
3
|
+
Events carry data, not prose: which pair is being mapped, how far through it, why one
|
|
4
|
+
was rejected. :attr:`Event.message` renders any of them as a line for a log, but its
|
|
5
|
+
wording is not part of the contract; the fields are.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
import dataclasses
|
|
11
|
+
from typing import Optional
|
|
12
|
+
|
|
13
|
+
import numpy as np
|
|
14
|
+
|
|
15
|
+
__all__ = [
|
|
16
|
+
"Event",
|
|
17
|
+
"Started",
|
|
18
|
+
"StageProgress",
|
|
19
|
+
"PairProgress",
|
|
20
|
+
"PairMapped",
|
|
21
|
+
"PairRejected",
|
|
22
|
+
"ViewDropped",
|
|
23
|
+
"Log",
|
|
24
|
+
"Status",
|
|
25
|
+
]
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
@dataclasses.dataclass(frozen=True)
|
|
29
|
+
class Event:
|
|
30
|
+
"""Something that happened while reconstructing.
|
|
31
|
+
|
|
32
|
+
Attributes:
|
|
33
|
+
stage: The stage it came from, one of the names in :data:`STAGES`.
|
|
34
|
+
progress: How far through the whole run this is, ``0.0``-``1.0``, with each stage
|
|
35
|
+
weighted by its typical cost. ``None`` for events that say nothing about
|
|
36
|
+
progress — a log line or a dropped view — which a progress bar should ignore
|
|
37
|
+
rather than move backwards for.
|
|
38
|
+
message: The event as one line for a log.
|
|
39
|
+
"""
|
|
40
|
+
|
|
41
|
+
stage: str
|
|
42
|
+
progress: Optional[float]
|
|
43
|
+
message: str
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
@dataclasses.dataclass(frozen=True)
|
|
47
|
+
class Started(Event):
|
|
48
|
+
"""The run has begun. ``pairs`` is how many pixelmap solves it will take."""
|
|
49
|
+
|
|
50
|
+
views: int
|
|
51
|
+
pairs: int
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
@dataclasses.dataclass(frozen=True)
|
|
55
|
+
class StageProgress(Event):
|
|
56
|
+
"""A stage reached a checkpoint, ``fraction`` of the way through it."""
|
|
57
|
+
|
|
58
|
+
fraction: float
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
@dataclasses.dataclass(frozen=True)
|
|
62
|
+
class PairProgress(Event):
|
|
63
|
+
"""The solver advanced within one pair's mapping.
|
|
64
|
+
|
|
65
|
+
``pair`` is ``(a, b)`` with ``a < b``, the indices of the photos. ``index`` of ``of``
|
|
66
|
+
is the pair's position in the run, from zero; ``step`` of ``steps`` is the solver's
|
|
67
|
+
position within the pair.
|
|
68
|
+
"""
|
|
69
|
+
|
|
70
|
+
pair: tuple[int, int]
|
|
71
|
+
index: int
|
|
72
|
+
of: int
|
|
73
|
+
step: int
|
|
74
|
+
steps: int
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
@dataclasses.dataclass(frozen=True, eq=False)
|
|
78
|
+
class PairMapped(Event):
|
|
79
|
+
"""One pair's dense correspondence is finished.
|
|
80
|
+
|
|
81
|
+
Attributes:
|
|
82
|
+
points: ``(rows, columns, 2)`` float32. ``points[r, c]`` is where the grid cell at
|
|
83
|
+
``(c * cell_size, r * cell_size)`` of photo ``a`` lands in photo ``b``, in the
|
|
84
|
+
pixels of the photos handed in. ``NaN`` where the cell is unmapped.
|
|
85
|
+
cell_size: Photo pixels between neighbouring grid cells.
|
|
86
|
+
coverage: The fraction of photo ``a`` that is mapped.
|
|
87
|
+
"""
|
|
88
|
+
|
|
89
|
+
pair: tuple[int, int]
|
|
90
|
+
index: int
|
|
91
|
+
of: int
|
|
92
|
+
points: np.ndarray
|
|
93
|
+
cell_size: float
|
|
94
|
+
coverage: float
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
@dataclasses.dataclass(frozen=True)
|
|
98
|
+
class PairRejected(Event):
|
|
99
|
+
"""Two-view geometry cannot use a pair to place cameras.
|
|
100
|
+
|
|
101
|
+
Its correspondences can still contribute to dense depth. ``reason`` is the kind, such
|
|
102
|
+
as ``"planar"`` or ``"no_parallax"``; ``explanation`` says what it means for the
|
|
103
|
+
photos.
|
|
104
|
+
"""
|
|
105
|
+
|
|
106
|
+
pair: tuple[int, int]
|
|
107
|
+
index: int
|
|
108
|
+
of: int
|
|
109
|
+
reason: str
|
|
110
|
+
explanation: str
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
@dataclasses.dataclass(frozen=True)
|
|
114
|
+
class ViewDropped(Event):
|
|
115
|
+
"""A photo was left out of the reconstruction, and why."""
|
|
116
|
+
|
|
117
|
+
view: int
|
|
118
|
+
reason: str
|
|
119
|
+
explanation: str
|
|
120
|
+
|
|
121
|
+
|
|
122
|
+
@dataclasses.dataclass(frozen=True)
|
|
123
|
+
class Log(Event):
|
|
124
|
+
"""Something worth saying that is not progress. ``level`` is ``"info"`` or
|
|
125
|
+
``"warning"``."""
|
|
126
|
+
|
|
127
|
+
level: str
|
|
128
|
+
|
|
129
|
+
|
|
130
|
+
_KINDS = {
|
|
131
|
+
"started": Started,
|
|
132
|
+
"stage": StageProgress,
|
|
133
|
+
"pair_progress": PairProgress,
|
|
134
|
+
"pair_mapped": PairMapped,
|
|
135
|
+
"pair_rejected": PairRejected,
|
|
136
|
+
"view_dropped": ViewDropped,
|
|
137
|
+
"log": Log,
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
|
|
141
|
+
def _event(kind: str, fields: dict) -> Event:
|
|
142
|
+
"""Builds the event the native module described as ``(kind, fields)``."""
|
|
143
|
+
cls = _KINDS.get(kind, Event)
|
|
144
|
+
names = {f.name for f in dataclasses.fields(cls)}
|
|
145
|
+
return cls(**{name: value for name, value in fields.items() if name in names})
|
|
146
|
+
|
|
147
|
+
|
|
148
|
+
@dataclasses.dataclass(frozen=True)
|
|
149
|
+
class Status:
|
|
150
|
+
"""Where a :class:`Job` has got to.
|
|
151
|
+
|
|
152
|
+
Attributes:
|
|
153
|
+
stage: The stage now running.
|
|
154
|
+
progress: How far through the whole run, ``0.0``-``1.0``. Only ever moves forward.
|
|
155
|
+
pairs_mapped: How many pairs have been mapped.
|
|
156
|
+
pairs_total: How many there are to map; zero until the run has started.
|
|
157
|
+
message: The most recent line worth showing.
|
|
158
|
+
"""
|
|
159
|
+
|
|
160
|
+
stage: str
|
|
161
|
+
progress: float
|
|
162
|
+
pairs_mapped: int
|
|
163
|
+
pairs_total: int
|
|
164
|
+
message: str
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
"""Reading photos from disc, which the Rust crate deliberately leaves to its callers."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import os
|
|
6
|
+
from collections.abc import Sequence
|
|
7
|
+
from typing import Optional, Union
|
|
8
|
+
|
|
9
|
+
import numpy as np
|
|
10
|
+
|
|
11
|
+
__all__ = ["load_photos"]
|
|
12
|
+
|
|
13
|
+
_EXIF_IFD = 0x8769
|
|
14
|
+
_FOCAL_LENGTH_IN_35MM_FILM = 0xA405
|
|
15
|
+
|
|
16
|
+
PathArg = Union[str, "os.PathLike[str]"]
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
def load_photos(
|
|
20
|
+
paths: Sequence[PathArg], *, max_size: Optional[int] = 1200
|
|
21
|
+
) -> tuple[list[np.ndarray], Optional[float]]:
|
|
22
|
+
"""Reads photos for :func:`reconstruct`, with the focal length EXIF records.
|
|
23
|
+
|
|
24
|
+
Each photo is turned upright as its EXIF orientation says, converted to RGB, and
|
|
25
|
+
scaled down so that its longer side is at most ``max_size`` pixels. Scaling costs no
|
|
26
|
+
matching time — pixelmap works at a fixed resolution whatever it is given — but it
|
|
27
|
+
does cost precision in the geometry that follows, so ``max_size`` is a trade of
|
|
28
|
+
memory against detail. 1200 is what the crate's measurements were taken at.
|
|
29
|
+
|
|
30
|
+
Requires Pillow: ``pip install pixelmap-multiview-python[images]``.
|
|
31
|
+
|
|
32
|
+
Args:
|
|
33
|
+
paths: The photos, all from one camera at one zoom setting.
|
|
34
|
+
max_size: The longest side to scale to, or ``None`` to keep full size.
|
|
35
|
+
|
|
36
|
+
Returns:
|
|
37
|
+
``(photos, focal_35mm)``. ``focal_35mm`` is the 35 mm-equivalent focal length
|
|
38
|
+
from EXIF when every photo records the same one, which is what
|
|
39
|
+
:func:`reconstruct` takes as ``focal_35mm``; otherwise ``None``. The equivalent
|
|
40
|
+
focal length does not depend on pixel count, so it stays right after scaling.
|
|
41
|
+
|
|
42
|
+
Raises:
|
|
43
|
+
ValueError: The photos are not all the same size once turned upright — say, one
|
|
44
|
+
portrait among landscapes.
|
|
45
|
+
"""
|
|
46
|
+
try:
|
|
47
|
+
from PIL import Image, ImageOps
|
|
48
|
+
except ImportError as err: # pragma: no cover - depends on the environment
|
|
49
|
+
raise ImportError(
|
|
50
|
+
"load_photos needs Pillow: pip install pixelmap-multiview-python[images]"
|
|
51
|
+
) from err
|
|
52
|
+
|
|
53
|
+
if max_size is not None and max_size < 1:
|
|
54
|
+
raise ValueError(f"max_size must be positive, got {max_size}")
|
|
55
|
+
|
|
56
|
+
photos: list[np.ndarray] = []
|
|
57
|
+
focals = set()
|
|
58
|
+
size = None
|
|
59
|
+
for path in paths:
|
|
60
|
+
with Image.open(path) as image:
|
|
61
|
+
focals.add(image.getexif().get_ifd(_EXIF_IFD).get(_FOCAL_LENGTH_IN_35MM_FILM))
|
|
62
|
+
image = ImageOps.exif_transpose(image).convert("RGB")
|
|
63
|
+
|
|
64
|
+
if size is None:
|
|
65
|
+
size = image.size
|
|
66
|
+
elif image.size != size:
|
|
67
|
+
raise ValueError(
|
|
68
|
+
f"{os.fspath(path)!r} is {image.size[0]}x{image.size[1]} but the first "
|
|
69
|
+
f"photo is {size[0]}x{size[1]}; all photos must come from one camera at "
|
|
70
|
+
f"one resolution and orientation"
|
|
71
|
+
)
|
|
72
|
+
|
|
73
|
+
if max_size is not None and max(image.size) > max_size:
|
|
74
|
+
scale = max_size / max(image.size)
|
|
75
|
+
target = (round(image.size[0] * scale), round(image.size[1] * scale))
|
|
76
|
+
image = image.resize(target, Image.Resampling.LANCZOS)
|
|
77
|
+
photos.append(np.asarray(image))
|
|
78
|
+
|
|
79
|
+
focal = focals.pop() if len(focals) == 1 else None
|
|
80
|
+
return photos, (float(focal) if focal else None)
|