WeChat 미니 프로그램 Mega 플러그인 sample project 빠르게 실행

이 문서는 WeChat 미니 프로그램 Mega 플러그인의 sample project를 빠르게 실행하는 방법을 소개합니다. 다음을 배우게 됩니다.

sample project의 development environment를 구축하고 구성합니다.
sample의 일부 기능 실행: Mega cloud localization 사용.
매핑 결과의 마스크 파일을 표시합니다.

시작하기 전에

내 localization 기능을 사용할 수 있나요? 문서를 참고하여 localization library가 올바르게 생성되고 map이 추가되었는지 확인합니다.

미니 프로그램 주체가 enterprise entity인지 확인

중요

Mega mini program 플러그인은 enterprise entity의 WeChat mini program만 지원합니다. individual entity 유형의 mini program은 Mega mini program 플러그인을 사용할 수 없습니다.

mini program backend에서 Settings > Basic Information > Entity Information이 enterprise legal person 또는 individual industrial and commercial household로 표시되는지 확인해야 합니다.

Mega 기능은 mini program 플러그인 형태로 제공되므로, host environment로 enterprise entity의 WeChat mini program을 보유해야 합니다.

제공된 sample project만 실행하려는 경우에도 developer tool에서 debug와 preview를 하려면 자신의 WeChat mini program AppID를 구성해야 합니다.

sample project 다운로드

development tool 다운로드 페이지로 이동합니다.
EasyAR Privacy Policy 확인 후 download를 클릭합니다.
다운로드가 완료되면 로컬에서 .zip package의 압축을 풉니다.

sample project 구성

WeChat Mini Program Developer Tools에 로그인합니다.
WeChat Mini Program Developer Tools를 사용하여 샘플 프로젝트를 가져옵니다.
- Developer Tools를 연 후 import 버튼을 클릭하고 로컬에서 압축 해제한 디렉터리를 선택합니다.
- AppID가 Mega 라이선스 신청 시 입력한 AppID와 일치하는지 확인하고, 개발 모드를 Mini Program으로 설정한 뒤 Create를 클릭합니다.
참고

AppID가 일치하지 않으면 라이선스 검증에 실패합니다
Mega 라이선스 및 클라우드 서비스 구성

miniprogram/components/sample-data/easyar-settings.ts 파일을 열고 준비 단계의 라이선스 및 서비스 정보에 따라 해당 필드를 입력합니다.
- Mega 라이선스
```
/** 您的小程序 Mega 许可证 */
export const EasyARLicenseKey: string = "";
```
Mega WeChat Mini Program 라이선스 받는 방법

EasyAR Developer Center에서 Mega WeChat Mini Program을 선택합니다.

사용할 Mega WeChat Mini Program 라이선스가 목록에 있어야 합니다. 사용 가능한 라이선스가 없다면 현재 계정이 Mega 로컬라이제이션 데이터베이스를 만든 계정과 같은지 확인하십시오.

Mini Program 이름을 클릭하여 해당 Mega 라이선스를 가져옵니다. 오른쪽의 Copy를 클릭한 뒤 easyar-settings.ts에 EasyARLicenseKey 값으로 붙여 넣고, 연결된 AppID가 WeChat Mini Program AppID와 완전히 일치하는지 확인합니다.
- 클라우드 서비스 API Key 및 Seceret
```
/** 您的云服务 API Key 及 Seceret */
export const EasyARAPIKey: string = "";
export const EasyARAPISecret: string = "";
```
클라우드 서비스 API Key 및 Seceret을 얻는 방법

EasyAR Developer Center에서 Cloud Service API KEY를 선택합니다.

이전에 클라우드 서비스 API Key 및 Seceret을 만든 적이 있다면 오른쪽의 Copy를 순서대로 클릭하고 easyar-settings.ts에 EasyARAPIKey와 EasyARAPISecret 값으로 붙여 넣습니다.

이전에 클라우드 서비스 API Key 및 Seceret을 만든 적이 없다면 다음 방식으로 만듭니다.

EasyAR Developer Center에서 Cloud Service API KEY > Create API KEY를 선택합니다.

애플리케이션 이름을 입력하고 사용할 클라우드 서비스 Mega Block 및/또는 Mega Landmark를 선택한 뒤 Confirm을 클릭합니다.
- 클라우드 서비스 ServerAddress 및 AppID：
```
/** 您的 Mega 云定位库的 ServerAddress 及 AppID */
export const MegaTrackerServerAddress: string = "";
export const MegaTrackerAppID: string = "";
```
Mega 클라우드 로컬라이제이션 데이터베이스의 ServerAddress 및 AppID를 얻는 방법

