lithop 0.2.0 → 0.4.0

data/docs/local-ui.md

@@ -0,0 +1,117 @@
+# ローカルブラウザUI
+
+LithopのローカルUIは、画像選択から設定、変換、進捗確認、中止、プレビューと成果物の表示までをブラウザで行います。サーバーは`127.0.0.1`だけで待ち受け、画像や設定を外部サービスへ送信しません。
+
+## 起動する
+
+インストール済みのgemでは次を実行します。
+
+```sh
+lithop ui
+```
+
+ソースチェックアウトではBundlerを使います。
+
+```sh
+bundle exec lithop ui
+```
+
+端末に表示された`http://127.0.0.1:4567`をブラウザで開きます。別ポートまたは別プロジェクトを使う場合は次のように指定します。
+
+```sh
+lithop ui --port 4667 --project-dir /path/to/project
+```
+
+待受アドレスは変更できません。ブラウザは自動起動しないため、表示されたURLを明示的に開いてください。
+
+## 画面を移動する
+
+上部の主メニューで「作成」「ジョブ」「プリセット」を切り替えます。「作成」は画像・変換設定と入力プレビュー、「ジョブ」は履歴・進捗・生成結果、「プリセット」は名前付き設定と下書きの管理を表示します。主メニューは画面幅にかかわらず表示され、狭い画面では横方向に収まる簡潔な表示になります。
+
+画面を切り替えても、選択中の画像、編集値、設定区分の開閉、プレビューの倍率・位置、履歴の検索条件と選択状態を保持します。ブラウザの戻る・進むにも対応し、URLの`view`は表示画面、`job`は閲覧ジョブを表します。再読み込み後は画面とジョブを復元しますが、ブラウザの制約により入力画像は再選択が必要です。
+
+上部ヘッダーにはプロジェクト名、現在の画面、実行中ジョブの入力名・ID・状態・進捗を表示します。過去ジョブを閲覧しても実行中ジョブを別に追跡するため、上部の停止対象は変わりません。ジョブ表示を選ぶと実行中ジョブの詳細へ戻ります。「使い方」は同梱された簡易説明を開くため、外部サイトへ接続しません。
+
+## 画像と設定を選ぶ
+
+JPEG、PNG、SVGを1ファイル選択します。画面では次の設定を変更できます。
+
+- 完成幅・高さ、XYセル、任意の色セル
+- `cover`／`contain`、横・縦位置、クロップ倍率
+- 明るさ、コントラスト、彩度、淡色のWhite化
+- 色の積層順、Yellowへ混ぜる色と割合、ノズル径
+- 最小・最大厚み、上下左右のWhite余白
+- XYタイル数と配置、Z方向の別プレート化、色領域の分割数。Z分割の要約には8層、Base White層数、最小プレート厚を表示する。3分割時のZプレート3はBase White 3層とTop White 1層以上で最小0.34 mm
+
+画像はファイル選択欄へのドラッグ＆ドロップにも対応します。「変換を開始」と現在の準備状態は画像選択欄の直下にあり、詳細を開くと完成寸法、セル、画像調整、Yellow補正、分割方法を確認できます。設定は「基本設定」「画像配置」「画像調整」「Yellow補正」「分割」「詳細設定」に分かれます。「基本設定」には色の積層順を含み、「Yellow補正」にはYellowへ混ぜる色とYellow混色率をまとめ、初期状態では閉じています。幅と高さの交換、縦横比の固定、区分ごとの初期値への復元も利用できます。画像配置と画像調整はスライダーと数値入力が同期します。grid以外の行列数と、Z分割を使用しない場合の色領域分割数は送信されません。
+
+画像の準備中に開始した場合は最新画像の検証を待って1回だけ送信します。入力エラー時は該当する設定区分を開きます。変換後に設定や画像を変更すると変更項目数を示し、「表示中の変換ジョブ」には編集値と異なる設定名を表示します。編集中の入力と履歴から開いたジョブは別に管理されるため、新しい画像を選んでも過去ジョブの「補正後入力」は置き換わりません。
+
+初期値は選択したプロジェクトの`config/settings.json`と組み込み既定値から読みます。画面で確定した値はCLIと同じ`Settings`で検証され、White高さとCMYWレシピを作る共通の変換エンジンへ渡されます。
+
+「プリセット」画面では、左の保存設定ペインで名前付きプリセットまたは下書きを選び、右の管理ペインで現在の変換設定を保存・名前変更・削除できます。プリセットは作成への適用ができ、過去ジョブの「作成に適用」も同じ操作で現在値との差分を確認してから反映します。適用後は「作成」を表示し、現在選択している画像は置き換えません。画面移動は上部の主メニューへ統一しています。保存対象は画面で編集できる変換設定だけで、画像、一時入力ID、ジョブID、成果物パスは含みません。UI再起動後も設定は`config/ui-settings.json`から復元できますが、画像は再選択が必要です。このバージョン付きUI専用ファイルはGit追跡対象外で、`config/settings.json`を上書きしません。保存値は読込時にも共通`Settings`で検証し、未知の項目や非対応形式は理由を表示して適用しません。
+
+JPEG／PNGは選択直後に簡易表示し、その後、共通画像処理で確定した入力プレビューへ置き換えます。SVGはサーバー側で既存の安全性検証を通してからPNGへラスター化するため、未検証のSVGをブラウザへ直接読み込みません。確定した入力プレビューにはEXIF回転、ICCからsRGBへの変換、透過部分のWhite合成、完成寸法と余白、`cover`／`contain`、クロップ、明るさ・コントラスト・彩度が反映されます。設定変更は約250 ms単位で反映し、古い処理結果は新しい表示を上書きしません。
+
+入力プレビューは画面表示用の最大960 × 720画素に抑え、CMYW材料の選択やWhite厚みを予測しません。「タイル境界」を有効にすると、生成処理と同じXYセル境界計算による分割位置とIDを重ねて表示します。拡大後、または「100%」で画像が表示枠より大きいときは、マウスやタッチでドラッグして表示位置を移動できます。「全体表示」で倍率と位置を戻します。表示の拡大・縮小・移動と背景変更は画面だけに作用し、印刷寸法や生成設定には影響しません。
+
+「大きく表示」では入力を画面内の専用表示で確認できます。「大きく比較」では補正後入力と生成結果を同じ倍率・位置で並べます。専用表示はドラッグに加えて矢印キーで移動し、`+`／`-`で拡大・縮小、`0`で全体表示へ戻せます。Escまたは「閉じる」で元の操作箇所へ戻ります。
+
+15インチ級ノートの基準画角を1440 × 900 CSS pxとします。幅900pxを超える場合は「作成」の設定と入力プレビュー、「ジョブ」の履歴と詳細をそれぞれ左右に並べます。入力プレビューと履歴の追従位置は、折り返しを含む上部ヘッダーの実際の高さから決めます。幅900px以下では縦配置へ切り替え、ジョブ詳細の「一覧へ戻る」で履歴へ復帰します。物理インチはブラウザから一意に判定できないため、切り替えにはCSSピクセル幅を使います。
+
+## 変換の進捗と中止
+
+「変換を開始」を押すとページを再読み込みせずジョブ画面へ切り替え、選択画像、編集値、スクロール位置を保持したまま、PumaのUIプロセスとは別のRubyプロセスで変換します。開始後に設定を編集すると、実行した設定から変わったことを画面に表示します。画面は`build/.jobs/<job_id>.json`を読み、工程、進捗率、完了・失敗・中止を更新します。JavaScriptを利用できない場合は通常のフォーム送信へフォールバックします。
+
+変換ジョブには最終更新時刻と実行中の経過時間を表示します。一時的に状態を取得できない場合は、変換失敗と区別して通信エラーを示し、自動再接続と「状態を再取得」を利用できます。再取得では変換開始や停止要求を重複送信しません。失敗・停止後も編集内容を保持し、画像の再選択、設定の確認、対象ジョブのローカルログ表示へ移動できます。
+
+同じプロジェクトで同時に変換できる通常生成と校正生成は合計1件です。別の変換が動作中の場合、新しいジョブは失敗として表示されます。「停止」は最初に共通の協調停止を要求し、UIが起動した子プロセスが応答しない場合だけ、そのプロセスグループへ`TERM`、続いて`KILL`を送ります。UI再起動後のプロセスやCLIのプロセスなど、UIが所有を確認できない処理は強制終了しません。
+
+成果物ディレクトリを原子的に公開する直前が停止と完了の境界です。公開前の停止は`cancelled`となり未完成データを回収します。公開後に停止要求が届いた場合は成果物を保持して`completed`とします。子プロセスが異常終了した場合も、UIが終了を確認して状態と一時データを再照合します。
+
+### 一時ファイルとローカル性
+
+選択後の画像はランダムIDの`build/.previews/`へ一時保存し、画像交換、画面離脱、変換開始時に回収します。異常終了で残ったものは24時間経過後のUI起動時に回収します。変換開始後は`build/.web/`へコピーし、子プロセスの終了後に回収します。完了済みの`build/<job_id>/`には入力画像をコピーしません。
+
+## 成果物を確認する
+
+完了すると、ジョブ詳細を「プレビュー」「成果物」「設定・ログ」のタブで表示します。左右矢印キーでもタブを移動できます。「プレビュー」では補正後入力と生成結果を並べ、変換時の完成幅と高さに追従した表示枠で確認します。表示種別は、仕上がりから材料、解析、配置へ確認を進められるように、`CMYW → Cyan → Magenta → Yellow → White → 透過明度 → 厚み → タイル`の順で表示します。利用できない成果物は飛ばし、残る項目の順序は変えません。拡大・縮小・移動と背景変更も利用できます。「成果物」ではXY分割の全体図からタイルを選び、行列位置、実寸、完成全体での配置座標、プレート数、タイルプレビュー、3MF保存リンクを確認できます。「設定・ログ」では生成時の設定とローカルログへのリンクを確認できます。値は`manifest.json`を基準にします。過去ジョブにタイルプレビューや補正後入力がない場合は理由を表示し、存在する全3MFは引き続き表示します。成果物リンクはモデル、画像・配置、設定・記録、印刷説明に分類します。3MFとSTLはダウンロードとして扱い、画像とテキストはブラウザで開けます。
+
+macOSでは、完了ジョブの各3MFに「Bambu Studioで開く」を表示します。未分割の`lithop.3mf`とXY分割された各タイルを1ファイルずつ選択できます。ボタンは保存済み3MFを変更せず、macOSへBambu Studioで開く要求を渡します。成功表示は要求をOSへ渡せたことを示すため、Bambu Studio側で対象ファイル、材料、プレート、寸法を確認してください。Bambu Studioで既存プロジェクトを開いている場合、アプリの状態によって別の3MFが表示されないことがあります。その場合も現在の作業は置き換えず、同じ行の「3MFを保存」から開けます。起動できない場合もZIP取得を利用できます。未保存プロジェクトの確認には自動応答しません。
+
+最近のジョブには入力名、状態、進捗、完成寸法、タイル数、作成日時を表示します。状態で絞り込み、12件単位で追加表示できます。履歴から別のジョブを開くと、そのジョブに保存された`corrected-input.png`を「補正後入力」へ表示し、編集中の画像と設定は保持します。履歴は`build/.jobs/`の記録から復元されるため、UIを再起動しても完了済み成果物を開けます。この成果物を持たない旧ジョブでは補正後入力を復元できません。
+
+履歴は入力名・ジョブIDの検索、開始日・終了日、状態、作成日時または入力名による並び替えに対応します。検索と絞り込みはサーバー側で履歴全体へ適用し、12件単位で取得します。完了ジョブには`preview.png`を遅延読み込みするサムネイルを表示します。履歴を開くだけでは全画像を読み込まず、ZIPも生成しません。
+
+完了ジョブを2件選択して「2件を比較」を押すと、入力名、ジョブID、日時、寸法と生成画像を左右に表示します。比較の表示種別も通常プレビューと同じ順序に統一し、倍率、移動位置、背景を同期します。設定差は寸法、セル、配置、画像調整、厚み、分割に限って表にします。異なる縦横比は各画像の比率を保ち、片方にしかない画像や削除済みジョブを別ジョブの画像で補いません。比較から採用する設定は差分確認後に編集欄へ読み込めます。画面上の色比較は実測透過色を保証しません。
+
+完了ジョブの成果物欄では、全3MFまたは全成果物をZIPで取得できます。生成前に対象の相対パス、件数、容量を表示し、状態JSONの`files`に成果物として記録されたファイルだけを格納します。ZIPの一時ファイルは送信完了または失敗時に削除し、UI再起動時にも残存分を回収します。
+
+`completed`、`failed`、`cancelled`のジョブは、画面に表示するファイル数と容量を確認して個別に削除できます。削除対象は選択したジョブの成果物、状態JSON、ログ、中止要求、終了を確認できるUI一時データです。実行中と停止要求中のジョブは削除できません。削除は元に戻せず、他のジョブ、元画像、`config/settings.json`には影響しません。
+
+終了済みジョブは複数選択して一括削除もできます。実行前に件数、ID、合計容量を表示し、実行中ジョブは対象にできません。各ジョブに個別削除と同じ安全確認を適用し、一部だけ失敗した場合は削除できなかったIDと理由を残します。
+
+印刷前の確認手順は[Bambu Studioでの確認と印刷](bambu-studio.md)、全ファイルの意味は[生成物と記録](artifacts.md)、分割出力は[3MFタイル分割とZ分割](tiling.md)を参照してください。
+
+## 採用した構成
+
+ローカルUIにはSinatra 4、ERB、Puma 7を採用しました。既存のRuby実装へ小さなHTTP層を追加でき、サーバー側の入力検証とテンプレートを共通管理しながら、重い変換を別プロセスへ分離できるためです。
+
+ERBテンプレート、CSS、JavaScriptはRubyGemへ同梱します。画面は外部CDN、Webフォント、外部JavaScriptを読み込まないため、gemとlibvipsの導入後はオフラインで動作します。状態を変えるリクエストには起動ごとのトークンを要求し、成果物はジョブ状態に記録された`build/`内のファイルだけを配信します。
+
+## 開発時のブラウザ試験
+
+実ブラウザの回帰試験にはPlaywrightを使用します。Node.jsとPlaywrightは開発時だけの依存関係であり、インストール済みRubyGemの実行には不要です。Node.js 22を用意し、初回だけ依存関係と固定ブラウザを導入します。
+
+```sh
+npm install
+npx playwright install chromium webkit
+```
+
+試験は一時プロジェクトと専用ポートでUIを起動し、通常の`build/`を変更しません。
+
+```sh
+npm run test:browser
+```
+
+ChromiumとWebKitで、画像選択直下の開始操作、プレビュー準備中を含むジョブ作成、設定保持、設定区分メニュー、プリセットの2ペイン操作、タイル境界、Z分割項目、成果物切り替え、Bambu Studioへ渡す3MFの選択、拡大専用表示、同期した比較、全体図からのタイル選択、通信切断からの復帰、設定再利用、2ジョブ比較、履歴検索、ZIP取得、複数削除、停止、主メニュー、画面間の状態保持、戻る・進む、共通ヘッダーの停止、ジョブ詳細のキーボード操作を確認します。1440 × 900、1024 × 768、600 × 800、390 × 844と200%表示相当のCSS表示領域では、横方向のはみ出しとペイン配置も検査します。試験では起動処理を差し替え、Bambu Studioを実際には起動しません。失敗時のスクリーンショット、動画、トレースは`tmp/playwright-results/`へ保存します。受入ブラウザは実機Chromeとし、WebKitはブラウザエンジン間の回帰検証に使用します。

