mat2tex 0.1.0

Bidirectional MAT/CSV/Excel to LaTeX table converter with PDF compilation and optional AI assistance.

Mat2Tex

MAT ↔ LaTeX 双向转换工具，支持 AI 辅助代码生成

🇺🇸 English | 🇹🇼 繁體中文

---

📖 简介

Mat2Tex 是一款专为科研人员和工程师设计的桌面工具，用于打通 MATLAB 和 LaTeX 之间的格式壁垒。

核心功能

• MAT → LaTeX 表格：将 .mat 文件变量转换为 LaTeX tabular 代码
• CSV/Excel → LaTeX：支持 .csv 和 .xlsx 格式
• LaTeX → MAT：反向解析表格为 MATLAB 变量
• PDF 表格提取：从 PDF 中提取表格并转为 LaTeX
• TeX → PDF：编译 LaTeX 为 PDF（支持 pdflatex/xelatex/lualatex/tectonic）
• AI 辅助：生成 MATLAB 代码、编写 LaTeX 报告
• 批量处理：glob 模式批量转换，带进度条

数据流

.mat / .csv / .xlsx  ── mat2table / csv2table / xlsx2table ──▶  .tex
        ▲                                                          │
        │                                                          │
   table2mat ◀────────────  .tex  ──── tex2pdf ──▶ .pdf            │
                                                                   │
                            .pdf  ──── pdf2tex  ──▶ .tex ──────────┘

                       ai-matlab / ai-report  (Claude / OpenAI / Gemini)

---

🚀 快速开始

安装

需要 Python 3.12 或更高版本。

# 核心 CLI
pip install mat2tex

# 支持 Excel 和 PDF 输入
pip install "mat2tex[excel,pdf]"

# AI 功能（Claude / OpenAI / Gemini）
pip install "mat2tex[ai]"

# 完整安装
pip install "mat2tex[excel,pdf,ai]"

基本使用

# 1. 查看 MAT 文件变量
mat2tex inspect data.mat

# 2. 生成 LaTeX 表格
mat2tex mat2table data.mat -o results.tex \
    -v "time,position,velocity" \
    -c "实验数据" -l "tab:exp" --decimal 3

# 3. 预览生成的 LaTeX
mat2tex csv2table experiments.csv --preview

# 4. 编译 TeX 为 PDF
mat2tex tex2pdf results.tex -e xelatex --clean

# 5. AI 生成 MATLAB 脚本
mat2tex config --set ai.api_key sk-...
mat2tex ai-matlab "对 x 做 FFT 并画频谱" --mat data.mat -o analyze.m

---

📋 命令一览

命令	用途
inspect	查看 MAT 文件变量（名称、类型、形状、预览）
mat2table	MAT 变量 → LaTeX 表格
csv2table	CSV 文件 → LaTeX 表格
xlsx2table	Excel 工作表 → LaTeX 表格
pdf2tex	PDF 表格提取 → LaTeX
mat2csv	MAT 变量 → CSV 文件
csv2mat	CSV 列 → MAT 变量
table2mat	LaTeX 表格 → MAT 文件
tex2pdf	TeX 文件编译为 PDF
batch	批量转换（支持 glob 模式）
config	配置管理（查看/设置/重置）
ai-matlab	AI 生成 MATLAB 脚本
ai-report	AI 生成 LaTeX 报告

所有命令支持 --help 查看完整选项。

---

⚙️ 配置

配置文件位于 ~/.mat2tex/config.toml（可通过 MAT2TEX_CONFIG_PATH 覆盖）。

mat2tex config --show

配置示例

[ai]
provider          = "claude"      # claude | openai | gemini
api_key           = ""            # 或设置 MAT2TEX_AI_API_KEY
base_url          = ""            # 自定义端点（代理 / Azure）
model             = ""            # 留空使用 provider 默认模型
timeout_seconds   = 60
max_tokens        = 4096
temperature       = 0.3

[tex]
engine        = "pdflatex"        # pdflatex | xelatex | lualatex | tectonic
compile_times = 2
clean_aux     = true

[table]
default_style   = "booktabs"
default_decimal = 2
default_align   = "c"

[output]
default_dir = "."
open_after  = false

环境变量

环境变量	对应配置
MAT2TEX_AI_API_KEY	ai.api_key
MAT2TEX_AI_BASE_URL	ai.base_url
MAT2TEX_TEX_ENGINE	tex.engine
ANTHROPIC_API_KEY	Claude SDK
OPENAI_API_KEY	OpenAI SDK
GEMINI_API_KEY	Gemini SDK

---

🖥️ macOS GUI

Mat2Tex 提供原生 macOS 桌面应用（SwiftUI），功能包括：

• 📁 文件浏览器：拖拽导入 MAT/CSV/XLSX 文件
• 📊 变量面板：实时预览变量内容
• 🔄 转换器：可视化配置表格样式
• 🤖 AI 助手：对话式生成代码和报告

构建 GUI

# 需要 Xcode 15+
cd macos
xcodebuild -project Mat2Tex.xcodeproj -scheme Mat2Tex build

---

🛠️ 开发

环境设置

# 克隆仓库
git clone https://github.com/xlle-er/mat2tex.git
cd mat2tex

# 创建虚拟环境
python3.12 -m venv .venv
source .venv/bin/activate

# 安装依赖
pip install -e ".[dev]"

运行测试

# 全部测试
pytest

# 带覆盖率
pytest --cov=mat2tex --cov-report=html

# 特定模块
pytest tests/unit/test_mat_parser.py

代码质量

# 格式化
ruff format .

# 检查
ruff check .

# 类型检查
mypy src/mat2tex

---

📊 项目状态

阶段	状态	说明
Phase 1: 核心 CLI	✅ 100%	MAT/CSV/LaTeX 转换
Phase 2: 完整 CLI	✅ 100%	Rich 输出 + 批量处理
Phase 3: AI 集成	✅ 100%	Claude/OpenAI/Gemini
Phase 4: macOS GUI	🔄 80%	SwiftUI 骨架完成
Phase 5: 打包发布	⏳ 待定	PyPI + Homebrew

当前版本: 1.0.0
测试: 333 passed, 87% 覆盖率
类型检查: 0 mypy errors

---

❓ 常见问题

MAT 文件提示需要 hdf5storage
新版 MATLAB 文件 (v7.3) 使用 HDF5 格式。安装可选依赖：pip install hdf5storage

xlsx2table 提示 openpyxl 缺失
安装 Excel 依赖：pip install -e ".[excel]"

tex2pdf 应该选哪个引擎？

• pdflatex：默认，适合纯英文文档
• xelatex：支持中日韩文字（配合 ctex）
• lualatex：现代引擎，Unicode 原生支持
• tectonic：单文件二进制，适合 CI 环境

--preview 在管道中会输出 ANSI 颜色吗？
不会。Rich 会自动检测非 TTY 输出并回退为纯文本。

可以使用自建或代理的 LLM 吗？
可以。设置 ai.base_url（如需认证还需 ai.api_key）。OpenAI provider 兼容 OpenAI 兼容端点。

---

📄 文档

• 用户指南 - 完整命令使用说明
• CLI 设计 - CLI 命令参考
• API 参考文档 - 核心模块 API 文档
• GUI 使用指南 - macOS GUI 应用指南
• 测试指南 - 测试框架和覆盖率
• 故障排除 - 常见问题和解决方案
• 贡献指南 - 如何参与贡献
• 项目状态 - 当前开发进度

多语言文档 / Multilingual Documentation

• English
• 繁體中文

---

📜 许可证

MIT License - 详见 LICENSE

---

Made with ❤️ by xlle-er