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,164 @@
1
+ """Convert between vectors and orientation angles.
2
+
3
+ Convention: x is east, y is north, z is up. All angles are in degrees.
4
+ A plane has an upward normal. A lineation is an axis that points down.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import numpy as np
10
+
11
+ from loop_link.errors import InvalidInputError
12
+
13
+ __all__ = [
14
+ "directions_to_lineation",
15
+ "lineation_to_directions",
16
+ "normals_to_orientation",
17
+ "orientation_to_normals",
18
+ ]
19
+
20
+
21
+ def _unit_vectors(vectors: object, name: str) -> np.ndarray:
22
+ """Return the input as unit vectors with shape (n, 3).
23
+
24
+ Parameters
25
+ ----------
26
+ vectors : array-like
27
+ Vectors with shape (n, 3) or (3,).
28
+ name : str
29
+ The name of the input. The name is used in error messages.
30
+
31
+ Returns
32
+ -------
33
+ numpy.ndarray
34
+ Unit vectors with shape (n, 3).
35
+
36
+ Raises
37
+ ------
38
+ InvalidInputError
39
+ If the shape is wrong, or a vector is zero-length or not finite.
40
+ """
41
+ try:
42
+ arr = np.asarray(vectors, dtype=float)
43
+ except (TypeError, ValueError) as exc:
44
+ raise InvalidInputError(f"The {name} must be numbers. Check the input.") from exc
45
+ arr = np.atleast_2d(arr)
46
+ if arr.ndim != 2 or arr.shape[1] != 3:
47
+ raise InvalidInputError(f"The {name} must have shape (n, 3) or (3,). Check the input.")
48
+ if not np.all(np.isfinite(arr)):
49
+ raise InvalidInputError(f"The {name} must be finite numbers. Check the input.")
50
+ lengths = np.linalg.norm(arr, axis=1)
51
+ if not np.all(np.isfinite(lengths)) or np.any(lengths == 0.0):
52
+ raise InvalidInputError(f"The {name} must not have a zero-length vector. Check the input.")
53
+ return arr / lengths[:, None]
54
+
55
+
56
+ def _angles(x: np.ndarray, y: np.ndarray) -> np.ndarray:
57
+ """Return the azimuth of (x, y) in degrees, in [0, 360).
58
+
59
+ The azimuth is 0.0 when x and y are both zero.
60
+ """
61
+ flat = (x == 0.0) & (y == 0.0)
62
+ # Adding 0.0 turns -0.0 into 0.0.
63
+ azimuth = np.degrees(np.arctan2(np.where(flat, 0.0, x), np.where(flat, 1.0, y))) % 360.0 + 0.0
64
+ # A tiny negative angle can round to 360.0 after the modulo.
65
+ azimuth = np.where(azimuth >= 360.0, 0.0, azimuth)
66
+ return azimuth
67
+
68
+
69
+ def normals_to_orientation(normals: object) -> tuple[np.ndarray, np.ndarray]:
70
+ """Convert plane normals to dip direction and dip.
71
+
72
+ A downward normal is flipped to point up before the conversion.
73
+
74
+ Parameters
75
+ ----------
76
+ normals : array-like
77
+ Normal vectors with shape (n, 3) or (3,).
78
+
79
+ Returns
80
+ -------
81
+ dip_direction : numpy.ndarray
82
+ Dip direction in degrees, in [0, 360).
83
+ dip : numpy.ndarray
84
+ Dip in degrees, in [0, 90].
85
+
86
+ Raises
87
+ ------
88
+ InvalidInputError
89
+ If a vector is zero-length or not finite.
90
+ """
91
+ n = _unit_vectors(normals, "normals")
92
+ n = np.where(n[:, 2:3] < 0.0, -n, n)
93
+ dip = np.degrees(np.arccos(np.clip(n[:, 2], -1.0, 1.0)))
94
+ dip_direction = _angles(n[:, 0], n[:, 1])
95
+ return dip_direction, dip
96
+
97
+
98
+ def directions_to_lineation(directions: object) -> tuple[np.ndarray, np.ndarray]:
99
+ """Convert line directions to trend and plunge.
100
+
101
+ An upward direction is flipped to point down before the conversion.
102
+
103
+ Parameters
104
+ ----------
105
+ directions : array-like
106
+ Direction vectors with shape (n, 3) or (3,).
107
+
108
+ Returns
109
+ -------
110
+ trend : numpy.ndarray
111
+ Trend in degrees, in [0, 360).
112
+ plunge : numpy.ndarray
113
+ Plunge in degrees, in [0, 90].
114
+
115
+ Raises
116
+ ------
117
+ InvalidInputError
118
+ If a vector is zero-length or not finite.
119
+ """
120
+ d = _unit_vectors(directions, "directions")
121
+ d = np.where(d[:, 2:3] > 0.0, -d, d)
122
+ plunge = np.degrees(np.arcsin(np.clip(-d[:, 2], -1.0, 1.0)))
123
+ trend = _angles(d[:, 0], d[:, 1])
124
+ return trend, plunge
125
+
126
+
127
+ def orientation_to_normals(dip_direction: object, dip: object) -> np.ndarray:
128
+ """Convert dip direction and dip to upward unit normals.
129
+
130
+ Parameters
131
+ ----------
132
+ dip_direction : array-like
133
+ Dip direction in degrees.
134
+ dip : array-like
135
+ Dip in degrees.
136
+
137
+ Returns
138
+ -------
139
+ numpy.ndarray
140
+ Unit normals with shape (n, 3).
141
+ """
142
+ a = np.radians(np.atleast_1d(np.asarray(dip_direction, dtype=float)))
143
+ d = np.radians(np.atleast_1d(np.asarray(dip, dtype=float)))
144
+ return np.column_stack((np.sin(d) * np.sin(a), np.sin(d) * np.cos(a), np.cos(d) + 0.0 * a))
145
+
146
+
147
+ def lineation_to_directions(trend: object, plunge: object) -> np.ndarray:
148
+ """Convert trend and plunge to downward unit direction vectors.
149
+
150
+ Parameters
151
+ ----------
152
+ trend : array-like
153
+ Trend in degrees.
154
+ plunge : array-like
155
+ Plunge in degrees.
156
+
157
+ Returns
158
+ -------
159
+ numpy.ndarray
160
+ Unit direction vectors with shape (n, 3).
161
+ """
162
+ t = np.radians(np.atleast_1d(np.asarray(trend, dtype=float)))
163
+ p = np.radians(np.atleast_1d(np.asarray(plunge, dtype=float)))
164
+ return np.column_stack((np.cos(p) * np.sin(t), np.cos(p) * np.cos(t), -np.sin(p) + 0.0 * t))
loop_link/protocol.py ADDED
@@ -0,0 +1,235 @@
1
+ """The binary frame codec of the loop_link protocol.
2
+
3
+ A message is one binary frame. All numbers are little-endian::
4
+
5
+ [u32 header_len][JSON header, UTF-8][buffer 0][buffer 1]...
6
+
7
+ The header lists the buffers in order. This module uses only numpy and the
8
+ standard library.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ import json
14
+ import math
15
+ import struct
16
+ from collections.abc import Sequence
17
+ from dataclasses import dataclass
18
+ from typing import Any
19
+
20
+ import numpy as np
21
+
22
+ from .errors import LoopLinkError
23
+
24
+ PROTOCOL_VERSION: dict[str, int] = {"major": 1, "minor": 14}
25
+ TOOL_PROTOCOL_VERSION: dict[str, int] = {"major": 1, "minor": 18}
26
+ CANCEL_PROTOCOL_VERSION: dict[str, int] = {"major": 1, "minor": 11}
27
+ # The version of the commands.list and command.run frames.
28
+ COMMAND_PROTOCOL_VERSION: dict[str, int] = {"major": 1, "minor": 11}
29
+
30
+ # The largest frame that is allowed, in bytes.
31
+ MAX_FRAME_BYTES: int = 256 * 1024 * 1024
32
+ # The largest JSON header that is allowed, in bytes.
33
+ MAX_HEADER_BYTES: int = 1024 * 1024
34
+ # The largest object that is allowed, in bytes. The encoder in encode.py uses it.
35
+ MAX_OBJECT_BYTES: int = 2 * 1024**3
36
+ # Beyond this distance from the origin an f32 coordinate is not exact to 1 mm.
37
+ F32_LIMIT: float = 4000.0
38
+
39
+ _LENGTH = struct.Struct("<I")
40
+
41
+ _DTYPE_NAMES: dict[str, str] = {
42
+ np.dtype("<f4").str: "f32",
43
+ np.dtype("<f8").str: "f64",
44
+ np.dtype("<u4").str: "u32",
45
+ np.dtype("<i4").str: "i32",
46
+ np.dtype("u1").str: "u8",
47
+ }
48
+ _NAME_DTYPES: dict[str, np.dtype] = {
49
+ "f32": np.dtype("<f4"),
50
+ "f64": np.dtype("<f8"),
51
+ "u32": np.dtype("<u4"),
52
+ "i32": np.dtype("<i4"),
53
+ "u8": np.dtype("u1"),
54
+ }
55
+
56
+
57
+ class ProtocolError(LoopLinkError):
58
+ """A frame cannot be written or read."""
59
+
60
+
61
+ @dataclass(frozen=True)
62
+ class Frame:
63
+ """A decoded frame.
64
+
65
+ Parameters
66
+ ----------
67
+ header : dict
68
+ The JSON header of the frame.
69
+ buffers : dict of str to numpy.ndarray
70
+ The arrays of the frame, by name. Each array has the shape from the header.
71
+ """
72
+
73
+ header: dict[str, Any]
74
+ buffers: dict[str, np.ndarray]
75
+
76
+
77
+ def encode_frame(
78
+ header: dict[str, Any],
79
+ buffers: Sequence[tuple[str, np.ndarray]] = (),
80
+ *,
81
+ version: dict[str, int] | None = None,
82
+ ) -> bytes:
83
+ """Return the frame for a header and its named buffers.
84
+
85
+ The function adds ``version`` and ``buffers`` to the header.
86
+
87
+ Parameters
88
+ ----------
89
+ header : dict
90
+ The header fields. The function does not change this dict.
91
+ buffers : sequence of (str, numpy.ndarray)
92
+ The named arrays. The dtype must be f32, f64, u32, i32 or u8.
93
+ version : dict, optional
94
+ The protocol version for the header. The default is ``PROTOCOL_VERSION``.
95
+ The function does not change this dict.
96
+
97
+ Returns
98
+ -------
99
+ bytes
100
+ The frame.
101
+
102
+ Raises
103
+ ------
104
+ ProtocolError
105
+ If a dtype is not supported, or the header or the frame is too large.
106
+ """
107
+ descriptions = []
108
+ payload = []
109
+ for name, array in buffers:
110
+ array = np.ascontiguousarray(array)
111
+ little = array.dtype.newbyteorder("<")
112
+ dtype_name = _DTYPE_NAMES.get(little.str)
113
+ if dtype_name is None:
114
+ raise ProtocolError(
115
+ f"Buffer {name!r} has the type {array.dtype}, which is not supported. "
116
+ "Use f32, f64, u32, i32 or u8."
117
+ )
118
+ descriptions.append({"name": name, "dtype": dtype_name, "shape": list(array.shape)})
119
+ payload.append(array.astype(little, copy=False).tobytes())
120
+ full = dict(header)
121
+ full["version"] = PROTOCOL_VERSION if version is None else dict(version)
122
+ full["buffers"] = descriptions
123
+ header_bytes = json.dumps(full, separators=(",", ":"), allow_nan=False).encode("utf-8")
124
+ if len(header_bytes) > MAX_HEADER_BYTES:
125
+ raise ProtocolError(
126
+ f"The header is {len(header_bytes)} bytes. The limit is {MAX_HEADER_BYTES} bytes."
127
+ )
128
+ total = _LENGTH.size + len(header_bytes) + sum(len(part) for part in payload)
129
+ if total > MAX_FRAME_BYTES:
130
+ raise ProtocolError(
131
+ f"The frame is {total} bytes. The limit is {MAX_FRAME_BYTES} bytes. "
132
+ "Send smaller objects."
133
+ )
134
+ return b"".join([_LENGTH.pack(len(header_bytes)), header_bytes, *payload])
135
+
136
+
137
+ def _read_header(data: bytes) -> tuple[dict[str, Any], int]:
138
+ """Return the header and the offset where the buffers start."""
139
+ if len(data) < _LENGTH.size:
140
+ raise ProtocolError("The frame is shorter than 4 bytes.")
141
+ (length,) = _LENGTH.unpack_from(data, 0)
142
+ if length > MAX_HEADER_BYTES:
143
+ raise ProtocolError(
144
+ f"The header length is {length} bytes. The limit is {MAX_HEADER_BYTES} bytes."
145
+ )
146
+ end = _LENGTH.size + length
147
+ if end > len(data):
148
+ raise ProtocolError("The frame stops inside the header.")
149
+ try:
150
+ header = json.loads(data[_LENGTH.size : end].decode("utf-8"))
151
+ except (ValueError, RecursionError) as error:
152
+ raise ProtocolError(f"The header is not valid JSON: {error}") from error
153
+ if not isinstance(header, dict):
154
+ raise ProtocolError("The header is not a JSON object.")
155
+ return header, end
156
+
157
+
158
+ def decode_header(data: bytes) -> dict[str, Any]:
159
+ """Return the JSON header of a frame. The buffers are ignored.
160
+
161
+ Parameters
162
+ ----------
163
+ data : bytes
164
+ The frame.
165
+
166
+ Returns
167
+ -------
168
+ dict
169
+ The header.
170
+
171
+ Raises
172
+ ------
173
+ ProtocolError
174
+ If the frame is too short or the header is not valid.
175
+ """
176
+ return _read_header(data)[0]
177
+
178
+
179
+ def decode_frame(data: bytes) -> Frame:
180
+ """Return the header and the arrays of a frame.
181
+
182
+ Parameters
183
+ ----------
184
+ data : bytes
185
+ The frame.
186
+
187
+ Returns
188
+ -------
189
+ Frame
190
+ The header and the named arrays.
191
+
192
+ Raises
193
+ ------
194
+ ProtocolError
195
+ If the frame is not valid, or its length does not match the header.
196
+ """
197
+ if len(data) > MAX_FRAME_BYTES:
198
+ raise ProtocolError(
199
+ f"The frame is {len(data)} bytes. The limit is {MAX_FRAME_BYTES} bytes."
200
+ )
201
+ header, offset = _read_header(data)
202
+ descriptions = header.get("buffers", [])
203
+ if not isinstance(descriptions, list):
204
+ raise ProtocolError("The header field 'buffers' is not a list.")
205
+ buffers: dict[str, np.ndarray] = {}
206
+ for entry in descriptions:
207
+ if not isinstance(entry, dict):
208
+ raise ProtocolError(f"A buffer description is not valid: {entry!r}.")
209
+ name = entry.get("name")
210
+ dtype_name = entry.get("dtype")
211
+ raw_shape = entry.get("shape")
212
+ if not isinstance(name, str):
213
+ raise ProtocolError(f"A buffer name is not a string: {name!r}.")
214
+ if name in buffers:
215
+ raise ProtocolError(f"The buffer name {name!r} is used more than once.")
216
+ if not isinstance(dtype_name, str) or dtype_name not in _NAME_DTYPES:
217
+ raise ProtocolError(f"Buffer {name!r} has an unknown dtype: {dtype_name!r}.")
218
+ if not isinstance(raw_shape, list) or any(type(n) is not int or n < 0 for n in raw_shape):
219
+ raise ProtocolError(f"Buffer {name!r} has a shape that is not valid: {raw_shape!r}.")
220
+ dtype = _NAME_DTYPES[dtype_name]
221
+ shape = tuple(raw_shape)
222
+ count = math.prod(shape)
223
+ size = count * dtype.itemsize
224
+ if offset + size > len(data):
225
+ raise ProtocolError(f"The frame stops inside buffer {name!r}.")
226
+ try:
227
+ buffers[name] = np.frombuffer(data, dtype=dtype, count=count, offset=offset).reshape(
228
+ shape
229
+ )
230
+ except ValueError as error:
231
+ raise ProtocolError(f"Buffer {name!r} cannot be read: {error}") from error
232
+ offset += size
233
+ if offset != len(data):
234
+ raise ProtocolError(f"The frame is {len(data)} bytes. The header describes {offset} bytes.")
235
+ return Frame(header=header, buffers=buffers)
loop_link/push.py ADDED
@@ -0,0 +1,166 @@
1
+ """Push many objects to GeoViewer in one call.
2
+
3
+ The module has no Qt code and no module state. The progress callback runs on the
4
+ calling thread.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import threading
10
+ from collections.abc import Callable, Iterable
11
+ from dataclasses import dataclass, field
12
+ from typing import TYPE_CHECKING, Any
13
+
14
+ from loop_link.errors import InvalidInputError, ObjectTooLargeError, Refusal
15
+
16
+ if TYPE_CHECKING:
17
+ from loop_link.viewer import Viewer
18
+
19
+
20
+ _OPTION_KEYS = ("name", "parent")
21
+
22
+
23
+ def _read_options(options: Any) -> dict[str, Any]: # noqa: ANN401
24
+ """Check the options of one item and return them.
25
+
26
+ Parameters
27
+ ----------
28
+ options : Any
29
+ The third part of an item. It must be a dict with the keys ``name`` and
30
+ ``parent`` only.
31
+
32
+ Returns
33
+ -------
34
+ dict
35
+ The same options as a new dict.
36
+
37
+ Raises
38
+ ------
39
+ InvalidInputError
40
+ If ``options`` is not a dict or it has an unknown key.
41
+ """
42
+ if not isinstance(options, dict):
43
+ raise InvalidInputError("The options of an object must be a dict.")
44
+ unknown = sorted(str(key) for key in options if key not in _OPTION_KEYS)
45
+ if unknown:
46
+ raise InvalidInputError(
47
+ f"Unknown options: {', '.join(unknown)}. Use only 'name' and 'parent'."
48
+ )
49
+ return dict(options)
50
+
51
+
52
+ @dataclass
53
+ class PushResult:
54
+ """Result of one call to `push_objects`.
55
+
56
+ Attributes
57
+ ----------
58
+ sent : int
59
+ Number of objects sent to the viewer.
60
+ removed : int
61
+ Number of old objects removed from the viewer.
62
+ refused : list of Refusal
63
+ Messages that the viewer refused.
64
+ skipped : list of tuple of str
65
+ Pairs of object id and reason for each object that was not sent.
66
+ cancelled : bool
67
+ True when the cancel event stopped the push.
68
+ """
69
+
70
+ sent: int = 0
71
+ removed: int = 0
72
+ refused: list[Refusal] = field(default_factory=list)
73
+ skipped: list[tuple[str, str]] = field(default_factory=list)
74
+ cancelled: bool = False
75
+
76
+ def summary(self) -> str:
77
+ """Return a short text that describes the result.
78
+
79
+ Returns
80
+ -------
81
+ str
82
+ The summary text.
83
+ """
84
+ text = f"{self.sent} objects sent to GeoViewer"
85
+ if self.removed:
86
+ text += f", {self.removed} old objects removed"
87
+ if self.skipped:
88
+ text += f", {len(self.skipped)} objects skipped"
89
+ text += "."
90
+ if self.refused:
91
+ text += f" The viewer refused {len(self.refused)} messages."
92
+ return text
93
+
94
+
95
+ def push_objects(
96
+ viewer: Viewer,
97
+ objects: Iterable[tuple[Any, ...]],
98
+ *,
99
+ replace_prefix: str | None = None,
100
+ progress: Callable[[str], None] | None = None,
101
+ cancel: threading.Event | None = None,
102
+ ) -> PushResult:
103
+ """Send objects to the viewer and report the result.
104
+
105
+ Parameters
106
+ ----------
107
+ viewer : Viewer
108
+ The viewer connection. The function connects it when it is not connected.
109
+ objects : iterable of tuple
110
+ Items of the form ``(id, obj)`` or ``(id, obj, options)``. ``options`` is a
111
+ dict with the optional keys ``name`` (display name) and ``parent`` (id of a
112
+ group). An unknown key, or an ``options`` value that is not a dict, skips
113
+ the item.
114
+ replace_prefix : str, optional
115
+ When given, the function removes each old object in the viewer inventory
116
+ whose id starts with this prefix and that this call did not send or skip.
117
+ The function never removes a group (an entry with the type ``Group``).
118
+ The function does not remove old objects when the push is cancelled.
119
+ progress : callable, optional
120
+ Called with a text before each object is sent. It runs on the calling thread.
121
+ cancel : threading.Event, optional
122
+ When this event is set, the push stops before the next object.
123
+
124
+ Returns
125
+ -------
126
+ PushResult
127
+ Counts, skipped objects and refusals.
128
+
129
+ Raises
130
+ ------
131
+ ViewerClosedError
132
+ If the viewer closes during the push.
133
+ BusyError
134
+ If the viewer is busy.
135
+ """
136
+ result = PushResult()
137
+ if not viewer.connected:
138
+ viewer.connect()
139
+ kept_ids: set[str] = set()
140
+ for item in objects:
141
+ object_id, obj = item[0], item[1]
142
+ if cancel is not None and cancel.is_set():
143
+ result.cancelled = True
144
+ break
145
+ if progress is not None:
146
+ progress(f"Sending {object_id}...")
147
+ try:
148
+ options = _read_options(item[2]) if len(item) > 2 else {}
149
+ viewer.send(obj, id=object_id, **options)
150
+ except (InvalidInputError, ObjectTooLargeError) as error:
151
+ result.skipped.append((object_id, str(error)))
152
+ kept_ids.add(object_id)
153
+ continue
154
+ kept_ids.add(object_id)
155
+ result.sent += 1
156
+ if replace_prefix and not result.cancelled:
157
+ for entry in viewer.inventory():
158
+ if (
159
+ entry.id.startswith(replace_prefix)
160
+ and entry.id not in kept_ids
161
+ and entry.object_type != "Group"
162
+ ):
163
+ viewer.remove(entry.id)
164
+ result.removed += 1
165
+ result.refused = viewer.flush(raise_on_refusal=False)
166
+ return result