Scene graph and coordinates
Quick answer
This tutorial explains that every Object3D hangs in one tree and that children store local transforms. It walks through Group, Mesh and Scene inheritance, parent and children relations, world matrix composition, getWorldPosition, localToWorld and the difference between add and attach. It also defines a single toScene function that offsets projected eastings and northings around a local origin. Readers can debug why objects move unexpectedly and keep GIS coordinates precise.
Key points
- Remember child positions are local; read world coordinates with getWorldPosition.
- Use attach to reparent an object while preserving its world transform.
- Call updateMatrixWorld(true) before reading world positions prior to rendering.
Example
const cityBlock = new THREE.Group();
cityBlock.position.set(120, 0, -80);
const building = new THREE.Mesh(boxGeometry, wallMaterial);
building.position.set(10, 15, 6); // 相对 cityBlock
cityBlock.add(building);
scene.add(cityBlock);
console.log(building.parent === cityBlock); // true
console.log(building.getWorldPosition(new THREE.Vector3()).x); // 130
cityBlock.traverse(function (obj) {
if (obj.isMesh) obj.castShadow = true;
});const pivot = new THREE.Group();
pivot.position.set(200, 0, 0);
const arm = new THREE.Mesh(new THREE.BoxGeometry(60, 2, 2), metalMaterial);
arm.position.set(30, 0, 0); // 伸出 30 米
pivot.add(arm);
pivot.rotation.y = THREE.MathUtils.degToRad(35);
pivot.updateMatrixWorld(true);
const endPoint = new THREE.Vector3(60, 0, 0);
arm.localToWorld(endPoint);Notes
- Rotation values are radians, so writing 35 means 35 radians rather than degrees.
- localToWorld mutates the passed vector, so clone it when the original value is needed.
English edition written for Atlaslog. Code is taken from the original Chinese page and runs unchanged.
Atlaslog (2026). Scene graph and coordinates. https://www.jingweizhi.com/en/three/tutorials/scene-graph.html (accessed 2026-11-03).