lithop 0.1.0 → 0.3.0

data/docs/command.md

@@ -1,6 +1,6 @@
 # コマンドリファレンス
 
-このページはCLI構文とオプションの正本です。実行中の版では`lithop --help`、`lithop calibrate --help`、`lithop clean --help`でも確認できます。ソースチェックアウトでは、例の`lithop`を`bundle exec lithop`に読み替えてください。
+このページはCLI構文とオプションの正本です。実行中の版では`lithop --help`、`lithop calibrate --help`、`lithop ui --help`、`lithop clean --help`でも確認できます。`lithop doctor`はRust拡張の状態をJSONで表示します。ソースチェックアウトでは、例の`lithop`を`bundle exec lithop`に読み替えてください。
 
 ## 画像からリトファンを生成する
 
@@ -19,8 +19,14 @@ Usage: lithop IMAGE [options]
 | オプション | 型 | 既定値 | 説明 |
 | --- | --- | ---: | --- |
 | `--layout-profile NAME` | String | `standard` | 標準構造を選ぶ。現在は`standard`のみ |
-| `--width MM` | Float | `130` | 完成幅をmm単位で指定する |
-| `--height MM` | Float | `100` | 完成高さをmm単位で指定する |
+| `--width MM` | Float | `140.0` | 完成幅をmm単位で指定する |
+| `--height MM` | Float | `104.0` | 完成高さをmm単位で指定する |
+| `--tile-count COUNT` | Integer | `1` | 出力する3MFタイルの総数を指定する |
+| `--tile-layout MODE` | String | `auto` | `auto`、`columns`、`rows`、`grid`から配置を選ぶ |
+| `--tile-rows COUNT` | Integer | なし | `grid`配置の行数を指定する |
+| `--tile-columns COUNT` | Integer | なし | `grid`配置の列数を指定する |
+| `--separate-z-parts` | — | 無効 | 下地White、CMYW色領域、上部Whiteを別プレートにする |
+| `--color-region-parts COUNT` | Integer | `3` | CMYW色領域のZ方向の分割数を指定する |
 | `--margin-top MM` | Float | `0` | 上側のWhite余白をmm単位で指定する |
 | `--margin-right MM` | Float | `0` | 右側のWhite余白をmm単位で指定する |
 | `--margin-bottom MM` | Float | `0` | 下側のWhite余白をmm単位で指定する |
@@ -29,6 +35,9 @@ Usage: lithop IMAGE [options]
 | `--crop-position-x FRACTION` | Float | `0.5` | 横方向の配置を左`0`から右`1`で指定する |
 | `--crop-position-y FRACTION` | Float | `0.5` | 縦方向の配置を上`0`から下`1`で指定する |
 | `--crop-scale FRACTION` | Float | `1.0` | `0`より大きく`1`以下の切り出し倍率を指定する |
+| `--brightness PERCENT` | Float | `0` | sRGB明るさを`-100`〜`100`で補正する |
+| `--contrast PERCENT` | Float | `0` | sRGBコントラストを`-100`〜`100`で補正する |
+| `--saturation PERCENT` | Float | `0` | sRGB彩度を`-100`〜`100`で補正する |
 | `--min-thickness MM` | Float | `1.0` | 要求最小厚さをmm単位で指定する |
 | `--max-thickness MM` | Float | `2.14689422` | 要求最大厚さをmm単位で指定する |
 | `--pixel-size MM` | Float | `0.22` | XYセル寸法をmm単位で指定する |
@@ -67,6 +76,8 @@ SVGをPNGへ書き出さずに生成します。
 lithop image.svg --width 20 --height 15 --pixel-size 0.5
 ```
 
+タイル分割とZ分割のコマンド例、配置、成果物は[3MFタイル分割とZ分割](tiling.md)を参照してください。
+
 完成寸法を変えず、上下1 mm、左右2 mmのWhite余白を設けます。
 
 ```sh
