World Locking Tools의 초기 설정

  • 아티클

가능한 최소 설정

이 자습서에서는 추가 작업(예: 공간 앵커) 없이 월드 고정된 애플리케이션의 모든 항목을 설치하고 실행하기 위한 최소 설정을 단계별로 안내합니다. 이 리포지토리의 형제인 샘플 리포지토리에 있습니다.

빠른 시작 가이드

WLT를 프로젝트에 통합하는 방법에 대한 개념적으로 덜 상세하고 더 실용적인 접근 방식은 여기에서 찾을 수 있습니다. 적절한 경우 이러한 상세 페이지를 다시 참조합니다. 실제로 어떤 접근 방식이 더 적합한지는 개인 선호도의 문제이지만 시작하기 전에 페이지를 훑어보면 이 설명서에서 주력해야 할 위치를 빠른 시간 안에 알 수 있습니다.

지원되는 환경

World Locking Tools for Unity는 현재 HoloLens 디바이스 제품군의 UWP 애플리케이션을 대상으로 합니다. 원래 HoloLens(x86) 및 HoloLens 2(ARM64)가 모두 지원됩니다.

다른 플랫폼에 대한 실험적 지원은 Unity의 AR 하위 시스템을 통해 사용할 수 있습니다.

World Locking Tools CI(연속 통합) 빌드는 Unity2018.4.6f1과 Visual Studio 2017에서 유효합니다. 그러나 광범위한 WLT 개발은 Unity2018 버전 전체와 특정 범위의 Unity2019를 사용하여 수행되었습니다. Visual Studio 2017 및 Visual Studio 2019는 모두 도구 개발에 사용되었습니다.

다른 버전의 Unity 및/또는 Visual Studio 호환성 문제가 발생하는 경우 알려주세요. 문제를 보고하는 가장 좋은 방법은 GitHub의 문제 포털을 사용하는 것입니다.

가정된 배경

World Locking Tools 솔루션을 프로젝트에 통합하려는 사람들은 이미 HoloLens 디바이스 제품군용 애플리케이션을 빌드하고 배포하는 방법에 대한 기본 사항을 잘 알고 있다고 가정합니다. 그렇지 않은 경우 이 문서의 끝 부분에 몇 가지 유용한 참조가 있습니다.

World Locking Tools 계층

World Locking Tools는 4개의 계층으로 나뉩니다. 계층을 가리키는 화살표가 종속된 경우 간단한 종속성 그래프는 다음과 같습니다.

레이어 다이어그램

파선은 선택적 종속성을 나타냅니다.

Examples 계층은 MRTK(MixedRealityToolkit)를 사용하지만 다른 계층에는 외부 종속성이 없으며 전체 기능은 MRTK와 호환되지만 독립적으로 사용할 수 있습니다.

애플리케이션 종속성에 대한 추가 정보는 아래와 같습니다.

계층은 다음과 같이 요약될 수 있습니다.

플러그 인

Engine DLL과의 직접 통신을 허용하는 명령적 인터페이스입니다. 여기서는 인수 마샬링과 같은 일반적인 문제 및 복합 지시문으로 조합하여 자주 사용되는 여러 함수의 일부 구성을 다룹니다. 기본 C++ DLL에 대한 하위 수준 C# 인터페이스를 유지합니다. 직접 사용할 수 있지만 필요하거나 권장되지 않습니다.

핵심

핵심은 선언적 인터페이스로 패키징된 World Locking Tools의 안정적인 월드 고정 공간의 이점을 얻는 데 필요한 모든 단계를 캡슐화한 것입니다. 작동 중인 애플리케이션은 핵심의 기능만 사용하여 제공되어야 합니다.

도구

도구는 기본적으로 진단입니다. World Locking Tools를 사용하는 모든 프로젝트에 쉽게 추가할 수 있는 양식에 World Locking Tools 프로세스의 시각화가 포함되어 있습니다.

다른 편리한 유틸리티도 포함되어 있지만 Core가 제공하는 최종 솔루션이 아닌 사용자 지정 솔루션 코딩을 시작하는 데 도움이 될 것으로 예상됩니다.

예제

예제 계층은 World Locking Tools를 사용할 때 일반적인 시나리오를 설정하는 샘플과 World Locking Tools를 다양한 시나리오에 통합하는 모범 사례를 제시하려고 시도합니다.

