@luii/node-tesseract-ocr 1.0.19 → 2.0.0

package/CMakeLists.txt

@@ -0,0 +1,45 @@
+cmake_minimum_required(VERSION 3.10...4.2.1)
+project(node-tesseract-ocr)
+add_compile_definitions(NAPI_VERSION=10)
+set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
+
+file(GLOB SOURCE_FILES "src/*.cpp" "src/*.hpp")
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+
+if(APPLE)
+  set(CMAKE_OSX_DEPLOYMENT_TARGET "14.0" CACHE STRING "" FORCE)
+endif()
+
+add_library(${PROJECT_NAME} SHARED ${SOURCE_FILES} ${CMAKE_JS_SRC})
+set_target_properties(${PROJECT_NAME} PROPERTIES PREFIX "" SUFFIX ".node")
+
+find_package(PkgConfig REQUIRED)
+pkg_check_modules(TESS REQUIRED IMPORTED_TARGET "tesseract>=5")
+pkg_check_modules(LEPT REQUIRED IMPORTED_TARGET "lept>=1.74")
+
+target_include_directories(${PROJECT_NAME} PRIVATE 
+  ${CMAKE_JS_INC}
+  ${TESS_INCLUDE_DIRS}
+  ${LEPT_INCLUDE_DIRS}
+)
+
+if(APPLE)
+  foreach(dir IN LISTS LEPT_INCLUDE_DIRS)
+    target_include_directories(${PROJECT_NAME} PRIVATE "${dir}/..")
+  endforeach()
+endif()
+
+target_link_libraries(${PROJECT_NAME} PRIVATE 
+  ${CMAKE_JS_LIB}
+  PkgConfig::TESS
+  PkgConfig::LEPT
+)
+target_compile_features(${PROJECT_NAME} PRIVATE cxx_std_20)
+
+if(MSVC AND CMAKE_JS_NODELIB_DEF AND CMAKE_JS_NODELIB_TARGET)
+  # Generate node.lib
+  execute_process(COMMAND ${CMAKE_AR} /def:${CMAKE_JS_NODELIB_DEF} /out:${CMAKE_JS_NODELIB_TARGET} ${CMAKE_STATIC_LINKER_FLAGS})
+endif()

package/README.md

@@ -1,134 +1,506 @@
 # node-tesseract-ocr
 
