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/__init__.py ADDED
@@ -0,0 +1,61 @@
1
+ """loop-link: send geoscience data to the LoopConnect viewer."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from .commands import ColourSettings, FilterResult
6
+ from .errors import (
7
+ BusyError,
8
+ CancelledError,
9
+ InvalidInputError,
10
+ LoopLinkError,
11
+ MissingExtraError,
12
+ MissingFeatureError,
13
+ NoViewerError,
14
+ ObjectTooLargeError,
15
+ Refusal,
16
+ StaleRevisionError,
17
+ TokenError,
18
+ UnsupportedObjectError,
19
+ ViewerClosedError,
20
+ ViewerRefusedError,
21
+ )
22
+ from .fetch import FetchResult
23
+ from .objects import BlockModel, Categorical, Drillhole, Lines, Points, Surface, TetraMesh, Vectors
24
+ from .push import PushResult, push_objects
25
+ from .selection import Selection, SelectionWatcher
26
+ from .version import __version__
27
+ from .viewer import InventoryEntry, Viewer
28
+
29
+ __all__ = [
30
+ "BlockModel",
31
+ "BusyError",
32
+ "CancelledError",
33
+ "Categorical",
34
+ "ColourSettings",
35
+ "Drillhole",
36
+ "FetchResult",
37
+ "FilterResult",
38
+ "InvalidInputError",
39
+ "InventoryEntry",
40
+ "Lines",
41
+ "LoopLinkError",
42
+ "MissingExtraError",
43
+ "MissingFeatureError",
44
+ "NoViewerError",
45
+ "ObjectTooLargeError",
46
+ "Points",
47
+ "PushResult",
48
+ "Refusal",
49
+ "Selection",
50
+ "SelectionWatcher",
51
+ "StaleRevisionError",
52
+ "Surface",
53
+ "TetraMesh",
54
+ "TokenError",
55
+ "UnsupportedObjectError",
56
+ "Vectors",
57
+ "Viewer",
58
+ "ViewerClosedError",
59
+ "ViewerRefusedError",
60
+ "push_objects",
61
+ ]
@@ -0,0 +1,436 @@
1
+ """A small WebSocket client for the link to the viewer.
2
+
3
+ It uses the standard library only, because some host applications do not ship a
4
+ WebSocket package for every platform. It does what the link needs: one
5
+ connection with an ``Authorization`` header, binary messages in both
6
+ directions, and the control frames (ping, pong, close). It does not do TLS.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import base64
12
+ import hashlib
13
+ import os
14
+ import socket
15
+ import struct
16
+ import time
17
+
18
+ import numpy as np
19
+
20
+ from loop_link.errors import LoopLinkError, NoViewerError, TokenError
21
+ from loop_link.protocol import MAX_FRAME_BYTES, MAX_HEADER_BYTES
22
+
23
+ _GUID = b"258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
24
+
25
+ OP_CONTINUATION = 0x0
26
+ OP_TEXT = 0x1
27
+ OP_BINARY = 0x2
28
+ OP_CLOSE = 0x8
29
+ OP_PING = 0x9
30
+ OP_PONG = 0xA
31
+
32
+ # The largest incoming message: one protocol frame, which is a header and a body.
33
+ MAX_INCOMING_BYTES: int = MAX_FRAME_BYTES + MAX_HEADER_BYTES
34
+ _HANDSHAKE_MAX_BYTES = 16 * 1024
35
+ # Time for the rest of a frame after its first bytes arrived
36
+ _FRAME_TIMEOUT = 10.0
37
+ # Time to send one frame. A receive can leave a short timeout on the socket,
38
+ # so each send sets this first.
39
+ _SEND_TIMEOUT = 60.0
40
+ # The smallest socket timeout: a timeout of zero makes the socket non-blocking.
41
+ _MIN_WAIT = 1e-3
42
+ # The size of one chunk for the mask. It must be a multiple of 4.
43
+ _MASK_CHUNK_BYTES = 1024 * 1024
44
+
45
+
46
+ class WebSocketError(LoopLinkError):
47
+ """The connection failed, or the server broke the protocol."""
48
+
49
+
50
+ class WebSocketClosed(WebSocketError):
51
+ """The server closed the connection."""
52
+
53
+
54
+ def _mask(data: bytes | bytearray, key: bytes) -> bytes | bytearray:
55
+ """Apply the WebSocket mask to data.
56
+
57
+ The function works in chunks, so the peak memory is about two times the
58
+ size of the data.
59
+
60
+ Parameters
61
+ ----------
62
+ data : bytes or bytearray
63
+ The bytes to mask or unmask.
64
+ key : bytes
65
+ The 4-byte mask key.
66
+
67
+ Returns
68
+ -------
69
+ bytes or bytearray
70
+ The data after the XOR with the repeated key.
71
+ """
72
+ size = len(data)
73
+ if not size:
74
+ return data
75
+ source = np.frombuffer(data, dtype=np.uint8)
76
+ result = bytearray(size)
77
+ target = np.frombuffer(result, dtype=np.uint8)
78
+ key_array = np.frombuffer(key, dtype=np.uint8)
79
+ # The chunk size is a multiple of 4, so the key stays aligned between chunks.
80
+ # Make the pattern only as long as the data needs, so small frames stay cheap.
81
+ pattern = np.tile(key_array, (min(size, _MASK_CHUNK_BYTES) + 3) // 4)
82
+ for start in range(0, size, _MASK_CHUNK_BYTES):
83
+ end = min(start + _MASK_CHUNK_BYTES, size)
84
+ np.bitwise_xor(source[start:end], pattern[: end - start], out=target[start:end])
85
+ return result
86
+
87
+
88
+ class WebSocketClient:
89
+ """One client connection. Not thread safe: use it from one thread.
90
+
91
+ Parameters
92
+ ----------
93
+ sock : socket.socket
94
+ A connected socket. Use :meth:`connect` to make a client.
95
+
96
+ Attributes
97
+ ----------
98
+ closed : bool
99
+ True after the connection is closed.
100
+ """
101
+
102
+ def __init__(self, sock: socket.socket) -> None:
103
+ self._sock = sock
104
+ self._buffer = b""
105
+ self._partial = False
106
+ self._fragmenting = False
107
+ self._fragment_opcode = OP_BINARY
108
+ self._fragments = bytearray()
109
+ self.closed = False
110
+
111
+ @classmethod
112
+ def connect(
113
+ cls,
114
+ host: str,
115
+ port: int,
116
+ *,
117
+ token: str = "",
118
+ timeout: float = 5.0,
119
+ path: str = "/",
120
+ ) -> WebSocketClient:
121
+ """Open the connection and do the handshake.
122
+
123
+ Parameters
124
+ ----------
125
+ host : str
126
+ The host name or address of the viewer.
127
+ port : int
128
+ The TCP port of the viewer.
129
+ token : str, optional
130
+ The access token. It is sent as ``Authorization: Bearer <token>``.
131
+ timeout : float, optional
132
+ The time in seconds to wait for the TCP connection.
133
+ path : str, optional
134
+ The path of the WebSocket request.
135
+
136
+ Returns
137
+ -------
138
+ WebSocketClient
139
+ The connected client.
140
+
141
+ Raises
142
+ ------
143
+ NoViewerError
144
+ If the TCP connection is refused or times out.
145
+ TokenError
146
+ If the viewer answers with HTTP 401.
147
+ WebSocketError
148
+ If the handshake fails for another reason.
149
+ """
150
+ try:
151
+ sock = socket.create_connection((host, port), timeout=timeout)
152
+ except OSError as error:
153
+ raise NoViewerError(f"Cannot connect to a viewer at {host}:{port}: {error}") from error
154
+ try:
155
+ sock.setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)
156
+ client = cls(sock)
157
+ client._handshake(host, port, token, path)
158
+ except BaseException:
159
+ sock.close()
160
+ raise
161
+ return client
162
+
163
+ def _handshake(self, host: str, port: int, token: str, path: str) -> None:
164
+ """Send the upgrade request and check the answer.
165
+
166
+ Parameters
167
+ ----------
168
+ host : str
169
+ The host name for the ``Host`` header.
170
+ port : int
171
+ The port for the ``Host`` header.
172
+ token : str
173
+ The access token. An empty string sends no ``Authorization`` header.
174
+ path : str
175
+ The path of the request.
176
+ """
177
+ key = base64.b64encode(os.urandom(16))
178
+ lines = [
179
+ f"GET {path} HTTP/1.1",
180
+ f"Host: {host}:{port}",
181
+ "Upgrade: websocket",
182
+ "Connection: Upgrade",
183
+ f"Sec-WebSocket-Key: {key.decode()}",
184
+ "Sec-WebSocket-Version: 13",
185
+ ]
186
+ if token:
187
+ lines.append(f"Authorization: Bearer {token}")
188
+ try:
189
+ self._sock.sendall(("\r\n".join(lines) + "\r\n\r\n").encode("ascii"))
190
+ data = b""
191
+ while b"\r\n\r\n" not in data:
192
+ chunk = self._sock.recv(4096)
193
+ if not chunk:
194
+ raise WebSocketError("The viewer closed the connection during the handshake.")
195
+ data += chunk
196
+ if len(data) > _HANDSHAKE_MAX_BYTES:
197
+ raise WebSocketError("The handshake answer is too long.")
198
+ except OSError as error:
199
+ raise WebSocketError(f"The handshake failed: {error}") from error
200
+ head, _, rest = data.partition(b"\r\n\r\n")
201
+ self._buffer = rest
202
+ status_line, *header_lines = head.decode("latin-1").split("\r\n")
203
+ parts = status_line.split(" ", 2)
204
+ status = parts[1] if len(parts) > 1 else ""
205
+ if status == "401":
206
+ raise TokenError("The viewer refused the token. Check the token of the link.")
207
+ if status != "101":
208
+ raise WebSocketError(f"The viewer refused the connection: {status_line}")
209
+ headers = {}
210
+ for line in header_lines:
211
+ name, _, value = line.partition(":")
212
+ headers[name.strip().lower()] = value.strip()
213
+ expected = base64.b64encode(hashlib.sha1(key + _GUID).digest()).decode()
214
+ if headers.get("sec-websocket-accept") != expected:
215
+ raise WebSocketError("The server did not answer as a WebSocket server.")
216
+
217
+ # -- sending ------------------------------------------------------------
218
+
219
+ def _send_frame(self, opcode: int, payload: bytes) -> None:
220
+ """Send one masked frame.
221
+
222
+ Parameters
223
+ ----------
224
+ opcode : int
225
+ The frame opcode.
226
+ payload : bytes
227
+ The frame body, before masking.
228
+ """
229
+ length = len(payload)
230
+ head = bytearray([0x80 | opcode])
231
+ if length < 126:
232
+ head.append(0x80 | length)
233
+ elif length < 1 << 16:
234
+ head.append(0x80 | 126)
235
+ head += struct.pack(">H", length)
236
+ else:
237
+ head.append(0x80 | 127)
238
+ head += struct.pack(">Q", length)
239
+ key = os.urandom(4)
240
+ try:
241
+ self._sock.settimeout(_SEND_TIMEOUT)
242
+ self._sock.sendall(bytes(head) + key)
243
+ self._sock.sendall(_mask(payload, key))
244
+ except OSError as error:
245
+ # This includes a timeout: part of the frame can be sent, so the stream is broken.
246
+ self._abort()
247
+ raise WebSocketError(f"Cannot send to the viewer: {error}") from error
248
+
249
+ def send_binary(self, data: bytes) -> None:
250
+ """Send one binary message.
251
+
252
+ Parameters
253
+ ----------
254
+ data : bytes
255
+ The message body.
256
+
257
+ Raises
258
+ ------
259
+ WebSocketClosed
260
+ If the connection is already closed.
261
+ WebSocketError
262
+ If the send fails. The connection is then closed.
263
+ """
264
+ self._check_open()
265
+ self._send_frame(OP_BINARY, data)
266
+
267
+ # -- receiving ----------------------------------------------------------
268
+
269
+ def _read_exactly(self, count: int) -> bytes:
270
+ """Read an exact number of bytes from the buffer and the socket.
271
+
272
+ Parameters
273
+ ----------
274
+ count : int
275
+ The number of bytes to read.
276
+
277
+ Returns
278
+ -------
279
+ bytes
280
+ The bytes that were read.
281
+ """
282
+ while len(self._buffer) < count:
283
+ chunk = self._sock.recv(65536)
284
+ if not chunk:
285
+ self.closed = True
286
+ raise WebSocketClosed("The viewer closed the connection.")
287
+ self._buffer += chunk
288
+ data, self._buffer = self._buffer[:count], self._buffer[count:]
289
+ return data
290
+
291
+ def _read_frame(self, wait: float | None) -> tuple[bool, int, bytes]:
292
+ """Read one frame.
293
+
294
+ Parameters
295
+ ----------
296
+ wait : float or None
297
+ The time to wait for the first bytes of the frame.
298
+
299
+ Returns
300
+ -------
301
+ tuple of (bool, int, bytes)
302
+ The FIN flag, the opcode and the unmasked body.
303
+ """
304
+ # The wait applies to the start of a frame only. A frame that started
305
+ # is read to the end, so a timeout cannot leave half a frame behind.
306
+ self._sock.settimeout(wait)
307
+ first, second = self._read_exactly(2)
308
+ self._partial = True
309
+ self._sock.settimeout(_FRAME_TIMEOUT)
310
+ fin, opcode = bool(first & 0x80), first & 0x0F
311
+ length = second & 0x7F
312
+ if length == 126:
313
+ (length,) = struct.unpack(">H", self._read_exactly(2))
314
+ elif length == 127:
315
+ (length,) = struct.unpack(">Q", self._read_exactly(8))
316
+ if first & 0x70:
317
+ self._abort()
318
+ raise WebSocketError("The viewer sent a frame with a reserved bit set.")
319
+ if opcode >= OP_CLOSE and length > 125:
320
+ self._abort()
321
+ raise WebSocketError("The viewer sent a control frame that is too long.")
322
+ if length > MAX_INCOMING_BYTES:
323
+ self._abort()
324
+ raise WebSocketError("The viewer sent a message that is too large.")
325
+ key = self._read_exactly(4) if second & 0x80 else None
326
+ payload = self._read_exactly(length)
327
+ return fin, opcode, _mask(payload, key) if key else payload
328
+
329
+ def receive(self, timeout: float) -> bytes | None:
330
+ """Return the next binary message.
331
+
332
+ Ping frames get a pong. A text message is skipped. A binary message in
333
+ parts is joined.
334
+
335
+ Parameters
336
+ ----------
337
+ timeout : float
338
+ The time in seconds to wait for a message to start.
339
+
340
+ Returns
341
+ -------
342
+ bytes or None
343
+ The message body, or None if nothing arrives in ``timeout`` seconds.
344
+ The socket stays usable after a timeout.
345
+
346
+ Raises
347
+ ------
348
+ WebSocketClosed
349
+ If the viewer closes the connection or sends a close frame.
350
+ WebSocketError
351
+ If a message is too large, the stream breaks, or a read fails.
352
+ """
353
+ self._check_open()
354
+ deadline = time.monotonic() + timeout
355
+ try:
356
+ while True:
357
+ self._partial = False
358
+ wait = max(deadline - time.monotonic(), _MIN_WAIT)
359
+ fin, opcode, payload = self._read_frame(wait)
360
+ if opcode == OP_PING:
361
+ self._send_frame(OP_PONG, payload)
362
+ elif opcode == OP_PONG:
363
+ continue
364
+ elif opcode == OP_CLOSE:
365
+ self.closed = True
366
+ try:
367
+ self._send_frame(OP_CLOSE, payload[:2])
368
+ except WebSocketError:
369
+ pass
370
+ self._close_socket()
371
+ raise WebSocketClosed("The viewer closed the connection.")
372
+ else:
373
+ if opcode == OP_CONTINUATION:
374
+ if not self._fragmenting:
375
+ self._abort()
376
+ raise WebSocketError("The viewer sent an unexpected continuation.")
377
+ else:
378
+ if self._fragmenting:
379
+ self._abort()
380
+ raise WebSocketError("The viewer sent a new message too early.")
381
+ self._fragment_opcode = opcode
382
+ self._fragments = bytearray()
383
+ self._fragments += payload
384
+ if len(self._fragments) > MAX_INCOMING_BYTES:
385
+ self._abort()
386
+ raise WebSocketError("The viewer sent a message that is too large.")
387
+ self._fragmenting = not fin
388
+ if fin:
389
+ message = bytes(self._fragments)
390
+ self._fragments = bytearray()
391
+ if self._fragment_opcode == OP_BINARY:
392
+ return message
393
+ except (TimeoutError, BlockingIOError) as error:
394
+ if not self._partial:
395
+ # The state of a message in parts stays: a later call goes on with it.
396
+ return None
397
+ # The bytes of the frame that were read are gone, so the next read
398
+ # would start in the middle of a frame.
399
+ self._abort()
400
+ raise WebSocketError("The viewer stopped in the middle of a message.") from error
401
+ except OSError as error:
402
+ self._abort()
403
+ raise WebSocketError(f"Cannot read from the viewer: {error}") from error
404
+
405
+ def _check_open(self) -> None:
406
+ """Raise ``WebSocketClosed`` if the connection is closed."""
407
+ if self.closed:
408
+ raise WebSocketClosed("The connection is closed.")
409
+
410
+ def _close_socket(self) -> None:
411
+ """Close the socket and ignore errors."""
412
+ try:
413
+ self._sock.close()
414
+ except OSError:
415
+ pass
416
+
417
+ def _abort(self) -> None:
418
+ """Close the socket without a close frame: the stream is broken."""
419
+ self.closed = True
420
+ try:
421
+ self._sock.close()
422
+ except OSError:
423
+ pass
424
+
425
+ def close(self) -> None:
426
+ """Close the connection. It is safe to call it more than one time."""
427
+ if not self.closed:
428
+ self.closed = True
429
+ try:
430
+ self._send_frame(OP_CLOSE, struct.pack(">H", 1000))
431
+ except WebSocketError:
432
+ pass
433
+ try:
434
+ self._sock.close()
435
+ except OSError:
436
+ pass
@@ -0,0 +1,51 @@
1
+ """Adapters that turn outside objects into loop_link scene objects."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import Any, get_args
6
+
7
+ from loop_link.errors import InvalidInputError
8
+ from loop_link.objects import SceneObject
9
+
10
+ _ACCEPTED_INPUTS = (
11
+ "Accepted inputs: loop_link objects (Points, Vectors, Lines, Surface, BlockModel, "
12
+ "TetraMesh, Drillhole); pyvista meshes and grids; LoopStructural Surface and "
13
+ "StructuredGrid; pandas tables for drillholes "
14
+ "(use loop_link.adapters.pandas.drillholes_from_pandas)."
15
+ )
16
+
17
+
18
+ def convert(obj: Any, **hints: Any) -> SceneObject: # noqa: ANN401
19
+ """Convert an input object to a loop_link scene object.
20
+
21
+ Parameters
22
+ ----------
23
+ obj : Any
24
+ A loop_link object, a pyvista mesh or grid, or a LoopStructural object.
25
+ **hints : Any
26
+ Options for the pyvista adapter.
27
+
28
+ Returns
29
+ -------
30
+ SceneObject
31
+ ``obj`` itself when it is a scene object, else the converted object.
32
+
33
+ Raises
34
+ ------
35
+ loop_link.errors.InvalidInputError
36
+ The input type is not accepted.
37
+ ImportError
38
+ The adapter module for the input type is not available.
39
+ """
40
+ if isinstance(obj, get_args(SceneObject)):
41
+ return obj
42
+ package = type(obj).__module__.split(".", 1)[0]
43
+ if package == "pyvista":
44
+ from loop_link.adapters.pyvista import from_pyvista
45
+
46
+ return from_pyvista(obj, **hints)
47
+ if package == "loop_common":
48
+ from loop_link.adapters.loopstructural import from_loopstructural
49
+
50
+ return from_loopstructural(obj)
51
+ raise InvalidInputError(_ACCEPTED_INPUTS)
@@ -0,0 +1,83 @@
1
+ """Adapter that turns LoopStructural geometry objects into loop_link scene objects."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import sys
6
+ from typing import Any
7
+
8
+ import numpy as np
9
+
10
+ from loop_link.errors import InvalidInputError, MissingExtraError
11
+ from loop_link.objects import BlockModel, SceneObject, Surface
12
+
13
+
14
+ def from_loopstructural(obj: Any) -> SceneObject: # noqa: ANN401
15
+ """Convert a LoopStructural Surface or StructuredGrid to a scene object.
16
+
17
+ The coordinates stay in world coordinates. No other transform is applied.
18
+
19
+ Parameters
20
+ ----------
21
+ obj : Any
22
+ A ``loop_common.geometry.Surface`` or ``loop_common.geometry.StructuredGrid``.
23
+
24
+ Returns
25
+ -------
26
+ SceneObject
27
+ A loop_link ``Surface`` for a Surface, or a ``BlockModel`` for a StructuredGrid.
28
+
29
+ Raises
30
+ ------
31
+ loop_link.errors.InvalidInputError
32
+ The input is not a Surface or a StructuredGrid.
33
+ loop_link.errors.MissingExtraError
34
+ The ``loop_common`` package is not installed.
35
+ """
36
+ from loop_link.adapters import _ACCEPTED_INPUTS
37
+
38
+ module = sys.modules.get("loop_common.geometry")
39
+ if module is None:
40
+ try:
41
+ import loop_common.geometry as module
42
+ except ImportError as error:
43
+ raise MissingExtraError("loopstructural") from error
44
+ if isinstance(obj, module.Surface):
45
+ return Surface(
46
+ vertices=obj.vertices,
47
+ triangles=obj.triangles,
48
+ properties=dict(obj.properties or {}),
49
+ cell_properties=dict(obj.cell_properties or {}),
50
+ )
51
+ if isinstance(obj, module.StructuredGrid):
52
+ return BlockModel(
53
+ origin=obj.origin,
54
+ cell_sizes=obj.step_vector,
55
+ cells=obj.nsteps_cells,
56
+ properties=_flatten(obj.properties),
57
+ cell_properties=_flatten(obj.cell_properties),
58
+ )
59
+ raise InvalidInputError(_ACCEPTED_INPUTS)
60
+
61
+
62
+ def _flatten(properties: dict[str, Any] | None) -> dict[str, Any]:
63
+ """Return the grid properties as 1-D arrays in x-fastest order.
64
+
65
+ ``StructuredGrid.vtk()`` reshapes each property to ``(n, -1)`` with ``order="F"``,
66
+ so a property can be a grid of shape ``(nx, ny, nz)`` or have more than one value
67
+ for each node, for example a vector of shape ``(n, 3)``. A grid is flattened in
68
+ x-fastest order. Each column of a 2-D array becomes one property with the name
69
+ ``"<name>_<column>"``. A 2-D array with one column keeps its name.
70
+ """
71
+ result: dict[str, Any] = {}
72
+ for name, values in (properties or {}).items():
73
+ array = np.asarray(values)
74
+ if array.ndim == 3:
75
+ array = array.ravel(order="F")
76
+ if array.ndim == 2 and array.shape[1] == 1:
77
+ array = array[:, 0]
78
+ if array.ndim == 2:
79
+ for column in range(array.shape[1]):
80
+ result[f"{name}_{column}"] = array[:, column]
81
+ continue
82
+ result[name] = array
83
+ return result