# homr 使用指南

## 安装状态

✅ 当前环境已预装 `homr` 和 `verovio`。

首次运行会自动下载检测模型（约 500MB），请耐心等待。

## 基本用法

### 命令行

```bash
# 基本识别
homr path/to/image.png --output result.musicxml

# 批量处理目录
homr path/to/folder/

# 指定输出文件名
homr image.png -o my_song.musicxml
```

### Python API

```python
from homr.main import process_image, ProcessingConfig, XmlGeneratorArguments

# 注意：homr 对中文路径支持有问题，建议先用 ASCII 路径
image_path = r"path/to/sheet_music.png"

config = ProcessingConfig(False, False, False, False, -1)
xml_args = XmlGeneratorArguments(False, None, None)

result = process_image(image_path, config, xml_args)
print("识别完成！")
# 输出文件自动生成：同目录下 .musicxml 文件
```

## 参数说明

| 参数 | 类型 | 说明 |
|------|------|------|
| `model_type` | str | 模型类型：`ctc`（默认）或 `transformer` |
| `language` | str | 语言：`english`、`german` 等 |
| `staffline_height` | float | 五线间距（像素），默认自动检测 |

## 输出格式

输出的 MusicXML 包含：
- `<part>` - 乐器/声部
- `<measure>` - 小节
- `<note>` - 音符
- `<attributes>` - 调号、拍号
- `<direction>` - 力度、表情记号

## 错误处理

```python
from homr.main import Homr

try:
    model = Homr()
    result = model.predict("image.png")
except Exception as e:
    print(f"识别失败: {e}")
```

## 已知限制

1. 手写体识别效果较差
2. 复杂和声识别可能不准确
3. 装饰音识别有限
4. 首次运行需下载模型（约 500MB）
5. **中文路径问题**：homr 对中文路径支持有问题，建议使用英文/数字路径

## 已知 Bug 修复

如果遇到 `numpy` 兼容性错误，修改 `autocrop.py`：
```python
# 原来的：
hist = cv2.calcHist([img], [0], None, [256], [0, 256])
dominant_color_gray_scale = max(enumerate(hist), ...)[0]

# 修复为：
hist = cv2.calcHist([img], [0], None, [256], [0, 256]).flatten()
dominant_color_gray_scale = max(enumerate(hist), ...)[0]
```