Table of Contents

XRFame 애플리케이션 실행 중 AR 환경에서 3D 콘텐츠를 수정하는 방법

이 글은 AR 추적 상태에 따른 가시성 제어 전략, 런타임 Transform 변환, 그리고 GLTF 재질 동적 업데이트에 대한 실용 가이드를 제공합니다.

시작하기 전에

런타임 Block의 가시성 제어 전략을 구성하는 방법

BlockController 컴포넌트의 가시성 제어 전략 visibleStrategy에는 세 가지 유형이 있습니다:

전략 설명
VisibleWhileTracked 기본값. Block이 성공적으로 추적될 때만 표시되며, 추적이 손실되면 숨겨집니다.
VisibleAfterFirstTracked Block이 한 번이라도 성공적으로 추적된 후에는 추적이 손실되어도 계속 표시됩니다.
None 엔진에 의해 가시성이 제어되지 않으며, 개발자가 직접 유지 관리합니다.

BlockHolder에서 holdBlock()을 호출하여 ShadowRoot 아래에 Block 노드를 생성한 후에는 해당 가시성 전략을 수정할 수 있습니다.

BlockID를 찾는 방법은 어노테이션 없이 콘텐츠 직접 마운트하기를 참조하세요.

const blockInfo: easyar.BlockInfo = { id: blockId };
blockHolder.holdBlock(blockInfo);
const block = blockHolder.getBlockById(blockInfo.id);

// 전략을 다음과 같이 수정: 추적되면 영구적으로 표시
block.visibleStrategy = BlockVisibleStrategy.VisibleAfterFirstTracked;

기본 VisibleStrategy는 VisibleWhileTracked입니다. 즉, Block이 MegaTracker 추적 상태에 있을 때만 해당 콘텐츠(자식 노드 포함)가 표시됩니다.

콘텐츠 편집 및 수정 방법

  • 오브젝트 Transform 수정

    장면 내 Element의 Transform을 수정하려면 해당 getComponent() 메서드를 호출하여 Component를 가져와야 합니다.

    const xrFrameSystem = wx.getXrFrameSystem();
let transform = model.getComponent(xrFrameSystem.Transform);
transform.position.setValue(1.0, 0.0, -1.0);
/** 원본 쿼터니언 복사 */
let originalQuaternion = modelTF.quaternion.clone();
/** Y축으로 180도 회전 */
let targetQuaternion = originalQuaternion.multiply(new xrFrameSystem.Quaternion().setValue(0, 1, 0, 0));
transform.quaternion.setValue(targetQuaternion);

    이 예시에서 프로그램은 model의 xrFrameSystem.Transform을 가져온 후 위치와 회전 각도를 수정합니다.

  • 텍스처 교체

    텍스처 교체 전에는 텍스처 자체를 xr-frame 장면의 자원 관리 시스템을 통해 loadAsset을 호출하여 수동으로 로드해야 합니다.

    이후 모델의 GLTF 속성을 가져와 각 mesh의 material에 대해 setTexture() 메서드를 호출합니다.

    const textureAsset = await scene.assets.loadAsset({
    type: 'texture',
    assetId: `texture01`,
    src: 'some-texture-url.png',
});
model.getComponent(xrFrameSystem.GLTF).meshes.forEach((m: any) => {
    m.material.setTexture('u_baseColorMap', textureAsset.value);
});

    이 예시에서 프로그램은 먼저 장면의 자원 관리자를 사용해 textureAsset을 로드한 후, 이를 사용해 GLTF 모델의 텍스처를 교체합니다.

  • 등록된 재질 교체

    등록된 재질을 교체하려면 먼저 xr-frame 장면의 자원 관리 시스템을 통해 getAsset()을 호출하여 재질 자원을 가져와야 합니다.

    이후 모델의 GLTF 속성을 가져와 각 mesh에 대해 setData를 호출하여 material 속성을 대상 재질로 수정합니다.

    let occlusionMaterial = scene.assets.getAsset("material", "easyar-occlusion");
model.getComponent(xrFrameSystem.GLTF).meshes.forEach((m: any) => {
    m.setData({ material: occlusionMaterial });
});

    이 예시에서 프로그램은 장면의 자원 관리자를 사용해 EasyAR가 등록한 오클루전 재질 easyar-occlusion을 가져온 후, 이를 GLTF 모델의 재질로 설정합니다.