一、辅助类简介

Three.js 提供了一些辅助类（Helpers）以帮助我们更容易地调试、可视化场景中的元素。

• ArrowHelepr：创建箭头辅助器；
• AxisHelper： 创建坐标轴辅助器；
• BoxHelper： 创建包围盒辅助器；
• Box3Helper：创建可视化Box3的辅助器；
• CameraHelper：用于创建相机的辅助器；
• DirectionalLightHelper：创建方向光源；
• GridHelper：创建网格辅助器；
• PolarGridHelper：极坐标网格辅助器；
• HemisphereLightHelper：可视化半球光源辅助器；
• PlaneHelper：可视化平面；
• PointLightHelper：可视化点光源；
• SkeletonHelper：可视化骨骼；
• SpotLightHelper：创建聚光灯辅助器。

二、ArrowHelepr

1. 简介

ArrowHelper 用于创建箭头辅助器，可以用来可视化方向向量或表示某一方向的箭头。

2. 构造函数

THREE.ArrowHelper(direction, origin, length, color, headLength, headWidth)

参数说明：

• direction：从箭头起点指向箭头终点的单位向量；
• origin：箭头的起点位置；
• length：箭头的长度，默认为 1；
• color：箭头的颜色，可以是十六进制颜色值或 THREE.Color 对象；
• headLength：箭头头部的长度。默认值为 0.2 * length；
• headWidth：箭头头部的宽度。默认值为 0.2 * headLength。

3. 示例

const dir = new THREE.Vector3( 2, 0, 2 );
dir.normalize();
const origin = new THREE.Vector3( 0, 0, 0 );
const length = 10;
const hex = 0xffff00;
const arrowHelper = new THREE.ArrowHelper( dir, origin, length, hex );
scene.add( arrowHelper );

运行效果，在前一章的图形基础上查看箭头效果，下面的箭头从原点指向 （2,0,2）的位置 ：

三、AxisHelper创建坐标轴辅助器

1. 构造函数

THREE.AxisHelper(size)

• size：坐标轴辅助器的尺寸，即坐标轴的长度。默认为 1。

2. 方法

• 默认情况下，红色表示 X 轴，绿色表示 Y 轴，蓝色表示 Z 轴，可以通过 setColors 来设置颜色。
• 辅助助器的默认原点是（0，0，0），可以设置position 来移动位置 。
• 不在使用时建议调用 .dispose () 释放资源。

运行效果

四、BoxHelper 创建包围盒

1. 构造函数

THREE.BoxHelper(object, color)

BoxHelper( object : Object3D, color : Color )

• object：可选参数，需要显示的包围盒对象，基于世界坐标轴对齐；
  color：可选参数，包围盒的颜色，默认是 #ffff00。

2. 示例

本示例包含创建形状的完整代码：

// 引入Three.js库的全部功能，并将其命名为THREE
import * as THREE from 'three';
// 引入交互控制器
import {OrbitControls} from 'three/examples/jsm/controls/OrbitControls.js';


// 创建一个场景
const scene = new THREE.Scene();

// 创建一个透视相机，参数分别为视野角度、视口宽高比、近端距离、远端距离
const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);

// 创建一个WebGL渲染器
const renderer = new THREE.WebGLRenderer();

// 设置渲染器的大小为窗口的宽度和高度
renderer.setSize(window.innerWidth, window.innerHeight);

// 将渲染器的canvas元素添加到HTML文档中的body标签中
document.body.appendChild(renderer.domElement);


//------------- 下面放创建几何体的代码 -----------------------
const geometry = new THREE.SphereGeometry( 10, 10, 10 );

const wireframe = new THREE.WireframeGeometry( geometry );

const myGeometry = new THREE.LineSegments( wireframe );
myGeometry.material.depthTest = false;
myGeometry.material.opacity = 0.5;
myGeometry.material.transparent = true;

scene.add( myGeometry );

//--------------- 创建几何体代码结束 --------------------------

// 创建一个平行光源
const directionalLight = new THREE.DirectionalLight(0xffffff, 1);
directionalLight.position.set(1, 1, 1).normalize(); // 设置光源的方向
scene.add(directionalLight);

const controls = new OrbitControls(camera, renderer.domElement);
camera.position.z = 40;