UX 및 개체 조작에 필요한 MRTK 종속성은 예제 계층의 스크립트 및 프리팹으로 제한됩니다. 이렇게 하면 하위 계층에 외부 종속성이 없습니다.

예제 계층의 스크립트 및 자산은 배송 제품에 직접 통합되는 것이 금지되지는 않지만 직접 통합되지 않을 것으로 예상됩니다. 오히려, 구조로 인해 재사용성과 효율성보다 단순성과 명확성을 선호합니다.

애플리케이션

일반적으로 애플리케이션은 World Locking Tools Core에만 종속되어야 합니다.

개발하는 동안에는 도구 계층에서 예기치 않은 동작을 이해하기 위한 많은 시각화 및 기타 도우미를 사용할 수 있습니다. 이러한 도우미는 완성된 애플리케이션에서 제거되거나 적어도 사용하지 않도록 설정되는 것이 이상적입니다. 물론, 현재 형태나 수정된 형태로 다른 용도로도 사용될 수 있습니다. 자세한 내용은 라이선스를 참조하세요.

고급 사용 및 World Locking Tools의 전체 기능 실험을 위한 플러그 인 계층은 Engine DLL에 대한 하위 수준의 명령적 액세스를 제공합니다.

플러그 인 계층에 대한 액세스가 필요해진다면 핵심 계층에서 제공되는 API 화면에 결함이 있는 것일 수 있습니다. World Locking Tools 팀은 항상 이러한 격차를 메우기 위해 노력하고 있습니다. 이러한 인사이트를 이 팀에 기여해 주시기 바랍니다. 기여를 참조하세요.

설치 경로 길이에 대한 경고 문구

일부 버전의 MRTK에는 긴 설치 경로와 관련된 문제가 있습니다. MRTK 설치에서 심층 하위 폴더의 전체 경로 길이가 Windows 경로 제한(260자)을 초과할 수 있습니다. 다음 양식의 빌드 오류가 나타나는 경우:

DirectoryNotFoundException: Could not find a part of the path "D:\MyOverTwentyEightCharacterLongLengthInstallPath\MixedReality-WorldLockingTools-Unity\Assets\MRTK\MixedRealityToolkit.Providers\WindowsMixedReality\DotNetAdapter\Plugins\net46\Microsoft.Windows.MixedReality.DotNetWinRT\Editor\Microsoft.Windows.MixedReality.DotNetWinRT.Editor.asmdef"

그러나 파일이 실제로 드라이브에 있다면 경로 길이가 문제일 수 있습니다. MRTK 팀은 이를 알고 있으며 이를 개선하기 위해 노력하고 있습니다(메모: 이 문제는 대폭 개선되었으며 더 이상 문제가 되지 않는다고 생각합니다). 그동안 해결 방법은 다음을 조합하여 경로 접두사를 단축하는 것입니다.

  1. 더 짧은 길이의 경로 루트(예: "D:\Proj")에 Unity 프로젝트를 설치합니다.
  2. 리포지토리를 복제하는 경우 다음과 같이 World Locking Tools의 루트를 기본 "\MixedReality-WorldLockingTools-Unity"보다 짧은 것으로 복제합니다.
git clone https://github.com/microsoft/MixedReality-WorldLockingTools-Unity.git d:\MyGit\wlt

이 경로 제한은 일반적으로 World Locking Tools 자체에서 문제가 되지 않습니다. 이 도구는 이처럼 긴 폴더 구조를 활용하지 않기 때문입니다.

Unity 프로젝트에 World Locking Tools 추가

참고

다음은 World Locking Tools 및 종속성의 수동 설치에 대한 설명입니다. Mixed Reality Feature Tool을 통해 훨씬 더 간소화된 설치 프로세스를 사용할 수 있습니다. Feature Tool을 통한 설치는 여기에 설명되어 있습니다. Feature Tool에서 WLT를 설치하는 경우 다음을 건너뛰고 장면에 WLT 추가를 진행할 수 있습니다.

World Locking Tools는 nuget을 사용하여 기본 Frozen World Engine을 설치합니다.