data/docs/tiling.md

@@ -1,6 +1,6 @@
 # 3MFタイル分割とZ分割
 
-Lithopは、1枚では印刷できない大きさのリトファンを、指定枚数のCMYW 3MFへXY方向に分割できます。分割後も、完成時の幅・高さ、White厚み、CMYWレシピ、画像の向きは変わりません。必要なら各タイルを、CMYW色領域と上部Whiteの4プレートにZ方向へ分けられます。
+Lithopは、1枚では印刷できない大きさのリトファンを、指定枚数のCMYW 3MFへXY方向に分割できます。XY分割後も、完成時の幅・高さ、White厚み、CMYWレシピ、画像の向きは変わりません。必要なら各タイルを連続プレートへZ方向に分けられます。分割プレートには強度を確保するBase Whiteをそれぞれ追加し、第1層を0.10 mm、以降を0.08 mm積層ピッチに統一します。3分割時のZプレート3はBase White 3層とTop White 1層のWhite合計4層となり、最小厚みは0.34 mmです。
 
 このページでは、タイルの数と配置、出力座標、Bambu Studioで確認する対象を定義します。材料、積層構造、Z境界は[CMYWの色モデルと積層構造](color-model.md)、入力値の全一覧は[生成オプションと設定ファイル](config.md)を参照してください。
 
