diff --git a/npmextra.json b/npmextra.json index 26688a6..778e506 100644 --- a/npmextra.json +++ b/npmextra.json @@ -8,14 +8,25 @@ "shortDescription": "an ocr module using ocrmypdf", "npmPackagename": "@push.rocks/smartocr", "license": "MIT", - "projectDomain": "push.rocks" + "projectDomain": "push.rocks", + "description": "A module that performs optical character recognition (OCR) using ocrmypdf.", + "keywords": [ + "OCR", + "optical character recognition", + "ocrmypdf", + "text extraction", + "PDF processing", + "machine learning", + "document analysis", + "text recognition" + ] } }, "npmci": { "npmGlobalTools": [], "npmAccessLevel": "public" }, - "tsdocs": { + "tsdoc": { "legal": "\n## License and Legal Information\n\nThis 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. \n\n**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.\n\n### Trademarks\n\nThis 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.\n\n### Company Information\n\nTask Venture Capital GmbH \nRegistered at District court Bremen HRB 35230 HB, Germany\n\nFor any legal inquiries or if you require further information, please contact us via email at hello@task.vc.\n\nBy 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.\n" } } \ No newline at end of file diff --git a/package.json b/package.json index da3868a..d510b53 100644 --- a/package.json +++ b/package.json @@ -2,7 +2,7 @@ "name": "@push.rocks/smartocr", "version": "1.0.8", "private": false, - "description": "an ocr module using ocrmypdf", + "description": "A module that performs optical character recognition (OCR) using ocrmypdf.", "main": "dist_ts/index.js", "typings": "dist_ts/index.d.ts", "author": "Lossless GmbH", @@ -40,5 +40,15 @@ "cli.js", "npmextra.json", "readme.md" + ], + "keywords": [ + "OCR", + "optical character recognition", + "ocrmypdf", + "text extraction", + "PDF processing", + "machine learning", + "document analysis", + "text recognition" ] } \ No newline at end of file diff --git a/readme.hints.md b/readme.hints.md new file mode 100644 index 0000000..0519ecb --- /dev/null +++ b/readme.hints.md @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/readme.md b/readme.md index 6574e31..f9959bc 100644 --- a/readme.md +++ b/readme.md @@ -1,39 +1,90 @@ -# @pushrocks/smartocr +# @push.rocks/smartocr an ocr module using ocrmypdf -## Availabililty and Links -* [npmjs.org (npm package)](https://www.npmjs.com/package/@pushrocks/smartocr) -* [gitlab.com (source)](https://gitlab.com/pushrocks/smartocr) -* [github.com (source mirror)](https://github.com/pushrocks/smartocr) -* [docs (typedoc)](https://pushrocks.gitlab.io/smartocr/) +## Install +To install `@push.rocks/smartocr`, use the following command with npm: -## Status for master +```bash +npm install @push.rocks/smartocr --save +``` -Status Category | Status Badge --- | -- -GitLab Pipelines | [![pipeline status](https://gitlab.com/pushrocks/smartocr/badges/master/pipeline.svg)](https://lossless.cloud) -GitLab Pipline Test Coverage | [![coverage report](https://gitlab.com/pushrocks/smartocr/badges/master/coverage.svg)](https://lossless.cloud) -npm | [![npm downloads per month](https://badgen.net/npm/dy/@pushrocks/smartocr)](https://lossless.cloud) -Snyk | [![Known Vulnerabilities](https://badgen.net/snyk/pushrocks/smartocr)](https://lossless.cloud) -TypeScript Support | [![TypeScript](https://badgen.net/badge/TypeScript/>=%203.x/blue?icon=typescript)](https://lossless.cloud) -node Support | [![node](https://img.shields.io/badge/node->=%2010.x.x-blue.svg)](https://nodejs.org/dist/latest-v10.x/docs/api/) -Code Style | [![Code Style](https://badgen.net/badge/style/prettier/purple)](https://lossless.cloud) -PackagePhobia (total standalone install weight) | [![PackagePhobia](https://badgen.net/packagephobia/install/@pushrocks/smartocr)](https://lossless.cloud) -PackagePhobia (package size on registry) | [![PackagePhobia](https://badgen.net/packagephobia/publish/@pushrocks/smartocr)](https://lossless.cloud) -BundlePhobia (total size when bundled) | [![BundlePhobia](https://badgen.net/bundlephobia/minzip/@pushrocks/smartocr)](https://lossless.cloud) -Platform support | [![Supports Windows 10](https://badgen.net/badge/supports%20Windows%2010/yes/green?icon=windows)](https://lossless.cloud) [![Supports Mac OS X](https://badgen.net/badge/supports%20Mac%20OS%20X/yes/green?icon=apple)](https://lossless.cloud) +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 -Use TypeScript for best in class intellisense +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. -## Contribution +### Preparing Your Project -We are always happy for code contributions. If you are not the code contributing type that is ok. Still, maintaining Open Source repositories takes considerable time and thought. If you like the quality of what we do and our modules are useful to you we would appreciate a little monthly contribution: You can [contribute one time](https://lossless.link/contribute-onetime) or [contribute monthly](https://lossless.link/contribute). :) +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. -For further information read the linked docs at the top of this readme. +### Basic Setup -> MIT licensed | **©** [Lossless GmbH](https://lossless.gmbh) -| By using this npm module you agree to our [privacy policy](https://lossless.gmbH/privacy) +```typescript +import { SmartOcr } from '@push.rocks/smartocr'; -[![repo-footer](https://lossless.gitlab.io/publicrelations/repofooter.svg)](https://maintainedby.lossless.com) +async function runOcrOnPdf(pdfFilePath: string): Promise { + // 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.