OBJExporter Guide

Basic Structure

OBJ is a text-based 3D geometry format:

# Comment
v x y z        # Vertex position
vn x y z       # Vertex normal
f v1 v2 v3     # Face (triangle)
f v1/vt1/vn1 v2/vt2/vn2 v3/vt3/vn3  # Face with texture/normal indices

Example:

# Cube
v 0 0 0
v 1 0 0
v 1 1 0
v 0 1 0
f 1 2 3
f 1 3 4

Three.js OBJExporter

Three.js provides OBJExporter in examples:

import { OBJExporter } from 'three/examples/jsm/exporters/OBJExporter.js';

const exporter = new OBJExporter();
const objString = exporter.parse(object3D);

// Write to file (Node.js)
import fs from 'fs';
fs.writeFileSync('output.obj', objString);

Exporting with World Transforms

To export geometry in world coordinates:

// Update world matrices first
root.updateMatrixWorld(true);

// Clone and transform geometry
const worldGeometry = mesh.geometry.clone();
worldGeometry.applyMatrix4(mesh.matrixWorld);

// Create new mesh for export
const exportMesh = new THREE.Mesh(worldGeometry);
const objData = exporter.parse(exportMesh);

Merging Multiple Geometries

import { mergeGeometries } from 'three/examples/jsm/utils/BufferGeometryUtils.js';

const geometries = [];
root.traverse((obj) => {
  if (obj instanceof THREE.Mesh) {
    const geom = obj.geometry.clone();
    geom.applyMatrix4(obj.matrixWorld);
    geometries.push(geom);
  }
});

const merged = mergeGeometries(geometries);
const mergedMesh = new THREE.Mesh(merged);
const objData = exporter.parse(mergedMesh);

Node.js ES Module Setup

For running Three.js in Node.js:

// package.json
{ "type": "module" }

// script.js
import * as THREE from 'three';
import { OBJExporter } from 'three/examples/jsm/exporters/OBJExporter.js';

OBJ Export for Scene Components

Component Definition (Hierarchy-Aware)

Treat each named THREE.Group as a component/part. Preserve hierarchy by using the nearest named parent group in the ancestor chain as the owning component for each mesh. Call root.updateMatrixWorld(true) before exporting so matrixWorld is correct.

function collectComponentMeshes(root) {
    const componentMap = {};
    root.traverse(obj => {
        if (obj instanceof THREE.Group && obj.name) {
            componentMap[obj.name] = { group: obj, meshes: [] };
        }
    });

    root.traverse(obj => {
        if (obj instanceof THREE.Mesh) {
            let parent = obj.parent;
            while (parent && !(parent instanceof THREE.Group && parent.name)) {
                parent = parent.parent;
            }
            if (parent && componentMap[parent.name]) {
                componentMap[parent.name].meshes.push(obj);
            }
        }
    });

    return Object.fromEntries(
        Object.entries(componentMap).filter(([_, data]) => data.meshes.length > 0)
    );
}

Export Individual Meshes (World Transforms)

import { OBJExporter } from 'three/examples/jsm/exporters/OBJExporter.js';

const exporter = new OBJExporter();

function exportMesh(mesh, filepath) {
    let geom = mesh.geometry.clone();
    geom.applyMatrix4(mesh.matrixWorld);
    if (geom.index) {
        geom = geom.toNonIndexed();
    }
    if (!geom.attributes.normal) {
        geom.computeVertexNormals();
    }
    const tempMesh = new THREE.Mesh(geom);
    tempMesh.name = mesh.name;
    const objData = exporter.parse(tempMesh);
    fs.writeFileSync(filepath, objData);
}

Export Merged Component Meshes (Optional)

import { mergeGeometries } from 'three/examples/jsm/utils/BufferGeometryUtils.js';

function mergeMeshes(meshes) {
    const geometries = [];
    for (const mesh of meshes) {
        let geom = mesh.geometry.clone();
        geom.applyMatrix4(mesh.matrixWorld);
        if (geom.index) {
            geom = geom.toNonIndexed();
        }
        if (!geom.attributes.normal) {
            geom.computeVertexNormals();
        }
        geometries.push(geom);
    }
    if (geometries.length === 0) return null;
    return new THREE.Mesh(mergeGeometries(geometries, false));
}

Output Paths

Write OBJ files to the paths specified by the task instructions or a provided output root variable. Avoid hardcoding fixed directories in the skill itself.