const dir = new THREE.Vector3( 2, 0, 2 );
dir.normalize();
const origin = new THREE.Vector3( 0, 0, 0 );
const length = 10;
const hex = 0xffff00;
const arrowHelper = new THREE.ArrowHelper( dir, origin, length, hex );
scene.add( arrowHelper );

const axesHelper = new THREE.AxesHelper( 10 );
scene.add( axesHelper );


const box = new THREE.BoxHelper( myGeometry, 0xffff00 );
scene.add( box );

// 创建一个动画函数
function animate() {
    // 请求下一帧动画
    requestAnimationFrame(animate);

    // 更新 OrbitControls
    controls.update();
    myGeometry.rotation.y += 0.01;
    myGeometry.rotation.z += 0.01;


    // 渲染场景
    renderer.render(scene, camera);
}

animate()

运行效果：

五、Box3Helper 可视化Box3的辅助器

Box3表示一个三维空间中的轴对齐包围盒，Box3Helper创建了用于显示该包围盒的线框辅助器。

1. 构造函数

THREE.Box3Helper(box, color)

参数说明：

• box：要可视化的 Box3 对象；
• color：（可选）线框辅助器的颜色。默认为 0xffff00。

2. 示例

const box = new THREE.Box3();
box.setFromCenterAndSize(new THREE.Vector3(1, 1, 1), new THREE.Vector3(2, 1, 3));

const helper = new THREE.Box3Helper(box, 0xffff00);
scene.add(helper);

运行效果：

六、CameraHelper 可视化相机的视锥体

CameraHelper 使用LinxSegments 将相机的视锥体可视化出来 ， 以帮助我们理解相机的视野范围。

1. 构造函数

THREE.CameraHelper(camera)

• camera：即要可视化的相机对象。

2. 属性

• .camera：相机对象，表示被可视化的相机。
• .pointMap：包含用于可视化相机的点的对象。
• .matrix：相机的世界变换矩阵的引用。
• .matrixAutoUpdate：参见 Object3D.matrixAutoUpdate。在这里设置为 false，因为辅助器使用相机的 matrixWorld。

3. 方法

• .dispose()：释放由该实例分配的与 GPU 相关的资源。当不再需要该实例时，请调用此方法。
• .setColors(frustum, cone, up, target, cross)：定义辅助器的颜色。
• .update()：基于相机的 projectionMatrix 更新辅助器。

4. 示例代码

...
// 创建一个透视相机，参数分别为视野角度、视口宽高比、近端距离、远端距离
const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);
...

const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);
const helper = new THREE.CameraHelper(camera);
scene.add(helper);

运行效果：

七、DirectionalLightHelper 可视化定向光源

1. 构造函数

THREE.DirectionalLightHelper(light, size, color)

参数说明：

• light：要可视化的定向光对象；
• size：（可选）平面的尺寸。默认为 1；
• color：（可选）辅助器的颜色。如果未设置，辅助器将采用光的颜色。

2. 属性

• .lightPlane：包含显示定向光位置的线条网格；
• .light：定向光对象的引用，表示被可视化的光源；
• .matrix：定向光的世界变换矩阵的引用；
• .matrixAutoUpdate：参见 Object3D.matrixAutoUpdate。在这里设置为 false，因为辅助器使用定向光的 matrixWorld；
• .color：构造函数中传入的颜色参数。默认为 undefined。如果更改，辅助器的颜色将在下一次调用 update 时更新。

3. 代码示例

// 引入Three.js库的全部功能，并将其命名为THREE
import * as THREE from 'three';
// 引入交互控制器
import {OrbitControls} from 'three/examples/jsm/controls/OrbitControls.js';


// 创建一个场景
const scene = new THREE.Scene();

// 创建一个透视相机，参数分别为视野角度、视口宽高比、近端距离、远端距离
const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);

// 创建一个WebGL渲染器
const renderer = new THREE.WebGLRenderer();

// 设置渲染器的大小为窗口的宽度和高度
renderer.setSize(window.innerWidth, window.innerHeight);

// 将渲染器的canvas元素添加到HTML文档中的body标签中
document.body.appendChild(renderer.domElement);


//------------- 下面放创建几何体的代码 -----------------------
const radius = 2;
const detail = 0;

