# Forge Intake
> Forge suite — physical-world and AI-world 3D intake. Converts real-world photo sequences into production-ready meshes or Gaussian splats (photogrammetry via COLMAP/Meshroom/ RealityScan), trains and exports Gaussian-splat / NeRF scenes (gsplat, Nerfstudio Splatfacto), and turns AI-generated raw geometry into clean, game-ready assets (Meshy/Tripo/TripoSR/Hunyuan3D → retopology + UV unwrap + texture rebake → GLB/FBX). Use whenever you need to: process a photo scan, run photogrammetry, reconstruct a 3D scene from images, train a Gaussian splat, convert a .ply splat file, generate 3D from a text prompt or reference image, clean up a raw AI-generated or scanned mesh, retopologise a dense scan, rebake textures off a raw scan, fix non-manifold geometry on raw capture, or make a raw scan/AI mesh game-ready. This is the INTAKE gate for raw scan/AI geometry only — for retopo/decimation/LOD of an EXISTING clean mesh use forge-topology; for PBR baking on a clean mesh use forge-texture. Produces validated GLB/FBX/PLY read
- Skill: `luminary19/forge-intake` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add luminary19/forge-intake`
- Raw SKILL.md: https://api.skillmd.com/api/skills/luminary19/forge-intake/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: luminary19 (https://skillmd.com/u/luminary19)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/luminary19/forge-intake
---
# Forge Intake — Photogrammetry · Gaussian Splat · AI-to-3D
The entry gate for real-world and AI-world geometry. Raw scans, splat captures, and AI-generated
meshes are rarely production-ready: scale is arbitrary, topology is chaotic, normals are broken,
UVs are missing, and textures bake in studio lighting. This skill drives every stage of intake —
from capture to validated, forge-clean GLB — without touching a GUI.
> **Project memory:** if **`FORGE.md`** exists at the project root, read it first — it carries
> the target engine, coordinate system, poly budget, texel density, and verified output paths
> for this project. Write your output paths back into FORGE.md when this skill exits successfully.
---
> **Forge suite — related skills (bold = most likely cross-skill calls from here):**
>
> Upstream — **`forge-brief`** establishes the asset brief and writes FORGE.md.
> **`forge-standards`** holds the canonical poly budgets, texel density, scale rules, and
> coordinate-system conventions that intake must satisfy.
>
> Downstream (mesh path) — **`forge-topology`** for manual retopo and edge-flow cleanup beyond
> what Quadriflow produces. **`forge-uv`** for advanced UDIM unwrap, seam planning, and
> distortion checks. **`forge-texture`** for full PBR baking (AO, curvature, displacement) from
> the high-res scan source to the clean low-res target. **`forge-material`** to wire the baked
> maps into a Principled BSDF / glTF PBR material. **`forge-render`** for the turntable
> contact-sheet QA render after cleanup. **`forge-export`** for final GLB/FBX/USD packaging.
> **`forge-validate`** is the mandatory gate before any asset leaves this pipeline.
>
> Downstream (splat path) — **`atelier-webgl`** embeds `.compressed.ply` / `.sog` files in a
> Three.js / R3F scene. Invoke = `Skill("atelier-webgl")`.
>
> **Scope boundary:** this skill is the INTAKE gate for RAW scan / AI / splat geometry only.
> For retopo, decimation, or LOD of an EXISTING clean mesh use **`forge-topology`**; for PBR
> baking (AO/curvature/normal) on a clean mesh use **`forge-texture`**; for the watertight/
> non-manifold gate use **`forge-validate`**. Intake owns retopo/rebake/cleanup only when the
> input is unprocessed scan or AI-generated raw geometry.
>
> **Run = call the Skill tool with its exact name. Writing "now run forge-validate" in prose
> runs nothing.**
---
## Decide first: which intake track?
Before touching any data, identify the track and verify its toolchain is available.
| Track | Input | Primary toolchain | Output |
|---|---|---|---|
| **A. Photogrammetry → mesh** | ≥80 photos of object/scene | COLMAP → PyMeshLab → Blender | Cleaned `.glb` / `.obj` |
| **B. Gaussian splat training** | Same photos OR video frames | COLMAP sparse → gsplat / Nerfstudio | `.ply` / `.compressed.ply` / `.sog` |
| **C. Splat conversion / cleanup** | Existing `.ply` / `.splat` | Open3D, SuperSplat | Validated splat PLY |
| **D. AI text/image-to-3D (cloud)** | Text prompt or reference image | Meshy API or Tripo H3 API | Raw `.glb` |
| **E. AI local inference** | Reference image | TripoSR / Hunyuan3D 2.1 | Raw `.glb` |
| **F. Mesh cleanup / rebake** | Raw `.glb` / `.obj` / `.fbx` | trimesh → Blender headless | Game-ready `.glb` |
**Tool availability check (run before every track):**
```powershell
# Quick availability probe — PowerShell
$tools = @{
blender = "blender"
python = "python"
colmap = "COLMAP" # or full path to COLMAP.bat
ffmpeg = "ffmpeg"
}
foreach ($name in $tools.Keys) {
$found = $null -ne (Get-Command $tools[$name] -ErrorAction SilentlyContinue)
Write-Host "[$( if ($found) {'OK '} else {'MISS'} )] $name"
}
```
If a required tool is missing, state the install path from **`references/toolchain-install.md`**
and ask the user before proceeding. Never assume a tool is present on a fresh machine.
---
## The flow
### 0. Read FORGE.md, confirm track, verify tools
Read `FORGE.md` if present. Confirm the intake track from the table above. Run the tool
availability check. Record the chosen track and confirmed tool paths in FORGE.md.
### 1. Pre-process inputs
**Photos/video (tracks A and B):**
- Extract frames from video with FFmpeg if needed: `ffmpeg -i video.mp4 -vf fps=1 -q:v 2 frames\%04d.jpg`
(1–2 fps for slow walks; up to 4 fps for fast orbits)
- Target: 80–200 images for a prop, 400+ for a complex scene. ≥80% frame overlap.
- Avoid: direct sunlight (specular hotspots fail SfM), featureless surfaces (spray texture).
**AI reference image (tracks D and E):**
- Remove background first: `rembg` (Python) produces a clean RGBA PNG with no background noise
bleeding into the mesh surface.
- Prefer even, diffuse lighting in the reference — avoid hard shadows (they bake into albedo).
- Capture note log in FORGE.md: image count, lighting conditions, known problem areas.
### 2. Sparse reconstruction (tracks A and B) or AI generation (tracks D and E)
**Tracks A/B — COLMAP sparse reconstruction:**
Full command reference: **`references/colmap-pipeline.md`**
One-shot automatic (fastest path):
```powershell
& "C:\COLMAP\COLMAP.bat" automatic_reconstructor `
--workspace_path "C:\project\scan01" `
--image_path "C:\project\scan01\images" `
--quality HIGH `
--data_type INDIVIDUAL `
--feature ALIKED `
--mapper INCREMENTAL `
--mesher POISSON
```
Verify registration ratio after sparse mapping — target >90% images registered, mean reprojection
error <1.0 px. If <70% registered, re-run with `vocab_tree_matcher` or increase overlap.
Scale is arbitrary after COLMAP. Fix with `model_aligner` (GPS) or manual two-point measurement
before exporting. Full alignment commands: **`references/colmap-pipeline.md §Scale recovery`**.
**Track D — Cloud AI generation (Meshy default):**
Full API reference: **`references/ai-generation.md`**
```powershell
$env:MESHY_API_KEY = "msy_..." # or test key: msy_dummy_api_key_for_test_mode_12345678
$meshy = "$env:CLAUDE_CONFIG_DIR\skills\forge-intake\scripts\meshy_gen.py"
python "$meshy" --mode text --prompt "Victorian armchair, aged oak" `
--topology quad --polycount 300000 --out-dir "C:\project\ai_raw" --json
```
`scripts/meshy_gen.py` ships with this skill (the only intake script that touches the network):
it posts to the Meshy OpenAPI v2 endpoint, runs the preview→refine poll loop, and downloads the
GLB. Generate at MAX polycount (`300000`); decimate afterwards — this preserves more detail for
UV packing and texture quality during generation. (For image-to-3D: `--mode image --image
input_nobg.png`. For Tripo, follow `references/ai-generation.md §3`.)
**Track E — Local AI generation:**
Full local inference guide: **`references/ai-generation.md §Local inference`**
Check CUDA availability first: `python -c "import torch; print(torch.cuda.is_available(), torch.version.cuda)"`
CUDA mismatch is the most common Windows failure — see **`references/ai-generation.md §Gotchas`**.
### 3. Dense reconstruction and meshing (track A) OR splat training (track B)
**Track A — Dense reconstruction → mesh:**
Full commands: **`references/colmap-pipeline.md §Dense reconstruction`**
```powershell
# Dense depth estimation (requires CUDA)
& "C:\COLMAP\COLMAP.bat" patch_match_stereo `
--workspace_path "C:\project\scan01\dense" `
--workspace_format COLMAP `
--PatchMatchStereo.geom_consistency true
# Fuse + Poisson mesh
& "C:\COLMAP\COLMAP.bat" stereo_fusion ...
& "C:\COLMAP\COLMAP.bat" poisson_mesher ...
```
No CUDA GPU? Use `--PatchMatchStereo.max_image_size 1000` to reduce OOM, or use Meshroom CPU
MVS (hours, not minutes). COLMAP.bat vs colmap.exe: always use the `.bat` — it sets DLL paths.
**Track B — Gaussian splat training:**
Full training commands: **`references/splat-training.md`**
```powershell
# gsplat headless training (--disable_viewer is CRITICAL for headless)
python examples/simple_trainer.py default `
--data_dir "C:\project\scan01\dense" `
--result_dir "C:\project\scan01\splat_out" `
--disable_viewer `
--max_steps 30000 `
--sh_degree 3 `
--strategy default
```
`--disable_viewer` suppresses the viser web server — mandatory for headless operation.
30,000 steps = production; 7,000 steps = fast preview. MCMCStrategy produces fewer but
higher-quality Gaussians.
### 4. Mesh cleanup and retopology (tracks A, D, E, F)
Full cleanup reference: **`references/mesh-cleanup.md`**
**Step 4a — trimesh pre-flight (always run before Blender):**
A non-watertight mesh with disconnected islands crashes Blender's remesh modifiers.
```powershell
python -c "
import trimesh, json, sys
m = trimesh.load(sys.argv[1], force='mesh')
print(json.dumps({'watertight': m.is_watertight, 'bodies': m.body_count,
'faces': len(m.faces), 'extents': m.extents.tolist()}))
" "input_raw.glb"
```
If `watertight: false` or `body_count > 1` → run trimesh repair before Blender.
**Step 4b — Blender headless cleanup (retopo + UV + rebake):**
```powershell
$blender = "C:\Program Files\Blender Foundation\Blender 4.4\blender.exe"
$cleanup = "$env:CLAUDE_CONFIG_DIR\skills\forge-intake\scripts\cleanup.py"
& $blender -b --factory-startup --python-exit-code 1 `
-P "$cleanup" `
-- "input_raw.glb" "output_clean.glb" 2048 20000 --seed 0
# args after --: