🔍 MeshLens

Lightweight 3D Model Intelligent Analysis Engine CLI
轻量级3D模型智能分析引擎 · 零依赖 · 跨平台 · 终端原生

简体中文 · 繁體中文 · English

---

🎉 简体中文

📖 项目介绍

MeshLens 是一款轻量级的3D模型智能分析引擎，专为开发者、3D美术和游戏开发者设计。它可以在终端中快速查看、分析任何3D模型文件的详细信息，包括网格统计、材质分析、纹理信息、动画数据以及模型健康检查。

💡 灵感来源：随着3D技术在游戏、AR/VR、数字孪生等领域的广泛应用，开发者需要一个快速、轻量的工具来检查和分析3D模型文件，而无需打开沉重的3D建模软件。MeshLens填补了这一空白。

✨ 差异化亮点：

• 🚀 零依赖 — 纯Python实现，无需安装任何第三方库
• ⚡ 极速分析 — 毫秒级完成模型文件解析与统计
• 🏥 健康检查 — 自动检测模型常见问题并给出修复建议
• 📊 批量处理 — 支持目录级批量分析并生成汇总报告
• 🌐 多格式支持 — 支持GLB/GLTF/OBJ/STL/FBX/PLY/DAE/3DS等主流格式

✨ 核心特性

特性	描述
🔺 网格分析	顶点数、面数、图元类型、包围盒、尺寸计算
🎭 材质解析	PBR参数、透明度、双面渲染、纹理引用
🖼️ 纹理信息	过滤模式、环绕模式、MIME类型、图片引用
🎬 动画检测	动画时长、通道类型、采样器数量
🏥 健康检查	非流形边、重复面、孤立顶点、缺失法线/UV等
📊 批量处理	递归扫描目录，生成JSON/Markdown汇总报告
📐 格式支持	GLB, GLTF, OBJ, STL, FBX, PLY, DAE, 3DS
🖥️ 跨平台	Windows / macOS / Linux 全平台支持

🚀 快速开始

环境要求：

• Python 3.8 或更高版本
• 无需任何第三方依赖

安装：

# 从PyPI安装（推荐）
pip install meshlens

# 或从源码安装
git clone https://github.com/gitstq/MeshLens.git
cd MeshLens
pip install -e .

使用：

# 查看帮助
meshlens --help

# 快速查看模型信息
meshlens info model.glb

# 完整分析（含健康检查）
meshlens analyze model.obj --health-check --verbose

# 导出为JSON
meshlens analyze model.fbx --format json --output report.json

# 导出为Markdown
meshlens analyze model.gltf --format markdown --output report.md

# 健康检查
meshlens health model.stl

# 批量分析目录
meshlens batch ./models/ --recursive --health-check --format markdown

# 查看支持的格式
meshlens formats

📖 详细使用指南

analyze — 完整分析

meshlens analyze <文件路径> [选项]

选项:
  --health-check, -hc    启用模型健康检查
  --format, -f           输出格式: text | json | markdown
  --output, -o           输出文件路径
  --verbose, -V          显示详细信息

info — 快速摘要

meshlens info <文件路径> [--verbose]

health — 健康检查

meshlens health <文件路径> [--format text|json]

batch — 批量处理

meshlens batch <目录路径> [选项]

选项:
  --recursive, -r        递归搜索子目录
  --health-check, -hc    启用健康检查
  --format, -f           报告格式: json | markdown
  --output, -o           输出文件名（不含扩展名）
  --extensions           指定文件扩展名

💡 设计思路与迭代规划

设计理念：

• 零依赖哲学 — 不引入任何第三方库，确保在任何Python环境下都能运行
• 终端优先 — 专为终端工作流设计，输出清晰、结构化
• 渐进式信息 — 从快速摘要到详细分析，按需获取信息

技术选型：

• 纯Python标准库实现（struct, json, xml.etree, argparse）
• 二进制格式解析使用struct模块直接读取
• 支持ASCII和Binary两种变体格式

后续规划：

• 🔄 添加模型格式转换功能（OBJ↔GLTF等）
• 📊 添加模型对比功能
• 🎨 添加TUI交互式界面
• 📦 添加Draco压缩支持
• 🔌 添加MCP服务器集成

📦 打包与部署

MeshLens是一个纯Python工具库/CLI工具，无需打包为可执行文件。

# 安装即可使用
pip install meshlens

# 验证安装
meshlens --version

🤝 贡献指南

欢迎贡献代码！请阅读 CONTRIBUTING.md 了解详情。

提交规范遵循 Angular Commit Convention：