const dodecahedronGeometry = new THREE.DodecahedronGeometry(radius, detail);
const material = new THREE.MeshPhongMaterial({ color: 0x00ff00 });
const myGeometry = new THREE.Mesh(dodecahedronGeometry, material);
myGeometry.material.depthTest = false;
myGeometry.material.opacity = 0.5;
myGeometry.material.transparent = true;

scene.add( myGeometry );

//--------------- 创建几何体代码结束 --------------------------

// 创建一个平行光源
const directionalLight = new THREE.DirectionalLight(0xffffff, 1);
directionalLight.position.set(1, 1, 1).normalize(); // 设置光源的方向
scene.add(directionalLight);

const controls = new OrbitControls(camera, renderer.domElement);
camera.position.z = 20;


const helper = new THREE.DirectionalLightHelper( directionalLight, 5 );
scene.add( helper );


// 创建一个动画函数
function animate() {
    // 请求下一帧动画
    requestAnimationFrame(animate);

    // 更新 OrbitControls
    controls.update();
    myGeometry.rotation.y += 0.01;
    myGeometry.rotation.z += 0.01;
    myGeometry.rotation.x += 0.01;


    // 渲染场景
    renderer.render(scene, camera);

    helper.update();
}

animate()

运行效果：

八、GridHelper 定义网格的辅助类

网格是二维线条的数组，用于帮助我们可视化场景中的空间布局。

1. 构造函数

THREE.GridHelper(size, divisions, colorCenterLine, colorGrid)

• size：网格的尺寸。默认为 10；
• divisions：网格每边的分段数。默认为 10；
• colorCenterLine：中心线的颜色。可以是 Color 对象、十六进制值或 CSS 颜色名称。默认为 0x444444；
• colorGrid：网格线的颜色。可以是 Color 对象、十六进制值或 CSS 颜色名称。默认为 0x888888。

GridHelper 基于 LineSegments 类，它具有与LineSegments 类相同的方法和属性。

2. 示例

下面示例创建一个尺寸为10、每边分10段的网格辅助器：

const size = 10;
const divisions = 10;

const gridHelper = new THREE.GridHelper(size, divisions);
scene.add(gridHelper);

运行效果：

九、PolarGridHelper 定义极坐标网格的辅助类

极坐标网格也是一个二维的线条数组，用于可视化极坐标系中的布局。

1. 构造函数

THREE.PolarGridHelper(radius, sectors, rings, divisions, color1, color2)

参数说明：

• radius：极坐标网格的半径。可以是任何正数。默认为 10；
• sectors：网格将被划分为的扇区数。可以是任何正整数。默认为 16；
• rings：环数，即网格的圈数。可以是任何正整数。默认为 8；
• divisions：用于每个圆的线段数。可以是任何大于等于 3 的正整数。默认为 64；
• color1：网格元素的第一种颜色。可以是 Color 对象、十六进制值或 CSS 颜色名称。默认为 0x444444；
• color2：网格元素的第二种颜色。可以是 Color 对象、十六进制值或 CSS 颜色名称。默认为 0x888888。

2. 示例

下面创建一个半径为10、分为16个扇区、有8个环数的极坐标网格，每个圆被平滑分成64个线段：

const radius1 = 10;
const sectors = 16;
const rings = 8;
const divisions = 64;

const helper = new THREE.PolarGridHelper(radius1, sectors, rings, divisions);
scene.add(helper);

运行效果：

十、HemisphereLightHelper 可视化半球光

HemisphereLightHelper 是用于可视化半球光（HemisphereLight）的辅助类，它创建了一个球形 Mesh 以辅助可视化半球光的效果。

1. 构造函数

THREE.HemisphereLightHelper(light, sphereSize, color)

参数：

• light：要可视化的半球光对象；
• sphereSize：用于可视化光的球形 Mesh 的大小；
• color：（可选）辅助器的颜色。如果未设置，辅助器将采用光的颜色。

2. 示例

下面示例创建一个半球光，然后创建基于该半球光的可视化辅助器：

// 引入Three.js库的全部功能，并将其命名为THREE
import * as THREE from 'three';
// 引入交互控制器
import {OrbitControls} from 'three/examples/jsm/controls/OrbitControls.js';


// 创建一个场景
const scene = new THREE.Scene();

// 创建一个透视相机，参数分别为视野角度、视口宽高比、近端距离、远端距离
const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);

// 创建一个WebGL渲染器
const renderer = new THREE.WebGLRenderer();