@@ -10,10 +10,10 @@ Lithopは、1枚では印刷できない大きさのリトファンを、指定
 | --- | --- | --- |
 | 通常の1枚出力 | 既定値 | `lithop.3mf`を1つ。Bambu Studioでは1プレート |
 | XY方向の分割 | `tile_count: 2`以上 | `tiles/tile_rNN_cNN.3mf`を指定枚数。各ファイルは1プレート |
-| Z方向の分割 | `separate_z_parts: true` | 各3MFに、3つの`Color region`と`Top White`の4プレート |
-| XYとZの併用 | 両方を指定 | タイルごとに4プレートを持つ3MF |
+| Z方向の分割 | `separate_z_parts: true` | 各3MFの完成モデルを連続Z範囲へ分割。標準設定では3プレート |
+| XYとZの併用 | 両方を指定 | タイルごとに同じZプレート構成を持つ3MF |
 
-`cmyk_white.stl`、`preview.png`、`transmission.png`、`thickness.png`、材料マスクは、常に分割前の完成全体を表します。XY分割時だけカラー3MFは`tiles/`へ出力され、ルートに`lithop.3mf`は作りません。
+`cmyk_white.stl`、`preview.png`、`transmission.png`、`thickness.png`、材料マスクは、常に分割前の完成全体を表します。Z分割したカラー3MFでは元モデルのBase White 1層を除外し、各プレート専用のBase Whiteへ置き換えます。3分割時はZプレート1・2が1層、Zプレート3が3層です。XY分割時だけカラー3MFは`tiles/`へ出力され、ルートに`lithop.3mf`は作りません。各3MFに対応する`tiles/tile_rNN_cNN-preview.png`も生成し、ローカルUIの変換ジョブでは全タイルを同時に確認できます。
 
 ## XY方向のタイル分割
 