• feat: 新增功能
• fix: 修复问题
• docs: 文档更新
• refactor: 代码重构
• test: 测试相关

📄 开源协议

本项目基于 MIT License 开源。

---

🎉 繁體中文

📖 專案介紹

MeshLens 是一款輕量級的3D模型智能分析引擎，專為開發者、3D美術和遊戲開發者設計。它可以在終端中快速查看、分析任何3D模型檔案的詳細資訊，包括網格統計、材質分析、紋理資訊、動畫資料以及模型健康檢查。

💡 靈感來源：隨著3D技術在遊戲、AR/VR、數位雙胞胎等領域的廣泛應用，開發者需要一個快速、輕量的工具來檢查和分析3D模型檔案，而無需打開沉重的3D建模軟體。MeshLens填補了這一空白。

✨ 差異化亮點：

• 🚀 零依賴 — 純Python實現，無需安裝任何第三方庫
• ⚡ 極速分析 — 毫秒級完成模型檔案解析與統計
• 🏥 健康檢查 — 自動檢測模型常見問題並給出修復建議
• 📊 批次處理 — 支援目錄級批次分析並生成彙總報告
• 🌐 多格式支援 — 支援GLB/GLTF/OBJ/STL/FBX/PLY/DAE/3DS等主流格式

✨ 核心特性

特性	描述
🔺 網格分析	頂點數、面數、圖元類型、包圍盒、尺寸計算
🎭 材質解析	PBR參數、透明度、雙面渲染、紋理引用
🖼️ 紋理資訊	過濾模式、環繞模式、MIME類型、圖片引用
🎬 動畫檢測	動畫時長、通道類型、取樣器數量
🏥 健康檢查	非流形邊、重複面、孤立頂點、缺失法線/UV等
📊 批次處理	遞迴掃描目錄，生成JSON/Markdown彙總報告
📐 格式支援	GLB, GLTF, OBJ, STL, FBX, PLY, DAE, 3DS
🖥️ 跨平台	Windows / macOS / Linux 全平台支援

🚀 快速開始

環境要求：

• Python 3.8 或更高版本
• 無需任何第三方依賴

安裝：

# 從PyPI安裝（推薦）
pip install meshlens

# 或從原始碼安裝
git clone https://github.com/gitstq/MeshLens.git
cd MeshLens
pip install -e .

使用：

# 查看幫助
meshlens --help

# 快速查看模型資訊
meshlens info model.glb

# 完整分析（含健康檢查）
meshlens analyze model.obj --health-check --verbose

# 匯出為JSON
meshlens analyze model.fbx --format json --output report.json

# 匯出為Markdown
meshlens analyze model.gltf --format markdown --output report.md

# 健康檢查
meshlens health model.stl

# 批次分析目錄
meshlens batch ./models/ --recursive --health-check --format markdown

# 查看支援的格式
meshlens formats

📖 詳細使用指南

analyze — 完整分析

meshlens analyze <檔案路徑> [選項]

選項:
  --health-check, -hc    啟用模型健康檢查
  --format, -f           輸出格式: text | json | markdown
  --output, -o           輸出檔案路徑
  --verbose, -V          顯示詳細資訊

info — 快速摘要

meshlens info <檔案路徑> [--verbose]

health — 健康檢查

meshlens health <檔案路徑> [--format text|json]

batch — 批次處理

meshlens batch <目錄路徑> [選項]

選項:
  --recursive, -r        遞迴搜尋子目錄
  --health-check, -hc    啟用健康檢查
  --format, -f           報告格式: json | markdown
  --output, -o           輸出檔案名（不含副檔名）
  --extensions           指定檔案副檔名

💡 設計思路與迭代規劃

設計理念：

• 零依賴哲學 — 不引入任何第三方庫，確保在任何Python環境下都能運行
• 終端優先 — 專為終端工作流設計，輸出清晰、結構化
• 漸進式資訊 — 從快速摘要到詳細分析，按需獲取資訊

技術選型：

• 純Python標準庫實現（struct, json, xml.etree, argparse）
• 二進制格式解析使用struct模組直接讀取
• 支援ASCII和Binary兩種變體格式

後續規劃：

• 🔄 新增模型格式轉換功能（OBJ↔GLTF等）
• 📊 新增模型對比功能
• 🎨 新增TUI互動式介面
• 📦 新增Draco壓縮支援
• 🔌 新增MCP伺服器整合

📦 打包與部署

MeshLens是一個純Python工具庫/CLI工具，無需打包為可執行檔案。

# 安裝即可使用
pip install meshlens

# 驗證安裝
meshlens --version

