Initial commit: skills library

- 70 skills with code and documentation - Add .gitignore (ignore __pycache__, output/, temp/, venv/) - Clean up test intermediates and caches
2026-04-26 19:27:40 +08:00
commit 04db423416
861 changed files with 210414 additions and 0 deletions
@@ -0,0 +1,3 @@
+# Example Reference
+
+This is an example reference file. Delete if not needed.
@@ -0,0 +1,88 @@
+# 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]
+```
@@ -0,0 +1,102 @@
+# 提高识别率技巧
+
+## 图片质量要求
+
+### ✅ 最佳
+- 300+ DPI 扫描件
+- 光线均匀、无阴影
+- 纸张平整无褶皱
+- 音符清晰、线条完整
+
+### ⚠️ 次佳
+- 150 DPI 扫描
+- 手机拍摄但光线好
+- 轻微阴影可接受
+
+### ❌ 避免
+- 50 DPI 以下的模糊图
+- 严重倾斜（可预处理校正）
+- 光线不均导致部分过暗/过亮
+- 铅笔痕迹干扰
+
+## 预处理建议
+
+### Python + PIL 增强
+
+```python
+from PIL import Image, ImageFilter, ImageOps
+import numpy as np
+
+def preprocess_sheet_music(image_path):
+    img = Image.open(image_path).convert('L')  # 灰度
+    
+    # 增加对比度
+    img = ImageOps.autocontrast(img)
+    
+    # 去噪
+    img = img.filter(ImageFilter.MedianFilter(size=3))
+    
+    # 二值化（有时有效）
+    # img = img.point(lambda x: 0 if x < 128 else 255)
+    
+    return img
+
+# 使用
+processed = preprocess_sheet_music("original.jpg")
+processed.save("processed.png")
+```
+
+### 倾斜校正
+
+```python
+from deskew import deskew
+
+# 自动检测并校正倾斜角度
+image = Image.open("tilted.jpg")
+corrected = deskew(image)
+corrected.save("corrected.jpg")
+```
+
+## 格式选择
+
+| 格式 | 推荐度 | 说明 |
+|------|--------|------|
+| PNG | ⭐⭐⭐⭐⭐ | 无损压缩，最佳 |
+| TIFF | ⭐⭐⭐⭐ | 印刷级无损 |
+| JPG (高画质) | ⭐⭐⭐ | 可接受 |
+| JPG (低画质) | ⭐ | 压缩失真严重 |
+
+## 分辨率建议
+
+| 乐谱复杂度 | 最小宽度 | 建议 DPI |
+|-----------|---------|---------|
+| 简单旋律 | 1000px | 150 |
+| 钢琴谱（双手） | 2500px | 300 |
+| 交响乐总谱 | 4000px | 400 |
+
+## 多页处理
+
+```python
+import subprocess
+
+# 将多页 PDF 转为单页图片
+subprocess.run([
+    "pdftoppm", 
+    "-r", "300",      # DPI
+    "-png",           # 输出 PNG
+    "score.pdf",      # 输入
+    "page"            # 输出前缀
+])
+
+# 然后逐页识别
+for i in range(1, page_count + 1):
+    model.predict(f"page-{i}.png")
+```
+
+## 识别后校对
+
+建议在 MuseScore 中打开识别结果，检查：
+1. 节拍是否正确
+2. 升降号是否遗漏
+3. 和弦分解是否正确
+4. 休止符位置
@@ -0,0 +1,70 @@
+# Verovio 渲染预览
+
+## 安装
+
+```bash
+pip install verovio
+```
+
+## 渲染 MusicXML 为图片
+
+```python
+import verovio
+
+toolkit = verovio.toolkit()
+
+# 加载 MusicXML
+toolkit.loadFile("score.musicxml")
+
+# 渲染为 SVG
+svg = toolkit.renderToSVG()
+
+# 保存 SVG
+with open("output.svg", "w") as f:
+    f.write(svg)
+
+# 渲染为 PNG
+toolkit.renderToPNG("output.png", 300)  # 300 DPI
+
+# 渲染为 PDF
+toolkit.renderToPDF("output.pdf")
+```
+
+## 命令行工具
+
+```bash
+# 安装命令行工具
+pip install verovio[commandline]
+
+# 转换
+vrv tool -o output.png input.musicxml -r 300
+```
+
+## 在 Jupyter 中预览
+
+```python
+from IPython.display import SVG, display
+
+toolkit = verovio.toolkit()
+toolkit.loadFile("score.musicxml")
+svg = toolkit.renderToSVG()
+display(SVG(svg))
+```
+
+## 调整页面布局
+
+```python
+toolkit.setOption("pageWidth", 2100)   # 页面宽度（tenths）
+toolkit.setOption("pageHeight", 2970)  # 页面高度
+toolkit.setOption("scale", 50)         # 缩放比例
+toolkit.setOption("spacingSystem", 50) # 五线间距
+```
+
+## 获取 MIDI
+
+```python
+toolkit.loadFile("score.musicxml")
+midi = toolkit.renderToMIDI()
+with open("output.mid", "wb") as f:
+    f.write(midi)
+```