lithop 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 13a626692e6ae5bd67e88bb4f81e0cf8ae8ad6fb220e5cdb4822a582eaec6dd7
-  data.tar.gz: 1497a224597acc9416aa67961969aeeb868981581af93cff6fb7e0bada32d781
+  metadata.gz: 724832daeb852eb0910033dd04b596f4d5f0f74535804e0577c20312b499ebe9
+  data.tar.gz: 0a75bcd7986e64d707736b67f49f6e5301819043cddccdd63fb09569541d6aa9
 SHA512:
-  metadata.gz: 879e0cc070dfd33464e12504d5409b2b98df8ff1f576e716c818968875cab637a9f315ddf41bd021c391e3c88e222ebc3eddb29dcbbecf002531b9b80068a743
-  data.tar.gz: 3ce5b71121d43b5c58ffb9bee086cf59e36ab1550554a007742ffc76852a2350b2e3dc49ec14596f4bc4caa4022efb1a53b752103eddfb18084d60a1ca454b31
+  metadata.gz: 719b4231386b719eacade124d17fb26c020d546ee526244bd285df6f78bf6c1905c4c1f62dd4b3d5853e57fb93f930b6c83e9c0bce47fee76d1fd49f4d320abc
+  data.tar.gz: 16d8f9c4ce8cd42fa152e0e4a1dc6d98b40cd8d615fdb871b0e54f9ac2a96c96184f57ae906d227dd994bc2f5b215259c70f89f113a112744214f5b7f27d427b

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.2.0 - 2026-10-16
+
+- Adds exact-count CMYW 3MF tiling, plus optional four-plate output for three Base White-backed CMYW color regions and Top White.
+- Aligns the CLI help and source-checkout settings with the 140 × 104 mm standard profile.
+- Adds reproducible sRGB brightness, contrast, and saturation adjustments to JSON settings and the CLI.
+- Records conversion progress and final status, supports cancellation and stale temporary-data recovery, and limits each project to one active conversion.
+
 ## 0.1.0 - 2026-10-12
 
 - Converts JPEG, PNG, and validated self-contained SVG files up to 15 MB into a White reference STL and a single-plate multipart CMYW 3MF.

data/README.md

@@ -30,15 +30,15 @@ Before printing, inspect every layer and confirm the Cyan, Magenta, Yellow, and
 
 ## Install
 
-To install the 0.1.0 release from RubyGems, install libvips and the matching Lithop version:
+To install the 0.2.0 release from RubyGems, install libvips and the matching Lithop version:
 
 ```sh
 brew install vips
-gem install lithop -v 0.1.0
+gem install lithop -v 0.2.0
 lithop --version
 ```
 
-The version command must print `0.1.0`.
+The version command must print `0.2.0`.
 
 To work from a source checkout instead:
 
@@ -69,6 +69,12 @@ bundle exec lithop path/to/image.jpeg
 
 It writes `lithop.3mf` with a single `lithophane` plate and White/Cyan/Magenta/Yellow extruders. Its layer preview and physical print still require manual verification.
 
+Use `--brightness`, `--contrast`, and `--saturation` with percentages from `-100` to `100` to adjust the shared sRGB input before White thickness and CMYW recipes are sampled. The resolved values are recorded in each job's `settings.json`.
+
+Use `--tile-count N` with `--tile-layout auto`, `columns`, `rows`, or `grid` to emit exactly N local-origin 3MF tiles. Tiled jobs include assembled offsets and bounds in `manifest.json` plus a physical-size `tile-layout.svg` placement guide.
+
+Add `--separate-z-parts` to place three closed CMYW color-region bands and Top White on four Bambu Studio plates inside every generated 3MF. Each color-region plate includes its own Base White carrier, and every plate is translated to start at Z=0 for independent printing; `manifest.json` retains the original assembly order and Z bounds.
+
 The command reports estimated and final triangle counts and creates a new `build/<job_id>/` directory. Completed jobs are never overwritten. Inspect `preview.png`, `transmission.png`, `thickness.png`, and the four material masks, then import `lithop.3mf` into Bambu Studio as a model. The 3MF contains geometry, fixed extruder numbers, and layer-height metadata. It does not select a printer, physical build plate, AMS slot, or complete slicing preset.
 
 The bundled color chart at standard settings produces 2,660,706 CMYW 3MF triangles, below the default 5,000,000-triangle limit. Runtime and memory depend on the image and machine; use a smaller model and a coarser cell size for initial checks.

