app.ocr - Text Recognition API

Optical character recognition (OCR) based on the Vision framework.

Requires macOS 10.15+

Methods

app.ocr.recognize(imagePath, options?)

Recognize text in an image.

Parameters:

• imagePath (string) - image file path
• options (table, optional):
  • language (string|array) - recognition language (e.g., "zh-Hans", {"zh-Hans", "en"})
  • level (string) - recognition level: "accurate" (default) or "fast"
  • rect (table) - recognition region (pixel coordinates): {x, y, w, h}

Returns: array<table>, error - each item contains:

• text (string) - recognized text
• confidence (number) - confidence score (0.0-1.0)

-- Recognize entire image
local results, err = app.ocr.recognize("/path/to/image.png")
if results then
    for _, item in ipairs(results) do
        app.log.info(item.text .. " (" .. string.format("%.0f%%", item.confidence * 100) .. ")")
    end
end

-- Specify language and region
local results = app.ocr.recognize("/path/to/image.png", {
    language = {"zh-Hans", "en"},
    level = "accurate",
    rect = {x = 100, y = 50, w = 500, h = 200}
})

app.ocr.recognizeFromScreen(options?)

Capture the screen and recognize text.

Parameters:

• options (table, optional):
  • displayId (number) - display ID
  • rect (table) - capture region: {x, y, w, h}
  • language (string|array) - recognition language
  • level (string) - recognition level

Returns: array<table>, error - same as recognize()

-- Capture entire screen and recognize
local results, err = app.ocr.recognizeFromScreen()

-- Capture specific region
local results = app.ocr.recognizeFromScreen({
    rect = {x = 0, y = 0, w = 800, h = 600},
    language = "en"
})

app.ocr.languages()

Get the list of OCR languages supported by the system.

Returns: array<string>, error

local langs = app.ocr.languages()
-- {"en-US", "fr-FR", "it-IT", "de-DE", "es-ES", "pt-BR", "zh-Hans", "zh-Hant", ...}

Examples

Extract Text from an Image

function MyPlugin:handleOCR(context)
    local file = context.selectedFiles[1]

    app.progress.show("Recognizing", {message = "Recognizing text..."})
    local results, err = app.ocr.recognize(file, {
        language = {"zh-Hans", "en"},
        level = "accurate"
    })
    app.progress.hide()

    if not results then
        app.dialog.alert("Error", err or "Recognition failed")
        return
    end

    if #results == 0 then
        app.dialog.alert("Result", "No text recognized")
        return
    end

    local text = ""
    for _, item in ipairs(results) do
        text = text .. item.text .. "\n"
    end

    app.clipboard.setText(text)
    app.notification.show("Done", "Recognized " .. #results .. " text segments, copied to clipboard")
end