使用 ARCore 和 Kotlin 开发 Android 增强现实应用入门指南

环境准备

1. 工具与设备要求

• Android Studio：Arctic Fox 或更高版本
• 设备：支持 ARCore 的 Android 设备（查看支持列表）
• 依赖库：

  // build.gradle (Module级)
  dependencies {implementation 'com.google.ar:core:1.35.0'implementation 'com.google.ar.sceneform:core:1.17.1'implementation 'com.google.ar.sceneform.ux:sceneform-ux:1.17.1'
  }
  

---

基础实现步骤

1. 配置 AndroidManifest.xml

<!-- 添加权限和AR特性 -->
<uses-permission android:name="android.permission.CAMERA" />
<uses-feature android:name="android.hardware.camera.ar" android:required="true" /><application><!-- 声明AR元数据 --><meta-dataandroid:name="com.google.ar.core"android:value="required" />
</application>

---

2. 创建完整布局文件

<!-- activity_main.xml -->
<?xml version="1.0" encoding="utf-8"?>
<FrameLayoutxmlns:android="http://schemas.android.com/apk/res/android"android:layout_width="match_parent"android:layout_height="match_parent"><fragmentandroid:id="@+id/arFragment"android:name="com.google.ar.sceneform.ux.ArFragment"android:layout_width="match_parent"android:layout_height="match_parent" /></FrameLayout>

---

3. 完整 Kotlin 主活动代码

// MainActivity.kt
import android.net.Uri
import android.os.Bundle
import android.widget.Toast
import androidx.appcompat.app.AppCompatActivity
import com.google.ar.core.ArCoreApk
import com.google.ar.core.Config
import com.google.ar.core.Session
import com.google.ar.sceneform.AnchorNode
import com.google.ar.sceneform.rendering.ModelRenderable
import com.google.ar.sceneform.ux.ArFragment
import com.google.ar.sceneform.ux.TransformableNodeclass MainActivity : AppCompatActivity() {private lateinit var arFragment: ArFragmentprivate var isArSupported = falseoverride fun onCreate(savedInstanceState: Bundle?) {super.onCreate(savedInstanceState)setContentView(R.layout.activity_main)checkARSupport()setupARScene()}// 检查AR支持性private fun checkARSupport() {val availability = ArCoreApk.getInstance().checkAvailability(this)when {availability.isSupported -> {isArSupported = trueArCoreApk.getInstance().requestInstall(this, true)}availability.isTransient -> {// 如果状态是暂时未知，延迟后重新检查Handler(Looper.getMainLooper()).postDelayed({checkARSupport()}, 200)}else -> {Toast.makeText(this, "设备不支持AR", Toast.LENGTH_LONG).show()finish()}}}// 初始化AR场景private fun setupARScene() {arFragment = supportFragmentManager.findFragmentById(R.id.arFragment) as ArFragment// 配置AR会话arFragment.arSceneView.scene.addOnUpdateListener { frameTime ->arFragment.arSceneView.scene.getCamera()?.let { camera ->// 在此处添加每帧更新的逻辑}}// 设置点击监听器arFragment.setOnTapArPlaneListener { hitResult, plane, motionEvent ->placeModel(hitResult.createAnchor())}}// 放置3D模型private fun placeModel(anchor: Anchor) {ModelRenderable.builder().setSource(this, Uri.parse("model.sfb")) // 替换为你的模型路径.build().thenAccept { modelRenderable ->val anchorNode = AnchorNode(anchor)anchorNode.setParent(arFragment.arSceneView.scene)val modelNode = TransformableNode(arFragment.transformationSystem)modelNode.renderable = modelRenderablemodelNode.setParent(anchorNode)modelNode.select() // 自动显示变换控制器}.exceptionally { throwable ->Toast.makeText(this, "模型加载失败: ${throwable.message}", Toast.LENGTH_LONG).show()null}}
}

---

4. 模型资源配置

1. 准备模型文件：
   • 将 .obj 和 .mtl 文件放入 app/src/main/assets
   • 创建 model.sfa 描述文件：

     // model.sfa
     {"resources": [{"filename": "model.obj","material": "model.mtl"}]
     }
     

2. 配置 Gradle 转换任务：

   plugins {id 'com.google.ar.sceneform.plugin'
   }sceneform.asset('src/main/assets/model.obj','default','src/main/assets/model.sfa','src/main/assets/model.sfb'
   )
   

---

高级功能扩展

1. 平面检测可视化

// 在setupARScene()中添加：
arFragment.arSceneView.planeRenderer.isVisible = true
arFragment.arSceneView.planeRenderer.material.thenAccept { material ->material.setFloat3("color", Color(0.3f, 0.7f, 0.3f))}

2. 光照估计

// 在每帧更新中获取光照信息
arFragment.arSceneView.scene.addOnUpdateListener { frameTime ->val frame = arFragment.arSceneView.arFrameval lightEstimate = frame?.lightEstimatelightEstimate?.let {val intensity = it.pixelIntensity// 根据光照强度调整模型材质}
}

---

常见问题解决

1. 黑屏问题排查

• 检查相机权限是否动态申请：

  // 在onCreate()中添加权限检查
  if (ContextCompat.checkSelfPermission(this, Manifest.permission.CAMERA) != PackageManager.PERMISSION_GRANTED) {ActivityCompat.requestPermissions(this, arrayOf(Manifest.permission.CAMERA), REQUEST_CAMERA_PERMISSION)
  }
  

2. 模型位置偏移

• 调整模型原点：

  modelNode.localPosition = Vector3(0f, 0.5f, 0f) // 在Y轴上抬高0.5米
  

---

完整项目结构

app/
├── src/
│   ├── main/
│   │   ├── assets/
│   │   │   ├── model.obj
│   │   │   ├── model.mtl
│   │   │   └── model.sfa
│   │   ├── java/
│   │   │   └── com.example.arapp/
│   │   │       └── MainActivity.kt
│   │   └── res/
│   │       └── layout/
│   │           └── activity_main.xml
└── build.gradle

---

运行与调试

1. 设备要求：
   • 确保设备已安装 Google Play Services for AR
2. 调试技巧：

   // 启用调试模式
   arFragment.arSceneView.arFrame?.let { frame ->Log.d("AR_DEBUG", "跟踪状态: ${frame.camera.trackingState}")
   }
   

---

下一步学习方向

• 手势交互：实现模型的旋转/缩放/平移
• 遮挡处理：使用深度API实现真实遮挡效果
• 多人共享：通过Cloud Anchors实现多设备协同

建议从简单模型开始，逐步添加复杂功能。