lithop 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 13a626692e6ae5bd67e88bb4f81e0cf8ae8ad6fb220e5cdb4822a582eaec6dd7
+  data.tar.gz: 1497a224597acc9416aa67961969aeeb868981581af93cff6fb7e0bada32d781
+SHA512:
+  metadata.gz: 879e0cc070dfd33464e12504d5409b2b98df8ff1f576e716c818968875cab637a9f315ddf41bd021c391e3c88e222ebc3eddb29dcbbecf002531b9b80068a743
+  data.tar.gz: 3ce5b71121d43b5c58ffb9bee086cf59e36ab1550554a007742ffc76852a2350b2e3dc49ec14596f4bc4caa4022efb1a53b752103eddfb18084d60a1ca454b31

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 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.
+- Uses the standard 0.2 mm nozzle profile with two White base layers, seven `Cyan -> Magenta -> Yellow -> White` color layers, and a continuous upper White surface; four- and five-layer comparisons remain available.
+- Maps material display colors and five-percent chart mixtures to labeled recipes, and generates matching 140 × 104 mm calibration SVG/3MF files with all 120 recipes and eight White thickness stages.
+- Supports optional measured color and physical White-thickness calibration, JSON/CLI overrides, image placement, independent color cells, atomic output, Bambu metadata, previews, manifests, and safe cleanup; the 0.2 mm fine-line target is print-verified, while the current full chart and numerical color measurement remain pending.

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 ogom
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,126 @@
+# Lithop
+
+Create backlit color lithophanes locally.
+
+Lithop is a command-line CMYW color lithophane generator. It turns a JPEG, PNG, or validated self-contained SVG image into a single-plate multipart CMYW 3MF and a White reference STL without uploading, modifying, or copying the source image into the output job.
+
+## Status and safety
+
+The standard profile uses:
+
+| Setting | Standard value |
+| --- | --- |
+| Model size | 140 × 104 mm |
+| Thickness grid | 637 × 473 cells, approximately 0.22 mm per cell |
+| Nozzle | 0.2 mm |
+| White base | Two 0.1 mm layers |
+| Color region | Seven 0.1 mm CMYW layers in `Cyan -> Magenta -> Yellow -> White` order |
+| Upper White | Continuous height field from 1.0 to 2.14689422 mm, sliced at 0.04 mm |
+| Extruders | Cyan=1, Magenta=2, Yellow=3, White=4 |
+
+Bambu Studio restores the generated single `lithophane` plate and its White/Cyan/Magenta/Yellow assignments. The bundled fine-line target has been printed successfully with the current 0.2 mm, seven-layer standard. The current 140 × 104 mm color chart has been sliced and inspected in Bambu Studio, but it has not been physically printed with the 0.2 mm standard; its 120 recipes and eight White thickness stages have not been measured numerically. Colorimetric accuracy is not guaranteed.
+
+Before printing, inspect every layer and confirm the Cyan, Magenta, Yellow, and White assignments. Do not move, align, scale, or merge individual material parts. Lithop does not slice models, send print jobs, or control a printer or AMS.
+
+## Requirements
+
+- macOS and Ruby 4.0 or later
+- libvips with JPEG, PNG, SVG (librsvg), and ICC profile support
+- For physical printing: Bambu Studio, an AMS-capable printer, and the required PLA Basic Cyan, Magenta, Yellow, and White filaments
+
+## Install
+
+To install the 0.1.0 release from RubyGems, install libvips and the matching Lithop version:
+
+```sh
+brew install vips
+gem install lithop -v 0.1.0
+lithop --version
+```
+
+The version command must print `0.1.0`.
+
+To work from a source checkout instead:
+
+```sh
+bin/setup
+bundle exec lithop --version
+```
+
+## Quick start
+
+With an installed gem, generate a model from one JPEG, PNG, or SVG:
+
+```sh
+lithop path/to/image.png
+```
+
+From a source checkout, use the bundled sample and a coarse cell size for a faster first run:
+
+```sh
+bundle exec lithop examples/cmy-fine-line.svg --width 20 --height 15 --pixel-size 0.5
+```
+
+The standard command generates the 140 × 104 × 2.14689422 mm, 0.2 mm-nozzle layout:
+
+```sh
+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.
+
+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.
+
+See [installation and basic use](docs/getting-started.md), the [artifact reference](docs/artifacts.md), and the [Bambu Studio checklist](docs/bambu-studio.md) before printing.
+
+## Input and settings
+
+JPEG and PNG input supports EXIF orientation, transparency composited over White, and embedded ICC conversion to sRGB. SVG input is rendered in memory through librsvg and must be an uncompressed, static, self-contained document no larger than 15,000,000 bytes. External files, network URLs, data URLs, external CSS, DTDs, scripts, animation, and `foreignObject` are rejected.
+
+Settings resolve in `command line > JSON file > built-in defaults` order. A project can keep reusable overrides in `config/settings.json`:
+
+```json
+{
+  "layout_profile": "standard",
+  "width": 140.0,
+  "height": 104.0
+}
+```
+
+The command-line options can override individual profile values. Use `--color-pixel-size` to make CMYW recipe cells coarser than the White thickness grid, and `--image-fit`, crop, and margin options to control placement. See [options and settings](docs/config.md) for the complete input schema and validation rules.
+
+## Other commands
+
+- `lithop calibrate` creates a 140 × 104 mm calibration SVG and matching printable 3MF with all 120 seven-layer recipes, eight White thickness stages, and a measurement-profile template. A completed measured profile can select both color recipes and the physical White height used by the 3MF, STL, previews, thickness map, and material masks. See [color calibration](docs/calibration.md).
+- `lithop clean` permanently removes the selected project's complete `build/` directory, not one job. See the [command reference](docs/command.md#生成物を削除する) before using it.
+- `lithop --help`, `lithop calibrate --help`, and `lithop clean --help` show the current command syntax.
+
+## Documentation
+
+- [Documentation index and verification status](docs/README.md)
+- [Installation and basic use](docs/getting-started.md)
+- [Bambu Studio verification and printing](docs/bambu-studio.md)
+- [Options and settings](docs/config.md)
+- [Artifacts and generation records](docs/artifacts.md)
+- [CMYW color model and layer structure](docs/color-model.md)
+- [Optional measured calibration](docs/calibration.md)
+- [Command reference](docs/command.md)
+- [Troubleshooting](docs/troubleshooting.md)
+
+## Ruby API and development
+
+The RubyGem and CLI command are named `lithop`; the Ruby namespace is `Lithop`. Supported public signatures are declared in [`sig/lithop.rbs`](sig/lithop.rbs). Helper classes under `lib/lithop/export/`, `lib/lithop/cli/`, and `lib/lithop/formats/three_mf/` are internal unless listed there.
+
+```sh
+bin/setup
+bundle exec rake
+bundle exec rbs validate
+```
+
+Before publishing, run `bundle exec rake release:check` and follow [RELEASING.md](RELEASING.md).
+
+## License
+
+[MIT](LICENSE)

data/RELEASING.md

@@ -0,0 +1,63 @@
+# Releasing lithop
+
+This checklist prepares and publishes one immutable gem version. Run every command from the repository root.
+
+## 1. Prepare the version
+
+1. Update `Lithop::VERSION` in `lib/lithop/version.rb`.
+2. Add or update the matching version and release date in `CHANGELOG.md`. Keep the changelog concise; add an `Unreleased` section only when subsequent changes need one.
+3. Confirm the README installation and usage examples match the release.
+4. Manually open the external links in `README.md` and `docs/`; automated tests intentionally validate only local links and anchors.
+5. Commit all intended files and verify that `git status --short` is empty.
+6. Run the non-publishing release check:
+
+```sh
+bundle exec rake release:check
+```
+
+The check runs the specs, RuboCop, and RBS validation; builds the gem; checks its version, metadata, runtime dependency, and packaged documentation; installs it into a temporary isolated gem directory; and executes the installed `lithop --version` command.
+
+## 2. Prepare publishing services
+
+Confirm the release commit is on the intended release branch, the repository has an `origin` remote, and GitHub CLI authentication is active:
+
+```sh
+git branch --show-current
+git remote -v
+gh auth status
+```
+
+Before the first release, confirm that the `lithop` name is available on RubyGems.org. For manual publishing, sign in and enable MFA:
+
+```sh
+gem signin
+```
+
+For later releases, confirm that the account owns the gem:
+
+```sh
+gem owner lithop
+```
+
+Alternatively, configure a RubyGems.org trusted publisher for this repository and its exact publishing workflow. Never commit an API key or `~/.gem/credentials`.
+
+## 3. Publish deliberately
+
+`bundle exec rake release` is a publishing command. It creates and pushes the version tag and publishes the gem to RubyGems.org. Run it only after `release:check` passes and the working tree is clean:
+
+```sh
+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:
+
+```sh
+gh release create v0.1.0 lithop-0.1.0.gem --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
+lithop --version
+```

