three.js GUI Controls - lil-gui, gui.add

three.js 사이트의 doc에서 Geometry(지오메트리, 기하 도형)들의 설명을 보면 오른쪽 상단에 Controls가 있습니다.  (https://threejs.org/docs/index.html#api/en/geometries/SphereGeometry)

 

Controls에는 객체의 속성 값들이 표시되고 속성 값을 변경하면 객체가 변경됩니다.

 

이번에 위의 예제 화면처럼 Controls를 만들어 주사위 객체의 Material(머티리얼)에 있는 alphaTest(알파 테스트) 속성을 변경해 보도록 하겠습니다.

 

이전에는 Controls를 만들기 위해 dat.GUI를 사용하였으나 최근에는 lil-gui를 대체하여 사용하고 있습니다. three.js에서도 lil-gui를 모듈에 포함하여 배포하고 있습니다.

 

Controls를 만들기 위해서는 lil-gui(릴 지유아이, 릴 그래픽 사용자 인터페이스) 모듈을 가져와야 합니다.

 

lil-gui(릴 지유아이, 릴 그래픽 사용자 인터페이스)는 사용자가 웹 페이지에서 객체의 속성 값들을 변경할 수 있게 플로팅 패널(Floating Panel, 떠 있는 패널)로 컨트롤러(Controller) UI를 만들어 줍니다.

 

자세한 설명은 lil-gui 사이트(https://lil-gui.georgealways.com/)를 참고하시기 바랍니다.

 

1. import를 통해 lil-gui(릴 지유아이, 릴 그래픽 사용자 인터페이스) 모듈을 가져옵니다.

import { GUI } from 'three/addons/libs/lil-gui.module.min.js';

 

lil-gui 모듈의 실제 위치는 "\node_modules\three\examples\jsm\libs\lil-gui.module.min.js" 입니다.

 

2. lil-gui(릴 지유아이, 릴 그래픽 사용자 인터페이스)를 생성합니다.

// GUI 생성
const gui = new GUI();

 

그러면 오른쪽 상단에 Controls가 생성되어 나타납니다.

 

3. Controls에 컨트롤러를 추가합니다.

gui.add(object, property, [$1], [max], [step])

• object(객체) : 컨트롤러가 제어할 객체입니다.
• property(프로퍼티, 속성) : 객체에서 제어할 속성 이름입니다.
• $1(최소 값, 선택 값) : 숫자 컨트롤러의 최소 값이거나 드롭다운에서 선택 가능한 값입니다. 
• max(최대 값) : 숫자 컨트롤러의 최대 값입니다.
• step(스탭, 간격) : 숫자 컨트롤러의 간격 값입니다.

 

object(객체)는 주사위 육면체 객체에 적용되어 있는 Material(머티리얼) 배열에서 첫 번째 배열을 설정하고 property(프로퍼티, 속성)는 alphaTest(알파 테스트)로 설정합니다.

// 컨트롤러 추가
// 주사위 육면체 객체에 적용되어 있는 머티리얼 객체, 프로퍼티는 alphaTest로 설정
gui.add(box2Materials[0], 'alphaTest');

 

그러면 오른쪽 상단에 있는 Controls에 alphaTest라는 이름(속성 이름)으로 숫자 컨트롤러가 추가됩니다.

alphaTest 숫자 컨트롤러에는 현재 alphaTest 속성 값이 나타납니다. (현재 속성 값은 0.1입니다.)

 

속성 값을 입력하거나 상/하 화살표 키보드를 눌러 값을 변경할 수 있습니다. (상/하 화살표 키보드를 누르면 1 간격으로 변경됩니다.)

 

맨 위의 예제 화면처럼 숫자 컨트롤러에 슬라이더(Sliders)를 추가하기 위해서는 $1(최소 값)과 max(최대 값)를 추가하면 됩니다.

 

alphaTest(알파 테스트) 속성 값인 알파 값(0 ~ 1)으로 $1(최소 값)과 max(최대 값)를 설정하고 step(스탭, 간격)으로 0.01로 설정합니다.

// 컨트롤러 추가
// 주사위 육면체 객체에 적용되어 있는 머티리얼 객체, 프로퍼티는 alphaTest로 설정
// 최소 값은 0, 최대 값은 1, 간격은 0.01로 설정
gui.add(box2Materials[0], 'alphaTest', 0, 1, 0.01);

 

 

또는 min(), max(), step() 메서드를 사용하여 설정할 수 있습니다.

gui.add(box2Materials[0], 'alphaTest').min(0).max(1).step(0.01);

 

그러면 alphaTest 숫자 컨트롤러에 슬라이더(Sliders)가 추가됩니다. 그리고 슬라이더(Sliders)를 마우스로 이동시키면 step(스탭, 간격) 값만큼 변경됩니다. (상/하 화살표 키보드를 눌러도 step 값만큼 변경됩니다.)

 

alphaTest 숫자 컨트롤러의 이름은 name() 메서드로 변경할 수 있습니다. alphaTest 숫자 컨트롤러의 이름을 "알파 테스트"로 변경하겠습니다.

// 컨트롤러 추가
// 주사위 육면체 객체에 적용되어 있는 머티리얼 객체, 프로퍼티는 alphaTest로 설정
// 최소 값은 0, 최대 값은 1, 간격은 0.01로 설정
// 칸트롤러의 이름을 '알파 테스트'로 변경
gui.add(box2Materials[0], 'alphaTest', 0, 1, 0.01).name('알파 테스트');

 

그러면 alphaTest 숫자 컨트롤러의 이름이 "알파 테스트"로 변경됩니다.

 

alphaTest 숫자 컨트롤러의 슬라이더(Sliders)를 마우스로 이동시켜 alphaTest 속성 값을 0으로 변경시키면 5번 주사위 이미지가 투명하지 않게 되고 그림자도 투명하지 않게 됩니다.

 

그리고 alphaTest 속성 값을 1로 변경시키면 5번 주사위 이미지가 투명해지지만 Aliasing(앨리어싱)이 발생되어 5번 주사위 이미지가 각지게 되고 그림자는 없어지게 됩니다. (alphaTest 속성이 1이 되면 흰색까지 투과되지 않습니다.)

 

alphaTest 속성 값의 변화에 따라 주사위 이미지와 그림자가 변화되는 것을 좀 더 명확하게 확인하기 위해서 주사위 육면체 객체에 적용되어 있는 Material(머티리얼) 배열에서 첫 번째 배열에 있는 alphaMap(알파 맵)을 이전에 추가한 그라데이션된 이미지 파일(dicemap.png)로 변경하여 테스트 헤보겠습니다.

// 머티리얼 배열
const box2Materials = [
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice5.png"), alphaMap: box2TextureLoader.load("resources/textures/dicemap.png"), side: THREE.DoubleSide, alphaTest: 0.1, transparent: true}),
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice2t.png"), side: THREE.DoubleSide, alphaTest: 0.1, transparent: true}),
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice1t.png"), side: THREE.DoubleSide, alphaTest: 0.1, transparent: true}),
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice6t.png"), side: THREE.DoubleSide, alphaTest: 0.1, transparent: true}),
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice3t.png"), side: THREE.DoubleSide, alphaTest: 0.1, transparent: true}),
    new THREE.MeshStandardMaterial({map: box2TextureLoader.load("resources/textures/dice4t.png"), side: THREE.DoubleSide, alphaTest: 0.1, transparent: true})
];

 

[alphaTest 속성 값을 0.1로 변경할 경우]

 

[alphaTest 속성 값을 0.54로 변경할 경우]

 

[alphaTest 속성 값을 0.9로 변경할 경우]