OCR

sikuli-go provides OCR APIs in Finder and Region:

By default, OCR is disabled at build time and these APIs return ErrBackendUnsupported.

Enable gosseract backend

sikuli-go includes an optional OCR backend adapter for:

Native runtime requirements:

Build or test with OCR enabled:

go test -tags gosseract ./...
go build -tags gosseract ./...

macOS setup (Homebrew)

Install native dependencies:

brew install leptonica tesseract pkg-config

Export build/link flags (Apple Silicon/Homebrew):

export HOMEBREW_PREFIX="$(brew --prefix)"
export PKG_CONFIG_PATH="$HOMEBREW_PREFIX/lib/pkgconfig:$PKG_CONFIG_PATH"
export CGO_CFLAGS="-I$HOMEBREW_PREFIX/include"
export CGO_CPPFLAGS="-I$HOMEBREW_PREFIX/include"
export CGO_LDFLAGS="-L$HOMEBREW_PREFIX/lib -llept -ltesseract"

Validate package config and run tests:

pkg-config --cflags lept tesseract
pkg-config --libs lept tesseract
go clean -cache -testcache
go test -tags gosseract ./internal/ocr ./pkg/sikuli

If you see ld: library 'lept' not found, create compatibility symlinks:

sudo ln -sf "$(brew --prefix leptonica)/lib/libleptonica.dylib" /opt/homebrew/lib/liblept.dylib
sudo ln -sf "$(brew --prefix leptonica)/lib/libleptonica.dylib" /usr/local/lib/liblept.dylib

macOS troubleshooting: fatal error: 'leptonica/allheaders.h' file not found

This means the compiler cannot find Leptonica headers while building the gosseract CGO path.

  1. Verify dependencies are installed:
brew install leptonica tesseract pkg-config
  1. Confirm where allheaders.h is located:
find /opt/homebrew /usr/local -name "allheaders.h" 2>/dev/null
  1. Prefer pkg-config + Homebrew prefix exports (portable across Intel/Apple Silicon):
export HOMEBREW_PREFIX="$(brew --prefix)"
export PKG_CONFIG_PATH="$HOMEBREW_PREFIX/lib/pkgconfig:$PKG_CONFIG_PATH"
export CGO_CFLAGS="-I$HOMEBREW_PREFIX/include"
export CGO_CPPFLAGS="-I$HOMEBREW_PREFIX/include"
export CGO_CXXFLAGS="-I$HOMEBREW_PREFIX/include"
export CGO_LDFLAGS="-L$HOMEBREW_PREFIX/lib -llept -ltesseract"
  1. If your headers/libs are versioned under Cellar and still not found, export explicit paths:
export LEPT_PREFIX="$(brew --prefix leptonica)"
export TESS_PREFIX="$(brew --prefix tesseract)"
export CGO_CFLAGS="-I$LEPT_PREFIX/include -I$TESS_PREFIX/include"
export CGO_CPPFLAGS="-I$LEPT_PREFIX/include -I$TESS_PREFIX/include"
export CGO_CXXFLAGS="-I$LEPT_PREFIX/include -I$TESS_PREFIX/include"
export CGO_LDFLAGS="-L$LEPT_PREFIX/lib -L$TESS_PREFIX/lib -llept -ltesseract"
  1. Validate and retry:
pkg-config --cflags lept tesseract
pkg-config --libs lept tesseract
go clean -cache -testcache
go test -tags gosseract ./internal/ocr ./pkg/sikuli

OCR parameters

OCRParams supports:

Example

txt, err := finder.ReadText(sikuli.OCRParams{
  Language: "eng",
})

matches, err := finder.FindText("Submit", sikuli.OCRParams{
  MinConfidence: 0.6,
})