@@ -85,6 +96,12 @@ lithop image.png --crop-position-x 1 --crop-scale 0.8 --pixel-size 0.25 --color-
 lithop image.png --image-fit contain
 ```
 
+明るさを10%上げ、コントラストを15%、彩度を20%強めます。指定値は出力の`settings.json`へ保存され、同じCLIまたは入力設定JSONで再現できます。
+
+```sh
+lithop image.png --brightness 10 --contrast 15 --saturation 20
+```
+
 別のプロジェクトと入力設定を使います。
 
 ```sh
@@ -99,17 +116,18 @@ lithop image.png --calibration-profile build/<calibration-job-id>/calibration-pr
 
 ### 出力
 
-書き出し前にWhite参照STL、CMYW 3MF、材料別3MFの三角形数を表示します。成功時は確定した三角形数、ジョブディレクトリの絶対パス、ファイル一覧を表示します。
+画像処理、White高さ、材料モデル、メッシュ計画、3MF、プレビュー、メタデータの進捗を百分率で表示します。書き出し前にWhite参照STL、CMYW 3MF、材料別3MFの三角形数を表示し、成功時は確定した三角形数、ジョブディレクトリの絶対パス、ファイル一覧を表示します。
 
 ```text
 Estimated ... STL and ... CMYW 3MF triangles before writing
   CMYW by material: cyan=..., magenta=..., yellow=..., white=...
+Progress ...%: ...
 Generated ... STL and ... CMYW 3MF triangles
 in /absolute/path/to/build/<job_id>
   ...
 ```
 
-一時出力、完了済みジョブ、各ファイルは[生成物と記録](artifacts.md)を参照してください。
+通常生成と校正生成を合わせて、同じプロジェクトで同時に実行できる変換は1件です。`Ctrl-C`で中止したジョブは`cancelled`になり、一時出力を回収して成果物ディレクトリを公開しません。状態、一時出力、完了済みジョブ、各ファイルは[生成物と記録](artifacts.md)を参照してください。
 
 ## 校正片を生成する
 
@@ -138,7 +156,28 @@ Usage: lithop calibrate [options]
 lithop calibrate
 ```
 
-固定レイアウトのため、画像用の`width`、`height`、`margin_*`、画像配置、`pixel_size`、`color_pixel_size`、`maximum_input_pixels`は使いません。生成物は[校正ジョブのファイル](artifacts.md#校正ジョブのファイル)、測定方法は[色校正](calibration.md)を参照してください。
+固定レイアウトで入力画像を使わないため、画像用の`width`、`height`、`margin_*`、画像配置、明るさ・コントラスト・彩度、`pixel_size`、`color_pixel_size`、`maximum_input_pixels`は使いません。生成物は[校正ジョブのファイル](artifacts.md#校正ジョブのファイル)、測定方法は[色校正](calibration.md)を参照してください。
+
+## ローカルUIを起動する
+
+画像選択、主要設定、プレビュー、進捗・中止、成果物表示を行うブラウザUIを`127.0.0.1`で起動します。
+
+```text
+Usage: lithop ui [--project-dir DIR] [--port PORT]
+```
+
+| オプション | 型 | 既定値 | 説明 |
+| --- | --- | ---: | --- |
+| `--project-dir DIR` | Path | 現在のディレクトリ | 設定を読み、`build/`を作るプロジェクトを選ぶ |
+| `--port PORT` | Integer | `4567` | ローカルUIのポートを1〜65535で指定する |
+| `-v`, `--version` | — | — | バージョンを表示して終了する |
+| `-h`, `--help` | — | — | ヘルプを表示して終了する |
+
+```sh
+lithop ui
+```
+
+表示された`http://127.0.0.1:4567`をブラウザで開きます。詳細は[ローカルブラウザUI](local-ui.md)を参照してください。
 
 ## 生成物を削除する
 
@@ -163,13 +202,15 @@ lithop clean --project-dir /path/to/project
 
 `build/`がなければ正常終了します。ファイルシステムのルート、`build`自体がシンボリックリンク、または`build`がディレクトリではない場合は削除を拒否します。
 