data/bin/lithop

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "lithop"
+
+exit Lithop::CLI.run(ARGV)

data/docs/README.md

@@ -0,0 +1,44 @@
+# Lithopドキュメント
+
+Lithopは、JPEG、PNG、SVGからCMYW材料のカラーLithophane（リトファン）3MFと、White参照STLを生成するローカルCLIです。画像を外部へ送信せず、入力画像自体を生成ジョブへコピーしません。
+
+## 安全と現在の検証範囲
+
+- 標準は0.2 mmノズル、White下地2層、CMYW色領域7層、連続高のWhite上面を使います。
+- Bambu Studioで単一プレートとWhite/Cyan/Magenta/Yellowの割り当て復元を確認済みです。0.2 mmノズルで実機印刷済みなのは細線評価片です。現行140 × 104 mmカラーチャートはBambu Studioで形状を確認済みですが、実機印刷は未実施です。
+- 現行カラーチャートの120レシピとWhite厚み8段階は数値測色していません。
+- 数値測色は必須にしておらず、入力画像やプレビューとの測色的一致は保証しません。
+- Lithopはスライス、印刷開始、プリンタやAMSの操作を行いません。
+- 印刷前にBambu Studioで材料割り当てと全レイヤーを確認してください。
+
+## 初めて使う
+
+- [導入と基本操作](getting-started.md) — インストール、小型モデルの生成、最初に見る成果物
+
+## 印刷・校正する
+
+- [Bambu Studioでの確認と印刷](bambu-studio.md) — 材料割り当て、スライス条件、印刷前チェック
+- [色校正](calibration.md) — 校正片、目視確認、任意の実測プロファイル
+
+## 仕様を調べる
+
+- [生成物と記録](artifacts.md) — ジョブ、全成果物、プレビュー、`settings.json`、`manifest.json`
+- [生成オプションと設定ファイル](config.md) — 設定の優先順位、入力JSON、既定値、検証規則
+- [コマンドリファレンス](command.md) — 構文、全オプション、終了ステータス
+- [CMYWの色モデルと積層構造](color-model.md) — 材料、減法混色、White厚み、3MF構造
+
+## 問題を解決する
+
+- [トラブルシューティング](troubleshooting.md) — 読み込み、材料、色、サイズ、削除に関する対処
+
+CLIの現在の構文は、次のコマンドでも確認できます。
+
+```sh
+lithop --help
+lithop calibrate --help
+lithop clean --help
+```
+
+## 文書の位置づけ
+
+`docs/`は、人がLithopを操作・印刷・評価するための利用者向け文書で、RubyGemにも含まれます。実装上の不変条件は`spec/`、設計検討や未確定の作業計画は配布対象外の`doc/`に置きます。

