Làm quen với Streetscape Geometry API và Rooftop anchors API trong ARCore

1. Trước khi bắt đầu

ARCore là khung của Google để tạo trải nghiệm thực tế tăng cường (AR) trên điện thoại thông minh. API Hình học cảnh quan đường phố và API Neo đậu trên mái nhà dựa trên vị trí địa lý giúp trải nghiệm AR của bạn hiểu được các toà nhà xung quanh người dùng.

Trong lớp học lập trình này, bạn sẽ tạo một ứng dụng thực tế tăng cường (AR) có thể trực quan hoá hình học cảnh đường phố trong khu vực của bạn và cho phép bạn trang trí các mặt của hình học đó. Sau đó, bạn có thể dùng neo trên mái nhà để thêm một vật trang trí lên đỉnh mái nhà xung quanh bạn.

Điều kiện tiên quyết

• Kiến thức cơ bản về AR
• Kiến thức cơ bản về ARCore Geospatial API

Kiến thức bạn sẽ học được

• Cách thiết lập một dự án Google Cloud có thể sử dụng ARCore Geospatial API.
• Cách lấy hình học cảnh quan đường phố từ Geospatial API.
• Cách trực quan hoá các toà nhà và địa hình thu được từ hình học cảnh quan đường phố.
• Cách thực hiện các phép tính cơ bản trên các đa giác thu được.
• Cách thực hiện kiểm thử lượt nhấn trên hình học.
• Cách sử dụng điểm neo trên mái nhà để gắn nội dung vào đỉnh toà nhà.

Bạn cần có

• Một thiết bị Android được ARCore hỗ trợ, được kết nối với máy phát triển bằng cáp USB và được định cấu hình bằng tính năng Gỡ lỗi qua USB.
• Dịch vụ Google Play cho Thực tế tăng cường phiên bản 1.37 trở lên đã được cài đặt trên thiết bị phát triển Android.
• Android Studio đã được cài đặt và định cấu hình để tạo ứng dụng Android.

2. Thiết lập môi trường

Để sử dụng Geospatial API với Kotlin và Android Studio, bạn cần có một dự án Google Cloud và dự án khởi đầu của chúng tôi.

Thiết lập một dự án trên Google Cloud

ARCore Geospatial API kết nối với Google Cloud để cung cấp thông tin bản địa hoá từ Hệ thống định vị bằng hình ảnh (VPS) của Google ở những khu vực được Google Street View hỗ trợ.

Để sử dụng máy chủ này trong dự án của bạn, hãy làm theo các bước sau:

1. Tạo một dự án trên Google Cloud.
2. Trong trường Project name (Tên dự án), hãy nhập một tên thích hợp, chẳng hạn như ARCore Geospatial API project, rồi chọn một vị trí bất kỳ.
3. Nhấp vào Tạo.
4. Trong Google Cloud Console, trên trang chọn dự án, hãy nhấp vào Tạo dự án.
5. Nhấp vào đường liên kết sau để xem ARCore API cho dự án này rồi nhấp vào Bật:
   Bật ARCore API
6. Tạo khoá API cho dự án của bạn:
   1. Trong phần API và dịch vụ, hãy chọn Thông tin xác thực.
   2. Nhấp vào Tạo thông tin xác thực rồi chọn Khoá API.
   3. Ghi lại khoá vì bạn sẽ cần đến khoá này sau.

Bạn đã tạo một dự án Google Cloud có uỷ quyền khoá API và bạn đã sẵn sàng sử dụng Geospatial API trong dự án mẫu.

Thiết lập Android Studio

Để giúp bạn bắt đầu sử dụng Geospatial API, chúng tôi đã cung cấp một dự án khởi đầu bao gồm những điểm cơ bản của một dự án ARCore được tích hợp với Geospatial API.

Để thiết lập Android Studio, hãy làm theo các bước sau:

1. Mở Android Studio và làm theo một trong những cách sau:
   • Nếu bạn đã mở một dự án, hãy nhấp vào File > New > Project from version control (Tệp > Mới > Dự án từ chế độ quản lý phiên bản).
   • Nếu bạn thấy cửa sổ Welcome to Android Studio (Chào mừng bạn đến với Android Studio), hãy nhấp vào Get from VCS (Lấy trên VCS).
2. Chọn Git rồi nhấn https://github.com/google-ar/codelab-streetscape-geometry-rooftop-anchors.git để nhập dự án.

Tích hợp khoá API với dự án Android Studio

Để liên kết khoá API từ Google Cloud với dự án của bạn, hãy làm theo các bước sau:

1. Trong Android Studio, hãy nhấp vào app > src rồi nhấp đúp vào AndroidManifest.xml.
2. Tìm các mục meta-data sau đây:

   <meta-data
       android:name="com.google.android.ar.API_KEY"
       android:value="API_KEY" />
   

3. Thay thế phần giữ chỗ API_KEY bằng khoá API mà bạn đã tạo trong dự án Google Cloud. Giá trị được lưu trữ trong com.google.android.ar.API_KEY cho phép ứng dụng này sử dụng Geospatial API.

