Python'da Tesseract OCR
pytesseract ile.
pytesseract için kapsamlı ve test edilmiş rehber: kurulum, temel API, görsel ön işleme, PDF, güven puanları, PSM/OEM yapılandırması, performans ve en sık karşılaşılan hatalar.
Hızlı başlangıç (üç satır)
Önce motoru kurun, sonra bunu çalıştırın. Tam kurulum aşağıdadır.
import pytesseract
from PIL import Image
text = pytesseract.image_to_string(Image.open("image.png"))
print(text)pytesseract kurulumu
pytesseract yalnızca bir sarmalayıcıdır: Tesseract ikili dosyasını çağırır, bu yüzden önce motor kurulmalıdır.
pip install pytesseract pillow
# isteğe bağlı, ön işleme için:
pip install opencv-python numpy
# isteğe bağlı, PDF girişi için:
pip install pdf2imageMotor PATH'te değilse (Windows'ta yaygın), açıkça belirtin:
import pytesseract
pytesseract.pytesseract.tesseract_cmd = r"C:\Program Files\Tesseract-OCR\tesseract.exe"Motorda yeni misiniz? Windows, macOS, Linux, Docker ve WSL için kurulum rehberine bakın.
Temel API
pytesseract her çıktı türü için bir fonksiyon sunar. İhtiyacınıza uygun olanı seçin.
| Fonksiyon | Döndürür | Ne zaman kullanılır |
|---|---|---|
image_to_string | Düz metin | Yalnızca tanınan metin gerektiğinde |
image_to_data | Sözcük kutuları + güven | Metni vurgulama, düşük güvenli sözcükleri filtreleme |
image_to_boxes | Karakter kutuları | Karakter düzeyinde geometri |
image_to_pdf_or_hocr | Aranabilir PDF veya hOCR | Aranabilir PDF veya web katmanları oluşturma |
image_to_osd | Yön ve yazı sistemi algılama | OCR öncesi dönüş veya yazı sistemi algılama |
image_to_alto_xml | ALTO XML | Arşiv / kütüphane iş akışları |
Yapılandırma: PSM, OEM, diller ve karakter beyaz listesi
Seçenekleri boşlukla ayrılmış bir dize olarak config= parametresine verin.
# Tek metin bloğu, LSTM motoru, Türkçe
text = pytesseract.image_to_string(img, lang="tur", config="--oem 3 --psm 6")
# Yalnızca rakamlar (fiş toplamları, sayaç değerleri)
text = pytesseract.image_to_string(img, config="--psm 7 -c tessedit_char_whitelist=0123456789.")
# Birleşik diller
text = pytesseract.image_to_string(img, lang="eng+tur")| PSM | Mod | İdeal kullanım |
|---|---|---|
| 3 | Tam otomatik (varsayılan) | Standart belgeler |
| 4 | Değişken boyutlu tek sütun | Makaleler, tek sütunlu sayfalar |
| 6 | Tekdüze tek metin bloğu | Paragraflar, etiketler |
| 7 | Tek metin satırı | Tek satırlık başlıklar, tek alanlar |
| 8 | Tek sözcük | Tek tek sözcükler |
| 11 | Seyrek metin | Fişler, dağınık arayüz metni |
| 13 | Ham satır | Tesseract hileleri olmadan tek satır |
OEM modları: --oem 1 (yalnızca LSTM, v5 varsayılanı), --oem 0 (eski), --oem 3 (otomatik). Tam başvuru belgelerde.
Görsel ön işleme
Temiz girdi, doğruluk üzerindeki en büyük etkendir. En çok önem taşıyan adımlar şunlardır.
import cv2, numpy as np, pytesseract
from PIL import Image
image = cv2.imread("fis.jpg")
gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
# Küçük metni ~300 DPI eşdeğerine ölçekleyin
gray = cv2.resize(gray, None, fx=2, fy=2, interpolation=cv2.INTER_CUBIC)
# Gürültüyü azaltın, ardından Otsu ile saf siyah-beyaza eşikleyin
blur = cv2.GaussianBlur(gray, (5, 5), 0)
_, binary = cv2.threshold(blur, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)
text = pytesseract.image_to_string(Image.fromarray(binary))- Gri tonlama — eşiklemeden önce renk kanallarını kaldırın.
- Ölçekleme — ~20 pikselden küçük metin kötü tanınır; büyütün.
- Eşikleme — düzgün ışıkta Otsu, düzensiz ışıkta uyarlanabilir.
- Gürültü azaltma — hafif bulanıklık, noktalama sanılan lekeleri temizler.
- Eğim düzeltme — OCR öncesi
cv2.minAreaRectile dönüşü düzeltin. - Kenar kırpma — düzen analizini bozan koyu tarama kenarlarını kaldırın.
Konumlar ve güven puanları
Sözcük kutuları ve 0–100 güven için image_to_data kullanın ve gürültüyü filtreleyin.
from pytesseract import Output
data = pytesseract.image_to_data(img, output_type=Output.DICT)
for text, conf in zip(data["text"], data["conf"]):
if text.strip() and float(conf) > 60: # düşük güvenli gürültüyü at
print(round(float(conf)), text)Python'da PDF'ye OCR
Tesseract görsellerle çalışır; önce PDF sayfalarını pdf2image (poppler gerektirir) ile rasterleştirin.
import io, pytesseract
from pdf2image import convert_from_path
from pypdf import PdfWriter, PdfReader
pages = convert_from_path("tarama.pdf", dpi=300) # poppler gerektirir
writer = PdfWriter()
for page in pages:
pdf_bytes = pytesseract.image_to_pdf_or_hocr(page, extension="pdf")
writer.add_page(PdfReader(io.BytesIO(pdf_bytes)).pages[0])
with open("tarama_aranabilir.pdf", "wb") as f:
writer.write(f)Windows'ta poppler bin klasörünü poppler_path= ile verin. Daha kapsamlı bir akış için çıktı biçimleri belgelerine bakın.
Performans
pytesseract her çağrıda CLI'yi çalıştırır, bu yüzden verim yapıya bağlıdır.
| Yaklaşım | Ne zaman | Ödünleşim |
|---|---|---|
Çağrı başına pytesseract | Betikler ve tek seferlik işler | Her çağrıda süreç başlatır — döngüde yavaş |
| Çok sayfalı TIFF'te gruplama | Çok sayfa, aynı ayarlar | Tek süreçte çok sayfa |
multiprocessing | Çok sayıda bağımsız görsel | Tüm çekirdekleri kullanır; daha çok bellek |
tesserocr | Yüksek hacim, süreç içi | Yerel bağlayıcı, daha fazla kurulum |
Hata kataloğu
Aşağıdaki hatalar pytesseract sorunlarının çoğunu kapsar.
| Hata | Neden | Çözüm |
|---|---|---|
TesseractNotFoundError | İkili dosya kurulu değil veya PATH dışında | Motoru kurun veya pytesseract.pytesseract.tesseract_cmd ayarlayın. |
(-215:Assertion failed) src.type() == CV_8UC1 | 3 kanallı görsele eşikleme | Önce cv2.cvtColor(img, cv2.COLOR_BGR2GRAY) ile dönüştürün. |
Error opening data file ...fra.traineddata | Dil paketi eksik | Dili kurun veya TESSDATA_PREFIX ayarlayın. |
| Boş çıktı | Düşük DPI, yanlış PSM veya metin yok | Ölçekleyin, --psm 6/7/11 deneyin ve ön işleyin. |
| Döngüde çok yavaş | Çağrı başına bir süreç | Gruplayın, multiprocessing veya tesserocr kullanın. |
Doğruluğu ölçme
Çıktıyı gözle değerlendirmek yerine karakter ve sözcük hata oranlarını ölçün.
import pytesseract, jiwer
from PIL import Image
hypothesis = pytesseract.image_to_string(Image.open("ornek.png"))
reference = open("ornek.gt.txt").read()
print("CER:", jiwer.cer(reference, hypothesis))
print("WER:", jiwer.wer(reference, hypothesis))Temsili görselleri referans metinleriyle birlikte küçük bir regresyon testi olarak tutun ve ön işleme veya yapılandırmayı değiştirdiğinizde yeniden çalıştırın.
Python SSS
Python'da Tesseract OCR'ı nasıl kullanırım?
Önce motoru, sonra pip install pytesseract pillow kurun. Görseli Pillow ile açın ve pytesseract.image_to_string(img) çağırın.
Neden TesseractNotFoundError alıyorum?
pytesseract ikili dosyayı bulamıyor. Motoru kurun, PATH'e ekleyin veya pytesseract.pytesseract.tesseract_cmd değerini tam yola ayarlayın.
Doğruluğu nasıl artırırım?
~300 DPI'a ölçekleyin, gri tonlama, eşikleme, gürültü azaltma, eğim düzeltme ve doğru --psm. Uygun lang= ve sabit alanlar için karakter beyaz listesi kullanın.
PDF'ye OCR nasıl uygularım?
pdf2image (poppler ile) sayfaları görsele dönüştürün, her sayfada pytesseract çalıştırın ve image_to_pdf_or_hocr(..., extension="pdf") ile birleştirin.
Güven puanlarını nasıl alırım?
image_to_data(..., output_type=Output.DICT) kullanın ve conf listesine göre filtreleyin.
pytesseract yavaş mı?
Her çağrı bir süreç başlatır. Gruplayın, multiprocessing kullanın veya süreç içi tesserocr bağlayıcısına geçin.
Sonraki adımlar
Motor ve ekosistemde derinleşin.