【Three.js】知识梳理十六：图形界面工具（GUI）

士必弘毅
1,400 阅读7分钟

在进行Three.js项目开发时，为了更好地调试和控制3D场景中的各种参数，图形用户界面工具（GUI）显得尤为重要。通过GUI工具，开发者可以在不修改代码的情况下实时调整参数，提高开发效率和灵活性。本文将介绍几种常用的Three.js GUI工具，并展示它们的基本用法。

image.png

在3D图形开发过程中，调整参数如光照强度、物体位置、材质属性等是一个频繁且必要的操作。通过GUI工具，开发者可以直观地调整这些参数，而不需要频繁修改代码和刷新页面。这不仅节省了时间，还能提高调试的精度。

常用GUI工具简介

dat.GUI

dat.GUI 是一个轻量级的JavaScript库，专为调试和参数调整设计。它提供了一个简洁的界面，可以快速集成到Three.js项目中。

GitHub - dataarts/dat.gui: Lightweight controller library for JavaScript.

ControlKit

ControlKit 是另一个功能强大的GUI工具。与dat.GUI相比，它提供了更多的控件和更美观的界面，适合需要复杂控制界面的项目。

GitHub - automat/controlkit.js: A lightweight controller and gui library

lil-gui

lil-gui 是一个现代化的GUI库，专注于性能和易用性。它的界面美观，控件丰富，适合大多数WebGL项目。

GitHub - georgealways/lil-gui: Makes a floating panel for controllers on the web. Works as a drop-in replacement for dat.gui in most projects.

dat.GUI

安装dat.GUI

可以通过npm或直接下载源码的方式来安装dat.GUI。推荐使用npm进行安装：

npm install dat.gui

基本用法

初始化dat.GUI

在Three.js项目中引入dat.GUI并进行初始化：

import * as THREE from 'three';
import { GUI } from 'dat.gui';
​
const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);
const renderer = new THREE.WebGLRenderer();
​
renderer.setSize(window.innerWidth, window.innerHeight);
document.body.appendChild(renderer.domElement);
​
// 创建一个简单的立方体
const geometry = new THREE.BoxGeometry();
const material = new THREE.MeshBasicMaterial({ color: 0x00ff00 });
const cube = new THREE.Mesh(geometry, material);
scene.add(cube);
​
camera.position.z = 5;
​
// 初始化dat.GUI
const gui = new GUI();
const cubeFolder = gui.addFolder('Cube');
cubeFolder.add(cube.rotation, 'x', 0, Math.PI * 2);
cubeFolder.add(cube.rotation, 'y', 0, Math.PI * 2);
cubeFolder.add(cube.rotation, 'z', 0, Math.PI * 2);
cubeFolder.add(cube.position, 'x', -5, 5);
cubeFolder.add(cube.position, 'y', -5, 5);
cubeFolder.add(cube.position, 'z', -5, 5);
cubeFolder.open();
​
function animate() {
    requestAnimationFrame(animate);
    renderer.render(scene, camera);
}
​
animate();

在上述代码中，我们创建了一个简单的Three.js场景，并使用dat.GUI创建了一个控制面板来实时调整立方体的旋转和位置。

控制物体的旋转和位置

我们可以通过dat.GUI的add方法将需要调整的属性添加到控制面板中。例如，控制立方体的旋转和位置：

cubeFolder.add(cube.rotation, 'x', 0, Math.PI * 2);
cubeFolder.add(cube.rotation, 'y', 0, Math.PI * 2);
cubeFolder.add(cube.rotation, 'z', 0, Math.PI * 2);
cubeFolder.add(cube.position, 'x', -5, 5);
cubeFolder.add(cube.position, 'y', -5, 5);
cubeFolder.add(cube.position, 'z', -5, 5);

高级用法

调整材质属性

img

dat.GUI不仅可以控制物体的旋转和位置，还可以调整材质的属性，例如颜色和线框模式：

const materialFolder = gui.addFolder('Material');
const materialParams = {
    color: material.color.getHex(),
    wireframe: material.wireframe,
};
materialFolder.addColor(materialParams, 'color').onChange((value) => {
    material.color.set(value);
});
materialFolder.add(materialParams, 'wireframe').onChange((value) => {
    material.wireframe = value;
});
materialFolder.open();
添加自定义函数

img

dat.GUI允许我们添加自定义按钮来执行特定操作，例如重置场景：

