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.
@@ -0,0 +1,1587 @@
1
+ """A fake viewer for the tests: a WebSocket server on 127.0.0.1.
2
+
3
+ The fake viewer does what the link of the real viewer does. It checks the bearer
4
+ token, answers ``hello`` with ``hello`` and ``scene.inventory``, and keeps the
5
+ objects that it receives. It has its own small server-side WebSocket code.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import base64
11
+ import copy
12
+ import hashlib
13
+ import json
14
+ import math
15
+ import os
16
+ import socket
17
+ import struct
18
+ import threading
19
+ import time
20
+ from collections.abc import Iterator, Sequence
21
+ from dataclasses import dataclass, field
22
+ from pathlib import Path
23
+ from typing import Any
24
+
25
+ import numpy as np
26
+
27
+ from .. import protocol
28
+ from ..protocol import (
29
+ MAX_FRAME_BYTES,
30
+ MAX_HEADER_BYTES,
31
+ MAX_OBJECT_BYTES,
32
+ Frame,
33
+ ProtocolError,
34
+ )
35
+
36
+ _GUID = b"258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
37
+
38
+ # The geometry roles that each object type needs.
39
+ _REQUIRED_ROLES: dict[str, tuple[str, ...]] = {
40
+ "Points": ("vertices",),
41
+ "Curve": ("vertices", "segments"),
42
+ "Surface": ("vertices", "triangles"),
43
+ "TetraMesh": ("vertices", "tetrahedra"),
44
+ "BlockModel": (),
45
+ "Drillhole": ("collar", "survey", "intervals"),
46
+ "Group": (),
47
+ }
48
+ # The roles whose rows hold vertex indices, and the roles that hold coordinates.
49
+ _INDEX_ROLES = ("segments", "triangles", "tetrahedra")
50
+ _COORDINATE_ROLES = ("vertices", "collar", "survey")
51
+ # The roles that give the cell count of an object.
52
+ _CELL_ROLES = ("segments", "triangles", "tetrahedra")
53
+ # The row width that each geometry role needs.
54
+ _ROLE_WIDTH = {
55
+ "vertices": 3,
56
+ "survey": 3,
57
+ "intervals": 2,
58
+ "segments": 2,
59
+ "triangles": 3,
60
+ "tetrahedra": 4,
61
+ }
62
+
63
+
64
+ # The protocol names of the array types, by NumPy dtype name.
65
+ _PROTOCOL_DTYPES = {
66
+ "float32": "f32",
67
+ "float64": "f64",
68
+ "uint32": "u32",
69
+ "int32": "i32",
70
+ "uint8": "u8",
71
+ }
72
+
73
+
74
+ class _Closed(Exception):
75
+ """The peer closed the connection."""
76
+
77
+
78
+ @dataclass
79
+ class StoredObject:
80
+ """An object that the fake viewer keeps.
81
+
82
+ Parameters
83
+ ----------
84
+ header : dict
85
+ The header of the ``scene.upsert`` frame.
86
+ buffers : dict of str to numpy.ndarray
87
+ The arrays of the frame, by name.
88
+ """
89
+
90
+ header: dict[str, Any]
91
+ buffers: dict[str, np.ndarray] = field(default_factory=dict)
92
+
93
+
94
+ def _error(code: str, message: str, object_id: object = None) -> Frame:
95
+ """Return an ``error`` frame."""
96
+ header: dict[str, Any] = {"type": "error", "code": code, "message": message}
97
+ if object_id is not None:
98
+ header["object"] = object_id
99
+ return Frame(header=header, buffers={})
100
+
101
+
102
+ def _encode(frame: Frame, version: dict[str, int] | None = None) -> bytes:
103
+ """Return the bytes of a frame, with ``version`` in the header if it is given."""
104
+ return protocol.encode_frame(frame.header, list(frame.buffers.items()), version=version)
105
+
106
+
107
+ def _request_error(
108
+ request: object, code: str, message: str, field_name: str | None = None
109
+ ) -> Frame:
110
+ """Return a ``request.error`` frame for a tool request."""
111
+ error: dict[str, Any] = {"code": code, "message": message}
112
+ if field_name is not None:
113
+ error["field"] = field_name
114
+ return Frame(header={"type": "request.error", "request": request, "error": error}, buffers={})
115
+
116
+
117
+ # The kinds of selection that each object type has. Drillhole and Group have none.
118
+ _SELECTION_KINDS: dict[str, tuple[str, ...]] = {
119
+ "Points": ("nodes",),
120
+ "Curve": ("nodes", "cells"),
121
+ "Surface": ("nodes", "cells"),
122
+ "BlockModel": ("nodes", "cells"),
123
+ "TetraMesh": ("nodes", "cells"),
124
+ "Drillhole": (),
125
+ "Group": (),
126
+ }
127
+
128
+
129
+ # The value types of the command inputs, with the JSON schema of each type.
130
+ _INPUT_SCHEMAS: dict[str, dict[str, Any]] = {
131
+ "str": {"type": "string"},
132
+ "str_or_null": {"type": ["string", "null"]},
133
+ "bool": {"type": "boolean"},
134
+ "u32_list": {"type": "array", "items": {"type": "integer", "minimum": 0}},
135
+ "colour": {
136
+ "type": ["array", "null"],
137
+ "items": {"type": "integer", "minimum": 0, "maximum": 255},
138
+ "minItems": 3,
139
+ "maxItems": 3,
140
+ },
141
+ "scale": {"type": "string", "enum": ["linear", "log"]},
142
+ "edit": {"type": "object"},
143
+ }
144
+ # The commands: (description, needs_window, {field: (value type, required)}).
145
+ _COMMANDS: dict[str, tuple[str, bool, dict[str, tuple[str, bool]]]] = {
146
+ "filter.edit": (
147
+ "Change the filters of an object.",
148
+ False,
149
+ {"object": ("str", True), "edit": ("edit", True)},
150
+ ),
151
+ "colour.set_active": (
152
+ "Choose the array that colours an object.",
153
+ False,
154
+ {"id": ("str", True), "array": ("str_or_null", False)},
155
+ ),
156
+ "colour.set_map": (
157
+ "Choose the colour map of an object.",
158
+ False,
159
+ {"id": ("str", True), "name": ("str", True)},
160
+ ),
161
+ "colour.set_range": (
162
+ "Set the colour range of an object.",
163
+ False,
164
+ {"id": ("str", True), "min": ("str", True), "max": ("str", True)},
165
+ ),
166
+ "colour.clear_range": (
167
+ "Clear the colour range of an object.",
168
+ False,
169
+ {"id": ("str", True)},
170
+ ),
171
+ "colour.set_scale": (
172
+ "Set the colour scale of an object.",
173
+ True,
174
+ {"object": ("str", True), "scale": ("scale", True)},
175
+ ),
176
+ "object.set_colour": (
177
+ "Set the plain colour of an object, or clear it.",
178
+ False,
179
+ {"id": ("str", True), "colour": ("colour", True)},
180
+ ),
181
+ }
182
+ # The fields of each kind of filter edit.
183
+ _EDIT_FIELDS: dict[str, dict[str, str]] = {
184
+ "add": {"array": "str"},
185
+ "set_range": {"array": "str", "min": "str", "max": "str", "keep_nan": "bool"},
186
+ "set_values": {"array": "str", "values": "u32_list"},
187
+ "set_on": {"array": "str", "on": "bool"},
188
+ "set_exclude": {"array": "str", "exclude": "bool"},
189
+ "remove": {"array": "str"},
190
+ "cancel": {},
191
+ }
192
+ # The colour maps that the viewer lists from minor version 18.
193
+ _COLOUR_MAPS = ["viridis", "grey", "coolwarm"]
194
+ # The data types that have no colour map, range or scale.
195
+ _FIXED_COLOUR_TYPES = ("referenced", "boolean")
196
+
197
+
198
+ def _value_ok(kind: str, value: object) -> bool:
199
+ """Return whether ``value`` fits the input type ``kind``."""
200
+ if kind == "str":
201
+ return isinstance(value, str)
202
+ if kind == "str_or_null":
203
+ return value is None or isinstance(value, str)
204
+ if kind == "bool":
205
+ return isinstance(value, bool)
206
+ if kind == "u32_list":
207
+ return isinstance(value, list) and all(type(v) is int and 0 <= v < 1 << 32 for v in value)
208
+ if kind == "colour":
209
+ return value is None or (
210
+ isinstance(value, list)
211
+ and len(value) == 3
212
+ and all(type(v) is int and 0 <= v <= 255 for v in value)
213
+ )
214
+ if kind == "scale":
215
+ return value in ("linear", "log")
216
+ return isinstance(value, dict)
217
+
218
+
219
+ def _check_input(fields: dict[str, tuple[str, bool]], given: object) -> str | None:
220
+ """Return the name of the first bad field of a command input, or ``None``.
221
+
222
+ A field is bad if it is unknown, missing, or of the wrong type.
223
+ """
224
+ if not isinstance(given, dict):
225
+ return "input"
226
+ for key in given:
227
+ if key not in fields:
228
+ return str(key)
229
+ for key, (kind, required) in fields.items():
230
+ if key not in given:
231
+ if required:
232
+ return key
233
+ elif not _value_ok(kind, given[key]):
234
+ return key
235
+ return None
236
+
237
+
238
+ def _check_edit(edit: dict[str, Any]) -> str | None:
239
+ """Return the name of the first bad field of a filter edit, or ``None``."""
240
+ kind = edit.get("kind")
241
+ if not isinstance(kind, str) or kind not in _EDIT_FIELDS:
242
+ return "edit"
243
+ fields = {key: (value_kind, True) for key, value_kind in _EDIT_FIELDS[kind].items()}
244
+ fields["kind"] = ("str", True)
245
+ return _check_input(fields, edit)
246
+
247
+
248
+ def _send(conn: socket.socket, payload: bytes) -> None:
249
+ """Write one unmasked binary WebSocket frame."""
250
+ length = len(payload)
251
+ if length < 126:
252
+ head = bytes([0x82, length])
253
+ elif length < 1 << 16:
254
+ head = bytes([0x82, 126]) + struct.pack(">H", length)
255
+ else:
256
+ head = bytes([0x82, 127]) + struct.pack(">Q", length)
257
+ conn.sendall(head + payload)
258
+
259
+
260
+ class _Reader:
261
+ """Read masked client frames from a socket.
262
+
263
+ Attributes
264
+ ----------
265
+ deferred : list of bytes
266
+ Messages that a read-ahead took from the socket but that the viewer must
267
+ still handle, in arrival order.
268
+ """
269
+
270
+ def __init__(self, conn: socket.socket, buffer: bytes = b"") -> None:
271
+ self._conn = conn
272
+ self._buffer = buffer
273
+ self.deferred: list[bytes] = []
274
+
275
+ def _take(self, count: int) -> bytes:
276
+ while len(self._buffer) < count:
277
+ chunk = self._conn.recv(65536)
278
+ if not chunk:
279
+ raise _Closed
280
+ self._buffer += chunk
281
+ data, self._buffer = self._buffer[:count], self._buffer[count:]
282
+ return data
283
+
284
+ def _frame(self) -> tuple[bool, int, bytes]:
285
+ """Return (fin, opcode, payload) of one WebSocket frame."""
286
+ head = self._take(2)
287
+ fin = bool(head[0] & 0x80)
288
+ opcode = head[0] & 0x0F
289
+ length = head[1] & 0x7F
290
+ if not head[1] & 0x80:
291
+ raise _Closed
292
+ if length == 126:
293
+ (length,) = struct.unpack(">H", self._take(2))
294
+ elif length == 127:
295
+ (length,) = struct.unpack(">Q", self._take(8))
296
+ if length > MAX_FRAME_BYTES + MAX_HEADER_BYTES:
297
+ raise _Closed
298
+ key = self._take(4)
299
+ payload = self._take(length)
300
+ if length:
301
+ mask = np.frombuffer((key * (length // 4 + 1))[:length], dtype=np.uint8)
302
+ payload = (np.frombuffer(payload, dtype=np.uint8) ^ mask).tobytes()
303
+ return fin, opcode, payload
304
+
305
+ def message(self) -> bytes | None:
306
+ """Return the next binary message, or ``None`` after a close frame.
307
+
308
+ The method joins fragments and answers ping frames. It ignores text frames.
309
+ """
310
+ parts: list[bytes] = []
311
+ binary = False
312
+ while True:
313
+ fin, opcode, payload = self._frame()
314
+ if opcode == 0x8:
315
+ self._conn.sendall(bytes([0x88, 0]))
316
+ return None
317
+ if opcode == 0x9:
318
+ self._conn.sendall(bytes([0x8A, len(payload[:125])]) + payload[:125])
319
+ continue
320
+ if opcode == 0xA:
321
+ continue
322
+ if opcode in (0x1, 0x2):
323
+ parts = [payload]
324
+ binary = opcode == 0x2
325
+ elif opcode == 0x0:
326
+ parts.append(payload)
327
+ if fin:
328
+ if binary:
329
+ return b"".join(parts)
330
+ parts = []
331
+
332
+
333
+ def _cell_count(arrays: dict[str, np.ndarray]) -> int | None:
334
+ """Return the number of segments, triangles or tetrahedra, or ``None``."""
335
+ return next((arrays[r].shape[0] for r in _CELL_ROLES if r in arrays), None)
336
+
337
+
338
+ def _expected_length(
339
+ object_type: str,
340
+ association: object,
341
+ arrays: dict[str, np.ndarray],
342
+ params: object,
343
+ log_sets: object,
344
+ ) -> int | None:
345
+ """Return the length that a data array needs, or ``None`` if it cannot fit."""
346
+ if object_type == "BlockModel":
347
+ cells = params.get("cells") if isinstance(params, dict) else None
348
+ if not isinstance(cells, list) or not all(type(n) is int and n >= 0 for n in cells):
349
+ return None
350
+ if association == "cell":
351
+ return math.prod(cells)
352
+ if association == "vertex":
353
+ return math.prod(n + 1 for n in cells)
354
+ return None
355
+ if object_type == "Drillhole":
356
+ if association == "vertex" and "survey" in arrays:
357
+ return arrays["survey"].shape[0]
358
+ has_set = isinstance(log_sets, list) and any(
359
+ isinstance(item, dict) and item.get("kind") == "interval" for item in log_sets
360
+ )
361
+ if association == "interval" and has_set and "intervals" in arrays:
362
+ return arrays["intervals"].shape[0]
363
+ return None
364
+ vertices = arrays.get("vertices")
365
+ if association == "vertex" and vertices is not None:
366
+ return vertices.shape[0]
367
+ if association == "cell" and object_type in ("Curve", "Surface", "TetraMesh"):
368
+ return _cell_count(arrays)
369
+ return None
370
+
371
+
372
+ def _check_data(
373
+ object_type: str,
374
+ entry: object,
375
+ arrays: dict[str, np.ndarray],
376
+ buffers: dict[str, np.ndarray],
377
+ params: object,
378
+ log_sets: object = None,
379
+ ) -> str | None:
380
+ """Return the text of a problem in one data array entry, or ``None``.
381
+
382
+ An ``interval`` array must name a log set of kind ``interval`` in ``log_set``.
383
+ """
384
+ if not isinstance(entry, dict):
385
+ return "A data entry is not an object."
386
+ name = entry.get("buffer")
387
+ if name not in buffers:
388
+ return f"The data entry {entry.get('name')!r} names the buffer {name!r}, which is missing."
389
+ association = entry.get("association")
390
+ if association not in ("vertex", "cell", "interval"):
391
+ return f"The association {association!r} is not known."
392
+ if association == "interval":
393
+ log_set = entry.get("log_set")
394
+ kinds = {
395
+ item.get("name"): item.get("kind")
396
+ for item in (log_sets if isinstance(log_sets, list) else [])
397
+ if isinstance(item, dict)
398
+ }
399
+ if kinds.get(log_set) != "interval":
400
+ return (
401
+ f"The interval array {name!r} names the log set {log_set!r}. "
402
+ "It needs a log set of kind 'interval' in 'log_sets'."
403
+ )
404
+ length = buffers[name].shape[0] if buffers[name].ndim else 0
405
+ if entry.get("data_type") == "text":
406
+ offsets_name = entry.get("offsets")
407
+ if offsets_name not in buffers:
408
+ return f"The text array {name!r} has no offsets buffer."
409
+ offsets = buffers[offsets_name].astype(np.int64)
410
+ if offsets.ndim != 1 or offsets.size < 1:
411
+ return f"The offsets of {name!r} are not valid."
412
+ if offsets[0] != 0 or offsets[-1] != length or np.any(np.diff(offsets) < 0):
413
+ return f"The offsets of {name!r} do not fit its {length} bytes."
414
+ length = offsets.size - 1
415
+ expected = _expected_length(object_type, association, arrays, params, log_sets)
416
+ if expected is None:
417
+ return f"The association {association!r} does not fit the object type {object_type}."
418
+ if length != expected:
419
+ return f"The data array {name!r} has {length} values. The association needs {expected}."
420
+ return None
421
+
422
+
423
+ _GROUP_MEMBERS: dict[str, tuple[set[str], set[str]]] = {
424
+ "orientation": ({"dip_direction", "dip", "polarity"}, {"dip_direction", "dip"}),
425
+ "lineation": ({"trend", "plunge"}, {"trend", "plunge"}),
426
+ }
427
+
428
+
429
+ def _check_group(group: object, data_ids: list[Any]) -> str | None:
430
+ """Return the text of a problem in one property group, or ``None``."""
431
+ if not isinstance(group, dict):
432
+ return "A property group is not an object."
433
+ members = group.get("members") or []
434
+ for member in members:
435
+ if not isinstance(member, dict) or member.get("data") not in data_ids:
436
+ return f"The group {group.get('id')!r} names a data array that the object lacks."
437
+ role = group.get("role")
438
+ if role is None:
439
+ return None
440
+ if role not in _GROUP_MEMBERS:
441
+ return f"The group role {role!r} is not known."
442
+ allowed, required = _GROUP_MEMBERS[role]
443
+ roles = [member.get("role") for member in members]
444
+ if any(r not in allowed for r in roles):
445
+ return (
446
+ f"The {role} group {group.get('id')!r} has a member role that the role does not list."
447
+ )
448
+ if len(set(roles)) != len(roles) or not required <= set(roles):
449
+ return f"The {role} group {group.get('id')!r} needs each of {sorted(required)} once."
450
+ return None
451
+
452
+
453
+ class FakeViewer:
454
+ """A fake viewer that listens on ``127.0.0.1``.
455
+
456
+ Parameters
457
+ ----------
458
+ token : str
459
+ The bearer token that a client must send.
460
+ crs : str
461
+ The CRS that the viewer reports in ``hello``.
462
+ origin : tuple of float
463
+ The origin that the viewer reports in ``hello``.
464
+ kind : str
465
+ The kind of the viewer for the instance file, ``"window"`` or other.
466
+ heartbeat_timeout : float
467
+ The seconds without a frame after which a data connection is closed.
468
+ reply_errors : dict of str to str, optional
469
+ Object id to error text. The viewer refuses these objects.
470
+ read_delay : float
471
+ The seconds to wait after each frame.
472
+ protocol_minor : int
473
+ The minor protocol version of the tool endpoint. Below 18, the tool endpoint
474
+ answers each message with an ``unknown_message`` error.
475
+ part_bytes : int
476
+ The size in bytes of one part of an ``object.fetch`` reply.
477
+ fetch_delay : float
478
+ The seconds to wait between the parts of an ``object.fetch`` reply.
479
+ filter_delay : float
480
+ The seconds that the scene stays busy after a ``filter.edit`` that changes a filter.
481
+ For ``protocol_minor`` 20 or more, the seconds that a filter build takes.
482
+ busy_wait : float
483
+ The seconds that a waiting command waits for the busy time to end. After that,
484
+ the viewer answers ``busy``.
485
+ filter_stop_after : float, optional
486
+ For ``protocol_minor`` 20 or more, the seconds after which a filter build gives
487
+ the result ``{"status": "done", "state": "building"}``. The edit stays applied.
488
+ It has no effect if it is not shorter than the build.
489
+
490
+ Attributes
491
+ ----------
492
+ port : int
493
+ The port of the server.
494
+ objects : dict of str to StoredObject
495
+ The objects in the scene.
496
+ received : list of Frame
497
+ All frames that the viewer received on all connections.
498
+ tool_requests : list of Frame
499
+ All frames that the viewer received on the tool endpoint.
500
+ """
501
+
502
+ def __init__(
503
+ self,
504
+ token: str = "secret",
505
+ crs: str = "EPSG:28350",
506
+ origin: tuple[float, float, float] = (0.0, 0.0, 0.0),
507
+ kind: str = "window",
508
+ heartbeat_timeout: float = 15.0,
509
+ reply_errors: dict[str, str] | None = None,
510
+ read_delay: float = 0.0,
511
+ protocol_minor: int = 18,
512
+ part_bytes: int = 64 * 1024 * 1024,
513
+ fetch_delay: float = 0.0,
514
+ filter_delay: float = 0.0,
515
+ busy_wait: float = 5.0,
516
+ filter_stop_after: float | None = None,
517
+ ) -> None:
518
+ self.token = token
519
+ self.crs = crs
520
+ self.origin = origin
521
+ self.kind = kind
522
+ self.heartbeat_timeout = heartbeat_timeout
523
+ self.reply_errors = dict(reply_errors or {})
524
+ self.read_delay = read_delay
525
+ self.protocol_minor = protocol_minor
526
+ self.part_bytes = part_bytes
527
+ self.fetch_delay = fetch_delay
528
+ self.filter_delay = filter_delay
529
+ self.busy_wait = busy_wait
530
+ self.filter_stop_after = filter_stop_after
531
+ self._filters: dict[str, dict[str, dict[str, Any]]] = {}
532
+ self._colouring: dict[str, dict[str, Any]] = {}
533
+ self._busy_until = 0.0
534
+ self._selection: dict[str, Any] | None = None
535
+ self.tool_requests: list[Frame] = []
536
+ self.objects: dict[str, StoredObject] = {}
537
+ self.received: list[Frame] = []
538
+ self._lock = threading.Lock()
539
+ self._state_lock = threading.Lock()
540
+ self._data_connections = 0
541
+ self._connections: set[socket.socket] = set()
542
+ self._server = socket.socket()
543
+ self._server.bind(("127.0.0.1", 0))
544
+ self._server.listen(8)
545
+ self.port: int = self._server.getsockname()[1]
546
+ self._thread = threading.Thread(target=self._serve, daemon=True)
547
+ self._thread.start()
548
+
549
+ def __enter__(self) -> FakeViewer:
550
+ """Return the viewer."""
551
+ return self
552
+
553
+ def __exit__(self, *exc: object) -> None:
554
+ """Close the viewer."""
555
+ self.close()
556
+
557
+ def close(self) -> None:
558
+ """Stop the server and close all connections."""
559
+ try:
560
+ self._server.close()
561
+ except OSError:
562
+ pass
563
+ with self._lock:
564
+ connections = list(self._connections)
565
+ for conn in connections:
566
+ try:
567
+ conn.shutdown(socket.SHUT_RDWR)
568
+ except OSError:
569
+ pass
570
+ try:
571
+ conn.close()
572
+ except OSError:
573
+ pass
574
+
575
+ # -- state --------------------------------------------------------------
576
+
577
+ def inventory(self) -> list[dict[str, Any]]:
578
+ """Return the inventory entries of the objects in the scene."""
579
+ with self._state_lock:
580
+ items = list(self.objects.items())
581
+ return [
582
+ {
583
+ "id": object_id,
584
+ "object_type": stored.header.get("object_type"),
585
+ "revision": stored.header.get("revision", 1),
586
+ }
587
+ for object_id, stored in items
588
+ ]
589
+
590
+ @property
591
+ def filters(self) -> dict[str, dict[str, dict[str, Any]]]:
592
+ """A copy of the filters, by object id and then by array name.
593
+
594
+ A filter is a dict with the keys ``kind`` (``"range"``, ``"values"`` or ``None``),
595
+ ``on``, ``minimum``, ``maximum``, ``keep_nan``, ``values`` and ``exclude``.
596
+ """
597
+ with self._state_lock:
598
+ return copy.deepcopy(self._filters)
599
+
600
+ @property
601
+ def colouring(self) -> dict[str, dict[str, Any]]:
602
+ """A copy of the colouring, by object id.
603
+
604
+ Each value is a dict with the keys ``array``, ``colour_map``, ``range``,
605
+ ``scale`` and ``plain``.
606
+ """
607
+ with self._state_lock:
608
+ return copy.deepcopy(self._colouring)
609
+
610
+ @property
611
+ def selection(self) -> dict[str, Any] | None:
612
+ """The selection, or ``None``.
613
+
614
+ The dict has the keys ``object``, ``revision``, ``cells`` and ``nodes``. The
615
+ value of ``cells`` or ``nodes`` is a ``uint32`` array without repeats, or
616
+ ``None`` if the selection has no index of that kind.
617
+ """
618
+ with self._state_lock:
619
+ return None if self._selection is None else dict(self._selection)
620
+
621
+ def set_user_selection(
622
+ self,
623
+ object_id: str,
624
+ *,
625
+ cells: Sequence[int] | None = None,
626
+ nodes: Sequence[int] | None = None,
627
+ ) -> None:
628
+ """Select cells or nodes, as if the user did it in the window.
629
+
630
+ Parameters
631
+ ----------
632
+ object_id : str
633
+ The id of the object.
634
+ cells, nodes : sequence of int, optional
635
+ The indices to select.
636
+
637
+ Raises
638
+ ------
639
+ ValueError
640
+ If the object is not known, the object lacks a kind, or an index is out of range.
641
+ """
642
+ kinds = {
643
+ kind: np.asarray(values, dtype=np.int64)
644
+ for kind, values in (("cells", cells), ("nodes", nodes))
645
+ if values is not None
646
+ }
647
+ with self._state_lock:
648
+ problem = self._selection_problem(object_id, None, kinds)
649
+ if problem is not None:
650
+ raise ValueError(problem[1])
651
+ self._store_selection(object_id, kinds)
652
+
653
+ def _store_selection(self, object_id: str, kinds: dict[str, np.ndarray]) -> None:
654
+ """Replace the selection. The caller holds the state lock."""
655
+ unique = {
656
+ kind: np.unique(values).astype(np.uint32)
657
+ for kind, values in kinds.items()
658
+ if values.size
659
+ }
660
+ if not unique:
661
+ self._selection = None
662
+ return
663
+ self._selection = {
664
+ "object": object_id,
665
+ "revision": self.objects[object_id].header.get("revision", 1),
666
+ "cells": unique.get("cells"),
667
+ "nodes": unique.get("nodes"),
668
+ }
669
+
670
+ @staticmethod
671
+ def _element_count(stored: StoredObject, kind: str) -> int:
672
+ """Return the number of nodes or cells of an object."""
673
+ header = stored.header
674
+ if header.get("object_type") == "BlockModel":
675
+ params = header.get("params")
676
+ shape = params.get("cells") if isinstance(params, dict) else None
677
+ shape = [int(n) for n in shape] if isinstance(shape, list) else [0, 0, 0]
678
+ if kind == "cells":
679
+ return math.prod(shape)
680
+ return math.prod(n + 1 for n in shape)
681
+ geometry = header.get("geometry") or {}
682
+ roles = ("vertices",) if kind == "nodes" else _CELL_ROLES
683
+ for role in roles:
684
+ if role in geometry and geometry[role] in stored.buffers:
685
+ return int(stored.buffers[geometry[role]].shape[0])
686
+ return 0
687
+
688
+ def _selection_problem(
689
+ self, object_id: object, revision: object, kinds: dict[str, np.ndarray]
690
+ ) -> tuple[str, str] | None:
691
+ """Return (field, message) for the first problem of a selection, or ``None``.
692
+
693
+ The caller holds the state lock.
694
+ """
695
+ stored = self.objects.get(object_id) if isinstance(object_id, str) else None
696
+ if stored is None:
697
+ return "object", f"The object {object_id!r} is not in the scene."
698
+ current = stored.header.get("revision", 1)
699
+ if revision is not None and revision != current:
700
+ return "revision", f"The revision {revision!r} is not the revision {current}."
701
+ allowed = _SELECTION_KINDS.get(stored.header.get("object_type"), ())
702
+ for kind, values in kinds.items():
703
+ if kind not in allowed:
704
+ return "kind", f"The object {object_id!r} has no {kind}."
705
+ count = self._element_count(stored, kind)
706
+ if values.size and (int(values.min()) < 0 or int(values.max()) >= count):
707
+ return "indices", f"The {kind} need indices from 0 to {count - 1}."
708
+ return None
709
+
710
+ def write_instance_file(self, settings: Path) -> Path:
711
+ """Write ``instances/<pid>.json`` in a settings folder and return its path.
712
+
713
+ The method does not write ``link.json``.
714
+ """
715
+ folder = Path(settings) / "instances"
716
+ folder.mkdir(parents=True, exist_ok=True)
717
+ path = folder / f"{os.getpid()}.json"
718
+ data = {"port": self.port, "kind": self.kind, "pid": os.getpid(), "focused": time.time()}
719
+ path.write_text(json.dumps(data), encoding="utf-8")
720
+ return path
721
+
722
+ # -- frames -------------------------------------------------------------
723
+
724
+ def accept_frame(self, data: bytes) -> list[Frame]:
725
+ """Apply one data-client frame and return the reply frames.
726
+
727
+ Parameters
728
+ ----------
729
+ data : bytes
730
+ The frame from the client.
731
+
732
+ Returns
733
+ -------
734
+ list of Frame
735
+ The frames that the viewer sends back. The list can be empty.
736
+ """
737
+ try:
738
+ frame = protocol.decode_frame(data)
739
+ except ProtocolError as error:
740
+ return [_error("invalid_frame", str(error))]
741
+ with self._state_lock:
742
+ self.received.append(frame)
743
+ header = frame.header
744
+ version = header.get("version")
745
+ major = version.get("major") if isinstance(version, dict) else None
746
+ if major != protocol.PROTOCOL_VERSION["major"]:
747
+ return [_error("unsupported_version", f"The version {version!r} is not supported.")]
748
+ kind = header.get("type")
749
+ if kind == "hello":
750
+ hello = {
751
+ "type": "hello",
752
+ "application": {"name": "fake-viewer"},
753
+ "crs": self.crs,
754
+ "origin": list(self.origin),
755
+ }
756
+ inventory = {"type": "scene.inventory", "entries": self.inventory()}
757
+ return [Frame(header=hello, buffers={}), Frame(header=inventory, buffers={})]
758
+ if kind == "heartbeat":
759
+ return []
760
+ if kind == "scene.upsert":
761
+ return self._upsert(frame)
762
+ if kind == "scene.remove":
763
+ with self._state_lock:
764
+ self.objects.pop(header.get("id"), None)
765
+ return []
766
+ if kind == "scene.clear":
767
+ with self._state_lock:
768
+ self.objects.clear()
769
+ return []
770
+ return [_error("unknown_message", f"The message type {kind!r} is not known.")]
771
+
772
+ def _upsert(self, frame: Frame) -> list[Frame]:
773
+ """Check and keep one object."""
774
+ header = frame.header
775
+ object_id = header.get("id")
776
+ if object_id in self.reply_errors:
777
+ return [_error("invalid_object", self.reply_errors[object_id], object_id)]
778
+ problem = self._check_object(frame)
779
+ if problem is not None:
780
+ return [_error("invalid_object", problem, object_id)]
781
+ names = {entry.get("name") for entry in header.get("data") or [] if isinstance(entry, dict)}
782
+ with self._state_lock:
783
+ self.objects[object_id] = StoredObject(header=header, buffers=dict(frame.buffers))
784
+ kept = self._filters.get(object_id)
785
+ if kept is not None:
786
+ self._filters[object_id] = {k: v for k, v in kept.items() if k in names}
787
+ return []
788
+
789
+ @staticmethod
790
+ def _check_object(frame: Frame) -> str | None:
791
+ """Return the text of the first problem of an object, or ``None``."""
792
+ header, buffers = frame.header, frame.buffers
793
+ object_id = header.get("id")
794
+ object_type = header.get("object_type")
795
+ if not isinstance(object_id, str):
796
+ return "The object has no id."
797
+ if object_type not in _REQUIRED_ROLES:
798
+ return f"The object type {object_type!r} is not known."
799
+ geometry = header.get("geometry") or {}
800
+ if not isinstance(geometry, dict):
801
+ return "The field 'geometry' is not an object."
802
+ for role in _REQUIRED_ROLES[object_type]:
803
+ if role not in geometry:
804
+ return f"The geometry role {role!r} is missing."
805
+ arrays: dict[str, np.ndarray] = {}
806
+ for role, name in geometry.items():
807
+ if name not in buffers:
808
+ return f"The geometry role {role!r} names the buffer {name!r}, which is missing."
809
+ arrays[role] = buffers[name]
810
+ collar = arrays.get("collar")
811
+ if collar is not None and collar.shape not in ((3,), (1, 3)):
812
+ return f"The buffer for 'collar' has the shape {collar.shape}. It needs (3,) or (1, 3)."
813
+ for role, width in _ROLE_WIDTH.items():
814
+ array = arrays.get(role)
815
+ if array is not None and (array.ndim != 2 or array.shape[1] != width):
816
+ return (
817
+ f"The buffer for {role!r} has the shape {array.shape}. It needs (n, {width})."
818
+ )
819
+ for role in _COORDINATE_ROLES:
820
+ array = arrays.get(role)
821
+ if array is not None and array.dtype.kind == "f" and not np.all(np.isfinite(array)):
822
+ return f"The buffer for {role!r} has a coordinate that is not finite."
823
+ if "vertices" in arrays:
824
+ vertices = arrays["vertices"]
825
+ count = vertices.shape[0] if vertices.ndim else 0
826
+ for role in _INDEX_ROLES:
827
+ array = arrays.get(role)
828
+ if array is None or not array.size:
829
+ continue
830
+ if array.dtype.kind not in "iu":
831
+ return f"The buffer for {role!r} does not hold integers."
832
+ if int(array.min()) < 0 or int(array.max()) >= count:
833
+ return f"The buffer for {role!r} has an index outside 0 to {count - 1}."
834
+ revision = header.get("revision")
835
+ if type(revision) is not int or revision < 1:
836
+ return f"The revision {revision!r} is not an integer of 1 or more."
837
+ data = header.get("data") or []
838
+ ids = [entry.get("id") for entry in data if isinstance(entry, dict)]
839
+ if len(set(ids)) != len(ids):
840
+ return "Two data arrays have the same id."
841
+ for entry in data:
842
+ problem = _check_data(
843
+ object_type, entry, arrays, buffers, header.get("params"), header.get("log_sets")
844
+ )
845
+ if problem is not None:
846
+ return problem
847
+ for group in header.get("property_groups") or []:
848
+ problem = _check_group(group, ids)
849
+ if problem is not None:
850
+ return problem
851
+ for name, array in buffers.items():
852
+ if array.size * array.itemsize != array.nbytes:
853
+ return f"The buffer {name!r} does not match its declared size."
854
+ size = sum(int(array.nbytes) for array in buffers.values())
855
+ if size > MAX_OBJECT_BYTES:
856
+ return f"The object is {size} bytes. The limit is {MAX_OBJECT_BYTES} bytes."
857
+ return None
858
+
859
+ def tool_frame(self, data: bytes) -> list[Frame]:
860
+ """Apply one tool-client frame and return the reply frames.
861
+
862
+ Parameters
863
+ ----------
864
+ data : bytes
865
+ The frame from the client.
866
+
867
+ Returns
868
+ -------
869
+ list of Frame
870
+ The frames that the viewer sends back.
871
+ """
872
+ try:
873
+ frame = protocol.decode_frame(data)
874
+ except ProtocolError as error:
875
+ return [_error("invalid_frame", str(error))]
876
+ with self._state_lock:
877
+ self.tool_requests.append(frame)
878
+ return self._tool_reply(frame)
879
+
880
+ def _tool_reply(self, frame: Frame) -> list[Frame]:
881
+ """Return the reply frames for one decoded tool-client frame.
882
+
883
+ For ``object.fetch`` the list holds all reply frames. A real connection
884
+ uses ``_stream_fetch`` instead, which can stop on ``command.cancel``.
885
+ """
886
+ kind = frame.header.get("type")
887
+ request = frame.header.get("request")
888
+ if self.protocol_minor >= 11 and kind == "commands.list":
889
+ return [self._commands_list(request)]
890
+ if self.protocol_minor >= 11 and kind == "command.run":
891
+ return [self._command_run(frame)]
892
+ if self.protocol_minor >= 18 and kind == "object.fetch":
893
+ return list(self._fetch_frames(frame))
894
+ if self.protocol_minor >= 18 and kind in ("selection.set", "selection.get"):
895
+ if self.kind == "headless":
896
+ return [_request_error(request, "needs_window", "The viewer has no window.")]
897
+ if kind == "selection.get":
898
+ return [self._selection_get(request)]
899
+ return [self._selection_set(frame)]
900
+ return [_error("unknown_message", f"The message type {kind!r} is not known.")]
901
+
902
+ def _commands_list(self, request: object) -> Frame:
903
+ """Return the ``commands`` frame for ``commands.list``."""
904
+ entries = []
905
+ for name, (description, needs_window, fields) in _COMMANDS.items():
906
+ properties = {key: dict(_INPUT_SCHEMAS[kind]) for key, (kind, _) in fields.items()}
907
+ if name == "colour.set_map":
908
+ properties["name"] = (
909
+ {"type": "string", "enum": list(_COLOUR_MAPS)}
910
+ if self.protocol_minor >= 18
911
+ else {"type": "string"}
912
+ )
913
+ entry: dict[str, Any] = {
914
+ "name": name,
915
+ "description": description,
916
+ "needs_window": needs_window,
917
+ "tool_available": True,
918
+ "unavailable_reason": None,
919
+ "input_schema": {
920
+ "type": "object",
921
+ "properties": properties,
922
+ "required": [key for key, (_, required) in fields.items() if required],
923
+ "additionalProperties": False,
924
+ },
925
+ "result_schema": {
926
+ "type": "object",
927
+ "properties": {
928
+ "status": {"enum": ["done", "refused"]},
929
+ "text": {"type": "string"},
930
+ },
931
+ "required": ["status"],
932
+ },
933
+ }
934
+ if name == "filter.edit" and self.protocol_minor >= 20:
935
+ entry["long"] = True
936
+ entries.append(entry)
937
+ header = {"type": "commands", "request": request, "viewer": self.kind, "commands": entries}
938
+ return Frame(header=header, buffers={})
939
+
940
+ def _wait_if_busy(self, command: str) -> bool:
941
+ """Wait for the busy time to end. Return ``False`` if the command must get ``busy``.
942
+
943
+ ``colour.set_scale`` does not wait. It gets ``busy`` at once. Other commands wait
944
+ at most ``busy_wait`` seconds.
945
+ """
946
+ with self._state_lock:
947
+ remaining = self._busy_until - time.monotonic()
948
+ if remaining <= 0:
949
+ return True
950
+ if command == "colour.set_scale":
951
+ return False
952
+ time.sleep(min(remaining, self.busy_wait))
953
+ return remaining <= self.busy_wait
954
+
955
+ def _command_problem(self, frame: Frame) -> Frame | None:
956
+ """Check the input and the object of a command. Return a ``request.error`` or ``None``."""
957
+ request = frame.header.get("request")
958
+ command = frame.header.get("command")
959
+ spec = _COMMANDS.get(command) if isinstance(command, str) else None
960
+ if spec is None:
961
+ return _request_error(
962
+ request, "invalid_input", f"The command {command!r} is not known."
963
+ )
964
+ _, needs_window, fields = spec
965
+ given = frame.header.get("input")
966
+ bad = _check_input(fields, given)
967
+ if bad is None and command == "filter.edit":
968
+ bad = _check_edit(given["edit"])
969
+ if bad is not None:
970
+ return _request_error(
971
+ request, "invalid_input", f"The input field {bad!r} is not valid.", bad
972
+ )
973
+ id_field = "object" if "object" in fields else "id"
974
+ with self._state_lock:
975
+ known = given[id_field] in self.objects
976
+ if not known:
977
+ return _request_error(
978
+ request,
979
+ "invalid_input",
980
+ f"The object {given[id_field]!r} is not in the scene.",
981
+ id_field,
982
+ )
983
+ if needs_window and self.kind == "headless":
984
+ return _request_error(request, "needs_window", "The viewer has no window.")
985
+ return None
986
+
987
+ def _command_run(self, frame: Frame) -> Frame:
988
+ """Check and run one command. Return the ``command.result`` or ``request.error`` frame."""
989
+ problem = self._command_problem(frame)
990
+ if problem is not None:
991
+ return problem
992
+ request = frame.header.get("request")
993
+ command = frame.header.get("command")
994
+ given = frame.header["input"]
995
+ cancel = command == "filter.edit" and given["edit"]["kind"] == "cancel"
996
+ if not cancel and not self._wait_if_busy(command):
997
+ return _request_error(request, "busy", "The scene is busy with a filter change.")
998
+ if command == "filter.edit":
999
+ result = self._filter_edit(given["object"], given["edit"])
1000
+ else:
1001
+ result = self._colour_command(command, given)
1002
+ header = {"type": "command.result", "request": request, "result": result}
1003
+ return Frame(header=header, buffers={})
1004
+
1005
+ def _filter_edit(self, object_id: str, edit: dict[str, Any]) -> dict[str, Any]:
1006
+ """Apply one filter edit and return the result dict.
1007
+
1008
+ ``add`` makes an off filter. Its kind is ``"values"`` for a ``referenced`` or
1009
+ ``boolean`` array, and ``"range"`` for other arrays. The ``set_*`` edits change
1010
+ a filter that exists. ``remove`` deletes a filter. ``cancel`` ends the busy time.
1011
+ An edit that changes a filter starts the busy time.
1012
+ """
1013
+ kind = edit["kind"]
1014
+ if kind == "cancel":
1015
+ with self._state_lock:
1016
+ self._busy_until = 0.0
1017
+ return {"status": "done"}
1018
+ array = edit["array"]
1019
+ with self._state_lock:
1020
+ entries = {
1021
+ e.get("name"): e
1022
+ for e in self.objects[object_id].header.get("data") or []
1023
+ if isinstance(e, dict)
1024
+ }
1025
+ entry = entries.get(array)
1026
+ filters = self._filters.setdefault(object_id, {})
1027
+ if kind == "add":
1028
+ if entry is None:
1029
+ return {"status": "refused", "text": f"The object has no array {array!r}."}
1030
+ if entry.get("data_type") == "text" or entry.get("association") == "object":
1031
+ return {
1032
+ "status": "refused",
1033
+ "text": f"The array {array!r} cannot have a filter.",
1034
+ }
1035
+ by_values = entry.get("data_type") in _FIXED_COLOUR_TYPES
1036
+ filters[array] = {
1037
+ "kind": "values" if by_values else "range",
1038
+ "on": False,
1039
+ "minimum": None,
1040
+ "maximum": None,
1041
+ "keep_nan": False,
1042
+ "values": [],
1043
+ "exclude": False,
1044
+ }
1045
+ elif kind == "remove":
1046
+ if filters.pop(array, None) is None:
1047
+ return {"status": "done"}
1048
+ else:
1049
+ state = filters.get(array)
1050
+ if state is None:
1051
+ return {"status": "refused", "text": f"The array {array!r} has no filter."}
1052
+ if kind == "set_range":
1053
+ if state["kind"] != "range":
1054
+ return {
1055
+ "status": "refused",
1056
+ "text": f"The array {array!r} has no range filter.",
1057
+ }
1058
+ try:
1059
+ state["minimum"] = float(edit["min"])
1060
+ state["maximum"] = float(edit["max"])
1061
+ except ValueError:
1062
+ return {"status": "refused", "text": "The range is not a number."}
1063
+ state["keep_nan"] = edit["keep_nan"]
1064
+ elif kind == "set_values":
1065
+ if state["kind"] != "values":
1066
+ return {
1067
+ "status": "refused",
1068
+ "text": f"The array {array!r} has no values filter.",
1069
+ }
1070
+ state["values"] = list(edit["values"])
1071
+ elif kind == "set_on":
1072
+ state["on"] = edit["on"]
1073
+ else:
1074
+ state["exclude"] = edit["exclude"]
1075
+ if self.protocol_minor < 20:
1076
+ self._busy_until = time.monotonic() + self.filter_delay
1077
+ return {"status": "done"}
1078
+
1079
+ def _filter_counts(self, object_id: str, array: str) -> tuple[int, int]:
1080
+ """Return ``(passing, total)`` for the array ``array`` of an object.
1081
+
1082
+ The count uses the filters that are on and that have the association of the
1083
+ array. A range filter keeps ``minimum <= v <= maximum``, and NaN only if
1084
+ ``keep_nan`` is set. A values filter keeps the listed codes, or all other
1085
+ codes if ``exclude`` is set.
1086
+ """
1087
+ with self._state_lock:
1088
+ stored = self.objects[object_id]
1089
+ entries = {
1090
+ e.get("name"): e for e in stored.header.get("data") or [] if isinstance(e, dict)
1091
+ }
1092
+ filters = copy.deepcopy(self._filters.get(object_id, {}))
1093
+ buffers = stored.buffers
1094
+ entry = entries[array]
1095
+ total = int(buffers[entry["buffer"]].shape[0])
1096
+ keep = np.ones(total, dtype=bool)
1097
+ for name, state in filters.items():
1098
+ other = entries.get(name)
1099
+ if not state["on"] or other is None:
1100
+ continue
1101
+ if other.get("association") != entry.get("association"):
1102
+ continue
1103
+ values = buffers[other["buffer"]]
1104
+ if state["kind"] == "range":
1105
+ passed = (values >= state["minimum"]) & (values <= state["maximum"])
1106
+ if state["keep_nan"]:
1107
+ passed = passed | np.isnan(values)
1108
+ else:
1109
+ passed = np.isin(values, state["values"])
1110
+ if state["exclude"]:
1111
+ passed = ~passed
1112
+ keep &= passed
1113
+ return int(keep.sum()), total
1114
+
1115
+ def _build(self, conn: socket.socket, reader: _Reader, request: object) -> str:
1116
+ """Send ``command.progress`` frames for one filter build.
1117
+
1118
+ The method sends a frame about every 0.1 s and reads a possible
1119
+ ``command.cancel`` between them. It returns ``"cancelled"`` on cancel,
1120
+ ``"stopped"`` when ``filter_stop_after`` ends the wait, and ``"done"`` at
1121
+ the end of the build.
1122
+ """
1123
+ version = protocol.TOOL_PROTOCOL_VERSION
1124
+ stop = self.filter_stop_after
1125
+ if stop is not None and stop >= self.filter_delay:
1126
+ stop = None
1127
+ started = time.monotonic()
1128
+ fraction = 0.0
1129
+ while True:
1130
+ progress = {
1131
+ "type": "command.progress",
1132
+ "request": request,
1133
+ "fraction": fraction,
1134
+ "text": "filter.edit",
1135
+ }
1136
+ _send(conn, _encode(Frame(header=progress, buffers={}), version))
1137
+ if fraction >= 1.0:
1138
+ return "done"
1139
+ end = self.filter_delay if stop is None else stop
1140
+ wait = min(0.1, end - (time.monotonic() - started))
1141
+ if wait > 0:
1142
+ time.sleep(wait)
1143
+ if self._cancelled(conn, reader, request):
1144
+ return "cancelled"
1145
+ elapsed = time.monotonic() - started
1146
+ if stop is not None and elapsed >= stop:
1147
+ return "stopped"
1148
+ fraction = min(1.0, elapsed / self.filter_delay)
1149
+
1150
+ def _filter_request(self, data: bytes) -> Frame | None:
1151
+ """Return the frame if ``data`` is a ``filter.edit`` that this viewer builds in steps.
1152
+
1153
+ The method also keeps the frame in ``tool_requests``. It returns ``None`` below
1154
+ protocol 1.20 and for other messages.
1155
+ """
1156
+ if self.protocol_minor < 20:
1157
+ return None
1158
+ try:
1159
+ frame = protocol.decode_frame(data)
1160
+ except ProtocolError:
1161
+ return None
1162
+ if frame.header.get("type") != "command.run":
1163
+ return None
1164
+ if frame.header.get("command") != "filter.edit":
1165
+ return None
1166
+ with self._state_lock:
1167
+ self.tool_requests.append(frame)
1168
+ return frame
1169
+
1170
+ def _stream_filter(self, conn: socket.socket, reader: _Reader, frame: Frame) -> None:
1171
+ """Run one ``filter.edit`` and send ``command.progress`` frames during a build.
1172
+
1173
+ A build runs when the edit is ``set_range``, ``set_values``, ``set_exclude`` or
1174
+ ``set_on``, the filter is on after the edit and ``filter_delay`` is above 0. On
1175
+ ``command.cancel``, the method restores the filters of the object and sends
1176
+ ``cancelled``. If ``filter_stop_after`` is shorter than the build, the result is
1177
+ ``{"status": "done", "state": "building"}`` at that time. At the end of a build,
1178
+ and for an edit with no build, the result has ``passing`` and ``total``.
1179
+ """
1180
+ version = protocol.TOOL_PROTOCOL_VERSION
1181
+ request = frame.header.get("request")
1182
+ problem = self._command_problem(frame)
1183
+ if problem is not None:
1184
+ _send(conn, _encode(problem, version))
1185
+ return
1186
+ given = frame.header["input"]
1187
+ object_id = given["object"]
1188
+ edit = given["edit"]
1189
+ with self._state_lock:
1190
+ before = copy.deepcopy(self._filters.get(object_id))
1191
+ result = self._filter_edit(object_id, edit)
1192
+ on = False
1193
+ if result["status"] == "done" and edit["kind"].startswith("set_"):
1194
+ with self._state_lock:
1195
+ on = self._filters[object_id][edit["array"]]["on"]
1196
+ # ``set_on`` always gives the count. Other edits give it only if the filter is on.
1197
+ if result["status"] == "done" and (on or edit["kind"] == "set_on"):
1198
+ array = edit["array"]
1199
+ outcome = "done"
1200
+ if on and self.filter_delay > 0:
1201
+ outcome = self._build(conn, reader, request)
1202
+ if outcome == "cancelled":
1203
+ with self._state_lock:
1204
+ if before is None:
1205
+ self._filters.pop(object_id, None)
1206
+ else:
1207
+ self._filters[object_id] = before
1208
+ error = _request_error(request, "cancelled", "The client cancelled the request.")
1209
+ _send(conn, _encode(error, version))
1210
+ return
1211
+ if outcome == "stopped":
1212
+ result = {"status": "done", "state": "building"}
1213
+ else:
1214
+ passing, total = self._filter_counts(object_id, array)
1215
+ result = {"status": "done", "passing": passing, "total": total}
1216
+ header = {"type": "command.result", "request": request, "result": result}
1217
+ _send(conn, _encode(Frame(header=header, buffers={}), version))
1218
+
1219
+ def _colour_command(self, command: str, given: dict[str, Any]) -> dict[str, Any]:
1220
+ """Run one colour command and return its result dict."""
1221
+ object_id = given["object"] if command == "colour.set_scale" else given["id"]
1222
+ with self._state_lock:
1223
+ stored = self.objects[object_id]
1224
+ state = self._colouring.setdefault(
1225
+ object_id,
1226
+ {
1227
+ "array": None,
1228
+ "colour_map": None,
1229
+ "range": None,
1230
+ "scale": "linear",
1231
+ "plain": None,
1232
+ },
1233
+ )
1234
+ entries = {
1235
+ e.get("name"): e for e in stored.header.get("data") or [] if isinstance(e, dict)
1236
+ }
1237
+ if command == "colour.set_active":
1238
+ array = given.get("array")
1239
+ if array is not None and array not in entries:
1240
+ return {
1241
+ "status": "refused",
1242
+ "text": f"The object {object_id!r} has no array {array!r}.",
1243
+ }
1244
+ state["array"] = array
1245
+ elif command == "colour.clear_range":
1246
+ state["range"] = None
1247
+ elif command == "object.set_colour":
1248
+ colour = given["colour"]
1249
+ state["plain"] = None if colour is None else list(colour)
1250
+ else:
1251
+ active = entries.get(state["array"])
1252
+ if active is not None and active.get("data_type") in _FIXED_COLOUR_TYPES:
1253
+ return {
1254
+ "status": "refused",
1255
+ "text": f"The array {state['array']!r} has a fixed colouring.",
1256
+ }
1257
+ if command == "colour.set_map":
1258
+ if self.protocol_minor >= 18 and given["name"] not in _COLOUR_MAPS:
1259
+ return {
1260
+ "status": "refused",
1261
+ "text": f"The colour map {given['name']!r} is not known.",
1262
+ }
1263
+ state["colour_map"] = given["name"]
1264
+ elif command == "colour.set_range":
1265
+ try:
1266
+ state["range"] = (float(given["min"]), float(given["max"]))
1267
+ except ValueError:
1268
+ return {"status": "refused", "text": "The range is not a number."}
1269
+ else:
1270
+ state["scale"] = given["scale"]
1271
+ return {"status": "done"}
1272
+
1273
+ def _selection_get(self, request: object) -> Frame:
1274
+ """Return the ``selection.result`` frame for ``selection.get``."""
1275
+ header: dict[str, Any] = {"type": "selection.result", "request": request, "entries": []}
1276
+ buffers: dict[str, np.ndarray] = {}
1277
+ with self._state_lock:
1278
+ current = self._selection
1279
+ if current is not None:
1280
+ header["object"] = current["object"]
1281
+ header["revision"] = current["revision"]
1282
+ for kind in ("cells", "nodes"):
1283
+ values = current[kind]
1284
+ if values is not None:
1285
+ header["entries"].append(
1286
+ {"kind": kind, "count": int(values.size), "indices": kind}
1287
+ )
1288
+ buffers[kind] = np.asarray(values, dtype=np.uint32)
1289
+ return Frame(header=header, buffers=buffers)
1290
+
1291
+ def _selection_set(self, frame: Frame) -> Frame:
1292
+ """Check and keep a selection. Return the reply to ``selection.set``."""
1293
+ header = frame.header
1294
+ request = header.get("request")
1295
+ object_id = header.get("object")
1296
+ entries = header.get("entries")
1297
+ if not isinstance(entries, list):
1298
+ return _request_error(request, "invalid_input", "The entries are missing.", "entries")
1299
+ kinds: dict[str, np.ndarray] = {}
1300
+ for item in entries:
1301
+ name = item.get("indices") if isinstance(item, dict) else None
1302
+ array = frame.buffers.get(name) if isinstance(name, str) else None
1303
+ if array is None or array.dtype != np.dtype("uint32") or array.ndim != 1:
1304
+ return _request_error(
1305
+ request, "invalid_input", "An entry needs a u32 buffer of indices.", "indices"
1306
+ )
1307
+ kinds[item.get("kind")] = array.astype(np.int64)
1308
+ with self._state_lock:
1309
+ problem = self._selection_problem(object_id, header.get("revision"), kinds)
1310
+ if problem is not None:
1311
+ return _request_error(request, "invalid_input", problem[1], problem[0])
1312
+ self._store_selection(object_id, kinds)
1313
+ revision = self.objects[object_id].header.get("revision", 1)
1314
+ result: dict[str, Any] = {
1315
+ "type": "selection.result",
1316
+ "request": request,
1317
+ "object": object_id,
1318
+ "revision": revision,
1319
+ "entries": [
1320
+ {"kind": kind, "count": int(np.unique(values).size)}
1321
+ for kind, values in kinds.items()
1322
+ ],
1323
+ }
1324
+ return Frame(header=result, buffers={})
1325
+
1326
+ def _fetch_frames(self, frame: Frame) -> Iterator[Frame]:
1327
+ """Yield the reply frames of ``object.fetch``.
1328
+
1329
+ The frames are the ``object.header`` frame, the ``object.part`` frames of each
1330
+ array in order (each followed by ``command.progress`` if there is more than one
1331
+ part), and the ``object.end`` frame. An unknown id gives one ``request.error``.
1332
+ """
1333
+ request = frame.header.get("request")
1334
+ object_id = frame.header.get("id")
1335
+ with self._state_lock:
1336
+ stored = self.objects.get(object_id) if isinstance(object_id, str) else None
1337
+ if stored is None:
1338
+ header = None
1339
+ buffers: dict[str, np.ndarray] = {}
1340
+ else:
1341
+ header = dict(stored.header, buffers=[])
1342
+ header["data"] = [
1343
+ {"offsets": None, "value_map": None, "colour_map": None, **entry}
1344
+ for entry in stored.header.get("data") or []
1345
+ ]
1346
+ buffers = dict(stored.buffers)
1347
+ if header is None:
1348
+ yield _request_error(
1349
+ request, "invalid_input", f"The object {object_id!r} is not in the scene.", "id"
1350
+ )
1351
+ return
1352
+ step = max(8, self.part_bytes // 8 * 8)
1353
+ raw = {
1354
+ name: np.ascontiguousarray(array)
1355
+ .astype(array.dtype.newbyteorder("<"), copy=False)
1356
+ .tobytes()
1357
+ for name, array in buffers.items()
1358
+ }
1359
+ total = sum(-(-len(data) // step) for data in raw.values())
1360
+ arrays = [
1361
+ {
1362
+ "name": name,
1363
+ "dtype": _PROTOCOL_DTYPES[array.dtype.name],
1364
+ "shape": [int(n) for n in array.shape],
1365
+ }
1366
+ for name, array in buffers.items()
1367
+ ]
1368
+ yield Frame(
1369
+ header={
1370
+ "type": "object.header",
1371
+ "request": request,
1372
+ "origin": list(self.origin),
1373
+ "crs": self.crs,
1374
+ "object": header,
1375
+ "arrays": arrays,
1376
+ },
1377
+ buffers={},
1378
+ )
1379
+ sent = 0
1380
+ for name, data in raw.items():
1381
+ for offset in range(0, len(data), step):
1382
+ chunk = data[offset : offset + step]
1383
+ sent += 1
1384
+ yield Frame(
1385
+ header={
1386
+ "type": "object.part",
1387
+ "request": request,
1388
+ "array": name,
1389
+ "offset": offset,
1390
+ "bytes": len(chunk),
1391
+ },
1392
+ buffers={"part": np.frombuffer(chunk, dtype=np.uint8)},
1393
+ )
1394
+ if total > 1:
1395
+ progress = {
1396
+ "type": "command.progress",
1397
+ "request": request,
1398
+ "fraction": sent / total,
1399
+ "text": f"Part {sent} of {total}",
1400
+ }
1401
+ yield Frame(header=progress, buffers={})
1402
+ yield Frame(header={"type": "object.end", "request": request, "parts": total}, buffers={})
1403
+
1404
+ def _stream_fetch(self, conn: socket.socket, reader: _Reader, frame: Frame) -> None:
1405
+ """Send the reply to ``object.fetch`` and read between the parts.
1406
+
1407
+ After the header and after each part, the method waits at most 0.001 s for a
1408
+ message (an object without parts has the header only). If it is a
1409
+ ``command.cancel`` with the same request, it sends ``cancelled`` and stops.
1410
+ """
1411
+ request = frame.header.get("request")
1412
+ for reply in self._fetch_frames(frame):
1413
+ _send(conn, _encode(reply, protocol.TOOL_PROTOCOL_VERSION))
1414
+ if reply.header["type"] not in ("object.header", "object.part"):
1415
+ continue
1416
+ if self.fetch_delay:
1417
+ time.sleep(self.fetch_delay)
1418
+ if self._cancelled(conn, reader, request):
1419
+ error = _request_error(request, "cancelled", "The client cancelled the request.")
1420
+ _send(conn, _encode(error, protocol.TOOL_PROTOCOL_VERSION))
1421
+ return
1422
+
1423
+ @staticmethod
1424
+ def _cancelled(conn: socket.socket, reader: _Reader, request: object) -> bool:
1425
+ """Return whether a ``command.cancel`` for ``request`` arrives within 0.001 s.
1426
+
1427
+ A message that is not a ``command.cancel`` is kept in ``reader.deferred``.
1428
+ The viewer handles it after the current work, as a real viewer does. A
1429
+ ``command.cancel`` for another request is dropped.
1430
+ """
1431
+ previous = conn.gettimeout()
1432
+ conn.settimeout(0.001)
1433
+ try:
1434
+ data = reader.message()
1435
+ except (TimeoutError, BlockingIOError):
1436
+ return False
1437
+ finally:
1438
+ conn.settimeout(previous)
1439
+ if data is None:
1440
+ raise _Closed
1441
+ try:
1442
+ header = protocol.decode_frame(data).header
1443
+ except ProtocolError:
1444
+ reader.deferred.append(data)
1445
+ return False
1446
+ if header.get("type") != "command.cancel":
1447
+ reader.deferred.append(data)
1448
+ return False
1449
+ return header.get("request") == request
1450
+
1451
+ # -- server -------------------------------------------------------------
1452
+
1453
+ def _serve(self) -> None:
1454
+ """Accept connections, each in its own thread."""
1455
+ while True:
1456
+ try:
1457
+ conn, _ = self._server.accept()
1458
+ except OSError:
1459
+ return
1460
+ with self._lock:
1461
+ self._connections.add(conn)
1462
+ threading.Thread(target=self._connection, args=(conn,), daemon=True).start()
1463
+
1464
+ def _connection(self, conn: socket.socket) -> None:
1465
+ """Run one connection until it ends."""
1466
+ is_data = False
1467
+ try:
1468
+ opened = self._handshake(conn)
1469
+ if opened is None:
1470
+ return
1471
+ path, reader = opened
1472
+ if path.split("?")[0] == "/tool":
1473
+ self._run(conn, reader, tool=True)
1474
+ return
1475
+ with self._lock:
1476
+ busy = self._data_connections > 0
1477
+ if not busy:
1478
+ self._data_connections += 1
1479
+ is_data = True
1480
+ if busy:
1481
+ refusal = _error("busy", "Another client is connected.")
1482
+ _send(conn, _encode(refusal))
1483
+ conn.sendall(bytes([0x88, 0]))
1484
+ self._drain(conn)
1485
+ return
1486
+ conn.settimeout(self.heartbeat_timeout)
1487
+ self._run(conn, reader, tool=False)
1488
+ except (_Closed, OSError):
1489
+ pass
1490
+ finally:
1491
+ if is_data:
1492
+ with self._lock:
1493
+ self._data_connections -= 1
1494
+ with self._lock:
1495
+ self._connections.discard(conn)
1496
+ try:
1497
+ conn.close()
1498
+ except OSError:
1499
+ pass
1500
+
1501
+ @staticmethod
1502
+ def _drain(conn: socket.socket) -> None:
1503
+ """Stop sending, then read until the peer closes or 0.5 s pass.
1504
+
1505
+ This stops a reset from the system that would destroy the last frames.
1506
+ """
1507
+ try:
1508
+ conn.shutdown(socket.SHUT_WR)
1509
+ conn.settimeout(0.5)
1510
+ while conn.recv(65536):
1511
+ pass
1512
+ except OSError:
1513
+ pass
1514
+
1515
+ def _handshake(self, conn: socket.socket) -> tuple[str, _Reader] | None:
1516
+ """Read the HTTP upgrade request. Return the path and a reader, or ``None``."""
1517
+ data = b""
1518
+ while b"\r\n\r\n" not in data:
1519
+ chunk = conn.recv(4096)
1520
+ if not chunk:
1521
+ return None
1522
+ data += chunk
1523
+ head, _, rest = data.partition(b"\r\n\r\n")
1524
+ lines = head.decode("latin-1").split("\r\n")
1525
+ parts = lines[0].split(" ")
1526
+ path = parts[1] if len(parts) > 1 else "/"
1527
+ headers = {
1528
+ k.strip().lower(): v.strip() for k, _, v in (line.partition(":") for line in lines[1:])
1529
+ }
1530
+ if headers.get("authorization") != f"Bearer {self.token}":
1531
+ conn.sendall(b"HTTP/1.1 401 Unauthorized\r\nContent-Length: 0\r\n\r\n")
1532
+ return None
1533
+ key = headers.get("sec-websocket-key")
1534
+ if key is None:
1535
+ conn.sendall(b"HTTP/1.1 400 Bad Request\r\nContent-Length: 0\r\n\r\n")
1536
+ return None
1537
+ accept = base64.b64encode(hashlib.sha1(key.encode() + _GUID).digest()).decode()
1538
+ conn.sendall(
1539
+ (
1540
+ "HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\n"
1541
+ f"Connection: Upgrade\r\nSec-WebSocket-Accept: {accept}\r\n\r\n"
1542
+ ).encode()
1543
+ )
1544
+ return path, _Reader(conn, rest)
1545
+
1546
+ def _fetch_request(self, data: bytes) -> Frame | None:
1547
+ """Return the frame if ``data`` is an ``object.fetch`` that this viewer supports.
1548
+
1549
+ The method also keeps the frame in ``tool_requests``.
1550
+ """
1551
+ if self.protocol_minor < 18:
1552
+ return None
1553
+ try:
1554
+ frame = protocol.decode_frame(data)
1555
+ except ProtocolError:
1556
+ return None
1557
+ if frame.header.get("type") != "object.fetch":
1558
+ return None
1559
+ with self._state_lock:
1560
+ self.tool_requests.append(frame)
1561
+ return frame
1562
+
1563
+ def _run(self, conn: socket.socket, reader: _Reader, tool: bool) -> None:
1564
+ """Read messages and send the replies.
1565
+
1566
+ The method handles the messages in ``reader.deferred`` first, in order.
1567
+ """
1568
+ while True:
1569
+ data = reader.deferred.pop(0) if reader.deferred else reader.message()
1570
+ if data is None:
1571
+ return
1572
+ if tool:
1573
+ fetch = self._fetch_request(data)
1574
+ if fetch is not None:
1575
+ self._stream_fetch(conn, reader, fetch)
1576
+ continue
1577
+ edit = self._filter_request(data)
1578
+ if edit is not None:
1579
+ self._stream_filter(conn, reader, edit)
1580
+ continue
1581
+ for reply in self.tool_frame(data):
1582
+ _send(conn, _encode(reply, protocol.TOOL_PROTOCOL_VERSION))
1583
+ else:
1584
+ for reply in self.accept_frame(data):
1585
+ _send(conn, _encode(reply))
1586
+ if self.read_delay:
1587
+ time.sleep(self.read_delay)