[ #8 ] ThreeJS의 Debug UI - 1탄

★☆ 이 글은 Three.js journey 강의를 통해 작성하게 되었습니다 ☆★  

 

우리는 ThreeJS 프로젝트를 진행하면서,
UI를 Debug하기 위한 방법이 절실히 필요합니다!

아직 딱히 필요성을 느끼시지 못하셨더라도,
한번 알아두시면 이후에 큰 도움이 될거에요~!

이를 위해 만들어진 Debug UI 라이브러리들이 있습니다!

• dat.GUI
• lil-gui
• control-panel
• ControlKit
• Uil
• Tweakpane
• Guify
• Oui

위 중에서 가장 많이 사용하고, 비교적 사용법이 간단한 'lil-gui'를 사용해 봅시다!

 

 

🍀 Lil-gui 란?

lil-gui에게는 부모격이 되는 라이브러리인 Dat.GUI가 있습니다

실제 옛날에는 Dat.GUI가 평균적으로 많이 사용되었습니다.
하지만, 유지보수를 하지 않게 되자 점점 문제가 되는 이슈들이 생기기 시작했고...

사람들은 이를 해결하기 위해, Dat.GUI의 경량화 버전인 lil-gui를 만들게 된것이죠!

아래는 'Bruno Simon' 센세의 프로젝트의 Debug UI의 모습입니다

 

 

🍀 Lil-gui 사용법

이제 사용법에 대해 알아봅시다! 

먼저 설치를 해주셔야 합니당.

npm install lil-gui

  이후 사용할 파일에서 import 해주시구,

import GUI from "lil-gui";
// 위 방법으로 import 시,
// const gui = new GUI();

import * as dat from 'lil-gui'
// 위 방법으로 import 시,
// const gui = new dat.GUI()

보통 UI를 추가할 때, 우리는 gui 객체에서 .add( ) 메서드를 사용해 생성하게 됩니다.
이때, 한가지 주의할 점이 있습니다!

바로..! gui.add(...) 안의 파라미터로는
"Object와 그 Object의 속성" 이어야 한다는 점입니다..!

아직 감은 잘 안잡히겠지만.. 코드를 보면서 배우도록 합시당!

 

[ 🌳 Range ]

Range는 최솟값과 최댓값을 갖는 숫자를 위한 UI 입니다.

mesh의 특정 속성을 변경하려면,
당연히 mesh가 생성된 이후에 UI를 추가해야 합니다!

없는 것을 변경할 순 없으니까요.!

const mesh = new THREE.Mesh(geometry, material)
scene.add(mesh)

gui.add(mesh.position, 'y')
// 1. mesh.position 이라는 Object와
// 2. 그 Object 안에 있는 y 속성을 인자로 넣어줌

gui.add(mesh.position, 'y', - 3, 3, 0.01)
// 이외에도 min, max, step과 같은 값을 설정할 수 있음
// 하지만 위 방법은 직관성이 떨어짐

// 아래의 방법을 추천!
gui
    .add(mesh.position, 'y')
    .min(- 3)
    .max(3)
    .step(0.01)
    .name('elevation') // UI 라벨 변경

예시 실행 결과

 

mesh의 특정 속성 이외에도, 직접 Object를 만들어 할당할 수도 있어요!

const myObject = {
    myVariable: 1337
}
gui.add(myObject, 'myVariable');
// min, max의 설정이 없을 시, 텍스트로 설정

// 하지만 아래와 같이 Object가 아닌 것은 적용되지 X
let myVariable = 1337;
gui.add(myVariable, '???');

예시 실행 결과

 

[ 🌳 Checkbox ]

Checkbox는 Boolean(true / fase)을 위한 UI입니다.

gui.add(mesh, "visible");
gui.add(mesh.material, "wireframe");
// mesh.material === material

예시 실행 결과

 

[ 🌳 Color ]

Color는 다양한 형식의 색상 형식들을 위한 UI입니다.

Color 속성은 String이 아닙니다, Boolean도 아니고, Number도 아니죠,
Color 속성은 Three.js의 Color 객체입니다.

따라서 Color는 gui.add( ) 대신 gui.addColor( )를 사용해야 합니다!

gui.addColor(mesh.material, "color");
// add 메서드 대신 addColor 사용

그런데..!

GUI를 통해 색상을 변경한 상황 / GUI의 색상을 그대로 코드에 입힌 상태

분명 같은 16진수 색상 코드이지만, 어째서인지 색상이 달리 출려됩니다..!

이는, Three.js는 렌더링 최적화를 위해 색상을 따로 관리하고 있기에
보정이 들어간 값을 결국 출력해주기 때문입니다.!!!

위 Three.js의 Color 등과 같은 후보정에 관한 내용은 추후에 자세히 다루겠습니다..!

 

그렇다면 어떻게 이러한 문제를 해결할 수 있을까요?

ThreeJS에서 제공하는 Color 객체가 아닌,
직접 만든 객체를 사용하면 됩니다!

const debugObject = {}; // 객체 생성

// ...

debugObject.color = "#3a6ea6";
// color 키 생성 및 value 초기 설정

// ...
const material = new THREE.MeshBasicMaterial({ color: debugObject.color });
// ...

// debugObejct를 대신 할당!
gui.addColor(debugObject, "color").onChange((value) => {
  material.color.set(debugObject.color);
  // 후보정이 안된 값을 바로 넣어줌
});

 

[ 🌳 Button ]

Button은 Function을 실행하기 위한 UI입니다.

Button 또한 함수를 value로 가지는 Object를 할당해줘야 하므로!
직접 만든 객체를 사용하여 UI를 생성해 줍니다!

참고로, gsap 라이브러리를 사용하여 애니메이션을 관리하였습니당.

debugObject.spin = () => {
  gsap.to(mesh.rotation, {
    duration: 2,
    y: mesh.rotation.y + Math.PI * 2,
    ease: "power2.inOut",
  });
};

gui.add(debugObject, "spin");

예시 실행 결과

 

 

길어질 것 같으니,
Debug UI 2탄으로 돌아오도록 하겠슴다!