rle_region op• 資料種類:voxel → rle_region
• 呼叫: import fullseye as fs; fs.ledger.vol_rle_encode(vol_binary) -> 'VolRLE'(要直接呼叫實作,import volregion; volregion.vol_rle_encode(vol_binary) -> 'VolRLE';從台帳取用則 ops3d.get("vol_rle_encode"))
把二值體編碼為 x 方向 run(3-D 的 HALCON region 表示)。
非 {0, 1} 的輸入以 > 0.5 做閾值(volops 的約定)。NaN / Inf 被拒絕。空遮罩編碼為 0 個 run —— 這是合法的 region,decode 後全為背景。
記憶體: 與 run 數成正比(約等於每個平面列的表面複雜度),而不是與 voxel 數成正比 —— 在真實的 384**3 零件上實測為密集 bool 遮罩的 1/145。
產生什麼: 將 (D, H, W) 的二值 volume 轉換為沿 x 軸(最後一軸)方向的連續前景區間(run)的列表。VolRLE 是持有 rows(平面列 id z*H + y,int32,升冪)、starts / ends(run 的 x 範圍 [start, end),end 為開區間)、shape (原始的 (D, H, W))的 frozen dataclass。run i 表示 vol[z, y, starts[i]:ends[i]]。
參數與驗證(fail-closed(失敗即拒絕)):
• vol_binary: 3-D 陣列。bool 原樣使用,其他型別轉換為 float64, 有 NaN/Inf 則 ValueError,以 > 0.5 二值化。
• 不是 3-D,或 voxel 數超過 MAX_VOXELS(1 << 27 ≈ 1.34 億)時 ValueError。
• 空遮罩成為 run 數為 0 的 VolRLE(不是錯誤)。
注意: 軸順序為 [z, y, x](depth, row, col)。run 只沿 x 方向延伸,因此在 x 方向上細碎斷開的形狀(條紋、雜訊)run 數越多,壓縮的好處越少。vol_rle_volume / vol_rle_bbox / vol_rle_centroid 不做 decode, 直接在 run 上作答。集合運算為 vol_rle_union / vol_rle_intersect / vol_rle_difference,轉回密集陣列用 vol_rle_decode。
• 範例資料目錄(下載 URL / 授權) —— 2-D 用 skimage.data(BSD/公有領域)加合成圖,3-D 給出真實資料源(Stanford/PDS 等)的下載 URL。
• 運算子來歷與參考文獻 —— 該運算子族所依據的研究/方法出處。
• rle_region_efficiency — py -3.11 examples_3d/rle_region_efficiency.py
rle_region 作為輸入)vol_rle_decode · vol_rle_volume · vol_rle_bbox · vol_rle_centroid · vol_rle_union · vol_rle_intersect · vol_rle_difference · fuse_to_voxel
rle_region)vol_rle_decode · vol_rle_volume · vol_rle_bbox · vol_rle_centroid · vol_rle_union · vol_rle_intersect · vol_rle_difference · vol_rle_components
*Provenance: volregion.py — 3D 運算子登記表。本條目由 tools/opdocs.py md 自動產生(請勿手動編輯)。*
© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.