woundscan 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.
- woundscan/__init__.py +6 -0
- woundscan/inference.py +57 -0
- woundscan/measurement.py +59 -0
- woundscan-0.1.0.dist-info/METADATA +141 -0
- woundscan-0.1.0.dist-info/RECORD +8 -0
- woundscan-0.1.0.dist-info/WHEEL +5 -0
- woundscan-0.1.0.dist-info/licenses/LICENSE +26 -0
- woundscan-0.1.0.dist-info/top_level.txt +1 -0
woundscan/__init__.py
ADDED
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
"""Composable wound measurement tools. Research use; no clinical validation."""
|
|
2
|
+
from .measurement import Measurement, measure_mask, reference_scale, body_surface_area
|
|
3
|
+
from .inference import Segmenter
|
|
4
|
+
|
|
5
|
+
__version__ = "0.1.0"
|
|
6
|
+
__all__ = ["Measurement", "measure_mask", "reference_scale", "body_surface_area", "Segmenter"]
|
woundscan/inference.py
ADDED
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
"""Optional ONNX inference matching the repository's Python evaluation recipe."""
|
|
2
|
+
from pathlib import Path
|
|
3
|
+
import numpy as np
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
class Segmenter:
|
|
7
|
+
"""Load a caller-supplied WoundScan-compatible ONNX probability model.
|
|
8
|
+
|
|
9
|
+
Contract: float32 RGB [1,3,256,256] in [0,1], output [1,1,256,256]
|
|
10
|
+
probabilities. No weights or network downloads are included in this package.
|
|
11
|
+
"""
|
|
12
|
+
def __init__(self, model_path):
|
|
13
|
+
path = Path(model_path)
|
|
14
|
+
if not path.is_file():
|
|
15
|
+
raise FileNotFoundError(path)
|
|
16
|
+
try:
|
|
17
|
+
import cv2
|
|
18
|
+
import onnxruntime as ort
|
|
19
|
+
except ImportError as exc:
|
|
20
|
+
raise ImportError('Install optional inference support: pip install "woundscan[inference]"') from exc
|
|
21
|
+
self._cv2 = cv2
|
|
22
|
+
self._session = ort.InferenceSession(str(path), providers=["CPUExecutionProvider"])
|
|
23
|
+
inputs = self._session.get_inputs()
|
|
24
|
+
if len(inputs) != 1 or inputs[0].shape != [1, 3, 256, 256] or inputs[0].type != "tensor(float)":
|
|
25
|
+
raise ValueError("Model must accept one float32 tensor of shape [1,3,256,256]")
|
|
26
|
+
self._input = inputs[0].name
|
|
27
|
+
|
|
28
|
+
def predict(self, rgb, *, tta=True) -> np.ndarray:
|
|
29
|
+
"""Return H x W float32 probabilities from an H x W x 3 uint8 RGB image.
|
|
30
|
+
|
|
31
|
+
TTA averages original, horizontal-flip and vertical-flip probabilities.
|
|
32
|
+
No browser mask smoothing, component filtering or hole filling is applied.
|
|
33
|
+
"""
|
|
34
|
+
image = np.asarray(rgb)
|
|
35
|
+
if image.ndim != 3 or image.shape[2] != 3 or not image.size or image.dtype != np.uint8:
|
|
36
|
+
raise ValueError("rgb must be a nonempty H x W x 3 uint8 array")
|
|
37
|
+
cv2 = self._cv2
|
|
38
|
+
x = cv2.resize(image, (256, 256), interpolation=cv2.INTER_AREA).astype(np.float32) / 255
|
|
39
|
+
x = x.transpose(2, 0, 1)[None]
|
|
40
|
+
def run(a):
|
|
41
|
+
result = self._session.run(None, {self._input: np.ascontiguousarray(a)})[0]
|
|
42
|
+
if result.shape != (1, 1, 256, 256):
|
|
43
|
+
raise ValueError("Model output must have shape [1,1,256,256]")
|
|
44
|
+
p = result[0, 0]
|
|
45
|
+
if not np.isfinite(p).all() or p.min() < 0 or p.max() > 1:
|
|
46
|
+
raise ValueError("Model output must contain probabilities in [0,1]")
|
|
47
|
+
return p
|
|
48
|
+
p = run(x)
|
|
49
|
+
if tta:
|
|
50
|
+
p = (p + run(x[..., ::-1])[:, ::-1] + run(x[:, :, ::-1])[::-1]) / 3
|
|
51
|
+
return cv2.resize(p, (image.shape[1], image.shape[0]), interpolation=cv2.INTER_LINEAR)
|
|
52
|
+
|
|
53
|
+
def segment(self, rgb, *, threshold=0.5, tta=True) -> np.ndarray:
|
|
54
|
+
"""Return a boolean mask using strict probability > threshold."""
|
|
55
|
+
if not np.isfinite(threshold) or not 0 <= threshold <= 1:
|
|
56
|
+
raise ValueError("threshold must be finite and between 0 and 1")
|
|
57
|
+
return self.predict(rgb, tta=tta) > threshold
|
woundscan/measurement.py
ADDED
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
"""Calibrated pixel-cell geometry with explicit units."""
|
|
2
|
+
from dataclasses import asdict, dataclass
|
|
3
|
+
import math
|
|
4
|
+
import numpy as np
|
|
5
|
+
|
|
6
|
+
|
|
7
|
+
def _positive(value, name):
|
|
8
|
+
try:
|
|
9
|
+
value = float(value)
|
|
10
|
+
except (TypeError, ValueError):
|
|
11
|
+
raise ValueError(f"{name} must be a positive finite number") from None
|
|
12
|
+
if not math.isfinite(value) or value <= 0:
|
|
13
|
+
raise ValueError(f"{name} must be a positive finite number")
|
|
14
|
+
return value
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
def reference_scale(reference_pixels: float, reference_mm: float) -> float:
|
|
18
|
+
"""Return millimetres per pixel from a coplanar reference length."""
|
|
19
|
+
return _positive(reference_mm, "reference_mm") / _positive(reference_pixels, "reference_pixels")
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
def body_surface_area(height_cm: float, weight_kg: float) -> float:
|
|
23
|
+
"""Mosteller body surface area, in square metres."""
|
|
24
|
+
return math.sqrt(_positive(height_cm, "height_cm") * _positive(weight_kg, "weight_kg") / 3600)
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
@dataclass(frozen=True)
|
|
28
|
+
class Measurement:
|
|
29
|
+
"""Pixel-cell area/perimeter, including holes and disconnected components."""
|
|
30
|
+
area_mm2: float
|
|
31
|
+
perimeter_mm: float
|
|
32
|
+
foreground_pixels: int
|
|
33
|
+
mm_per_pixel: float
|
|
34
|
+
tbsa_percent: float | None = None
|
|
35
|
+
|
|
36
|
+
def to_dict(self) -> dict:
|
|
37
|
+
"""Return JSON-serializable scalar values."""
|
|
38
|
+
return asdict(self)
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def measure_mask(mask, mm_per_pixel: float, *, height_cm=None, weight_kg=None) -> Measurement:
|
|
42
|
+
"""Measure a nonempty 2D boolean or binary 0/1 mask.
|
|
43
|
+
|
|
44
|
+
Perimeter counts exposed pixel edges, NOT a smooth subpixel contour.
|
|
45
|
+
This lattice perimeter is orientation dependent and differs from the browser
|
|
46
|
+
contour method. Empty foreground is allowed and measures zero.
|
|
47
|
+
"""
|
|
48
|
+
scale = _positive(mm_per_pixel, "mm_per_pixel")
|
|
49
|
+
a = np.asarray(mask)
|
|
50
|
+
if a.ndim != 2 or not a.size or a.dtype.kind not in "buif" or not np.isin(a, [0, 1]).all():
|
|
51
|
+
raise ValueError("mask must be a nonempty 2D array containing only 0 and 1")
|
|
52
|
+
a = np.pad(a.astype(np.int8), 1)
|
|
53
|
+
count = int(a.sum())
|
|
54
|
+
edges = int(np.abs(np.diff(a, axis=0)).sum() + np.abs(np.diff(a, axis=1)).sum())
|
|
55
|
+
if (height_cm is None) != (weight_kg is None):
|
|
56
|
+
raise ValueError("height_cm and weight_kg must be supplied together")
|
|
57
|
+
area = count * scale**2
|
|
58
|
+
tbsa = None if height_cm is None else 100 * area / (body_surface_area(height_cm, weight_kg) * 1_000_000)
|
|
59
|
+
return Measurement(area, edges * scale, count, scale, tbsa)
|
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: woundscan
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Composable calibrated wound-mask measurement and optional ONNX segmentation for research
|
|
5
|
+
Author: Muhammad Allam Rafi, Cindy Rizky Afrilia
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/sharing-123/WoundScan
|
|
8
|
+
Project-URL: Repository, https://github.com/sharing-123/WoundScan
|
|
9
|
+
Project-URL: Issues, https://github.com/sharing-123/WoundScan/issues
|
|
10
|
+
Project-URL: Documentation, https://github.com/sharing-123/WoundScan/blob/main/docs/PYPI_README.md
|
|
11
|
+
Project-URL: OSF registration, https://doi.org/10.17605/OSF.IO/KV3SP
|
|
12
|
+
Project-URL: Zenodo archive, https://doi.org/10.5281/zenodo.24412818
|
|
13
|
+
Keywords: wound,segmentation,medical-imaging,calibration,research
|
|
14
|
+
Classifier: Development Status :: 3 - Alpha
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Operating System :: OS Independent
|
|
17
|
+
Classifier: Topic :: Scientific/Engineering :: Image Processing
|
|
18
|
+
Classifier: Intended Audience :: Science/Research
|
|
19
|
+
Requires-Python: >=3.10
|
|
20
|
+
Description-Content-Type: text/markdown
|
|
21
|
+
License-File: LICENSE
|
|
22
|
+
Requires-Dist: numpy>=1.23
|
|
23
|
+
Provides-Extra: inference
|
|
24
|
+
Requires-Dist: onnxruntime>=1.17; extra == "inference"
|
|
25
|
+
Requires-Dist: opencv-python-headless>=4.8; extra == "inference"
|
|
26
|
+
Provides-Extra: test
|
|
27
|
+
Requires-Dist: pytest>=8; extra == "test"
|
|
28
|
+
Dynamic: license-file
|
|
29
|
+
|
|
30
|
+
# WoundScan for Python
|
|
31
|
+
|
|
32
|
+
Calibrated binary-mask measurements and local ONNX segmentation for research pipelines.
|
|
33
|
+
|
|
34
|
+
Install with `pip install woundscan`. Requires Python 3.10 or later.
|
|
35
|
+
|
|
36
|
+
[Source](https://github.com/sharing-123/WoundScan) | [Issues](https://github.com/sharing-123/WoundScan/issues) | [OSF](https://doi.org/10.17605/OSF.IO/KV3SP) | [Zenodo](https://doi.org/10.5281/zenodo.24412818)
|
|
37
|
+
|
|
38
|
+
## Measure any binary mask
|
|
39
|
+
|
|
40
|
+
```python
|
|
41
|
+
import json
|
|
42
|
+
import numpy as np
|
|
43
|
+
from woundscan import measure_mask, reference_scale
|
|
44
|
+
|
|
45
|
+
mask = np.zeros((100, 100), dtype=bool)
|
|
46
|
+
mask[20:40, 30:60] = True
|
|
47
|
+
scale = reference_scale(reference_pixels=100, reference_mm=10)
|
|
48
|
+
result = measure_mask(mask, scale, height_cm=170, weight_kg=70)
|
|
49
|
+
print(result.area_mm2) # 6.0
|
|
50
|
+
print(result.perimeter_mm) # 10.0
|
|
51
|
+
print(json.dumps(result.to_dict(), indent=2))
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
The API accepts masks from any segmentation model or manual annotation pipeline.
|
|
55
|
+
Measurements use millimetres and square millimetres. Mosteller body surface area
|
|
56
|
+
uses height in centimetres and weight in kilograms. Supply both to calculate
|
|
57
|
+
`tbsa_percent`, otherwise it is `None`. A reference must lie in the wound plane.
|
|
58
|
+
Curved surfaces, perspective and calibration uncertainty affect accuracy.
|
|
59
|
+
|
|
60
|
+
## Optional segmentation
|
|
61
|
+
|
|
62
|
+
Install with `pip install "woundscan[inference]"`.
|
|
63
|
+
|
|
64
|
+
```python
|
|
65
|
+
import cv2
|
|
66
|
+
from woundscan import Segmenter, measure_mask
|
|
67
|
+
|
|
68
|
+
model = Segmenter("/path/to/wound_seg.onnx")
|
|
69
|
+
bgr = cv2.imread("/path/to/image.png")
|
|
70
|
+
if bgr is None:
|
|
71
|
+
raise ValueError("Image could not be loaded")
|
|
72
|
+
rgb = cv2.cvtColor(bgr, cv2.COLOR_BGR2RGB)
|
|
73
|
+
probability = model.predict(rgb)
|
|
74
|
+
mask = model.segment(rgb, threshold=0.5)
|
|
75
|
+
result = measure_mask(mask, mm_per_pixel=0.1)
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
Supply a model you have permission to use. No weights or network downloads are
|
|
79
|
+
included. Inference uses ONNX Runtime CPU, with float32 RGB input [1,3,256,256]
|
|
80
|
+
in [0,1] and probability output [1,1,256,256]. The recipe follows the repository
|
|
81
|
+
Python evaluation script, averaging original, horizontal and vertical flips.
|
|
82
|
+
Set `tta=False` for a single pass. Invalid probabilities and logits are rejected.
|
|
83
|
+
|
|
84
|
+
## API
|
|
85
|
+
|
|
86
|
+
| Function | Result |
|
|
87
|
+
| --- | --- |
|
|
88
|
+
| reference_scale(reference_pixels, reference_mm) | Millimetres per pixel |
|
|
89
|
+
| body_surface_area(height_cm, weight_kg) | Mosteller BSA in square metres |
|
|
90
|
+
| measure_mask(mask, mm_per_pixel, height_cm=None, weight_kg=None) | Immutable Measurement; height and weight are keyword-only |
|
|
91
|
+
| Measurement.to_dict() | JSON-compatible dictionary |
|
|
92
|
+
| Segmenter(model_path).predict(rgb, tta=True) | Original-resolution probability array; tta is keyword-only |
|
|
93
|
+
| Segmenter(model_path).segment(rgb, threshold=0.5, tta=True) | Boolean mask; threshold and tta are keyword-only |
|
|
94
|
+
|
|
95
|
+
Functions compose with notebooks, batch processing and APIs. Import starts no
|
|
96
|
+
server, downloads no models and performs no inference. Model loading occurs only
|
|
97
|
+
when a Segmenter is constructed.
|
|
98
|
+
|
|
99
|
+
## Scope and evidence
|
|
100
|
+
|
|
101
|
+
Version 0.1 provides measurement and optional inference. Browser reconstructive
|
|
102
|
+
planning, tissue analysis, donor mapping and interactive editing remain in the
|
|
103
|
+
GitHub application and are not exported by this Python API.
|
|
104
|
+
|
|
105
|
+
Area counts foreground pixel cells across all components. Perimeter counts
|
|
106
|
+
exposed pixel edges, including holes. This lattice perimeter is orientation
|
|
107
|
+
dependent and differs from the browser's smoothed subpixel contour algorithm.
|
|
108
|
+
Inference does not apply browser smoothing, component removal or hole filling.
|
|
109
|
+
Final masks can therefore differ from browser masks.
|
|
110
|
+
|
|
111
|
+
The repository model evaluation reported Dice 0.827 on 200 validation images and
|
|
112
|
+
0.793 on 160 external images. These describe that evaluation, not a guarantee
|
|
113
|
+
for this package or new photographs. Small punctures and thin abrasions were
|
|
114
|
+
important failure modes. The software is a research prototype without clinical
|
|
115
|
+
validation and must not replace clinical judgement.
|
|
116
|
+
|
|
117
|
+
## Licensing and model rights
|
|
118
|
+
|
|
119
|
+
The Python package, tests and package documentation use MIT. Wheels and source
|
|
120
|
+
archives exclude model weights, photographs, datasets and browser libraries.
|
|
121
|
+
Repository weights were trained on restricted noncommercial datasets and data
|
|
122
|
+
without a documented redistribution license. Obtain appropriate permissions or
|
|
123
|
+
train with suitably licensed data. MIT does not relicense these assets. PyPI
|
|
124
|
+
hosting does not certify scientific accuracy or clinical suitability.
|
|
125
|
+
|
|
126
|
+
## Development
|
|
127
|
+
|
|
128
|
+
Clone the repository and create a virtual environment, then run:
|
|
129
|
+
|
|
130
|
+
```bash
|
|
131
|
+
pip install -e ".[test,inference]" build twine
|
|
132
|
+
pytest
|
|
133
|
+
python -m build
|
|
134
|
+
python -m twine check dist/*
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
Tests cover known geometry, units, input validation and inference transforms.
|
|
138
|
+
Default measurement tests require no model weights. Bug reports should include
|
|
139
|
+
package versions and a minimal example without identifying patient information.
|
|
140
|
+
|
|
141
|
+
Authors: Muhammad Allam Rafi and Cindy Rizky Afrilia.
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
woundscan/__init__.py,sha256=vowE_9I14bBzNimg7eExHKA8MW7H6U2nppiKJFWq9Eg,319
|
|
2
|
+
woundscan/inference.py,sha256=tBOjfMfCafQ7rjjWogOL_OevihkeWI2qT5bBLht9KVQ,2811
|
|
3
|
+
woundscan/measurement.py,sha256=RbUBmuIX8us0WQLd14sTr_xZY9mkQWWgXy6kueiArcU,2477
|
|
4
|
+
woundscan-0.1.0.dist-info/licenses/LICENSE,sha256=95lw3vAfc6PaT8-StxWtihWA5cvB4nrCzz9bCplrVZI,1378
|
|
5
|
+
woundscan-0.1.0.dist-info/METADATA,sha256=oVv753VGc2EL5aYSApTj-W4DoA5IspLUv9a2v0pw4YQ,6305
|
|
6
|
+
woundscan-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
|
|
7
|
+
woundscan-0.1.0.dist-info/top_level.txt,sha256=w13AmMnrX9BnKpBc6HKTyNN_Sz2zHcZ6TRYpApUZYro,10
|
|
8
|
+
woundscan-0.1.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Muhammad Allam Rafi and Cindy Rizky Afrilia
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
22
|
+
|
|
23
|
+
Scope: this license covers the Python package under src/woundscan and its
|
|
24
|
+
package tests and documentation. Model weights, datasets, photographs,
|
|
25
|
+
third-party browser libraries, and other repository assets are excluded.
|
|
26
|
+
Their original rights and restrictions continue to apply.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
woundscan
|