VoxelSieve

VoxelSieve

OpenVDB を基盤とする、産業用 CT ボリューム向けのオープンソースツールです。

再構成された CT ボリュームは、ほとんどのボクセルが空気である、大容量の非圧縮 raw ファイルです。 VoxelSieve は周囲の空気と部品を分離し、気孔などの内部空隙を保持して、メモリ容量を超えるサイズのスキャンにも対応する疎なブリック形式の VDB データセットとして結果を保存します。 さらに、気孔や緩みのある微細構造を検出し、検査レポートを作成します。

CT スライス	気孔率解析	検査レポート
ベルハウジングの合成スキャンの断面：エンジンフランジに緩み領域と引け巣があります	vs-porosity：気孔は赤、緩み領域は黄色で表示	vs-report：検査ゾーンごとの評価（BDG P 202方式）

気孔率解析の画像はすべて、サンプルのベルハウジングを合成スキャンしたデータから作成されています。データは 765 × 765 × 380 ボクセル、ボクセルサイズは 0.1 mm（445 MB）で、鋳造部が最後に凝固する箇所に引け巣と緩み領域があります：vs-synth --part bellhousing --voxel-size 0.1 --hot-spots --lunker 12 --lunker-radius 0.9 --lunker-spread 0.6 --loosening 3 --loosening-radius 1.5 --noise 500 --cupping 0.08 --blur 0.07 --seed 12。すべての引け巣の体積は正解値との差が 2 % 以内（最小の 0.06 mm³ は 4 % 以内）で検出され、フランジの奥にあるゾーンは 2 % 以内、表面直下にあるゾーンは 10 % 以内の差で検出されます。部品体積の誤差は 0.02 % 以内です。

ステータス：初期開発段階、最新リリースは 0.3.1（CHANGELOG.md を参照）。初めてお使いですか？ クイックスタートでは、サンプルデータを使って、ダウンロードから AI アシスタントによる気孔率レポートの作成までを説明します。ツール：

ツール	機能
vs-sieve	raw ボリューム（ベンダーヘッダー付き）または TIFF スタック → 疎なブリック形式のデータセット。ストリーミング処理、アウトオブコア対応
vs-porosity	気孔と緩み領域 → JSON、投影画像、Blender または Houdini 用 VDB
vs-surface	データセット → コンパクトな距離マスク、メッシュ、または VDB レベルセットとしての表面
vs-segment	データセット → グレイ値または学習済みモデル（--model）による材料クラス分類。ラベルと照合してスコアを算出
vs-denoise	データセット → ノイズ除去済みデータセット（非局所平均法または学習済みモデル）。--benchmark で両者を比較
vs-compare	表面 + CAD モデル（STL）→ アライメント済みの公称値と実測値の偏差、統計情報、色付き PLY
vs-thickness	データセット → 表面の全点における壁厚（レイまたは球による計測）、薄肉部と厚肉部、色付き PLY。--volume-map で材料ボクセルすべての厚さを出力
vs-diconde	データセット + 気孔 + 材料 + 検査順序 → DICONDE シリーズ。--info で内容を表示
vs-report	気孔率解析 + 合否判定限界 → 検査レポート（HTML、PDF 印刷対応）
vs-battery	バッテリーセル → ハウジング、電極層、負極オーバーハング、粒子、空隙、レポート
vs-gui	ウィザード、取り消し、スライス表示、3D 表示に対応したブラウザー UI。--mcp で AI システムに提供
vs-synth	STL メッシュ → 欠陥、ノイズ、アーティファクトを含む合成 CT スキャンと正解データ
vs-phantom	解析的な正解データ付きのシンプルなボックスファントム

ビルド

依存関係はvcpkgから取得し、vcpkg.jsonで固定しています。Ubuntu 24.04の場合：

sudo apt-get install cmake ninja-build g++ git curl zip unzip tar autoconf automake libtool pkg-config
tools/setup-vcpkg.sh && export VCPKG_ROOT=~/vcpkg
cmake --preset release && cmake --build --preset release && ctest --preset release
./build/release/apps/vs-phantom/vs-phantom --out phantom --dims 256

phantom.raw（uint16、リトルエンディアン、x軸が最速）と、フォーマットの説明および解析的なグラウンドトゥルース（細孔、壁厚、材料体積）を記載したphantom.jsonが作成されます。

最初の構成時にはOpenVDB、Boost、TBBをソースからビルドするため、時間がかかります。vcpkgはビルド結果をバイナリキャッシュに保存するため、以降のビルドでは再利用されます。vcpkgへの切り替え前に構成したビルドディレクトリにはツールチェーンが反映されないため、--freshを付けて再構成してください（cmake --preset release --fresh）。

Windows（x64、C++ワークロードを含むMSVC 2022ビルドツールを使用し、Git BashをPATHに追加したDeveloper PowerShellから実行）およびmacOS（Appleシリコン、Xcodeコマンドラインツールとbrew install ninja autoconf autoconf-archive automake libtool pkg-configを使用）では、releaseの代わりにwindowsまたはmacosプリセットを使用してください。Windowsでは、プログラムはbuild/windows/binに配置されます。

ボリュームをふるいにかける

VoxelSieveは、ブリック分割されたデータセット（サイズを問わず、ストリーミング処理）または単一の.vdbグリッド（小規模なボリューム向け、メモリ内処理）を書き出します。

大規模スキャン向けのブリック分割データセット

./build/release/apps/vs-sieve/vs-sieve scan.raw --out scan.vsieve

scan.vsieve/には、index.json、overview.vdb（ボリューム全体を最大256³ボクセルの1つのグリッドに格納）と、256³ブリックごとに1つのVDBファイルを格納したlevel0/、level1/、…が含まれます。外気だけで構成されるブリックは書き出されません。入力はメモリマップされ、2回のストリーミングパスで処理されるため、スキャン全体をRAMに収める必要はありません。--phantom Nを指定すると、ファイルの代わりにN³の計算ファントムをふるいにかけます。