data/RELEASING.md

@@ -49,15 +49,15 @@ Alternatively, configure a RubyGems.org trusted publisher for this repository an
 bundle exec rake release
 ```
 
-After the tag exists on GitHub, create a GitHub Release and attach the exact gem that passed validation. Replace `0.1.0` for later versions:
+After the tag exists on GitHub, create a GitHub Release and attach the exact gem that passed validation. Replace `0.2.0` for later versions:
 
 ```sh
-gh release create v0.1.0 lithop-0.1.0.gem --verify-tag --generate-notes
+gh release create v0.2.0 --verify-tag --generate-notes
 ```
 
 Finally, install the published version in a clean environment and verify the CLI:
 
 ```sh
-gem install lithop -v 0.1.0
+gem install lithop -v 0.2.0
 lithop --version
 ```

data/docs/README.md

@@ -23,6 +23,7 @@ Lithopは、JPEG、PNG、SVGからCMYW材料のカラーLithophane（リトフ
 ## 仕様を調べる
 
 - [生成物と記録](artifacts.md) — ジョブ、全成果物、プレビュー、`settings.json`、`manifest.json`
+- [3MFタイル分割とZ分割](tiling.md) — 指定枚数のXY分割、組み立て座標、4プレートのZ分割
 - [生成オプションと設定ファイル](config.md) — 設定の優先順位、入力JSON、既定値、検証規則
 - [コマンドリファレンス](command.md) — 構文、全オプション、終了ステータス
 - [CMYWの色モデルと積層構造](color-model.md) — 材料、減法混色、White厚み、3MF構造

data/docs/artifacts.md

@@ -6,7 +6,11 @@ Lithopは生成中のファイルを一時ディレクトリへ書き、すべ
 
 通常生成は`build/<job_id>/`、校正片生成は`build/<job_id>-calibration/`へ保存します。ジョブIDはUTC時刻とランダム値から作られます。
 
-生成中は`build/.tmp-<job_id>/`を排他的に取得します。失敗または中断した実行は自分が作成した一時領域だけを回収し、入力画像、別の実行の一時領域、完了済みジョブを削除しません。完了済みジョブと同じIDは上書きしません。
+生成中は`build/.tmp-<job_id>/`へ書き込みます。通常生成と校正生成はプロジェクトごとの`build/.lithop.lock`を共有し、同時変換数を1に制限します。変換中に別の変換を開始した場合は待機せず、`another conversion is already running`で失敗します。完了済みジョブと同じIDは上書きしません。
+
+状態は`build/.jobs/<job_id>.json`へ原子的に保存します。`state`は`queued`、`running`、中止要求を受けた`cancelling`、終了状態の`completed`／`failed`／`cancelled`です。`phase`、0〜100の`percent`、メッセージ、開始・更新・終了日時を持ち、完了時だけ`output_path`と`files`を記録します。CLIにも主要工程の進捗を表示します。
+
+`Ctrl-C`などの割り込みと`JobExecution.request_cancel`による中止要求は`cancelled`として記録し、未完成ジョブを公開しません。失敗はエラーのクラスとメッセージを`failed`状態へ記録します。どちらも実行自身が作成した一時領域を回収し、入力画像、別の実行の所有情報がない一時領域、使用中の一時領域、完了済みジョブを削除しません。プロセスが強制終了して回収できなかった所有情報付き一時領域は、所有PIDの終了を確認したうえで次の変換開始時に削除し、残っていた実行状態を`failed`の`recovered`工程へ変更します。
 
 ## 通常ジョブのファイル
 
@@ -28,6 +32,8 @@ Lithopは生成中のファイルを一時ディレクトリへ書き、すべ
 
 標準ジョブは単一プレートと非一様レイヤー情報を持つ`lithop.3mf`を出力します。未使用のCyan、Magenta、Yellowは3MFのメッシュから省略されるため、材料部品は1〜4個です。Whiteは必ず含まれます。`cmyk_white.stl`は比較用で、CMYWの材料分離情報を持ちません。
 
+XYタイルとZ分割のファイル構成、座標、`tile-layout.svg`、マニフェスト記録、4プレート構成は[3MFタイル分割とZ分割](tiling.md)を参照してください。
+
 ## プレビューの座標と値
 
 全プレビューの1画素は3MFの1セルに対応し、左上がモデルの`+Y`側です。材料マスクは黒が0層で、明るいほど層数が多く、4材料で同じ明度尺度を使います。
@@ -55,12 +61,21 @@ Lithopは生成中のファイルを一時ディレクトリへ書き、すべ
   "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.22,
   "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,
@@ -78,12 +93,14 @@ Lithopは生成中のファイルを一時ディレクトリへ書き、すべ
   "effective_color_pixel_size": 0.22,
   "effective_minimum_thickness": 1.0,
   "effective_maximum_thickness": 2.14689422,
+  "resolved_tile_rows": 1,
+  "resolved_tile_columns": 1,
   "columns": 637,
   "rows": 473,
   "pixel_size_x": 0.21978021978021978,
   "pixel_size_y": 0.21987315010570824,
   "schema_version": 1,
-  "generator_version": "0.1.0",
+  "generator_version": "0.2.0",
   "input_path": "/absolute/path/to/image.png",
   "input_settings_path": "/absolute/path/to/config/settings.json",
   "calibration_profile_id": null,

data/docs/bambu-studio.md

@@ -24,6 +24,8 @@ bundle exec lithop examples/cmy-fine-line.svg --width 20 --height 15 --pixel-siz
 
 表示された`build/<job_id>/`で、`preview.png`、`PRINT_README.md`、`settings.json`、`manifest.json`を確認してから`lithop.3mf`を開きます。自分のジョブIDと印刷条件は`manifest.json`に記録されています。
 
+タイルまたはZ分割ジョブを開く場合は、[3MFタイル分割とZ分割](tiling.md)に従い、対象3MF、組み立て座標、4プレート、材料割り当てを確認します。
+
 ## 3MFを読み込む
 
 1. `cmyk_white.stl`ではなく`lithop.3mf`をモデルとして読み込む。

data/docs/color-model.md

@@ -77,6 +77,8 @@ Z=0 / バックライト側
 | CMYW色領域 |          7 | 0.20–0.90 mm |
 | 上部White  |       可変 | 0.90–2.14689422 mm |
 
+`--separate-z-parts`で出力する4プレート、Base Whiteキャリア、元のZ境界、積層順は[3MFタイル分割とZ分割](tiling.md)を参照してください。
+
 標準の最小厚さは1.0 mm、最大厚さは2.14689422 mmです。
 
 ## 材料別メッシュの関係

data/docs/command.md

@@ -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,7 @@ 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)を参照してください。
 
 ## 生成物を削除する
 

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)を参照してください。
 

data/docs/getting-started.md

@@ -13,15 +13,15 @@ Lithopは、画像からカラーLithophane（リトファン）の3MFとWhite
 
 ## インストール
 
-公開版0.1.0を使う場合は、libvipsとバージョンを指定したLithopをインストールします。
+公開版0.2.0を使う場合は、libvipsとバージョンを指定したLithopをインストールします。
 
 ```sh
 brew install vips