기존 프로젝트에 World Locking Tools를 추가하는 경우 HoloLens 디바이스에 빌드하고 배포하는 것으로 확인된 프로젝트로 시작하는 것이 좋습니다. 이렇게 하면 우선 HoloLens에서 앱을 실행하는 것과 관련된 문제를 World Locking Tools 관련 문제와 구분하는 데 도움이 됩니다. 그런 다음, 아래의 FrozenWorld Engine 설치 및 World Locking Tools 자산 섹션을 진행합니다.

FrozenWorld Engine 설치

Frozen World Engine DLL은 우수한 NuGet For Unity 유틸리티를 사용하거나 수동으로 NuGet을 가져올 수 있습니다.

NuGet For Unity 사용

nuget.org 피드가 소스에 있는지 확인합니다. 이는 Unity > 편집 > 기본 설정 > NuGet for Unity에서 확인합니다. 실패한 경우 둘 중 하나를 수행합니다.

Unity > 편집 > 기본 설정 > NuGet For Unity에서 새 소스 추가 GUI를 사용하여 동일한 공유를 추가합니다.

  • "새 소스"를 선택한 이름(예: "NuGet")으로 바꿉니다.
  • "source_path"를 "http://www.nuget.org/api/v2/"로 바꿉니다.

nuget.org 피드를 확인한 후 Unity > NuGet > NuGet 패키지 관리에서 최신 버전의 Microsoft.MixedReality.FrozenWorld.Engine을 찾아 설치합니다. ("FrozenWorld"를 검색합니다.)

이후 버전으로 업데이트하려면 Unity > NuGet > NuGet 패키지 관리를 다시 열고 FrozenWorld.Engine 패키지를 찾아 업데이트를 선택합니다. 참고: 원하는 버전을 찾으려면 업데이트 탭으로 이동해야 할 수 있습니다.

수동 Frozen World Engine DLL 설치

텍스트 편집기를 사용하여 Assets/NuGet.config에 packageSources 줄을 추가합니다.

  <packageSources>
    <add key="NuGet" value="http://www.nuget.org/api/v2/" />
  </packageSources>

Assets/NuGet.config 파일이 아직 없는 경우 World Locking Tools github 리포지토리에서 복사할 수 있습니다.

텍스트 편집기를 사용하여 Frozen World Engine DLL 패키지를 Assets/packages.config 등에 추가합니다.

<?xml version="1.0" encoding="utf-8"?>
<packages>
  <package id="Microsoft.MixedReality.Unity.FrozenWorld.Engine" version="1.0.0" />
</packages>

다시 말하지만, Assets/packages.config 파일이 아직 없는 경우에는 World Locking Tools github 리포지토리에서 파일을 가져오거나 위 파일을 "Assets/packages.config"라는 텍스트 파일에 복사하면 됩니다.

NuGet.config 및 packages.config를 설정했으면 다음과 같은 방법으로 설치합니다.

  1. NuGet 다운로드에서 최신 nuget.exe를 가져옵니다.
  2. nuget.exe가 경로에 있는지 확인합니다(여기서는 Assets에 복사되었다고 가정합니다).
  3. PowerShell 명령 창을 열고 디렉터리를 Assets 폴더로 변경합니다.
  4. 다음 명령을 실행합니다.
.\nuget.exe restore

이후 버전으로 업그레이드하려면 다음을 수행합니다.

  1. 위의 packages.config 파일에서 FrozenWorld.Engine 버전 번호를 원하는 버전으로 업데이트합니다(예: version="1.0.0"은 version="1.0.1").
  2. "Microsoft.MixedReality.Unity.FrozenWorld.Engine"으로 시작하는 Assets/Packages 폴더의 모든 항목을 삭제합니다.
  3. 위와 같이 nuget.exe를 다시 실행합니다.

World Locking Tools 자산

필요한 World Locking Tools .unitypackage 파일을 프로젝트로 가져오거나(권장 방법) 복사합니다. 애플리케이션 개발에 방해가 되지 않도록 Assets 내의 하위 폴더로 이동할 수 있습니다.

안정적인 버전의 최신 .unitypackage 파일은 World Locking Tools for Unity 릴리스에서 찾을 수 있습니다.

WorldLocking.Core 및 Engine 계층은 반드시 필요하므로 최소 설치 패키지는 WorldLockingCoreEngine.unitypackage가 됩니다.