EasyAR Developer Center에서 Block Cloud Localization을 선택한 뒤 자신의 Mega 클라우드 로컬라이제이션 서비스 그룹을 선택합니다.

자신의 Mega 클라우드 로컬라이제이션 데이터베이스를 선택합니다.

Key를 클릭한 뒤 아래에서 클라우드 로컬라이제이션 데이터베이스의 AppID와 Server Address를 순서대로 가져옵니다. 오른쪽의 Copy를 클릭하고 easyar-settings.ts에 MegaTrackerAppID와 MegaTrackerServerAddress 값으로 붙여 넣습니다.
매핑 결과의 마스크 파일로 빠르게 검증

Mask file download 항목을 통해 매핑 결과의 glb 마스크 파일을 다운로드하고 실제 공간의 3D white model을 표시하여, annotation을 만들지 않고 모델과 실제 공간의 정렬 상태를 확인할 수 있습니다.

참고

이 방식은 mapping version 9.6 이상의 매핑 결과에만 적용됩니다.

cloud localization database에서 테스트할 Block을 찾고 해당 행의 Action 열에서 Mask file download 를 클릭합니다. 실행 시 이 Block에 대응하는 scene에서 테스트해야 합니다.

팝업에서 Low precision 을 선택하고 해당 Download 버튼을 클릭하여 휴대폰의 로딩 및 렌더링 부담을 줄입니다.

다운로드한 glb 파일을 Mini Program 프로젝트의 assets 디렉터리, 예제에서는 miniprogram/assets/ 에 넣고 원래 position, rotation, scale을 유지합니다.

sample project에는 마스크 파일 로드, 표시, 해제 로직이 이미 포함되어 있습니다. 예를 들어 occlusion_mesh_sd.glb 를 miniprogram/assets/ 에 넣은 뒤 sampleAssets.occlusionMesh.src 에 프로젝트 루트 기준 상대 경로를 입력합니다.
```
src: "assets/occlusion_mesh_sd.glb",
```
sampleAssets.occlusionMesh 의 assetId, type, options 는 변경하지 않습니다. sample 실행 후 페이지에서 Mask file 스위치를 켜면 모델을 볼 수 있습니다.

실제 기기에서 sample 실행

Mini Program developer tool 상단 바의 real-device preview 버튼을 클릭하고 QR code를 스캔하여 개발용 휴대폰에 로드합니다.

주의

developer tool에서 AR 기능이 있는 xr-frame 컴포넌트를 직접 시뮬레이션 실행할 수 없습니다.

참고

WeChat Developer Tools에서 sample project를 처음 실행할 때 아직 plugin permission을 얻지 못한 경우, tool은 일반적으로 plugin이 인증되지 않았다는 팝업을 표시합니다. WeChat Developer Tools를 통해 자동으로 인증하거나 plugin access process를 참고할 수 있습니다.
EasyAR Mega Samples를 클릭하여 sample project의 AR scene으로 들어갑니다.

참고

sample project의 AR scene에 들어갈 수 없다면, 현재 device가 WeChat의 시각 알고리즘 컴포넌트 VisionKit을 지원하지 않기 때문일 수 있습니다. 자세한 내용은 device restrictions를 참고하십시오.
화면의 EasyAR Session is initializing 프롬프트는 WeChat plane detection이 초기화 중임을 나타냅니다.

팁

조명이 충분한 환경에서 테스트하고 넓은 단색 벽면이나 단색 바닥은 피하십시오.

바닥 또는 다른 plane을 향해 일정한 속도로 좌우로 흔들면 이 과정을 빠르게 진행할 수 있습니다.
초기화가 완료되면 휴대폰을 세로로 세워 camera가 정상적인 현실 화면을 촬영하도록 합니다. Localization이 성공하면 Debug 정보에 Found가 나타나고 오른쪽 아래의 상태 표시기가 흰색에서 녹색으로 바뀝니다.
occlusion 효과 확인

앞의 마스크 파일 표시 구성이 완료된 뒤 모델이 로드되고 해당 Block에 성공적으로 localized되면, 카메라 화면 위에 겹쳐진 3D white model을 볼 수 있습니다.