Xác minh dự án của bạn

• Để xác minh dự án, hãy chạy ứng dụng trên thiết bị phát triển. Bạn sẽ thấy chế độ xem camera và thông tin gỡ lỗi không gian địa lý ở đầu màn hình. Bạn cũng sẽ thấy các nút và chế độ điều khiển dường như không có chức năng; bạn sẽ lập trình chức năng đó vào dự án của mình trong suốt lớp học lập trình này.

Thận trọng: Nếu Geospatial API không khởi động, hãy đảm bảo rằng khoá API đã được chèn vào tệp AndroidManifest.xml của bạn chính xác như trong Google Cloud.

3. Trực quan hoá dữ liệu hình học về cảnh đường phố

Sau khi xác nhận rằng Geospatial API hoạt động trên thiết bị của bạn, bạn sẽ nhận được hình học đường phố từ Geospatial API.

Bật hình học cảnh đường phố

1. Trong tệp StreetscapeGeometryActivity.kt, hãy tìm dòng sau:

   // TODO: Enable Streetscape Geometry.
   

2. Sau dòng này, hãy bật chế độ streetscape-geometry:

   streetscapeGeometryMode = Config.StreetscapeGeometryMode.ENABLED
   

   Khi bật API Không gian địa lý và chế độ hình học cảnh đường phố, ứng dụng của bạn có thể nhận được thông tin hình học cảnh đường phố xung quanh người dùng.

Lấy hình học cảnh đường phố

1. Trong tệp StreetscapeGeometryActivity.kt, hãy tìm dòng sau:

   // TODO: Obtain Streetscape Geometry.
   

2. Sau dòng này, hãy lấy hình học của chế độ xem đường phố bằng cách lấy tất cả các đối tượng Trackable và lọc theo StreetscapeGeometry:

   val streetscapeGeometry = session.getAllTrackables(StreetscapeGeometry::class.java)
   

   Bạn sử dụng các hình học này trong một hình ảnh trực quan đơn giản có trong dự án mẫu. Hình ảnh trực quan này hiển thị từng đa giác của toà nhà hoặc địa hình bằng một màu riêng.
3. Ở dòng tiếp theo, hãy thêm mã sau:

   streetscapeGeometryRenderer.render(render, streetscapeGeometry)
   

4. Chạy ứng dụng và ghé thăm một toà nhà trong khu vực của bạn.
5. Sau khi hoàn tất quá trình Bản địa hoá không gian địa lý, hãy nhấn vào Cài đặt rồi bật chế độ trực quan hoá hình học cảnh đường phố.
6. Xem một toà nhà ở chế độ thực tế tăng cường. Mỗi toà nhà được phân đoạn đều có màu riêng và các Enum Quality và Type của hình học ở trung tâm nhất sẽ xuất hiện.

Thận trọng: Nếu bạn không thấy hình học cảnh đường phố hoặc không thấy bất kỳ thành phần trang trí nào xuất hiện khi nhấn vào màn hình, hãy làm theo các bước sau để đặt lại từ điểm kiểm tra của lớp học lập trình:

1. Trong Android Studio, hãy nhấp vào VCS > Git > Branches > Checkout > step-3 (VCS > Git > Branches > Checkout > step-3). Thao tác này sẽ quay lại bước thứ ba.
2. Thêm khoá API vào tệp AndroidManifest.xml như được trình bày chi tiết trong hướng dẫn thiết lập.

4. Thực hiện kiểm tra lượt nhấn bằng dữ liệu streetscape-geometry

Giờ đây, bạn có thể thấy hình học của khung cảnh đường phố, bạn có thể sử dụng một lượt kiểm tra lượt truy cập để trang trí toà nhà. Thử nghiệm lượt truy cập tìm ra giao điểm giữa hình học ảo và một tia. Bạn sử dụng một thử nghiệm trỏ và nhấp để tìm hình học mà người dùng nhấn vào.

Thực hiện kiểm tra lượt nhấn

Trong phần này, bạn đặt một ngôi sao trên mặt tiền của toà nhà khi người dùng nhấn vào hình học của toà nhà đó. Bạn thực hiện việc này bằng một lượt kiểm tra lượt truy cập từ góc độ của người dùng trên thế giới và đăng ký những đối tượng thực tế tăng cường mà lượt truy cập đó gặp phải trên đường đi. Sau đó, bạn sử dụng thông tin này để kiểm tra xem người dùng có nhấn vào một đa giác toà nhà hay không.

1. Trong tệp StreetscapeCodelabRenderer.kt, hãy tìm dòng sau:

   // TODO: determine the Streetscape Geometry at the center of the viewport
   

2. Sau dòng này, hãy thêm mã sau:

   val centerHits = frame.hitTest(centerCoords[0], centerCoords[1])
   val hit = centerHits.firstOrNull {
     val trackable = it.trackable
     trackable is StreetscapeGeometry && trackable.type == StreetscapeGeometry.Type.BUILDING
   } ?: return
   

   Mã này sử dụng toạ độ tâm để tìm một hình học đường phố là một toà nhà. Bạn dùng kết quả này để thêm các thành phần trang trí.

