Skip to content

Commit fd64516

Browse files
authored
Merge pull request #45 from DigitalHolography/codex/cross-section-memory-gpu
Refactor cross-section processing with shared topology, bounded memory, and expanded vascular metrics
2 parents 1869424 + 09878cf commit fd64516

172 files changed

Lines changed: 19146 additions & 5118 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎README.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,55 @@ eyeflow --data path\to\input.holo
4848
eyeflow-cli --data path\to\input.holo
4949
```
5050

51+
## Lumen-size plots
52+
53+
Spatial gradients are computed directly on interpolated vessel segments.
54+
The filter order is a centered 7-frame moving average, Sobel magnitude, an
55+
ImageJ Gaussian blur with radius (sigma) 6 pixels, an ImageJ unsharp mask with
56+
radius 8 pixels and mask weight 0.6, then a final 7-frame moving average.
57+
The averaging windows shrink at recording boundaries and propagate NaNs.
58+
Both spatial filters operate independently per frame, propagate NaNs, and set
59+
valid pixels on the outermost rows and columns to zero. The unsharp mask clips
60+
negative values to zero.
61+
These calculations run only when the independently selectable
62+
`spatial_gradient_moment0` pipeline is enabled. The pipeline reuses the
63+
topology prepared by the hidden waveform core; `waveform_velocity` does not
64+
execute or import spatial-gradient processing.
65+
The optional gradient pipeline also owns its dynamic-edge and static-edge
66+
blood-volume-rate calculations. Mask-detection blood-volume rate remains a
67+
waveform-profile product and applies mask-derived circular-area scaling by
68+
default.
69+
70+
When masked spatial-gradient lumen metrics are computed, PNGs are exported
71+
immediately to `png/lumen_size/`, with separate `_artery` and `_vein` files.
72+
`lumen_size_by_branch` plots the joint NaN-ignoring median over beat and radius
73+
for each branch against time in seconds, with lumen size in pixels. The time
74+
axis spans the mean cardiac-cycle duration derived from beat boundaries and
75+
the acquisition frame interval.
76+
`lumen_size_by_branch_top_quartile` plots the mean curve of branches whose
77+
temporal median is at or above the 75th percentile of branch medians, including
78+
ties. Both plots use only `Processing/SpatialGradientMetrics/{Vessel}/Transverse/Masked/tbkr/lumen/size`,
79+
without applying QC.
80+
The branch curves are also stored in HDF5 at
81+
`Processing/SpatialGradientMetrics/{Vessel}/Transverse/Masked/tk/lumen_size`,
82+
with axes `(time, branch)` and units of pixels. PNGs use these same arrays.
83+
84+
## Cross-section topology and memory
85+
86+
Branch identity, annular geometry, segment masks, orientation, transforms, and
87+
run-scoped caching live in `calculations.topology`. An explicit optic-disc
88+
center controls annuli and radial direction; the published optic-disc mask is
89+
excluded from vessels, skeletons, labels, and measurement rings.
90+
91+
Velocity and displacement segments use a fused resize-and-rotate affine
92+
transform. Spatial gradients are the deliberate exception: interpolation and
93+
the radius-6/radius-8 filter chain above must complete before rotation.
94+
Production segment processing is temporally chunked. Worker count and chunk
95+
length share the configured `working_memory_mb` scratch budget; retained
96+
result arrays are not charged to that budget. The staged gradient path carries
97+
a six-frame halo on both sides of each output chunk so chunk boundaries match
98+
whole-recording filtering.
99+
51100
## Scope
52101

53102
### In Scope
Lines changed: 228 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,228 @@
1+
{
2+
"gpu": "NVIDIA GeForce RTX 4090",
3+
"python": "3.12.14",
4+
"numpy": "2.5.3",
5+
"scipy": "1.18.1",
6+
"cupy": "14.2.0",
7+
"cuda_runtime": 13020,
8+
"cuda_driver": 13030,
9+
"cases": [
10+
{
11+
"frames": 64,
12+
"native_side": 33,
13+
"varying_validity": false,
14+
"parity_max_abs_error": {
15+
"masked.raw": 1.9073486328125e-06,
16+
"masked.safe_velocity": 1.9073486328125e-06,
17+
"masked.transverse_profiles": 5.7220458984375e-06,
18+
"masked.longitudinal_profiles": 3.814697265625e-06,
19+
"unmasked.raw": 4.76837158203125e-06,
20+
"unmasked.safe_velocity": 2.384185791015625e-06,
21+
"unmasked.transverse_profiles": 1.7642974853515625e-05,
22+
"unmasked.longitudinal_profiles": 1.430511474609375e-06
23+
},
24+
"main_cpu": {
25+
"seconds": [
26+
0.2631446998566389,
27+
0.26410079980269074,
28+
0.26410700008273125,
29+
0.26214379956945777,
30+
0.26418490009382367
31+
],
32+
"median_seconds": 0.26410079980269074,
33+
"cuda_pool_reserved_mib": 0.0
34+
},
35+
"new_cpu": {
36+
"seconds": [
37+
0.2563567999750376,
38+
0.2561121000908315,
39+
0.25351430010050535,
40+
0.2551613003015518,
41+
0.2575320000760257
42+
],
43+
"median_seconds": 0.2561121000908315,
44+
"cuda_pool_reserved_mib": 0.0
45+
},
46+
"new_gpu": {
47+
"seconds": [
48+
0.021474100183695555,
49+
0.02153669996187091,
50+
0.021507100202143192,
51+
0.021516299806535244,
52+
0.02161499997600913
53+
],
54+
"median_seconds": 0.021516299806535244,
55+
"cuda_pool_reserved_mib": 61.59228515625
56+
},
57+
"windowed_cpu": {
58+
"seconds": [
59+
0.2579212998971343,
60+
0.261404599994421,
61+
0.25806180015206337,
62+
0.25859880028292537,
63+
0.25796290021389723
64+
],
65+
"median_seconds": 0.25806180015206337,
66+
"cuda_pool_reserved_mib": 0.0
67+
},
68+
"windowed_gpu": {
69+
"seconds": [
70+
0.025804100092500448,
71+
0.02564609982073307,
72+
0.025661500170826912,
73+
0.02562159998342395,
74+
0.025511799845844507
75+
],
76+
"median_seconds": 0.02564609982073307,
77+
"cuda_pool_reserved_mib": 61.59228515625
78+
},
79+
"windowed_gpu_speedup": 10.062418923575995,
80+
"gpu_speedup_vs_new_cpu": 11.903166547857891
81+
},
82+
{
83+
"frames": 256,
84+
"native_side": 65,
85+
"varying_validity": false,
86+
"parity_max_abs_error": {
87+
"masked.raw": 1.9073486328125e-06,
88+
"masked.safe_velocity": 1.9073486328125e-06,
89+
"masked.transverse_profiles": 4.76837158203125e-06,
90+
"masked.longitudinal_profiles": 3.814697265625e-06,
91+
"unmasked.raw": 4.76837158203125e-06,
92+
"unmasked.safe_velocity": 2.86102294921875e-06,
93+
"unmasked.transverse_profiles": 1.9550323486328125e-05,
94+
"unmasked.longitudinal_profiles": 1.9073486328125e-06
95+
},
96+
"main_cpu": {
97+
"seconds": [
98+
1.0224035996943712,
99+
1.0433074999600649,
100+
1.047608199995011,
101+
1.0430449000559747,
102+
1.0473556998185813
103+
],
104+
"median_seconds": 1.0433074999600649,
105+
"cuda_pool_reserved_mib": 0.0
106+
},
107+
"new_cpu": {
108+
"seconds": [
109+
0.9985433002002537,
110+
0.9808040000498295,
111+
0.9933404000476003,
112+
0.9864547997713089,
113+
1.0235187001526356
114+
],
115+
"median_seconds": 0.9933404000476003,
116+
"cuda_pool_reserved_mib": 0.0
117+
},
118+
"new_gpu": {
119+
"seconds": [
120+
0.06685409974306822,
121+
0.05280760023742914,
122+
0.04665900021791458,
123+
0.046986100263893604,
124+
0.04645359981805086
125+
],
126+
"median_seconds": 0.046986100263893604,
127+
"cuda_pool_reserved_mib": 249.25
128+
},
129+
"windowed_cpu": {
130+
"seconds": [
131+
1.2096396000124514,
132+
1.2046519997529685,
133+
1.2129534999839962,
134+
1.211948299780488,
135+
1.2076723002828658
136+
],
137+
"median_seconds": 1.2096396000124514,
138+
"cuda_pool_reserved_mib": 0.0
139+
},
140+
"windowed_gpu": {
141+
"seconds": [
142+
0.1467368002049625,
143+
0.13858129968866706,
144+
0.11636310024186969,
145+
0.11598289990797639,
146+
0.11542609985917807
147+
],
148+
"median_seconds": 0.11636310024186969,
149+
"cuda_pool_reserved_mib": 162.59814453125
150+
},
151+
"windowed_gpu_speedup": 10.395388207242005,
152+
"gpu_speedup_vs_new_cpu": 21.141154393928947
153+
},
154+
{
155+
"frames": 256,
156+
"native_side": 65,
157+
"varying_validity": true,
158+
"parity_max_abs_error": {
159+
"masked.raw": 1.9073486328125e-06,
160+
"masked.safe_velocity": 1.9073486328125e-06,
161+
"masked.transverse_profiles": 4.76837158203125e-06,
162+
"masked.longitudinal_profiles": 3.814697265625e-06,
163+
"unmasked.raw": 4.76837158203125e-06,
164+
"unmasked.safe_velocity": 2.86102294921875e-06,
165+
"unmasked.transverse_profiles": 1.9550323486328125e-05,
166+
"unmasked.longitudinal_profiles": 1.9073486328125e-06
167+
},
168+
"main_cpu": {
169+
"seconds": [
170+
1.2038238998502493,
171+
1.2135808998718858,
172+
1.2070334004238248,
173+
1.2202066997997463,
174+
1.2052440997213125
175+
],
176+
"median_seconds": 1.2070334004238248,
177+
"cuda_pool_reserved_mib": 0.0
178+
},
179+
"new_cpu": {
180+
"seconds": [
181+
1.156547799706459,
182+
1.1561942999251187,
183+
1.1536400001496077,
184+
1.1679037003777921,
185+
1.1553869000636041
186+
],
187+
"median_seconds": 1.1561942999251187,
188+
"cuda_pool_reserved_mib": 0.0
189+
},
190+
"new_gpu": {
191+
"seconds": [
192+
0.08417529985308647,
193+
0.04954920010641217,
194+
0.04705600021407008,
195+
0.047077199909836054,
196+
0.04683490004390478
197+
],
198+
"median_seconds": 0.047077199909836054,
199+
"cuda_pool_reserved_mib": 249.25
200+
},
201+
"windowed_cpu": {
202+
"seconds": [
203+
1.566662299912423,
204+
1.5547615000978112,
205+
1.5674175997264683,
206+
1.5488176997750998,
207+
1.5544372000731528
208+
],
209+
"median_seconds": 1.5547615000978112,
210+
"cuda_pool_reserved_mib": 0.0
211+
},
212+
"windowed_gpu": {
213+
"seconds": [
214+
0.13331930013373494,
215+
0.11624439992010593,
216+
0.11497739981859922,
217+
0.11569879995658994,
218+
0.11613699980080128
219+
],
220+
"median_seconds": 0.11613699980080128,
221+
"cuda_pool_reserved_mib": 162.59814453125
222+
},
223+
"windowed_gpu_speedup": 13.387305533676136,
224+
"gpu_speedup_vs_new_cpu": 24.559538420711164
225+
}
226+
],
227+
"scope": "One segment: resize, rotate, fit limits, profiles and host outputs. Synchronized wall time; compilation excluded. Synthetic data; excludes branch labeling, profile postprocessing, and export."
228+
}

‎default_settings.json‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,12 @@
11
{
22
"pipeline_visibility": {
33
"absolute_waveform_metrics": true,
4+
"blood_volume_rate": true,
5+
"displacement_map": false,
46
"lowrank_waveform_decomposition": true,
57
"pdf_report": true,
8+
"spatial_gradient_moment0": false,
9+
"velocity_profile_analysis": true,
610
"waveform_shape_metrics": true,
711
"waveform_velocity": true
812
},
@@ -12,6 +16,10 @@
1216
"per_beat": true,
1317
"segments": true
1418
},
19+
"blood_volume_rate": {
20+
"gradient_edges": false,
21+
"masked_edges": true
22+
},
1523
"lowrank_waveform_decomposition": {
1624
"quadrants": true
1725
},
@@ -24,7 +32,8 @@
2432
"quadrants": true,
2533
"per_beat": true,
2634
"segments": true,
27-
"velocity_profiles": false,
35+
"velocity_profiles": true,
36+
"velocity_profile_fft": false,
2837
"segment_velocity_maps": false
2938
}
3039
},

‎docs/velocity_profile_analysis.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# Artery velocity-profile analysis
2+
3+
Selecting `velocity_profile_analysis` ensures the upstream waveform pipeline
4+
computes segments and per-beat products and publishes velocity profiles, even
5+
when those selectable outputs were disabled. Analysis reads the work HDF5 dataset:
6+
7+
`/Processing/VelocityProfiles/Artery/TransverseVelocityProfileMasked/value`
8+
9+
Input axes are `(x, time, beat, branch, radius)`. Every profile is fit independently;
10+
there is no averaging across time, beats, branches or radii.
11+
12+
## Fit definition
13+
14+
Use `x = 0, ..., Nx-1` and minimize `sum(w * (v - (a*x*x+b*x+c))**2)` over
15+
finite observed samples. For `u=x/(Nx-1)` and `d=abs(2*u-1)`, use `w=1-d^p`.
16+
The default `p=2` gives a quadratic decrease from weight one at the domain
17+
center to weight zero at either border. Direct API callers may supply any finite
18+
`p>0`. With an even number of samples, the two samples nearest the center have
19+
equal maximum sampled weights below one. Weights remain tied to the complete
20+
input domain when some samples are missing. A one-sample domain has weight one.
21+
22+
The solver scales design rows and observations by `sqrt(w)` and works in
23+
float64 on centered/scaled coordinates. Stored coefficients refer to the original
24+
zero-based index coordinate. Time slabs contain at most 256 profiles per
25+
beat/branch/radius, and profiles sharing finite masks reuse the least-squares
26+
solve within each slab. The entire input dataset is not materialized.
27+
28+
## Output schema
29+
30+
Each name below is written to
31+
`/Processing/VelocityProfileAnalysis/Artery/<name>/value` with axes
32+
`(time, beat, branch, radius)`. Float arrays are float32 and counts are int32.
33+
34+
| Names | Definition |
35+
|---|---|
36+
| `a`, `b`, `c` | Quadratic coefficients; coefficient `b` is distinct from the input beat axis |
37+
| `fit_rss` | Sum of squared residuals over finite samples |
38+
| `fit_rmse` | `sqrt(fit_rss/n_fit_samples)` |
39+
| `fit_r_squared` | `1-fit_rss/SST`, using the ordinary observed mean |
40+
| `fit_weighted_rss` | Sum of `w*residual**2` |
41+
| `fit_weighted_rmse` | `sqrt(fit_weighted_rss/sum(w))` |
42+
| `fit_weighted_r_squared` | `1-fit_weighted_rss/weighted_SST`, using the weighted observed mean |
43+
| `n_fit_samples` | Number of finite input samples |
44+
| `index_center` | Fractional vertex index for a downward-opening, nondegenerate fit |
45+
| `index_left_zero`, `index_right_zero` | Sorted fractional real roots, not clipped to the input range |
46+
| `Qv_fit`, `Qv` | Unweighted signed sums of fitted and observed values on identical observed support |
47+
| `n_area_samples` | Size of that observed support |
48+
49+
Observed support consists of finite input samples whose integer indexes are
50+
inclusively between the roots. Indexes outside the sampled domain contribute
51+
nothing. There is no extrapolation, quadrature, absolute value, or pixel-spacing
52+
factor in either area sum. In particular, negative observed samples retain their
53+
sign. Coefficients and area sums use index coordinates, not physical distances.
54+
55+
All datasets include axis, source path, zero-based-index, model, weighting, and
56+
integration metadata. The `weight_power` attribute records the production value
57+
`2.0`. Only artery analysis is produced.
58+
59+
## Invalid or degenerate profiles
60+
61+
- Fewer than three finite samples, rank deficiency or nonfinite coefficients:
62+
numerical outputs are NaN; the observed sample count is retained.
63+
- Upward-opening or effectively linear fits retain coefficients and diagnostics,
64+
but geometry and areas are NaN. Negligible normalized curvature is at most
65+
`64*float64_epsilon*max(1,max(abs(v)))` in magnitude.
66+
- Downward fits retain the vertex even without two distinct finite real roots.
67+
A discriminant within float64 roundoff of zero is treated as a repeated root;
68+
the tolerance is `64*epsilon*max(1,alpha**2,beta**2,abs(4*alpha*gamma))` for
69+
normalized coefficients `(alpha,beta,gamma)`.
70+
- No usable roots or no observed indexes between roots: NaN areas and zero area count.
71+
- Constant observations have undefined R-squared, returned as NaN. Unweighted
72+
R-squared may be negative because the fit optimizes weighted residuals.
73+
- Empty time/beat/branch/radius axes are preserved. Missing input or a wrong
74+
dimensionality raises an explicit error before outputs are returned.

0 commit comments

Comments
 (0)