Add scene engine pipeline

.github/workflows/main.yml

@@ -147,6 +147,11 @@ jobs:
             --extra-index-url https://download.blender.org/pypi/
           pip install pytest-xdist
 
+      - name: Verify Scene Engine gensim installation
+        run: |
+          python -c "import matplotlib, numpy, open3d, requests, scipy, shapely, trimesh; from PIL import Image; import embodichain.gen_sim.scene_engine.pipeline.generate"
+          pytest tests/gen_sim/scene_engine -q
+
       - name: Run default tests
         run: |
           echo "Default test suite (GPU-marked tests are skipped)"

docs/source/features/generative_sim/index.rst

@@ -7,3 +7,4 @@ Generative Simulation collects EmbodiChain features for generating simulation-re
    :maxdepth: 2
 
    SimReady Asset Pipeline <simready_pipeline.md>
+   Scene Engine <scene_engine.md>

docs/source/features/generative_sim/scene_engine.md

@@ -0,0 +1,83 @@
+# Scene Engine
+
+Scene Engine reconstructs a table-top scene from one image. It identifies the
+table and visible objects, segments their masks, generates simulation-ready
+meshes, refines the object layout on the table, and exports a scene that can be
+loaded by EmbodiChain.
+
+## Quick Start
+
+Install EmbodiChain with the `gensim` extra first; see
+[Installation](../../quick_start/install.md#optional-generative-simulation-gensim).
+
+Configure the required services in `embodichain/gen_sim/.env`, then generate a
+scene:
+
+```bash
+embodichain scene-engine \
+    --image /path/to/scene.png \
+    --output_root /path/to/scene_output
+```
+
+The same command is available through the package entry point:
+
+```bash
+python -m embodichain scene-engine \
+    --image /path/to/scene.png \
+    --output_root /path/to/scene_output
+```
+
+## Configuration
+
+Scene Engine reads the LLM, segmentation, and geometry-generation settings
+from `embodichain/gen_sim/.env`:
+
+```bash
+OPENAI_API_KEY="your-api-key"
+OPENAI_MODEL="your-model"
+OPENAI_BASE_URL="https://api.openai.com/v1"
+SCENE_ENGINE_OPENAI_DEFAULT_QUERY="{}"
+OPENAI_MAX_ATTEMPTS=3
+
+SCENE_ENGINE_IMAGE_SEGMENTATION_BASE_URL="http://host:port"
+SCENE_ENGINE_IMAGE_SEGMENTATION_TIMEOUT_S=30
+SCENE_ENGINE_IMAGE_SEGMENTATION_MAX_ATTEMPTS=3
+SCENE_ENGINE_IMAGE_SEGMENTATION_HEALTH_PATH="/health"
+SCENE_ENGINE_IMAGE_SEGMENTATION_SINGLE_OBJECT_PATH="/predict"
+
+SCENE_ENGINE_GEOMETRY_GENERATION_BASE_URL="http://host:port"
+SCENE_ENGINE_GEOMETRY_GENERATION_TIMEOUT_S=600
+SCENE_ENGINE_GEOMETRY_GENERATION_MAX_ATTEMPTS=3
+SCENE_ENGINE_GEOMETRY_GENERATION_HEALTH_PATH="/health"
+SCENE_ENGINE_GEOMETRY_GENERATION_OBJECTS_PATH="/generate_multiple_objects"
+```
+
+## Processing Flow
+
+- **Scene understanding**: analyzes the image and segments the table and visible objects.
+- **Scene generation**: generates meshes, prepares SimReady geometry, detects the table support surface, and refines the table-top layout.
+- **Scene export**: copies the final GLBs and writes a portable z-up scene export.
+
+## Output and Preview
+
+The important final outputs are:
+
+```text
+scene_output/
+|-- scene_understanding/     # Object analysis, masks, and stage JSON
+|-- scene_generation/        # Generated, SimReady, and layout-debug artifacts
+`-- scene_export/
+    |-- mesh_assets/         # Final GLBs
+    `-- scene_config.json    # Exported scene description
+```
+
+Validate the export without opening a window:
+
+```bash
+embodichain preview-scene \
+    --output_root /path/to/scene_output \
+    --headless
+```
+
+For an interactive preview, omit `--headless`. Add `--viser` to publish the
+scene through Viser.

embodichain/__main__.py

@@ -51,6 +51,16 @@ class Command:
         target="embodichain.gen_sim.simready_pipeline.cli.start:main",
         help="Convert a raw asset directory into a SimReady asset.",
     ),
+    Command(
+        name="scene-engine",
+        target="embodichain.gen_sim.scene_engine.cli.start:main",
+        help="Generate a scene export from an input image using gen_sim/.env.",
+    ),
+    Command(
+        name="preview-scene",
+        target="embodichain.gen_sim.scene_engine.cli.preview:main",
+        help="Preview a generated Scene Engine scene export.",
+    ),
     Command(
         name="preview-asset",
         target="embodichain.lab.scripts.preview_asset:cli",

embodichain/gen_sim/scene_engine/__init__.py

@@ -0,0 +1,19 @@
+# ----------------------------------------------------------------------------
+# Copyright (c) 2021-2026 DexForce Technology Co., Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ----------------------------------------------------------------------------
+
+from __future__ import annotations
+
+__all__: list[str] = []

embodichain/gen_sim/scene_engine/cli/__init__.py

@@ -0,0 +1,19 @@
+# ----------------------------------------------------------------------------
+# Copyright (c) 2021-2026 DexForce Technology Co., Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ----------------------------------------------------------------------------
+
+from __future__ import annotations
+
+__all__: list[str] = []