-gem install lithop -v 0.1.0
+gem install lithop -v 0.2.0
 lithop --version
 ```
 
-`lithop --version`が`0.1.0`を表示することを確認します。
+`lithop --version`が`0.2.0`を表示することを確認します。
 
 ソースチェックアウトから実行する場合は、代わりに次を実行します。
 
@@ -87,6 +87,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/tiling.md

@@ -0,0 +1,132 @@
+# 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`は作りません。
+
+## 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_c02.3mf  # Color region 1–3、Top Whiteの4プレート
+├── 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

@@ -35,6 +35,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 +97,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/lib/lithop/calibration/export.rb

@@ -10,34 +10,47 @@ module Lithop
     class Export
       Result = Data.define(:job_id, :path, :files, :triangle_count, :patch_count)
 
-      def initialize(settings:, project_dir:, clock: Time, random: SecureRandom)
+      def initialize(
+        settings:, project_dir:, job_progress: nil, clock: Time, random: SecureRandom, job_id: nil
+      )
         @settings = settings
         @project_dir = File.expand_path(project_dir)
         @clock = clock
         @random = random
+        @job_progress = job_progress
+        @job_id = job_id
       end
 
       def call
-        job_id = "#{@clock.now.utc.strftime("%Y%m%dT%H%M%SZ")}-#{@random.hex(4)}-calibration"
-        destination, generated = JobDirectory.new(project_dir: @project_dir, job_id:).call do |directory|
-          generate(directory, job_id)
+        job_id = @job_id || "#{@clock.now.utc.strftime("%Y%m%dT%H%M%SZ")}-#{@random.hex(4)}-calibration"
+        execution = JobExecution.new(
+          project_dir: @project_dir, job_id:, progress: @job_progress, clock: @clock
+        )
+        execution.call do |job|
+          destination, generated = JobDirectory.new(project_dir: @project_dir, job_id:).call do |directory|
+            generate(directory, job_id, job)
+          end
+          job.progress(phase: :publishing, percent: 99, message: "Calibration artifacts published")
+          Result.new(job_id:, path: destination, files: generated.fetch(:files),
+                     triangle_count: generated.fetch(:triangle_count), patch_count: generated.fetch(:patch_count))
         end