🤝 貢獻指南

歡迎貢獻程式碼！請閱讀 CONTRIBUTING.md 了解詳情。

提交規範遵循 Angular Commit Convention：

• feat: 新增功能
• fix: 修復問題
• docs: 文件更新
• refactor: 程式碼重構
• test: 測試相關

📄 開源協議

本專案基於 MIT License 開源。

---

🎉 English

📖 Introduction

MeshLens is a lightweight 3D model intelligent analysis engine designed for developers, 3D artists, and game developers. It provides instant, detailed inspection of any 3D model file directly from your terminal — including mesh statistics, material analysis, texture information, animation data, and model health checks.

💡 Inspiration: With the growing adoption of 3D technology across gaming, AR/VR, and digital twins, developers need a fast, lightweight tool to inspect and analyze 3D model files without opening heavy 3D modeling software. MeshLens fills this gap.

✨ Key Differentiators:

• 🚀 Zero Dependencies — Pure Python implementation, no third-party libraries required
• ⚡ Blazing Fast — Millisecond-level model parsing and statistics
• 🏥 Health Checks — Automatically detect common model issues with fix suggestions
• 📊 Batch Processing — Directory-level batch analysis with consolidated reports
• 🌐 Multi-Format — Support for GLB/GLTF/OBJ/STL/FBX/PLY/DAE/3DS

✨ Core Features

Feature	Description
🔺 Mesh Analysis	Vertex count, face count, primitive types, bounding box, dimensions
🎭 Material Parsing	PBR parameters, transparency, double-sided rendering, texture refs
🖼️ Texture Info	Filter modes, wrap modes, MIME types, image references
🎬 Animation Detection	Duration, channel types, sampler count
🏥 Health Checks	Non-manifold edges, duplicate faces, isolated vertices, missing normals/UVs
📊 Batch Processing	Recursive directory scanning, JSON/Markdown report generation
📐 Format Support	GLB, GLTF, OBJ, STL, FBX, PLY, DAE, 3DS
🖥️ Cross-Platform	Windows / macOS / Linux

🚀 Quick Start

Requirements:

• Python 3.8+
• No third-party dependencies

Installation:

# Install from PyPI (recommended)
pip install meshlens

# Or install from source
git clone https://github.com/gitstq/MeshLens.git
cd MeshLens
pip install -e .

Usage:

# Show help
meshlens --help

# Quick model info
meshlens info model.glb

# Full analysis with health check
meshlens analyze model.obj --health-check --verbose

# Export as JSON
meshlens analyze model.fbx --format json --output report.json

# Export as Markdown
meshlens analyze model.gltf --format markdown --output report.md

# Health check only
meshlens health model.stl

# Batch analyze a directory
meshlens batch ./models/ --recursive --health-check --format markdown

# List supported formats
meshlens formats

📖 Detailed Usage Guide

analyze — Full Analysis

meshlens analyze <file_path> [options]

Options:
  --health-check, -hc    Enable model health checking
  --format, -f           Output format: text | json | markdown
  --output, -o           Output file path
  --verbose, -V          Show verbose output

info — Quick Summary

meshlens info <file_path> [--verbose]

health — Health Check

meshlens health <file_path> [--format text|json]

batch — Batch Processing

meshlens batch <directory> [options]

Options:
  --recursive, -r        Recursively search subdirectories
  --health-check, -hc    Enable health checking
  --format, -f           Report format: json | markdown
  --output, -o           Output filename (without extension)
  --extensions           Specify file extensions

💡 Design Philosophy & Roadmap

Design Principles:

• Zero Dependencies — No third-party libraries, runs in any Python environment
• Terminal-First — Designed for terminal workflows with clear, structured output
• Progressive Disclosure — From quick summary to detailed analysis, get info on demand

Tech Stack:

• Pure Python standard library (struct, json, xml.etree, argparse)
• Binary format parsing via struct module
• Support for both ASCII and Binary format variants

Roadmap:

• 🔄 Model format conversion (OBJ↔GLTF, etc.)
• 📊 Model comparison feature
• 🎨 TUI interactive interface
• 📦 Draco compression support
• 🔌 MCP server integration

📦 Installation & Deployment

MeshLens is a pure Python tool/library — no executable packaging needed.

# Install and use
pip install meshlens

# Verify installation
meshlens --version

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md for details.

Follow the Angular Commit Convention:

• feat: New features
• fix: Bug fixes
• docs: Documentation updates
• refactor: Code refactoring
• test: Test-related changes

📄 License

This project is licensed under the MIT License.

---

Made with ❤️ by gitstq