memseg 0.2.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.
memseg/__init__.py ADDED
@@ -0,0 +1,12 @@
1
+ """memseg: membrane segmentation (semantic and instance) with interchangeable methods.
2
+
3
+ Layers (dependencies point inwards only, see architecture.md):
4
+ memseg.domain models, ports (interfaces) and metrics; numpy only
5
+ memseg.application use cases that orchestrate ports
6
+ memseg.segmenters instance methods (registry + plugins), implementing domain.ports.InstanceSegmenter
7
+ memseg.semantic semantic methods (registry + plugins), implementing domain.ports.SemanticSegmenter
8
+ memseg.io file-system adapters (readers, writers, sources, reports)
9
+ memseg.cli composition root: parses arguments and wires everything together
10
+ """
11
+
12
+ __version__ = "0.2.0"
memseg/__main__.py ADDED
@@ -0,0 +1,5 @@
1
+ import sys
2
+
3
+ from .cli import main
4
+
5
+ sys.exit(main())
@@ -0,0 +1,7 @@
1
+ """Application layer: use cases built only on domain ports."""
2
+
3
+ from .compare import CompareSegmenters, PairSampling
4
+ from .semantic import SegmentMicrographs
5
+ from .use_cases import EvaluateSegmenter, SegmentImages
6
+
7
+ __all__ = ["CompareSegmenters", "EvaluateSegmenter", "PairSampling", "SegmentImages", "SegmentMicrographs"]
@@ -0,0 +1,164 @@
1
+ """Use case: run several segmentation methods on the same images and compare them."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import contextlib
6
+ import time
7
+ from collections.abc import Mapping
8
+ from dataclasses import dataclass, field
9
+
10
+ from ..domain.metrics import match_instances, pair_counts, sample_pixel_pairs, summarize
11
+ from ..domain.models import (
12
+ ComparisonItem,
13
+ ComparisonSummary,
14
+ ImageRef,
15
+ InstanceLabels,
16
+ MembraneMask,
17
+ MethodOutcome,
18
+ MethodSummary,
19
+ PairCounts,
20
+ Status,
21
+ )
22
+ from ..domain.ports import (
23
+ ComparisonListener,
24
+ ComparisonReportWriter,
25
+ ComparisonSink,
26
+ GroundTruthReader,
27
+ ImageSource,
28
+ InstanceSegmenter,
29
+ MaskReader,
30
+ ResultSink,
31
+ )
32
+
33
+
34
+ def _err(e: BaseException) -> str:
35
+ return f"{type(e).__name__}: {e}"
36
+
37
+
38
+ @dataclass
39
+ class PairSampling:
40
+ """Pixel pairs used for the same-instance AUROC (identical pairs for every method)."""
41
+
42
+ n_pairs: int = 20000
43
+ radius: float = 100.0
44
+ seed: int = 0
45
+
46
+
47
+ @dataclass
48
+ class CompareSegmenters:
49
+ """Segment every image with each method, time it, and, when ground truth exists, score it.
50
+
51
+ segmenters: name -> method (order is kept in reports and previews)
52
+ setup_seconds: name -> time spent constructing the method (e.g. loading a network)
53
+ method_sinks: optional name -> sink for that method's label maps
54
+ """
55
+
56
+ segmenters: Mapping[str, InstanceSegmenter]
57
+ source: ImageSource
58
+ reader: MaskReader
59
+ gt_reader: GroundTruthReader | None = None
60
+ method_sinks: Mapping[str, ResultSink] = field(default_factory=dict)
61
+ comparison_sink: ComparisonSink | None = None
62
+ report: ComparisonReportWriter | None = None
63
+ progress: ComparisonListener = field(default_factory=ComparisonListener)
64
+ setup_seconds: Mapping[str, float] = field(default_factory=dict)
65
+ iou_threshold: float = 0.5
66
+ pairs: PairSampling = field(default_factory=PairSampling)
67
+ warmup: bool = False # run each method once on the first image, untimed (GPU/cuDNN start-up)
68
+
69
+ def run(self) -> tuple[list[ComparisonItem], ComparisonSummary]:
70
+ if len(self.segmenters) < 2:
71
+ raise ValueError("comparison needs at least two methods")
72
+ refs = list(self.source)
73
+ names = list(self.segmenters)
74
+ self.progress.start(len(refs), names)
75
+ if self.warmup and refs:
76
+ self._warm(refs[0])
77
+ items = []
78
+ for i, ref in enumerate(refs, 1):
79
+ item = self._one(ref, names)
80
+ items.append(item)
81
+ self.progress.item_done(i, len(refs), item)
82
+ summary = self._summarize(items, names)
83
+ if self.report is not None:
84
+ self.report.write(items, summary)
85
+ self.progress.finished(items, summary)
86
+ return items, summary
87
+
88
+ def _one(self, ref: ImageRef, names: list[str]) -> ComparisonItem:
89
+ item = ComparisonItem(ref=ref)
90
+ try:
91
+ mask = self.reader.read(ref)
92
+ gt = self._read_gt(ref)
93
+ except Exception as e:
94
+ item.error = _err(e)
95
+ return item
96
+ item.shape, item.has_gt = mask.shape, gt is not None
97
+ pa = pb = None
98
+ if gt is not None:
99
+ item.n_gt = gt.n_instances
100
+ pa, pb = sample_pixel_pairs(gt, self.pairs.n_pairs, self.pairs.radius, self.pairs.seed)
101
+ for name in names:
102
+ item.outcomes[name] = self._run_method(name, ref, mask, gt, pa, pb)
103
+ if self.comparison_sink is not None:
104
+ self.comparison_sink.save(item, mask, gt)
105
+ return item
106
+
107
+ def _warm(self, ref: ImageRef) -> None:
108
+ try:
109
+ mask = self.reader.read(ref)
110
+ except Exception:
111
+ return
112
+ for seg in self.segmenters.values():
113
+ with contextlib.suppress(Exception): # the real run records the failure
114
+ seg.segment(mask)
115
+
116
+ def _read_gt(self, ref: ImageRef) -> InstanceLabels | None:
117
+ if self.gt_reader is None or ref.gt_path is None:
118
+ return None
119
+ return self.gt_reader.read(ref)
120
+
121
+ def _run_method(self, name, ref, mask: MembraneMask, gt, pa, pb) -> MethodOutcome:
122
+ t0 = time.perf_counter()
123
+ try:
124
+ result = self.segmenters[name].segment(mask)
125
+ except Exception as e:
126
+ return MethodOutcome(name, Status.FAILED, time.perf_counter() - t0, error=_err(e))
127
+ seconds = time.perf_counter() - t0 # segmentation only, excludes reading and writing
128
+ out = MethodOutcome(name, Status.OK, seconds, result=result)
129
+ if gt is not None:
130
+ out.match = match_instances(gt, result.labels, self.iou_threshold)
131
+ out.pairs = pair_counts(gt, result.labels, pa, pb)
132
+ sink = self.method_sinks.get(name)
133
+ if sink is not None:
134
+ sink.save(ref, result)
135
+ return out
136
+
137
+ def _summarize(self, items: list[ComparisonItem], names: list[str]) -> ComparisonSummary:
138
+ out = []
139
+ for name in names:
140
+ outs = [it.outcomes[name] for it in items if name in it.outcomes]
141
+ ok = [o for o in outs if o.status is Status.OK]
142
+ matches = [o.match for o in ok if o.match is not None]
143
+ pairs = None
144
+ if matches:
145
+ pairs = PairCounts()
146
+ for o in ok:
147
+ if o.pairs is not None:
148
+ pairs = pairs + o.pairs
149
+ total = sum(o.seconds for o in ok)
150
+ out.append(
151
+ MethodSummary(
152
+ method=name,
153
+ description=self.segmenters[name].describe(),
154
+ n_ok=len(ok),
155
+ n_failed=len(outs) - len(ok),
156
+ setup_seconds=self.setup_seconds.get(name, 0.0),
157
+ total_seconds=total,
158
+ mean_seconds=total / len(ok) if ok else 0.0,
159
+ total_instances=sum(o.result.labels.n_instances for o in ok if o.result is not None),
160
+ evaluation=summarize(matches) if matches else None,
161
+ pairs=pairs,
162
+ )
163
+ )
164
+ return ComparisonSummary(methods=out, n_images=len(items), n_with_gt=sum(it.has_gt for it in items))
@@ -0,0 +1,101 @@
1
+ """Semantic segmentation use case: micrograph -> membrane mask [-> instances].
2
+
3
+ Knows nothing about files, networks or a specific method.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ import time
9
+ from dataclasses import dataclass, field
10
+
11
+ from ..domain.metrics import pixel_scores, summarize_semantic
12
+ from ..domain.models import ImageRef, MicrographOutcome, SemanticSummary, Status
13
+ from ..domain.ports import (
14
+ GroundTruthMaskReader,
15
+ ImageSource,
16
+ InstanceSegmenter,
17
+ MicrographListener,
18
+ MicrographReader,
19
+ NullSink,
20
+ ResultSink,
21
+ SemanticReportWriter,
22
+ SemanticSegmenter,
23
+ SemanticSink,
24
+ )
25
+
26
+
27
+ def _describe_error(e: BaseException) -> str:
28
+ return f"{type(e).__name__}: {e}"
29
+
30
+
31
+ @dataclass
32
+ class SegmentMicrographs:
33
+ """For every micrograph: semantic segmentation, then optionally an instance method on its mask.
34
+
35
+ * `instance`: any InstanceSegmenter; it receives the semantic mask (with the micrograph's ref).
36
+ * `gt_reader`: when given, images whose `ref.gt_path` is set are scored against that
37
+ ground-truth membrane mask (pixel IoU / Dice); a summary over the scored images is returned.
38
+ * `semantic_sink` decides "already done" for `skip_existing`.
39
+
40
+ Failures on single images are recorded and do not stop the run.
41
+ """
42
+
43
+ semantic: SemanticSegmenter
44
+ source: ImageSource
45
+ reader: MicrographReader
46
+ instance: InstanceSegmenter | None = None
47
+ semantic_sink: SemanticSink = field(default_factory=NullSink)
48
+ instance_sink: ResultSink = field(default_factory=NullSink)
49
+ gt_reader: GroundTruthMaskReader | None = None
50
+ report: SemanticReportWriter | None = None
51
+ progress: MicrographListener = field(default_factory=MicrographListener)
52
+ skip_existing: bool = False
53
+
54
+ def describe(self) -> str:
55
+ d = self.semantic.describe()
56
+ return d + (f" -> {self.instance.describe()}" if self.instance is not None else "")
57
+
58
+ def run(self) -> tuple[list[MicrographOutcome], SemanticSummary | None]:
59
+ refs = list(self.source)
60
+ self.progress.start(len(refs), f"segment micrographs with {self.describe()}")
61
+ outcomes = []
62
+ for i, ref in enumerate(refs, 1):
63
+ outcome = self._one(ref)
64
+ outcomes.append(outcome)
65
+ self.progress.item_done(i, len(refs), outcome)
66
+ scored = [o.scores for o in outcomes if o.scores is not None]
67
+ summary = summarize_semantic(scored) if scored else None
68
+ if self.report is not None:
69
+ self.report.write(outcomes, summary)
70
+ self.progress.finished(outcomes, summary)
71
+ return outcomes, summary
72
+
73
+ def _one(self, ref: ImageRef) -> MicrographOutcome:
74
+ if self.skip_existing and self.semantic_sink.exists(ref):
75
+ return MicrographOutcome(ref=ref, status=Status.SKIPPED)
76
+ t0 = time.time()
77
+ try:
78
+ image = self.reader.read(ref)
79
+ sem = self.semantic.segment(image)
80
+ if sem.mask.shape != image.shape:
81
+ raise ValueError(f"method returned a {sem.mask.shape} mask for a {image.shape} image")
82
+ sem.mask.ref = ref
83
+ self.semantic_sink.save(ref, sem)
84
+ inst = None
85
+ if self.instance is not None:
86
+ inst = self.instance.segment(sem.mask)
87
+ self.instance_sink.save(ref, inst)
88
+ scores = None
89
+ if self.gt_reader is not None and ref.gt_path is not None:
90
+ scores = pixel_scores(self.gt_reader.read(ref), sem.mask)
91
+ return MicrographOutcome(
92
+ ref=ref,
93
+ status=Status.OK,
94
+ seconds=time.time() - t0,
95
+ shape=image.shape,
96
+ semantic=sem,
97
+ instances=inst,
98
+ scores=scores,
99
+ )
100
+ except Exception as e: # keep going on bad inputs
101
+ return MicrographOutcome(ref=ref, status=Status.FAILED, seconds=time.time() - t0, error=_describe_error(e))
@@ -0,0 +1,108 @@
1
+ """Use cases. They orchestrate ports and know nothing about files, torch or a specific method."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import time
6
+ from dataclasses import dataclass, field
7
+
8
+ from ..domain.metrics import match_instances, summarize
9
+ from ..domain.models import EvaluationSummary, ImageRef, ItemOutcome, Status
10
+ from ..domain.ports import (
11
+ GroundTruthReader,
12
+ ImageSource,
13
+ InstanceSegmenter,
14
+ MaskReader,
15
+ NullSink,
16
+ ProgressListener,
17
+ ReportWriter,
18
+ ResultSink,
19
+ )
20
+
21
+
22
+ def _describe_error(e: BaseException) -> str:
23
+ return f"{type(e).__name__}: {e}"
24
+
25
+
26
+ @dataclass
27
+ class SegmentImages:
28
+ """Segment every image from a source and hand the results to a sink.
29
+
30
+ Failures on single images are recorded and do not stop the run.
31
+ """
32
+
33
+ segmenter: InstanceSegmenter
34
+ source: ImageSource
35
+ reader: MaskReader
36
+ sink: ResultSink = field(default_factory=NullSink)
37
+ report: ReportWriter | None = None
38
+ progress: ProgressListener = field(default_factory=ProgressListener)
39
+ skip_existing: bool = True
40
+
41
+ def run(self) -> list[ItemOutcome]:
42
+ refs = list(self.source)
43
+ self.progress.start(len(refs), f"segment with {self.segmenter.describe()}")
44
+ outcomes = []
45
+ for i, ref in enumerate(refs, 1):
46
+ outcome = self._one(ref)
47
+ outcomes.append(outcome)
48
+ self.progress.item_done(i, len(refs), outcome)
49
+ if self.report is not None:
50
+ self.report.write(outcomes)
51
+ self.progress.finished(outcomes, None)
52
+ return outcomes
53
+
54
+ def _one(self, ref: ImageRef) -> ItemOutcome:
55
+ if self.skip_existing and self.sink.exists(ref):
56
+ return ItemOutcome(ref=ref, status=Status.SKIPPED)
57
+ t0 = time.time()
58
+ try:
59
+ mask = self.reader.read(ref)
60
+ result = self.segmenter.segment(mask)
61
+ self.sink.save(ref, result)
62
+ return ItemOutcome(ref=ref, status=Status.OK, seconds=time.time() - t0, shape=mask.shape, result=result)
63
+ except Exception as e: # keep going on bad inputs
64
+ return ItemOutcome(ref=ref, status=Status.FAILED, seconds=time.time() - t0, error=_describe_error(e))
65
+
66
+
67
+ @dataclass
68
+ class EvaluateSegmenter:
69
+ """Segment images that have ground truth and score them (precision / recall / F1 / IoU).
70
+
71
+ The sink is optional; give one to also keep the predicted label maps.
72
+ """
73
+
74
+ segmenter: InstanceSegmenter
75
+ source: ImageSource
76
+ reader: MaskReader
77
+ gt_reader: GroundTruthReader
78
+ sink: ResultSink = field(default_factory=NullSink)
79
+ report: ReportWriter | None = None
80
+ progress: ProgressListener = field(default_factory=ProgressListener)
81
+ iou_threshold: float = 0.5
82
+
83
+ def run(self) -> tuple[list[ItemOutcome], EvaluationSummary]:
84
+ refs = list(self.source)
85
+ self.progress.start(len(refs), f"evaluate {self.segmenter.describe()}")
86
+ outcomes = []
87
+ for i, ref in enumerate(refs, 1):
88
+ t0 = time.time()
89
+ try:
90
+ if ref.gt_path is None:
91
+ raise ValueError("no ground truth for this image")
92
+ mask = self.reader.read(ref)
93
+ gt = self.gt_reader.read(ref)
94
+ result = self.segmenter.segment(mask)
95
+ self.sink.save(ref, result)
96
+ m = match_instances(gt, result.labels, self.iou_threshold)
97
+ outcome = ItemOutcome(
98
+ ref=ref, status=Status.OK, seconds=time.time() - t0, shape=mask.shape, result=result, match=m
99
+ )
100
+ except Exception as e:
101
+ outcome = ItemOutcome(ref=ref, status=Status.FAILED, seconds=time.time() - t0, error=_describe_error(e))
102
+ outcomes.append(outcome)
103
+ self.progress.item_done(i, len(refs), outcome)
104
+ summary = summarize([o.match for o in outcomes if o.match is not None])
105
+ if self.report is not None:
106
+ self.report.write(outcomes, summary)
107
+ self.progress.finished(outcomes, summary)
108
+ return outcomes, summary