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.
- 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.pyd +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,273 @@
|
|
|
1
|
+
"""A finished reconstruction."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import dataclasses
|
|
6
|
+
import functools
|
|
7
|
+
import os
|
|
8
|
+
from pathlib import Path
|
|
9
|
+
from typing import Optional, Union
|
|
10
|
+
|
|
11
|
+
import numpy as np
|
|
12
|
+
|
|
13
|
+
from . import _pixelmap_multiview
|
|
14
|
+
|
|
15
|
+
__all__ = ["Model", "Texture", "Intrinsics", "Pose", "PairReport"]
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
@dataclasses.dataclass(frozen=True, eq=False)
|
|
19
|
+
class Pose:
|
|
20
|
+
"""Where a camera is and which way it faces.
|
|
21
|
+
|
|
22
|
+
Stored as the transform from world coordinates into the camera's frame,
|
|
23
|
+
``x_cam = rotation @ x_world + translation``. The camera frame is the usual
|
|
24
|
+
computer-vision one: x to the right of the image, y down, z forward.
|
|
25
|
+
"""
|
|
26
|
+
|
|
27
|
+
rotation: np.ndarray
|
|
28
|
+
"""``(3, 3)`` float64: world axes into camera axes."""
|
|
29
|
+
|
|
30
|
+
translation: np.ndarray
|
|
31
|
+
"""``(3,)`` float64: the world origin, in the camera's frame."""
|
|
32
|
+
|
|
33
|
+
@property
|
|
34
|
+
def centre(self) -> np.ndarray:
|
|
35
|
+
"""The camera centre, in world coordinates: ``-rotation.T @ translation``."""
|
|
36
|
+
return -self.rotation.T @ self.translation
|
|
37
|
+
|
|
38
|
+
@property
|
|
39
|
+
def matrix(self) -> np.ndarray:
|
|
40
|
+
"""The ``(3, 4)`` projection matrix ``[R | t]``."""
|
|
41
|
+
return np.hstack([self.rotation, self.translation[:, np.newaxis]])
|
|
42
|
+
|
|
43
|
+
@classmethod
|
|
44
|
+
def _from(cls, fields: Optional[dict]) -> Optional[Pose]:
|
|
45
|
+
return None if fields is None else cls(**fields)
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
@dataclasses.dataclass(frozen=True)
|
|
49
|
+
class Intrinsics:
|
|
50
|
+
"""The pinhole camera every photo shares, in the pixels of the photos handed in."""
|
|
51
|
+
|
|
52
|
+
fx: float
|
|
53
|
+
fy: float
|
|
54
|
+
cx: float
|
|
55
|
+
cy: float
|
|
56
|
+
source: str
|
|
57
|
+
"""Where the focal length came from: ``"provided"``, ``"exif35mm"``,
|
|
58
|
+
``"estimated"`` or ``"refined"``."""
|
|
59
|
+
|
|
60
|
+
@property
|
|
61
|
+
def matrix(self) -> np.ndarray:
|
|
62
|
+
"""The ``(3, 3)`` matrix K."""
|
|
63
|
+
return np.array(
|
|
64
|
+
[[self.fx, 0.0, self.cx], [0.0, self.fy, self.cy], [0.0, 0.0, 1.0]]
|
|
65
|
+
)
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
@dataclasses.dataclass(frozen=True, eq=False)
|
|
69
|
+
class PairReport:
|
|
70
|
+
"""What two-view geometry made of one pair of photos.
|
|
71
|
+
|
|
72
|
+
Attributes:
|
|
73
|
+
pair: ``(a, b)``, the photos' indices, ``a < b``.
|
|
74
|
+
coverage: The fraction of photo ``a`` its dense mapping covers.
|
|
75
|
+
pose: Camera ``b`` in camera ``a``'s frame, with the distance between them scaled
|
|
76
|
+
to 1. ``None`` when the pair was rejected.
|
|
77
|
+
inlier_ratio: The share of sampled matches that agree on one camera motion.
|
|
78
|
+
median_angle_deg: The median angle between the two cameras' rays, in degrees.
|
|
79
|
+
rejection: Why the pair could not anchor a registration, such as ``"planar"``,
|
|
80
|
+
or ``None`` if it could.
|
|
81
|
+
explanation: What the rejection means for the photos.
|
|
82
|
+
"""
|
|
83
|
+
|
|
84
|
+
pair: tuple[int, int]
|
|
85
|
+
coverage: float
|
|
86
|
+
pose: Optional[Pose]
|
|
87
|
+
inlier_ratio: Optional[float]
|
|
88
|
+
median_angle_deg: Optional[float]
|
|
89
|
+
rejection: Optional[str]
|
|
90
|
+
explanation: Optional[str]
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
class Texture:
|
|
94
|
+
"""Colour for a mesh: per vertex, and as a texture atlas.
|
|
95
|
+
|
|
96
|
+
Each triangle's texture comes from the single photo that sees it best. Connected
|
|
97
|
+
triangles that share a photo form a chart, and the charts are packed into one atlas.
|
|
98
|
+
"""
|
|
99
|
+
|
|
100
|
+
def __init__(self, inner: _pixelmap_multiview.Model) -> None:
|
|
101
|
+
self._inner = inner
|
|
102
|
+
|
|
103
|
+
@functools.cached_property
|
|
104
|
+
def atlas(self) -> np.ndarray:
|
|
105
|
+
"""``(H, W, 4)`` uint8 RGBA: the packed charts."""
|
|
106
|
+
return self._inner.atlas
|
|
107
|
+
|
|
108
|
+
@functools.cached_property
|
|
109
|
+
def texcoords(self) -> np.ndarray:
|
|
110
|
+
"""``(K, 2)`` float32 coordinates into :attr:`atlas`, OBJ convention: ``v``
|
|
111
|
+
grows upwards."""
|
|
112
|
+
return self._inner.texcoords
|
|
113
|
+
|
|
114
|
+
@functools.cached_property
|
|
115
|
+
def face_texcoords(self) -> np.ndarray:
|
|
116
|
+
"""``(T, 3)`` uint32: for each triangle, indices into :attr:`texcoords` of its
|
|
117
|
+
three corners. Separate from the vertex indices, because a vertex on a chart
|
|
118
|
+
border has a different place in the atlas for each chart."""
|
|
119
|
+
return self._inner.face_texcoords
|
|
120
|
+
|
|
121
|
+
@functools.cached_property
|
|
122
|
+
def face_views(self) -> np.ndarray:
|
|
123
|
+
"""``(T,)`` uint32: the photo each triangle's texture comes from."""
|
|
124
|
+
return self._inner.face_views
|
|
125
|
+
|
|
126
|
+
@property
|
|
127
|
+
def charts(self) -> int:
|
|
128
|
+
"""How many charts the atlas holds."""
|
|
129
|
+
return self._inner.charts
|
|
130
|
+
|
|
131
|
+
@property
|
|
132
|
+
def atlas_scale(self) -> float:
|
|
133
|
+
"""Atlas pixels per photo pixel; below 1 when the charts were shrunk to fit."""
|
|
134
|
+
return self._inner.atlas_scale
|
|
135
|
+
|
|
136
|
+
def __repr__(self) -> str:
|
|
137
|
+
height, width = self.atlas.shape[:2]
|
|
138
|
+
return (
|
|
139
|
+
f"<pixelmap_multiview.Texture {width}x{height} atlas, {self.charts} charts>"
|
|
140
|
+
)
|
|
141
|
+
|
|
142
|
+
|
|
143
|
+
class Model:
|
|
144
|
+
"""A finished reconstruction.
|
|
145
|
+
|
|
146
|
+
Everything spatial is in one frame, which the best-connected pair of photos defines:
|
|
147
|
+
its first camera sits at the origin looking along +z with +y down the image, and the
|
|
148
|
+
distance between that pair's two cameras is the unit of length. **Nothing is
|
|
149
|
+
metric.** :meth:`save` turns the result half a revolution about x so that viewers
|
|
150
|
+
show it upright; the arrays here are not turned.
|
|
151
|
+
|
|
152
|
+
Returned by :func:`reconstruct` and :meth:`Job.join`; not constructed directly.
|
|
153
|
+
"""
|
|
154
|
+
|
|
155
|
+
def __init__(self, inner: _pixelmap_multiview.Model) -> None:
|
|
156
|
+
if not isinstance(inner, _pixelmap_multiview.Model):
|
|
157
|
+
raise TypeError(
|
|
158
|
+
"Model is returned by pixelmap_multiview.reconstruct(), not constructed "
|
|
159
|
+
"directly"
|
|
160
|
+
)
|
|
161
|
+
self._inner = inner
|
|
162
|
+
|
|
163
|
+
# -- the mesh -------------------------------------------------------------
|
|
164
|
+
|
|
165
|
+
@functools.cached_property
|
|
166
|
+
def vertices(self) -> np.ndarray:
|
|
167
|
+
"""``(V, 3)`` float64 vertex positions."""
|
|
168
|
+
return self._inner.vertices
|
|
169
|
+
|
|
170
|
+
@functools.cached_property
|
|
171
|
+
def normals(self) -> np.ndarray:
|
|
172
|
+
"""``(V, 3)`` float64 unit normals, pointing towards the side the cameras saw."""
|
|
173
|
+
return self._inner.normals
|
|
174
|
+
|
|
175
|
+
@functools.cached_property
|
|
176
|
+
def triangles(self) -> np.ndarray:
|
|
177
|
+
"""``(T, 3)`` uint32 vertex indices, counter-clockwise seen from the side the
|
|
178
|
+
normals point to."""
|
|
179
|
+
return self._inner.triangles
|
|
180
|
+
|
|
181
|
+
@functools.cached_property
|
|
182
|
+
def vertex_colours(self) -> np.ndarray:
|
|
183
|
+
"""``(V, 3)`` uint8 RGB: each vertex a blend of the photos that see it best."""
|
|
184
|
+
return self._inner.vertex_colours
|
|
185
|
+
|
|
186
|
+
@functools.cached_property
|
|
187
|
+
def texture(self) -> Texture:
|
|
188
|
+
"""The texture atlas and its coordinates."""
|
|
189
|
+
return Texture(self._inner)
|
|
190
|
+
|
|
191
|
+
# -- the cameras ----------------------------------------------------------
|
|
192
|
+
|
|
193
|
+
@functools.cached_property
|
|
194
|
+
def intrinsics(self) -> Intrinsics:
|
|
195
|
+
"""The camera the later stages used, with its focal length refined if it was."""
|
|
196
|
+
return Intrinsics(**self._inner.intrinsics)
|
|
197
|
+
|
|
198
|
+
@functools.cached_property
|
|
199
|
+
def cameras(self) -> list[Optional[Pose]]:
|
|
200
|
+
"""Where each photo was taken from, by index. ``None`` for a photo left out."""
|
|
201
|
+
return [Pose._from(fields) for fields in self._inner.cameras]
|
|
202
|
+
|
|
203
|
+
@property
|
|
204
|
+
def views(self) -> int:
|
|
205
|
+
"""How many photos went in."""
|
|
206
|
+
return self._inner.views
|
|
207
|
+
|
|
208
|
+
@functools.cached_property
|
|
209
|
+
def connected(self) -> list[int]:
|
|
210
|
+
"""The indices of the photos that made it into the model."""
|
|
211
|
+
return self._inner.connected
|
|
212
|
+
|
|
213
|
+
@functools.cached_property
|
|
214
|
+
def pairs(self) -> list[PairReport]:
|
|
215
|
+
"""Every pair's two-view geometry, including the pairs that were not usable."""
|
|
216
|
+
reports = []
|
|
217
|
+
for fields in self._inner.pairs:
|
|
218
|
+
fields["pose"] = Pose._from(fields["pose"])
|
|
219
|
+
reports.append(PairReport(**fields))
|
|
220
|
+
return reports
|
|
221
|
+
|
|
222
|
+
# -- writing out ----------------------------------------------------------
|
|
223
|
+
|
|
224
|
+
def save(self, path: Union[str, os.PathLike]) -> list[Path]:
|
|
225
|
+
"""Writes the model for MeshLab, Blender, CloudCompare and the like.
|
|
226
|
+
|
|
227
|
+
The format follows the suffix:
|
|
228
|
+
|
|
229
|
+
- ``.obj``: textured Wavefront OBJ, with a ``.mtl`` material library and the atlas
|
|
230
|
+
as ``<stem>_texture.png`` next to it.
|
|
231
|
+
- ``.x3d``: textured X3D, with the atlas as ``<stem>_texture.png`` next to it.
|
|
232
|
+
- ``.ply``: ASCII PLY with a colour per vertex, for viewers that do not load
|
|
233
|
+
textures.
|
|
234
|
+
|
|
235
|
+
The model is turned half a revolution about x so that viewers show it upright.
|
|
236
|
+
|
|
237
|
+
Returns:
|
|
238
|
+
Every file written, the one named first.
|
|
239
|
+
"""
|
|
240
|
+
path = Path(path)
|
|
241
|
+
suffix = path.suffix.lower()
|
|
242
|
+
texture = path.with_name(f"{path.stem}_texture.png")
|
|
243
|
+
|
|
244
|
+
if suffix == ".obj":
|
|
245
|
+
mtl = path.with_suffix(".mtl")
|
|
246
|
+
files = {
|
|
247
|
+
path: self._inner.obj(mtl.name),
|
|
248
|
+
mtl: self._inner.mtl(texture.name),
|
|
249
|
+
texture: self._inner.atlas_png(),
|
|
250
|
+
}
|
|
251
|
+
elif suffix == ".x3d":
|
|
252
|
+
files = {
|
|
253
|
+
path: self._inner.x3d(texture.name),
|
|
254
|
+
texture: self._inner.atlas_png(),
|
|
255
|
+
}
|
|
256
|
+
elif suffix == ".ply":
|
|
257
|
+
files = {path: self._inner.ply()}
|
|
258
|
+
else:
|
|
259
|
+
raise ValueError(
|
|
260
|
+
f"cannot tell the format from {path.name!r}; use a .obj, .x3d or .ply "
|
|
261
|
+
f"suffix"
|
|
262
|
+
)
|
|
263
|
+
|
|
264
|
+
for target, data in files.items():
|
|
265
|
+
target.write_bytes(data)
|
|
266
|
+
return list(files)
|
|
267
|
+
|
|
268
|
+
def __repr__(self) -> str:
|
|
269
|
+
return (
|
|
270
|
+
f"<pixelmap_multiview.Model {len(self.vertices)} vertices, "
|
|
271
|
+
f"{len(self.triangles)} triangles, "
|
|
272
|
+
f"{len(self.connected)} of {self.views} photos>"
|
|
273
|
+
)
|
|
Binary file
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
"""Type stubs for the native module.
|
|
2
|
+
|
|
3
|
+
Not the package's public interface — see ``pixelmap_multiview/__init__.py`` for that.
|
|
4
|
+
These exist so that type checkers can follow the wrapper's calls into Rust.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from typing import Any, Callable
|
|
8
|
+
|
|
9
|
+
import numpy as np
|
|
10
|
+
from numpy.typing import NDArray
|
|
11
|
+
|
|
12
|
+
MIN_VIEWS: int
|
|
13
|
+
MIN_DIMENSION: int
|
|
14
|
+
MIN_PAIR_COVERAGE: float
|
|
15
|
+
DEFAULT_MAX_TEXTURE_SIZE: int
|
|
16
|
+
STAGES: list[tuple[str, str]]
|
|
17
|
+
|
|
18
|
+
class Model:
|
|
19
|
+
@property
|
|
20
|
+
def vertices(self) -> NDArray[np.float64]: ...
|
|
21
|
+
@property
|
|
22
|
+
def normals(self) -> NDArray[np.float64]: ...
|
|
23
|
+
@property
|
|
24
|
+
def triangles(self) -> NDArray[np.uint32]: ...
|
|
25
|
+
@property
|
|
26
|
+
def vertex_colours(self) -> NDArray[np.uint8]: ...
|
|
27
|
+
@property
|
|
28
|
+
def atlas(self) -> NDArray[np.uint8]: ...
|
|
29
|
+
@property
|
|
30
|
+
def texcoords(self) -> NDArray[np.float32]: ...
|
|
31
|
+
@property
|
|
32
|
+
def face_texcoords(self) -> NDArray[np.uint32]: ...
|
|
33
|
+
@property
|
|
34
|
+
def face_views(self) -> NDArray[np.uint32]: ...
|
|
35
|
+
@property
|
|
36
|
+
def charts(self) -> int: ...
|
|
37
|
+
@property
|
|
38
|
+
def atlas_scale(self) -> float: ...
|
|
39
|
+
@property
|
|
40
|
+
def intrinsics(self) -> dict[str, Any]: ...
|
|
41
|
+
@property
|
|
42
|
+
def cameras(self) -> list[dict[str, NDArray[np.float64]] | None]: ...
|
|
43
|
+
@property
|
|
44
|
+
def views(self) -> int: ...
|
|
45
|
+
@property
|
|
46
|
+
def connected(self) -> list[int]: ...
|
|
47
|
+
@property
|
|
48
|
+
def pairs(self) -> list[dict[str, Any]]: ...
|
|
49
|
+
def obj(self, material_library: str) -> bytes: ...
|
|
50
|
+
def mtl(self, texture_file: str) -> bytes: ...
|
|
51
|
+
def ply(self) -> bytes: ...
|
|
52
|
+
def x3d(self, texture_file: str) -> bytes: ...
|
|
53
|
+
def atlas_png(self) -> bytes: ...
|
|
54
|
+
|
|
55
|
+
class Job:
|
|
56
|
+
def next_event(
|
|
57
|
+
self, timeout: float | None = None
|
|
58
|
+
) -> tuple[str, dict[str, Any]] | None: ...
|
|
59
|
+
def status(self) -> dict[str, Any]: ...
|
|
60
|
+
def cancel(self) -> None: ...
|
|
61
|
+
@property
|
|
62
|
+
def cancelled(self) -> bool: ...
|
|
63
|
+
def join(self) -> Model: ...
|
|
64
|
+
|
|
65
|
+
def run(
|
|
66
|
+
photos: list[NDArray[np.uint8]],
|
|
67
|
+
quality: str,
|
|
68
|
+
focal_kind: str,
|
|
69
|
+
focal_value: float,
|
|
70
|
+
seed: int | None,
|
|
71
|
+
refine_focal: bool,
|
|
72
|
+
max_texture_size: int,
|
|
73
|
+
on_event: Callable[[str, dict[str, Any]], None] | None,
|
|
74
|
+
) -> Model: ...
|
|
75
|
+
def start(
|
|
76
|
+
photos: list[NDArray[np.uint8]],
|
|
77
|
+
quality: str,
|
|
78
|
+
focal_kind: str,
|
|
79
|
+
focal_value: float,
|
|
80
|
+
seed: int | None,
|
|
81
|
+
refine_focal: bool,
|
|
82
|
+
max_texture_size: int,
|
|
83
|
+
) -> Job: ...
|
|
84
|
+
def _synthetic_orbit(
|
|
85
|
+
scene: str, views: int, spread_deg: float, width: int, height: int
|
|
86
|
+
) -> list[NDArray[np.uint8]]: ...
|
|
File without changes
|
|
@@ -0,0 +1,186 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: pixelmap-multiview-python
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Classifier: Development Status :: 4 - Beta
|
|
5
|
+
Classifier: Intended Audience :: Science/Research
|
|
6
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
7
|
+
Classifier: Programming Language :: Python :: 3
|
|
8
|
+
Classifier: Programming Language :: Rust
|
|
9
|
+
Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
|
|
10
|
+
Classifier: Topic :: Scientific/Engineering :: Image Processing
|
|
11
|
+
Classifier: Typing :: Typed
|
|
12
|
+
Requires-Dist: numpy>=1.21
|
|
13
|
+
Requires-Dist: pytest ; extra == 'dev'
|
|
14
|
+
Requires-Dist: pillow>=9.1 ; extra == 'dev'
|
|
15
|
+
Requires-Dist: ruff ; extra == 'dev'
|
|
16
|
+
Requires-Dist: pillow>=9.1 ; extra == 'images'
|
|
17
|
+
Provides-Extra: dev
|
|
18
|
+
Provides-Extra: images
|
|
19
|
+
License-File: LICENSE
|
|
20
|
+
Summary: 3D reconstruction from three or more photos: camera registration, dense depth, fusion and texturing
|
|
21
|
+
Keywords: computer-vision,photogrammetry,3d-reconstruction,structure-from-motion,sfm,mesh
|
|
22
|
+
Author-email: Per Brendelökken <per@brendelokken.se>
|
|
23
|
+
Requires-Python: >=3.9
|
|
24
|
+
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
|
|
25
|
+
Project-URL: Homepage, https://pixelmap.dogduck.com
|
|
26
|
+
Project-URL: Repository, https://github.com/d4per/pixelmap-multiview-python
|
|
27
|
+
Project-URL: Rust crate, https://crates.io/crates/pixelmap_multiview
|
|
28
|
+
|
|
29
|
+
# pixelmap-multiview-python
|
|
30
|
+
|
|
31
|
+
[](https://pypi.org/project/pixelmap-multiview-python/)
|
|
32
|
+
[](https://pypi.org/project/pixelmap-multiview-python/)
|
|
33
|
+
[](LICENSE)
|
|
34
|
+
|
|
35
|
+
**Turn a set of ordinary photos of a scene into a textured 3D model.**
|
|
36
|
+
|
|
37
|
+
Python bindings for the [`pixelmap_multiview`](https://crates.io/crates/pixelmap_multiview)
|
|
38
|
+
Rust crate. It maps every pair of three or more photos with
|
|
39
|
+
[pixelmap](https://pypi.org/project/pixelmap-python/)'s dense correspondence, works out
|
|
40
|
+
where each photo was taken from, and fuses all of the views into one mesh. You don't need
|
|
41
|
+
calibration, markers or measurements.
|
|
42
|
+
|
|
43
|
+
These 23 phone photos were taken while walking once around a statue:
|
|
44
|
+
|
|
45
|
+

|
|
46
|
+
|
|
47
|
+
The mesh fused from them, shown untextured in MeshLab from three sides:
|
|
48
|
+
|
|
49
|
+

|
|
50
|
+
|
|
51
|
+
## Install
|
|
52
|
+
|
|
53
|
+
```console
|
|
54
|
+
pip install pixelmap-multiview-python # the library; NumPy is the only dependency
|
|
55
|
+
pip install "pixelmap-multiview-python[images]" # plus Pillow, for load_photos()
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
The distribution is `pixelmap-multiview-python`, and the import name is
|
|
59
|
+
`pixelmap_multiview`. Wheels are published for Linux (x86-64, aarch64, musl), macOS (Apple
|
|
60
|
+
silicon and Intel) and Windows (x86-64), for CPython 3.9 and newer. You only need a Rust
|
|
61
|
+
toolchain to build from source.
|
|
62
|
+
|
|
63
|
+
## Quick start
|
|
64
|
+
|
|
65
|
+
```python
|
|
66
|
+
import pixelmap_multiview as pmv
|
|
67
|
+
|
|
68
|
+
photos, focal = pmv.load_photos(["a.jpg", "b.jpg", "c.jpg", "d.jpg"])
|
|
69
|
+
model = pmv.reconstruct(photos, quality="medium", focal_35mm=focal)
|
|
70
|
+
|
|
71
|
+
print(model) # <pixelmap_multiview.Model 23314 vertices, 45708 triangles, 4 of 4 photos>
|
|
72
|
+
model.save("out/statue.obj") # + statue.mtl + statue_texture.png, for MeshLab or Blender
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
`load_photos` turns each photo upright according to its EXIF orientation and scales it
|
|
76
|
+
to 1200 px on the long side. It also returns the 35 mm-equivalent focal length from EXIF
|
|
77
|
+
when every photo records the same one. Photos from anywhere else work too: pass a list
|
|
78
|
+
of uint8 arrays `(H, W, 3)`, `(H, W, 4)` or `(H, W)`, or Pillow images, all the same size.
|
|
79
|
+
|
|
80
|
+
## What you get
|
|
81
|
+
|
|
82
|
+
| Attribute | Contents |
|
|
83
|
+
|---|---|
|
|
84
|
+
| `model.vertices`, `model.normals` | `(V, 3)` float64 |
|
|
85
|
+
| `model.triangles` | `(T, 3)` uint32, counter-clockwise seen from the normal's side |
|
|
86
|
+
| `model.vertex_colours` | `(V, 3)` uint8 |
|
|
87
|
+
| `model.texture.atlas` | `(H, W, 4)` uint8, with each part of the surface taken from the photo that sees it best |
|
|
88
|
+
| `model.texture.texcoords`, `.face_texcoords`, `.face_views` | the atlas mapping, OBJ convention |
|
|
89
|
+
| `model.intrinsics` | `fx, fy, cx, cy`, `.matrix`, and whether the focal length was provided, from EXIF, estimated or refined |
|
|
90
|
+
| `model.cameras` | a `Pose` per photo (`rotation`, `translation`, `centre`, `matrix`), or `None` for a photo left out |
|
|
91
|
+
| `model.pairs` | what two-view geometry made of each pair: coverage, relative pose, inlier ratio, and why it was rejected |
|
|
92
|
+
|
|
93
|
+
All of these are in one frame. The first camera of the best pair sits at the origin
|
|
94
|
+
looking along +z with +y down the image, and the distance between that pair's cameras is
|
|
95
|
+
the unit of length. **Nothing is metric.** `model.save()` writes `.obj` (textured),
|
|
96
|
+
`.x3d` (textured) or `.ply` (vertex colours), turned half a revolution about x so that
|
|
97
|
+
viewers show the model upright.
|
|
98
|
+
|
|
99
|
+
## Following along and stopping
|
|
100
|
+
|
|
101
|
+
A run takes minutes of work. `on_event` hears about all of it, as data rather than prose:
|
|
102
|
+
|
|
103
|
+
```python
|
|
104
|
+
def on_event(event):
|
|
105
|
+
if event.progress is not None: # None for log lines and dropped photos
|
|
106
|
+
print(f"{event.progress:5.1%} {event.message}")
|
|
107
|
+
if isinstance(event, pmv.PairMapped):
|
|
108
|
+
event.points # (rows, cols, 2): the dense correspondence for this pair, NaN where unmapped
|
|
109
|
+
|
|
110
|
+
|
|
111
|
+
model = pmv.reconstruct(photos, on_event=on_event)
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
The events are `Started`, `StageProgress`, `PairProgress`, `PairMapped`, `PairRejected`,
|
|
115
|
+
`ViewDropped` and `Log`. Each one carries `stage`, `progress` and `message`, along with its
|
|
116
|
+
own fields. If `on_event` raises an exception, the run stops at the next checkpoint and
|
|
117
|
+
the exception propagates. Ctrl-C stops a run the same way.
|
|
118
|
+
|
|
119
|
+
To keep your own thread free, run the reconstruction as a `Job`:
|
|
120
|
+
|
|
121
|
+
```python
|
|
122
|
+
job = pmv.Job(photos, quality="medium")
|
|
123
|
+
for event in job: # each event as it happens; ends when the run does
|
|
124
|
+
print(f"{job.status.progress:.0%} {event.message}")
|
|
125
|
+
model = job.join()
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
For code with its own event loop, `job.next_event(timeout=0)` polls without waiting, and
|
|
129
|
+
`job.status` works from any thread. After `job.cancel()`, `join()` raises `CancelledError`,
|
|
130
|
+
well within a second.
|
|
131
|
+
|
|
132
|
+
## When a capture fails
|
|
133
|
+
|
|
134
|
+
A run that can't produce a correct model raises an exception rather than returning a
|
|
135
|
+
plausible-looking wrong one. Each exception names the stage that failed and says what to
|
|
136
|
+
change:
|
|
137
|
+
|
|
138
|
+
```python
|
|
139
|
+
try:
|
|
140
|
+
model = pmv.reconstruct(photos)
|
|
141
|
+
except pmv.ReconstructionError as err:
|
|
142
|
+
print(err.stage, err.reason) # tracks too_few_tracks
|
|
143
|
+
# only 338 points could be followed across three or more photos (need 500);
|
|
144
|
+
# the photos share too little of the scene
|
|
145
|
+
print(err)
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
`InvalidInputError` (also a `ValueError`) covers too few photos, photos of different
|
|
149
|
+
sizes, and photos that are too small. `ReconstructionError` covers captures that
|
|
150
|
+
can't be reconstructed: a camera that only turned, a flat scene, or photos with too little
|
|
151
|
+
in common. Match on `err.reason` rather than on the message. The failure's details
|
|
152
|
+
are attributes, such as `err.found` and `err.required`.
|
|
153
|
+
|
|
154
|
+
For a good capture:
|
|
155
|
+
- Step sideways between shots rather than turning on the spot.
|
|
156
|
+
- Let neighbouring photos overlap generously.
|
|
157
|
+
- Keep one camera at one zoom setting throughout.
|
|
158
|
+
|
|
159
|
+
## Cost
|
|
160
|
+
|
|
161
|
+
Mapping the pairs dominates: N photos take N(N−1)/2 pixelmap runs. One pair of 4:3 photos,
|
|
162
|
+
native build:
|
|
163
|
+
|
|
164
|
+
| Quality | 800 px | 1200 px | 1800 px |
|
|
165
|
+
|---------|--------|---------|---------|
|
|
166
|
+
| low | 0.60 s | 0.56 s | 0.50 s |
|
|
167
|
+
| medium | 2.25 s | 2.30 s | 2.38 s |
|
|
168
|
+
| high | | 5.81 s | |
|
|
169
|
+
|
|
170
|
+
Input size barely changes the matching time, because pixelmap scales every photo to a
|
|
171
|
+
fixed working width first. What a larger input buys is precision in the geometry that
|
|
172
|
+
follows. Runs are deterministic: the same photos, quality and `seed` give the same model.
|
|
173
|
+
|
|
174
|
+
## Development
|
|
175
|
+
|
|
176
|
+
```console
|
|
177
|
+
python -m venv .venv && . .venv/bin/activate
|
|
178
|
+
pip install maturin pytest pillow ruff numpy
|
|
179
|
+
maturin develop --release # release matters: the tests run whole reconstructions
|
|
180
|
+
pytest
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
## License
|
|
184
|
+
|
|
185
|
+
MIT
|
|
186
|
+
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
pixelmap_multiview/__init__.py,sha256=RcING3i8DabJcaX-rQ0hTg8PpZT-Avwam9SK1FlbK4Q,12692
|
|
2
|
+
pixelmap_multiview/_errors.py,sha256=82Vnzvy7GpXaa3uFy0gh9i-U4PtRmiXeFuOJJu9CbrY,2474
|
|
3
|
+
pixelmap_multiview/_events.py,sha256=_HNOU7x4mNH7_JVXClgeeyPJrnhyxIXG_X1Zrg4NNx0,4554
|
|
4
|
+
pixelmap_multiview/_io.py,sha256=zoNe1-q_6fu0EBe4P5XuUafbhtGs1FPnidSB_wJw7Ug,3242
|
|
5
|
+
pixelmap_multiview/_model.py,sha256=A9PcvH8M_Ed2lm8_5b4RNRlK4ZkbxmnDR_LHca_XL0Q,9875
|
|
6
|
+
pixelmap_multiview/_pixelmap_multiview.pyd,sha256=VInlW-bDKeVRDT2vL9FC9ujEg2CZ7mmSA0G642cUg7w,1250816
|
|
7
|
+
pixelmap_multiview/_pixelmap_multiview.pyi,sha256=NHDfVH24C29pCSDE7MtUlQi4r9-esKux10JNNzuJoAg,2550
|
|
8
|
+
pixelmap_multiview/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
9
|
+
pixelmap_multiview_python-0.1.0.dist-info/METADATA,sha256=MyM57EhSPvS1gNgGLzIeiOpY2go1zdpE5P_GLx-LtXE,8346
|
|
10
|
+
pixelmap_multiview_python-0.1.0.dist-info/WHEEL,sha256=xe4_tbg8wYdeh4O7nLbnWckzIQtCR4nODDgwke_TKy8,95
|
|
11
|
+
pixelmap_multiview_python-0.1.0.dist-info/licenses/LICENSE,sha256=z7v4yXrvZ6OMfazZ6zC6g0dlK1vryTkEoOnN70KCwIg,1083
|
|
12
|
+
pixelmap_multiview_python-0.1.0.dist-info/sboms/pixelmap-multiview-py.cyclonedx.json,sha256=SAQEHrRkHPK5i-O-yvUvzIqCzvcXxhifhM_euZh2xuI,62800
|
|
13
|
+
pixelmap_multiview_python-0.1.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 d4per
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|