smlm-view3d 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,24 @@
1
+ """napari-storm's drawing core, without napari: the 3D view of SMLM localizations.
2
+
3
+ - ``smlm_view3d.core``: the localization table, the render planner, the
4
+ renderer contract and the scene; numpy only, with no Qt, napari or VisPy.
5
+ - ``smlm_view3d.particles``: the instanced VisPy billboards
6
+ (``billboard_filter``, ``footprint_shaders``, ``summed_contrast``,
7
+ ``vispy_compat`` and the ``instanced`` prototype) and the plain-VisPy
8
+ backend, ``vispy_renderer.VispyInstancedRenderer``; VisPy and numpy, with no
9
+ napari, and Qt only through VisPy's app.
10
+
11
+ napari-storm depends on this package. Its old names, ``napari_storm.core``,
12
+ ``napari_storm.core.<module>`` and ``napari_storm.napari_particles.<module>``
13
+ for the modules moved here, are these same module objects.
14
+ """
15
+
16
+ from importlib.metadata import PackageNotFoundError
17
+ from importlib.metadata import version as _distribution_version
18
+
19
+ try:
20
+ __version__ = _distribution_version("smlm-view3d")
21
+ except PackageNotFoundError: # running from a source tree without installation
22
+ __version__ = "0.0.0+unknown"
23
+
24
+ __all__ = ["__version__"]
@@ -0,0 +1,199 @@
1
+ """The scientific core: localization data and derived quantities.
2
+
3
+ Level 2 of ``docs/modernization-review.md`` separates the science from the
4
+ application. Everything in this package depends on numpy and the standard
5
+ library only -- **no Qt, no napari, no file I/O** -- so it can be tested
6
+ headlessly and reused outside one dock widget.
7
+
8
+ That boundary is enforced by a test, not by convention: see
9
+ ``_tests/test_core_is_host_free.py``. Adding a Qt or napari import anywhere
10
+ under ``napari_storm.core`` fails the suite.
11
+ """
12
+
13
+ from .bounds import EMPTY, Bounds
14
+ from .dataset_state import (
15
+ AppearanceChanged,
16
+ DatasetState,
17
+ MaskChanged,
18
+ TransformChanged,
19
+ )
20
+ from .dataset_store import (
21
+ BatchCommitted,
22
+ DatasetClosed,
23
+ DatasetOpened,
24
+ DatasetStore,
25
+ StoreCleared,
26
+ )
27
+ from .density import DEFAULT_DENSITY_RADIUS_NM, DENSITY_COLUMN, local_density
28
+ from .focus import (
29
+ DEFAULT_FOCUS_RADIUS_NM,
30
+ DEFAULT_OUTSIDE_OPACITY,
31
+ FocusState,
32
+ focus_weight,
33
+ pivot_on_view_axis,
34
+ point_under_ray,
35
+ )
36
+ from .footprints import (
37
+ BLEND_ADDITIVE,
38
+ BLEND_OPAQUE,
39
+ DEFAULT_MIN_SIZE_PX,
40
+ FOOTPRINT_DISC,
41
+ FOOTPRINT_GAUSSIAN,
42
+ FOOTPRINTS,
43
+ PALETTE,
44
+ Footprint,
45
+ footprint_named,
46
+ )
47
+ from .localization_table import (
48
+ ACTIVE,
49
+ AXES,
50
+ COORDINATE_DTYPE,
51
+ DEFAULT_PHOTON_COLUMN,
52
+ DEFAULT_POSITION_COLUMNS,
53
+ DEFAULT_SIGMA_COLUMNS,
54
+ FILTERED,
55
+ LocalizationTable,
56
+ TableSelection,
57
+ )
58
+ from .metadata import (
59
+ DATA_IN_NM,
60
+ PHOTON_COUNT_PRESENT,
61
+ PIXEL_SIZE_NM,
62
+ SIGMA_PRESENT,
63
+ ZDIM_PRESENT,
64
+ MetadataProvider,
65
+ RecordingMetadataProvider,
66
+ StaticMetadataProvider,
67
+ )
68
+ from .render_planner import DatasetTraits, GaussianSettings, RenderPlanner
69
+ from .renderer import (
70
+ Changed,
71
+ LayerAppearance,
72
+ LocalizationRenderer,
73
+ NullRenderer,
74
+ RenderRequest,
75
+ )
76
+ from .scene import (
77
+ CameraState,
78
+ ColorCodingEntry,
79
+ DatasetEntry,
80
+ ReferenceImageEntry,
81
+ Scene,
82
+ SceneFormatError,
83
+ ViewState,
84
+ drop_edits,
85
+ edits_of,
86
+ load_scene,
87
+ record_edit,
88
+ resolve_source_path,
89
+ save_scene,
90
+ split_lineage,
91
+ split_point,
92
+ )
93
+ from .traces import (
94
+ BUILTIN_COLOR_BY,
95
+ COLOR_BY_PROGRESS,
96
+ COLOR_BY_TIME,
97
+ COLOR_BY_TRACE,
98
+ DEFAULT_TRACE_WIDTH_PX,
99
+ TraceVertices,
100
+ find_trace_column,
101
+ is_trace_column,
102
+ plan_traces,
103
+ trace_spread_is_meaningful,
104
+ )
105
+ from .validation import (
106
+ InvalidLocalizationData,
107
+ non_finite_mask,
108
+ require_positive_maximum,
109
+ sanitize_positive,
110
+ )
111
+ from .world_transform import IDENTITY, WorldTransform
112
+
113
+ __all__ = [
114
+ "ACTIVE",
115
+ "CameraState",
116
+ "ColorCodingEntry",
117
+ "DatasetEntry",
118
+ "ReferenceImageEntry",
119
+ "Scene",
120
+ "SceneFormatError",
121
+ "ViewState",
122
+ "drop_edits",
123
+ "edits_of",
124
+ "load_scene",
125
+ "record_edit",
126
+ "resolve_source_path",
127
+ "save_scene",
128
+ "split_lineage",
129
+ "split_point",
130
+ "DEFAULT_DENSITY_RADIUS_NM",
131
+ "DENSITY_COLUMN",
132
+ "local_density",
133
+ "DEFAULT_FOCUS_RADIUS_NM",
134
+ "DEFAULT_OUTSIDE_OPACITY",
135
+ "FocusState",
136
+ "focus_weight",
137
+ "pivot_on_view_axis",
138
+ "point_under_ray",
139
+ "AXES",
140
+ "FILTERED",
141
+ "TableSelection",
142
+ "COORDINATE_DTYPE",
143
+ "DEFAULT_PHOTON_COLUMN",
144
+ "DEFAULT_POSITION_COLUMNS",
145
+ "DEFAULT_SIGMA_COLUMNS",
146
+ "LocalizationTable",
147
+ "BatchCommitted",
148
+ "DatasetClosed",
149
+ "DatasetOpened",
150
+ "DatasetStore",
151
+ "StoreCleared",
152
+ "MetadataProvider",
153
+ "RecordingMetadataProvider",
154
+ "StaticMetadataProvider",
155
+ "DATA_IN_NM",
156
+ "PHOTON_COUNT_PRESENT",
157
+ "PIXEL_SIZE_NM",
158
+ "SIGMA_PRESENT",
159
+ "ZDIM_PRESENT",
160
+ "LocalizationRenderer",
161
+ "NullRenderer",
162
+ "RenderRequest",
163
+ "InvalidLocalizationData",
164
+ "non_finite_mask",
165
+ "require_positive_maximum",
166
+ "sanitize_positive",
167
+ "Bounds",
168
+ "EMPTY",
169
+ "AppearanceChanged",
170
+ "DatasetState",
171
+ "MaskChanged",
172
+ "TransformChanged",
173
+ "Changed",
174
+ "BLEND_ADDITIVE",
175
+ "BLEND_OPAQUE",
176
+ "DEFAULT_MIN_SIZE_PX",
177
+ "FOOTPRINTS",
178
+ "FOOTPRINT_DISC",
179
+ "FOOTPRINT_GAUSSIAN",
180
+ "Footprint",
181
+ "PALETTE",
182
+ "footprint_named",
183
+ "LayerAppearance",
184
+ "DatasetTraits",
185
+ "GaussianSettings",
186
+ "RenderPlanner",
187
+ "IDENTITY",
188
+ "WorldTransform",
189
+ "BUILTIN_COLOR_BY",
190
+ "COLOR_BY_PROGRESS",
191
+ "COLOR_BY_TIME",
192
+ "COLOR_BY_TRACE",
193
+ "DEFAULT_TRACE_WIDTH_PX",
194
+ "TraceVertices",
195
+ "find_trace_column",
196
+ "is_trace_column",
197
+ "plan_traces",
198
+ "trace_spread_is_meaningful",
199
+ ]
@@ -0,0 +1,81 @@
1
+ """Derived spatial bounds, and the percent-to-absolute mapping over them.
2
+
3
+ These were three lists of two floats mutated in place on
4
+ ``DataToLayerInterface``, with an empty extent spelled ``[inf, -inf]`` and every
5
+ consumer expected to remember that. The arithmetic that maps a slider
6
+ percentage onto an axis is the same arithmetic that the auto-offset removal
7
+ turned out to hinge on (§3.5.1), so it is worth having in one tested place
8
+ rather than inlined at each call site.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ from dataclasses import dataclass
14
+
15
+ import numpy as np
16
+
17
+ __all__ = ["Bounds", "EMPTY"]
18
+
19
+
20
+ @dataclass(frozen=True)
21
+ class Bounds:
22
+ """A closed interval on one axis, in nanometres.
23
+
24
+ An empty interval is ``(inf, -inf)``: the identity for :meth:`union`, which
25
+ is why accumulating extents over datasets can start from it and needs no
26
+ special case for the first one.
27
+ """
28
+
29
+ low: float = np.inf
30
+ high: float = -np.inf
31
+
32
+ @property
33
+ def is_empty(self):
34
+ return not (np.isfinite(self.low) and np.isfinite(self.high))
35
+
36
+ @property
37
+ def span(self):
38
+ return 0.0 if self.is_empty else float(self.high - self.low)
39
+
40
+ @property
41
+ def centre(self):
42
+ return None if self.is_empty else 0.5 * (self.low + self.high)
43
+
44
+ def union(self, other):
45
+ """The smallest interval containing both."""
46
+ if isinstance(other, Bounds):
47
+ low, high = other.low, other.high
48
+ else:
49
+ low, high = other
50
+ return Bounds(min(self.low, low), max(self.high, high))
51
+
52
+ @classmethod
53
+ def of(cls, values):
54
+ """Bounds of a set of values; empty for an empty set."""
55
+ values = np.asarray(values)
56
+ if values.size == 0:
57
+ return EMPTY
58
+ return cls(float(np.min(values)), float(np.max(values)))
59
+
60
+ def percent_to_absolute(self, percent_pair):
61
+ """Map a ``[low%, high%]`` pair onto this interval, in nanometres.
62
+
63
+ ``absolute = low + percent / 100 * (high - low)``.
64
+
65
+ The specialised form ``percent / 100 * high`` that this replaced was
66
+ only correct while every axis had been translated to start at zero --
67
+ the job the auto-offset used to do. An empty interval has nothing to
68
+ map onto, so the percentages come back unchanged rather than becoming
69
+ NaN.
70
+ """
71
+ percent = np.asarray(percent_pair, dtype=float)
72
+ if self.is_empty:
73
+ return percent
74
+ return self.low + percent / 100.0 * self.span
75
+
76
+ def as_tuple(self):
77
+ return (self.low, self.high)
78
+
79
+
80
+ #: The empty interval; the identity for union.
81
+ EMPTY = Bounds()
@@ -0,0 +1,119 @@
1
+ """Per-dataset application state, separated from the localizations themselves.
2
+
3
+ :class:`~napari_storm.core.LocalizationTable` owns the measurements. This owns
4
+ everything the *application* decided about them: what they are called, where
5
+ they sit in world space, and how they are displayed. Both were previously
6
+ scattered — the name on the dataset object, the placement nowhere at all, and
7
+ the appearance inside Qt widget state, where it could not survive the widget or
8
+ be tested without one.
9
+
10
+ State changes announce themselves. A control that moves a slider changes this
11
+ object; whoever draws hears :class:`AppearanceChanged` and acts. That is the
12
+ inversion §4.1 asks for: a change carries what changed, rather than every
13
+ consumer rediscovering global state.
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ from dataclasses import dataclass, field, replace
19
+
20
+ from .bounds import EMPTY, Bounds
21
+ from .renderer import LayerAppearance
22
+ from .world_transform import IDENTITY, WorldTransform
23
+
24
+ __all__ = ["DatasetState", "MaskChanged", "AppearanceChanged", "TransformChanged"]
25
+
26
+
27
+ @dataclass(frozen=True)
28
+ class MaskChanged:
29
+ """Which localizations are drawn changed: a filter, or the render budget."""
30
+
31
+ dataset_id: int
32
+
33
+
34
+ @dataclass(frozen=True)
35
+ class AppearanceChanged:
36
+ """How a dataset is drawn changed. Nothing about the data moved."""
37
+
38
+ dataset_id: int
39
+ appearance: LayerAppearance = None
40
+
41
+
42
+ @dataclass(frozen=True)
43
+ class TransformChanged:
44
+ """Where a dataset sits in world space changed."""
45
+
46
+ dataset_id: int
47
+ transform: WorldTransform = None
48
+
49
+
50
+ @dataclass(frozen=True)
51
+ class DriftChanged:
52
+ dataset_id: int
53
+ positions_only: bool = False
54
+
55
+
56
+ @dataclass(frozen=True)
57
+ class DriftView:
58
+ model: object
59
+ row_times: object
60
+ applied: bool = True
61
+ alpha: float = 1.0
62
+ group: object = None
63
+ scale: tuple = (1.0, 1.0, 1.0)
64
+
65
+ def displacement(self, ids):
66
+ import numpy as np
67
+
68
+ return self.model.evaluate(self.row_times[ids]) * np.asarray(self.scale)
69
+
70
+ def offset(self, ids):
71
+ return (1 - self.alpha) * self.displacement(ids)
72
+
73
+
74
+ @dataclass
75
+ class DatasetState:
76
+ """What the application knows about one loaded dataset.
77
+
78
+ Deliberately not the localizations: this can be copied, compared and
79
+ persisted without dragging a million rows along, which is what makes it a
80
+ plausible basis for the scene format Level 4 has to define.
81
+ """
82
+
83
+ dataset_id: int
84
+ name: str = ""
85
+ drift: DriftView = None
86
+ appearance: LayerAppearance = field(default_factory=LayerAppearance)
87
+ transform: WorldTransform = IDENTITY
88
+ #: Extent per axis in world nanometres, derived from the table and cached
89
+ #: here so consumers do not each recompute it from a million coordinates.
90
+ bounds: dict = field(default_factory=lambda: {"x": EMPTY, "y": EMPTY, "z": EMPTY})
91
+
92
+ def bounds_for(self, axis):
93
+ return self.bounds.get(axis, EMPTY)
94
+
95
+ def merged_bounds(self, axis, other):
96
+ """This dataset's extent on *axis*, widened to include *other*."""
97
+ return self.bounds_for(axis).union(other)
98
+
99
+ def with_appearance(self, **fields):
100
+ """The appearance updated in place; unspecified fields keep their value.
101
+
102
+ Returns the new appearance, so a caller can hand it straight to an
103
+ :class:`AppearanceChanged`.
104
+ """
105
+ changes = {name: value for name, value in fields.items() if value is not None}
106
+ self.appearance = replace(self.appearance, **changes)
107
+ return self.appearance
108
+
109
+ def update_bounds_from(self, table, zdim_present):
110
+ """Recompute the derived extents from a table. Returns the bounds."""
111
+ axes = ("x", "y", "z") if zdim_present else ("x", "y")
112
+ bounds = {"x": EMPTY, "y": EMPTY, "z": EMPTY}
113
+ for axis in axes:
114
+ if not table.has_axis(axis):
115
+ continue
116
+ values = table.coordinate_nm(axis)[table.finite_position_mask()]
117
+ bounds[axis] = Bounds.of(self.transform.apply_axis(axis, values))
118
+ self.bounds = bounds
119
+ return bounds