技能备份 - 2026-04-15 (40个技能)

2026-04-15 18:53:15 +08:00
parent f62f14814f
commit c65fce24e4
791 changed files with 190773 additions and 0 deletions
@@ -0,0 +1,163 @@
+# API Reference for Super OCR
+
+This document provides complete API documentation for using Super OCR as a Python library.
+
+## Quick Start
+
+```python
+from super_ocr import OCRProcessor
+
+# Auto mode (recommended)
+processor = OCRProcessor(engine='auto')
+result = processor.extract('image.png')
+
+print(result['text'])
+print(f"Confidence: {result['confidence']:.2%}")
+print(f"Engine: {result['engine']}")
+```
+
+## OCRProcessor Class
+
+### `__init__(engine: str = 'auto', verbose: bool = False)`
+
+Initialize the OCR processor.
+
+**Parameters:**
+- `engine` (str): 'auto', 'tesseract', or 'paddle'. Default: 'auto'
+- `verbose` (bool): Enable detailed logging. Default: False
+
+### `extract(image_path: str) -> Dict`
+
+Extract text from a single image.
+
+**Parameters:**
+- `image_path` (str): Path to the input image
+
+**Returns:**
+```python
+{
+    'text': str,                    # Extracted text
+    'confidence': float,           # Confidence score (0.0 - 1.0)
+    'engine': str,                 # 'tesseract' or 'paddle'
+    'processing_time_ms': float,   # Processing time in milliseconds
+    'error': Optional[str],        # Error message if failed
+    'results': List[Dict],         # Detailed results (PaddleOCR only)
+    'line_count': int              # Number of lines detected
+}
+```
+
+### `batch_extract(image_paths: List[str]) -> List[Dict]`
+
+Process multiple images.
+
+**Parameters:**
+- `image_paths` (List[str]): List of image file paths
+
+**Returns:**
+- List of result dictionaries (same structure as `extract()`)
+
+## Engine Selection
+
+### Auto Mode (Default)
+
+The processor automatically selects the best engine based on:
+
+1. **Image filename heuristics:**
+   - `screenshot`, `snap`, `capture` → Tesseract
+   - `menu`, `invoice`, `certificate`, `receipt` → PaddleOCR
+   - Default → PaddleOCR (better accuracy)
+
+2. **Quality fallback:**
+   - If Tesseract returns low confidence, PaddleOCR is used
+
+### Force Mode
+
+You can explicitly choose an engine:
+
+```python
+# Force Tesseract
+processor = OCRProcessor(engine='tesseract')
+
+# Force PaddleOCR
+processor = OCRProcessor(engine='paddle')
+```
+
+## Preprocessing
+
+For advanced users, you can preprocess images before OCR:
+
+```python
+from super_ocr.preprocessing import preprocess_pipeline
+
+# Load image
+import cv2
+image = cv2.imread('input.png')
+
+# Preprocess
+processed = preprocess_pipeline(
+    image,
+    denoise=True,
+    enhance=True,
+    binarize=True,
+    deskew=True,
+    resize_scale=2.0
+)
+
+# Save processed image
+cv2.imwrite('processed.png', processed)
+```
+
+## Output Formats
+
+The skill supports multiple output formats:
+
+| Format | Description |
+|--------|-------------|
+| `text` | Clean extracted text only |
+| `json` | Full JSON with metadata |
+| `structured` | Human-readable formatted output |
+| `verbose` | Debug information with confidence scores |
+
+## Configuration
+
+You can customize behavior by creating a `config.yaml`:
+
+```yaml
+default_engine: auto
+confidence_threshold: 0.8
+output_format: json
+preprocess:
+  denoise: true
+  enhance_contrast: true
+```
+
+## Error Handling
+
+```python
+try:
+    result = processor.extract('image.png')
+    
+    if result.get('error'):
+        print(f"Error: {result['error']}")
+    else:
+        print(result['text'])
+        
+except Exception as e:
+    print(f"Unexpected error: {e}")
+```
+
+## CLI Usage
+
+```bash
+# Single image
+python scripts/main.py --image image.png
+
+# Multiple images
+python scripts/main.py --images ./images/*.png --output ./results
+
+# Force engine
+python scripts/main.py --image doc.png --engine paddle --verbose
+
+# Different output format
+python scripts/main.py --image img.png --format text
+```
@@ -0,0 +1,77 @@
+# Engine Comparison
+
+## Tesseract vs PaddleOCR
+
+| Feature | Tesseract | PaddleOCR |
+|---------|-----------|-----------|
+| **Accuracy** | 90-95% | 98%+ |
+| **Chinese Support** | Good | Excellent |
+| **Speed** | ~200ms init, ~50ms/img | ~3s init, ~500ms/img |
+| **Memory** | ~100MB | ~500MB |
+| **Dependencies** | `pytesseract + cv2 + PIL` | `paddleocr + paddlepaddle` |
+| **Best For** | Quick extraction, English | High accuracy, Chinese docs |
+
+## When to Use Which
+
+### Use Tesseract When:
+- ✅ Extracting text from screenshots
+- ✅ Processing English-only documents
+- ✅ Need fast OCR (-web scraping, quick验证)
+- ✅ Limited memory environment
+
+### Use PaddleOCR When:
+- ✅ Processing Chinese documents
+- ✅ Need high accuracy (98%+)
+- ✅ Working with complex layouts（tables, forms）
+- ✅ Critical data extraction (invoices, contracts)
+
+## Performance Comparison
+
+| Task | Tesseract | PaddleOCR | Improvement |
+|------|-----------|-----------|-------------|
+| Screenshot text | ~70ms | ~600ms | Tesseract faster |
+| Chinese menu | ~200ms | ~550ms | - |
+| Invoice extraction | ~180ms | ~520ms | - |
+| Certificate OCR | ~250ms | ~580ms | PaddleOCR more accurate |
+
+## Quality Comparison
+
+### Example: Chinese Restaurant Menu
+
+**Tesseract (confidence: 88%)**
+```
+北京烤鸭
+宫保鸡丁
+麻婆豆腐...
+```
+
+**PaddleOCR (confidence: 99%)**
+```
+北京烤鸭
+宫保鸡丁
+麻婆豆腐
+...
+```
+
+### Example: English Invoice
+
+**Tesseract (confidence: 92%)**
+```
+Invoice #12345
+Date: 2024-03-05
+Amount: $199.99
+```
+
+**PaddleOCR (confidence: 98%)**
+```
+Invoice #12345
+Date: 2024-03-05
+Amount: $199.99
+```
+
+## Recommendation
+
+- **General use**: Auto mode (PaddleOCR by default for quality)
+- **Speed-critical**: Force Tesseract
+- **Chinese critical**: Force PaddleOCR
+- **Production**: Auto mode with fallback to PaddleOCR for low confidence
@@ -0,0 +1,150 @@
+# Troubleshooting
+
+Common issues and solutions for Super OCR。
+
+## Installation Issues
+
+### "Module not found: paddleocr"
+
+**Solution:**
+```bash
+pip install paddleocr paddlepaddle
+```
+
+For macOS/Linux:
+```bash
+pip install paddleocr paddlepaddle
+```
+
+For Windows:
+```bash
+pip install paddleocr paddlepaddle
+```
+
+### "Tesseract not found"
+
+**macOS:**
+```bash
+brew install tesseract
+```
+
+**Ubuntu/Debian:**
+```bash
+sudo apt update && sudo apt install tesseract-ocr
+```
+
+**Windows:**
+Download from: https://github.com/UB-Mannheim/tesseract/wiki
+
+## Runtime Issues
+
+### Low Confidence Results
+
+If OCR results have low confidence:
+
+1. **Enable verbose mode:**
+   ```bash
+   python scripts/main.py --image image.png --verbose
+   ```
+
+2. **Preprocess image manually:**
+   ```python
+   from super_ocr.preprocessing import preprocess_pipeline
+   import cv2
+   
+   image = cv2.imread('input.png')
+   processed = preprocess_pipeline(image, enhance=True, binarize=True)
+   cv2.imwrite('processed.png', processed)
+   ```
+
+3. **Force PaddleOCR for better accuracy:**
+   ```bash
+   python scripts/main.py --image image.png --engine paddle
+   ```
+
+### Memory Issues (PaddleOCR)
+
+PaddleOCR uses ~500MB memory。If you see memory errors:
+
+1. **Use Tesseract instead:**
+   ```bash
+   python scripts/main.py --image image.png --engine tesseract
+   ```
+
+2. **Process images one by one:**
+   ```bash
+   for img in images/*.png; do
+       python scripts/main.py --image "$img" --output results/
+   done
+   ```
+
+### Batch Processing Too Slow
+
+**Solutions:**
+
+1. **Use Tesseract for speed:**
+   ```bash
+   python scripts/main.py --images ./images/*.png --engine tesseract --output ./results/
+   ```
+
+2. **Process in parallel:**
+   ```bash
+   # macOS/Linux
+   find ./images -name "*.png" -print0 | xargs -0 -P 4 -I {} python scripts/main.py --image {} --output ./results/
+   ```
+
+3. **Initialize processor once, reuse:**
+   ```python
+   processor = OCRProcessor(engine='auto')
+   
+   for image in images:
+       result = processor.extract(image)
+       # Process result
+   ```
+
+## Configuration Issues
+
+### Custom Configuration Not Loading
+
+Create `config.yaml` in skill directory:
+
+```yaml
+default_engine: auto
+confidence_threshold: 0.8
+output_format: json
+preprocess:
+  denoise: true
+  enhance_contrast: true
+```
+
+### Output Format Not Working
+
+Check format name:
+```bash
+python scripts/main.py --image image.png --format json
+python scripts/main.py --image image.png --format text
+python scripts/main.py --image image.png --format structured
+```
+
+## Dependency Checker
+
+Run the checker to diagnose issues:
+
+```bash
+python scripts/dependencies.py --check --verbose
+python scripts/dependencies.py --install
+python scripts/dependencies.py --guide
+```
+
+## Getting Help
+
+If you encounter issues not covered here:
+
+1. Enable verbose mode: `--verbose`
+2. Check dependency status: `python scripts/dependencies.py --check`
+3. Try force engine: `--engine tesseract` or `--engine paddle`
+4. Report issue with:
+   - Python version
+   - OS
+   - Command used
+   - Error message