CTシステムのrawファイルには、通常、独自形式のヘッダーが先頭にあります。VoxelSieveはこれをスキップします。寸法を指定すると、ファイル内のボクセルデータを超える部分をすべてヘッダーとして扱い、検出したサイズを表示します。ファイルにフッターも含まれる場合は--header <bytes>を、8ビットデータには--type uint8を、ビッグエンディアンの16ビットサンプルには--big-endianを使用してください。表示されたヘッダーサイズを確認してください。寸法が小さすぎる場合も余分なバイトが残り、ヘッダーとして誤って読み取られます。

入力	rawサイズ	データセット	時間	ピークメモリ
1024³ rawファイル（mmap）	2 GB	776 MB	6.1 s	2.5 GB（うち約2 GBは再利用可能なメモリマップ済み入力ページ）
1024³計算ファントム	(2 GB)	776 MB	35.5 s	0.46 GB
2048³計算ファントム	(16 GB)	5.8 GB	345 s	0.87 GB

計算ファントムは各ボクセルを2回評価するため、処理が遅くなります。メモリ値は、メモリマップ済み入力ページを除いた、ふるい処理自体の使用量を示しています。

プログラムはvoxelsieve::Datasetを通じてデータセットを読み込みます。ブリックは、メモリ予算を設定したLRUキャッシュに必要に応じて読み込まれます。

const auto dataset = voxelsieve::Dataset::open("scan.vsieve", /*cache_bytes=*/4ULL << 30U);
std::optional<float> value = dataset.sample(0, {512, 400, 300});  // nullopt for removed air
std::vector<float> slab(512 * 512 * 16);
dataset.readRegion(0, {{0, 0, 300}, {512, 512, 316}}, slab);      // across brick boundaries
dataset.forEachGrid(1, [](const auto& brick, const auto& grid) { /* parallel, uint16/uint8/float */ });

TIFF スタック

./build/release/apps/vs-sieve/vs-sieve slices/ --out scan.vsieve --voxel-size 0.05
./build/release/apps/vs-sieve/vs-sieve scan.zip --out scan.vsieve        # read without extracting
./build/release/apps/vs-sieve/vs-sieve scan.zip --folder target --threshold 0.5 --out labels.vsieve
./build/release/apps/vs-sieve/vs-sieve recon.zip --value-range -0.05,0.3 --out scan.vsieve  # float
./build/release/apps/vs-sieve/vs-sieve pipe.zip --air-from xy --out pipe.vsieve  # cut at both ends

スライスのディレクトリ、複数ページの TIFF、またはいずれかを格納した ZIP アーカイブを直接読み込みます （voxelsieve::TiffStackSource、ADR 0011）。スライスは名前順に並べ、数字は数値として比較します （slice2 は slice10 より前になります）。対応形式は、クラシック TIFF と BigTIFF、ストリップとタイル、 非圧縮、LZW、Deflate、PackBits、水平予測子の有無を問わない形式、符号なし 8 ビットまたは 16 ビットのサンプルです。32 ビットのサンプルは、16 ビットに収まる場合に受け付けます（ラベルボリューム）。浮動小数点の スライス（32 ビットまたは 64 ビット、浮動小数点予測子を含む）は、--value-range で指定するか 33 枚のスライスから 推定した値の範囲にわたって、グレー値 0～65535 に線形変換されます。変換内容は出力され、データセットの index.json に記録されます（value = offset + scale * grey）。範囲外の値はクリップされ、その数がカウントされます（ADR 0015）。カラー画像と符号付き画像は 受け付けません。最初と最後のスライスが部品（パイプやドリルコア）を横切っている場合、--air-from xy を指定すると、外側の空気を側面からのみ取り込むため、部品の内部が保たれます（ADR 0003）。入力にスライスのフォルダーが複数含まれる場合、ラベルやマスクのような名前のフォルダー（label*、mask*、 seg*、gt、target）ではなく、グレー値が使用されます。ほかのフォルダーは表示され、--folder で選択できます。ボクセルサイズは OME-XML の画像説明（PhysicalSizeX、Y、Z）、センチメートル単位の解像度、印刷時の既定値（72 dpi や 300 dpi など）ではないインチ単位の解像度、または key=value 形式の画像説明（スライスの spacing を含む）から取得します。いずれも存在しない場合は 1 mm とみなされ、その旨が表示されます。--voxel-size で設定できます。GUI では、この操作は import_tiff です。 データセットの場合、まずすべてのスライスを全コアを使って一度だけデコードし、出力ディレクトリにボクセルあたり 2 バイトの一時 RAW ファイルを作成します（--staging-dir を指定すると別の場所に作成します）。このファイルは処理の最後に削除されます。--no-staging を指定するとスライスを直接読み込みますが、大きなスタックでは大幅に遅くなります。

DICOM スタック

./build/release/apps/vs-sieve/vs-sieve dicom/ --out scan.vsieve          # a directory of slices
./build/release/apps/vs-sieve/vs-sieve dicom.zip --out scan.vsieve       # the same in a ZIP archive

DICOM スライスのディレクトリ、またはそれらを格納した ZIP アーカイブ（展開せずに読み込み、各エントリの CRC を確認）を、DCMTK で読み込みます （voxelsieve::DicomStackSource、ADR 0019）。対応形式は、非圧縮または RLE、プリアンブルの有無を問わない形式で、スライス法線に沿った位置順に並べられます。 ボクセルサイズと姿勢はファイルから取得します。符号付きサンプルは 32768 だけシフトされ、リスケールの傾きと切片とともに値の変換情報として記録されるため、値は失われません。ディレクトリに複数のシリーズがある場合、最大のシリーズを読み込み、ほかのシリーズを表示します。GUI では、この操作は import_dicom です。スライスが間隔に比べて薄い場合、またはピクセル間隔に比べて大きく離れている場合、インポートの概要に警告が表示されます（warnings）。interpolate_slices（すべてのインポート）を使うと、測定済みスライスの間を補間したスライスで隙間を埋められます。

DICONDE

./build/release/apps/vs-diconde/vs-diconde scan.vsieve --porosity scan.porosity \
  --materials scan.materials --order examples/inspection_order.json --out scan.diconde
./build/release/apps/vs-diconde/vs-diconde --info scan.diconde/volume