const actions = {
    reset: () => {
        cube.position.set(0, 0, 0);
        cube.rotation.set(0, 0, 0);
    },
};
gui.add(actions, 'reset');
使用对象进行分组

img

dat.GUI支持将参数分组，这样可以更好地组织控制面板：

const params = {
    rotation: {
        x: cube.rotation.x,
        y: cube.rotation.y,
        z: cube.rotation.z,
    },
    position: {
        x: cube.position.x,
        y: cube.position.y,
        z: cube.position.z,
    }
};
​
const rotationFolder = gui.addFolder('Rotation');
rotationFolder.add(params.rotation, 'x', 0, Math.PI * 2).onChange((value) => {
    cube.rotation.x = value;
});
rotationFolder.add(params.rotation, 'y', 0, Math.PI * 2).onChange((value) => {
    cube.rotation.y = value;
});
rotationFolder.add(params.rotation, 'z', 0, Math.PI * 2).onChange((value) => {
    cube.rotation.z = value;
});
​
const positionFolder = gui.addFolder('Position');
positionFolder.add(params.position, 'x', -5, 5).onChange((value) => {
    cube.position.x = value;
});
positionFolder.add(params.position, 'y', -5, 5).onChange((value) => {
    cube.position.y = value;
});
positionFolder.add(params.position, 'z', -5, 5).onChange((value) => {
    cube.position.z = value;
});

使用dat.GUI管理复杂场景

对于复杂的Three.js场景，可以通过dat.GUI来管理多个物体和材质的参数。以下是一个更复杂的示例，展示如何使用dat.GUI管理多个物体：

const cube1 = new THREE.Mesh(new THREE.BoxGeometry(), new THREE.MeshBasicMaterial({ color: 0xff0000 }));
const cube2 = new THREE.Mesh(new THREE.BoxGeometry(), new THREE.MeshBasicMaterial({ color: 0x0000ff }));
​
scene.add(cube1);
scene.add(cube2);
​
const cubes = {
    cube1: {
        rotation: cube1.rotation,
        position: cube1.position,
        material: cube1.material
    },
    cube2: {
        rotation: cube2.rotation,
        position: cube2.position,
        material: cube2.material
    }
};
​
const cube1Folder = gui.addFolder('Cube 1');
cube1Folder.add(cubes.cube1.rotation, 'x', 0, Math.PI * 2);
cube1Folder.add(cubes.cube1.rotation, 'y', 0, Math.PI * 2);
cube1Folder.add(cubes.cube1.rotation, 'z', 0, Math.PI * 2);
cube1Folder.add(cubes.cube1.position, 'x', -5, 5);
cube1Folder.add(cubes.cube1.position, 'y', -5, 5);
cube1Folder.add(cubes.cube1.position, 'z', -5, 5);
​
const cube2Folder = gui.addFolder('Cube 2');
cube2Folder.add(cubes.cube2.rotation, 'x', 0, Math.PI * 2);
cube2Folder.add(cubes.cube2.rotation, 'y', 0, Math.PI * 2);
cube2Folder.add(cubes.cube2.rotation, 'z', 0, Math.PI * 2);
cube2Folder.add(cubes.cube2.position, 'x', -5, 5);
cube2Folder.add(cubes.cube2.position, 'y', -5, 5);
cube2Folder.add(cubes.cube2.position, 'z', -5, 5);

ControlKit

安装ControlKit

可以通过npm或直接下载源码的方式来安装ControlKit。推荐使用npm进行安装：

npm install controlkit

基本用法

初始化ControlKit

在Three.js项目中引入ControlKit并进行初始化：

import * as THREE from 'three';
import ControlKit from 'controlkit';
​
const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);
const renderer = new THREE.WebGLRenderer();
​
renderer.setSize(window.innerWidth, window.innerHeight);
document.body.appendChild(renderer.domElement);
​
// 创建一个简单的立方体
const geometry = new THREE.BoxGeometry();
const material = new THREE.MeshBasicMaterial({ color: 0x00ff00 });
const cube = new THREE.Mesh(geometry, material);
scene.add(cube);
​
camera.position.z = 5;
​
// 初始化ControlKit
const controlKit = new ControlKit();
controlKit.addPanel({ label: 'Cube Controls' })
    .addGroup({ label: 'Rotation' })
    .addSlider(cube.rotation, 'x', { label: 'Rotation X', min: 0, max: Math.PI * 2, step: 0.01 })
    .addSlider(cube.rotation, 'y', { label: 'Rotation Y', min: 0, max: Math.PI * 2, step: 0.01 })
    .addSlider(cube.rotation, 'z', { label: 'Rotation Z', min: 0, max: Math.PI * 2, step: 0.01 })
    .addGroup({ label: 'Position' })
    .addSlider(cube.position, 'x', { label: 'Position X', min: -5, max: 5, step: 0.01 })
    .addSlider(cube.position, 'y', { label: 'Position Y', min: -5, max: 5, step: 0.01 })
    .addSlider(cube.position, 'z', { label: 'Position Z', min: -5, max: 5, step: 0.01 });