-C++ Addon for Node.js, that uses Tesseract OCR (`libtesseract-dev`) in JavaScript/TypeScript.
+Native C++ addon for Node.js that exposes Tesseract OCR (`libtesseract-dev`) to JavaScript/TypeScript.
+
+## Table of Contents
+
+- [Features](#features)
+- [Prerequisites](#prerequisites)
+- [Install](#install)
+  - [Install additional training data](#install-additional-training-data)
+- [Build](#build)
+- [Start](#start)
+- [Scripts](#scripts)
+- [Examples](#examples)
+- [Public API](#public-api)
+  - [Enums](#enums)
+  - [Types](#types)
+  - [Tesseract API](#tesseract-api)
+- [Example](#example)
+- [License](#license)
+- [Special Thanks](#special-thanks)
+
+## Features
+
+- Native bindings to Tesseract (prebuilds via `pkg-prebuilds`)
+- Access to Tesseract enums and configuration from TypeScript
+- Progress callback and multiple output formats
+
+## Prerequisites
 
-Status: **WIP**
+- nodejs
+- node-addon-api
+- c++ build toolchain (e.g. build-essentials)
+- libtesseract-dev
+- libleptonica-dev
+- Tesseract training data (eng, deu, ...)
+
+> See [Install](#install)
+
+## Install
+
+```bash
+sudo apt update
+sudo apt install -y nodejs npm build-essential pkg-config libtesseract-dev libleptonica-dev tesseract-ocr-eng
+```
+
+```bash
+git clone git@github.com:luii/node-tesseract-ocr.git
+cd node-tesseract-ocr
+npm install
+```
+
+### Install additional training data
+
+On Debian/Ubuntu, language data is provided as packages named `tesseract-ocr-<lang>`.
+Install additional languages as needed, for example:
+
+```bash
+sudo apt install -y tesseract-ocr-deu tesseract-ocr-eng tesseract-ocr-jpn
+```
+
+If you install traineddata files manually, make sure `NODE_TESSERACT_DATAPATH` points to the directory that contains them (for example `/usr/share/tesseract-ocr/5/tessdata`).
+
+## Build
+
+```bash
+# Debug build (native addon + TS outputs)
+npm run build:debug
+
+# Release build
+npm run build:release
+```
+
+## Start
+
+Set `NODE_TESSERACT_DATAPATH` to your traineddata directory (usually `/usr/share/tesseract-ocr/5/tessdata`).
+
+```sh
+env NODE_TESSERACT_DATAPATH=/usr/share/tesseract-ocr/5/tessdata node path/to/your/app.js
+```
+
+## Scripts
+
+```bash
+# Build native addon + TS outputs (debug / release)
+npm run build:debug
+npm run build:release
 
-Lizenz: **Apache-2.0**
+# Build precompiled binaries for distribution
+npm run prebuild
+
+# Run the JS example (builds debug first)
+npm run example:recognize
+
+# Tests
+npm run test:cpp
+npm run test:js
+npm run test:js:watch
+```
+
+## Examples
+
+```sh
+env NODE_TESSERACT_DATAPATH=/usr/share/tesseract-ocr/5/tessdata npm run example:recognize
+```
 
 ## Public API
 
-### Class: `Tesseract`
+### Enums
+
+#### `Language`
+
+Mapping of available Tesseract language codes. Most are [_3-letter ISO 639-2/T style_](https://en.wikipedia.org/wiki/List_of_ISO_639-2_codes) (e.g. `eng`, `deu`, `jpn`), with Tesseract-specific variants such as `chi_sim`, `deu_latf`, or `osd`. The value must match the installed traineddata filename (without the `.traineddata` suffix). You can pass a single code via `TesseractInitOptions.lang`.
+
+> [!IMPORTANT]
+> **If you join codes with a plus sign (e.g. `deu+eng`), Tesseract will look for multiple languages in the same image (here: German and English).**
+
+#### `OcrEngineMode`
+
+Full list of OCR engine modes from Tesseract.
 
-#### TesseractOptions
+| Name                          | Value | Deprecated | Description                                                |
+| ----------------------------- | ----- | ---------- | ---------------------------------------------------------- |
+| `OEM_TESSERACT_ONLY`          | 0     | Yes        | Run Tesseract only (fastest).                              |
+| `OEM_LSTM_ONLY`               | 1     | No         | Run only the LSTM line recognizer.                         |
+| `OEM_TESSERACT_LSTM_COMBINED` | 2     | Yes        | Run LSTM with fallback to Tesseract.                       |
+| `OEM_DEFAULT`                 | 3     | No         | Infer engine mode from configs; default is Tesseract-only. |
+
+#### `PageSegmentationMode`
+
+Full list of page segmentation modes from Tesseract.
+
+| Name                         | Value | Deprecated | Description                                               |
+| ---------------------------- | ----- | ---------- | --------------------------------------------------------- |
+| `PSM_OSD_ONLY`               | 0     | No         | Orientation and script detection only.                    |
+| `PSM_AUTO_OSD`               | 1     | No         | Automatic page segmentation with OSD.                     |
+| `PSM_AUTO_ONLY`              | 2     | No         | Automatic page segmentation, no OSD or OCR.               |
+| `PSM_AUTO`                   | 3     | No         | Fully automatic page segmentation, no OSD.                |
+| `PSM_SINGLE_COLUMN`          | 4     | No         | Assume a single column of text of variable sizes.         |
+| `PSM_SINGLE_BLOCK_VERT_TEXT` | 5     | No         | Assume a single uniform block of vertically aligned text. |
+| `PSM_SINGLE_BLOCK`           | 6     | No         | Assume a single uniform block of text (default).          |
+| `PSM_SINGLE_LINE`            | 7     | No         | Treat the image as a single text line.                    |
+| `PSM_SINGLE_WORD`            | 8     | No         | Treat the image as a single word.                         |
+| `PSM_CIRCLE_WORD`            | 9     | No         | Treat the image as a single word in a circle.             |
+| `PSM_SINGLE_CHAR`            | 10    | No         | Treat the image as a single character.                    |
+| `PSM_SPARSE_TEXT`            | 11    | No         | Find as much text as possible in no particular order.     |
+| `PSM_SPARSE_TEXT_OSD`        | 12    | No         | Sparse text with orientation and script detection.        |
+| `PSM_RAW_LINE`               | 13    | No         | Single text line, bypassing Tesseract-specific hacks.     |
+
+### Types
+
+#### `TesseractInitOptions`
+
+| Field                   | Type                                                                                                  | Optional | Default     | Description                             |
+| ----------------------- | ----------------------------------------------------------------------------------------------------- | -------- | ----------- | --------------------------------------- |
+| `lang`                  | [`Language[]`](#availablelanguages)                                                                   | Yes      | `undefined` | Languages to load as an array.          |
+| `oem`                   | [`OcrEngineMode`](#ocrenginemode)                                                                     | Yes      | `undefined` | OCR engine mode.                        |
+| `vars`                  | `Partial<Record<keyof ConfigurationVariables, ConfigurationVariables[keyof ConfigurationVariables]>>` | Yes      | `undefined` | Variables to set.                       |
+| `configs`               | `Array<string>`                                                                                       | Yes      | `undefined` | Tesseract config files to apply.        |
+| `setOnlyNonDebugParams` | `boolean`                                                                                             | Yes      | `undefined` | If true, only non-debug params are set. |
+
+#### `TesseractSetRectangleOptions`
+
+| Field    | Type     | Optional | Default | Description       |
+| -------- | -------- | -------- | ------- | ----------------- |
+| `top`    | `number` | No       | n/a     | Top coordinate.   |
+| `left`   | `number` | No       | n/a     | Left coordinate.  |
+| `width`  | `number` | No       | n/a     | Rectangle width.  |
+| `height` | `number` | No       | n/a     | Rectangle height. |
+
+#### `ProgressChangedInfo`
+
+| Field      | Type     | Optional | Default | Description                                |
+| ---------- | -------- | -------- | ------- | ------------------------------------------ |
+| `progress` | `number` | No       | n/a     | Chars in the current buffer.               |
+| `percent`  | `number` | No       | n/a     | Percent complete (0-100).                  |
+| `ocrAlive` | `number` | No       | n/a     | Non-zero if worker is alive.               |
+| `top`      | `number` | No       | n/a     | Top coordinate of current element bbox.    |
+| `right`    | `number` | No       | n/a     | Right coordinate of current element bbox.  |
+| `bottom`   | `number` | No       | n/a     | Bottom coordinate of current element bbox. |
+| `left`     | `number` | No       | n/a     | Left coordinate of current element bbox.   |
+
+#### `DetectOrientationScriptResult`
+
+| Field                   | Type     | Optional | Default | Description                                        |
+| ----------------------- | -------- | -------- | ------- | -------------------------------------------------- |
+| `orientationDegrees`    | `number` | No       | n/a     | Orientation of the source image (0, 90, 180, 270). |
+| `orientationConfidence` | `number` | No       | n/a     | Confidence for the orientation.                    |
+| `scriptName`            | `string` | No       | n/a     | Detected script name.                              |
+| `scriptConfidence`      | `number` | No       | n/a     | Confidence for the script.                         |
+
+### Tesseract API
+
+#### Constructor
 
 ```ts
- {
-    /**
-     * Its generally safer to use as few languages as possible.
-     * The more languages Tesseract needs to load the longer 
-     * it takes to recognize a image.
-     * @public
-     */
-    lang: Array<keyof typeof AvailableLanguages>;
+new Tesseract();
+```
+
+Creates a new Tesseract instance.
 
-    /**
-     * Skip Ocr for when you only want to (for example) analyze the layout
-     * @property {boolean} [skipOcr]
-     */
-    skipOcr?: boolean;
+#### init
 
-    /**
-     * OCR Engine Modes
-     * The engine mode cannot be changed after creating the instance
-     * If another mode is needed, its advised to create a new instance.
-     * @throws {Error} Will throw an error when oem mode is below 0 or over 3
-     */
-    oemMode?: OcrEngineMode;
+Initializes Tesseract with language, engine mode, configs, and variables.
 
-    /**
-     * Page Segmentation Modes
-     * The page segmentation mode cannot be changed after creating the instance
-     * If another mode is needed, its advised to create a new instance.
-     * @throws {Error} Will throw a error when psm mode is below 0 or over 13
-     */
-    psm?: PageSegmentationMode;
-  }
+| Name    | Type                                            | Optional | Default | Description             |
+| ------- | ----------------------------------------------- | -------- | ------- | ----------------------- |
+| options | [`TesseractInitOptions`](#tesseractinitoptions) | No       | n/a     | Initialization options. |
+
+```ts
+init(options: TesseractInitOptions): Promise<void>
 ```
 
-#### constructor(options: TesseractOptions)
+#### initForAnalysePage
+
+Initializes for layout analysis only.
 
 ```ts
-new Tesseract({
-  lang: string,
-  skipOcr: boolean
-})
+initForAnalysePage(): Promise<void>
 ```
 
-##### recognize
+#### analysePage
+
+Runs the layout analysis.
+
+| Name              | Type    | Optional | Default | Description                     |
+| ----------------- | ------- | -------- | ------- | ------------------------------- |
+| mergeSimilarWords | boolean | No       | n/a     | Whether to merge similar words. |
 
 ```ts
-recognize(buffer: Buffer, RecognizeOptions) => Promise<{
-  getText() => string;
-  getHOCR() => string;
-  getTSV() => string;
-  getALTO() => string;
-}>
+analysePage(mergeSimilarWords: boolean): Promise<void>
+```
+
+#### setPageMode
+
+Sets the page segmentation mode.
+
+| Name | Type                                             | Optional | Default | Description             |
+| ---- | ------------------------------------------------ | -------- | ------- | ----------------------- |
+| psm  | [`PageSegmentationMode`](#pagesegmentationmodes) | No       | n/a     | Page segmentation mode. |
 
+```ts
+setPageMode(psm: PageSegmentationMode): Promise<void>
 ```
 
-###### Recognize Options
+#### setVariable
+
+Sets a Tesseract variable. Returns `false` if the lookup failed.
+
+| Name  | Type                                                           | Optional | Default | Description     |
+| ----- | -------------------------------------------------------------- | -------- | ------- | --------------- |
+| name  | keyof SetVariableConfigVariables                               | No       | n/a     | Variable name.  |
+| value | SetVariableConfigVariables\[keyof SetVariableConfigVariables\] | No       | n/a     | Variable value. |
 
 ```ts
-{
-  progressChanged?: ({ 
-    progress: number; 
-    ocrAlive: number;
-    top: number; 
-    right: number; 
-    bottom: number; 
-    left: number;
-  }) => void,
-   
-}
+setVariable(name: keyof SetVariableConfigVariables, value: SetVariableConfigVariables[keyof SetVariableConfigVariables]): Promise<boolean>
 ```
 
-## Prerequisities
+#### getIntVariable
 
-- nodejs
-- python3 (for `node-gyp`)
-- node-addon-api
-- c++ build-toolchain (e.g. build-essentials)
-- libtesseract-dev
-- libleptonica-dev
-- Tesseract Training-data (eng, deu, ...)
+Reads an integer variable from Tesseract.
 
-> See [Install](#install)
+| Name | Type                             | Optional | Default | Description    |
+| ---- | -------------------------------- | -------- | ------- | -------------- |
+| name | keyof SetVariableConfigVariables | No       | n/a     | Variable name. |
 
-## Install
+```ts
+getIntVariable(name: keyof SetVariableConfigVariables): Promise<number>
+```
 
-```bash
-sudo apt update
-sudo apt install -y nodejs npm build-essential python3 pkg-config libtesseract-dev libleptonica-dev tesseract-ocr-eng
+#### getBoolVariable
+
+Reads a boolean variable from Tesseract. Returns `0` or `1`.
+
+| Name | Type                             | Optional | Default | Description    |
+| ---- | -------------------------------- | -------- | ------- | -------------- |
+| name | keyof SetVariableConfigVariables | No       | n/a     | Variable name. |
+
+```ts
+getBoolVariable(name: keyof SetVariableConfigVariables): Promise<number>
 ```
 
-```bash
-git clone git@github.com:luii/node-tesseract-ocr.git
-cd node-tesseract-ocr
-npm install
+#### getDoubleVariable
+
+Reads a double variable from Tesseract.
+
+| Name | Type                             | Optional | Default | Description    |
+| ---- | -------------------------------- | -------- | ------- | -------------- |
+| name | keyof SetVariableConfigVariables | No       | n/a     | Variable name. |
+
+```ts
+getDoubleVariable(name: keyof SetVariableConfigVariables): Promise<number>
 ```
 
-## Build
+#### getStringVariable
 
-```bash
-npm run build
+Reads a string variable from Tesseract.
+
+| Name | Type                             | Optional | Default | Description    |
+| ---- | -------------------------------- | -------- | ------- | -------------- |
+| name | keyof SetVariableConfigVariables | No       | n/a     | Variable name. |
+
+```ts
+getStringVariable(name: keyof SetVariableConfigVariables): Promise<string>
 ```
 
-## Start
+#### setImage
 
-Either set the `NODE_TESSERACT_DATAPATH` beforehand or do it in one go, it needs to point to where the training data is located.
-On a standard install this is usually `/usr/share/tesseract-ocr/5/tessdata`
+Sets the image from a Buffer.
 
-```bash
-NODE_TESSERACT_DATAPATH=/usr/share/tesseract-ocr/5/tessdata npm run dev
+| Name   | Type   | Optional | Default | Description |
+| ------ | ------ | -------- | ------- | ----------- |
+| buffer | Buffer | No       | n/a     | Image data. |
+
+```ts
+setImage(buffer: Buffer): Promise<void>
 ```
 
-## Examples
+#### setRectangle
 
-```bash
-NODE_TESSERACT_DATAPATH=/usr/share/tesseract-ocr/5/tessdata npm run examples:recognize
+Sets the image region using coordinates and size.
+
+| Name    | Type                                                            | Optional | Default | Description        |
+| ------- | --------------------------------------------------------------- | -------- | ------- | ------------------ |
+| options | [`TesseractSetRectangleOptions`](#tesseractsetrectangleoptions) | No       | n/a     | Region definition. |
+
+```ts
+setRectangle(options: TesseractSetRectangleOptions): Promise<void>
+```
+
+#### setSourceResolution
+
+Sets the source resolution in PPI.
+
+| Name | Type   | Optional | Default | Description      |
+| ---- | ------ | -------- | ------- | ---------------- |
+| ppi  | number | No       | n/a     | Pixels per inch. |
+
+```ts
+setSourceResolution(ppi: number): Promise<void>
+```
+
+#### recognize
+
+Starts OCR and calls the callback with progress info.
+
+| Name             | Type                                                          | Optional | Default | Description        |
+| ---------------- | ------------------------------------------------------------- | -------- | ------- | ------------------ |
+| progressCallback | (info: [`ProgressChangedInfo`](#progresschangedinfo)) => void | No       | n/a     | Progress callback. |
+
+```ts
+recognize(progressCallback: (info: ProgressChangedInfo) => void): Promise<void>
 ```
 
+#### getUTF8Text
+
+Returns recognized text as UTF-8.
+
+```ts
+getUTF8Text(): Promise<string>
+```
+
+#### getHOCRText
+
+Returns HOCR output. Optional progress callback and page number.
+
+| Name             | Type                                                          | Optional | Default   | Description            |
+| ---------------- | ------------------------------------------------------------- | -------- | --------- | ---------------------- |
+| progressCallback | (info: [`ProgressChangedInfo`](#progresschangedinfo)) => void | Yes      | undefined | Progress callback.     |
+| pageNumber       | number                                                        | Yes      | undefined | Page number (0-based). |
+
+```ts
+getHOCRText(
+  progressCallback?: (info: ProgressChangedInfo) => void,
+  pageNumber?: number,
+): Promise<string>
+```
+
+#### getTSVText
+
+Returns TSV output.
+
+```ts
+getTSVText(): Promise<string>
+```
+
+#### getUNLVText
+
+Returns UNLV output.
+
+```ts
+getUNLVText(): Promise<string>
+```
+
+#### getALTOText
+
+Returns ALTO output. Optional progress callback and page number.
+
+| Name             | Type                                                          | Optional | Default   | Description            |
+| ---------------- | ------------------------------------------------------------- | -------- | --------- | ---------------------- |
+| progressCallback | (info: [`ProgressChangedInfo`](#progresschangedinfo)) => void | Yes      | undefined | Progress callback.     |
+| pageNumber       | number                                                        | Yes      | undefined | Page number (0-based). |
+
+```ts
+getALTOText(
+  progressCallback?: (info: ProgressChangedInfo) => void,
+  pageNumber?: number,
+): Promise<string>
+```
+
+#### detectOrientationScript
+
+Detects orientation and script with confidences. Returns [`DetectOrientationScriptResult`](#detectorientationscriptresult).
+
+```ts
+detectOrientationScript(): Promise<DetectOrientationScriptResult>
+```
+
+#### meanTextConf
+
+Mean text confidence (0-100).
+
+```ts
+meanTextConf(): Promise<number>
+```
+
+#### getInitLanguages
+
+Returns [`Language`](#availablelanguages) in raw Tesseract format (e.g. "deu+eng").
+
+```ts
+getInitLanguages(): Promise<string>
+```
+
+#### getLoadedLanguages
+
+Returns [`Language[]`](#availablelanguages) in raw Tesseract format.
+
+```ts
+getLoadedLanguages(): Promise<Language[]>
+```
+
+#### getAvailableLanguages
+
+Returns [`Language[]`](#availablelanguages) in raw Tesseract format.
+
+```ts
+getAvailableLanguages(): Promise<Language[]>
+```
+
+#### clear
+
+Clears internal state.
+
+```ts
+clear(): Promise<void>
+```
+
+#### end
+
+Ends the instance.
+
+```ts
+end(): Promise<void>
+```
+
+## Example
+
+You can find a similar example in the `examples/` folder of the project
+
+```ts
+import fs from "node:fs";
+import Tesseract, { OcrEngineModes } from "node-tesseract-ocr";
+
+async function main() {
+  const tesseract = new Tesseract();
+  await tesseract.init({
+    lang: ["eng"],
+    oem: OcrEngineModes.OEM_LSTM_ONLY,
+  });
+
+  const buffer = fs.readFileSync("example1.png");
+  await tesseract.setImage(buffer);
+  await tesseract.recognize((info) => {
+    console.log(`Progress: ${info.percent}%`);
+  });
+
+  const text = await tesseract.getUTF8Text();
+  console.log(text);
+
+  await tesseract.end();
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});
+```
+
+## License
+
+Apache-2.0. See [`LICENSE.md`](/LICENSE.md) for full terms.
+
 ## Special Thanks
 
 - **Stunt3000**