DICONDE（ASTM E2339）は、非破壊評価用の DICOM です（ADR 0024）。VoxelSieve はデータセットを CT 画像のシリーズとして、スライスごとに 1 ファイルずつ書き出します。正確なグレー値、ボクセルサイズ、物体の位置が保持され、除去された外側の空気には空気レベルが設定されます。検査の順序は、コンポーネント（部品、シリアル番号、図面、材料）、検査（ラボ、顧客、報告書と注文番号、検査員、許容限界に照らした評価）、スキャン設定として記録されます。ポアや接合の緩んだ領域は、位置、体積、サイズを持つ指示領域となり、材料セグメンテーションは同じ座標系のラベルからなる 2 つ目の派生シリーズとなります。DICONDE ファイルはほかの DICOM スライスと同様に読み込まれ（vs-sieve、import_dicom）、インポート時にコンポーネントと指示領域が報告されます。GUI では、この操作は export_diconde です。

読み込み中の初回プレビュー、ネットワーク共有からも表示

./build/release/apps/vs-sieve/vs-sieve /mnt/ct-share/part.zip --out part.vsieve --preview first.png

各パスの前に、インポートではボリューム全体に均等に分散した64枚のスライスを読み込み、一度に表示します。z、y、xに垂直な中央断面を面内で平均化し、各辺を最大1024ボクセル、全体で3200万ボクセルに収めたものと、推定しきい値を示すそれらのスライスのヒストグラムです（ADR 0020）。段階的なインポートで残りのデータをコピーしている間に、プレビューはより鮮明になります。プレビュー対象の残りのスライスを粗いものから細かいものへと読み込み、各ラウンドでその数を3倍にし、ラウンドごとに新しいプレビューを表示します。最後のプレビューではボリューム全体のヒストグラムを表示します。スライスは、すべての入力形式でデータがまとめて保存される単位（スタックのファイルや、rawファイルの連続した部分）なので、SMB経由でも1スライスにつき1回のリクエストで済みます。インポートではスライスを再度読み込む必要はありません。ネットワーク共有上のスタックやファイルは、スライスごとにローカルのステージングファイルへ一度だけコピーし、プレビュー対象のスライスを先にコピーします。ローカルのrawファイルは直接読み込まれ、初回プレビューのみが表示されます。これらのインポートでは、読み込み速度ではなくパスが処理速度を左右します。SMBまたはNFS共有上のrawファイルや、ネットワークドライブとしてマウントされたrawファイルも検出してステージングするため、小分けにして2回読み込む必要はありません。GUIでは、プレビューはすべてのインポートの進捗バーに表示され、ステップとともに保持されます（preview.png）。AI アシスタントには import_preview で渡されます。

gzip圧縮されたrawファイル（scan.raw.gz と scan.json の組み合わせ）も、vs-sieve、import_raw、GUIのファイルブラウザーで読み込めます。gzipは前方にしか読み込めないため、このようなファイルはスライスの順序に従って一度だけ展開され、ステージングファイルに書き込まれます。そのパスの最後にプレビューが表示されます。非圧縮データにヘッダーがある場合は、--header を指定してください。

単一グリッド

./build/release/apps/vs-sieve/vs-sieve phantom.raw --out phantom.vdb

寸法とボクセルサイズは phantom.json から読み込むか、--dims X Y Z と --voxel-size MM で指定します。ボクセルは立方体でなくてもかまいません（ADR 0012）。--voxel-size 0.33,0.33,0.6 はx、y、z方向の辺の長さを指定し、--slice-thickness 0.4 は間隔より薄いスライス（スライス間の隙間）を記録します。すべての測定値、VDB変換、画像、ビューアーでは、軸ごとのピッチを使用します。--threshold を指定しない場合、空気と素材のしきい値はヒストグラムから推定されます。これは空気のピークと次の素材の間の谷であり、複数の素材が含まれるスキャンでは、明るい素材も素材として扱われます（素材が1種類だけの場合は大津の二値化）。--margin は部品の周囲に残す空気のボクセル数を制御します。--dense はふるい分けを行わず、すべてのボクセルを書き出し、ベースラインとして使用します。グレー値は入力の16ビットまたは8ビットを維持します（ADR 0021）。--value-type float を指定すると、.vdb とデータセットの各ブリックをBlenderまたはHoudiniで直接開けます。これらのアプリケーションが読み込めるのは、OpenVDBの標準グリッドタイプのみです。

ファントムのベンチマーク（体積の約4分の1を細孔が占める中空の箱、ノイズ σ = 500、4コア）：

ボリューム	Raw	Dense VDB	Sieved VDB	アクティブボクセル	ふるい分け時間
256³	32 MB	43.6 MB	11.8 MB	27 %	0.03 s
512³	256 MB	348.9 MB	85.9 MB	26 %	0.23 s

この表の測定ではグレー値を32ビット浮動小数点数として保存しています（ADR 0002）。そのため、Denseのベースラインはrawファイルより大きくなっています。ADR 0021ではグリッドが入力の16ビットを維持するため、256³のファントムのDense VDBはrawファイルの140 %ではなく、115 %のサイズになります。

設計上の決定はdocs/adrに記録されています。

STL からの合成スキャン

vs-synth は、閉じた STL メッシュ（mm）を、人工的な欠陥、ノイズ、アーティファクトを含む生の CT ボリュームに変換し、正解データを含む JSON サイドカーファイルを生成します。欠陥解析のテストベッドとして使用します。

./build/release/apps/vs-synth/vs-synth part.stl --out part --voxel-size 0.05 \
    --lunker 5 --loosening 2 --noise 500 --cupping 0.1 --rings 8
./build/release/apps/vs-sieve/vs-sieve part.raw --out part.vsieve

