lithop 0.2.0 → 0.3.0

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

@@ -13,7 +13,7 @@ Lithopは、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`は作りません。
+`cmyk_white.stl`、`preview.png`、`transmission.png`、`thickness.png`、材料マスクは、常に分割前の完成全体を表します。XY分割時だけカラー3MFは`tiles/`へ出力され、ルートに`lithop.3mf`は作りません。各3MFに対応する`tiles/tile_rNN_cNN-preview.png`も生成し、ローカルUIの変換ジョブでは全タイルを同時に確認できます。
 
 ## XY方向のタイル分割
 
@@ -113,7 +113,9 @@ build/<job_id>/
 ├── tile-layout.svg
 ├── tiles/
 │   ├── tile_r01_c01.3mf  # Color region 1–3、Top Whiteの4プレート
-│   └── tile_r01_c02.3mf  # Color region 1–3、Top Whiteの4プレート
+│   ├── tile_r01_c01-preview.png
+│   ├── tile_r01_c02.3mf  # Color region 1–3、Top Whiteの4プレート
+│   └── tile_r01_c02-preview.png
 ├── manifest.json
 ├── settings.json
 └── preview.png ほか

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として画像アプリで開けるか確認します。

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")

data/ext/lithop_native/src/column_mesh.rs

@@ -0,0 +1,388 @@
+use crate::mesh::{index_mesh_vertex, MeshBuilder, MeshData, VertexKey};
+use crate::COMPONENTS;
+use magnus::{Error, Ruby};
+
+struct ColumnMeshInput<'a> {
+    columns: usize,
+    rows: usize,
+    x_boundaries: &'a [f64],
+    y_boundaries: &'a [f64],
+    z_boundaries: &'a [f64],
+    intervals: Vec<Option<(usize, usize)>>,
+    group_ids: &'a [usize],
+    group_count: usize,
+}
+
+impl ColumnMeshInput<'_> {
+    fn interval_at(&self, row: isize, column: isize) -> Option<(usize, usize)> {
+        if row < 0 || column < 0 || row as usize >= self.rows || column as usize >= self.columns {
+            return None;
+        }
+        self.intervals[row as usize * self.columns + column as usize]
+    }
+
+    fn group_at(&self, row: isize, column: isize) -> usize {
+        if row < 0 || column < 0 || row as usize >= self.rows || column as usize >= self.columns {
+            return 0;
+        }
+        self.group_ids[row as usize * self.columns + column as usize]
+    }
+
+    fn grouped_interval(
+        &self,
+        row: usize,
+        column: usize,
+        neighbour_row: isize,
+        neighbour_column: isize,
+    ) -> Option<(usize, usize)> {
+        if self.group_at(row as isize, column as isize)
+            != self.group_at(neighbour_row, neighbour_column)
+        {
+            return None;
+        }
+        self.interval_at(neighbour_row, neighbour_column)
+    }
+
+    fn occupied(&self, layer: isize, row: isize, column: isize, group: usize) -> bool {
+        if layer < 0 || self.group_at(row, column) != group {
+            return false;
+        }
+        self.interval_at(row, column)
+            .is_some_and(|(bottom, top)| layer as usize >= bottom && (layer as usize) < top)
+    }
+}
+
+pub(crate) fn column_mesh(
+    ruby: &Ruby,
+    columns: usize,
+    rows: usize,
+    x_boundaries: Vec<f64>,
+    y_boundaries: Vec<f64>,
+    z_boundaries: Vec<f64>,
+    raw_intervals: Vec<i64>,
+    group_ids: Vec<usize>,
+    group_count: usize,
+) -> Result<MeshBuilder, Error> {
+    let expected_cells = columns.saturating_mul(rows);
+    let valid = columns > 0
+        && rows > 0
+        && x_boundaries.len() == columns + 1
+        && y_boundaries.len() == rows + 1
+        && z_boundaries.len() >= 2
+        && raw_intervals.len() == expected_cells * 2
+        && group_ids.len() == expected_cells
+        && group_count > 0
+        && x_boundaries.iter().all(|value| value.is_finite())
+        && y_boundaries.iter().all(|value| value.is_finite())
+        && z_boundaries.iter().all(|value| value.is_finite());
+    if !valid {
+        return Err(Error::new(
+            ruby.exception_arg_error(),
+            "invalid native column mesh input",
+        ));
+    }
+    let maximum_vertices_per_cell =
+        8_usize.saturating_add(16_usize.saturating_mul(z_boundaries.len().saturating_sub(1)));
+    if expected_cells.saturating_mul(maximum_vertices_per_cell) > u32::MAX as usize {
+        return Err(Error::new(
+            ruby.exception_arg_error(),
+            "native column mesh contains too many vertices",
+        ));
+    }
+
+    let intervals = raw_intervals
+        .chunks_exact(2)
+        .map(|pair| match pair {
+            [-1, -1] => Ok(None),
+            [bottom, top] if *bottom >= 0 && *top > *bottom && *top < z_boundaries.len() as i64 => {
+                Ok(Some((*bottom as usize, *top as usize)))
+            }
+            _ => Err(Error::new(
+                ruby.exception_arg_error(),
+                "invalid native column interval",
+            )),
+        })
+        .collect::<Result<Vec<_>, _>>()?;
+    let input = ColumnMeshInput {
+        columns,
+        rows,
+        x_boundaries: &x_boundaries,
+        y_boundaries: &y_boundaries,
+        z_boundaries: &z_boundaries,
+        intervals,
+        group_ids: &group_ids,
+        group_count,
+    };
+    let mut data = MeshData::default();
+    data.triangles.reserve_exact(column_triangle_count(&input));
+    for row in 0..rows {
+        for column in 0..columns {
+            let Some(current) = input.interval_at(row as isize, column as isize) else {
+                continue;
+            };
+            emit_column_caps(&mut data, &input, row, column, current);
+            emit_column_sides(&mut data, &input, row, column, current);
+        }
+    }
+    Ok(MeshBuilder::from_data(data))
+}
+
+type ColumnOwner = (usize, usize, usize);
+
+fn column_triangle_count(input: &ColumnMeshInput<'_>) -> usize {
+    let mut count = 0;
+    for row in 0..input.rows {
+        for column in 0..input.columns {
+            let Some(current) = input.interval_at(row as isize, column as isize) else {
+                continue;
+            };
+            count += 4;
+            count += 2 * [
+                (row as isize, column as isize - 1),
+                (row as isize, column as isize + 1),
+                (row as isize + 1, column as isize),
+                (row as isize - 1, column as isize),
+            ]
+            .into_iter()
+            .map(|(neighbour_row, neighbour_column)| {
+                exposed_layer_count(
+                    current,
+                    input.grouped_interval(row, column, neighbour_row, neighbour_column),
+                )
+            })
+            .sum::<usize>();
+        }
+    }
+    count
+}
+
+fn emit_column_caps(
+    data: &mut MeshData,
+    input: &ColumnMeshInput<'_>,
+    row: usize,
+    column: usize,
+    current: (usize, usize),
+) {
+    let (bottom, top) = current;
+    let bottom_owner = (bottom, row, column);
+    let top_owner = (top - 1, row, column);
+    emit_column_quad(
+        data,
+        [
+            column_vertex(input, column, row + 1, bottom, bottom_owner),
+            column_vertex(input, column, row, bottom, bottom_owner),
+            column_vertex(input, column + 1, row, bottom, bottom_owner),
+            column_vertex(input, column + 1, row + 1, bottom, bottom_owner),
+        ],
+    );
+    emit_column_quad(
+        data,
+        [
+            column_vertex(input, column, row + 1, top, top_owner),
+            column_vertex(input, column + 1, row + 1, top, top_owner),
+            column_vertex(input, column + 1, row, top, top_owner),
+            column_vertex(input, column, row, top, top_owner),
+        ],
+    );
+}
+
+fn emit_column_sides(
+    data: &mut MeshData,
+    input: &ColumnMeshInput<'_>,
+    row: usize,
+    column: usize,
+    current: (usize, usize),
+) {
+    for layer in exposed_layers(
+        current,
+        input.grouped_interval(row, column, row as isize, column as isize - 1),
+    ) {
+        let owner = (layer, row, column);
+        emit_column_quad(
+            data,
+            [
+                column_vertex(input, column, row + 1, layer, owner),
+                column_vertex(input, column, row + 1, layer + 1, owner),
+                column_vertex(input, column, row, layer + 1, owner),
+                column_vertex(input, column, row, layer, owner),
+            ],
+        );
+    }
+    for layer in exposed_layers(
+        current,
+        input.grouped_interval(row, column, row as isize, column as isize + 1),
+    ) {
+        let owner = (layer, row, column);
+        emit_column_quad(
+            data,
+            [
+                column_vertex(input, column + 1, row + 1, layer, owner),
+                column_vertex(input, column + 1, row, layer, owner),
+                column_vertex(input, column + 1, row, layer + 1, owner),
+                column_vertex(input, column + 1, row + 1, layer + 1, owner),
+            ],
+        );
+    }
+    for layer in exposed_layers(
+        current,
+        input.grouped_interval(row, column, row as isize + 1, column as isize),
+    ) {
+        let owner = (layer, row, column);
+        emit_column_quad(
+            data,
+            [
+                column_vertex(input, column, row + 1, layer, owner),
+                column_vertex(input, column + 1, row + 1, layer, owner),
+                column_vertex(input, column + 1, row + 1, layer + 1, owner),
+                column_vertex(input, column, row + 1, layer + 1, owner),
+            ],
+        );
+    }
+    for layer in exposed_layers(
+        current,
+        input.grouped_interval(row, column, row as isize - 1, column as isize),
+    ) {
+        let owner = (layer, row, column);
+        emit_column_quad(
+            data,
+            [
+                column_vertex(input, column, row, layer, owner),
+                column_vertex(input, column, row, layer + 1, owner),
+                column_vertex(input, column + 1, row, layer + 1, owner),
+                column_vertex(input, column + 1, row, layer, owner),
+            ],
+        );
+    }
+}
+
+fn exposed_layers(current: (usize, usize), neighbour: Option<(usize, usize)>) -> Vec<usize> {
+    let (bottom, top) = current;
+    let Some((neighbour_bottom, neighbour_top)) = neighbour else {
+        return (bottom..top).collect();
+    };
+    if neighbour_top <= bottom || neighbour_bottom >= top {
+        return (bottom..top).collect();
+    }
+    let mut layers = Vec::new();
+    if neighbour_bottom > bottom {
+        layers.extend(bottom..top.min(neighbour_bottom));
+    }
+    if neighbour_top < top {
+        layers.extend(bottom.max(neighbour_top)..top);
+    }
+    layers
+}
+
+fn exposed_layer_count(current: (usize, usize), neighbour: Option<(usize, usize)>) -> usize {
+    let (bottom, top) = current;
+    let Some((neighbour_bottom, neighbour_top)) = neighbour else {
+        return top - bottom;
+    };
+    if neighbour_top <= bottom || neighbour_bottom >= top {
+        return top - bottom;
+    }
+    neighbour_bottom.saturating_sub(bottom).min(top - bottom)
+        + top.saturating_sub(neighbour_top).min(top - bottom)
+}
+
+fn column_vertex(
+    input: &ColumnMeshInput<'_>,
+    x_index: usize,
+    row_boundary: usize,
+    z_index: usize,
+    owner: ColumnOwner,
+) -> ([f64; COMPONENTS], VertexKey) {
+    let (_, owner_row, owner_column) = owner;
+    let group = input.group_at(owner_row as isize, owner_column as isize);
+    let coordinate_key =
+        ((x_index * (input.rows + 1) + row_boundary) * input.z_boundaries.len()) + z_index;
+    let cache_key = coordinate_key * input.group_count + group;
+    let mask = occupancy_mask(input, x_index, row_boundary, z_index, group);
+    let owner_bit = owner_bit(owner, x_index, row_boundary, z_index);
+    let component = component_root(mask, owner_bit);
+    let topology = cache_key * 8 + component;
+    let point = [
+        input.x_boundaries[x_index],
+        input.y_boundaries[input.y_boundaries.len() - 1] - input.y_boundaries[row_boundary],
+        input.z_boundaries[z_index],
+    ];
+    (point, VertexKey::Topology(topology as i64))
+}
+
+fn occupancy_mask(
+    input: &ColumnMeshInput<'_>,
+    x_index: usize,
+    row_boundary: usize,
+    z_index: usize,
+    group: usize,
+) -> u8 {
+    let mut mask = 0;
+    for layer_offset in 0..2 {
+        for row_offset in 0..2 {
+            for column_offset in 0..2 {
+                let bit = layer_offset * 4 + row_offset * 2 + column_offset;
+                if input.occupied(
+                    z_index as isize - 1 + layer_offset as isize,
+                    row_boundary as isize - 1 + row_offset as isize,
+                    x_index as isize - 1 + column_offset as isize,
+                    group,
+                ) {
+                    mask |= 1 << bit;
+                }
+            }
+        }
+    }
+    mask
+}
+
+fn owner_bit(owner: ColumnOwner, x_index: usize, row_boundary: usize, z_index: usize) -> usize {
+    let (layer, row, column) = owner;
+    ((layer as isize - z_index as isize + 1) * 4
+        + (row as isize - row_boundary as isize + 1) * 2
+        + column as isize
+        - x_index as isize
+        + 1) as usize
+}
+
+fn component_root(mask: u8, start: usize) -> usize {
+    let mut visited = [false; 8];
+    let mut pending = [0; 8];
+    pending[0] = start;
+    let mut pending_count = 1;
+    visited[start] = true;
+    let mut root = start;
+    while pending_count > 0 {
+        pending_count -= 1;
+        let current = pending[pending_count];
+        root = root.min(current);
+        for candidate in 0..8 {
+            let difference = current ^ candidate;
+            if !visited[candidate]
+                && mask & (1 << candidate) != 0
+                && matches!(difference, 1 | 2 | 4)
+            {
+                visited[candidate] = true;
+                pending[pending_count] = candidate;
+                pending_count += 1;
+            }
+        }
+    }
+    root
+}
+
+fn emit_column_quad(data: &mut MeshData, vertices: [([f64; COMPONENTS], VertexKey); 4]) {
+    let indices = vertices.map(|(point, key)| index_mesh_vertex(data, point, key));
+    data.triangles.push([indices[0], indices[1], indices[2]]);
+    data.triangles.push([indices[0], indices[2], indices[3]]);
+}
+
+#[cfg(test)]
+mod tests {
+    use super::component_root;
+
+    #[test]
+    fn finds_face_connected_voxel_components_without_joining_diagonals() {
+        assert_eq!(component_root(0b0000_0011, 1), 0);
+        assert_eq!(component_root(0b1000_0001, 7), 7);
+    }
+}

data/ext/lithop_native/src/lib.rs

@@ -0,0 +1,37 @@
+mod column_mesh;
+mod mesh;
+mod palette;
+mod xml;
+
+use column_mesh::column_mesh;
+use magnus::{function, method, prelude::*, Error, Ruby};
+use mesh::MeshBuilder;
+use palette::palette_indices;
+use xml::{triangle_xml, vertex_xml};
+
+pub(crate) const COMPONENTS: usize = 3;
+
+fn extension_version() -> &'static str {
+    env!("CARGO_PKG_VERSION")
+}
+
+#[magnus::init]
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    let lithop = ruby.define_module("Lithop")?;
+    let native = lithop.define_module("Native")?;
+    native.define_singleton_method("palette_indices", function!(palette_indices, 2))?;
+    native.define_singleton_method("vertex_xml", function!(vertex_xml, 2))?;
+    native.define_singleton_method("triangle_xml", function!(triangle_xml, 1))?;
+    native.define_singleton_method("extension_version", function!(extension_version, 0))?;
+    native.define_singleton_method("column_mesh", function!(column_mesh, 8))?;
+    let mesh_builder = native.define_class("MeshBuilder", ruby.class_object())?;
+    mesh_builder.define_singleton_method("new", function!(MeshBuilder::new, 0))?;
+    mesh_builder.define_method("add_batch", method!(MeshBuilder::add_batch, 2))?;
+    mesh_builder.define_method("vertex_count", method!(MeshBuilder::vertex_count, 0))?;
+    mesh_builder.define_method("triangle_count", method!(MeshBuilder::triangle_count, 0))?;
+    mesh_builder.define_method("center", method!(MeshBuilder::center, 0))?;
+    mesh_builder.define_method("vertex_xml", method!(MeshBuilder::vertex_xml, 3))?;
+    mesh_builder.define_method("triangle_xml", method!(MeshBuilder::triangle_xml, 2))?;
+    mesh_builder.define_method("memory_bytes", method!(MeshBuilder::memory_bytes, 0))?;
+    Ok(())
+}