---
title: "@push.rocks/smartocr"
---
# @push.rocks/smartocr
an ocr module using ocrmypdf

## Install
To install `@push.rocks/smartocr`, use the following command with npm:

```bash
npm install @push.rocks/smartocr --save
```

This module depends on a few external utilities like `ocrmypdf`, so make sure you have these installed and available in your system's PATH. Consult the `ocrmypdf` documentation for installation instructions suitable for your operating system.

## Usage

This module provides a TypeScript interface for OCR processing of PDF documents using `ocrmypdf`, encapsulated in the `SmartOcr` class. Here's how to leverage it in your TypeScript project.

### Preparing Your Project

First, ensure your TypeScript configuration is set up to handle ESModule syntax. You will also need to have Node.js and the external `ocrmypdf` tool installed on your system.

### Basic Setup

```typescript
import { SmartOcr } from '@push.rocks/smartocr';

async function runOcrOnPdf(pdfFilePath: string): Promise<Buffer> {
  // Initialize the SmartOcr instance
  const smartOcrInstance = await SmartOcr.createAndInit();

  // Load your PDF file into a Buffer, this can be from a file or even a remote source
  const pdfBuffer = await fs.promises.readFile(pdfFilePath);

  // Process the PDF Buffer through SmartOcr
  const processedBuffer = await smartOcrInstance.processPdfBuffer(pdfBuffer);

  return processedBuffer;
}

// Replace './path/to/your/document.pdf' with the actual path to the PDF document you want to OCR
const ocredPdfBuffer = await runOcrOnPdf('./path/to/your/document.pdf');

// You can now save this buffer to a file, or use it as needed in your application
await fs.promises.writeFile('./path/to/output/document_ocr.pdf', ocredPdfBuffer);
```

In the example above, we import the `SmartOcr` class and use it to process a PDF by passing a `Buffer` of the PDF file to the `processPdfBuffer` method. The method returns a `Buffer` of the processed PDF which includes a text layer added by OCR.

### Advanced Usage

The `SmartOcr` class maintains an internal `smartshell` instance to interface with the `ocrmypdf` command. This setup is abstracted away, ensuring you don't need to manage or understand the underlying shell commands to use OCR functionality in your application.

### Handling OCR Result

The result of the `processPdfBuffer` is a `Buffer` that contains the OCR-processed PDF. This buffer can be directly written to a file system or further manipulated in memory, depending on your application's needs.

### Error Handling

It's important to handle errors that may arise from reading files or the OCR process. The OCR process depends on the external `ocrmypdf` utility, so errors can occur if the utility encounters unsupported PDF structures or if there are issues with the installation of `ocrmypdf`.

```typescript
try {
  const ocredPdfBuffer = await runOcrOnPdf('./path/to/your/document.pdf');
  await fs.promises.writeFile('./path/to/output/document_ocr.pdf', ocredPdfBuffer);
} catch (error) {
  console.error('Failed to OCR the document:', error);
}
```

### Conclusion

The `@push.rocks/smartocr` library simplifies adding OCR capabilities to your TypeScript applications by abstracting away the complexity of interfacing with `ocrmypdf`. With minimal setup, you can start processing PDF documents to add searchable text layers, making this library a valuable tool for any project that requires OCR functionality.

## License and Legal Information

This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. 

**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

### Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.

### Company Information

Task Venture Capital GmbH  
Registered at District court Bremen HRB 35230 HB, Germany

For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.