• --lunker N：収縮巣。重なり合う球が不規則に結合した形状です。
• --loosening N：組織の緩み（Gefügeauflockerung）領域。--loosening-porosity（デフォルトは 5 %）まで、ボクセルサイズ以下の小さな気孔を多数生成します。
• --noise、--cupping（ビームハードニング）、--rings（z 軸を中心とするリング状アーティファクト）。
• --blur MM：撮像系の不鮮明さを表し、指定した値をシグマとするガウス点拡がり関数を適用します。
• --hot-spots を指定すると、収縮巣と組織の緩み領域を、空きのある場所ではなく、鋳物が最後に凝固する最も肉厚な部分に配置します。--lunker-spread F は、収縮巣のサイズを --lunker-radius の (1 - F) 倍まで変化させます。
• --box X Y Z は STL ファイルの代わりにボックスを使用します。--part housing|bracket|hub|bellhousing は、壁、リブ、ボス、ボア、フィレットを備えたサンプル鋳物を使用します（--scale、--stl でメッシュを書き出します）。

part.json には、各欠陥の位置、サイズ、空隙体積、および総空隙率が記録されます。グレー値は、ボクセルよりはるかに小さい気孔でも、空隙体積を正確に表します（docs/adr/0005-synthetic-scans-from-meshes.md を参照）。スキャンは要求に応じて計算され、ディスクにストリーミングされます。1040 × 840 × 640 ボクセル（1.1 GB）で欠陥が 15 個の場合、4 コアで 41 秒かかります。

表面

vs-surface は部品の表面を特定し（デフォルトでは ISO 50 %）、符号付き距離を 1/7 ボクセル刻みで ±1 ボクセルの範囲にわたって符号化する、ボクセルあたり 4 ビットのボクセルマスクとして保存します。それより遠い位置はすべて「材料」または「空気」として扱います。表面に接する 8³ ブロックのみをブリックごとに zstd 圧縮して保存するため、ファイルサイズはスキャンではなく表面積に応じて増加します。

./build/release/apps/vs-synth/vs-synth --part housing --voxel-size 0.1 --blur 0.05 --out housing
./build/release/apps/vs-sieve/vs-sieve housing.raw --out housing.vsieve
./build/release/apps/vs-surface/vs-surface housing.vsieve --out housing.vss --stl housing.stl

上記のハウジング（520 × 400 × 220 ボクセル）ではファイルサイズは 156 kB となり、16 ビットの生ボリュームに対して 588：1 の比率です。また、三角形分割した表面は解析的な表面から 0.033 ボクセル（RMS）の距離にあります。voxelsieve::SurfaceMask は単一ボクセルまたは領域のコードと距離を読み取り、VDB レベルセットまたはメッシュに変換します。--vdb を指定すると、Blender または Houdini 用にレベルセットを書き出します。GUI では「Surface」操作として実行され、マスクの中央スライスが表示されます。形式と測定値については、docs/adr/0009-surface-distance-mask.md を参照してください。

名目値と実測値の比較

vs-compare は、スキャンした部品表面と CAD モデル（単位：mm の STL）を比較します。CAD モデルをスキャンに位置合わせし、表面上のすべての点の符号付き偏差を測定します。部品の材料が名目値より多い場合は正、材料が不足している場合は負になります。

./build/release/apps/vs-compare/vs-compare housing.vss housing-cad.stl --out housing.compare \
    --tolerance 0.1

• 位置合わせ： デフォルトでは、両方の表面の主軸を使って大まかに位置合わせし、ロバストなベストフィット（点と平面の ICP）で調整します。CAD モデルの位置や向きは問いません。--align refine は --initial を開始位置としてベストフィットを行い、--align none は --initial をそのまま使用します。たとえば、CAD モデルがすでにスキャン座標系にある場合に使います。
• 出力：
  • compare.json：変換、フィット、平均、RMS、極値とパーセンタイル、公差内外の面積、ヒストグラムが含まれます。
  • deviation.ply：偏差と頂点ごとの色を付与したスキャン表面です。
  • deviation_view_1.png、deviation_view_2.png：上側と下側から見た陰影付き画像です。
  • --aligned-stl を指定すると cad_aligned.stl が出力され、CAD モデルがスキャン座標系に移動します。
• 内部空隙： 閉じた内部空隙（気孔）の表面はデフォルトでは除外されます。これらはポロシティ解析の対象です。
• 柔軟な部品： --non-rigid は剛体位置合わせの後にスキャン表面を CAD モデルに沿って変形させます。薄板金属、プラスチック、ゴムなど、スキャナー内で名目形状を保てない部品に使います。変形は弾性的で滑らかです。薄い部分は容易に曲がり、厚い部分や部品全体の形状はほとんど変わりません。また、制御点間隔（--non-rigid-spacing）より短い形状は変形されないため、へこみ、突起、壁厚の誤りは偏差として残ります。偏差は変形後の表面で測定されます。deviation.ply と displacement_view_[12].png には各点の移動距離が示され、compare.json には比較用として剛体位置合わせのみの数値が保持されます （docs/adr/0022-non-rigid-registration.md）。

合成鋳物では、フィットによって CAD モデルの位置と向きを 0.15 ボクセルの精度で特定でき、0.4 mm のへこみを 0.02 mm の精度で測定できます。GUI では「Nominal-actual comparison」という操作で比較を実行し、3D ビューに色付きの表面を「Nominal-actual deviation」として表示します。手法と判断については docs/adr/0010-nominal-actual-comparison.md を参照してください。

壁厚

vs-thicknessは、CADモデルを使わずに部品表面の各点で壁の厚さを測定し、図面で許容される厚さより薄い領域または厚い領域を検出します。

./build/release/apps/vs-thickness/vs-thickness housing.vsieve --out housing.thickness \
    --min-wall 2.5 --max-wall 8

• 方法： --method ray（デフォルト）では、ノギスのように、内向き法線に沿ってグレー値を通り抜け、壁の反対側の面までボクセルの端数単位で測定します。壁の端から外へ出る光線や、リブに沿って進む光線では、到達した面が検索角度（--search-angle、デフォルトは30°）の範囲内にない場合、壁ではない長さを報告せず、その点を未測定のままにします。--method sphereでは、その点に接する、材料内部で最大の球の直径を測定します。リブや角でも定義されますが、定義上、凸状の端では値が小さくなります。
• ポア： ポアがある箇所では壁が薄くなります。ポアの表面が光線や球の境界になりますが、値が付くのは外側のスキンのみです（--all-surfacesを指定すると、ポアの表面も測定します）。
• 出力：
  • wall_thickness.json：面積で重み付けした統計値（最小値、平均値、パーセンタイル、ヒストグラム）、測定された表面の割合、および面積、極値、位置を含む薄い領域と厚い領域。
  • thickness.ply：mm単位の表面データ。各頂点に厚さと色が付与されます。
  • thickness_view_1.png、thickness_view_2.png：上方および下方からのビュー。薄い壁は赤、黄色と緑を経て、厚い壁は青で表示されます。最小値未満はマゼンタ、最大値を超える部分は紫、--max-thicknessまで壁が見つからなかった箇所は灰色で表示されます。
