hs.ocr
ModuleRecognize text in images using Apple's Vision framework.
hs.ocr provides access to on-device text recognition without requiring
network access or any third-party dependencies. Pass a file path to
recognizeText() and receive back an HSOCRResult containing the full
recognized text and individual per-region observations with confidence
scores and normalized bounding boxes.
- Example:
// Basic: print all text found in an image
hs.ocr.recognizeText('/tmp/screenshot.png')
.then(result => {
console.log(result.text)
})
.catch(err => console.log('OCR failed: ' + err))
- Example:
// Advanced: filter to high-confidence observations only
const result = await hs.ocr.recognizeText('/tmp/photo.png', {
minimumConfidence: 0.8,
recognitionLevel: 'accurate'
})
result.observations.forEach(obs => {
const b = obs.bounds
console.log(obs.text + ' at (' + b.x.toFixed(3) + ', ' + b.y.toFixed(3) + ') ' + b.w.toFixed(3) + 'x' + b.h.toFixed(3))
})
Types
This module provides the following types:
Properties
This module has no properties.
Methods
hs.ocr.recognizeText(path, options) -> Promise<HSOCRResult>
Recognize text in the image at the given file path.
Returns a Promise that resolves with an `HSOCRResult` containing all
recognized text and per-region observations. The image must exist on
disk; URLs and data buffers are not supported.
Recognition is performed on a background thread; the main thread is
not blocked during the operation.
`"accurate"` uses a larger neural network for better results;
`"fast"` trades accuracy for speed.
Observations whose `confidence` is below this threshold are excluded
from `result.observations` (and therefore from `result.text`).
Hints Vision toward specific languages. Use `supportedLanguages()` to
enumerate the available codes for the current device.
When `true`, Vision selects recognition languages automatically.
Overrides `languages` when set.
Declaration
hs.ocr.recognizeText(path, options) -> Promise<HSOCRResult>Parameters
| Name | Type | Description |
|---|---|---|
| path | string | Absolute path to the image file. |
| options | JSValue | Optional configuration object (see description). |
Returns
Promise<HSOCRResult>
Resolves with the recognition result.
Example
// Async/await style
async function getTextFromImage(imagePath) {
const result = await hs.ocr.recognizeText(imagePath)
return result.text
}// Promise chain style, with options
hs.ocr.recognizeText('/tmp/image.png', { minimumConfidence: 0.75 })
.then(result => console.log('Found ' + result.observations.length + ' regions'))
.catch(err => console.log('Error: ' + err))hs.ocr.supportedLanguages() -> string[]
Returns the BCP-47 language codes supported by the Vision text recognizer
on this device.
The set of languages varies between macOS versions and hardware. Call
this at runtime to discover which codes are valid for the `languages`
option passed to `recognizeText()`.
Declaration
hs.ocr.supportedLanguages() -> string[]Returns
string[]
An array of BCP-47 language code strings (e.g. `["en-US", "fr-FR"]`).
Example
const langs = hs.ocr.supportedLanguages()
console.log('Supported languages: ' + langs.join(', '))