Thêm hình trang trí ngôi sao khi người dùng nhấn

1. Trong tệp StreetscapeCodelabRenderer.kt, hãy tìm dòng sau:

   // TODO: Create an anchor for a star, and add it to the starAnchors object.
   

2. Sau dòng này, hãy thêm mã sau:

   val transformedPose = ObjectPlacementHelper.createStarPose(hit.hitPose)
   val anchor = hit.trackable.createAnchor(transformedPose)
   starAnchors.add(anchor)
   

   Lớp ObjectPlacementHelper xác định vị trí thích hợp để đặt ngôi sao bằng cách xem xét tư thế chạm. Đối tượng starAnchors được dùng để kết xuất các ngôi sao trong khung hiển thị thực tế tăng cường.

Dùng thử

1. Chạy ứng dụng và ghé thăm một toà nhà trong khu vực của bạn.
2. Sau khi quá trình bản địa hoá không gian địa lý hoàn tất, hãy hướng camera vào toà nhà rồi nhấn vào màn hình. Bạn sẽ thấy một ngôi sao xuất hiện trên toà nhà ở giữa màn hình.

Thận trọng: Nếu bạn không thấy hình học của chế độ xem đường phố hoặc không thấy bất kỳ hình trang trí nào xuất hiện khi nhấn vào màn hình, hãy làm theo các bước sau:

1. Trong Android Studio, hãy nhấp vào VCS > Git > Branches > Checkout > step-4 (VCS > Git > Nhánh > Kiểm xuất > bước 4).
2. Thêm khoá API vào tệp AndroidManifest.xml như được trình bày chi tiết trong hướng dẫn thiết lập.

5. Sử dụng dữ liệu về điểm neo trên mái nhà

Cuối cùng, bạn sẽ dùng neo trên mái nhà để thêm đồ trang trí lên đỉnh toà nhà. Neo trên mái nhà giúp bạn gắn neo thực tế tăng cường vào đỉnh của các toà nhà bằng vĩ độ và kinh độ. Bạn sử dụng các điểm neo này để gắn các quả bóng vào các toà nhà xung quanh người dùng.

Thêm hành vi vào chế độ bong bóng

Dự án này có 2 chế độ đặt vị trí cho thành phần: chế độ hoa hướng dương mà bạn đã dùng và chế độ quả bóng.

Để lập trình hành vi cho chế độ bong bóng, hãy làm theo các bước sau:

1. Trong tệp StreetscapeCodelabRenderer.kt, hãy tìm dòng sau:

   // TODO: Create an anchor for a balloon and add it to the balloonAnchors object.
   

2. Sử dụng tư thế chạm để tạo vị trí phù hợp cho quả bóng:

   val transformedPose = ObjectPlacementHelper.createBalloonPose(frame.camera.pose, hit.hitPose)
   

3. Chuyển đổi biến transformedPose thành tư thế không gian địa lý:

   val earth = session?.earth ?: return
   val geospatialPose = earth.getGeospatialPose(transformedPose)
   

4. Tạo một điểm neo trên mái nhà bằng vĩ độ và kinh độ đã được chuyển đổi:

   earth.resolveAnchorOnRooftopAsync(
     geospatialPose.latitude, geospatialPose.longitude,
     0.0,
     transformedPose.qx(), transformedPose.qy(), transformedPose.qz(), transformedPose.qw()
   ) { anchor, state ->
     if (!state.isError) {
       balloonAnchors.add(anchor)
     }
   }
   

Dùng thử

1. Chạy ứng dụng và ghé thăm một toà nhà trong khu vực của bạn.
2. Sau khi quá trình bản địa hoá không gian địa lý hoàn tất, hãy chuyển sang chế độ bong bóng và nhấn vào một toà nhà. Bạn sẽ thấy một quả bóng xuất hiện phía trên toà nhà.

Nếu bạn không thể tái tạo hành vi dự kiến, hãy làm theo các bước sau:

1. Trong Android Studio, hãy nhấp vào VCS > Git > Branches > Checkout > step-5 (VCS > Git > Nhánh > Kiểm xuất > bước 5).
2. Thêm khoá API vào tệp AndroidManifest.xml như được trình bày chi tiết trong hướng dẫn thiết lập.

6. Kết luận

Xin chúc mừng! Bạn đã tạo một ứng dụng thực tế tăng cường (AR) có thể trực quan hoá hình học cảnh quan đường phố trong khu vực của bạn và cho phép bạn trang trí các mặt của hình học đó bằng các ngôi sao. Bạn cũng dùng các điểm neo trên mái nhà để thêm một quả bóng vào đỉnh của các mái nhà xung quanh.

Tìm hiểu thêm

• Hướng dẫn cho nhà phát triển về hình học của Streetscape
• Hướng dẫn dành cho nhà phát triển về điểm neo trên sân thượng
• Tổng quan về Geospatial API