@@ -74,7 +74,7 @@ JSON設定ファイルでは次のように指定します。
 
 複数のタイルを1つの完成物として配置する場合は、各3MFの材料部品を動かさず、対応する`offset_mm`を使ってタイル全体を配置します。`tile-layout.svg`と`manifest.json`は、その配置を復元するための正本です。
 
-## Z方向の4プレート分割
+## Z方向のプレート分割
 
 `--separate-z-parts`を指定すると、各3MFのZ方向を複数のBambu Studioプレートへ分けます。
 
@@ -82,24 +82,23 @@ JSON設定ファイルでは次のように指定します。
 lithop image.svg --separate-z-parts
 ```
 
-標準の7層CMYW色領域と既定の`--color-region-parts 3`では、Bambu Studioで次の4プレートを開きます。
+`--color-region-parts`はZプレート数を1〜3で指定します。Z分割では色領域を8層・0.64 mmへ変更します。3を指定した場合は元モデルのBase White 1層を除外し、0.32 mmの均等な元Z範囲を各プレートへ割り当てます。CMYとTop Whiteの積層ピッチは0.08 mmです。8層のCMY領域はZプレート1・2に収まり、Zプレート2の上端Z=0.74 mmで終了します。Zプレート1・2のBase Whiteは1層・0.10 mmです。Zプレート3はCMYを含まないため、Base Whiteを3層・0.26 mmとし、最薄部をTop White 1層と合わせてWhite合計4層・0.34 mmにします。3枚を組み立てた最薄部は1.18 mm、最大厚みは2.30 mmです。
 
-| プレート | 元のZ範囲 | 内容 |
-| --- | --- | --- |
-| `Color region 1` | 0.2–0.5 mm | 3層のCMYW色領域と0.0–0.2 mmのBase Whiteキャリア |
-| `Color region 2` | 0.5–0.7 mm | 2層のCMYW色領域とBase Whiteキャリア |
-| `Color region 3` | 0.7–0.9 mm | 2層のCMYW色領域とBase Whiteキャリア |
-| `Top White` | 0.9 mm–可変上面 | 色領域より上のWhite |
+| プレート | 元のZ範囲 | 印刷時の厚み | 内容 |
+| --- | --- | ---: | --- |
+| `Z plate 1` | 0.10–0.42 mm | 0.42 mm | Base White第1層0.10 mm + CMYW色領域0.32 mm |
+| `Z plate 2` | 0.42–0.74 mm | 0.42 mm | Base White第1層0.10 mm + CMYW色領域0.32 mm |
+| `Z plate 3` | 0.74–1.06 mm（最大1.94 mm） | 0.34–1.46 mm | Base White 3層0.26 mm + Top White 0.08–1.20 mm（CMYなし） |
 
-各プレートは単独印刷できるよう、出力3MFでは底面が`Z=0`になります。Base Whiteだけのプレートは作りません。Base Whiteキャリアは各`Color region`に含まれ、使用されるCyan、Magenta、Yellowの閉じた部品と同じ領域を支えます。未使用の顔料部品は省略されますが、Extruder番号はCyan=1、Magenta=2、Yellow=3、White=4のままです。
+Base Whiteの元のZ範囲0.0–0.1 mmは、Z分割3MFへそのまま出力しません。Zプレート1・2へ専用のBase White 1層・0.10 mm、Zプレート3へ3層・0.26 mmを追加し、その上へ8層の色領域とTop Whiteを連続するZ範囲として1回だけ配置します。3枚を元の順番で重ねた厚みは`1.18–2.30 mm`です。可変厚みはTop Whiteだけへ加えます。未使用の顔料部品は省略されますが、Extruder番号はCyan=1、Magenta=2、Yellow=3、White=4のままです。
 
-`color_region_parts`は1から色層数まで指定できます。既定の3は7層を3・2・2層に分けます。値を変えると領域数と各領域のZ境界が変わるため、印刷前に生成ジョブの`manifest.json`にある`color_model.z_part_separation.plates`を確認してください。この記録には、元のZ境界、各プレートでの印刷厚み、積層順、部品名が入ります。
+`color_region_parts`は1〜3を指定でき、指定数どおりに出力します。生成ジョブの`manifest.json`には`requested_parts`、`resolved_parts`、`minimum_source_plate_thickness`、`minimum_plate_thickness`、`adjusted_minimum_total_thickness`、Base Whiteの層数と厚み、各プレートの元のZ境界、最大印刷厚み、最小印刷厚み、積層順を記録します。
 
-分離したZ部品を印刷後に組み立てる場合は、`Color region 1`から`Top White`まで、マニフェストの積層順どおりに同じXY位置で重ねます。各プレート内の部品を移動、整列、拡大縮小、結合してはいけません。
+分離したZ部品を印刷後に組み立てる場合は、`Z plate 1`から順に、マニフェストの積層順どおりに同じXY位置で重ねます。各プレート内の部品を移動、整列、拡大縮小、結合してはいけません。
 
 ## XY分割とZ分割を併用する
 
-次の例は、完成全体を横2枚へ分け、各タイルを4プレートにします。
+次の例は、完成全体を横2枚へ分け、各タイルを標準設定の3プレートにします。
 
 ```sh
 lithop image.svg --tile-count 2 --tile-layout columns --separate-z-parts
