loop-link 0.1.0__py3-none-any.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.
loop_link/fetch.py ADDED
@@ -0,0 +1,610 @@
1
+ """Fetch viewer objects and decode them into scene objects.
2
+
3
+ The viewer sends an object as a JSON header and a set of named arrays. The
4
+ function :func:`decode_object` makes a scene object from them. The coordinates
5
+ of the result are world coordinates in float64. The function
6
+ :func:`fetch_object` asks the viewer for an object and collects the reply.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import itertools
12
+ import math
13
+ import threading
14
+ import warnings
15
+ from collections.abc import Callable, Mapping, Sequence
16
+ from dataclasses import dataclass
17
+ from typing import Any
18
+
19
+ import numpy as np
20
+
21
+ from loop_link import encode, protocol
22
+ from loop_link.errors import (
23
+ InvalidInputError,
24
+ ObjectTooLargeError,
25
+ UnsupportedObjectError,
26
+ ViewerClosedError,
27
+ )
28
+ from loop_link.objects import (
29
+ DEFAULT_CATEGORY_COLOURS,
30
+ BlockModel,
31
+ Categorical,
32
+ Drillhole,
33
+ Lines,
34
+ Points,
35
+ SceneObject,
36
+ Surface,
37
+ TetraMesh,
38
+ Vectors,
39
+ )
40
+ from loop_link.protocol import Frame, ProtocolError
41
+ from loop_link.tool import ToolConnection
42
+
43
+ __all__ = ["FetchResult", "decode_object", "fetch_object"]
44
+
45
+ # The numpy type of each array type name in the protocol. All are little-endian.
46
+ _ARRAY_DTYPES = {
47
+ "f32": np.dtype("<f4"),
48
+ "f64": np.dtype("<f8"),
49
+ "u32": np.dtype("<u4"),
50
+ "i32": np.dtype("<i4"),
51
+ "u8": np.dtype("u1"),
52
+ }
53
+
54
+ # The members of the property groups that make a Points object into a Vectors object.
55
+ _GROUP_MEMBERS = {
56
+ "orientation": ("dip_direction", "dip"),
57
+ "lineation": ("trend", "plunge"),
58
+ }
59
+
60
+ _SUPPORTED_TYPES = ("Points", "Curve", "Surface", "TetraMesh", "BlockModel", "Drillhole")
61
+
62
+
63
+ @dataclass(frozen=True, eq=False)
64
+ class FetchResult:
65
+ """An object that was fetched from the viewer.
66
+
67
+ Parameters
68
+ ----------
69
+ id : str
70
+ The identifier of the object.
71
+ object : SceneObject
72
+ The decoded object, in world coordinates.
73
+ object_type : str
74
+ The type of the object in the viewer, for example ``"Curve"``.
75
+ revision : int
76
+ The revision of the object in the viewer.
77
+ name : str or None
78
+ The display name.
79
+ parent : str or None
80
+ The identifier of the parent group.
81
+ origin : tuple of float or None
82
+ The scene origin that was used to decode the object.
83
+ crs : str or None
84
+ The coordinate reference system of the scene.
85
+ """
86
+
87
+ id: str
88
+ object: SceneObject
89
+ object_type: str
90
+ revision: int
91
+ name: str | None
92
+ parent: str | None
93
+ origin: tuple[float, float, float] | None
94
+ crs: str | None
95
+
96
+
97
+ def _warn_dropped(name: str, object_id: str, reason: str) -> None:
98
+ """Tell the user that a property is not in the result."""
99
+ warnings.warn(
100
+ f"loop_link dropped the property '{name}' of object '{object_id}': {reason}",
101
+ UserWarning,
102
+ stacklevel=4,
103
+ )
104
+
105
+
106
+ def _decode_text(desc: Mapping[str, Any], arrays: Mapping[str, np.ndarray]) -> np.ndarray:
107
+ """Return a numpy unicode array from the bytes and the offsets of a text property."""
108
+ if desc.get("offsets") is None:
109
+ raise ProtocolError(f"The text property '{desc.get('name')}' has no offsets.")
110
+ data = np.asarray(arrays[desc["buffer"]], dtype=np.uint8).tobytes()
111
+ offsets = np.asarray(arrays[desc["offsets"]]).astype(np.int64)
112
+ items = [
113
+ data[int(start) : int(end)].decode("utf-8") for start, end in itertools.pairwise(offsets)
114
+ ]
115
+ return np.array(items, dtype=str)
116
+
117
+
118
+ class _UnmappedCodeError(Exception):
119
+ """A code of a referenced property is not in its value map."""
120
+
121
+
122
+ def _decode_referenced(
123
+ desc: Mapping[str, Any], arrays: Mapping[str, np.ndarray], object_id: str
124
+ ) -> Categorical:
125
+ """Return a :class:`Categorical` from the codes and the value map of a property."""
126
+ value_map = sorted(desc.get("value_map") or [], key=lambda item: item["id"])
127
+ ids = np.array([item["id"] for item in value_map], dtype=np.int64)
128
+ names = [str(item["name"]) for item in value_map]
129
+ colours = []
130
+ for index, item in enumerate(value_map):
131
+ colour = item.get("colour")
132
+ if colour is None:
133
+ colours.append(DEFAULT_CATEGORY_COLOURS[index % len(DEFAULT_CATEGORY_COLOURS)])
134
+ continue
135
+ values = tuple(int(c) for c in colour)
136
+ colours.append(values if len(values) == 4 else (*values[:3], 255))
137
+ raw = np.asarray(arrays[desc["buffer"]]).astype(np.int64)
138
+ positions = np.searchsorted(ids, raw)
139
+ safe = np.minimum(positions, max(len(ids) - 1, 0))
140
+ if raw.size and (len(ids) == 0 or not np.all(ids[safe] == raw)):
141
+ raise _UnmappedCodeError
142
+ return Categorical(positions, names, colours)
143
+
144
+
145
+ def _decode_values(
146
+ desc: Mapping[str, Any], arrays: Mapping[str, np.ndarray], object_id: str
147
+ ) -> np.ndarray | Categorical:
148
+ """Return the values of one data entry as a numpy array or a Categorical."""
149
+ data_type = desc.get("data_type")
150
+ if data_type == "referenced":
151
+ return _decode_referenced(desc, arrays, object_id)
152
+ if data_type == "text":
153
+ return _decode_text(desc, arrays)
154
+ values = np.asarray(arrays[desc["buffer"]])
155
+ if data_type == "boolean":
156
+ return values != 0
157
+ if data_type == "integer":
158
+ return values.astype(np.int32)
159
+ if values.dtype == np.float32:
160
+ return values
161
+ return values.astype(np.float64)
162
+
163
+
164
+ def _route(
165
+ desc: Mapping[str, Any],
166
+ object_type: str,
167
+ object_id: str,
168
+ interval_set: str | None,
169
+ ) -> str | None:
170
+ """Return the target dictionary of a data entry, or None with a reason in a warning.
171
+
172
+ The result is ``"properties"``, ``"cell_properties"`` or ``"interval_properties"``.
173
+ """
174
+ name = str(desc.get("name", desc.get("id")))
175
+ association = desc.get("association")
176
+ if association == "vertex":
177
+ return "properties"
178
+ if association == "cell":
179
+ if object_type == "Drillhole":
180
+ return "interval_properties"
181
+ if object_type == "Points":
182
+ raise UnsupportedObjectError(object_id, object_type)
183
+ return "cell_properties"
184
+ if association == "interval" and object_type == "Drillhole":
185
+ log_set = desc.get("log_set")
186
+ if log_set is None or log_set == interval_set:
187
+ return "interval_properties"
188
+ _warn_dropped(name, object_id, f"it belongs to the log set '{log_set}', not the first one")
189
+ return None
190
+ _warn_dropped(name, object_id, f"the association '{association}' is not supported")
191
+ return None
192
+
193
+
194
+ def _group_pair(
195
+ group: Mapping[str, Any],
196
+ names: tuple[str, str],
197
+ entries: Mapping[str, Mapping[str, Any]],
198
+ arrays: Mapping[str, np.ndarray],
199
+ ) -> tuple[np.ndarray, np.ndarray]:
200
+ """Return the two float64 arrays of a property group."""
201
+ by_role = {member["role"]: member["data"] for member in group.get("members") or []}
202
+ result = []
203
+ for role in names:
204
+ if role not in by_role or by_role[role] not in entries:
205
+ raise InvalidInputError(
206
+ f"The property group '{group.get('id')}' has no member '{role}'. "
207
+ "Check the object in the viewer."
208
+ )
209
+ buffer = entries[by_role[role]]["buffer"]
210
+ result.append(np.asarray(arrays[buffer]).astype(np.float64))
211
+ return result[0], result[1]
212
+
213
+
214
+ def decode_object(
215
+ header: Mapping[str, Any],
216
+ arrays: Mapping[str, np.ndarray],
217
+ origin: Sequence[float] | None,
218
+ ) -> SceneObject:
219
+ """Decode the header and the arrays of a viewer object into a scene object.
220
+
221
+ Parameters
222
+ ----------
223
+ header : mapping
224
+ The ``scene.upsert`` header of the object.
225
+ arrays : mapping of str to numpy.ndarray
226
+ The buffers of the object, by name.
227
+ origin : sequence of float or None
228
+ The scene origin. The function adds it to the coordinates. None means
229
+ (0, 0, 0).
230
+
231
+ Returns
232
+ -------
233
+ SceneObject
234
+ The object, with float64 world coordinates.
235
+
236
+ Raises
237
+ ------
238
+ UnsupportedObjectError
239
+ If the object type is not supported, or a cell property is on a Points object.
240
+
241
+ Warns
242
+ -----
243
+ UserWarning
244
+ One time for each property that the function drops. This includes a
245
+ referenced property that has a code that is not in its value map.
246
+ """
247
+ object_id = str(header.get("id"))
248
+ object_type = str(header.get("object_type"))
249
+ if object_type not in _SUPPORTED_TYPES:
250
+ raise UnsupportedObjectError(object_id, object_type)
251
+ shift = np.zeros(3) if origin is None else np.asarray(origin, dtype=np.float64)
252
+ geometry = header.get("geometry") or {}
253
+ params = header.get("params") or {}
254
+
255
+ def geo(role: str) -> np.ndarray:
256
+ return np.asarray(arrays[geometry[role]])
257
+
258
+ entries = {str(desc["id"]): desc for desc in header.get("data") or []}
259
+ groups = [
260
+ group
261
+ for group in header.get("property_groups") or []
262
+ if object_type == "Points" and group.get("role") in _GROUP_MEMBERS
263
+ ]
264
+ member_ids = {member["data"] for group in groups for member in group.get("members") or []}
265
+
266
+ interval_set = None
267
+ for log_set in header.get("log_sets") or []:
268
+ if log_set.get("kind") == "interval":
269
+ interval_set = log_set.get("name")
270
+ break
271
+
272
+ targets: dict[str, dict[str, Any]] = {
273
+ "properties": {},
274
+ "cell_properties": {},
275
+ "interval_properties": {},
276
+ }
277
+ for data_id, desc in entries.items():
278
+ if data_id in member_ids:
279
+ continue
280
+ target = _route(desc, object_type, object_id, interval_set)
281
+ if target is not None:
282
+ try:
283
+ targets[target][str(desc["name"])] = _decode_values(desc, arrays, object_id)
284
+ except _UnmappedCodeError:
285
+ _warn_dropped(
286
+ str(desc["name"]),
287
+ object_id,
288
+ "a code is not in its value map",
289
+ )
290
+
291
+ if object_type == "Drillhole":
292
+ end_of_hole = params.get("end_of_hole")
293
+ return Drillhole(
294
+ geo("collar").astype(np.float64) + shift,
295
+ geo("survey").astype(np.float64),
296
+ geo("intervals").astype(np.float64),
297
+ end_of_hole=None if end_of_hole is None else float(end_of_hole[0]),
298
+ properties=targets["properties"],
299
+ interval_properties=targets["interval_properties"],
300
+ )
301
+ if object_type == "BlockModel":
302
+ return BlockModel(
303
+ np.asarray(params["origin"], dtype=np.float64) + shift,
304
+ params["cell_sizes"],
305
+ params["cells"],
306
+ properties=targets["properties"],
307
+ cell_properties=targets["cell_properties"],
308
+ )
309
+
310
+ vertices = geo("vertices").astype(np.float64) + shift
311
+ if object_type == "Curve":
312
+ return Lines(vertices, geo("segments"), targets["properties"], targets["cell_properties"])
313
+ if object_type == "Surface":
314
+ return Surface(
315
+ vertices, geo("triangles"), targets["properties"], targets["cell_properties"]
316
+ )
317
+ if object_type == "TetraMesh":
318
+ return TetraMesh(
319
+ vertices, geo("tetrahedra"), targets["properties"], targets["cell_properties"]
320
+ )
321
+ if not groups:
322
+ return Points(vertices, targets["properties"])
323
+ pairs: dict[str, tuple[np.ndarray, np.ndarray]] = {}
324
+ for group in groups:
325
+ role = group["role"]
326
+ pairs[role] = _group_pair(group, _GROUP_MEMBERS[role], entries, arrays)
327
+ return Vectors(
328
+ vertices,
329
+ orientation=pairs.get("orientation"),
330
+ lineation=pairs.get("lineation"),
331
+ properties=targets["properties"],
332
+ )
333
+
334
+
335
+ def _is_int(value: object) -> bool:
336
+ """Return whether the value is an integer and not a boolean."""
337
+ return isinstance(value, int) and not isinstance(value, bool)
338
+
339
+
340
+ def _as_dict(value: object, what: str) -> dict[str, Any]:
341
+ """Return the value if it is a dict, or raise a ProtocolError."""
342
+ if not isinstance(value, dict):
343
+ raise ProtocolError(f"The {what} is not an object.")
344
+ return value
345
+
346
+
347
+ def _is_origin(origin: object) -> bool:
348
+ """Return whether the value is a list of 3 finite numbers."""
349
+ return (
350
+ isinstance(origin, list)
351
+ and len(origin) == 3
352
+ and all(
353
+ isinstance(v, int | float) and not isinstance(v, bool) and math.isfinite(v)
354
+ for v in origin
355
+ )
356
+ )
357
+
358
+
359
+ def _as_origin(origin: Sequence[float]) -> tuple[float, float, float]:
360
+ """Return the origin as a tuple of 3 floats."""
361
+ x, y, z = (float(value) for value in origin)
362
+ return (x, y, z)
363
+
364
+
365
+ class _Assembler:
366
+ """Collect the frames of one ``object.fetch`` reply and make the result.
367
+
368
+ Parameters
369
+ ----------
370
+ object_id : str
371
+ The identifier of the object that was requested.
372
+ """
373
+
374
+ def __init__(self, object_id: str) -> None:
375
+ self._object_id = object_id
376
+ self._header: dict[str, Any] | None = None
377
+ self._arrays: dict[str, np.ndarray] = {}
378
+ self._shapes: dict[str, tuple[int, ...]] = {}
379
+ self._dtypes: dict[str, np.dtype] = {}
380
+ self._filled: dict[str, int] = {}
381
+ self._parts = 0
382
+ self._ended = False
383
+
384
+ def feed(self, frame: Frame) -> None:
385
+ """Take the next frame of the reply.
386
+
387
+ Parameters
388
+ ----------
389
+ frame : loop_link.protocol.Frame
390
+ An ``object.header``, ``object.part`` or ``object.end`` frame.
391
+
392
+ Raises
393
+ ------
394
+ loop_link.protocol.ProtocolError
395
+ If the frame breaks a rule of the stream.
396
+ loop_link.errors.ObjectTooLargeError
397
+ If the arrays of the header are larger than the limit.
398
+ """
399
+ kind = frame.header.get("type")
400
+ if self._ended:
401
+ raise ProtocolError(f"The viewer sent a '{kind}' frame after 'object.end'.")
402
+ if self._header is None:
403
+ if kind != "object.header":
404
+ raise ProtocolError(
405
+ f"The first frame of an object must be 'object.header', not '{kind}'."
406
+ )
407
+ self._take_header(frame.header)
408
+ elif kind == "object.part":
409
+ self._take_part(frame)
410
+ elif kind == "object.end":
411
+ self._take_end(frame.header)
412
+ else:
413
+ raise ProtocolError(f"The viewer sent an unknown frame '{kind}' for an object.")
414
+
415
+ def finish(self) -> FetchResult:
416
+ """Return the object that the frames described.
417
+
418
+ Returns
419
+ -------
420
+ FetchResult
421
+ The decoded object and its data from the header.
422
+
423
+ Raises
424
+ ------
425
+ loop_link.protocol.ProtocolError
426
+ If the stream did not end, or the header is not valid.
427
+ """
428
+ header = self._header
429
+ if header is None or not self._ended:
430
+ raise ProtocolError("The viewer did not finish the object.")
431
+ arrays = {
432
+ name: data.view(self._dtypes[name]).reshape(self._shapes[name])
433
+ for name, data in self._arrays.items()
434
+ }
435
+ try:
436
+ obj = _as_dict(header["object"], "object header")
437
+ origin = header["origin"]
438
+ object_type = obj["object_type"]
439
+ revision = obj["revision"]
440
+ if not isinstance(object_type, str):
441
+ raise ProtocolError("The field 'object_type' is not a string.")
442
+ if not _is_int(revision) or revision < 0:
443
+ raise ProtocolError("The field 'revision' is not a non-negative integer.")
444
+ for field, value in (
445
+ ("name", obj.get("name")),
446
+ ("parent", obj.get("parent")),
447
+ ("crs", header.get("crs")),
448
+ ):
449
+ if value is not None and not isinstance(value, str):
450
+ raise ProtocolError(f"The field '{field}' is not a string or null.")
451
+ if origin is not None and not _is_origin(origin):
452
+ raise ProtocolError("The field 'origin' is not null or 3 finite numbers.")
453
+ scene_object = decode_object(obj, arrays, origin)
454
+ return FetchResult(
455
+ id=self._object_id,
456
+ object=scene_object,
457
+ object_type=object_type,
458
+ revision=revision,
459
+ name=obj.get("name"),
460
+ parent=obj.get("parent"),
461
+ origin=None if origin is None else _as_origin(origin),
462
+ crs=header.get("crs"),
463
+ )
464
+ except (
465
+ KeyError,
466
+ TypeError,
467
+ ValueError,
468
+ IndexError,
469
+ OverflowError,
470
+ AttributeError,
471
+ ) as error:
472
+ raise ProtocolError(f"The object header is not valid: {error!r}") from error
473
+
474
+ def _take_header(self, header: dict[str, Any]) -> None:
475
+ """Check the header, then make the empty arrays."""
476
+ entries = header.get("arrays")
477
+ if not isinstance(entries, list):
478
+ raise ProtocolError("The 'arrays' field of the object header is not a list.")
479
+ sizes: dict[str, int] = {}
480
+ shapes: dict[str, tuple[int, ...]] = {}
481
+ dtypes: dict[str, np.dtype] = {}
482
+ for entry in entries:
483
+ entry = _as_dict(entry, "array entry")
484
+ name, dtype_name, shape = entry.get("name"), entry.get("dtype"), entry.get("shape")
485
+ if not isinstance(name, str) or name in sizes:
486
+ raise ProtocolError(f"The array name {name!r} is not valid or not unique.")
487
+ if not isinstance(dtype_name, str) or dtype_name not in _ARRAY_DTYPES:
488
+ raise ProtocolError(f"The array '{name}' has the type {dtype_name!r}.")
489
+ if not isinstance(shape, list) or not all(_is_int(n) and n >= 0 for n in shape):
490
+ raise ProtocolError(f"The array '{name}' has a shape that is not valid.")
491
+ dtypes[name] = _ARRAY_DTYPES[dtype_name]
492
+ shapes[name] = tuple(shape)
493
+ sizes[name] = math.prod(shape) * dtypes[name].itemsize
494
+ total = sum(sizes.values())
495
+ if total > protocol.MAX_OBJECT_BYTES:
496
+ raise ObjectTooLargeError(self._object_id, total, protocol.MAX_OBJECT_BYTES)
497
+ obj = _as_dict(header.get("object"), "object header")
498
+ self._check_buffer_names(obj, sizes)
499
+ self._header = header
500
+ self._shapes = shapes
501
+ self._dtypes = dtypes
502
+ self._arrays = {name: np.empty(size, dtype=np.uint8) for name, size in sizes.items()}
503
+ self._filled = dict.fromkeys(sizes, 0)
504
+
505
+ @staticmethod
506
+ def _check_buffer_names(obj: dict[str, Any], sizes: Mapping[str, int]) -> None:
507
+ """Check that each buffer name of the object is in the arrays."""
508
+ names = list(_as_dict(obj.get("geometry") or {}, "geometry").values())
509
+ data = obj.get("data") or []
510
+ if not isinstance(data, list):
511
+ raise ProtocolError("The 'data' field of the object is not a list.")
512
+ for desc in data:
513
+ desc = _as_dict(desc, "data entry")
514
+ names.append(desc.get("buffer"))
515
+ if desc.get("offsets") is not None:
516
+ names.append(desc["offsets"])
517
+ for name in names:
518
+ if not isinstance(name, str) or name not in sizes:
519
+ raise ProtocolError(f"The object uses the buffer {name!r}, which is not sent.")
520
+
521
+ def _take_part(self, frame: Frame) -> None:
522
+ """Copy the bytes of one ``object.part`` frame into its array."""
523
+ header = frame.header
524
+ name, offset, size = header.get("array"), header.get("offset"), header.get("bytes")
525
+ if not isinstance(name, str) or name not in self._arrays:
526
+ raise ProtocolError(f"The viewer sent a part for the unknown array {name!r}.")
527
+ if not _is_int(offset) or not _is_int(size) or offset < 0 or size < 0:
528
+ raise ProtocolError(f"The part of the array '{name}' has a bad offset or size.")
529
+ if offset % 8 != 0:
530
+ raise ProtocolError(
531
+ f"The part of the array '{name}' starts at {offset}, not a multiple of 8."
532
+ )
533
+ part = frame.buffers.get("part")
534
+ if not isinstance(part, np.ndarray) or part.dtype != np.uint8 or part.size != size:
535
+ raise ProtocolError(f"The part of the array '{name}' is not {size} bytes of type u8.")
536
+ if offset != self._filled[name]:
537
+ raise ProtocolError(
538
+ f"The part of the array '{name}' starts at {offset}, "
539
+ f"but {self._filled[name]} bytes are filled."
540
+ )
541
+ target = self._arrays[name]
542
+ if offset + size > target.size:
543
+ raise ProtocolError(f"The part of the array '{name}' goes past the end of the array.")
544
+ target[offset : offset + size] = part.reshape(-1)
545
+ self._filled[name] = offset + size
546
+ self._parts += 1
547
+
548
+ def _take_end(self, header: dict[str, Any]) -> None:
549
+ """Check the ``object.end`` frame."""
550
+ parts = header.get("parts")
551
+ if not _is_int(parts) or parts != self._parts:
552
+ raise ProtocolError(f"The viewer said {parts!r} parts, but sent {self._parts}.")
553
+ for name, array in self._arrays.items():
554
+ if self._filled[name] != array.size:
555
+ raise ProtocolError(f"The array '{name}' is not full when the object ends.")
556
+ self._ended = True
557
+
558
+
559
+ def fetch_object(
560
+ tool: ToolConnection,
561
+ id: str,
562
+ *,
563
+ progress: Callable[[float], None] | None = None,
564
+ cancel: threading.Event | None = None,
565
+ timeout: float = 30.0,
566
+ ) -> FetchResult:
567
+ """Ask the viewer for one object and decode it.
568
+
569
+ Parameters
570
+ ----------
571
+ tool : loop_link.tool.ToolConnection
572
+ The connection to the viewer.
573
+ id : str
574
+ The identifier of the object.
575
+ progress : callable, optional
576
+ Called with the fraction of each progress report.
577
+ cancel : threading.Event, optional
578
+ When it is set, the request is cancelled.
579
+ timeout : float, optional
580
+ The time in seconds to wait for the next frame.
581
+
582
+ Returns
583
+ -------
584
+ FetchResult
585
+ The object, in world coordinates.
586
+
587
+ Raises
588
+ ------
589
+ loop_link.errors.ViewerClosedError
590
+ If the connection closed, or the viewer sent an object that is not valid.
591
+ In the second case the function closes the connection.
592
+ loop_link.errors.ObjectTooLargeError
593
+ If the object is larger than the limit.
594
+ """
595
+ assembler = _Assembler(id)
596
+ try:
597
+ tool.request(
598
+ lambda n: encode.fetch_frame(n, id),
599
+ until=("object.end",),
600
+ feature="selection and fetch (geoviewer protocol 1.18)",
601
+ object_id=id,
602
+ on_frame=assembler.feed,
603
+ progress=progress,
604
+ cancel=cancel,
605
+ timeout=timeout,
606
+ )
607
+ return assembler.finish()
608
+ except ProtocolError as error:
609
+ tool.close()
610
+ raise ViewerClosedError(f"The viewer sent an object that is not valid: {error}") from error