-## バージョンとヘルプを表示する
+## バージョン、診断、ヘルプを表示する
 
 | コマンド | 内容 |
 | --- | --- |
 | `lithop --version` | バージョンを表示する。短縮形は`lithop -v` |
+| `lithop doctor` | Rustバックエンドのロード・有効状態、拡張とLithopのバージョン、Ruby、実行プラットフォームをJSONで表示する |
 | `lithop --help` | 通常生成の構文とオプションを表示する |
 | `lithop calibrate --help` | 校正片生成の構文とオプションを表示する |
+| `lithop ui --help` | ローカルUIの起動オプションを表示する |
 | `lithop clean --help` | 削除コマンドの構文とオプションを表示する |
 
 ## 終了ステータスとエラー

data/docs/config.md

@@ -30,12 +30,21 @@
   "crop_position_x": 0.5,
   "crop_position_y": 0.5,
   "crop_scale": 1.0,
+  "brightness": 0.0,
+  "contrast": 0.0,
+  "saturation": 0.0,
   "minimum_thickness": 1.0,
   "maximum_thickness": 2.14689422,
   "pixel_size": 0.5,
   "color_pixel_size": null,
   "grid_columns": null,
   "grid_rows": null,
+  "tile_count": 1,
+  "tile_layout": "auto",
+  "tile_rows": null,
+  "tile_columns": null,
+  "separate_z_parts": false,
+  "color_region_parts": 3,
   "first_layer_height": 0.1,
   "layer_height": 0.1,
   "base_white_layers": 2,
@@ -84,12 +93,21 @@ lithop image.png --config presets/fine.json
 | `crop_position_x` | `--crop-position-x FRACTION` | `0.5` | 左`0`から右`1`までの横位置 |
 | `crop_position_y` | `--crop-position-y FRACTION` | `0.5` | 上`0`から下`1`までの縦位置 |
 | `crop_scale` | `--crop-scale FRACTION` | `1.0` | 切り出し矩形または収容画像の倍率 |
+| `brightness` | `--brightness PERCENT` | `0.0` | sRGB明るさ補正。`-100`〜`100` |
+| `contrast` | `--contrast PERCENT` | `0.0` | sRGBコントラスト補正。`-100`〜`100` |
+| `saturation` | `--saturation PERCENT` | `0.0` | sRGB彩度補正。`-100`〜`100` |
 | `minimum_thickness` | `--min-thickness MM` | `1.0` | 要求最小厚さmm |
 | `maximum_thickness` | `--max-thickness MM` | `2.14689422` | 要求最大厚さmm |
 | `pixel_size` | `--pixel-size MM` | `0.22` | XYセル寸法mm |
 | `color_pixel_size` | `--color-pixel-size MM` | `null` | `pixel_size`以上のCMYW色セル寸法。`null`は同じ寸法 |
-| `grid_columns` | なし | `591` | fit格子の列数。寸法または`pixel_size`指定時は未指定扱い |
-| `grid_rows` | なし | `455` | fit格子の行数。寸法または`pixel_size`指定時は未指定扱い |
+| `grid_columns` | なし | `637` | fit格子の列数。寸法または`pixel_size`指定時は未指定扱い |
+| `grid_rows` | なし | `473` | fit格子の行数。寸法または`pixel_size`指定時は未指定扱い |
+| `tile_count` | `--tile-count COUNT` | `1` | 出力する3MFタイルの総数 |
+| `tile_layout` | `--tile-layout MODE` | `auto` | `auto`、`columns`、`rows`、`grid` |
+| `tile_rows` | `--tile-rows COUNT` | `null` | `grid`配置の行数 |
+| `tile_columns` | `--tile-columns COUNT` | `null` | `grid`配置の列数 |
+| `separate_z_parts` | `--separate-z-parts` | `false` | 下地White、CMYW色領域、上部WhiteをZ方向の別プレートにする |
+| `color_region_parts` | `--color-region-parts COUNT` | `3` | Z分離時のCMYW色領域の分割数 |
 | `first_layer_height` | `--first-layer-height MM` | `0.1` | 下地Whiteの層高mm |
 | `layer_height` | `--layer-height MM` | `0.1` | CMYW色領域の積層ピッチmm |
 | `base_white_layers` | なし | `2` | 色領域より下のWhite層数 |