​
function animate() {
    requestAnimationFrame(animate);
    renderer.render(scene, camera);
}
​
animate();

在上述代码中，我们创建了一个基本的Three.js场景，并使用ControlKit创建了一个控制面板来实时调整立方体的旋转和位置。

高级用法

动态调整材质属性

image.png

ControlKit可以调整物体的材质属性，例如颜色和线框模式：

const materialParams = {
    color: material.color.getHex(),
    wireframe: material.wireframe,
};
​
controlKit.addPanel({ label: 'Material Controls' })
    .addColor(materialParams, 'color', { label: 'Color' }).onChange((value) => {
        material.color.set(value);
    })
    .addCheckbox(materialParams, 'wireframe', { label: 'Wireframe' }).onChange((value) => {
        material.wireframe = value;
    });
添加自定义按钮

image.png

ControlKit允许我们添加自定义按钮来执行特定操作，例如重置场景：

const actions = {
    reset: () => {
        cube.position.set(0, 0, 0);
        cube.rotation.set(0, 0, 0);
    },
};
​
controlKit.addPanel({ label: 'Actions' })
    .addButton(actions, 'reset', { label: 'Reset Cube' });
使用对象进行分组

image.png

ControlKit支持将参数分组，这样可以更好地组织控制面板：

const params = {
    rotation: {
        x: cube.rotation.x,
        y: cube.rotation.y,
        z: cube.rotation.z,
    },
    position: {
        x: cube.position.x,
        y: cube.position.y,
        z: cube.position.z,
    }
};
​
const controlPanel = controlKit.addPanel({ label: 'Cube Controls' });
​
const rotationGroup = controlPanel.addGroup({ label: 'Rotation' });
rotationGroup.addSlider(params.rotation, 'x', { label: 'Rotation X', min: 0, max: Math.PI * 2, step: 0.01 }).onChange((value) => {
    cube.rotation.x = value;
});
rotationGroup.addSlider(params.rotation, 'y', { label: 'Rotation Y', min: 0, max: Math.PI * 2, step: 0.01 }).onChange((value) => {
    cube.rotation.y = value;
});
rotationGroup.addSlider(params.rotation, 'z', { label: 'Rotation Z', min: 0, max: Math.PI * 2, step: 0.01 }).onChange((value) => {
    cube.rotation.z = value;
});
​
const positionGroup = controlPanel.addGroup({ label: 'Position' });
positionGroup.addSlider(params.position, 'x', { label: 'Position X', min: -5, max: 5, step: 0.01 }).onChange((value) => {
    cube.position.x = value;
});
positionGroup.addSlider(params.position, 'y', { label: 'Position Y', min: -5, max: 5, step: 0.01 }).onChange((value) => {
    cube.position.y = value;
});
positionGroup.addSlider(params.position, 'z', { label: 'Position Z', min: -5, max: 5, step: 0.01 }).onChange((value) => {
    cube.position.z = value;
});

ControlKit的优势

  • 丰富的控件类型：除了基本的滑块和复选框外，ControlKit还提供了颜色选择器、按钮、折叠面板等多种控件，适用于各种复杂的场景。
  • 高度可定制的界面：ControlKit的界面高度可定制，开发者可以根据需求调整控件的布局和样式。
  • 事件处理：ControlKit支持事件处理，允许开发者在参数变化时执行特定操作，提高了界面的互动性。

lil-gui

安装lil-gui

可以通过npm或直接下载源码的方式来安装lil-gui。推荐使用npm进行安装：

npm install lil-gui

基本用法

初始化lil-gui

在Three.js项目中引入lil-gui并进行初始化：