필요한 다른 계층을 확인하려면 위의 World Locking Tools 계층 및 종속성에 대한 설명을 참조하세요. 각 계층은 단일 Unity 패키지에 포함됩니다.

일부 World Locking Tools 예제는 MRTK의 기능을 사용하므로 호환되는 MRTK 스냅샷이 예제 unitypackage에 포함됩니다. 최신 MRTK 릴리스는 여기를 참조하세요.

Unity 장면에 World Locking Tools 추가

참고

아래에 나열된 단계는 모두 WLT 장면 구성 유틸리티에서 자동화되며, Mixed Reality Toolkit > 유틸리티 > World Locking Tools 메뉴에서 찾을 수 있습니다. 구성 메뉴

nuget.org의 FrozenWorld 엔진이 포함된 Unity 프로젝트 내에서 원하는 World Locking Tools 자산 계층(최소 WorldLocking.Core)을 가져오고 필요에 따라 MRTK를 가져옵니다. 그런 다음, 새 장면을 만들거나 기존 장면을 엽니다.

참고

카메라 계층 구조의 루트에 추가 노드를 추가합니다. 이 노드는 머리 추적 카메라를 월드 고정 공간으로 조정하는 데 사용됩니다. (MRTK를 사용하는 경우 이 새 GameObject는 MixedRealityPlayspace의 부모가 됩니다.)

핵심 환경

Assets/WorldLocking.Core/Prefabs의 WorldLockingManager 프리팹을 장면으로 끌어옵니다. 장면에서의 위치는 중요하지 않지만 카메라 트리에 있으면 안 됩니다. 제안된 구성에 대한 샘플 장면을 참조하세요.

WorldLockingManager 프리팹에서 사용할 수 있는 설정이 있지만 기본값으로 두고 시작하는 것이 좋습니다.

제공되는 옵션에 대한 설명은 World Locking Tools Context를 참조하세요.

[선택 사항] MRTK

World Locking Tools는 MRTK에 대한 직교적이지만 보완적인 도구입니다. World Locking Tools와 MRTK를 함께 사용하는 것은 전적으로 선택 사항입니다.

즉, World Locking Tools 샘플은 MRTK를 사용하여 빌드되었으며, MRTK는 일반적으로 World Locking Tools로 가장 큰 혜택을 받는 MR 애플리케이션 유형을 개발하는 데 매우 유용합니다.

예제에 포함된 스냅샷을 사용하는 대신 MRTK를 사용하는 경우 적어도 다음 패키지의 최신 버전을 추가하는 것이 좋습니다.

  • MixedReality.Toolkit
  • MixedReality.Toolkit.Providers
  • MixedReality.Toolkit.Services
  • MixedReality.Toolkit.SDK

[선택 사항] Spongy 및 월드 고정 앵커 시각화

이렇게 하려면 프로젝트의 자산에 WorldLocking.Tools를 추가해야 합니다.

앵커를 시각화하려면 Assets/WorldLocking.Tools/Prefabs의 AnchorGraphVisual 프리팹을 장면으로 끌어옵니다. 검사기에서 시각화의 가로 세로 비율을 전환하는 확인란은 WorldLockingManager에 있습니다.

진단 기능인 WorldLocking.Tools 시각화는 크게 최적화되지 않으며, 핵심 World Locking Tools 처리 시간이 관련되기 훨씬 전에 성능을 저하시킵니다.

[선택 사항] Mixed Reality 내의 매개 변수 제어를 위한 간단한 대시보드

MR 내부에서 런타임 시 WorldLockingManager를 제어하는 데 사용할 수 있는 간단한 HUD를 사용할 수 있습니다. 이는 예제 패키지에 제공됩니다. 그대로 사용할 수 있지만 애플리케이션 자체 디스플레이 시스템 및 UX에 유사한 기능을 빌드할 때 패턴으로 사용하도록 고안되었습니다.

WorldLocking.Examples/Prefabs/Dashboard 프리팹을 끌어서 앵커 시각화 도우미 필드를 이전 섹션의 시각화로 가리킵니다.

기존 장면을 World Locking Tools로 마이그레이션

World Locking Tools로 이동할 때 가장 큰 변화는 더 이상 월드 고정 가상 개체에 공간 앵커를 사용할 필요가 없다는 것입니다.

