Metadata-Version: 2.4
Name: mat2tex
Version: 0.1.0
Summary: Bidirectional MAT/CSV/Excel to LaTeX table converter with PDF compilation and optional AI assistance.
Project-URL: Homepage, https://github.com/mat2tex/mat2tex
Project-URL: Repository, https://github.com/mat2tex/mat2tex
Project-URL: Documentation, https://github.com/mat2tex/mat2tex#readme
Project-URL: Bug Tracker, https://github.com/mat2tex/mat2tex/issues
Project-URL: Changelog, https://github.com/mat2tex/mat2tex/blob/main/CHANGELOG.md
Author: Mat2Tex Contributors
Maintainer: Mat2Tex Contributors
License: MIT
License-File: LICENSE
Keywords: academic,cli,converter,csv,excel,latex,mat-file,matlab,pdflatex,scientific-computing,table,tectonic,xelatex
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Text Processing :: Markup :: LaTeX
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: click>=8.1.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: scipy>=1.11.0
Provides-Extra: ai
Requires-Dist: anthropic>=0.40.0; extra == 'ai'
Requires-Dist: google-generativeai>=0.7.0; extra == 'ai'
Requires-Dist: openai>=1.40.0; extra == 'ai'
Provides-Extra: dev
Requires-Dist: openpyxl>=3.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Provides-Extra: excel
Requires-Dist: openpyxl>=3.0.0; extra == 'excel'
Provides-Extra: pdf
Requires-Dist: pdfplumber>=0.10.0; extra == 'pdf'
Description-Content-Type: text/markdown

# Mat2Tex

<p align="center">
  <img src="macos/Mat2Tex/Resources/Assets.xcassets/AppIcon.appiconset/icon_256x256@2x.png" width="128" height="128" alt="Mat2TeX Icon">
</p>

<p align="center">
  <strong>MAT ↔ LaTeX 双向转换工具，支持 AI 辅助代码生成</strong>
</p>

<p align="center">
  <a href="https://github.com/xlle-er/mat2tex/blob/main/README_EN.md">🇺🇸 English</a> |
  <a href="https://github.com/xlle-er/mat2tex/blob/main/README_TW.md">🇹🇼 繁體中文</a>
</p>

<p align="center">
  <img src="https://img.shields.io/badge/version-1.0.0-blue?style=flat-square" alt="Version">
  <img src="https://img.shields.io/badge/python-3.12+-green?style=flat-square&logo=python&logoColor=white" alt="Python">
  <img src="https://img.shields.io/badge/platform-macOS-lightgrey?style=flat-square&logo=apple&logoColor=white" alt="Platform">
  <img src="https://img.shields.io/badge/license-MIT-yellow?style=flat-square" alt="License">
  <img src="https://img.shields.io/badge/tests-333%20passed-brightgreen?style=flat-square" alt="Tests">
  <img src="https://img.shields.io/badge/coverage-87%25-green?style=flat-square" alt="Coverage">
</p>

---

## 📖 简介

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 或更高版本。

```bash
# 核心 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]"
```

### 基本使用

```bash
# 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` 覆盖）。

```bash
mat2tex config --show
```

### 配置示例

```toml
[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

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

---

## 🛠️ 开发

### 环境设置

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

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

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

### 运行测试

```bash
# 全部测试
pytest

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

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

### 代码质量

```bash
# 格式化
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 兼容端点。

---

## 📄 文档

- [用户指南](docs/12-user-guide.md) - 完整命令使用说明
- [CLI 设计](docs/04-cli-design.md) - CLI 命令参考
- [API 参考文档](docs/11-api-reference.md) - 核心模块 API 文档
- [GUI 使用指南](docs/28-gui-user-guide.md) - macOS GUI 应用指南
- [测试指南](docs/33-testing-guide.md) - 测试框架和覆盖率
- [故障排除](docs/en/troubleshooting.md) - 常见问题和解决方案
- [贡献指南](docs/en/contributing-guide.md) - 如何参与贡献
- [项目状态](PROJECT_STATUS.md) - 当前开发进度

### 多语言文档 / Multilingual Documentation

- [English](docs/en/README.md)
- [繁體中文](docs/zh-TW/README.md)

---

## 📜 许可证

MIT License - 详见 [LICENSE](LICENSE)

---

<p align="center">
  Made with ❤️ by <a href="https://github.com/xlle-er">xlle-er</a>
</p>
