Qt Quick 3D - XR 심플 터치 예제

Qt Quick 3D XR에서 손 추적 입력을 시연합니다.

‘XR Touch Example’이라고 표시된 가상 화면에 세 개의 버튼이 있습니다.

이 예제는 Qt Quick 3D XR에서 손 추적 API를 사용하여 씬 내의 2D 및 3D 오브젝트와 상호 작용하는 방법을 보여줍니다. 이 예제는 xr_simple 예제의 기본 구조를 따릅니다.

먼저, 각 손에 필요한 모든 로직을 캡슐화한 재사용 가능한 ` TouchHand ` 컴포넌트를 생성합니다.

// Copyright (C) 2025 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
import QtQuick
import QtQuick3D
import QtQuick3D.Xr

Node {
    id: root
    property color color: "#ddaa88"
    required property int touchId
    required property int hand
    required property XrView view

    property alias touchPosition: handController.scenePos
    property bool touchActive: false

    XrController {
        id: handController
        controller: root.hand

        property vector3d scenePos: view.xrOrigin.mapPositionToScene(pokePosition)

        onScenePosChanged: {
            const touchOffset = view.processTouch(scenePos, root.touchId)
            handModel.position = touchOffset

            const touchState = view.touchpointState(root.touchId)
            const gadget = touchState.model as XrGadget
            if (gadget) {
                gadget.handleTouch(touchState.uvPosition, root.touchId, touchState.pressed)
            }
        }
    }

    XrHandModel {
        id: handModel
        hand: root.hand
        materials: PrincipledMaterial {
            baseColor: root.color
            roughness: 0.5
        }
    }
}

이 컴포넌트에는 집게손가락의 3D 위치를 제공하는 ` XrController`와 손의 위치를 표시하는 ` XrHandModel `가 포함되어 있습니다. ` onTouchPositionChanged ` 핸들러에서 핵심 처리가 이루어집니다. 우리는 ` XrView.processTouch()`를 호출하며, 이 함수가 주요 작업을 수행합니다. 즉, 3D 터치 위치를 ` XrItem `의 2D 위치로 매핑하고, 항목을 찾으면 터치 이벤트를 전송합니다. 그런 다음 3D 위치에서 2D 표면의 터치 지점까지의 오프셋을 반환합니다. 우리는 이 오프셋을 사용하여 XrHandModel 의 위치를 이동시켜, 마치 손이 표면에 막힌 듯한 착시 효과를 만듭니다.

참고: Apple Vision Pro에서는 시스템이 사용자의 실제 손을 표시하고 ‘ XrHandModel ’가 표시되지 않으므로이 효과는 작동하지 않습니다.

XrOrigin 내부에 각 손 하나씩, 총 두 개의 TouchHand 컴포넌트 인스턴스를 생성합니다:

XrOrigin {
    id: theOrigin
    z: 50
    TouchHand {
        id: rightHandModel
        hand: XrHandModel.RightHand
        view: xrView
        touchId: 0
        onTouchPositionChanged: buttons.handleTouch(touchPosition)
    }
    TouchHand {
        id: leftHandModel
        hand: XrHandModel.LeftHand
        view: xrView
        touchId: 1
        onTouchPositionChanged: buttons.handleTouch(touchPosition)
    }
}
xrOrigin: theOrigin

여기서 ` buttons `는 ` handleTouch ` 함수를 가진 3D 버튼 그룹입니다. (이 구현은 XR 전용이 아니므로, 자세한 내용은 여기에서 다루지 않습니다.)

XrOrigin 를 씬의 원점으로부터 50센티미터 떨어진 위치에 배치합니다. 이는 터치하기에 적당한 거리입니다.

장면의 나머지 부분에는 몇 가지 3D 모델과 터치 이벤트에 반응하는 XrItem 가 포함되어 있습니다.

예제 프로젝트 @ code.qt.io

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.