@@ -112,8 +111,10 @@ build/<job_id>/
 ├── cmyk_white.stl
 ├── tile-layout.svg
 ├── tiles/
-│   ├── tile_r01_c01.3mf  # Color region 1–3、Top Whiteの4プレート
-│   └── tile_r01_c02.3mf  # Color region 1–3、Top Whiteの4プレート
+│   ├── tile_r01_c01.3mf  # Z plate 1–3
+│   ├── tile_r01_c01-preview.png
+│   ├── tile_r01_c02.3mf  # Z plate 1–3
+│   └── tile_r01_c02-preview.png
 ├── manifest.json
 ├── settings.json
 └── preview.png ほか
@@ -126,7 +127,7 @@ build/<job_id>/
 1. `preview.png`、`thickness.png`、4枚の材料マスクで、分割前の色・厚みが意図どおりか確認する。
 2. XY分割時は`tile-layout.svg`と`manifest.json`で、枚数、ID、完成全体での位置、タイル寸法を確認する。
 3. 各タイル3MFをBambu Studioで開き、Cyan=1、Magenta=2、Yellow=3、White=4の材料割り当てを確認する。
-4. Z分割時は4プレートと各`Color region`・`Top White`の部品を確認し、`manifest.json`のZ境界と積層順に合わせる。
+4. Z分割時は生成された全`Z plate`を確認し、`manifest.json`の解決後プレート数、最小厚み、Z境界、積層順に合わせる。
 5. すべてのレイヤーを確認してからスライスする。Lithopはスライス、造形可否の判定、印刷開始を行わない。
 
 分割した実機での継ぎ目の位置ずれ、色差、光漏れはまだ評価対象です。小さい入力と少数タイルで、Bambu Studioのレイヤープレビューを確認してから完成寸法へ進めてください。