-        Result.new(job_id:, path: destination, files: generated.fetch(:files),
-                   triangle_count: generated.fetch(:triangle_count), patch_count: generated.fetch(:patch_count))
       end
 
       private
 
-      def generate(directory, job_id)
+      def generate(directory, job_id, job)
+        job.progress(phase: :calibration_planning, percent: 10, message: "Planning calibration target")
         target = Target.new(settings: @settings)
+        job.progress(phase: :three_mf_write, percent: 35, message: "Writing calibration 3MF")
         result = write_three_mf(File.join(directory, "calibration.3mf"), target)
+        job.progress(phase: :supporting_files, percent: 80, message: "Writing calibration files")
         TargetSVG.write(File.join(directory, "calibration.svg"), target)
         profile = Profile.template(profile_id: job_id, settings: @settings, target:)
         profile.write(File.join(directory, "calibration-profile.json"))
         write_manifest(directory, job_id, target, result)
         write_readme(directory, target)
         {
-          files: Dir.children(directory).sort,
+          files: Dir.children(directory).reject { |name| name == JobDirectory::OWNER_FILE }.sort,
           triangle_count: result.triangle_count,
           patch_count: target.patches.length
         }

data/lib/lithop/cli/calibration.rb

@@ -17,7 +17,9 @@ module Lithop
       raise OptionParser::InvalidArgument, arguments.join(" ") unless arguments.empty?
 
       project_dir, settings, = load_settings(options, keys: CALIBRATION_SETTING_KEYS)
-      result = Calibration::Export.new(settings:, project_dir:).call
+      result = Calibration::Export.new(
+        settings:, project_dir:, job_progress: method(:report_job_progress)
+      ).call
       @out.puts "Generated #{result.patch_count} calibration patches and #{result.triangle_count} 3MF triangles"
       @out.puts "in #{result.path}"
       result.files.each { |file| @out.puts "  #{file}" }