用 React 在浏览器中实时操控 RealSense 相机librealsense REST API React Viewer 全指南【免费下载链接】librealsenseRealSense SDK项目地址: https://gitcode.com/GitHub_Trending/li/librealsenseRealSense React Viewer 是 librealsense 仓库中wrappers/rest-api子项目提供的一套现代化 Web 用户界面它以 FastAPI 编写的 REST API 为后端通过浏览器即可完成 RealSense 设备的发现、选型、复位、实时视频流查看WebRTC、相机参数调节、3D 点云可视化、IMU 曲线绘制以及 PLY/CSV 数据导出。读完本文你将能够独立搭建后端 REST API 前端 React Viewer的双进程开发环境理解其 WebRTC 与 Socket.IO 两条实时数据通道的原理掌握环境变量、AI 助手、自动化测试与 Tauri 桌面打包等进阶玩法并基于源码证据弄清楚每一个功能背后的实现链路。功能总览一个浏览器能做什么根据 react-viewer/README.md 的 Features 列表该 Viewer 覆盖了从设备管理到数据导出的完整闭环设备管理Device Management发现、选择并复位resetRealSense 设备支持多相机同时激活流查看Stream Viewing通过 WebRTC 实时查看 Depth、Color、Infrared 视频流相机控制Camera Controls调整 exposure曝光、gain增益、laser power激光功率等传感器选项3D 点云3D Point Cloud基于 Three.js 的交互式点云可视化IMU 可视化IMU Visualization实时绘制加速度计与陀螺仪曲线数据导出Export点云导出为 PLY 格式IMU 数据导出为 CSV 格式。此外Viewer 还内置了一个 AI 聊天助手Ask/Agent 两种模式与固件状态检查能力这些会在后文逐一展开。架构概览与技术栈整个 Viewer 采用前后端分离的架构二者通过 HTTP REST、WebSocketSocket.IO与 WebRTC 三种协议通信后端wrappers/rest-api下的 FastAPI 服务基于 pyrealsense2 封装 librealsense SDK暴露设备发现、传感器/选项控制、流控制、点云与 WebRTC 信令等接口服务端口默认8000交互式 API 文档位于/docs前端wrappers/rest-api/tools/react-viewer下的 React 18 TypeScript 应用开发端口默认3000。前端技术栈见 package.json包括技术用途React 18UI 框架TypeScript类型安全Vite 4构建与开发服务器TailwindCSS样式方案Zustand 4全局状态管理React Three Fiber drei Three.js3D 点云渲染RechartsIMU 数据图表Socket.IO Client实时元数据/点云数据通道WebRTC低延迟视频流从 vite.config.ts 可以看到构建层面的两个细节开发服务器把/api与/socket两个路径都代理到http://localhost:8000后者开启ws: true以支持 WebSocket 升级生产构建则通过manualChunks把 three.js 全家桶与 recharts 拆成独立 chunk避免单一 bundle 过大。快速开始双终端并行启动开发环境需要两个终端并行运行——一个跑 FastAPI 后端一个跑 Vite 前端各自只有一次性的安装步骤和一条常驻运行命令。以下命令默认从仓库根目录执行。终端 1启动后端 REST APIcd wrappers/rest-api python3 install.py # 一次性安装 requirements.txt 依赖如缺少 pyrealsense2 会从 PyPI 拉取 python3 main.py # 常驻在 http://localhost:8000 提供 APIinstall.py的安装逻辑在 wrappers/rest-api/README.md 中有明确说明它安装requirements.txt中列出的包并且仅当pyrealsense2尚不可导入时才从 PyPI 安装——如果你本地已经有源码编译、apt 或 pip 安装的pyrealsense2脚本会保持原样不动。后端也提供了start_server.shLinux/macOS作为启动入口。启动后可用浏览器访问http://localhost:8000/docs打开 Swagger UI交互式地探索全部端点这比任何接口文档都直观。终端 2启动前端 React Viewercd wrappers/rest-api/tools/react-viewer npm install # 一次性安装 Node 依赖 npm run dev # 常驻在 http://localhost:3000 提供 UI如果系统没有 npmsudo apt install npm打开浏览器两个终端都就绪后后端在:8000、前端在:3000访问 http://localhost:3000。开发模式下前端通过 Vite 代理自动把/api与/socket请求转发到后端用户无需关心跨域问题。前置条件Node.js 18 与 npm正在运行的 RealSense REST API 服务器即wrappers/rest-api目录见 rest-api/README.md一台可用的 RealSense 相机没有相机时 Viewer 也能启动主区域会提示 No Device Activated。可选环境变量与 AI 聊天助手Viewer 内置的 AI 聊天助手分为两种模式Ask 模式基于 Kapa.ai无需任何 API Key 即可使用Agent 模式需要配置大模型 API Key能根据对话内容直接生成相机参数建议如曝光、增益并允许一键应用。只有在想启用 Agent 模式时才需要配置环境变量。不配置.env文件 Viewer 也能正常运行只是聊天图标会显示 AI Assistant unavailable。配置步骤如下以wrappers/rest-api/tools/react-viewer为当前目录第 1 步进入 React viewer 目录.env.example与 dev server 都在这里cd wrappers/rest-api/tools/react-viewer第 2 步复制.env.example为.env同名内容不同文件名保证模板不被本地改动覆盖# Linux / macOS cp .env.example .env# Windows PowerShell Copy-Item .env.example .env:: Windows cmd.exe copy .env.example .env第 3 步从下面任一服务商获取 API KeyGroq推荐免费在 Groq 控制台创建 Key默认使用 Llama 3.3 70BOpenAI付费在 OpenAI 平台创建sk-...Key默认使用 GPT-4o-mini自托管 / OpenAI 兼容端点任何实现 OpenAI Chat Completions 协议的端点如 Ollama、LM Studio、vLLM 等。第 4 步编辑.env填入对应值。默认Groq只启用第一行VITE_GROQ_API_KEYgsk_xxxxxxxxxxxxxxxxxxxxxxxx若用 OpenAI改为取消对应行的注释并粘贴sk-...若用自定义提供商则设置VITE_LLM_API_URL、VITE_LLM_API_KEY与VITE_LLM_MODEL。当 FastAPI 部署在其他主机时还可通过VITE_API_URL覆盖后端地址。第 5 步重启npm run dev让 Vite 重新加载环境变量Vite 只在启动时读取.env*文件。.env已被 git 忽略密钥不会被提交进仓库。上述流程在 Windows、Linux、macOS 上完全一致只有第 1 步的复制命令不同。从源码看 AI 助手的实现src/api/chat.ts 展示了三种供应商的统一接入方式getActiveProvider()按VITE_GROQ_API_KEY→VITE_OPENAI_API_KEY→VITE_LLM_API_KEY VITE_LLM_API_URL的优先级探测可用 Key请求体统一走 OpenAI 兼容协议model、messages、temperature: 0.7、max_tokens: 2048并特殊处理了 429 限流读取Retry-After提示重试时间。助手能给出参数建议的关键在于 src/utils/chatPrompt.ts 的buildSystemPrompt会把当前设备/传感器/选项状态注入系统提示词再通过parseProposedSettings从回复中解析出结构化设置项供用户在 SettingsPreview.tsx 里预览并一键应用。项目结构解读Viewer 的目录结构来自 README如下react-viewer/ ├── src/ # React 应用TypeScript │ ├── api/ # 后端客户端REST、Socket.IO、WebRTC、chat │ ├── components/ # React 组件 │ │ └── ChatBot/ # AI 聊天 UIAsk Agent 两种模式 │ ├── store/ # Zustand 状态管理 │ └── utils/ # 工具函数如 AI prompt 构建器 ├── src-tauri/ # Tauri 桌面桥接层Rust │ ├── src/ # Rust 源码 │ ├── icons/ # 应用图标复用 common/res │ └── resources/ ├── public/ # 静态资源favicon、logo ├── scripts/ # 构建辅助脚本如 bundle-for-prod └── tests/ # Vitest 单元测试 Playwright E2E 测试 ├── unit/ ├── e2e/ ├── mocks/ # MSW handlers fixtures ├── setup/ # Vitest 全局 setup └── utils/ # 测试工具对照 src/App.tsx 可以看到整体 UI 布局左侧w-80宽的DevicePanel侧边栏负责设备选择与控制主区域根据viewMode在 2DStreamViewer与 3DPointCloudViewer之间切换底部可折叠的IMUViewer绘制传感器曲线右下角固定一个连接状态徽标绿色 Connected / 红色 Disconnected另有ApiDiagnostics组件在连接异常时展示诊断信息。值得注意的源码细节多相机支持src/store/index.ts 中以deviceStates: Recordstring, DeviceState按device_id维护每台设备的独立状态传感器、选项、流配置、固件信息并支持仅有一台设备且用户未手动操作时自动激活的便捷行为流配置自动推导buildStreamConfigs会遍历传感器的supported_stream_profiles自动生成以 depth/color 为默认启用的流配置buildSensorConfigs则取各 profile 分辨率与帧率的交集并优先选择 30fps、其次 15fps两种流控模式状态机区分pipeline整机级 start/stop与sensor按传感器细粒度启停两种 streamingMode二者互斥——使用 sensor API 前必须先停止 pipeline 流。API 集成前端如何与 FastAPI 对话Viewer 通过 src/api/client.ts 中的ApiClient类统一封装 HTTP 调用所有端点以/api/v1/为前缀。该文件还处理了两种运行环境的差异Tauri 桌面应用直接连http://localhost:8000/api/v1浏览器环境则使用相对路径/api/v1开发时由 Vite 代理、生产时由后端托管。REST 端点清单方法路径用途GET/api/v1/health健康检查含 SDK 版本GET/api/v1/devices/列出已连接设备GET/api/v1/devices/{id}/获取单台设备详情GET/api/v1/devices/{id}/status固件状态当前/推荐版本POST/api/v1/devices/{id}/reset/远程硬件复位GET/api/v1/devices/{id}/sensors/获取设备传感器列表GET/api/v1/devices/{id}/sensors/{sid}/传感器详情与支持的流 profileGET/api/v1/devices/{id}/sensors/{sid}/options/列出传感器选项曝光、增益等PUT/api/v1/devices/{id}/sensors/{sid}/options/{oid}/更新可写选项值POST/api/v1/devices/{id}/stream/start/按分辨率/格式/FPS 启动流POST/api/v1/devices/{id}/stream/stop/停止流GET/api/v1/devices/{id}/stream/status/查询流状态GET/api/v1/devices/{id}/stream/depth-at-pixel/查询指定像素深度GET/api/v1/devices/{id}/stream/depth-range/查询深度范围POST/api/v1/devices/{id}/sensors/{sid}/start按传感器启动流支持多 profilePOST/api/v1/devices/{id}/sensors/{sid}/stop按传感器停止流GET/api/v1/devices/{id}/sensors/{sid}/status传感器流状态POST/api/v1/devices/{id}/sensors/batch/start批量启动多个传感器POST/api/v1/devices/{id}/sensors/batch/stop批量停止GET/api/v1/devices/{id}/sensors/batch/status批量状态POST/api/v1/devices/{id}/point_cloud/activate/激活点云输出POST/api/v1/devices/{id}/point_cloud/deactivate/停用点云输出GET/api/v1/devices/{id}/point_cloud/status/点云开关状态POST/api/v1/webrtc/offer/创建 WebRTC 会话SDP offerPOST/api/v1/webrtc/answer/提交浏览器 answerPOST/api/v1/webrtc/ice-candidates/上报本地 ICE candidateGET/api/v1/webrtc/sessions/{id}/ice-candidates/拉取对端 ICE candidateGET/api/v1/webrtc/sessions/{id}/会话状态DELETE/api/v1/webrtc/sessions/{id}/关闭会话实际端点的 FastAPI 实现位于 wrappers/rest-api/app/api/endpoints/devices.py、sensors.py、options.py、streams.py、sensor_streaming.py、point_cloud.py、webrtc.py、firmware.py路由前缀由 router.py 统一注册这也是上文/docs里可交互文档的数据来源。实时数据通道WebRTC 视频流与 Socket.IO 元数据视频帧与元数据不走 REST而是走两条专门的低延迟通道。WebRTC浏览器直接收视频src/api/webrtc.ts 的WebRTCHandler完整实现了服务端发起 offer的握手流程创建RTCPeerConnection配置 Google 公共 STUN 服务器stun:stun.l.google.com:19302等为每种请求的流类型depth/color/infraredaddTransceiver(video, { direction: recvonly })即纯接收方向向POST /api/v1/webrtc/offer/提交{ device_id, stream_types }拿到服务端生成的 offer 与session_idsetRemoteDescription后createAnswer并回传完成 SDP 协商ICE 候选交换本地 candidate 通过POST /webrtc/ice-candidates/上报远端 candidate 则每 500ms 轮询GET /webrtc/sessions/{id}/ice-candidates/拉取直到iceConnectionState离开new/checking状态。Socket.IO帧元数据与点云src/api/socket.ts 的SocketService连接路径为/socket与 Vite 代理配置一致开发模式直连http://localhost:8000生产模式用当前页面 origin传输层从 polling 自动升级到 websocket并配置了最多 10 次、指数退避1s → 5s的重连策略。连接后监听两个核心事件welcome服务端握手消息metadata_update携带帧时间戳、帧号等元数据MetadataUpdate由 Zustand store 的updateMetadata写入对应设备状态。点云数据同样经 Socket.IO 下发。根据 wrappers/rest-api/README.md 的解码说明客户端需要把 Base64 字符串解码为Uint8Array再按字节视图解释为Float32Array——这里的关键假设是后端 NumPy 数组使用float32若为 float64 则改用Float64Array。Float32Array构造器只是对底层ArrayBuffer建立视图、不复制数据因此可直接获得vertices顶点数组用于渲染。IMU 原始数据也通过同一 Socket.IO 通道传播。点云与 IMU 可视化主区域根据viewMode切换 2D/3DPointCloudViewer.tsx 基于 React Three Fiber drei 渲染交互式点云配合 DepthLegend.tsx 用色条映射深度值开启点云后顶点数据经 Socket.IO 持续更新到pointCloudVerticesIMUViewer.tsx 使用 Recharts 实时绘制加速度计accel与陀螺仪gyro三轴曲线历史数据保存在 store 的imuHistory中maxIMUHistoryLength限制长度防止内存膨胀。导出功能方面点云以 PLY 格式导出见 CodeExport.tsx 等组件的导出实现IMU 数据导出为 CSV方便离线分析。可用脚本速查package.json中定义的脚本命令说明npm run dev启动带热重载的开发服务器npm run build生产构建先tsc类型检查再 Vite 打包npm run preview本地预览生产构建npm run lint运行 ESLint--max-warnings 0严格模式npm run bundle把构建产物复制到 FastAPI 静态目录npm test运行 Vitest 单元与集成测试npm run test:watch监听模式测试npm run test:coverage生成 HTML/LCOV 覆盖率报告npm run test:e2e运行 Playwright E2Eheadlessnpm run tauri:devTauri 桌面开发模式npm run tauri:buildTauri 桌面打包测试体系Vitest Playwright MSW测试按三层组织详见 tests/README.md 与 tests/INSTALLATION.md单元/集成测试Vitest React Testing Library jsdom如 Header.test.tsx、DevicePanel.test.tsxAPI MockMSWMock Service Worker在 tests/mocks/api-handlers.ts 中模拟后端端点fixtures 位于 tests/mocks/fixtures/E2EPlaywrightsmoke.spec.ts 冒烟测试与 real-device.spec.ts 真实设备测试首次运行需npx playwright install下载浏览器。常用命令npm test # 单元测试 npm run test:coverage # 覆盖率打开 coverage/index.html 查看 npm run test:e2e # E2E需 dev server 与后端都在运行 npx playwright install # 首次 E2E 环境准备后端侧也可在wrappers/rest-api目录运行python run_tests.py同时执行 pytest 与前端 Vitest 套件--backend/--frontend可单独执行见 rest-api/README.md。桌面应用用 Tauri 打包跨平台安装程序Viewer 通过 src-tauriRust把 React UI 与 FastAPI 后端一起打包成独立桌面应用支持 Windows、macOS、Linux并产出平台原生安装包。Tauri 内部架构、子进程管理与配置参考见 DESKTOP_BUILD.md其中包含开发模式的热重载工作流说明。生产构建一键构建脚本会依次执行三个阶段PyInstaller打包 FastAPI 后端→ Vite构建 React→ Tauri bundle生成安装包。Linux / macOScd wrappers/rest-api/tools/react-viewer chmod x build-all.sh ./build-all.sh # 构建全部 ./build-all.sh --clean # 清理后重建WindowsPowerShellcd wrappers\rest-api\tools\react-viewer .\build-all.ps1 # 构建全部 .\build-all.ps1 -Clean # 清理后重建两个脚本在仓库根目录下产出build/rest-api-dist/realsense_api/— FastAPI 后端的 PyInstaller 打包结果build/tauri-target/release/bundle/— 原生安装包Windows.msi.exeNSISLinux.deb.AppImagemacOS.dmg前置条件Node.js 18、Python 3.8、Rust 1.56通过 rustup 安装、PyInstallerpip install pyinstaller。Linux 发行版支持情况Tauri 1.5当前项目使用 Tauri 1.5它链接 WebKitGTK4.0Ubuntu LTS代号桌面构建Tauri20.04Focal✅ 原生构建22.04Jammy✅ 原生构建推荐24.04Noble❌ Tauri 1.5 不支持4.0 头文件已移除symlink hack 能过 pkg-config但 wry crate 会在编译 4.1 API 时失败26.04Resolute❌ 4.0 软件包不再发布Ubuntu 24.04 / 26.04 用户注意桌面安装包构建build-all.sh目前在这些发行版上无法产出可用的二进制。请改用上文快速开始中的双终端开发模式——它在所有 Ubuntu 版本上都能工作可以获得完整的本地 ViewerFastAPI 在:8000、React 在:3000浏览器中只是没有打包好的.AppImage/.deb。迁移到 Tauri 2是规划中的改进也是解除 Ubuntu 24.04 桌面构建限制的路径Tauri 2 链接 WebKitGTK 4.1可在这类发行版上原生构建。迁移属于中等工作量有经验的开发者约半天升级tauri/tauri-build/ wry运行npm run tauri migrate自动重写约 70% 的tauri.conf.json与 JS API 导入再修复剩余编译错误并回归测试 FastAPI 子进程启动。Linux 构建依赖Rust 打包器需要 WebKitGTK 等开发头文件Debian/Ubuntusudo apt install -y \ libwebkit2gtk-4.0-dev libgtk-3-dev libsoup2.4-dev \ libayatana-appindicator3-dev librsvg2-dev libssl-dev \ pkg-config build-essential常见构建错误若build-all.sh报failed to get cargo metadata或cargo: command not found说明cargo不在PATH上。安装 Rust 后在当前 shell 启用source $HOME/.cargo/env永久生效则把同一行加入~/.bashrc。构建脚本在检测到cargo缺失时也会自动尝试这一操作。生产部署方案一纯 Web 浏览器模式单独启动 FastAPI 后端将 React 应用部署到任意静态托管Vercel、Netlify 等通过环境变量把 API URL 指向你的后端服务器VITE_API_URL。方案二合并部署FastAPI 托管 React 静态文件构建前端并复制产物npm run build npm run bundle第二步会把构建产物复制到../rest-api/static/由 scripts/bundle-for-prod.js 实现。在wrappers/rest-api/main.py中追加静态文件挂载from fastapi.staticfiles import StaticFiles # Add at the end, after all API routes app.mount(/, StaticFiles(directorystatic, htmlTrue), namestatic)启动 FastAPI它将同时提供 API 与 UIpython main.py这样只需一个进程、一个端口/api/v1提供接口、其余路径回退到 React 的index.html。常见问题与排障结合源码与文档整理几个高频问题的排查思路页面显示 No Device Activated侧边栏DevicePanel列表为空或未激活。确认后端已启动curl http://localhost:8000/api/v1/health应返回status与服务/版本信息、相机已连接仅一台设备且未手动操作时前端会自动激活。Socket.IO 一直断开检查:8000是否可达。开发模式下socket.ts直连http://localhost:8000而client.ts中的连接则经 Vite 代理/socket需ws: truevite.config.ts 已配置生产环境需确认后端 CORS 与静态托管配置。WebRTC 视频不显示查看控制台 ICE 状态。webrtc.ts使用公共 Google STUN纯内网环境可能需要额外配置 TURN同时确认流已通过 REST 端点启动stream/start或 sensor 级 startWebRTC 只是传输通道而非流开关。AI 助手显示 unavailable未配置 Key 或端点不可达。chat.ts的checkChatAvailability会先探测modelsEndpoint连通性配置后记得重启 dev server因为 Vite 只在启动时读取.env*。AI 回复被限流429chat.ts会读取Retry-After头提示等待秒数免费层尤其需要注意频率。E2E 测试连不上确保npm run dev在运行、后端在http://localhost:8000可用tests/INSTALLATION.md 有完整说明。MSW 控制台警告 unhandled request新加的 API 端点需要在 tests/mocks/api-handlers.ts 中补充 handler。小结RealSense React Viewer 用一套现代 Web 技术栈React 18 TypeScript Vite Zustand Three.js Socket.IO WebRTC Tauri把 librealsense 的能力完整搬进了浏览器与桌面REST 负责设备/传感器/选项/流控制WebRTC 承载低延迟视频Socket.IO 推送元数据与点云Zustand 统一管理多相机状态AI 助手则把参数调节从手动查找变成对话生成一键应用。无论是开发期双终端模式还是生产期合并部署都能在数分钟内跑通测试体系Vitest Playwright MSW与 Tauri 打包脚本则让它在工程化上同样完备。继续深入可以参考 react-viewer 源码、后端端点实现 与 rest-api 总览。【免费下载链接】librealsenseRealSense SDK项目地址: https://gitcode.com/GitHub_Trending/li/librealsense创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 用 React 在浏览器中实时操控 RealSense 相机：librealsense REST API React Viewer 全指南
用 React 在浏览器中实时操控 RealSense 相机librealsense REST API React Viewer 全指南【免费下载链接】librealsenseRealSense SDK项目地址: https://gitcode.com/GitHub_Trending/li/librealsenseRealSense React Viewer 是 librealsense 仓库中wrappers/rest-api子项目提供的一套现代化 Web 用户界面它以 FastAPI 编写的 REST API 为后端通过浏览器即可完成 RealSense 设备的发现、选型、复位、实时视频流查看WebRTC、相机参数调节、3D 点云可视化、IMU 曲线绘制以及 PLY/CSV 数据导出。读完本文你将能够独立搭建后端 REST API 前端 React Viewer的双进程开发环境理解其 WebRTC 与 Socket.IO 两条实时数据通道的原理掌握环境变量、AI 助手、自动化测试与 Tauri 桌面打包等进阶玩法并基于源码证据弄清楚每一个功能背后的实现链路。功能总览一个浏览器能做什么根据 react-viewer/README.md 的 Features 列表该 Viewer 覆盖了从设备管理到数据导出的完整闭环设备管理Device Management发现、选择并复位resetRealSense 设备支持多相机同时激活流查看Stream Viewing通过 WebRTC 实时查看 Depth、Color、Infrared 视频流相机控制Camera Controls调整 exposure曝光、gain增益、laser power激光功率等传感器选项3D 点云3D Point Cloud基于 Three.js 的交互式点云可视化IMU 可视化IMU Visualization实时绘制加速度计与陀螺仪曲线数据导出Export点云导出为 PLY 格式IMU 数据导出为 CSV 格式。此外Viewer 还内置了一个 AI 聊天助手Ask/Agent 两种模式与固件状态检查能力这些会在后文逐一展开。架构概览与技术栈整个 Viewer 采用前后端分离的架构二者通过 HTTP REST、WebSocketSocket.IO与 WebRTC 三种协议通信后端wrappers/rest-api下的 FastAPI 服务基于 pyrealsense2 封装 librealsense SDK暴露设备发现、传感器/选项控制、流控制、点云与 WebRTC 信令等接口服务端口默认8000交互式 API 文档位于/docs前端wrappers/rest-api/tools/react-viewer下的 React 18 TypeScript 应用开发端口默认3000。前端技术栈见 package.json包括技术用途React 18UI 框架TypeScript类型安全Vite 4构建与开发服务器TailwindCSS样式方案Zustand 4全局状态管理React Three Fiber drei Three.js3D 点云渲染RechartsIMU 数据图表Socket.IO Client实时元数据/点云数据通道WebRTC低延迟视频流从 vite.config.ts 可以看到构建层面的两个细节开发服务器把/api与/socket两个路径都代理到http://localhost:8000后者开启ws: true以支持 WebSocket 升级生产构建则通过manualChunks把 three.js 全家桶与 recharts 拆成独立 chunk避免单一 bundle 过大。快速开始双终端并行启动开发环境需要两个终端并行运行——一个跑 FastAPI 后端一个跑 Vite 前端各自只有一次性的安装步骤和一条常驻运行命令。以下命令默认从仓库根目录执行。终端 1启动后端 REST APIcd wrappers/rest-api python3 install.py # 一次性安装 requirements.txt 依赖如缺少 pyrealsense2 会从 PyPI 拉取 python3 main.py # 常驻在 http://localhost:8000 提供 APIinstall.py的安装逻辑在 wrappers/rest-api/README.md 中有明确说明它安装requirements.txt中列出的包并且仅当pyrealsense2尚不可导入时才从 PyPI 安装——如果你本地已经有源码编译、apt 或 pip 安装的pyrealsense2脚本会保持原样不动。后端也提供了start_server.shLinux/macOS作为启动入口。启动后可用浏览器访问http://localhost:8000/docs打开 Swagger UI交互式地探索全部端点这比任何接口文档都直观。终端 2启动前端 React Viewercd wrappers/rest-api/tools/react-viewer npm install # 一次性安装 Node 依赖 npm run dev # 常驻在 http://localhost:3000 提供 UI如果系统没有 npmsudo apt install npm打开浏览器两个终端都就绪后后端在:8000、前端在:3000访问 http://localhost:3000。开发模式下前端通过 Vite 代理自动把/api与/socket请求转发到后端用户无需关心跨域问题。前置条件Node.js 18 与 npm正在运行的 RealSense REST API 服务器即wrappers/rest-api目录见 rest-api/README.md一台可用的 RealSense 相机没有相机时 Viewer 也能启动主区域会提示 No Device Activated。可选环境变量与 AI 聊天助手Viewer 内置的 AI 聊天助手分为两种模式Ask 模式基于 Kapa.ai无需任何 API Key 即可使用Agent 模式需要配置大模型 API Key能根据对话内容直接生成相机参数建议如曝光、增益并允许一键应用。只有在想启用 Agent 模式时才需要配置环境变量。不配置.env文件 Viewer 也能正常运行只是聊天图标会显示 AI Assistant unavailable。配置步骤如下以wrappers/rest-api/tools/react-viewer为当前目录第 1 步进入 React viewer 目录.env.example与 dev server 都在这里cd wrappers/rest-api/tools/react-viewer第 2 步复制.env.example为.env同名内容不同文件名保证模板不被本地改动覆盖# Linux / macOS cp .env.example .env# Windows PowerShell Copy-Item .env.example .env:: Windows cmd.exe copy .env.example .env第 3 步从下面任一服务商获取 API KeyGroq推荐免费在 Groq 控制台创建 Key默认使用 Llama 3.3 70BOpenAI付费在 OpenAI 平台创建sk-...Key默认使用 GPT-4o-mini自托管 / OpenAI 兼容端点任何实现 OpenAI Chat Completions 协议的端点如 Ollama、LM Studio、vLLM 等。第 4 步编辑.env填入对应值。默认Groq只启用第一行VITE_GROQ_API_KEYgsk_xxxxxxxxxxxxxxxxxxxxxxxx若用 OpenAI改为取消对应行的注释并粘贴sk-...若用自定义提供商则设置VITE_LLM_API_URL、VITE_LLM_API_KEY与VITE_LLM_MODEL。当 FastAPI 部署在其他主机时还可通过VITE_API_URL覆盖后端地址。第 5 步重启npm run dev让 Vite 重新加载环境变量Vite 只在启动时读取.env*文件。.env已被 git 忽略密钥不会被提交进仓库。上述流程在 Windows、Linux、macOS 上完全一致只有第 1 步的复制命令不同。从源码看 AI 助手的实现src/api/chat.ts 展示了三种供应商的统一接入方式getActiveProvider()按VITE_GROQ_API_KEY→VITE_OPENAI_API_KEY→VITE_LLM_API_KEY VITE_LLM_API_URL的优先级探测可用 Key请求体统一走 OpenAI 兼容协议model、messages、temperature: 0.7、max_tokens: 2048并特殊处理了 429 限流读取Retry-After提示重试时间。助手能给出参数建议的关键在于 src/utils/chatPrompt.ts 的buildSystemPrompt会把当前设备/传感器/选项状态注入系统提示词再通过parseProposedSettings从回复中解析出结构化设置项供用户在 SettingsPreview.tsx 里预览并一键应用。项目结构解读Viewer 的目录结构来自 README如下react-viewer/ ├── src/ # React 应用TypeScript │ ├── api/ # 后端客户端REST、Socket.IO、WebRTC、chat │ ├── components/ # React 组件 │ │ └── ChatBot/ # AI 聊天 UIAsk Agent 两种模式 │ ├── store/ # Zustand 状态管理 │ └── utils/ # 工具函数如 AI prompt 构建器 ├── src-tauri/ # Tauri 桌面桥接层Rust │ ├── src/ # Rust 源码 │ ├── icons/ # 应用图标复用 common/res │ └── resources/ ├── public/ # 静态资源favicon、logo ├── scripts/ # 构建辅助脚本如 bundle-for-prod └── tests/ # Vitest 单元测试 Playwright E2E 测试 ├── unit/ ├── e2e/ ├── mocks/ # MSW handlers fixtures ├── setup/ # Vitest 全局 setup └── utils/ # 测试工具对照 src/App.tsx 可以看到整体 UI 布局左侧w-80宽的DevicePanel侧边栏负责设备选择与控制主区域根据viewMode在 2DStreamViewer与 3DPointCloudViewer之间切换底部可折叠的IMUViewer绘制传感器曲线右下角固定一个连接状态徽标绿色 Connected / 红色 Disconnected另有ApiDiagnostics组件在连接异常时展示诊断信息。值得注意的源码细节多相机支持src/store/index.ts 中以deviceStates: Recordstring, DeviceState按device_id维护每台设备的独立状态传感器、选项、流配置、固件信息并支持仅有一台设备且用户未手动操作时自动激活的便捷行为流配置自动推导buildStreamConfigs会遍历传感器的supported_stream_profiles自动生成以 depth/color 为默认启用的流配置buildSensorConfigs则取各 profile 分辨率与帧率的交集并优先选择 30fps、其次 15fps两种流控模式状态机区分pipeline整机级 start/stop与sensor按传感器细粒度启停两种 streamingMode二者互斥——使用 sensor API 前必须先停止 pipeline 流。API 集成前端如何与 FastAPI 对话Viewer 通过 src/api/client.ts 中的ApiClient类统一封装 HTTP 调用所有端点以/api/v1/为前缀。该文件还处理了两种运行环境的差异Tauri 桌面应用直接连http://localhost:8000/api/v1浏览器环境则使用相对路径/api/v1开发时由 Vite 代理、生产时由后端托管。REST 端点清单方法路径用途GET/api/v1/health健康检查含 SDK 版本GET/api/v1/devices/列出已连接设备GET/api/v1/devices/{id}/获取单台设备详情GET/api/v1/devices/{id}/status固件状态当前/推荐版本POST/api/v1/devices/{id}/reset/远程硬件复位GET/api/v1/devices/{id}/sensors/获取设备传感器列表GET/api/v1/devices/{id}/sensors/{sid}/传感器详情与支持的流 profileGET/api/v1/devices/{id}/sensors/{sid}/options/列出传感器选项曝光、增益等PUT/api/v1/devices/{id}/sensors/{sid}/options/{oid}/更新可写选项值POST/api/v1/devices/{id}/stream/start/按分辨率/格式/FPS 启动流POST/api/v1/devices/{id}/stream/stop/停止流GET/api/v1/devices/{id}/stream/status/查询流状态GET/api/v1/devices/{id}/stream/depth-at-pixel/查询指定像素深度GET/api/v1/devices/{id}/stream/depth-range/查询深度范围POST/api/v1/devices/{id}/sensors/{sid}/start按传感器启动流支持多 profilePOST/api/v1/devices/{id}/sensors/{sid}/stop按传感器停止流GET/api/v1/devices/{id}/sensors/{sid}/status传感器流状态POST/api/v1/devices/{id}/sensors/batch/start批量启动多个传感器POST/api/v1/devices/{id}/sensors/batch/stop批量停止GET/api/v1/devices/{id}/sensors/batch/status批量状态POST/api/v1/devices/{id}/point_cloud/activate/激活点云输出POST/api/v1/devices/{id}/point_cloud/deactivate/停用点云输出GET/api/v1/devices/{id}/point_cloud/status/点云开关状态POST/api/v1/webrtc/offer/创建 WebRTC 会话SDP offerPOST/api/v1/webrtc/answer/提交浏览器 answerPOST/api/v1/webrtc/ice-candidates/上报本地 ICE candidateGET/api/v1/webrtc/sessions/{id}/ice-candidates/拉取对端 ICE candidateGET/api/v1/webrtc/sessions/{id}/会话状态DELETE/api/v1/webrtc/sessions/{id}/关闭会话实际端点的 FastAPI 实现位于 wrappers/rest-api/app/api/endpoints/devices.py、sensors.py、options.py、streams.py、sensor_streaming.py、point_cloud.py、webrtc.py、firmware.py路由前缀由 router.py 统一注册这也是上文/docs里可交互文档的数据来源。实时数据通道WebRTC 视频流与 Socket.IO 元数据视频帧与元数据不走 REST而是走两条专门的低延迟通道。WebRTC浏览器直接收视频src/api/webrtc.ts 的WebRTCHandler完整实现了服务端发起 offer的握手流程创建RTCPeerConnection配置 Google 公共 STUN 服务器stun:stun.l.google.com:19302等为每种请求的流类型depth/color/infraredaddTransceiver(video, { direction: recvonly })即纯接收方向向POST /api/v1/webrtc/offer/提交{ device_id, stream_types }拿到服务端生成的 offer 与session_idsetRemoteDescription后createAnswer并回传完成 SDP 协商ICE 候选交换本地 candidate 通过POST /webrtc/ice-candidates/上报远端 candidate 则每 500ms 轮询GET /webrtc/sessions/{id}/ice-candidates/拉取直到iceConnectionState离开new/checking状态。Socket.IO帧元数据与点云src/api/socket.ts 的SocketService连接路径为/socket与 Vite 代理配置一致开发模式直连http://localhost:8000生产模式用当前页面 origin传输层从 polling 自动升级到 websocket并配置了最多 10 次、指数退避1s → 5s的重连策略。连接后监听两个核心事件welcome服务端握手消息metadata_update携带帧时间戳、帧号等元数据MetadataUpdate由 Zustand store 的updateMetadata写入对应设备状态。点云数据同样经 Socket.IO 下发。根据 wrappers/rest-api/README.md 的解码说明客户端需要把 Base64 字符串解码为Uint8Array再按字节视图解释为Float32Array——这里的关键假设是后端 NumPy 数组使用float32若为 float64 则改用Float64Array。Float32Array构造器只是对底层ArrayBuffer建立视图、不复制数据因此可直接获得vertices顶点数组用于渲染。IMU 原始数据也通过同一 Socket.IO 通道传播。点云与 IMU 可视化主区域根据viewMode切换 2D/3DPointCloudViewer.tsx 基于 React Three Fiber drei 渲染交互式点云配合 DepthLegend.tsx 用色条映射深度值开启点云后顶点数据经 Socket.IO 持续更新到pointCloudVerticesIMUViewer.tsx 使用 Recharts 实时绘制加速度计accel与陀螺仪gyro三轴曲线历史数据保存在 store 的imuHistory中maxIMUHistoryLength限制长度防止内存膨胀。导出功能方面点云以 PLY 格式导出见 CodeExport.tsx 等组件的导出实现IMU 数据导出为 CSV方便离线分析。可用脚本速查package.json中定义的脚本命令说明npm run dev启动带热重载的开发服务器npm run build生产构建先tsc类型检查再 Vite 打包npm run preview本地预览生产构建npm run lint运行 ESLint--max-warnings 0严格模式npm run bundle把构建产物复制到 FastAPI 静态目录npm test运行 Vitest 单元与集成测试npm run test:watch监听模式测试npm run test:coverage生成 HTML/LCOV 覆盖率报告npm run test:e2e运行 Playwright E2Eheadlessnpm run tauri:devTauri 桌面开发模式npm run tauri:buildTauri 桌面打包测试体系Vitest Playwright MSW测试按三层组织详见 tests/README.md 与 tests/INSTALLATION.md单元/集成测试Vitest React Testing Library jsdom如 Header.test.tsx、DevicePanel.test.tsxAPI MockMSWMock Service Worker在 tests/mocks/api-handlers.ts 中模拟后端端点fixtures 位于 tests/mocks/fixtures/E2EPlaywrightsmoke.spec.ts 冒烟测试与 real-device.spec.ts 真实设备测试首次运行需npx playwright install下载浏览器。常用命令npm test # 单元测试 npm run test:coverage # 覆盖率打开 coverage/index.html 查看 npm run test:e2e # E2E需 dev server 与后端都在运行 npx playwright install # 首次 E2E 环境准备后端侧也可在wrappers/rest-api目录运行python run_tests.py同时执行 pytest 与前端 Vitest 套件--backend/--frontend可单独执行见 rest-api/README.md。桌面应用用 Tauri 打包跨平台安装程序Viewer 通过 src-tauriRust把 React UI 与 FastAPI 后端一起打包成独立桌面应用支持 Windows、macOS、Linux并产出平台原生安装包。Tauri 内部架构、子进程管理与配置参考见 DESKTOP_BUILD.md其中包含开发模式的热重载工作流说明。生产构建一键构建脚本会依次执行三个阶段PyInstaller打包 FastAPI 后端→ Vite构建 React→ Tauri bundle生成安装包。Linux / macOScd wrappers/rest-api/tools/react-viewer chmod x build-all.sh ./build-all.sh # 构建全部 ./build-all.sh --clean # 清理后重建WindowsPowerShellcd wrappers\rest-api\tools\react-viewer .\build-all.ps1 # 构建全部 .\build-all.ps1 -Clean # 清理后重建两个脚本在仓库根目录下产出build/rest-api-dist/realsense_api/— FastAPI 后端的 PyInstaller 打包结果build/tauri-target/release/bundle/— 原生安装包Windows.msi.exeNSISLinux.deb.AppImagemacOS.dmg前置条件Node.js 18、Python 3.8、Rust 1.56通过 rustup 安装、PyInstallerpip install pyinstaller。Linux 发行版支持情况Tauri 1.5当前项目使用 Tauri 1.5它链接 WebKitGTK4.0Ubuntu LTS代号桌面构建Tauri20.04Focal✅ 原生构建22.04Jammy✅ 原生构建推荐24.04Noble❌ Tauri 1.5 不支持4.0 头文件已移除symlink hack 能过 pkg-config但 wry crate 会在编译 4.1 API 时失败26.04Resolute❌ 4.0 软件包不再发布Ubuntu 24.04 / 26.04 用户注意桌面安装包构建build-all.sh目前在这些发行版上无法产出可用的二进制。请改用上文快速开始中的双终端开发模式——它在所有 Ubuntu 版本上都能工作可以获得完整的本地 ViewerFastAPI 在:8000、React 在:3000浏览器中只是没有打包好的.AppImage/.deb。迁移到 Tauri 2是规划中的改进也是解除 Ubuntu 24.04 桌面构建限制的路径Tauri 2 链接 WebKitGTK 4.1可在这类发行版上原生构建。迁移属于中等工作量有经验的开发者约半天升级tauri/tauri-build/ wry运行npm run tauri migrate自动重写约 70% 的tauri.conf.json与 JS API 导入再修复剩余编译错误并回归测试 FastAPI 子进程启动。Linux 构建依赖Rust 打包器需要 WebKitGTK 等开发头文件Debian/Ubuntusudo apt install -y \ libwebkit2gtk-4.0-dev libgtk-3-dev libsoup2.4-dev \ libayatana-appindicator3-dev librsvg2-dev libssl-dev \ pkg-config build-essential常见构建错误若build-all.sh报failed to get cargo metadata或cargo: command not found说明cargo不在PATH上。安装 Rust 后在当前 shell 启用source $HOME/.cargo/env永久生效则把同一行加入~/.bashrc。构建脚本在检测到cargo缺失时也会自动尝试这一操作。生产部署方案一纯 Web 浏览器模式单独启动 FastAPI 后端将 React 应用部署到任意静态托管Vercel、Netlify 等通过环境变量把 API URL 指向你的后端服务器VITE_API_URL。方案二合并部署FastAPI 托管 React 静态文件构建前端并复制产物npm run build npm run bundle第二步会把构建产物复制到../rest-api/static/由 scripts/bundle-for-prod.js 实现。在wrappers/rest-api/main.py中追加静态文件挂载from fastapi.staticfiles import StaticFiles # Add at the end, after all API routes app.mount(/, StaticFiles(directorystatic, htmlTrue), namestatic)启动 FastAPI它将同时提供 API 与 UIpython main.py这样只需一个进程、一个端口/api/v1提供接口、其余路径回退到 React 的index.html。常见问题与排障结合源码与文档整理几个高频问题的排查思路页面显示 No Device Activated侧边栏DevicePanel列表为空或未激活。确认后端已启动curl http://localhost:8000/api/v1/health应返回status与服务/版本信息、相机已连接仅一台设备且未手动操作时前端会自动激活。Socket.IO 一直断开检查:8000是否可达。开发模式下socket.ts直连http://localhost:8000而client.ts中的连接则经 Vite 代理/socket需ws: truevite.config.ts 已配置生产环境需确认后端 CORS 与静态托管配置。WebRTC 视频不显示查看控制台 ICE 状态。webrtc.ts使用公共 Google STUN纯内网环境可能需要额外配置 TURN同时确认流已通过 REST 端点启动stream/start或 sensor 级 startWebRTC 只是传输通道而非流开关。AI 助手显示 unavailable未配置 Key 或端点不可达。chat.ts的checkChatAvailability会先探测modelsEndpoint连通性配置后记得重启 dev server因为 Vite 只在启动时读取.env*。AI 回复被限流429chat.ts会读取Retry-After头提示等待秒数免费层尤其需要注意频率。E2E 测试连不上确保npm run dev在运行、后端在http://localhost:8000可用tests/INSTALLATION.md 有完整说明。MSW 控制台警告 unhandled request新加的 API 端点需要在 tests/mocks/api-handlers.ts 中补充 handler。小结RealSense React Viewer 用一套现代 Web 技术栈React 18 TypeScript Vite Zustand Three.js Socket.IO WebRTC Tauri把 librealsense 的能力完整搬进了浏览器与桌面REST 负责设备/传感器/选项/流控制WebRTC 承载低延迟视频Socket.IO 推送元数据与点云Zustand 统一管理多相机状态AI 助手则把参数调节从手动查找变成对话生成一键应用。无论是开发期双终端模式还是生产期合并部署都能在数分钟内跑通测试体系Vitest Playwright MSW与 Tauri 打包脚本则让它在工程化上同样完备。继续深入可以参考 react-viewer 源码、后端端点实现 与 rest-api 总览。【免费下载链接】librealsenseRealSense SDK项目地址: https://gitcode.com/GitHub_Trending/li/librealsense创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考