import * as THREE from 'three';
import GUI from 'lil-gui';
​
const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);
const renderer = new THREE.WebGLRenderer();
​
renderer.setSize(window.innerWidth, window.innerHeight);
document.body.appendChild(renderer.domElement);
​
// 创建一个简单的立方体
const geometry = new THREE.BoxGeometry();
const material = new THREE.MeshBasicMaterial({ color: 0x00ff00 });
const cube = new THREE.Mesh(geometry, material);
scene.add(cube);
​
camera.position.z = 5;
​
// 初始化lil-gui
const gui = new GUI();
const cubeFolder = gui.addFolder('Cube');
cubeFolder.add(cube.rotation, 'x', 0, Math.PI * 2).name('Rotation X');
cubeFolder.add(cube.rotation, 'y', 0, Math.PI * 2).name('Rotation Y');
cubeFolder.add(cube.rotation, 'z', 0, Math.PI * 2).name('Rotation Z');
cubeFolder.add(cube.position, 'x', -5, 5).name('Position X');
cubeFolder.add(cube.position, 'y', -5, 5).name('Position Y');
cubeFolder.add(cube.position, 'z', -5, 5).name('Position Z');
cubeFolder.open();
​
function animate() {
    requestAnimationFrame(animate);
    renderer.render(scene, camera);
}
​
animate();

在上述代码中，我们创建了一个基本的Three.js场景，并使用lil-gui创建了一个控制面板来实时调整立方体的旋转和位置。

控制物体的旋转和位置

我们可以通过lil-gui的add方法将需要调整的属性添加到控制面板中。例如，控制立方体的旋转和位置：

cubeFolder.add(cube.rotation, 'x', 0, Math.PI * 2).name('Rotation X');
cubeFolder.add(cube.rotation, 'y', 0, Math.PI * 2).name('Rotation Y');
cubeFolder.add(cube.rotation, 'z', 0, Math.PI * 2).name('Rotation Z');
cubeFolder.add(cube.position, 'x', -5, 5).name('Position X');
cubeFolder.add(cube.position, 'y', -5, 5).name('Position Y');
cubeFolder.add(cube.position, 'z', -5, 5).name('Position Z');

高级用法

动态调整材质属性

image.png

lil-gui可以调整物体的材质属性，例如颜色和线框模式：

const materialFolder = gui.addFolder('Material');
const materialParams = {
    color: material.color.getHex(),
    wireframe: material.wireframe,
};
​
materialFolder.addColor(materialParams, 'color').name('Color').onChange((value) => {
    material.color.set(value);
});
materialFolder.add(materialParams, 'wireframe').name('Wireframe').onChange((value) => {
    material.wireframe = value;
});
materialFolder.open();
添加自定义按钮

image.png

lil-gui允许我们添加自定义按钮来执行特定操作，例如重置场景：

const actions = {
    reset: () => {
        cube.position.set(0, 0, 0);
        cube.rotation.set(0, 0, 0);
    },
};
​
gui.add(actions, 'reset').name('Reset Cube');
使用对象进行分组

image.png

lil-gui支持将参数分组，这样可以更好地组织控制面板：

const params = {
    rotation: {
        x: cube.rotation.x,
        y: cube.rotation.y,
        z: cube.rotation.z,
    },
    position: {
        x: cube.position.x,
        y: cube.position.y,
        z: cube.position.z,
    }
};
​
const rotationFolder = gui.addFolder('Rotation');
rotationFolder.add(params.rotation, 'x', 0, Math.PI * 2).name('X').onChange((value) => {
    cube.rotation.x = value;
});
rotationFolder.add(params.rotation, 'y', 0, Math.PI * 2).name('Y').onChange((value) => {
    cube.rotation.y = value;
});
rotationFolder.add(params.rotation, 'z', 0, Math.PI * 2).name('Z').onChange((value) => {
    cube.rotation.z = value;
});
​
const positionFolder = gui.addFolder('Position');
positionFolder.add(params.position, 'x', -5, 5).name('X').onChange((value) => {
    cube.position.x = value;
});
positionFolder.add(params.position, 'y', -5, 5).name('Y').onChange((value) => {
    cube.position.y = value;
});
positionFolder.add(params.position, 'z', -5, 5).name('Z').onChange((value) => {
    cube.position.z = value;
});

lil-gui的优势

  • 现代化界面：lil-gui拥有现代化的用户界面，设计简洁美观，用户体验良好。
  • 高性能：lil-gui专注于性能优化，适用于复杂的WebGL项目。
  • 丰富的控件类型：提供了丰富的控件类型，包括滑块、颜色选择器、按钮、折叠面板等，能够满足各种需求。
  • 易用性：lil-gui的API设计简洁，易于上手和使用。
avatar
文章
阅读
粉丝