@@ -123,8 +141,12 @@ SVGでは、通常の厚さ格子と`color_pixel_size`を指定した色格子
 
 `image_fit=cover`は出力領域を満たして余分を切り出し、`contain`は画像全体を収めて残りをWhiteにします。`crop_position_x`と`crop_position_y`は、`cover`では切り出す位置、`contain`では画像を置く位置です。`crop_scale`を`1`より小さくすると、`cover`では拡大して狭い範囲を切り出し、`contain`では画像を縮小してWhite領域を増やします。
 
+`brightness`、`contrast`、`saturation`はJPEG、PNG、SVGをsRGBへ正規化した後、格子へサンプリングする前にこの順で適用します。単位は百分率で、`0`は無補正です。明るさはRGB値へ加算し、コントラストは50%グレーを中心に、彩度はRec.601輝度を中心に調整します。`-100`はそれぞれ黒方向、コントラストなし、無彩色となり、`100`は既定量の2倍です。範囲外の値はクリップされます。同じ補正済み画像をWhite厚さとCMYW色選択で共有します。
+
 `color_pixel_size`を指定すると、White厚さは`pixel_size`の格子で保ったまま、各色セル内の厚さセルが同じCMYWレシピを使います。色セルはモデル原点から独立して区切り、端には部分セルを残します。未指定時は従来どおり厚さと色が同じ格子です。
 
+タイル配置の選択、座標、Z分割のプレート構成、併用時の成果物は[3MFタイル分割とZ分割](tiling.md)を参照してください。
+
 標準では`null`を推奨します。140 × 104 mmの細線評価では、0.4 mm以上の色セルは色境界の段差と3MF三角形数を増やし、処理時間を短縮しませんでした。細線を含まない入力で個別にプレビューとBambu Studioのレイヤー表示を確認できる場合だけ、より大きい値を使用してください。
 
 ## 出力先
@@ -149,9 +171,14 @@ lithop images/page.png --project-dir output/book
 - 幅、高さ、厚さ、XYセル寸法、レイヤー高さが正の有限値ではない
 - `layout_profile`が`standard`ではない
 - `grid_columns`と`grid_rows`が同時に指定されていない、または正の整数ではない
+- `tile_count`が1以上の整数ではない、配置名が不明、`grid`の行数 × 列数が総数と一致しない
+- 行数または列数がXYセル数を超え、幅または高さが0セルになるタイルがある
+- `separate_z_parts`が真偽値ではない、または`color_region_parts`が1〜`color_layer_count`の整数ではない
+- Z分離時に上部Whiteの最小厚さが0になる
 - `color_pixel_size`が`null`でも`pixel_size`以上の正の有限値でもない
 - `image_fit`が`cover`または`contain`ではない
 - クロップ位置が0〜1の範囲外、または`crop_scale`が0より大きく1以下ではない
+- 明るさ、コントラスト、彩度が`-100`〜`100`の有限値ではない
 - 要求最小厚さが要求最大厚さを超える
 - ノズル径が0.2または0.4ではない
 - 色モデルが`cmy`ではない
@@ -180,7 +207,7 @@ effective: 1.0–2.14689422 mm
 
 ## 校正片に使う設定
 
-`lithop calibrate`は、厚さ、ノズル、レイヤー高さ、色モデル、色領域の層数、顔料順、三角形数上限を設定から読みます。固定レイアウトのため、`width`、`height`、`margin_*`、画像配置、`pixel_size`、`color_pixel_size`、`maximum_input_pixels`は使いません。
+`lithop calibrate`は、厚さ、ノズル、レイヤー高さ、色モデル、色領域の層数、顔料順、三角形数上限を設定から読みます。固定レイアウトで入力画像を使わないため、`width`、`height`、`margin_*`、画像配置、明るさ・コントラスト・彩度、`pixel_size`、`color_pixel_size`、`maximum_input_pixels`は使いません。
 
 現在の校正片は7層・`cyan,magenta,yellow`順と、White厚みを8段階取れる範囲を要求します。通常生成で使う`--calibration-profile`は入力設定キーではなくCLIオプションです。詳しくは[色校正](calibration.md)を参照してください。
 