공간 앵커는 기존에 월드 고정 개별 개체에 사용할 수 있는 유일한 도구였습니다. 그러나 World Locking Tools를 사용하는 경우 가상 개체가 존재하는 좌표 공간은 이미 월드 고정되어 있습니다. 추가 잠금이 필요하지 않습니다.

공간 앵커가 필요하지 않을 뿐만 아니라 카메라 계층 구조 상부의 추가 변환(예: MRTK "Playspace" 변환)을 고려하지 못하기 때문에 제대로 작동하지 않습니다.

따라서 모든 공간 앵커를 장면에서 제거해야 하며 공간 앵커를 추가하는 스크립트는 중단해야 합니다. 공간 앵커는 아무것도 바꿀 필요가 없습니다. World Locking Tools는 현실 세계에 대상을 고정합니다.

World Locking Tools를 사용하거나 사용하지 않고 월드 고정을 비교하는 것이 바람직하다면 WorldAnchors를 제거하는 대신 WorldLocking.Tools에 제공된 ToggleWorldAnchor로 바꿀 수 있습니다.

ToggleWorldAnchor는 WorldAnchor와 정확히 동일하게 작동하며, World Locking Tools Manager가 활성 상태일 때 편리하게 자체적으로 사용하지 않도록 설정되고 방해하지 않는다는 중요한 차이점이 있습니다. World Locking Tools Manager가 사용하지 않도록 설정되면 일반 WorldAnchor로 동작합니다.

다른 이유로 인해 장면에서 WorldAnchor가 여전히 필요한 경우(예: 네트워크 공유를 위해) WorldAnchorAdapter로 제공되는 어댑터와 함께 사용할 수 있습니다.

WorldAnchorAdapter는 WorldAnchor에 의해 배치된 GameObject의 원시 위치를 월드 고정 Unity 글로벌 공간으로 변환한 다음, 대상 개체에 변환을 적용합니다. 이를 사용하려면 WorldAnchor를 개체에 직접 추가하는 대신 프록시 개체(일반적으로 비어 있는 GameObject)에 WorldAnchor를 적용해야 합니다. 그러면 Update()에서 WorldAnchorAdapter가 WorldAnchor의 포즈를 읽고, 올바르게 변환하고, 대상에 적용합니다.

설정 완료

위의 단계를 수행하면 디바이스에 배포된 프로젝트가 World Locking Tools에 의해 조정된 상태로 실행되어 최적으로 안정화된 월드 고정 공간을 유지합니다. 장면에 배치된 고정 개체는 시각적으로 서로 간에 일관되고, 실제 세계와 일관되게 유지됩니다.

사용 가능한 예제 애플리케이션

스크립트와 자산을 포함한 샘플 장면은 World Locking Tools의 기능을 보다 복잡하게 사용하는 방법을 보여 줍니다.

예를 들어 WorldLockedPhysicsSample은 서로 상호 작용하고 환경(공간 매핑)과 상호 작용하도록 물리적으로 시뮬레이션된 개체를 만들고 제거할 수 있는 간단한 환경을 제공합니다.

공간 고정 기능을 좀 더 집중적으로 볼 수 있도록 SpacePin은 대규모 가상 개체를 실제 피쳐에 맞추는 훨씬 간소화된 예제를 제공합니다.

RayPins는 SpacePin 예제에 도입된 기능을 확장하여 공간 메시에 대한 광선 테스트를 통해 가상 세계를 물리적 세계에 고정할 수 있습니다.

시작을 위한 참조

AR 앱을 만들고, 빌드하고, HoloLens 디바이스 제품군에 배포하는 방법에 대한 기본 사항에 익숙하지 않은 경우, 시작하는 데 도움이 될 수 있는 몇 가지 참조는 다음과 같습니다.

Unity 개발 개요 - MR/AR용 Unity 개발입니다.

MR 기본 사항 100 - HoloLens 개발 시작을 안내합니다.

HoloLens 2 자습서 - HoloLens 2 개발 시작을 안내합니다.

좌표계 AR 개발의 좌표 공간 관련 정보입니다.

  • World Locking Tools는 여기에 설명된 문제를 해결합니다.

문제가 있나요?

문제 해결 가이드를 참조하세요.