pixelmap-multiview-python 0.1.0__cp39-abi3-win_amd64.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.
@@ -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)