data/docs/artifacts.md

@@ -0,0 +1,122 @@
+# 生成物と記録
+
+Lithopは生成中のファイルを一時ディレクトリへ書き、すべて成功した後に完了済みジョブとして公開します。このページは通常ジョブと校正ジョブの成果物、およびJSON記録の正本です。
+
+## ジョブディレクトリ
+
+通常生成は`build/<job_id>/`、校正片生成は`build/<job_id>-calibration/`へ保存します。ジョブIDはUTC時刻とランダム値から作られます。
+
+生成中は`build/.tmp-<job_id>/`を排他的に取得します。失敗または中断した実行は自分が作成した一時領域だけを回収し、入力画像、別の実行の一時領域、完了済みジョブを削除しません。完了済みジョブと同じIDは上書きしません。
+
+## 通常ジョブのファイル
+
+| ファイル | 内容 |
+| --- | --- |
+| `lithop.3mf` | 使用するCyan、Magenta、Yellow、Whiteの材料別メッシュを持つカラー用モデル |
+| `cmyk_white.stl` | 厚さマップから作るWhite単色の参照リトファン |
+| `preview.png` | 公称レシピ色に相対的な厚さの明暗を重ねた確認用画像 |
+| `transmission.png` | White厚さによる相対透過明度 |
+| `thickness.png` | セル単位の厚さマップ |
+| `cyan-mask.png` | Cyanの層数マップ |
+| `magenta-mask.png` | Magentaの層数マップ |
+| `yellow-mask.png` | Yellowの層数マップ |
+| `white-mask.png` | Whiteの層数マップ |
+| `settings.json` | 解決済み設定、実効値、制限値、入力元のパス |
+| `manifest.json` | 寸法、ハッシュ、材料、レシピ、三角形数、成果物の記録 |
+| `PRINT_README.md` | そのジョブ固有の印刷前チェック |
+| `calibration-profile.json` | 実測プロファイルを指定した場合だけ保存するコピー |
+
+標準ジョブは単一プレートと非一様レイヤー情報を持つ`lithop.3mf`を出力します。未使用のCyan、Magenta、Yellowは3MFのメッシュから省略されるため、材料部品は1〜4個です。Whiteは必ず含まれます。`cmyk_white.stl`は比較用で、CMYWの材料分離情報を持ちません。
+
+## プレビューの座標と値
+
+全プレビューの1画素は3MFの1セルに対応し、左上がモデルの`+Y`側です。材料マスクは黒が0層で、明るいほど層数が多く、4材料で同じ明度尺度を使います。
+
+`preview.png`は、3MFと同じ材料モデルが選択したレシピとWhite厚さを可視化します。表示色そのものの明るさも含むため、異なる色同士のWhite高さを比較する画像ではありません。高さは`thickness.png`、材料層数は4枚のマスクで確認します。未校正時はフィラメントの実測透過色を使わないため、入力画像や印刷物との測色的一致を予測するものではありません。
+
+通常画像の連続White高さはRec.601輝度から求めます。材料表示色と同梱カラーチャートの配合色には定義済みの明暗値を使うため、同じ明暗行ではYellowを含む全色列が同じ高さになります。
+
+実測校正プロファイルを指定した場合は、White厚み8段階の測定輝度から最も近い高さを選びます。選択結果は3MF、参照STL、プレビュー、厚み画像、材料マスクで共通です。
+
+## 出力される settings.json
+
+`settings.json`は入力用設定ファイルではなく、そのジョブで確定した値の記録です。代表的な構造は次のとおりです。
+
+```json
+{
+  "layout_profile": "standard",
+  "width": 140.0,
+  "height": 104.0,
+  "margin_top": 0.0,
+  "margin_right": 0.0,
+  "margin_bottom": 0.0,
+  "margin_left": 0.0,
+  "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.22,
+  "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,
+  "maximum_input_pixels": 20000000,
+  "maximum_triangles": 5000000,
+  "effective_color_pixel_size": 0.22,
+  "effective_minimum_thickness": 1.0,
+  "effective_maximum_thickness": 2.14689422,
+  "columns": 637,
+  "rows": 473,
+  "pixel_size_x": 0.21978021978021978,
+  "pixel_size_y": 0.21987315010570824,
+  "schema_version": 1,
+  "generator_version": "0.1.0",
+  "input_path": "/absolute/path/to/image.png",
+  "input_settings_path": "/absolute/path/to/config/settings.json",
+  "calibration_profile_id": null,
+  "calibration_profile_path": null
+}
+```
+
+入力可能なキーに加え、レイヤー境界へ丸めた実効厚さ、格子寸法、生成器版、入力元、校正情報を含みます。そのまま`config/settings.json`として再利用せず、[生成設定](config.md#生成設定)にある入力キーだけをコピーしてください。
+
+## manifest.jsonとの違い
+
+| ファイル | 目的 |
+| --- | --- |
+| 入力側の`config/settings.json` | 繰り返し使う生成条件を指定する |
+| 出力側の`settings.json` | CLIと設定ファイルを統合した確定値、実効値、制限値、入力元を記録する |
+| `manifest.json` | ジョブID、入力SHA-256、寸法、印刷条件、材料プロファイル、積層構造、使用材料、レシピ、三角形数、成果物一覧を記録する |
+
+`manifest.json`の`dimensions_mm`には幅、高さ、実効最大厚さを保存します。`color_model`には、校正ID、色領域の層数と顔料順、White厚み構造、使用／未使用材料、材料別三角形数、レシピ集計、プレビュー方式が入ります。計画時と書き出し後の3MF三角形数は一致を検証してから保存します。
+
+## 校正ジョブのファイル
+
+| ファイル | 内容 |
+| --- | --- |
+| `calibration.svg` | 140 × 104 mmの編集可能なパッチ配置図。パッチIDと向きの確認用 |
+| `calibration.3mf` | 全120レシピ、White厚み8段階、向き判別列を持つ校正片 |
+| `calibration-profile.json` | 各パッチの反復測定値を追加するプロファイル雛形 |
+| `manifest.json` | 積層条件、配置、材料数、三角形数を記録する生成情報 |
+| `CALIBRATION_README.md` | パッチ配置と測定値の記入方法 |
+
+校正プロファイルの記入と適用は[色校正](calibration.md)を参照してください。
+
+## ローカルパスと共有時の注意
+
+入力画像自体はジョブへコピーされません。ただし、`settings.json`の`input_path`、`input_settings_path`、`calibration_profile_path`にはローカルのディレクトリ名やファイル名が含まれます。Issueや第三者へ共有する前に機密情報がないか確認してください。
+
+`manifest.json`には入力画像のSHA-256が含まれます。公開してよい識別情報か判断してから共有してください。

data/docs/bambu-studio.md

@@ -0,0 +1,93 @@
+# Bambu Studioでの確認と印刷
+
+標準の`lithop.3mf`は、単一`lithophane`プレート、CMYW割り当て、上部Whiteのレイヤー範囲を持ちます。単一プレートとWhite/Cyan/Magenta/Yellow割り当ての復元はBambu Studioで確認済みです。G-code、温度、速度、AMS実スロット、機種固有の開始・終了コードを含まないため、その他の印刷条件はBambu Studio側で確認します。
+
+標準構造は0.2 mmノズル、White下地2層、7層の`Cyan -> Magenta -> Yellow -> White`、連続高のWhite上面を使います。以下の確認をすべて終えるまで印刷を開始しないでください。
+
+## 現在の確認範囲
+
+- 単一プレートとWhite/Cyan/Magenta/Yellow割り当ての復元は確認済み
+- 0.2 mmノズル、7層構造の細線評価片は問題なく印刷完了
+- 現行カラーチャートを0.2 mmノズル・0.1 mm積層ピッチで再スライスし、第1・8・15・30・39層の外形、グリッド、ラベル、各セルに形状欠落がないことを確認済み
+- 現行140 × 104 mmカラーチャートの0.2 mmノズルによる実機印刷は未実施
+- 120レシピの数値測色は未実施で、測色的一致は保証しない
+
+材料製品、表示色、積層の設計は[CMYWの色モデルと積層構造](color-model.md)を参照してください。
+
+## 小型モデルを準備する
+
+最初は同梱画像と粗いXYセルで小型モデルを作ります。
+
+```sh
+bundle exec lithop examples/cmy-fine-line.svg --width 20 --height 15 --pixel-size 0.5
+```
+
+表示された`build/<job_id>/`で、`preview.png`、`PRINT_README.md`、`settings.json`、`manifest.json`を確認してから`lithop.3mf`を開きます。自分のジョブIDと印刷条件は`manifest.json`に記録されています。
+
+## 3MFを読み込む
+
+1. `cmyk_white.stl`ではなく`lithop.3mf`をモデルとして読み込む。
+2. 一つの親オブジェクトの下に、使用材料の部品が同じ位置で組み立てられていることを確認する。
+3. 部品を個別に移動、整列、拡大縮小、結合しない。
+4. 各部品のExtruder番号と材料を確認する。
+5. Extruderと実際に装填したAMSスロットの対応を確認する。
+
+| Extruder | 材料 |
+| ---: | --- |
+| 1 | PLA Basic Cyan |
+| 2 | PLA Basic Magenta |
+| 3 | PLA Basic Yellow |
+| 4 | PLA Basic White |
+
+標準出力はCyan=1、Magenta=2、Yellow=3、White=4です。Blackスロットは追加しません。
+
+未使用のCyan、Magenta、Yellowは省略されますが、残る番号は詰めません。Bambu Studioの表示は版によって異なるため、部品名や画面上の色だけで判断しないでください。
+
+## スライス条件を合わせる
+
+| 項目 | 確認内容 |
+| --- | --- |
+| ノズル | 生成時の0.2 mmまたは0.4 mm。既定は0.2 mm |
+| 下地White | 既定は0.1 mmを2層 |
+| 色レイヤー | 既定は0.1 mm |
+| 色領域 | 既定は7層、Cyan -> Magenta -> Yellow -> White |
+| 上部White | Z=1.0 mm以上を0.04 mmでスライス |
+| 充填 | 100 % rectilinear |
+| 向き | 平らな背面をZ=0、完成後は+Z側から見る |
+
+実際の値はそのジョブの`settings.json`と`PRINT_README.md`を優先します。生成側とスライサー側のZ境界が異なると、材料層が消失または混在する可能性があります。
+
+フィラメントの取り扱いと対応アクセサリは、製品情報と[Bambu LabのCMYKリトファン印刷ガイド](https://wiki.bambulab.com/en/knowledge-sharing/CMYK-color-lithophane-printing-instructions)で最新情報を確認してください。
+
+## レイヤープレビューを確認する
+
+レイヤープレビューを下から上まで動かし、すべて確認します。
+
+- 最初の2層が連続したWhiteである
+- 色領域の層数と材料順が`settings.json`、`manifest.json`と一致する
+- 0.9〜1.0 mmがWhiteで、1.0 mm以上に連続高のWhite上面がある
+- Cyan、Magenta、Yellowの必要な領域が消えていない
+- 材料同士の重複、穴、孤立領域、浮遊形状がない
+- 画像の上下左右が正しい
+- 幅、高さ、最大厚さが生成記録と一致する
+
+一つでも確認できない場合は印刷を開始しないでください。材料が分かれない場合は[3MFの材料が期待した色に分かれない](troubleshooting.md#3mfの材料が期待した色に分かれない)を参照してください。
+
+標準ジョブではWhite下地2層、元画像のsRGBから選ぶCMY/W色領域7層、0.9〜1.0 mmのWhite、その上の0.04 mmレイヤーを確認します。外周、Black部品、写真フレーム、導光板は含みません。
+
+## 初回印刷を記録する
+
+小型モデルを白色バックライトで確認し、少なくとも次を記録します。
+
+```text
+Lithop version / Job ID:
+Bambu Studio version:
+Printer / nozzle / build plate:
+First layer / layer height / infill:
+AMS slot 1 / 2 / 3 / 4:
+Filament product and lot:
+Backlight:
+Result and observations:
+```
+
+条件の異なる結果を混在させないため、校正を行う場合もこの記録を使用します。

data/docs/calibration.md

@@ -0,0 +1,126 @@
+# 色校正
+
+Lithopの標準構造は、2層のWhite下地、7層のCMYW色領域、連続した上部Whiteで構成されます。未校正出力は材料の表示色を基準にレシピを選ぶため、実際のフィラメント、プリンタ、バックライトを含む測色的一致は保証しません。
+
+目視結果で用途を満たす場合、数値校正は不要です。使用する材料と観察条件で透過色を測り、入力色に近いレシピと明るさに対応する厚みを選びたい場合に、任意の実測プロファイルを使用します。
+
+## 現在の校正片
+
+`lithop calibrate`は画像を変換せず、標準パレットのセルから校正SVGと印刷用3MFを直接生成します。レイアウトの物理サイズは[`examples/cmy-color-chart.svg`](../examples/cmy-color-chart.svg)と同じ140 × 104 mmです。
+
+| 項目 | 現在の仕様 |
+| --- | --- |
+| 物理サイズ | 140 × 104 mm |
+| 配置 | 16列 × 9行 |
+| レシピ | `R000`〜`R119`の120種類 |
+| White厚み | `W00`〜`W07`の8段階 |
+| 標準ノズル | 0.2 mm |
+| 第1層／通常レイヤー | 0.1 mm／0.1 mm |
+| 色領域 | 7層、`Cyan -> Magenta -> Yellow -> White` |
+
+120レシピは、7層をCyan、Magenta、Yellow、Whiteへ配分できる全組み合わせです。レシピは先頭8行の15列を使い、鑑賞面から見て上段左の`R000`から行優先で並びます。各セルは横8.125 mm、縦約11.111 mmです。
+
+下段の`W00`から`W07`は、全7色層をWhiteに固定して上部Whiteの厚みだけを変えます。現在の標準設定では、総厚は順に1.0、1.16、1.32、1.48、1.64、1.8、2.0、2.14689422 mmです。値は最小・最大厚さと印刷可能なZ境界から算出されるため、厚さ設定を変更した場合は生成された`calibration-profile.json`の`total_thickness_mm`を正本とします。
+
+右端は向き判別用のWhite列で、上端に`TOP`を表示します。下段の未使用セルもWhiteです。`calibration.svg`はパッチID、色、向きを確認する編集可能な配置図です。材料の積層と厚みを持つ印刷データは、同時に生成される`calibration.3mf`です。
+
+## 校正片を生成する
+
+プロジェクトの`config/settings.json`を使う場合は次を実行します。
+
+```sh
+bundle exec lithop calibrate
+```
+
+別の設定ファイルを使う場合は`--config`、別のプロジェクトへ出力する場合は`--project-dir`を指定します。校正片は7層・`cyan,magenta,yellow`順と、相異なるWhite厚みを8段階生成できる厚さ範囲を要求します。画像用の幅、高さ、余白、配置、ピクセルサイズは使用しません。
+
+`build/<job_id>-calibration/`へ次の5ファイルを生成します。
+
+| ファイル | 用途 |
+| --- | --- |
+| `calibration.svg` | 140 × 104 mmのパッチ配置、ID、向きを確認する |
+| `calibration.3mf` | Bambu Studioで材料、積層、厚みを確認して印刷する |
+| `calibration-profile.json` | 材料、光源、測定条件、各パッチの測定値を記録する |
+| `manifest.json` | 積層構造、配置、材料数、三角形数を確認する |
+| `CALIBRATION_README.md` | 生成時の設定とパッチ配置を確認する |
+
+全ファイルの定義は[校正ジョブのファイル](artifacts.md#校正ジョブのファイル)、コマンドの全オプションは[校正片を生成する](command.md#校正片を生成する)、読み込む設定は[校正片に使う設定](config.md#校正片に使う設定)を参照してください。
+
+印刷前に[Bambu Studioのレイヤープレビュー](bambu-studio.md#レイヤープレビューを確認する)で、単一プレート、White/Cyan/Magenta/Yellowの割り当て、全レイヤー、140 × 104 mmの寸法を確認します。3MFの寸法、レイヤー高さ、材料順は変更しません。
+
+## 測定プロファイルを記入する
+
+生成直後の`calibration-profile.json`は`status: "draft"`の雛形です。次の条件を記録します。
+
+- Cyan、Magenta、Yellow、Whiteの材料ロット
+- バックライトの種類、色温度、照度
+- 測定方法、機器、測定不確かさ
+- 光源だけを測った白点と、遮光時の黒点
+- 120レシピとWhite厚み8段階の測定値
+
+各パッチの`measurements`配列へ、同じ条件で測った値を1件以上追加します。反復測定は複数件をそのまま追加できます。
+
+```json
+{
+  "transmitted_srgb": [0.81, 0.62, 0.35],
+  "luminance": 118.4,
+  "error": 1.7
+}
+```
+
+`transmitted_srgb`は0〜1の3要素、`luminance`は0以上、任意の`error`も0以上です。`measurement.white_point`と`measurement.black_point`にも同じ形式の測定値を記録します。条件が変わった場合は値を混在させず、新しい校正ジョブまたはプロファイルとして管理します。
+
+カメラを使う場合は、自動露出、自動ホワイトバランス、HDR、画像補正を無効にし、同じ撮影条件を維持します。カメラ値を測色計の値と同等には扱わず、`measurement.method`と`measurement.device`へ方法と機器を記録します。
+
+## 測定手順
+
+1. `calibration.svg`でパッチIDと向きを確認する。
+2. `calibration.3mf`をBambu Studioで開き、材料割り当てと全レイヤーを確認して印刷する。
+3. 十分に冷却し、一定のバックライトと周囲光を用意する。
+4. 各パッチの中央を測色するか、固定した条件でRAW撮影する。
+5. 光源だけの白点と、遮光時の黒点を測る。
+6. 測定値を対応するパッチの`measurements`へ追加する。
+7. 必要に応じて同じ条件で反復し、材料、光源、機器、誤差を記録する。
+
+## 実測プロファイルを使う
+
+全128パッチと白点・黒点を記入したプロファイルを、通常生成の`--calibration-profile`へ指定します。
+
+```sh
+bundle exec lithop image.png \
+  --calibration-profile build/<calibration-job-id>-calibration/calibration-profile.json
+```
+
+読み込み時には、次の条件を検証します。
+
+- スキーマ版とJSONの形式が正しい
+- ノズル径、レイヤー高さ、色領域の層数、顔料順が現在の設定と一致する
+- 120レシピが現在のパレットと一致する
+- White厚みパッチが相異なる8段階ある
+- 全パッチに1件以上の測定値がある
+- 白点と黒点がある
+- White厚みの測定輝度に差がある
+
+条件を満たさない場合は、通常ジョブを作る前に生成を中止します。
+
+## 実測値の使い方
+
+同じパッチに複数の測定値がある場合、`transmitted_srgb`と`luminance`をそれぞれ平均します。
+
+色レシピは、各パッチの平均`transmitted_srgb`を最大成分で正規化し、入力色から求めたRGB比に最も近いものを120レシピから選びます。この段階では明るさを除いた色成分を比較します。
+
+厚みは、入力のWhite明暗密度0〜1を、White厚み8段階で測った最も明るい輝度から最も暗い輝度までへ線形に対応させ、目標輝度に最も近い段階を選びます。通常画像のWhite明暗密度はRec.601輝度から求め、材料表示色と同梱カラーチャートの配合色では定義済みの明暗値を使います。選択した厚みは現在のレイヤー境界へ丸めます。
+
+選択した同じWhite高さを`lithop.3mf`のWhite形状、`cmyk_white.stl`、材料モデル、`preview.png`、`transmission.png`、`thickness.png`、4材料マスクへ渡します。このため、実測プロファイル適用後の形状と確認画像で異なる厚みを使いません。
+
+使用したプロファイルは通常ジョブへ`calibration-profile.json`としてコピーされ、`settings.json`と`manifest.json`へプロファイルID、元パス、選択方式を記録します。
+
+色レシピと明るさは独立に選択します。レシピごとの明るさの違いや、色と厚みの相互作用を同時に補正する色管理方式ではありません。
+
+## 現在の検証範囲
+
+- 140 × 104 mm、16列 × 9行のSVGと3MFの寸法・配置を自動検証している
+- 7層120レシピ、White厚み8段階、向き判別列の生成を自動検証している
+- プロファイルの生成、JSON検証、積層条件照合、反復測定の平均、レシピと厚みの選択を自動検証している
+- 現行140 × 104 mm校正片の0.2 mmノズルによる実機印刷は完了していない
+- 7層120レシピについて、実機での数値測色と色差評価は完了していない