关于 sceneview
SceneView 是面向 Android、Apple 平台和 Web 的开源 3D 与 AR SDK,供应用开发者以声明式方式构建场景。它还提供面向 AI 助手的 API 参考、示例和 MCP 工具。
主要功能
- 01跨平台 3D 与 AR 场景
- 02声明式 UI 集成
- 03模型、几何体与动画节点
- 04ARCore 场景支持
- 05代码校验与 API 参考
- 06多平台示例和设置指南
适用场景
- 01在 Android 应用中显示 3D 模型
- 02将模型放置到 AR 场景
- 03在 Web 页面嵌入模型查看器
- 04借助 AI 助手生成 SceneView 代码
MCP 相关
MCP 服务向 AI 助手提供 SceneView 代码校验、节点 API 参考、示例查询和项目设置指南。支持本地 STDIO、HTTP 连接及托管端点。
配置
本地服务的配置在各客户端中通用,复制后粘贴到客户端的 MCP 配置文件即可。
工具
13收录的工具列表 · 更新于 2 周前
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| scenario | enum | 是 | 要获取的场景: - "model-viewer": 全屏 3D 场景,包含 GLB 模型、HDR 环境、轨道相机和动画控件 - "ar-model-viewer": 带平面检测的 AR 场景。点击表面可放置 3D 模型,并通过捏合缩放和拖动旋转手势进行操作。 - "ar-augmented-image": 检测摄像头画面中的参考图像,并在其上方叠加 3D 模型或视频。 - "ar-cloud-anchor": 使用 ARCore Cloud Anchors 创建并解析可跨设备持久存在的锚点。 - "ar-point-cloud": 将 ARCore 特征点显示为 3D 球体,并按置信度进行筛选。 - "gltf-camera": 提取并使用嵌入 glTF 文件中的相机定义,呈现电影感视角。 - "camera-manipulator": 通过可自定义的灵敏度和边界控制相机的轨道旋转、平移和缩放。 - "autopilot-demo": 完整的自动驾驶 HUD,包含动画汽车、交通灯、道路和实时遥测叠加层。 - "physics-demo": 交互式物理模拟,包含弹跳球体、重力、可配置的恢复系数和颜色选择。 - "dynamic-sky": 通过 DynamicSkyNode 实现日照周期,并通过 FogNode 添加大气雾效。 - "line-path": 动画 3D 线条艺术,包含正弦波、利萨如曲线和参数滑块。 - "text-labels": 面向摄像机的 3D 文本标签(TextNode + BillboardNode),并支持交互式切换标签。 - "reflection-probe": 基于区域的 IBL 覆盖,带有材质选择器(Chrome、Gold、Copper、Rough)和探针开关。 - "post-processing": 实时后处理效果:泛光、暗角、色调映射、FXAA 和 SSAO 控件。 - "ios-model-viewer": SwiftUI 3D 场景,包含 USDZ 模型、IBL 环境、轨道相机和动画播放。 - "ios-ar-model-viewer": 带平面检测的 AR 场景。使用 ARKit + RealityKit,点击表面即可放置 3D 模型。 - "ios-ar-augmented-image": 使用 ARKit 检测摄像头画面中的参考图像,并在其上方叠加 3D 内容。 - "ios-geometry-shapes": 程序化几何形状——立方体、球体、圆柱体、圆锥体和平面,带 PBR 材质。 - "ios-lighting": 方向光、点光源和聚光灯,支持配置强度、颜色和阴影。 - "ios-physics": 交互式物理模拟,包含弹跳球体、重力和可配置的恢复系数。 - "ios-text-labels": 使用 TextNode 和 BillboardNode 创建面向摄像机的 3D 文本标签,使标签始终朝向摄像机。 - "ios-video-player": 使用 VideoNode 在 3D 平面上播放视频,并提供播放/暂停控件。 - "web-model-viewer": 基于浏览器的 3D 模型查看器,使用 Filament.js (WebGL2/WASM)——与 SceneView Android 使用相同的引擎 - "web-environment": 浏览器中的 3D 场景,使用 KTX 文件提供 IBL 环境光照和天空盒model-viewer | ar-model-viewer | ar-augmented-image | ar-cloud-anchor | ar-point-cloud | gltf-camera | camera-manipulator | autopilot-demo | physics-demo | dynamic-sky | line-path | text-labels | reflection-probe | post-processing | ios-model-viewer | ios-ar-model-viewer | ios-ar-augmented-image | ios-geometry-shapes | ios-lighting | ios-physics | ios-text-labels | ios-video-player | web-model-viewer | web-environment |
详细介绍
SceneView
面向 Jetpack Compose、SwiftUI 和 Web 的 AI 优先 3D 与 AR SDK。
为应用开发者提供声明式 3D 和 AR:无需游戏引擎,即可在屏幕上或房间中展示模型。Android 上使用 Filament + ARCore,Apple 平台上使用 RealityKit + ARKit,浏览器中使用 Filament.js + WebXR,并提供 Flutter、React Native 和 Compose Multiplatform 桥接。开源,Apache 2.0。
此处的 AI 优先 只有一个含义:助手读取 llms.txt 或
the MCP server 后,编写的 SceneView 代码能一次成功。如果未能成功,我们就修复 API 或文档。
试用
演示应用由 samples/ 构建。点击链接即可直接打开任意演示:
https://sceneview.github.io/open?demo=<id>。可以从 Cosmos 开始,这是目录打开时展示的星系;也可以试试 3D Scan,这是使用 ARCore 扫描并重建为 3D 的空间。
帮助测试演示
安装 Android 演示应用,使用演示时录制屏幕,并告诉我们有哪些问题或令人困惑之处:提交 issue并附上录屏,或直接从应用中发送反馈(打开任意演示,然后进入 Settings,选择 Send feedback)。 提交第一份报告后,即可立即解锁 SceneView Labs,抢先体验实验性演示。
快速开始
每个平台各提供一个最精简的可运行示例。各平台的完整参考见
llms.txt。
Android
// build.gradle.kts
implementation("io.github.sceneview:sceneview:4.62.0")
应用模块需要设置 compileSdk = 37、minSdk 24 或更高、AGP 9.4.0+、Kotlin 2.4,并将 Java 和 Kotlin 的 JVM
目标都设为 21:SceneView 使用 Java 21 字节码,并提供公开的 inline
函数。快速入门要求中提供了 Gradle
代码片段,并说明了每项要求的原因。
@Composable
fun ModelScreen() {
SceneView(modifier = Modifier.fillMaxSize()) { // orbit camera + default lighting
rememberModelInstance(modelLoader, "models/helmet.glb")?.let { instance ->
ModelNode(modelInstance = instance, scaleToUnits = 1.0f, autoAnimate = true)
}
}
}
models/helmet.glb 位于 src/main/assets/ 中。模型加载完成前,rememberModelInstance 会返回 null,加载完成后会触发重组。切勿在后台
协程中调用 modelLoader.createModel*:Filament 调用必须在主线程运行,而 rememberModelInstance 会处理这一点。
AR(Android)
// build.gradle.kts
implementation("io.github.sceneview:arsceneview:4.62.0") // includes the 3D module
@Composable
fun ARScreen() {
var anchor by remember { mutableStateOf<Anchor?>(null) }
ARSceneView(
modifier = Modifier.fillMaxSize(),
planeRenderer = true,
onSessionUpdated = { _, frame ->
if (anchor == null) {
anchor = frame.getUpdatedPlanes()
.firstOrNull { it.type == Plane.Type.HORIZONTAL_UPWARD_FACING }
?.let { it.createAnchorOrNull(it.centerPose) }
}
}
) {
val helmet = rememberModelInstance(modelLoader, "models/helmet.glb")
anchor?.let { a ->
AnchorNode(anchor = a) {
helmet?.let { ModelNode(modelInstance = it, scaleToUnits = 0.5f) }
}
}
}
}
检测到平面 → 设置 anchor → Compose 触发重组 → 模型出现。**AR 状态就是 Kotlin
状态。**如需无需点击即可放置、自动贴合地面且支持手势的功能,请从
AutoPlacementScene 开始(参见 llms.txt)。
arsceneview 已声明 CAMERA 权限,并将 ARCore 标记为可选。AR
Optional 应用需要将 android.hardware.camera.ar 和 android.hardware.camera 声明为
<uses-feature … android:required="false" />;AR Required 应用则使用 tools:replace="android:value" 覆盖 ARCore 的值。两个代码片段都在
AR 清单文件一节中。
iOS / macOS / visionOS(SwiftUI)
Swift Package Manager:https://github.com/sceneview/sceneview.git,版本从 4.60.0 起。
import SwiftUI
import SceneViewSwift
struct ModelScreen: View {
@State private var model: ModelNode?
var body: some View {
SceneView { root in
if let model { root.addChild(model.entity) }
}
.contentID(model != nil) // re-run the builder once the model has loaded
.environment(.studio)
.cameraControls(.orbit)
.task { model = try? await ModelNode.load("helmet.usdz") }
}
}
除非 .contentID(_:) 发生变化,否则内容闭包只会运行一次:若没有这一行,场景显示后才完成加载的模型永远不会被添加。
Web
<canvas id="viewer" style="width: 100%; height: 480px"></canvas>
<script src="https://cdn.jsdelivr.net/gh/sceneview/[email protected]/website-static/js/filament/filament.js"></script>
<script src="https://cdn.jsdelivr.net/gh/sceneview/[email protected]/website-static/js/sceneview.js"></script>
<script> SceneView.modelViewer("viewer", "model.glb") </script>
Compose Multiplatform(Android · iOS · 桌面)
// commonMain dependencies
implementation("io.github.sceneview:sceneview-compose:4.62.0")
SceneViewer(model = ModelSource.Asset("models/helmet.glb"), modifier = Modifier.fillMaxSize())
这是一个查看器:加载、旋转、打光、点击;不支持 AR。功能范围和 iOS 的一次性设置见:
sceneview-compose/。
Flutter
// pubspec.yaml → flutter_sceneview: ^4.62.0
final controller = SceneViewController();
SceneView(
controller: controller,
onViewCreated: () => controller.loadModel(
const ModelNode(modelPath: 'models/helmet.glb'),
),
)
React Native
// npm install @sceneview-sdk/react-native
import { SceneView } from '@sceneview-sdk/react-native';
<SceneView
style={{ flex: 1 }}
modelNodes={[{ src: 'models/helmet.glb', position: [0, 0, -2] }]}
cameraControlMode="orbit"
/>
Flutter 和 React Native 通过桥接支持部分原生 API;具体支持内容见
flutter/ 和
react-native/。
你的 AI 助手
claude mcp add sceneview -- npx -y sceneview-mcp # Claude Code
codex mcp add sceneview -- npx -y sceneview-mcp # Codex
然后提问:*“为我的 Compose 屏幕添加一个 3D 模型查看器。”*其他客户端见 与 AI 搭配使用。
支持的平台
每一行都列出了一个已发布的软件包,以及一个如今即可打开的应用或页面,并附有实际截图。
| 平台 | 状态 | 安装 | 打开 | 截图 |
|---|---|---|---|---|
| Android | 已发布 · 稳定 | Maven Central | Google Play | ![]() |
| iOS | 已发布 · Alpha | Swift Package | App Store | ![]() |
| Web | 已发布 · Alpha | npm sceneview-web | 在线 Web 演示 | ![]() |
已发布表示已发布且可公开访问;第二个词表示 API 的成熟度。 下表中的其他平台会在有对应截图后加入本节。
平台
| 平台 | 渲染器 | 框架 | 状态 |
|---|---|---|---|
| Android | Filament | Jetpack Compose | 稳定 |
| Android TV | Filament | Compose TV | Alpha |
| iOS / macOS / visionOS | RealityKit | SwiftUI | Alpha |
| Web | Filament.js (WebGL2 / WASM) | JavaScript + Kotlin/JS | Alpha |
| Compose Multiplatform | Filament (Android、desktop) · RealityKit (iOS) | sceneview-compose | Alpha — 查看器子集 |
| Desktop (JVM) | Filament,通过 filament-kmp | Compose Desktop (sceneview-compose) | Alpha |
| Flutter | 各平台原生 | PlatformView | Alpha |
| React Native | 各平台原生 | Fabric | Alpha |
| AI 助手 | — | llms.txt、MCP 服务、skills | 稳定 |
安装
| 平台 | 坐标 |
|---|---|
| Android 3D | io.github.sceneview:sceneview:4.62.0 |
| Android AR | io.github.sceneview:arsceneview:4.62.0 |
| Compose Multiplatform | io.github.sceneview:sceneview-compose:4.62.0 |
| 仅 KMP 核心(数学、碰撞、物理) | io.github.sceneview:sceneview-core:4.62.0 |
| Apple (SPM) | https://github.com/sceneview/sceneview.git,从 4.60.0 开始 |
| Web,script 标签 | Web 中的两个 <script> 标签 |
| Web,打包工具 (Kotlin/JS) | npm install sceneview-web — 请参阅 SceneView Web |
| Flutter | pub.dev 上的 flutter_sceneview |
| React Native | npm 上的 @sceneview-sdk/react-native |
| AI 助手 | npx -y sceneview-mcp — 请参阅与 AI 配合使用 |
与 AI 配合使用
SDK 提供了助手编写 SceneView 代码所需的一切:
llms.txt— 完整的 API 参考,集中在一个文件中:可组合项、所有节点类型、线程规则和配方。其 Kotlin 代码片段会在 CI 中编译。可通过https://sceneview.github.io/llms.txt访问,供不支持 MCP 的工具使用。- 规则文件 —
AGENTS.md(Codex、Cursor、GitHub Copilot、Android Studio 中的 Gemini 等)、CLAUDE.md(Claude Code)、.github/copilot-instructions.md,以及适用于旧版 Cursor 的.cursorrules。 - MCP 服务 — 免费,无需 API 密钥。助手最常用的工具:
validate_code(运行前检查代码片段中已知的陷阱和未知符号;不检查参数名称)、get_node_reference(准确的节点签名,而非凭空编造的签名)、list_samples/get_sample(38 个可供参考的示例),以及get_setup/get_ar_setup(项目配置)。
MCP 配置
claude mcp add sceneview -- npx -y sceneview-mcp # Claude Code
codex mcp add sceneview -- npx -y sceneview-mcp # Codex
copilot mcp add sceneview -- npx -y sceneview-mcp # GitHub Copilot CLI
// Cursor (.cursor/mcp.json), Cline, JetBrains AI Assistant
{ "mcpServers": { "sceneview": { "command": "npx", "args": ["-y", "sceneview-mcp"] } } }
// VS Code (.vscode/mcp.json) uses the "servers" key instead
{ "servers": { "sceneview": { "type": "stdio", "command": "npx", "args": ["-y", "sceneview-mcp"] } } }
仅支持 HTTP 的客户端(Android Studio 中的 Gemini、ChatGPT)可使用托管端点
https://mcp.sceneview.dev/mcp,或运行 npx sceneview-mcp --http 搭建自己的服务。各客户端的
代码片段:sceneview.github.io/#ai-setup。已收录于
MCP Registry。
ChatGPT / Codex 插件
此仓库也是一个 OpenAI 插件:.codex-plugin/plugin.json 指向 agents/ 下的三个
技能(sceneview、sceneview-ios、sceneview-web)。在代码库检出目录中运行:
codex plugin marketplace add "$PWD" # absolute path — a relative one does not resolve
codex plugin add sceneview@sceneview-local
Codex 也会自动从 .agents/skills/ 发现这些技能。通过 HTTP 使用时,MCP 服务会在对话中提供一个内嵌的 view_3d_model 小组件,用于渲染公开的 GLB/glTF URL。插件简介和测试提示词:agents/OPENAI-PLUGIN.md。
Claude Code 插件
运行 /plugin marketplace add sceneview/claude-marketplace,然后运行 /plugin install sceneview@sceneview,
即可安装与 Codex 插件相同的三个技能以及 MCP 服务。用于处理此仓库的命令另有一个独立插件,即 sceneview-contrib@sceneview — 请参阅
sceneview/claude-marketplace。
垂直领域的 MCP 服务(Rerun AR 调试等)列于 MCP README。
深入了解 Android
3D 场景
SceneView 是一个可组合项,用于渲染 Filament 视口。节点是其中的可组合项。
val engine = rememberEngine()
val modelLoader = rememberModelLoader(engine)
val environmentLoader = rememberEnvironmentLoader(engine)
SceneView(
modifier = Modifier.fillMaxSize(),
engine = engine,
modelLoader = modelLoader,
environment = rememberEnvironment(environmentLoader) {
environmentLoader.createHDREnvironment("envs/studio.hdr")
?: createEnvironment(environmentLoader)
},
cameraManipulator = rememberCameraManipulator()
) {
// Model — async loaded, appears when ready
rememberModelInstance(modelLoader, "models/helmet.glb")?.let {
ModelNode(modelInstance = it, scaleToUnits = 1.0f, autoAnimate = true)
}
// Geometry — procedural shapes
CubeNode(size = Size(0.2f))
SphereNode(radius = 0.1f, position = Position(x = 0.5f))
// Nesting — same as Column { Row { } }
Node(position = Position(y = 1.0f)) {
LightNode(type = LightManager.Type.POINT, apply = { intensity(50_000f) })
CubeNode(size = Size(0.05f))
}
}
节点可组合项 — 3D 中有 27 个,AR 中另有 15 个
| 类别 | 节点 | 功能 |
|---|---|---|
| 模型 | ModelNode | 支持骨骼动画和变形动画的 glTF/GLB。设置 isEditable = true 可启用手势操作。 |
| 基本图形 | CubeNode · SphereNode · CylinderNode · ConeNode · TorusNode · CapsuleNode · TubeNode · PlaneNode | 程序化几何体,支持参数化尺寸和分段 |
| 曲线与形状 | LineNode · PathNode · ShapeNode | 单条线段、折线、拉伸的 2D 多边形 |
| 自定义几何体 | MeshNode | 使用你自己的 Filament VertexBuffer / IndexBuffer |
| 表面 | ImageNode · VideoNode · BillboardNode | PNG/JPG 平面、视频平面(MediaPlayer)、朝向摄像机的精灵 |
| 3D 文本 | TextNode | 世界空间文本标签,始终面向摄像机 |
| 在 3D 中使用 Compose | ViewNode | 将任意 Compose UI 渲染为 3D 表面,并支持完整的触摸交互 |
| 高斯泼溅 | SplatNode | 渲染高斯泼溅捕获结果 |
| 光照与天空 | LightNode · ReflectionProbeNode · DynamicSkyNode · FogNode | 太阳光/方向光/点光源/聚光灯、本地 IBL、随时间变化的天空、大气雾效 |
| 物理 | PhysicsNode | 简单的刚体模拟(重力、碰撞) |
| 摄像机 | CameraNode · SecondaryCamera | 主摄像机和画中画摄像机 |
| 组 | Node | 用于嵌套和变换继承的空枢轴 |
AR 场景
ARSceneView 是集成 ARCore 的 SceneView:摄像机会跟随现实世界中的追踪结果。请参阅上文的
AR 快速入门。
| 节点 | 功能 |
|---|---|
AnchorNode | 将节点固定到现实世界中的 ARCore Anchor |
HitResultNode · DepthHitResultNode | 根据每帧的命中测试(平面或深度)显示实时表面光标 |
PoseNode | 将节点放置在任意 ARCore Pose 位置 |
PlaneNode · ReticleNode | 渲染检测到的平面或放置瞄准标记 |
PointCloudNode · DepthMeshNode · SceneMeshNode | 特征点、深度网格、分类后的地理空间场景网格 |
AugmentedImageNode | 图像追踪 — 检测到的图像的姿态和 2D 范围 |
AugmentedFaceNode | 人脸网格叠加层(前置摄像机) |
CloudAnchorNode | 可跨设备持久化的锚点(托管 + 解析) |
StreetscapeGeometryNode | 地理空间 — 语义城市网格(建筑物、地形) |
TerrainAnchorNode | 地理空间 — 固定在给定纬度/经度地面上的锚点 |
RooftopAnchorNode | 地理空间 — 固定在建筑物屋顶上的锚点 |
| 功能 | API 接口 |
|---|---|
| 自动放置 | AutoPlacementScene + AutoPlacementModel — 自动贴合地面并支持手势,无需点击 |
| 平面/深度/即时放置 | ARSceneView(planeRenderer = …, depthMode = …, instantPlacementMode = …) |
| 地理空间(VPS) | 通过 Earth 会话使用 Streetscape + Terrain + Rooftop 锚点 |
| 云锚点 | CloudAnchorNode.host(ttlDays = N) + .resolve(id) |
| 增强人脸与图像 | AugmentedFaceNode、AugmentedImageDatabase、运行时添加图像 |
| 图像稳定(EIS) | ARSceneView(imageStabilizationMode = ImageStabilizationMode.EIS) |
| 摄像机曝光与对焦 | ARSceneView(sessionCameraConfig = …, focusMode = …, cameraExposure = …) |
| 录制与回放 | 使用 rememberARRecorder() 进行捕获,使用 ARSceneView(playbackDataset = file) 进行 1:1 回放 — 请参阅 AR 调试 |
| Rerun.io 实时调试 | rememberRerunBridge() 将姿态、平面和点云流式传输到 Rerun 查看器 |
| 权限流程 | ARPermissionHandler — 从 ComponentActivity 自动检测 |
功能
| 功能 | 提供的能力 | 所在位置 |
|---|---|---|
| 手势 | 拖动、双指缩放、双指旋转、抬升、轻触。可通过 isEditable 为每个节点单独启用。 | NodeGestureDelegate、OnGestureListener |
| 动画 | glTF 骨骼/变形动画,以及逐节点的弹簧、属性和平滑变换动画。 | ModelNode.playAnimation()、NodeAnimationDelegate |
| 物理 | 刚体动力学——重力、碰撞、冲量。纯 Kotlin Multiplatform,无需 JNI。 | PhysicsNode、sceneview-core |
| 碰撞与射线检测 | 射线与盒体/球体的相交检测、命中测试、视锥剔除。 | CollisionSystem、Ray、Box、Sphere |
| 程序化几何体 | 立方体/球体/圆柱体/圆锥体/圆环体/胶囊体生成器,以及从 2D 形状挤出几何体(Earcut + Delaunator)。 | sceneview-core 几何体与三角剖分 |
| HDR 环境 | 基于 IBL 的光照和来自 .hdr/.ktx 的天空盒。异步加载并支持响应式切换。 | EnvironmentLoader、rememberEnvironment |
| 自定义材质 | 带参数的 Filament .filamat 材质,以及内置的无光照/有光照/叠加变体。 | MaterialLoader |
| 后期处理 | 泛光、景深、SSAO、暗角、色彩分级、色调映射。 | View.bloomOptions、dynamicResolutionOptions、… |
| 3D 中的 Compose UI | 将任意 @Composable 作为纹理平面置于世界空间中。触摸事件会转发,因此 Button.onClick、涟漪效果和内部滚动均可正常工作。 | ViewNode + ViewNode.WindowManager |
| 多个摄像机 | 画中画、迷你地图、监控摄像机视图。 | SecondaryCamera |
| 响应式场景图 | 更改状态 → 树随之更新。无需命令式调用 parent.addChild()。 | SceneScope / ARSceneScope DSL |
模型格式
| 格式 | Android | Apple | Web |
|---|---|---|---|
| glTF / GLB | ✅ | — 转换为 USDZ(tools/convert-usdz.sh) | ✅ |
| USDZ / Reality / USD | — | ✅ RealityKit | — |
| STL(二进制 + ASCII) | ✅ 在内存中转换为 GLB | ✅ ModelIO,默认单位为毫米 | — |
| OBJ + MTL | ✅ 转换为 GLB,支持材质颜色 | ✅ ModelIO | — |
| PLY(二进制 + ASCII) | ✅ 转换为 GLB,支持顶点颜色 | ✅ ModelIO,支持顶点颜色 | — |
| 3MF | ✅ 转换为 GLB,遵循声明的单位 | ✅ SceneViewSwift 解析器,遵循声明的单位 | — |
Android 上没有按格式区分的 API:rememberModelInstance(modelLoader, path) 接受所有这些格式。在 Apple 平台上,RealityKit 不读取 glTF,因此 .gltf / .glb 刻意未加入 ModelFormat;USD/Reality 通过 RealityKit 加载,网格格式则通过 MeshAsset 加载。格式根据文件字节判断,而不是根据扩展名判断,因此,即使文件以 application/octet-stream 类型分享至应用且没有文件名,也仍可打开。转换器是 sceneview-core 中不依赖其他库的 Kotlin 代码。后续计划:
统一的 ModelFormat 入口 和
Web 上支持所有格式。详情:
模型格式。
Apple(iOS / macOS / visionOS)
基于 RealityKit 构建的原生 Swift Package,包含一组与 Android API 对应的节点。可同步构建的内容使用 @NodeBuilder 形式:
SceneView {
GeometryNode.cube(size: 0.1, color: .blue)
.position(.init(x: 0.5, y: 0, z: 0))
LightNode.directional(intensity: 1000)
}
.environment(.studio)
.cameraControls(.orbit)
iOS 上的 AR — 轻触检测到的平面以放置内容:
ARSceneView(
planeDetection: .horizontal,
onTapOnPlane: { position, arView in
let anchor = AnchorNode.world(position: position)
anchor.add(GeometryNode.cube(size: 0.1, color: .blue).entity)
arView.scene.addAnchor(anchor.entity)
}
)
节点 — ModelNode · GeometryNode(立方体/球体/圆柱体/圆锥体/圆环体/胶囊体/平面)·
LightNode · ImageNode · VideoNode · TextNode · ViewNode · BillboardNode · MeshNode ·
LineNode · PathNode · ShapeNode · PhysicsNode · ReflectionProbeNode · DynamicSkyNode ·
FogNode · CameraNode · AnchorNode · AugmentedImageNode · SceneReconstructionNode
(visionOS 场景网格)。此外还有 iOS RerunBridge,其线格式与 Android 相同。
完整指南:SceneViewSwift/README.md。
SceneView Web
两个 <script> 标签和一次调用(见上文 Web)。封装压缩后约为 24 KB;它驱动的
引擎是 Filament——与 Android SceneView 使用相同的渲染器,编译为 WebAssembly
(压缩后约为 2.3 MB)。
JavaScript API(script 标签):
SceneView.modelViewer(canvasOrId, url, options?)— 一体化查看器,支持环绕 + 自动旋转SceneView.create(canvasOrId, options?)— 空白查看器,可稍后加载模型viewer.loadModel(url)— 加载或替换 glTF/GLB 模型viewer.setAutoRotate(enabled)— 切换旋转viewer.dispose()— 释放资源
Kotlin/JS(仅限 sceneview-web npm 包) — 面向高级用户的 API:OrbitCameraController、几何体 DSL、响应式节点更新,以及通过 ARSceneView(immersive-ar、命中测试、锚点、光照估算)、VRSceneView(immersive-vr、控制器)和底层 WebXRSession 提供的 WebXR。该模块会构建 webpack 包,因此没有 Maven 坐标:
npm install sceneview-web
该包需要全局 Filament,且不包含 SceneView.modelViewer 脚本辅助函数。仅需共享核心功能(碰撞、数学、几何体、动画、物理——不含渲染器)的 Kotlin Multiplatform 项目,可使用
implementation("io.github.sceneview:sceneview-core-js:4.62.0")。
Sceneform 的 Compose 原生继任者
Google 于 2021 年归档了 Sceneform,且未推出第一方声明式 AR 渲染器。SceneView 源自持续维护的 Sceneform 社区分支:使用 ARCore 进行感知、Filament 进行渲染、Jetpack Compose 作为 API,并使用 glTF(.glb / .gltf),而非已弃用的 .sfb 格式。
从 Sceneform 转来?迁移指南按概念逐一对应(ArFragment → ARSceneView { }、ModelRenderable → rememberModelInstance 等)。
AR 调试
- 录制与回放 — 使用
rememberARRecorder()录制一次 ARCore 会话,然后在办公桌前通过ARSceneView(playbackDataset = file)按原样回放。请参阅docs/docs/ar-recording.md和 录制与回放演示。 - 托管式 Rerun 查看器 — 从 3D 扫描演示中导出扫描的 Rerun 录制文件,将
.rrd文件托管在以.rrd结尾的 https 地址上,然后打开https://sceneview.github.io/rerun/?url=<encoded-url>,即可在浏览器中逐帧浏览会话,无需本地安装。托管方必须允许跨域请求(CORS):公开 GitHub 仓库的raw.githubusercontent.com链接和 GitHub Pages 可以,GitHub release 附件则不行(截至 2026-10-13 已验证);R2 或 S3 存储桶在配置允许https://sceneview.github.io的 CORS 规则后可以使用。架构和 Kotlin API (RerunBridge.requestSaveAndShare) 见llms.txt中的 AR Debug — Rerun.io 部分。
架构
每个平台都使用其原生渲染器。共享逻辑由 Kotlin Multiplatform 实现。
sceneview-core (Kotlin Multiplatform)
├── math, collision, geometry, physics, animation, model-format converters
│
├── sceneview (Android) → Filament + Jetpack Compose
├── arsceneview (Android) → ARCore
├── sceneview-compose (KMP) → one SceneViewer for Android, iOS and desktop
├── SceneViewSwift (Apple) → RealityKit + SwiftUI
├── sceneview-web (Web) → Filament.js + WebXR
└── flutter/ · react-native/ → bridges to the native views
示例
| 示例 | 平台 | 运行 |
|---|---|---|
samples/android-demo | Android — 3D 和 AR | ./gradlew :samples:android-demo:assembleDebug |
samples/android-tv-demo | Android TV | ./gradlew :samples:android-tv-demo:assembleDebug |
samples/ios-demo | iOS — 3D 和 AR | 在 Xcode 中打开 |
samples/web-demo | Web | cd samples/web-demo && cp ../../website-static/js/sceneview.js site/js/sceneview.js && npx http-server site -p 8080 |
samples/desktop-demo | 桌面端(JDK 21+) | ./gradlew :samples:desktop-demo:run |
samples/flutter-demo | Flutter | cd samples/flutter-demo && flutter run |
samples/react-native-demo | React Native | 请参阅其 README |
使用 SceneView 构建
- 3D AR Model Viewer — 从任意应用或链接打开 3D 文件(GLB、glTF、STL、OBJ、PLY、3MF),并以实际尺寸在房间中查看。
- Will It Fit — 输入一件家具的尺寸,购买前即可查看它是否放得下。
链接
- 网站 · Playground · 文档
- Discord · 贡献指南 · 更新日志 · v2 → v3 迁移指南
赞助商
SceneView 免费且开源,由用户资助。
在 Open Collective 上赞助 · 或通过 GitHub Sponsors 赞助
评论
一个开放协议,规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话,MCP 服务负责提供工具、资源和提示模板,两者通过标准消息通信,同一个服务可以被不同客户端复用。