// 设置渲染器的大小为窗口的宽度和高度
renderer.setSize(window.innerWidth, window.innerHeight);

// 将渲染器的canvas元素添加到HTML文档中的body标签中
document.body.appendChild(renderer.domElement);


//------------- 下面放创建几何体的代码 -----------------------
const radius = 2;
const detail = 0;

const dodecahedronGeometry = new THREE.DodecahedronGeometry(radius, detail);
const material = new THREE.MeshPhongMaterial({ color: 0x00ff00 });
const myGeometry = new THREE.Mesh(dodecahedronGeometry, material);
myGeometry.material.depthTest = false;
myGeometry.material.opacity = 0.5;
myGeometry.material.transparent = true;

scene.add( myGeometry );

//--------------- 创建几何体代码结束 --------------------------


const controls = new OrbitControls(camera, renderer.domElement);
camera.position.z = 20;

const light = new THREE.HemisphereLight(0xffffbb, 0x080820, 1);
scene.add(light);
const helper = new THREE.HemisphereLightHelper(light, 5);
scene.add(helper);



// 创建一个动画函数
function animate() {
    // 请求下一帧动画
    requestAnimationFrame(animate);

    // 更新 OrbitControls
    controls.update();
    myGeometry.rotation.y += 0.01;
    myGeometry.rotation.z += 0.01;
    myGeometry.rotation.x += 0.01;


    // 渲染场景
    renderer.render(scene, camera);

    helper.update();
}

animate()

十一、PlaneHelper 可视化平面

PlaneHelper 用于可视化平面的辅助类，它创建了一个平面的线框表示。

1. 构造函数

THREE.PlaneHelper(plane, size, hex)

参数：

• plane：要可视化的平面对象；
• size：（可选）平面辅助器的边长。默认为 1；
• hex：（可选）辅助器的颜色。默认为 0xffff00。

属性：

• .plane：被可视化的平面对象的引用；
• .size：平面辅助器的边长。

2. 示例

// 引入Three.js库的全部功能，并将其命名为THREE
import * as THREE from 'three';
// 引入交互控制器
import {OrbitControls} from 'three/examples/jsm/controls/OrbitControls.js';


// 创建一个场景
const scene = new THREE.Scene();

// 创建一个透视相机，参数分别为视野角度、视口宽高比、近端距离、远端距离
const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);

// 创建一个WebGL渲染器
const renderer = new THREE.WebGLRenderer();

// 设置渲染器的大小为窗口的宽度和高度
renderer.setSize(window.innerWidth, window.innerHeight);

// 将渲染器的canvas元素添加到HTML文档中的body标签中
document.body.appendChild(renderer.domElement);


//------------- 下面放创建几何体的代码 -----------------------
const myGeometry = new THREE.Plane(new THREE.Vector3(1, 1, 0.2), 5);
scene.add(myGeometry);

//--------------- 创建几何体代码结束 --------------------------
const controls = new OrbitControls(camera, renderer.domElement);
camera.position.z = 20;

const helper = new THREE.PlaneHelper(myGeometry, 10, 0xffff00);
scene.add(helper);


// 创建一个动画函数
function animate() {
    // 请求下一帧动画
    requestAnimationFrame(animate);

    // 更新 OrbitControls
    controls.update();

    // 渲染场景
    renderer.render(scene, camera);

    helper.update();
}

animate()

运行效果：

十二、PointLightHelper 可视化点光源

PointLightHelper 创建了一个球形 Mesh 以辅助可视化点光源的效果。

1. 构造函数

THREE.PointLightHelper(light, sphereSize, color)

参数：

• light：要可视化的点光源对象；
• sphereSize：（可选）球形辅助器的大小。默认为 1；
• color：（可选）辅助器的颜色。如果未设置，辅助器将采用光源的颜色。

2. 示例

下面创建了一个白色的圆锥体，点光源颜色是 ： #0xffff00：

// 引入Three.js库的全部功能，并将其命名为THREE
import * as THREE from 'three';
// 引入交互控制器
import {OrbitControls} from 'three/examples/jsm/controls/OrbitControls.js';


// 创建一个场景
const scene = new THREE.Scene();

// 创建一个透视相机，参数分别为视野角度、视口宽高比、近端距离、远端距离
const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);