• 大規模なスキャン： メモリに保持するのは表面メッシュのみです（--max-triangles）。グレー値は、ブリックキャッシュを介して光線に沿って読み取ります。
• CADモデルとの比較： --nominal part.compare（vs-compareの出力）を指定すると、同じ方法で、位置合わせされたCADモデルの公称厚さも各点で測定し、実際の厚さとの差を算出します。これにより、コアのずれの両側の壁など、設計より薄くなった壁や厚くなった壁を確認できます。thickness.plyには各頂点のnominalとdeviationが追加され、thickness_deviation_view_[12].pngにその差が表示されます。
• 部品内部： --volume-mapを指定すると、材料の各ボクセルにおける局所厚さ（そのボクセルを含む、材料内部で最大の球）もthickness_map/データセットとして出力されます。統計値、制限値を超える領域、最も厚い箇所を通るスライスも含まれます。表面には表示されない、壁とフランジの接合部にあるホットスポットなどの材料の蓄積を検出します。--map-max-thickness（デフォルト：部品の最小寸法。ただし最大64ボクセル）を超える厚さの材料には、その値が設定されます。凸状の端は、それが境界となる壁に含めます。

GUIでは、この処理は「Wall thickness」という操作として実行され、3Dビューに色付きの表面を「Wall thickness」として表示します（公称値と実測値を比較した場合は、公称厚さとの比較も表示します）。厚さマップはスライスビューのオーバーレイとして表示され、レポートには壁厚のセクションが追加されます（以下を参照）。方法と判断基準については、docs/adr/0030-wall-thickness.mdを参照してください。

気孔の分析

vs-porosity は、ふるい分けしたデータセットから内部の気孔と、微細組織が緩んだ領域を検出します。

./build/release/apps/vs-porosity/vs-porosity part.vsieve --out part.porosity

• porosity.json：部品の体積、気孔率、および中心、境界、空隙体積を含むすべての気孔と領域。
• projection_x.png、projection_y.png、projection_z.png：部品を厚さのグレースケール画像で表示し、気孔を赤、領域を黄色で表示します。
• porosity.vdb：データセットのワールド座標空間にあるグリッド pores と zones。Blender または Houdini で部品の横に表示できます。

気孔の体積はグレー値から算出するため、部分的に満たされた端のボクセルも、その割合に応じて数えます。領域は 8³ ブロックで、同じ深さにある表面下の材料レベルよりグレー値が明らかに低い部分です。そのため、ビームハードニングによるカッピングは気孔率として報告されません（docs/adr/0006-porosity-analysis.md を参照）。830 MB の合成スキャン（1025 × 775 × 525 ボクセル、ラウンカー6個、緩んだ領域3か所、ノイズおよび10 %のカッピング）では、すべてのラウンカーの体積が実際の体積との差2 %以内、すべての領域が2 %以内、全気孔率が1 %以内となり、4コアで分析に約30秒かかります。外気から3ボクセル以内のボクセルは領域検出から除外されます。そのため、部分体積の境界がブロックを通る斜面、フィレット、穴は、緩んだ材料として判定されません。 PorosityOptions と --min-pore、--zone-sigma、--zone-min オプションで検出のしきい値を設定します。

検査レポート

vs-report はポロシティ解析を実行し、検査指示書の合格基準と照合して評価したうえで、自己完結型の HTML ファイルとして試験レポートを作成します（ブラウザーから PDF に印刷できます）。

./build/release/apps/vs-report/vs-report part.vsieve --order examples/inspection_order.json \
    --out part.report

レポートは、ISO/IEC 17025（7.8）の報告内容と ISO 15708-3 の CT 試験レポートに沿って構成されています。内容は、指示書、部品、手法、スキャン設定、解析パラメーターと検出限界、投影画像とポア一覧を含む結果、評価、承認です。検査指示書（examples/inspection_order.json）には、顧客、部品番号、管電圧など、スキャンでは把握できない情報が記載されています。必須項目が不足している場合、レポートには「未記入」と表示され、警告が出力されます。

合否判定には BDG P 202 の方式を採用しています。検査ゾーン（データセット座標で指定するボックス、または部品全体）ごとに、最大ポア寸法、指定サイズを超えるポアの数、ポロシティ、微小組織の緩みを許容するかどうかについて、任意の限度値を設定できます。限度値は図面または顧客から指定されます。

vs-surface で生成した --surface part.vss を指定すると、レポートに部品とポアの 3D 表示が追加されます。部品はガラス状、ポアは赤、緩んだ領域は琥珀色で、実寸どおりに表示されます。vs-compare で生成した --comparison part.compare を指定すると、公称値と実測値の比較が追加されます。主要な数値、上方および下方から見た色付き偏差表示、偏差のヒストグラムが含まれます。vs-thickness で生成した --wall-thickness part.thickness を指定すると、肉厚に関する統計情報、色付き表示、ヒストグラム、薄い領域と厚い領域が追加されます。指示書の wall_thickness セクションで限度値を設定できます。また、max_area_below_min_mm2 を指定すると、最も薄い点だけで判定するのではなく、鋭いエッジなどに見られる小さな薄肉部を許容できます。解析で肉厚マップが出力されている場合（--volume-map）、レポートにはそのマップも表示され、max_mm で部品内部の最も厚い箇所も判定できます。CAD モデル（--nominal）を使用する場合、nominal_tolerance_mm で公称肉厚からの偏差を判定し、max_area_outside_nominal_mm2 で公称値を超える小さな領域を許容できます。

