lithop 0.1.0

data/docs/color-model.md

@@ -0,0 +1,114 @@
+# CMYWの色モデルと積層構造
+
+Lithopは、Cyan、Magenta、Yellow、Whiteの4材料を積み重ね、カラーリトファンの色と明暗を表現します。Blackや中間色のフィラメントは使いません。
+
+## 使用する材料
+
+| チャンネル | 製品名            | カラーコード | 表示色（RGB系HEX） | CMYK（Japan Color 2001 Coated） | Extruder |
+| ---------- | ----------------- | ------------ | ------------------- | -------------------------------- | -------: |
+| Cyan       | PLA Basic Cyan    | 10603        | `#0086D6`           | C: 85%, M: 45%, Y: 0%, K: 0%    |        1 |
+| Magenta    | PLA Basic Magenta | 10202        | `#EC008C`           | C: 0%, M: 97%, Y: 0%, K: 0%     |        2 |
+| Yellow     | PLA Basic Yellow  | 10400        | `#FCE300`           | C: 3%, M: 9%, Y: 95%, K: 0%     |        3 |
+| White      | PLA Basic White   | 10100        | `#FFFFFF`           | C: 0%, M: 0%, Y: 0%, K: 0%      |        4 |
+
+材料表の表示色はRGB系のHEX（16進カラーコード）であり、隣の列にJapan Color 2001 CoatedでのCMYK変換値を併記しています。いずれも画面や印刷物で材料を識別するための色値で、フィラメントの透過色や光学特性を表すものではありません。入力sRGBが表示色と完全に一致する場合は材料チャンネルの指定値としても扱い、`#0086D6`はCyan 7層、`#EC008C`はMagenta 7層、`#FCE300`はYellow 7層へ割り当てます。未使用の顔料を省略してもExtruder番号は詰めません。
+
+140 mm × 104 mmの`examples/cmy-color-chart.svg`では、横方向の表示色を図中のCMY配合へ割り当て、縦方向の0〜100%を明暗値として扱います。Yellowを含む列だけでなく、Cyan、Magentaおよび混色の列も5%からCMY配合を保持します。5%未満のごく薄い非Yellow色差はWhiteのノイズとして除去します。暗い無彩色と茶色い細線はCyan 1層、Magenta 1層、Yellow 1層、White 4層へ割り当てます。明暗値は全色列で共通の上部White連続高へ変換し、Y100だけが別の高さ段階にならないようにします。0%は顔料なしのWhiteです。
+
+## 色の作り方
+
+Cyan、Magenta、Yellowは減法混色として扱います。
+
+- Green: Cyan + Yellow
+- Purple: Cyan + Magenta
+- Red: Magenta + Yellow
+- 暗色: Cyan + Magenta + Yellow
+- White: 顔料なし
+
+標準の色領域7層にCyan、Magenta、Yellow、Whiteを配分すると、120個の整数レシピになります。入力sRGBから求めたCMY被覆量に最も近いレシピを選びます。実際の色は材料の透過率、層数、積層順、光源に依存します。
+
+明暗は主に上部Whiteの厚さで表します。厚い場所ほどバックライトを通しにくく、暗く見えます。材料表示色とチャート配合には指定された明暗値を使い、それ以外の入力色はRec.601輝度を反転して画像内の最小・最大で正規化します。White上面は連続高のまま生成します。0.04 mmは上面メッシュの刻みではなく、Bambu Studioへ渡すスライス層高です。
+
+## 現行の積層構造
+
+モデルは平らな背面をビルドプレート側の`Z=0`に置きます。完成後はバックライトを背面側に置き、凹凸のある`+Z`側から鑑賞します。
+
+```text
++Z / 観察側
+┌─────────────────────────┐
+│ White: 1.0 mm以上で可変  │  明暗を制御
+├─────────────────────────┤
+│ CMYWレシピ: 標準7層      │  色相を制御
+├─────────────────────────┤
+│ White: 下地2層           │  共通の背面
+└─────────────────────────┘
+Z=0 / バックライト側
+```
+
+### 下地のWhite
+
+最初の2層はモデル全体を支える連続したWhiteです。各層は0.1 mmで、平らなバックライト側の面になります。
+
+### CMYWの色領域
+
+下地の上へ、各0.1 mmの色レイヤーを7層置きます。各XYセル・各高さには4材料のどれか一つだけを割り当て、重複や空洞を作りません。
+
+顔料はバックライト側から`Cyan -> Magenta -> Yellow`の順に並び、残りをWhiteが埋めます。`pigment_order`が表すのは3顔料の順序で、Whiteは常にその後です。
+
+| 表現する色 | 色領域7層の例             |
+| ---------- | ------------------------- |
+| Cyan       | Cyan × 7                  |
+| Green      | Cyan × 3 -> Yellow × 4    |
+| Purple     | Cyan × 3 -> Magenta × 4   |
+| Red        | Magenta × 3 -> Yellow × 4 |
+| White      | White × 7                 |
+
+表は代表例で、入力色により層数配分は変わります。暗い無彩色や茶色い細線にはCMYを各1層重ね、残り4層をWhiteにします。
+
+### 明暗を作る上部White
+
+色領域の上を1.0 mmまでWhiteで埋め、その上面を連続高にします。材料表示色と同梱カラーチャートの配合色では指定された明暗値を使い、それ以外の入力色ではRec.601輝度を使います。明るい場所は薄く、暗い場所は厚くします。
+
+`cmy-color-chart.svg`では同じ明暗行にある全13色列を共通のWhite高さへ変換します。YellowのRGB表示色はほかの材料色より明るく見えますが、Y100だけに別のWhite段差は作りません。高さの比較には`preview.png`の見た目ではなく`thickness.png`を使います。
+
+| 領域       | 既定の層数 | Z範囲        |
+| ---------- | ---------: | ------------ |
+| 下地White  |          2 | 0.00–0.20 mm |
+| CMYW色領域 |          7 | 0.20–0.90 mm |
+| 上部White  |       可変 | 0.90–2.14689422 mm |
+
+標準の最小厚さは1.0 mm、最大厚さは2.14689422 mmです。
+
+## 材料別メッシュの関係
+
+材料ごとの形状は、共通座標にある互いに重ならない閉じたメッシュです。Whiteは必ず含まれ、使わないCyan、Magenta、Yellowは省略されるため、3MFの材料部品数は1〜4個です。
+
+Bambu Studioでは一つの親オブジェクトの材料部品として扱います。部品を個別に移動、整列、拡大縮小、結合すると位置関係が壊れます。
+
+## 積層構造の比較結果
+
+4層／5層は比較用に指定できます。標準構造は7層の`Cyan -> Magenta -> Yellow -> White`です。
+
+| 項目   | 標準構造                  | 比較可能な代替構造        |
+| ------ | ------------------------- | ------------------------- |
+| 色領域 | 7層                       | 4層または5層             |
+| 顔料順 | Cyan -> Magenta -> Yellow | Yellow -> Magenta -> Cyan |
+| 下地   | White 2層                 | White 2層                 |
+| 上部   | 可変厚のWhite             | 可変厚のWhite             |
+
+`--color-layer-count`と`--pigment-order`で比較構造を再生成できます。これは目視による発色バランスの採用結果であり、測色校正の結果ではありません。
+
+## 現在の制約
+
+- 未校正時のレシピはフィラメントの実測透過率を使わない
+- 入力画像と印刷物の測色的一致を保証しない
+- `preview.png`は公称色表示で、印刷物の測色予測ではない
+- プリンタ、ノズル、フィラメントロット、光源が変わると発色も変わり得る
+
+測色的一致が必要な場合だけ、[色校正](calibration.md)で実測プロファイルを作成してください。
+
+## 3MFに含まれる情報
+
+`lithop.3mf`には材料別メッシュ、材料名・コード・表示色、Bambu Studio向けExtruder対応、共通座標の組み立て情報が含まれます。
+
+プリンタ、ノズル、AMS実スロット、ビルドプレート、温度、速度、スライスプリセットは含みません。[Bambu Studioでの確認と印刷](bambu-studio.md)に従って設定してください。全成果物は[生成物と記録](artifacts.md)を参照してください。