// 创建一个WebGL渲染器
const renderer = new THREE.WebGLRenderer();

// 设置渲染器的大小为窗口的宽度和高度
renderer.setSize(window.innerWidth, window.innerHeight);

// 将渲染器的canvas元素添加到HTML文档中的body标签中
document.body.appendChild(renderer.domElement);


//------------- 下面放创建几何体的代码 -----------------------
const geometry = new THREE.ConeGeometry( 1, 1, 20, 40 );
const material = new THREE.MeshPhongMaterial( {color: 0xffffff} );
const myGeometry = new THREE.Mesh( geometry, material ); scene.add( myGeometry );

//--------------- 创建几何体代码结束 --------------------------


const controls = new OrbitControls(camera, renderer.domElement);

camera.position.z = 10;

// 创建点光源
const pointLight = new THREE.PointLight(0xffff00, 1, 100);
pointLight.position.set(1, 1, 2);
scene.add(pointLight);

const sphereSize = 1;
const pointLightHelper = new THREE.PointLightHelper(pointLight, sphereSize);
scene.add(pointLightHelper);


// 创建一个动画函数
function animate() {
    // 请求下一帧动画
    requestAnimationFrame(animate);

    // 更新 OrbitControls
    controls.update();

    myGeometry.rotation.x += 0.01;
    myGeometry.rotation.y += 0.01;

    // 渲染场景
    renderer.render(scene, camera);

}

animate()

运行效果：

十三、SkeletonHelper 可视化骨骼

SkeletonHelper 通过使用 LineBasicMaterial 渲染实现可视化骨骼。

本助手类将在后续章节详细介绍。

十四、SpotLightHelper 可视化SpotLight

1. 构造函数

SpotLightHelper( light : SpotLight, color : Hex )

参数：

• light: 要可视化的 SpotLight；
• color: （可选）如果设置，辅助对象将采用该颜色，否则将采用光源的颜色。
  属性：
• .cone: 用于可视化光源的 LineSegments；
• .light: 被可视化的 SpotLight 的引用；
• .matrix: 引用 spotLight 的 matrixWorld；
• .matrixAutoUpdate: 参见 - Object3D.matrixAutoUpdate。在这里设置为 false，因为辅助对象使用了 spotLight 的 matrixWorld；
• .color: 通过构造函数传递的颜色参数。默认为 undefined。如果更改了这个值，辅助对象的颜色将在下一次调用 update 时更新。

2. 示例

// 引入Three.js库的全部功能，并将其命名为THREE
import * as THREE from 'three';
// 引入交互控制器
import {OrbitControls} from 'three/examples/jsm/controls/OrbitControls.js';


// 创建一个场景
const scene = new THREE.Scene();

// 创建一个透视相机，参数分别为视野角度、视口宽高比、近端距离、远端距离
const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);

// 创建一个WebGL渲染器
const renderer = new THREE.WebGLRenderer();

// 设置渲染器的大小为窗口的宽度和高度
renderer.setSize(window.innerWidth, window.innerHeight);

// 将渲染器的canvas元素添加到HTML文档中的body标签中
document.body.appendChild(renderer.domElement);


//------------- 下面放创建几何体的代码 -----------------------
const geometry = new THREE.ConeGeometry( 1, 1, 20, 40 );
const material = new THREE.MeshPhongMaterial( {color: 0xffffff} );
const myGeometry = new THREE.Mesh( geometry, material ); scene.add( myGeometry );

//--------------- 创建几何体代码结束 --------------------------


const controls = new OrbitControls(camera, renderer.domElement);

camera.position.z = 10;

// 创建 SpotLight
const spotLight = new THREE.SpotLight(0xff0000);
spotLight.position.set(2, 2, 2);
scene.add(spotLight);

// 创建 SpotLightHelper
const spotLightHelper = new THREE.SpotLightHelper(spotLight, 0xff0000); // 可选：设置颜色
scene.add(spotLightHelper);

const helper = new THREE.SkeletonHelper(myGeometry);
scene.add(helper);


// 创建一个动画函数
function animate() {
    // 请求下一帧动画
    requestAnimationFrame(animate);

    // 更新 OrbitControls
    controls.update();

    myGeometry.rotation.x += 0.01;
    myGeometry.rotation.y += 0.01;

    // 渲染场景
    renderer.render(scene, camera);

}

animate()

运行效果：