中文 | English

MeshViewerRust 是一个基于 Rust + Bevy 的高性能桌面 3D 模型查看器：专为大模型场景而生，百万面模型也能秒级打开，并提供网格、材质、骨骼、UV 等完整视图能力。

• 多渲染模式：线框、实体、部件、材质、骨骼（动画模式预留）
• 右侧信息面板：模型统计、材质信息、UV 面板
• 文件加载方式：命令行参数、文件对话框、目录浏览、拖拽文件
• 快捷键工作流：模式切换与面板切换
• 中英文 UI 本地化
• 设置持久化（TOML）
• macOS Finder 打开文件支持（项目内含对应插件）
• 秒级打开百万面模型（硬件相关）

预览图 1	预览图 2

当前内置识别的扩展名：

glb, gltf, fbx, obj, stl, ply, dae, 3ds

说明：不同格式的实际解析能力受底层依赖与文件内容影响。

• Rust (Edition 2024)
• Bevy
• bevy_egui
• russimp-ng
• rfd

• 安装 Rust（建议使用最新 stable 工具链）
• 安装平台编译工具链（例如 macOS 上的 Xcode Command Line Tools）

cargo run

可选：启动时直接打开模型文件

cargo run -- /path/to/model.fbx

• 1：线框模式
• 2：实体模式
• 3：部件视图
• 4：材质预览
• 5：骨骼模式
• B：切换左侧边栏
• I：切换信息面板
• M：切换材质面板
• U：切换 UV 面板
• F：视角适配（Fit to View）
• Ctrl/Cmd + O：打开模型文件
• Ctrl/Cmd + Shift + O：打开目录
• Ctrl/Cmd + ,：打开设置

默认配置样例位于：

• config/default_settings.toml

运行时设置会写入系统配置目录（按平台自动选择），应用重启后会保留：

• 语言、主题
• 启动默认模式
• 渲染参数（如线框颜色、骨骼显示参数等）
• Blender 可执行文件路径（可选）

项目提供脚本用于打包 .app：

./scripts/bundle_macos.sh

调试构建：

./scripts/bundle_macos.sh debug

可选：安装 create-dmg（用于更美观的 DMG 布局）

brew install create-dmg

脚本会优先使用 create-dmg；若未安装，会自动回退到系统自带 hdiutil 生成 .dmg。

如果下载或拷贝后的 .app 无法直接打开，可先移除隔离属性：

xattr -dr com.apple.quarantine /path/to/MeshViewerRust.app

如仍有签名相关告警，可执行一次本地 ad-hoc 自签名：

codesign --force --deep --sign - /path/to/MeshViewerRust.app

• UV 预览能力完善
• 动画模式与播放控制增强
• 更完整的跨平台打包与分发流程
• 更多渲染与调试辅助选项

欢迎 Issue 和 PR。
建议在提交前先运行本地检查：

cargo fmt
cargo clippy --all-targets --all-features -- -D warnings
cargo test

本项目采用 MIT 许可证，详见 LICENSE。

MeshViewerRust is a desktop 3D mesh viewer built with Rust + Bevy, focused on lightweight, fast, and extensible model inspection workflows.
It currently targets practical preview/debug use cases such as mesh/material/skeleton/UV inspection and basic workflow integrations (file dialog, drag-and-drop, optional Blender handoff).
Built for heavy assets: million-face models load in seconds, with mesh/material/skeleton/UV workflows in one desktop app.

• Multiple render modes: Wireframe, Solid, Component, Material, Skeleton (Animation reserved)
• Right-side panels for model stats, material details, and UV panel
• Multiple load entry points: CLI argument, file dialog, directory browser, drag-and-drop
• Keyboard-first workflow for mode/panel switching
• Built-in Chinese/English localization
• Persistent settings via TOML
• macOS Finder open-file support plugin
• Seconds-level loading for million-face models (hardware dependent)

Preview 1	Preview 2

Recognized file extensions:

glb, gltf, fbx, obj, stl, ply, dae, 3ds

Note: Actual parsing quality depends on file content and underlying importer support.

• Rust (Edition 2024)
• Bevy
• bevy_egui
• russimp-ng
• rfd

• Rust (latest stable recommended)
• Platform build toolchain (e.g., Xcode Command Line Tools on macOS)

cargo run

Optional: open a model at startup

cargo run -- /path/to/model.fbx

• 1: Wireframe mode
• 2: Solid mode
• 3: Component view
• 4: Material preview
• 5: Skeleton mode
• B: Toggle left sidebar
• I: Toggle info panel
• M: Toggle material panel
• U: Toggle UV panel
• F: Fit to view
• Ctrl/Cmd + O: Open file
• Ctrl/Cmd + Shift + O: Open directory
• Ctrl/Cmd + ,: Open settings

Default config reference:

• config/default_settings.toml

Runtime settings are persisted in an OS-specific config directory, including:

• locale and theme
• default startup mode
• render parameters (wireframe/skeleton options, etc.)
• optional Blender executable path

Build .app bundle:

./scripts/bundle_macos.sh

Debug bundle:

./scripts/bundle_macos.sh debug

Optional: install create-dmg (for prettier DMG layout):

brew install create-dmg

The script prefers create-dmg; if unavailable, it automatically falls back to macOS built-in hdiutil.

If the app cannot be opened on first launch, remove quarantine attributes:

xattr -dr com.apple.quarantine /path/to/MeshViewerRust.app

If signature warnings still appear, apply local ad-hoc signing:

codesign --force --deep --sign - /path/to/MeshViewerRust.app

• Better UV preview implementation
• Enhanced animation mode and playback controls
• More complete cross-platform packaging/distribution
• Additional rendering/debugging helpers

Issues and PRs are welcome.
Before opening a PR, run:

cargo fmt
cargo clippy --all-targets --all-features -- -D warnings
cargo test

This project is licensed under the MIT License. See LICENSE for details.