data/docs/troubleshooting.md

@@ -21,6 +21,16 @@ bundle exec lithop --version
 
 **関連:** [導入と基本操作](getting-started.md#インストール)
 
+## Rustネイティブ拡張をビルドできない
+
+**症状:** `gem install lithop`または`bundle exec rake compile`が、Cargo、Rustコンパイラ、`rb_sys`に関するエラーで終了します。
+
+**原因候補:** Rustツールチェーンが未導入、またはRubyを切り替えた後にネイティブ拡張を再ビルドしていません。
+
+**対処:** macOSでは`brew install rust`を実行し、`rustc --version`と`cargo --version`を確認してからLithopを再インストールします。ソースチェックアウトでは`bundle install`に続けて`bundle exec rake compile`を実行します。`lithop doctor`で`backend: rust`と拡張バージョンを確認できます。Ruby版との比較用に`LITHOP_DISABLE_NATIVE=1`を指定できますが、インストール時の拡張ビルドを省略する設定ではありません。
+
+現在のCI対象はmacOSとRuby 4.0で、実測環境はApple siliconです。他のOS、CPU、Ruby ABI向けのビルド済みgemは配布せず、0.4.0は利用環境でRust拡張をビルドするソースgemとして扱います。
+
 ## 入力画像を読めない
 
 **最初の確認:** ファイルが実在し、JPEG、PNG、またはSVGとして画像アプリで開けるか確認します。
@@ -57,9 +67,9 @@ bundle exec lithop --version
 
 **最初の確認:** 色領域の層数、第1層、通常レイヤー、要求最小・最大厚さを確認します。
 
-**原因候補:** 選択した層構造に、下地White、色領域、`top_white_start`までのWhite領域、設定された最小上部White層を収容できません。メッセージ中の最小値は現在の設定から計算されます。標準設定の`minimum_top_white_layers`は`0`です。
+**原因候補:** 選択した層構造に、下地White、色領域、`top_white_start`までのWhite領域、設定された最小上部White層を収容できません。メッセージ中の最小値は現在の設定から計算されます。標準設定の`minimum_top_white_layers`は`1`です。
 
-**対処:** `--min-thickness`または`--max-thickness`を必要最小厚さ以上にします。標準の7層構造では1.0 mmです。
+**対処:** `--min-thickness`または`--max-thickness`を必要最小厚さ以上にします。標準の7層構造では0.74 mmです。
 
 **関連:** [レイヤー境界と実効厚さ](config.md#レイヤー境界と実効厚さ)
 

data/ext/lithop_native/Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "lithop_native"
+version = "0.4.0"
+edition = "2021"
+publish = false
+license = "MIT"
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+libc = "0.2"
+magnus = "0.8.2"
+rb-sys = { version = "0.9", features = ["stable-api-compiled-fallback"] }
+
+[build-dependencies]
+rb-sys-env = "0.2.2"

data/ext/lithop_native/build.rs

@@ -0,0 +1,4 @@
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let _ = rb_sys_env::activate()?;
+    Ok(())
+}

data/ext/lithop_native/extconf.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require "mkmf"
+require "rb_sys/mkmf"
+
+create_rust_makefile("lithop_native/lithop_native")