data/docs/command.md

@@ -0,0 +1,182 @@
+# コマンドリファレンス
+
+このページはCLI構文とオプションの正本です。実行中の版では`lithop --help`、`lithop calibrate --help`、`lithop clean --help`でも確認できます。ソースチェックアウトでは、例の`lithop`を`bundle exec lithop`に読み替えてください。
+
+## 画像からリトファンを生成する
+
+JPEG、PNG、または非圧縮SVGから、CMYW 3MFとWhite参照STLを含む通常ジョブを生成します。
+
+### 構文
+
+```text
+Usage: lithop IMAGE [options]
+```
+
+`IMAGE`は必須で、指定できる入力ファイルは1つです。相対パスは現在の作業ディレクトリを基準に解決します。
+
+### オプション
+
+| オプション | 型 | 既定値 | 説明 |
+| --- | --- | ---: | --- |
+| `--layout-profile NAME` | String | `standard` | 標準構造を選ぶ。現在は`standard`のみ |
+| `--width MM` | Float | `130` | 完成幅をmm単位で指定する |
+| `--height MM` | Float | `100` | 完成高さをmm単位で指定する |
+| `--margin-top MM` | Float | `0` | 上側のWhite余白をmm単位で指定する |
+| `--margin-right MM` | Float | `0` | 右側のWhite余白をmm単位で指定する |
+| `--margin-bottom MM` | Float | `0` | 下側のWhite余白をmm単位で指定する |
+| `--margin-left MM` | Float | `0` | 左側のWhite余白をmm単位で指定する |
+| `--image-fit MODE` | String | `cover` | `cover`で全面を満たすか、`contain`で画像全体を収める |
+| `--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`以下の切り出し倍率を指定する |
+| `--min-thickness MM` | Float | `1.0` | 要求最小厚さをmm単位で指定する |
+| `--max-thickness MM` | Float | `2.14689422` | 要求最大厚さをmm単位で指定する |
+| `--pixel-size MM` | Float | `0.22` | XYセル寸法をmm単位で指定する |
+| `--color-pixel-size MM` | Float | `--pixel-size`と同じ | `--pixel-size`以上のCMYW色セル寸法を指定する |
+| `--first-layer-height MM` | Float | `0.1` | 下地Whiteの層高をmm単位で指定する |
+| `--layer-height MM` | Float | `0.1` | CMYW色領域の積層ピッチを指定する |
+| `--nozzle-diameter MM` | Float | `0.2` | ノズル径を`0.2`または`0.4`から選ぶ |
+| `--color-model MODEL` | String | `cmy` | 色モデルを指定する。現在は`cmy`のみ |
+| `--color-layer-count COUNT` | Integer | `7` | 色領域を`4`層、`5`層、`7`層から選ぶ |
+| `--pigment-order LIST` | String | `cyan,magenta,yellow` | CMYの顔料順をカンマ区切りで指定する |
+| `--config FILE` | Path | `PROJECT/config/settings.json` | 入力設定JSONを明示する |
+| `--project-dir DIR` | Path | 現在のディレクトリ | 設定を読み、`build/`を作るプロジェクトを選ぶ |
+| `--calibration-profile FILE` | Path | なし | 完了した実測プロファイルを選ぶ |
+| `-v`, `--version` | — | — | バージョンを表示して終了する |
+| `-h`, `--help` | — | — | ヘルプを表示して終了する |
+
+値の優先順位、入力JSON、詳細な検証規則は[生成オプションと設定ファイル](config.md)を参照してください。
+
+### 実行例
+
+標準構造で生成します。
+
+```sh
+lithop image.jpeg
+```
+
+小型モデルを生成します。
+
+```sh
+lithop image.png --width 20 --height 15 --pixel-size 0.5
+```
+
+SVGをPNGへ書き出さずに生成します。
+
+```sh
+lithop image.svg --width 20 --height 15 --pixel-size 0.5
+```
+
+完成寸法を変えず、上下1 mm、左右2 mmのWhite余白を設けます。
+
+```sh
+lithop image.png --margin-top 1 --margin-right 2 --margin-bottom 1 --margin-left 2
+```
+
+右寄せで切り出して拡大し、厚さセル0.25 mmごと、色セル0.8 mmごとに生成します。
+
+```sh
+lithop image.png --crop-position-x 1 --crop-scale 0.8 --pixel-size 0.25 --color-pixel-size 0.8
+```
+
+画像全体をWhiteの余白内へ収めます。
+
+```sh
+lithop image.png --image-fit contain
+```
+
+別のプロジェクトと入力設定を使います。
+
+```sh
+lithop image.png --project-dir output/book --config presets/fine.json
+```
+
+完成した実測プロファイルを使います。
+
+```sh
+lithop image.png --calibration-profile build/<calibration-job-id>/calibration-profile.json
+```
+
+### 出力
+
+書き出し前にWhite参照STL、CMYW 3MF、材料別3MFの三角形数を表示します。成功時は確定した三角形数、ジョブディレクトリの絶対パス、ファイル一覧を表示します。
+
+```text
+Estimated ... STL and ... CMYW 3MF triangles before writing
+  CMYW by material: cyan=..., magenta=..., yellow=..., white=...
+Generated ... STL and ... CMYW 3MF triangles
+in /absolute/path/to/build/<job_id>
+  ...
+```
+
+一時出力、完了済みジョブ、各ファイルは[生成物と記録](artifacts.md)を参照してください。
+
+## 校正片を生成する
+
+標準の7層・`Cyan -> Magenta -> Yellow`構造について、全120レシピとWhite厚み8段階を持つ140 × 104 mmの校正SVGと、同じ配置の印刷用3MFを生成します。画像は指定しません。
+
+```text
+Usage: lithop calibrate [options]
+```
+
+| オプション | 型 | 既定値 | 説明 |
+| --- | --- | ---: | --- |
+| `--min-thickness MM` | Float | `1.0` | 要求最小厚さを指定する |
+| `--max-thickness MM` | Float | `2.14689422` | 要求最大厚さを指定する |
+| `--first-layer-height MM` | Float | `0.1` | 下地Whiteの層高を指定する |
+| `--layer-height MM` | Float | `0.1` | CMYW色領域の積層ピッチを指定する |
+| `--nozzle-diameter MM` | Float | `0.2` | ノズル径を`0.2`または`0.4`から選ぶ |
+| `--color-model MODEL` | String | `cmy` | 色モデルを指定する |
+| `--color-layer-count COUNT` | Integer | `7` | 色領域の層数を指定する |
+| `--pigment-order LIST` | String | `cyan,magenta,yellow` | CMYの顔料順を指定する |
+| `--config FILE` | Path | `PROJECT/config/settings.json` | 入力設定JSONを明示する |
+| `--project-dir DIR` | Path | 現在のディレクトリ | 設定と出力先のプロジェクトを選ぶ |
+| `-v`, `--version` | — | — | バージョンを表示して終了する |
+| `-h`, `--help` | — | — | ヘルプを表示して終了する |
+
+```sh
+lithop calibrate
+```
+
+固定レイアウトのため、画像用の`width`、`height`、`margin_*`、画像配置、`pixel_size`、`color_pixel_size`、`maximum_input_pixels`は使いません。生成物は[校正ジョブのファイル](artifacts.md#校正ジョブのファイル)、測定方法は[色校正](calibration.md)を参照してください。
+
+## 生成物を削除する
+
+### 構文
+
+```text
+Usage: lithop clean [--project-dir DIR]
+```
+
+### オプション
+
+| オプション | 型 | 既定値 | 説明 |
+| --- | --- | ---: | --- |
+| `--project-dir DIR` | Path | 現在のディレクトリ | 削除する`build/`を持つプロジェクトを選ぶ |
+| `-h`, `--help` | — | — | ヘルプを表示して終了する |
+
+```sh
+lithop clean --project-dir /path/to/project
+```
+
+`clean`は個別ジョブではなく、対象プロジェクトの`build/`全体を完全に削除します。元に戻せないため、実行前にプロジェクトパスと内容を確認してください。
+
+`build/`がなければ正常終了します。ファイルシステムのルート、`build`自体がシンボリックリンク、または`build`がディレクトリではない場合は削除を拒否します。
+
+## バージョンとヘルプを表示する
+
+| コマンド | 内容 |
+| --- | --- |
+| `lithop --version` | バージョンを表示する。短縮形は`lithop -v` |
+| `lithop --help` | 通常生成の構文とオプションを表示する |
+| `lithop calibrate --help` | 校正片生成の構文とオプションを表示する |
+| `lithop clean --help` | 削除コマンドの構文とオプションを表示する |
+
+## 終了ステータスとエラー
+
+| ステータス | 意味 |
+| ---: | --- |
+| `0` | 生成、削除、情報表示が正常に完了した |
+| `1` | 引数、設定、入力、生成、またはファイル操作に失敗した |
+
+既知のエラーは標準エラー出力へ`lithop: MESSAGE`の形式で表示します。三角形数超過時は、`pixel_size`の概算推奨値、または幅・高さの縮小を案内します。対処は[トラブルシューティング](troubleshooting.md)を参照してください。

data/docs/config.md

@@ -0,0 +1,201 @@
+# 生成オプションと設定ファイル
+
+`lithop`は、CLI、入力設定JSON、組み込み既定値を統合して生成条件を決めます。このページは入力設定、既定値、検証規則の正本です。CLI表記は[コマンドリファレンス](command.md)を参照してください。
+
+## 値の決まり方
+
+| 優先順位 | 設定元 | 動作 |
+| ---: | --- | --- |
+| 1 | CLIオプション | 指定した値で入力設定を上書きする |
+| 2 | 入力設定ファイル | CLIで指定されなかった値を上書きする |
+| 3 | 組み込み既定値 | どちらにもない値に使用する |
+
+既定では、選択したプロジェクトの`config/settings.json`を、存在する場合だけ読みます。`--config FILE`で明示したファイルが存在しない場合はエラーです。
+
+## 入力設定ファイル
+
+入力設定はJSONオブジェクトです。`schema_version`は省略でき、省略時は`1`として扱います。未知のキー、対応していない版、壊れたJSON、オブジェクト以外のルートは拒否します。
+
+```json
+{
+  "schema_version": 1,
+  "layout_profile": "standard",
+  "width": 20.0,
+  "height": 15.0,
+  "margin_top": 1.0,
+  "margin_right": 1.5,
+  "margin_bottom": 1.0,
+  "margin_left": 1.5,
+  "image_fit": "cover",
+  "crop_position_x": 0.5,
+  "crop_position_y": 0.5,
+  "crop_scale": 1.0,
+  "minimum_thickness": 1.0,
+  "maximum_thickness": 2.14689422,
+  "pixel_size": 0.5,
+  "color_pixel_size": null,
+  "grid_columns": null,
+  "grid_rows": null,
+  "first_layer_height": 0.1,
+  "layer_height": 0.1,
+  "base_white_layers": 2,
+  "top_layer_height": 0.04,
+  "top_white_start": 1.0,
+  "minimum_top_white_layers": 0,
+  "exact_maximum_thickness": true,
+  "nozzle_diameter": 0.2,
+  "color_model": "cmy",
+  "color_layer_count": 7,
+  "pigment_order": ["cyan", "magenta", "yellow"],
+  "bambu_project": true
+}
+```
+
+```sh
+lithop image.png --config presets/fine.json
+```
+
+相対パスは現在の作業ディレクトリを基準に解決します。リポジトリの既定`config/settings.json`はローカル設定のためGit追跡対象外です。
+
+`layout_profile`で標準値を選び、その後に記載した個別キーで必要な値だけを上書きできます。JSON内のキー順には依存しません。たとえば次の設定は標準の7層構造と0.2 mmノズルを維持したまま、幅と高さを100 × 130 mmへ変更します。
+
+```json
+{
+  "layout_profile": "standard",
+  "width": 100.0,
+  "height": 130.0
+}
+```
+
+`width`、`height`、`pixel_size`のいずれかを個別指定し、`grid_columns`と`grid_rows`を指定しなかった場合、標準の637 × 473固定格子は解除され、指定寸法と`pixel_size`から格子数を再計算します。この例では既定の`pixel_size: 0.22`を使い、455 × 591セルになります。
+
+## 生成設定
+
+| 設定キー | CLIオプション | 既定値 | 内容 |
+| --- | --- | ---: | --- |
+| `layout_profile` | `--layout-profile NAME` | `standard` | 標準構造。現在は`standard`のみ |
+| `width` | `--width MM` | `140.0` | 完成幅mm |
+| `height` | `--height MM` | `104.0` | 完成高さmm |
+| `margin_top` | `--margin-top MM` | `0.0` | 上側のWhite余白mm |
+| `margin_right` | `--margin-right MM` | `0.0` | 右側のWhite余白mm |
+| `margin_bottom` | `--margin-bottom MM` | `0.0` | 下側のWhite余白mm |
+| `margin_left` | `--margin-left MM` | `0.0` | 左側のWhite余白mm |
+| `image_fit` | `--image-fit MODE` | `cover` | `cover`または`contain` |
+| `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` | 切り出し矩形または収容画像の倍率 |
+| `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`指定時は未指定扱い |
+| `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層数 |
+| `top_layer_height` | なし | `0.04` | 上部Whiteのスライス層高 |
+| `top_white_start` | なし | `1.0` | 上部Whiteの開始Z |
+| `minimum_top_white_layers` | なし | `0` | 上部Whiteに必要な最小層数 |
+| `exact_maximum_thickness` | なし | `true` | 最大厚みを正確に残すか |
+| `nozzle_diameter` | `--nozzle-diameter MM` | `0.2` | `0.2`または`0.4` |
+| `color_model` | `--color-model MODEL` | `cmy` | 現在はCMYのみ |
+| `color_layer_count` | `--color-layer-count COUNT` | `7` | 色領域の4層、5層、7層 |
+| `pigment_order` | `--pigment-order LIST` | `["cyan", "magenta", "yellow"]` | バックライト側からのCMY順序 |
+| `bambu_project` | なし | `true` | 単一プレートのBambuプロジェクト情報を追加するか |
+| `maximum_input_pixels` | なし | `20000000` | ラスター入力、またはSVGの描画面の総画素数上限 |
+| `maximum_triangles` | なし | `5000000` | 推定STLと実際のCMYW 3MFの三角形数上限 |
+
+`schema_version`の現在値は`1`です。CLIオプションが「なし」のキーは入力設定でだけ変更できます。
+
+## 標準構造
+
+`standard`は、外周なしの構造を使います。幅140 mm、高さ104 mm、637 × 473の均等fit格子、White下地2層、0.1 mmの色領域7層、連続高のWhite上面、Z=1.0 mm以上をスライスする0.04 mm層高、最大Z 2.14689422 mm、0.2 mmノズル、単一`lithophane`プレートを設定します。White上面は、材料表示色とチャート配合では指定された明暗値、それ以外の入力色ではRec.601輝度から求めます。Black、写真フレーム、導光板は出力しません。
+
+```sh
+lithop path/to/image.jpeg
+```
+
+個別キーを指定した場合は、標準値を上書きします。
+
+SVGでは、通常の厚さ格子と`color_pixel_size`を指定した色格子の両方から必要な描画倍率を求めます。描画予定の幅 × 高さが`maximum_input_pixels`を超える場合は描画前に拒否し、描画後の実寸法も同じ上限で検査します。SVGファイル自体には15,000,000バイト（15 MB）の上限があります。
+
+余白を指定しても完成寸法は変わりません。画像を残りの領域へ配置し、余白をWhiteにします。余白のサンプル数は`pixel_size`の格子へ丸めます。
+
+`image_fit=cover`は出力領域を満たして余分を切り出し、`contain`は画像全体を収めて残りをWhiteにします。`crop_position_x`と`crop_position_y`は、`cover`では切り出す位置、`contain`では画像を置く位置です。`crop_scale`を`1`より小さくすると、`cover`では拡大して狭い範囲を切り出し、`contain`では画像を縮小してWhite領域を増やします。
+
+`color_pixel_size`を指定すると、White厚さは`pixel_size`の格子で保ったまま、各色セル内の厚さセルが同じCMYWレシピを使います。色セルはモデル原点から独立して区切り、端には部分セルを残します。未指定時は従来どおり厚さと色が同じ格子です。
+
+標準では`null`を推奨します。140 × 104 mmの細線評価では、0.4 mm以上の色セルは色境界の段差と3MF三角形数を増やし、処理時間を短縮しませんでした。細線を含まない入力で個別にプレビューとBambu Studioのレイヤー表示を確認できる場合だけ、より大きい値を使用してください。
+
+## 出力先
+
+`--project-dir DIR`は形状ではなく、既定設定を読む場所と`build/`を作る場所を選びます。
+
+| オプション | 既定値 | 内容 |
+| --- | --- | --- |
+| `--project-dir DIR` | 現在の作業ディレクトリ | `DIR/config/settings.json`を読み、`DIR/build/`へ出力する |
+| `--config FILE` | `PROJECT/config/settings.json` | 入力設定を明示する |
+
+```sh
+lithop images/page.png --project-dir output/book
+```
+
+`clean`も`--project-dir`で対象を選びますが、設定ファイルは読みません。
+
+## 値の検証
+
+次の条件に違反すると終了ステータス1になります。
+
+- 幅、高さ、厚さ、XYセル寸法、レイヤー高さが正の有限値ではない
+- `layout_profile`が`standard`ではない
+- `grid_columns`と`grid_rows`が同時に指定されていない、または正の整数ではない
+- `color_pixel_size`が`null`でも`pixel_size`以上の正の有限値でもない
+- `image_fit`が`cover`または`contain`ではない
+- クロップ位置が0〜1の範囲外、または`crop_scale`が0より大きく1以下ではない
+- 要求最小厚さが要求最大厚さを超える
+- ノズル径が0.2または0.4ではない
+- 色モデルが`cmy`ではない
+- 色領域が4層、5層、7層のいずれでもない
+- 顔料順にCyan、Magenta、Yellowが各1回含まれない
+- 余白が負、非数、または左右・上下の合計が画像領域を残さない
+- 要求厚さ内に印刷可能なレイヤー境界がない
+- 標準構造に必要な下地、色領域、上部Whiteを収容できない
+- 推定STLまたは実際のCMYW 3MFが設定された`maximum_triangles`を超える
+- 入力画像が設定された`maximum_input_pixels`を超える
+
+## レイヤー境界と実効厚さ
+
+要求厚さは、第1層と通常レイヤーで構成できるZ境界へ丸めます。実効最小厚さは要求値以上の最初の境界、実効最大厚さは要求値以下の最後の境界です。
+
+```text
+requested: 1.0–2.14689422 mm
+effective: 1.0–2.14689422 mm
+```
+
+標準構造では、0.0〜0.2 mmをWhite下地、0.2〜0.9 mmを7層の色領域、0.9〜1.0 mmをWhite、1.0 mm以上を0.04 mm刻みのWhiteとして扱います。最後の上面だけは2.14689422 mmで閉じます。
+
+## 積層構造の比較
+
+`color_layer_count`と`pigment_order`は、標準の7層・Cyan、Magenta、Yellow順と、比較用の4層・5層や別順序を再現する設定です。Whiteは顔料列の後ろに固定されます。
+
+## 校正片に使う設定
+
+`lithop calibrate`は、厚さ、ノズル、レイヤー高さ、色モデル、色領域の層数、顔料順、三角形数上限を設定から読みます。固定レイアウトのため、`width`、`height`、`margin_*`、画像配置、`pixel_size`、`color_pixel_size`、`maximum_input_pixels`は使いません。
+
+現在の校正片は7層・`cyan,magenta,yellow`順と、White厚みを8段階取れる範囲を要求します。通常生成で使う`--calibration-profile`は入力設定キーではなくCLIオプションです。詳しくは[色校正](calibration.md)を参照してください。
+
+## 出力される settings.json
+
+出力側の`settings.json`は入力設定ではなく、確定値、実効値、制限値、入力元、校正情報を記録します。全キーと例は[出力されるsettings.json](artifacts.md#出力される-settingsjson)を参照してください。この見出しは既存リンクとの互換性のために残しています。
+
+## manifest.jsonとの違い
+
+入力設定、出力設定、manifestの役割は[manifest.jsonとの違い](artifacts.md#manifestjsonとの違い)を参照してください。この見出しは既存リンクとの互換性のために残しています。
+
+## Bambu Studioの設定
+
+選択したノズルとレイヤー高さは記録されますが、3MFへスライサープリセットとして埋め込みません。[Bambu Studioでの確認と印刷](bambu-studio.md)に従い、同じ値を設定してください。
+
+## 情報表示オプション
+
+`--help`と`--version`の対応は[バージョンとヘルプを表示する](command.md#バージョンとヘルプを表示する)を参照してください。

data/docs/getting-started.md

@@ -0,0 +1,98 @@
+# 導入と基本操作
+
+Lithopは、画像からカラーLithophane（リトファン）の3MFとWhite参照STLをローカルで生成します。このページでは小型モデルを作り、印刷前の確認へ進むところまでを扱います。
+
+## 準備
+
+- macOS
+- Ruby 4.0以上
+- JPEG、PNG、SVG（librsvg）、ICCプロファイルを扱えるlibvips
+- 印刷する場合はBambu Studio、AMS対応プリンタ、必要なCMYWフィラメント
+
+標準構造は0.2 mmノズル、White下地2層、CMYW色領域7層、連続高のWhite上面を使います。Lithopはスライスや印刷開始を行いません。
+
+## インストール
+
+公開版0.1.0を使う場合は、libvipsとバージョンを指定したLithopをインストールします。
+
+```sh
+brew install vips
+gem install lithop -v 0.1.0
+lithop --version
+```
+
+`lithop --version`が`0.1.0`を表示することを確認します。
+
+ソースチェックアウトから実行する場合は、代わりに次を実行します。
+
+```sh
+bin/setup
+bundle exec lithop --version
+```
+
+RubyGemとCLIの名前は`lithop`、Ruby APIの名前空間は`Lithop`です。
+
+## 最初の3MFを生成する
+
+ソースチェックアウトでは、同梱画像から20 × 15 mm、XYセル0.5 mmの小型モデルを生成します。
+
+```sh
+bundle exec lithop examples/cmy-fine-line.svg --width 20 --height 15 --pixel-size 0.5
+```
+
+インストール済みgemでは、手元のJPEG、PNG、またはSVGを指定します。
+
+```sh
+lithop path/to/image.png --width 20 --height 15 --pixel-size 0.5
+```
+
+成功すると、書き出し前の見積り、確定した三角形数、新しい`build/<job_id>/`の絶対パス、ファイル一覧が表示されます。完了済みジョブは上書きされません。
+
+## 設定を調整する
+
+最初は小型モデルと0.5 mm程度のセルで確認してください。`pixel_size`を小さくすると細部が増える一方、三角形数、処理時間、メモリ使用量も増えます。
+
+幅、高さ、4辺のWhite余白、厚さ、セル寸法、ノズル、レイヤー高さ、色領域の層数と顔料順を指定できます。全オプションは[コマンドリファレンス](command.md#画像からリトファンを生成する)、繰り返し使うJSON設定と既定値は[生成オプションと設定ファイル](config.md)を参照してください。
+
+既定では外周なしの140 × 104 mmモデルを標準構造で生成します。
+
+```sh
+bundle exec lithop path/to/image.jpeg
+```
+
+CLIで指定した値は`config/settings.json`より優先されます。ノズル径は生成記録に保存されますが、形状やレイヤー高さを自動変更しないため、Bambu Studioにも同じ条件を設定してください。
+
+## 入力画像の扱い
+
+対応形式はJPEG、PNG、非圧縮SVGです。LithopはEXIF Orientationを適用し、透過部分をWhiteへ合成し、埋め込みICCプロファイルを使ってsRGBへ変換します。SVGは96 DPIを基準に、厚さ格子と色格子を満たす解像度へメモリ内で描画します。PNGの中間ファイルは作りません。SVGファイルの上限は15,000,000バイト（15 MB）です。既定では指定した縦横比へ中央クロップします。構図は`--crop-position-x`、`--crop-position-y`、`--crop-scale`で調整でき、`--image-fit contain`では画像全体をWhite領域内へ収められます。
+
+SVGは正の`width`・`height`（単位なし、`px`、`mm`、`in`）または`viewBox`を必要とします。文書内の`#id`参照は利用できますが、別ファイル、HTTP(S)、`data:`、外部CSS、DTD、スクリプト、アニメーション、`foreignObject`は利用できません。文字の形はローカルフォントに依存するため、再現性が必要な場合はパスへ変換してください。SVGZには対応していません。
+
+厚さセルと色セルは既定で同じ`--pixel-size`を使います。色の細部だけ粗くまとめる場合は`--color-pixel-size`を指定します。全入力項目は[生成オプションと設定ファイル](config.md#生成設定)を参照してください。
+
+上部Whiteの高さは、材料表示色と同梱カラーチャートの配合色では図中の明暗値を使い、それ以外の入力色ではRec.601輝度を使います。このため、カラーチャートではYellowを含む全色列の同じ明暗行が同じWhite高さになります。
+
+入力画像はその場で読み取ります。変更、アップロード、`build/`へのコピー、削除は行いません。
+
+## 結果を確認する
+
+最初に次を開きます。
+
+- `preview.png`: 実際に選択された公称レシピ色と相対的な厚さの確認用。測色予測ではありません
+- `transmission.png`: White厚さによる相対透過明度
+- `thickness.png`: セル単位の厚さ
+- `cyan-mask.png`など4枚: 各材料の層数。全画像で同じ明度尺度を使用
+
+各画像の1画素は3MFの1セルで、左上がモデルの`+Y`側です。入力画像と向き、色、明暗、材料層数を比較してください。全ファイルとJSONの説明は[生成物と記録](artifacts.md)にあります。
+
+確認後、`lithop.3mf`をBambu Studioへモデルとして読み込みます。材料部品を個別に移動、整列、拡大縮小、結合しないでください。
+
+## 生成物を削除する
+
+`lithop clean`は、選択したプロジェクトの`build/`全体を完全に削除します。個別ジョブの削除ではなく、元に戻せません。実行前に対象パスを確認してください。
+
+安全条件と全オプションは[生成物を削除する](command.md#生成物を削除する)を参照してください。
+
+## 次の手順
+
+[Bambu Studioでの確認と印刷](bambu-studio.md)へ進み、材料割り当てと全レイヤーを確認してください。印刷物の発色を実測値で合わせる必要がある場合だけ、[色校正](calibration.md)の任意手順を使用します。