measure op• 資料種類:labels → table
• 呼叫: import fullseye as fs; fs.ledger.vol_label_shape_stats(labels, spacing=None, shape: 'bool' = True)(要直接呼叫實作,import volcolor; volcolor.vol_label_shape_stats(labels, spacing=None, shape: 'bool' = True);從台帳取用則 opsvolcolor.get("vol_label_shape_stats"))
每個成分線性時間可得的定量值(體積・重心・包圍盒・主成分形狀指標)。
是 volops.vol_region_props 的姊妹,但目的不同:
• 那邊輸出 surface_area 與 Wadell sphericity。為此要對每個成分執行 marching cubes,所以 Python 迴圈的次數與成分數成正比(在 1 體素 1 標籤的病態輸入下會迅速變重)。
• 這邊只限於用 np.bincount 的加權總和就能得到的量。每 1 個標籤陣列 9 次 bincount = O(N + n)。實測(connectivity=26, 1 體素 1 標籤的棋盤格 = 病態輸入):
16 ** 3 = 4096 體素 / 512 成分 = 0.0037 s,32 ** 3 = 32768 / 4096 =
0.0350 s,64 ** 3 = 262144 / 32768 = 0.2556 s,128 ** 3 = 2097152 / 262144 =
2.3122 s。體素每增加 8 倍,耗時為 9.5 / 7.3 / 9.0 倍(若是二次則為 64 倍),
全程約 1.1 微秒/體素。同樣 128 ** 3 的上色為 0.0357 s。
(參考: volops.vol_region_props(surface="faces") 在同樣的 16 ** 3 上為
0.0121 s —— 因為有逐成分的 Python 迴圈,是 3.5 倍。使用 marching cubes 的
預設 surface="auto" 更重。)
label voxel_count volume centroid bbox 這 5 項與 volops.vol_region_props 定義相同、值相同 (由 tests/test_volcolor.py::test_stats_agree_with_vol_region_props_exactly 以嚴格一致固定)。bbox 為 (z0, z1, y0, y1, x0, x1),上限為開區間。
另外還回傳:
centroid_mm (z, y, x) 物理座標(無 spacing 時與 voxel 相同)·
extent bbox 的物理尺寸 (dz, dy, dx) · equivalent_diameter
(6V/pi)**(1/3) · touches_border bbox 是否接觸體資料邊緣 ·
principal_extent 共變異數特徵值的平方根 (s1 >= s2 >= s3)(物理單位) ·
linearity (l1-l2)/l1 · planarity (l2-l3)/l1 · isotropy
l3/l1 · elongation sqrt(l1/l2)。
elongation 可能為無窮(約定): l1 > 0 且 l2 == 0, 即厚度 1 體素的完全直線狀成分時回傳 inf。這不是除以 0 的事故, 而是「第 2 軸方向沒有延展」這項事實,若加以捨入,細長程度的排名會默默調換。單一體素(l1 == 0)是等向的點,所以為 1.0。
忘記傳 spacing,數字和結論都會變。實測 —— 把半徑 6 mm 的球以 spacing = (3.0, 1.0, 1.0) mm 的異向性網格(只有 z 粗 3 倍)取樣, 得到 293 體素。閉合式的真值為 4/3 pi 6**3 = 904.78 mm**3:
• 有 spacing = 879.0 mm ** 3(誤差 -2.85 %), isotropy = 0.7349(近乎等向 = 正確)。
• 無 spacing = 293.0(voxel 單位。若讀作 mm ** 3 則誤差 -67.62 %), isotropy = 0.0817 —— 球看起來像「板」。忽略異向性, 形狀指標就會失效,而且作為有限且看似合理的值回傳。
• 等效直徑也是 11.8849 mm 對 8.2406,差 1.44 倍。
數值上的注意: 2 階矩以 E[x**2] - E[x]**2 求得,所以對座標大而延展小的成分可能發生有效位數流失。在上限 MAX_COLOR_VOXELS (1 邊至 ~2000)下,相對 E[x**2] ~ 4e6,float64 的相對精度 1e-16 = 絕對 1e-10,相對體素單位的變異數有 10 位的餘裕。比這更大的體資料請先裁出 ROI 再傳入(設定上限也是為此)。
把 *shape* 設為 False 時省略共變異數(9 次中的 6 次 bincount), 不回傳 principal_extent 及其後的 5 項 —— 只需要體積過濾時,可把 O(N) 的暫存陣列減為 1 個。
依標籤升冪回傳 list[dict](僅實際存在的標籤 —— 即使編號有缺號,也不會回傳 labels.max() 那麼多的空 dict)。
• 範例資料目錄(下載 URL / 授權) —— 2-D 用 skimage.data(BSD/公有領域)加合成圖,3-D 給出真實資料源(Stanford/PDS 等)的下載 URL。
• 運算子來歷與參考文獻 —— 該運算子族所依據的研究/方法出處。
• 演算法的正典(作者、年份)與用途見上面的族使用指南。
• poc_cold_chain_excursion — py -3.11 examples/poc_cold_chain_excursion.py
• voxel_labels_color — py -3.11 examples/voxel_labels_color.py
table 作為輸入)—
measure)*Provenance: volcolor.py — VOLCOLOR 運算子登記表。本條目由 tools/opdocs.py md 自動產生(請勿手動編輯)。*
© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.