@@ -198,4 +225,4 @@ effective: 1.0–2.14689422 mm
 
 ## 情報表示オプション
 
-`--help`と`--version`の対応は[バージョンとヘルプを表示する](command.md#バージョンとヘルプを表示する)を参照してください。
+`--help`、`--version`、`doctor`の対応は[バージョン、診断、ヘルプを表示する](command.md#バージョン診断ヘルプを表示する)を参照してください。

data/docs/getting-started.md

@@ -4,8 +4,9 @@ Lithopは、画像からカラーLithophane（リトファン）の3MFとWhite
 
 ## 準備
 
-- macOS
+- macOS（CIはmacOS／Ruby 4.0、現在の実測環境はApple silicon）
 - Ruby 4.0以上
+- CMYWレシピ選択用ネイティブ拡張をビルドするRust
 - JPEG、PNG、SVG（librsvg）、ICCプロファイルを扱えるlibvips
 - 印刷する場合はBambu Studio、AMS対応プリンタ、必要なCMYWフィラメント
 
@@ -13,15 +14,17 @@ Lithopは、画像からカラーLithophane（リトファン）の3MFとWhite
 
 ## インストール
 
-公開版0.1.0を使う場合は、libvipsとバージョンを指定したLithopをインストールします。
+0.3.0を使う場合は、libvips、Rust、バージョンを指定したLithopをインストールします。
 
 ```sh
-brew install vips
-gem install lithop -v 0.1.0
+brew install vips rust
+gem install lithop -v 0.3.0
 lithop --version
+lithop doctor
 ```
 
-`lithop --version`が`0.1.0`を表示することを確認します。
+`lithop --version`が`0.3.0`を表示することを確認します。
+`lithop doctor`では`backend`が`rust`、`extension_version`がLithopと同じバージョンであることを確認します。
 
 ソースチェックアウトから実行する場合は、代わりに次を実行します。
 
@@ -87,6 +90,8 @@ SVGは正の`width`・`height`（単位なし、`px`、`mm`、`in`）または`v
 
 確認後、`lithop.3mf`をBambu Studioへモデルとして読み込みます。材料部品を個別に移動、整列、拡大縮小、結合しないでください。
 
+タイル分割またはZ分割を使う場合は、[3MFタイル分割とZ分割](tiling.md)に従って各3MF、組み立て位置、Bambu Studioのプレートを確認してください。
+
 ## 生成物を削除する
 
 `lithop clean`は、選択したプロジェクトの`build/`全体を完全に削除します。個別ジョブの削除ではなく、元に戻せません。実行前に対象パスを確認してください。

data/docs/local-ui.md

@@ -0,0 +1,114 @@
+# ローカルブラウザ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を明示的に開いてください。
+
+## 画面を移動する
+
+左の主メニューで「作成」「ジョブ」「プリセット」を切り替えます。「作成」は画像・変換設定と入力プレビュー、「ジョブ」は履歴・進捗・生成結果、「プリセット」は名前付き設定と下書きの管理を表示します。幅1439px以下では主メニューを左上のメニューボタンから開き、Escまたは背景の選択で閉じます。
+
+画面を切り替えても、選択中の画像、編集値、設定区分の開閉、プレビューの倍率・位置、履歴の検索条件と選択状態を保持します。ブラウザの戻る・進むにも対応し、URLの`view`は表示画面、`job`は閲覧ジョブを表します。再読み込み後は画面とジョブを復元しますが、ブラウザの制約により入力画像は再選択が必要です。
+
+上部ヘッダーにはプロジェクト名、現在の画面、実行中ジョブの入力名・ID・状態・進捗を表示します。過去ジョブを閲覧しても実行中ジョブを別に追跡するため、上部の停止対象は変わりません。ジョブ表示を選ぶと実行中ジョブの詳細へ戻ります。「使い方」は同梱された簡易説明を開くため、外部サイトへ接続しません。
+
+## 画像と設定を選ぶ
+
+JPEG、PNG、SVGを1ファイル選択します。画面では次の設定を変更できます。
+
+- 完成幅・高さ、XYセル、任意の色セル
+- `cover`／`contain`、横・縦位置、クロップ倍率
+- 明るさ、コントラスト、彩度、ノズル径
+- 最小・最大厚み、上下左右のWhite余白
+- XYタイル数と配置、Z方向の別プレート化、色領域の分割数
+
+画像はファイル選択欄へのドラッグ＆ドロップにも対応します。設定は「基本設定」「画像配置」「画像調整」「分割」「詳細設定」に分かれ、幅と高さの交換、縦横比の固定、区分ごとの初期値への復元ができます。画像配置と画像調整はスライダーと数値入力が同期します。grid以外の行列数と、Z分割を使用しない場合の色領域分割数は送信されません。
+
+開始ボタンの手前に、入力名、完成寸法、セル、画像調整、分割方法の要約を表示します。変換後に設定や画像を変更すると変更項目数を示し、「表示中の変換ジョブ」には編集値と異なる設定名を表示します。編集中の入力と履歴から開いたジョブは別に管理されるため、新しい画像を選んでも過去ジョブの「補正後入力」は置き換わりません。
+
+初期値は選択したプロジェクトの`config/settings.json`と組み込み既定値から読みます。画面で確定した値はCLIと同じ`Settings`で検証され、White高さとCMYWレシピを作る共通の変換エンジンへ渡されます。
+
+「プリセット」画面では、現在の変換設定を名前付きプリセットまたは1件の下書きとして保存できます。プリセットは読込、名前変更、削除ができ、過去ジョブの「この設定を編集へ読み込む」も同じ操作で現在値との差分を確認してから反映します。適用後は「作成」へ戻り、現在選択している画像は置き換えません。保存対象は画面で編集できる変換設定だけで、画像、一時入力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とします。幅1440px以上では主メニューを左に常設し、「作成」の設定と入力プレビュー、「ジョブ」の履歴と詳細をそれぞれ左右に並べます。幅1439px以下では主メニューを折りたたみ、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で、画像選択、プレビュー準備中を含むジョブ作成、設定保持、タイル境界、Z分割項目、成果物切り替え、Bambu Studioへ渡す3MFの選択、拡大専用表示、同期した比較、全体図からのタイル選択、通信切断からの復帰、設定再利用、2ジョブ比較、履歴検索、ZIP取得、複数削除、停止、主メニュー、画面間の状態保持、戻る・進む、共通ヘッダーの停止、ジョブ詳細のキーボード操作を確認します。試験では起動処理を差し替え、Bambu Studioを実際には起動しません。失敗時のスクリーンショット、動画、トレースは`tmp/playwright-results/`へ保存します。受入ブラウザは実機Chromeとし、WebKitはブラウザエンジン間の回帰検証に使用します。

data/docs/tiling.md

@@ -0,0 +1,134 @@
+# 3MFタイル分割とZ分割
+
+Lithopは、1枚では印刷できない大きさのリトファンを、指定枚数のCMYW 3MFへXY方向に分割できます。分割後も、完成時の幅・高さ、White厚み、CMYWレシピ、画像の向きは変わりません。必要なら各タイルを、CMYW色領域と上部Whiteの4プレートにZ方向へ分けられます。
+
+このページでは、タイルの数と配置、出力座標、Bambu Studioで確認する対象を定義します。材料、積層構造、Z境界は[CMYWの色モデルと積層構造](color-model.md)、入力値の全一覧は[生成オプションと設定ファイル](config.md)を参照してください。
+
+## 使い分け
+
+| 目的 | 設定 | 出力 |
+| --- | --- | --- |
+| 通常の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 |
+
+`cmyk_white.stl`、`preview.png`、`transmission.png`、`thickness.png`、材料マスクは、常に分割前の完成全体を表します。XY分割時だけカラー3MFは`tiles/`へ出力され、ルートに`lithop.3mf`は作りません。各3MFに対応する`tiles/tile_rNN_cNN-preview.png`も生成し、ローカルUIの変換ジョブでは全タイルを同時に確認できます。
+
+## XY方向のタイル分割
+
+`--tile-count`で出力する3MFの総数を指定します。既定値は`1`です。
+
+4枚を自動的に、できるだけ正方形に近い行列へ配置します。
+
+```sh
+lithop image.svg --tile-count 4 --tile-layout auto
+```
+
+横1行に6枚、または3行1列に並べる場合は、それぞれ次を使います。
+
+```sh
+lithop image.svg --tile-count 6 --tile-layout columns
+lithop image.svg --tile-count 3 --tile-layout rows
+```
+
+2行3列を明示する場合は、次のように行と列を指定します。
+
+```sh
+lithop image.svg --tile-count 6 --tile-layout grid --tile-rows 2 --tile-columns 3
+```
+
+| `tile_layout` | 行列の決め方 |
+| --- | --- |
+| `auto` | 指定枚数になる因数の組から、実寸法で最も正方形に近いタイルを選ぶ。同点では列数が多い配置を選ぶ |
+| `columns` | 1行 × `tile_count`列 |
+| `rows` | `tile_count`行 × 1列 |
+| `grid` | `tile_rows` × `tile_columns`。積は必ず`tile_count`と一致させる |
+
+JSON設定ファイルでは次のように指定します。
+
+```json
+{
+  "layout_profile": "standard",
+  "tile_count": 6,
+  "tile_layout": "grid",
+  "tile_rows": 2,
+  "tile_columns": 3
+}
+```
+
+### 分割の契約
+
+画像全体のWhite厚みとCMYW材料配置を先に決めてから、既存のXYセル境界で切り出します。分割境界が色セルを横切らないため、隣接タイルを組み立てた結果は、分割しない場合と同じ色・厚みになります。タイルごとに新しい外枠、重なり、隙間、位置合わせ用のダボは追加しません。
+
+各タイルはローカルXY座標へ移動し、左下を`(0, 0)`、底面を`Z=0`にします。回転・拡縮は行いません。タイルIDは鑑賞面から見た左上を`tile_r01_c01`とし、左から右、次に上から下の順です。`tile_rNN_cNN.3mf`の`NN`はこの行列番号です。
+
+幅または高さのセル数が行数・列数で割り切れない場合でも、セルを切りません。そのため、タイル寸法には最大1セルの差が生じます。各タイルには少なくとも1つのXYセルが必要で、行数または列数がセル数を超える設定はエラーになります。
+
+### 成果物と組み立て位置
+
+タイルジョブは`tile-layout.svg`を追加します。これは完成寸法と同じ物理サイズの配置図で、各タイルIDと幅・高さを示します。`manifest.json`には次の情報を保存します。
+
+- `tile_layout`: 要求した配置、解決後の行数・列数、IDの順序、ローカル原点、画像上端の向き
+- `tiles`: 各タイルのID、3MFファイル名、行・列、完成全体での`offset_mm`、`bounds_mm`、寸法、材料、三角形数
+
+複数のタイルを1つの完成物として配置する場合は、各3MFの材料部品を動かさず、対応する`offset_mm`を使ってタイル全体を配置します。`tile-layout.svg`と`manifest.json`は、その配置を復元するための正本です。
+
+## Z方向の4プレート分割
+
+`--separate-z-parts`を指定すると、各3MFのZ方向を複数のBambu Studioプレートへ分けます。
+
+```sh
+lithop image.svg --separate-z-parts
+```
+
+標準の7層CMYW色領域と既定の`--color-region-parts 3`では、Bambu Studioで次の4プレートを開きます。
+
+| プレート | 元の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 |
+
+各プレートは単独印刷できるよう、出力3MFでは底面が`Z=0`になります。Base Whiteだけのプレートは作りません。Base Whiteキャリアは各`Color region`に含まれ、使用されるCyan、Magenta、Yellowの閉じた部品と同じ領域を支えます。未使用の顔料部品は省略されますが、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境界、各プレートでの印刷厚み、積層順、部品名が入ります。
+
+分離したZ部品を印刷後に組み立てる場合は、`Color region 1`から`Top White`まで、マニフェストの積層順どおりに同じXY位置で重ねます。各プレート内の部品を移動、整列、拡大縮小、結合してはいけません。
+
+## XY分割とZ分割を併用する
+
+次の例は、完成全体を横2枚へ分け、各タイルを4プレートにします。
+
+```sh
+lithop image.svg --tile-count 2 --tile-layout columns --separate-z-parts
+```
+
+出力は次の構造になります。
+
+```text
+build/<job_id>/
+├── cmyk_white.stl
+├── tile-layout.svg
+├── tiles/
+│   ├── tile_r01_c01.3mf  # Color region 1–3、Top Whiteの4プレート
+│   ├── tile_r01_c01-preview.png
+│   ├── tile_r01_c02.3mf  # Color region 1–3、Top Whiteの4プレート
+│   └── tile_r01_c02-preview.png
+├── manifest.json
+├── settings.json
+└── preview.png ほか
+```
+
+タイルのXY組み立て情報とZ方向の積層情報は別の契約です。XY方向は各タイルの`offset_mm`、Z方向は各タイルの`color_model.z_part_separation.plates`を使います。Bambu Studioへ読み込んだ後は、同一タイル内の材料部品を移動、整列、拡大縮小、結合しないでください。
+
+## 印刷前の確認
+
+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境界と積層順に合わせる。
+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.3.0は利用環境でRust拡張をビルドするソースgemとして扱います。
+
 ## 入力画像を読めない
 
 **最初の確認:** ファイルが実在し、JPEG、PNG、またはSVGとして画像アプリで開けるか確認します。
@@ -35,6 +45,8 @@ bundle exec lithop --version
 
 **最初の確認:** `cmyk_white.stl`ではなく`lithop.3mf`を開き、一つの親オブジェクトの下に材料部品があるか確認します。
 
+分割ジョブでは`lithop.3mf`の代わりに`tiles/tile_rNN_cNN.3mf`を開きます。各ファイル内の材料部品は同じローカル座標を共有し、全体の位置は`tile-layout.svg`と`manifest.json`で確認します。
+
 **原因候補:** White参照STLを開いた、部品を結合・修復・自動整列した、材料割り当てを変更した可能性があります。未使用顔料の省略は正常です。
 
 **対処:** 3MFを読み直し、部品を動かさず、Cyan=1、Magenta=2、Yellow=3、White=4を確認します。省略された番号は詰めません。
@@ -95,6 +107,16 @@ bundle exec lithop image.png --width 20 --height 15 --pixel-size 0.5
 
 **関連:** [生成物を削除する](command.md#生成物を削除する)
 
+## `another conversion is already running`と表示される
+
+**最初の確認:** 同じプロジェクトを指定した別の`lithop`または`lithop calibrate`が実行中か確認します。
+
+**原因候補:** プロジェクト単位の同時変換数は1です。通常生成と校正生成は同じ排他ロックを使います。
+
+**対処:** 実行中の変換が完了または中止してから再実行します。プロセスが異常終了した場合もOSが排他ロックを解放し、次回の変換が所有情報付き一時データを回収します。`.lithop.lock`ファイルの存在だけでは実行中を意味しないため、手動で削除する必要はありません。
+
+**関連:** [ジョブディレクトリ](artifacts.md#ジョブディレクトリ)
+
 ## 不具合を報告する
 
 **最初の確認:** 入力画像、ローカルパス、ハッシュを公開してよいか判断します。公開できない画像は添付しないでください。

data/ext/lithop_native/Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "lithop_native"
+version = "0.3.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")