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 +12 -0
- memseg/__main__.py +5 -0
- memseg/application/__init__.py +7 -0
- memseg/application/compare.py +164 -0
- memseg/application/semantic.py +101 -0
- memseg/application/use_cases.py +108 -0
- memseg/cli.py +518 -0
- memseg/domain/__init__.py +91 -0
- memseg/domain/metrics.py +145 -0
- memseg/domain/models.py +389 -0
- memseg/domain/ports.py +197 -0
- memseg/io/__init__.py +42 -0
- memseg/io/images.py +52 -0
- memseg/io/micrographs.py +199 -0
- memseg/io/previews.py +56 -0
- memseg/io/reports.py +269 -0
- memseg/io/side_by_side.py +86 -0
- memseg/io/sinks.py +71 -0
- memseg/io/sources.py +111 -0
- memseg/py.typed +0 -0
- memseg/registry.py +53 -0
- memseg/segmenters/__init__.py +43 -0
- memseg/segmenters/base.py +49 -0
- memseg/segmenters/components.py +50 -0
- memseg/semantic/__init__.py +38 -0
- memseg/semantic/base.py +27 -0
- memseg/semantic/threshold.py +92 -0
- memseg-0.2.0.dist-info/METADATA +362 -0
- memseg-0.2.0.dist-info/RECORD +32 -0
- memseg-0.2.0.dist-info/WHEEL +4 -0
- memseg-0.2.0.dist-info/entry_points.txt +2 -0
- memseg-0.2.0.dist-info/licenses/LICENSE +21 -0
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,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
|