"wall_thickness": { "min_mm": 2.5, "max_mm": 8.0, "max_area_below_min_mm2": 5.0,
                    "nominal_tolerance_mm": 0.4, "max_area_outside_nominal_mm2": 5.0 }

GUI では、レポートのステップで、プロジェクトに存在する最新のサーフェス、比較結果、肉厚データが使用されます。表示のレンダリングは CPU 上で行われるため（voxelsieve/render.hpp）、GPU は必要ありません。

繊維複合材など、複数の材料で構成された部品の場合、GUI のレポートステップでは材料のセグメンテーション（グレイ値、体積、割合を含む材料情報、および材料ごとに色分けした断面）と繊維配向（方向、割合、ばらつきを含む繊維ファミリー情報、および方向ごとに色分けした断面）も使用されます。指示書の fibres セクションでは、繊維ファミリーごとに要件を設定できます。各要件は、公称方向に最も近い実測ファミリーと比較されます。

"fibres": { "families": [
  { "name": "Warp", "direction": [0, 0, 1], "tolerance_deg": 5,
    "min_share_percent": 40, "max_share_percent": 60 } ] }

レイアウトはテンプレートです。vs-report --print-template > my_template.html で組み込みテンプレートを出力し、--template my_template.html で独自のテンプレートを使用できます。テンプレートでは Mustache の一部機能（{{name}}、{{#list}}...{{/list}}、{{^name}}...{{/name}}）を使用します。出力先の report.json ですべての利用可能なデータを確認できます。docs/adr/0007-inspection-report.md を参照してください。

寸法測定と初品検査レポート

measure_dimensions 操作では、名目値と実測値の比較（compare_cad または compare_objects）で配置された CAD モデルを用いて、スキャン面上の図面の特性を 測定します。CAD モデルの座標を使った検査計画（examples/first_article_plan.json）では、 各要素をその上の点で指定します。平面、円柱、球、点を CAD モデル上で検出し、最小二乗法で スキャン面にフィッティングして、部品をデータム（3-2-1、RPS）に合わせるか、ベストフィットの 状態に保ちます。特性には、寸法（直径、半径、距離、角度、座標）、形状（平面度、円筒度、 球面度）、姿勢（平行度、直角度）、位置、輪郭、点の偏差があり、それぞれにバルーン番号、 公称値、公差が付与されます。GUI メソッドの cad_features は、CAD モデルの標準的な形状を 画像とともに一覧表示するため、CAD システムがなくても検査計画を作成できます。

first_article_report は初品検査レポートを作成します。表紙（サプライヤー、顧客、部品、 図面と改訂版、提出理由。examples/first_article_order.json から取得）、判定、公称値、 公差、実測値、結果を含む特性一覧、特性番号を赤と緑のバルーンで示した CAD モデルのビュー、 測定要素、さらにプロジェクトに含まれる場合は名目値と実測値の比較および受け入れ限度を 示したポロシティが含まれます。検査レポートと同様、差し替え可能なテンプレート （vs-report --print-first-article-template）から単一の HTML ファイルを作成し、あわせて report.json と characteristics.csv も出力します。フィッティングには最小領域法ではなく 最小二乗法を使用します。測定方法と制限事項については docs/adr/0027-dimensional-measurement.md を参照してください。

バッテリーセル

vs-battery（battery_inspection 操作）は、円筒型（缶に巻回電極を収めたもの）または 積層型（パウチ型、角形）のリチウムイオンセルを検査します。断面ごとのハウジングの直径、 真円度、へこみ、壁厚、コア、電極層の数と層間ギャップ、電極スタックの各端における各層の アノードの張り出し、電極端の不均一さ、層間の金属粒子やガス空隙を測定します。 --order examples/battery_order.json（battery_report 操作）を指定すると、注文の要件に 対するセルの適合性を判定する検査レポートを作成します。評価項目は、張り出し、層数、寸法、 真円度、壁厚、ギャップ、粒子、空隙です。

vs-battery --cell cylindrical --out cell --extension 3 1 0.35 40 100   # synthetic cell, defect
vs-sieve cell.raw --out cell.vsieve
vs-battery cell.vsieve --out cell_result --order examples/battery_order.json

合成セルでは、4 周目のカソードが上部の 60°にわたって突き出ています。レポートでは、 その層と角度が検出されます。

体積データではなく断面画像で提供された円筒型セルも検査できます。フォルダーまたは ZIP アーカイブに、セルごとのフォルダーを格納し、その中に axial_images/<angle>.png（軸を 通る縦断面。指定角度側が右半分、反対側が左半分、上段が高い側）と radial_images/<position mm>.png（横断面）を配置します。ハウジングと層は横断面から、 張り出しは各縦断面の両半分から、粒子と空隙はすべての画像から検出されます （battery_images 操作）。--image-cell を指定しない場合はすべてのセルを検査し、 cells.csv に概要を出力します。

vs-battery --images scans.zip --list-cells
vs-battery --images scans.zip --out results --order examples/battery_order.json

--pixel-size で指定しない場合、ピクセルサイズは縦断面の高さに対する横断面の位置から 算出されます。

セルの軸または積層面の法線は、体積データのいずれかの軸に沿っている必要があります。 測定方法と制限事項については docs/adr/0029-battery-cell-inspection.md を参照してください。

プロジェクト、操作、プラグイン

ライブラリでは、作業をプロジェクトとして記録します。プロジェクトはproject.jsonと、各ステップに1つずつのディレクトリで構成されます。 各ステップには、操作、パラメーター、入力、出力、メッセージが保存されます。元に戻す操作とやり直す操作ではステップ間のカーソルが移動し、元に戻した後で新しいステップを追加すると、元に戻したステップは破棄されます。操作によって入力が変更されることはありません。

voxelsieve::OperationRegistry registry;
voxelsieve::registerBuiltinOperations(registry);   // open_dataset, import_raw, import_tiff, porosity, …
registry.loadPlugins("plugins");                    // every *.so (*.dll) in the directory
auto project = voxelsieve::Project::create("casting.vsproj", "Casting 4711");
project.run(registry, "import_raw", {{"path", "scan.raw"}});
project.run(registry, "porosity");                  // input: the latest dataset
project.run(registry, "report", {{"order_path", "examples/inspection_order.json"}});
project.undo();

プラグインは、voxelsieve_plugin_api_version()とvoxelsieve_register_operations()をエクスポートする共有ライブラリです。examples/plugins/histogramは完全な実例です。docs/adr/0008-gui-projects-operations-ui.mdを参照してください。

GUI

vs-guiを起動するとGUIが立ち上がり、アドレスが表示されます。デフォルトはhttp://localhost:8410です。ブラウザーUIでは、データセットの選択（またはrawファイルのインポート）、気孔率解析などの操作の実行、検査レポートの作成という3つのステップを進めます。すべてのステップはパラメーターと結果とともにプロトコルに表示され、元に戻す（Ctrl+Z）ことややり直すことができます。プロジェクトは各ステップの後に保存されます。プラグインは組み込み操作の隣に表示されます。

ビューでは、x、y、z方向のスライスを表示します。ズームに合った解像度レベルから画面上のタイルだけを読み込むため、数百GBのスキャンでも高速に動作します。ホイールでズームし、ドラッグでパンします。矢印キー（またはShiftとホイール）でスライスを切り替えます。気孔は赤、緩み領域は黄色で色付けされ、一覧の気孔をクリックするとその位置に移動します。

3Dビューでは、ブラウザー内でデータセットの粗いレベル（各軸最大256ボクセル）をレイキャストします。「Surface」は、ヒストグラム上でドラッグして設定したしきい値で部品の表面をシェーディングします。「Transfer function」は、グレー値ごとに色と不透明度を合成します。「Maximum intensity projection」は、各レイ上で最も密度の高い値を表示します。伝達関数はヒストグラム上で編集します。クリックすると制御点が追加され、ドラッグすると移動し、ダブルクリックすると削除されます。各点には独自の色があり、カラーマップ（Steel、Viridis、Ember、Copper、Grey）を使うとすべての点の色を変更できます。また、プリセットを使って一般的な設定から始めることもできます。気孔と領域にはそれぞれ独自の色があり、ライティングはグレー値の勾配に従います。x方向に切り込むと部品が開きます。背景には、柔らかな明るい色、グラデーション、単色を設定できます。ドラッグすると部品が回転し、右ドラッグまたはShiftを押しながらドラッグすると移動し、ホイールでズームします。拡大表示時には、カメラに最も近い部品を、その場所で必要な解像度レベルで再び読み込み（領域を指定した/api/volume）、粗いボリュームに重ねてフェードインするため、見ている場所の解像度が上がります。

「Extracted surface」では、「Surface」操作の実行結果として、粗いレベルではなく、フル解像度の三角形メッシュで表面のみを表示します。平坦な領域には大きな三角形が使われ、三角形の予算（GET /api/surface?max_triangles=、デフォルトは150万）を超える表面は、予算内に収まるまでボクセルサイズを2倍ずつにして再サンプリングされます。こちらもx方向に切り込んで開くことができます。

ボリュームを読み込むと、ビューにはヒストグラムをもとにした2つまたは3つのレンダリング候補が、小さな画像とともに表示されます。素材の密度分布、素材より低密度の領域（気孔、緩んだ構造）や、介在物などのさらなるピーク、または部品をソリッドボディとして表示する候補です。

プロジェクトには表示状態が記憶されます。ステージ、スライス、ズームとウィンドウ、カメラ、伝達関数、色、背景は、再度開いたときに復元されます。「Save view」を使うと、現在のビューを名前と画像とともにプロジェクトに保存できます（views/<id>.png）。保存したビューをクリックすると再表示され、「Export image」では画像をダウンロードできます。ビューは処理ではなく表示用のため、ステップには含まれず、元に戻す操作の影響も受けません。

1つのプロジェクトには、複数のオブジェクトを保持できます。スキャンとCADモデル（STL）を1つのグローバル座標系に配置し、それぞれの姿勢も保持します（ADR 0018）。「Objects」ビューには、各オブジェクトが存在する位置に、それぞれの色で表示されます。次の手順を順に適用して位置合わせします。「Move」で手動移動し、「Align by point pairs」で両方のオブジェクト上にクリックした点を使って位置合わせし、「Best fit of the surfaces」で表面を最適に一致させます。最後の位置合わせは、オブジェクトの現在位置を基準に行うか、大きく離れている場合は主軸を基準に行います。続いて「Nominal-actual comparison」で、スキャンとCADモデル、または別のスキャンを、両方が存在する位置で比較します。その結果は3Dビューと、compare_cad と同様のレポートに表示されます。MCPでは、view_objects がシーンを画像として描画し、materials はセグメント化されたボリュームの各材料を、それぞれの色の表面として表示します。スライスビューには、表示中のボリュームのスライス内にある他のオブジェクトが表示されます。他のスキャンはその色を重ねて表示するか、市松模様で表示し、CADモデルは切断線として表示します。

スキャンに、立てているホルダーなど部品以外のものが含まれる場合、「Isolate part」（isolate_part）を使うと、指定領域（ボクセル単位のボックス）の外側にあるボクセルと、最大のオブジェクト以外のすべてのオブジェクトを除いたデータセットを書き出せます。そのため、セグメンテーション、ポロシティ、体積の解析を部品だけに対して行えます（ADR 0026）。接触しているオブジェクトは、互いに侵食して分離してから再び膨張させます（separate_voxels）。また、ボックスでは除去できない部分は、切断平面や円柱で切り取れます。材料セグメンテーションでは、材料数を自動で検出します。materials に 0 を指定すると、ヒストグラムのピークごと、またはガウス混合モデルが検出した肩や裾ごとに材料を分けます。この方法の提案結果とクラス境界にあるボクセルの割合は histogram で確認でき、preview_thresholds を指定した view_slice でクラスをプレビューできます。「Material meshes」（material_meshes）は、各材料の表面をSTLとして書き出し、その材料の色のオブジェクトとして追加します。「Measure objects」（measure_objects）は、材料ごとに連結した各オブジェクト、または内包された空気（材料 0。浮き袋や空洞など）を測定します。測定項目は体積、表面積、重心、バウンディングボックス、主軸に沿った長さ、および指定した軸に沿った長さで、表（objects.csv）として出力されます。

vs-gui --project /data/casting.vsproj --plugins build/release/plugins

サーバーは 127.0.0.1 のみで待ち受け、認証機能はありません。ネットワークに公開しないでください。

AIシステム：MCP

vs-gui --mcp は、Model Context Protocol（stdio）経由でGUIを提供するため、AIアシスタントからVoxelSieveを操作できます。プロジェクトの作成やオープン、処理の実行、元に戻す・やり直す操作、結果の読み取りが可能です。処理はお使いのマシン上で実行されます。スキャンデータはその場に留まり、アシスタントに渡されるのは、ポア一覧、測定値、スライス画像、レポートなどの結果だけです。

インストール。 すべてのリリースには、同じソースからビルドされた Linux（x64）、Windows（x64）、macOS（Appleシリコン）向けのパッケージがあります。

• voxelsieve-<version>-<platform>.mcpb：MCPバンドルです。Claude Desktopで開き（ダブルクリックするか、設定の「Extensions」ページにドラッグします）、スキャンのあるディレクトリを選択します。
• voxelsieve-<version>-<platform>.tar.gz / .zip：すべてのツールとライブラリが含まれています。任意の場所に展開してください。ほかにインストールするものはありません。
• voxelsieve-<version>-samples.zip：鋳造ハウジングの合成スキャンとそのCADモデル、検査手順、欠陥の正解データが含まれています。クイックスタートで使用します。
• ghcr.io/yoshi5534/voxelsieve：packaging/Dockerfile を使って Linux パッケージからビルドされたDockerイメージです。デフォルトではブラウザーUIが起動し、--mcp を指定するとMCPが起動します（クイックスタートを参照）。

パッケージにはまだ署名されていません。macOSでは、xattr -dr com.apple.quarantine voxelsieve-* を一度実行してダウンロード時のフラグを解除してください。Windowsでは、SmartScreenの確認が表示されることがあります。Linuxビルドには glibc 2.39 以降が必要です（Ubuntu 24.04、Debian 13、Fedora 40）。 展開したサーバーを、stdio サーバーとして任意の MCP クライアントに登録します。オプションの後に指定するディレクトリだけが、VoxelSieve がデータを読み込み、プロジェクトを保存する場所です。

claude mcp add voxelsieve -- /opt/voxelsieve/bin/vs-gui --mcp /data/scans   # Claude Code

{"mcpServers": {"voxelsieve": {"command": "/opt/voxelsieve/bin/vs-gui",
                               "args": ["--mcp", "/data/scans"]}}}

サーバーは最後に使用したプロジェクトを保持し、次回の起動時に再び開きます（--project で別のプロジェクトを指定するか、--no-reopen を指定した場合を除きます）。そのため、チャットごとに新しいサーバーを起動するクライアントでも、プロジェクトが開いた状態になります。

たとえば、「/data/scans/housing.raw をインポートし、気孔率を分析して、サンプルの注文書を使った検査レポートを作成してください」や、「最新のデータセットのスライス 400 を、気孔とともに表示してください」と依頼できます。クライアントは実行中のインポートや分析をキャンセルでき、次の進捗報告時に停止します。大きなスキャンのインポートや分析は、クライアントが 1 回の呼び出しを待つ時間を超える場合があります。background: true を指定すると、run_<operation> ツールはすぐに戻ります。wait は処理の完了まで追跡し（1 回の呼び出しにつき最大 50 秒）、完了時にそのステップを返します。cancel は処理を停止します。pipeline は、たとえばインポート、isolate_part、segment_materials、material_meshes など、複数の操作を 1 回の呼び出しで順番に実行します。

ツール：project_create、project_open、project_status、project_save_as、undo、redo、objects、results、object_select、dataset_info、histogram（しきい値と推奨材料数を含むグレー値のヒストグラム）、cad_features（検査計画用に、CAD モデルの平面、円柱、球を画像とともに表示）、view_slice（気孔と領域を含むスライス画像）、view_objects（材料ごとの色分け表示にも対応）、import_preview、step_telemetry、list_files、read_file（テキストファイルと画像としての PNG 画像）、browse、wait、cancel、pipeline、およびプラグインを含む各操作用の run_<operation>（--plugins <dir> または VOXELSIEVE_PLUGIN_PATH）。モデルが選ぶツールを絞るため、ブラウザー UI の保存済みビューを扱うメソッド（view_set、view_save、view_list、view_image、view_rename、view_delete）、list_operations（tools/list で全操作の説明を確認できます）、および object_add（run_open_dataset と run_add_mesh と同じ機能）は、--tools all を指定しない限り含まれません。ツールにはアノテーションが付いているため、クライアントは読み取り専用のツール（readOnlyHint）と、何かを削除するツール（destructiveHint）を判別できます。パラメーターのスキーマは各操作に基づき、エラーは理由とともにツールエラーとして返され、時間のかかる操作では進捗が報告されます。

リソース：プロジェクトの各ステップの結果ファイル（report.html、report.json、porosity.json、投影画像、比較結果、測定結果）は、voxelsieve://step/<id>/<output>/<file> として一覧表示されるため、クライアントはそれらを会話に添付できます。データセットがプロトコル経由で送信されることはなく、メタデータとこれらの結果のみが送信されます。

プロンプト：porosity_check（検査注文書に基づく気孔率の確認とレポート作成）、compare_with_cad（公称値と実測値の比較）、wall_thickness_check（図面の最小値に基づく壁厚の確認）、first_article_inspection（スキャン上で測定した図面の特性と初品検査レポート）、first_look（サイズ、ボクセルサイズ、3 つのスライス）を使うと、一般的な検査の手順をモデルに沿って進められます。

貢献

CONTRIBUTING.md を参照してください。コミットには Developer Certificate of Origin に基づく署名が必要です。

ライセンス

Apache-2.0 です。詳細は LICENSE を参照してください。サードパーティライブラリとそのライセンスは NOTICE に記載されています。