Last reviewed: 2026-05-28

Repository source: palatial-sim-mesh-gen/docs/cad-agent-modelers.md.

This guide documents how Palatial routes mesh-generation jobs through the current CAD and scene agent systems. It covers queue-facing controls, the object-mode CAD modelers, the scene-mode framework, and the industrial-vs-organic routing rules.

Quick Map

Layer Main files Responsibility
Queue command builder palatial-pipeline-queue/qProcess/processes/qRealToSim/Tools/qMeshGeneration.py Converts qProcess parameters into run_pipeline.py CLI flags, selects provider, checks required env.
Mesh-gen CLI mesh_gen/cli.py Parses the shared CLI surface. Scene mode uses a lightweight direct path and emits queue status lines. Object/texture modes enter the orchestrator.
Orchestrator mesh_gen/orchestrator.py Selects provider, builds GenerationRequest, normalizes output, runs postprocess.
Parametric provider mesh_gen/providers/parametric.py Runs mesh_gen.cad.forgecad_shape_generator as a subprocess for object-mode CAD.
CAD generator mesh_gen/cad/forgecad_shape_generator.py Resolves model/provider, chooses CAD backend, runs ForgeCAD or Blender loops, emits sidecars.
Scene framework mesh_gen/scene/* Builds scene manifests, architecture shells, proxy/object job specs, placement/refinement artifacts.

Queue-Facing Routing

qMeshGeneration defaults to ordinary single-object shape generation. Scene mode is opt-in with parameters.mode = "scene".

Setting Default
shape provider tencent_cloud_pro
texture provider meshy_retexture
parametric actor model gpt-5.5
parametric critic model gemini-3.5-flash
parametric CAD pipeline omitted from command unless explicitly set; mesh-gen defaults to auto
parametric iterations 5
parametric minimum score 70
scene runtime tool_runtime
scene object mode proxy
scene planner model gpt-5.5

For parametric object jobs, the queue forwards only explicit overrides. If a caller does not set parametric_cad_pipeline, the lower mesh-gen app owns backend choice. Explicit controls now pass through: parametric_cad_pipeline, parametric_mechanism_mode, parametric_part_plan_mode, parametric_scaffold_mode, parametric_critic_every, parametric_local_repair_between_critics, parametric_agentic_repair, parametric_agent_model, and the agent budget flags.

Object Pipeline

Object mode is the asset-level generation flow. The default provider is still cloud shape generation unless the caller chooses --model parametric.

For parametric object jobs:

  1. qMeshGeneration builds a run_pipeline.py command with --mode object --model parametric.
  2. mesh_gen.orchestrator builds a GenerationRequest and forwards CAD controls as provider extras.
  3. ParametricProvider runs python -m mesh_gen.cad.forgecad_shape_generator in a subprocess.
  4. forgecad_shape_generator runs cad_pipeline=auto unless forced.
  5. The chosen CAD loop writes OBJ/GLB/STL/source summaries, and the orchestrator normalizes the canonical OBJ.

Backend Selection

cad_pipeline=auto asks the actor model to choose one of these backends:

Backend Best fit Core files
gemini_cad_loop Hard-surface, mechanical, industrial, architectural, furniture, racks, frames, repeated exact parts, CSG-like objects mesh_gen/cad/pipelines/gemini_cad_loop.py
blender_loop Cloth, apparel, cushions, soft goods, organic silhouettes, curved panels, folds, freeform shells, mesh-vertex surfaces mesh_gen/cad/pipelines/blender_loop.py