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 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
@@ -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,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -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