Merge branch 'naptha:master' into master

.gitpod.yml

@@ -1,7 +1,7 @@
 image:
   file: .gitpod.Dockerfile
 tasks:
-  - command: gp await-port 3000 && sleep 3 && gp preview $(gp url 3000)/examples/browser/demo.html
+  - command: gp await-port 3000 && sleep 3 && gp preview $(gp url 3000)/examples/browser/basic-efficient.html
   - init: npm install
     command: npm start
 ports:

README.md

@@ -81,6 +81,21 @@ yarn add tesseract.js@3.0.3
 * [Local Installation](./docs/local-installation.md)
 * [FAQ](./docs/faq.md)
 
+## Community Projects and Examples
+The following are examples and projects built by the community using Tesseract.js. Officially supported examples are found in the [examples](https://github.com/naptha/tesseract.js/tree/master/examples) directory. 
+
+- Projects
+   - Scribe OCR: web application for scanning documents (images and PDFs)
+      - Site at [scribeocr.com](https://scribeocr.com/), repo at [github.com/scribeocr/scribeocr](https://github.com/scribeocr/scribeocr)
+   - Chrome Extension (with Manifest V3): https://github.com/Tshetrim/Image-To-Text-OCR-extension-for-ChatGPT
+- Examples
+   - Converting PDF to text: https://github.com/racosa/pdf2text-ocr
+   - Use `blocks` output to generate granular data [word/symbol level]: https://github.com/Kishlay-notabot/tesseract-bbox-examples
+   - Electron: https://github.com/Balearica/tesseract.js-electron
+   - Typescript: https://github.com/Balearica/tesseract.js-typescript
+
+If you have a project or example repo that uses Tesseract.js, feel free to add it to this list using a pull request. Examples submitted should be well documented such that new users can run them; projects should be functional and actively maintained.
+
 ## Major changes in v5
 Version 5 changes are documented in [this issue](https://github.com/naptha/tesseract.js/issues/820).  Highlights are below.
 
@@ -118,24 +133,6 @@ Version 4 includes many new features and bug fixes--see [this issue](https://git
    - ASM.js version, any other old versions of Tesseract.js-core (<3.0.0) 
    - Node.js versions 10 and 12
 
-
-## Use tesseract.js the way you like!
-
-- Electron Version: https://github.com/Balearica/tesseract.js-electron
-- Typescript: https://github.com/Balearica/tesseract.js-typescript
-- Chrome Extension (with Manifest V3): https://github.com/Tshetrim/Image-To-Text-OCR-extension-for-ChatGPT
-- Converting PDF to text: https://github.com/racosa/pdf2text-ocr
-
-The following are old examples that use depreciated versions of Tesseract.js.  Updating to Tesseract.js v5 is highly recommended.  Users are encouraged to create updated examples (or make entirely new ones) and submit them as pull requests. 
-- Offline Version: https://github.com/jeromewu/tesseract.js-offline
-- Firefox Extension: https://github.com/gnonio/korporize
-- With Vue: https://github.com/jeromewu/tesseract.js-vue-app
-- With Angular: https://github.com/jeromewu/tesseract.js-angular-app
-- With React: https://github.com/jeromewu/tesseract.js-react-app
-- Video Real-time Recognition: https://github.com/jeromewu/tesseract.js-video
-
-React Native is **not** supported as it does not support Webassembly.
-
 ## Contributing
 
 ### Development
@@ -152,14 +149,14 @@ npm install
 npm start
 ```
 
-The development server will be available at http://localhost:3000/examples/browser/demo.html in your favorite browser.
+The development server will be available at http://localhost:3000/examples/browser/basic-efficient.html in your favorite browser.
 It will automatically rebuild `tesseract.min.js` and `worker.min.js` when you change files in the **src** folder.
 
 ### Online Setup with a single Click
 
 You can use Gitpod(A free online VS Code like IDE) for contributing. With a single click it will launch a ready to code workspace with the build & start scripts already in process and within a few seconds it will spin up the dev server so that you can start contributing straight away without wasting any time. 
 
-[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/naptha/tesseract.js/blob/master/examples/browser/demo.html)
+[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/naptha/tesseract.js/blob/master/examples/browser/basic-efficient.html)
 
 ### Building Static Files
 To build the compiled static files just execute the following:
@@ -172,7 +169,7 @@ This will output the files into the `dist` directory.
 
 ### Code Contributors
 
-This project exists thanks to all the people who contribute. [[Contribute](CONTRIBUTING.md)].
+This project exists thanks to all the people who contribute. [[Contribute](https://github.com/naptha/tesseract.js?tab=readme-ov-file#contributing)].
 <a href="https://github.com/naptha/tesseract.js/graphs/contributors"><img src="https://opencollective.com/tesseractjs/contributors.svg?width=890&button=false" /></a>
 
 ### Financial Contributors

docs/api.md

@@ -31,7 +31,7 @@
 
 **Arguments:**
 
-- `langs` a string to indicate the languages traineddata to download, multiple languages are concated with **+**, ex: **eng+chi\_tra**
+- `langs` a string to indicate the languages traineddata to download, multiple languages are specified using an array (['eng', 'chi_sim'])
 - `oem` a enum to indicate the OCR Engine Mode you use
 - `options` an object of customized options
   - `corePath` path to a directory containing **both** `tesseract-core.wasm.js` and `tesseract-core-simd.wasm.js` from [Tesseract.js-core](https://www.npmjs.com/package/tesseract.js-core) package
@@ -68,11 +68,12 @@ const worker = await createWorker('eng', 1, {
 ```
 
 <a name="worker-recognize"></a>
-### Worker.recognize(image, options, output, jobId): Promise
+### worker.recognize(image, options, output, jobId): Promise
 
-Worker.recognize() provides core function of Tesseract.js as it executes OCR
+`worker.recognize` provides core function of Tesseract.js as it executes OCR
 
 Figures out what words are in `image`, where the words are in `image`, etc.
+> [!TIP]
 > Note: `image` should be sufficiently high resolution.
 > Often, the same image will get much better results if you upscale it before calling `recognize`.
 
@@ -85,6 +86,10 @@ Figures out what words are in `image`, where the words are in `image`, etc.
 - `jobId` Please see details above
 
 **Output:**
+`worker.recognize` returns a promise to an object containing `jobId` and `data` properties.  The `data` property contains output in all of the formats specified using the `output` argument.
+
+> [!NOTE]  
+> `worker.recognize` still returns an output object even if no text is detected (the outputs will simply contain no words). No exception is thrown as determining the page is empty is considered a valid result. 
 
 **Examples:**
 
@@ -150,7 +155,7 @@ This list is incomplete.  As Tesseract.js passes parameters to the Tesseract eng
 
 **Arguments:**
 
-- `langs` a string to indicate the languages traineddata to download, multiple languages are concated with **+**, ex: **eng+chi\_tra**
+- `langs` a string to indicate the languages traineddata to download, multiple languages are specified using an array (['eng', 'chi_sim'])
 - `oem` a enum to indicate the OCR Engine Mode you use
 - `config` an object of customized options which are set prior to initialization (see details above)
 - `jobId` Please see details above
@@ -164,11 +169,12 @@ await worker.reinitialize('eng', 1);
 ```
 
 <a name="worker-detect"></a>
-### Worker.detect(image, jobId): Promise
+### worker.detect(image, jobId): Promise
 
-Worker.detect() does OSD (Orientation and Script Detection) to the image instead of OCR.
+`worker.detect` does OSD (Orientation and Script Detection) to the image instead of OCR.
 
-Note: Running `worker.detect` requires a worker with code and language data that supports Tesseract Legacy (this is not enabled by default).  If you want to run `worker.detect`, set `legacyCore` and `legacyLang` to `true` in the `createWorker` options. 
+> [!NOTE]  
+> Running `worker.detect` requires a worker with code and language data that supports Tesseract Legacy (this is not enabled by default).  If you want to run `worker.detect`, set `legacyCore` and `legacyLang` to `true` in the `createWorker` options. 
 
 **Arguments:**
 
@@ -187,9 +193,9 @@ const { createWorker } = Tesseract;
 ```
 
 <a name="worker-terminate"></a>
-### Worker.terminate(jobId): Promise
+### worker.terminate(jobId): Promise
 
-Worker.terminate() terminates the worker and cleans up
+`worker.terminate` terminates the worker and cleans up
 
 ```javascript
 (async () => {
@@ -201,7 +207,7 @@ Worker.terminate() terminates the worker and cleans up
 <a name="worker-writeText"></a>
 ### Worker.writeText(path, text, jobId): Promise
 
-Worker.writeText() writes a text file to the path specified in MEMFS, it is useful when you want to use some features that requires tesseract.js
+`worker.writeText` writes a text file to the path specified in MEMFS, it is useful when you want to use some features that requires tesseract.js
 to read file from file system.
 
 **Arguments:**
@@ -219,9 +225,9 @@ to read file from file system.
 ```
 
 <a name="worker-readText"></a>
-### Worker.readText(path, jobId): Promise
+### worker.readText(path, jobId): Promise
 
-Worker.readText() reads a text file to the path specified in MEMFS, it is useful when you want to check the content.
+`worker.readText` reads a text file to the path specified in MEMFS, it is useful when you want to check the content.
 
 **Arguments:**
 
@@ -238,9 +244,9 @@ Worker.readText() reads a text file to the path specified in MEMFS, it is useful
 ```
 
 <a name="worker-removeFile"></a>
-### Worker.removeFile(path, jobId): Promise
+### worker.removeFile(path, jobId): Promise
 
-Worker.removeFile() remove a file in MEMFS, it is useful when you want to free the memory.
+`worker.removeFile` removes a file in MEMFS, it is useful when you want to free the memory.
 
 **Arguments:**
 
@@ -256,9 +262,9 @@ Worker.removeFile() remove a file in MEMFS, it is useful when you want to free t
 ```
 
 <a name="worker-FS"></a>
-### Worker.FS(method, args, jobId): Promise
+### worker.FS(method, args, jobId): Promise
 
-Worker.FS() is a generic FS function to do anything you want, you can check [HERE](https://emscripten.org/docs/api_reference/Filesystem-API.html) for all functions.
+`worker.FS` is a generic FS function to do anything you want, you can check [HERE](https://emscripten.org/docs/api_reference/Filesystem-API.html) for all functions.
 
 **Arguments:**
 
@@ -279,7 +285,7 @@ Worker.FS() is a generic FS function to do anything you want, you can check [HER
 <a name="create-scheduler"></a>
 ## createScheduler(): Scheduler
 
-createScheduler() is a factory function to create a scheduler, a scheduler manages a job queue and workers to enable multiple workers to work together, it is useful when you want to speed up your performance.
+`createScheduler` is a factory function to create a scheduler, a scheduler manages a job queue and workers to enable multiple workers to work together, it is useful when you want to speed up your performance.
 
 **Examples:**
 
@@ -291,9 +297,9 @@ const scheduler = createScheduler();
 ### Scheduler
 
 <a name="scheduler-add-worker"></a>
-### Scheduler.addWorker(worker): string
+### scheduler.addWorker(worker): string
 
-Scheduler.addWorker() adds a worker into the worker pool inside scheduler, it is suggested to add one worker to only one scheduler.
+`scheduler.addWorker` adds a worker into the worker pool inside scheduler, it is suggested to add one worker to only one scheduler.
 
 **Arguments:**
 
@@ -309,9 +315,9 @@ scheduler.addWorker(worker);
 ```
 
 <a name="scheduler-add-job"></a>
-### Scheduler.addJob(action, ...payload): Promise
+### scheduler.addJob(action, ...payload): Promise
 
-Scheduler.addJob() adds a job to the job queue and scheduler waits and finds an idle worker to take the job.
+`scheduler.addJob` adds a job to the job queue and scheduler waits and finds an idle worker to take the job.
 
 **Arguments:**
 
@@ -328,19 +334,19 @@ Scheduler.addJob() adds a job to the job queue and scheduler waits and finds an
 ```
 
 <a name="scheduler-get-queue-len"></a>
-### Scheduler.getQueueLen(): number
+### scheduler.getQueueLen(): number
 
-Scheduler.getNumWorkers() returns the length of job queue.
+`scheduler.getNumWorkers()` returns the length of job queue.
 
 <a name="scheduler-get-num-workers"></a>
 ### Scheduler.getNumWorkers(): number
 
 Scheduler.getNumWorkers() returns number of workers added into the scheduler
 
 <a name="scheduler-terminate"></a>
-### Scheduler.terminate(): Promise
+### scheduler.terminate(): Promise
 
-Scheduler.terminate() terminates all workers added, useful to do quick clean up.
+`scheduler.terminate()` terminates all workers added, useful to do quick clean up.
 
 **Examples:**
 
@@ -353,7 +359,7 @@ Scheduler.terminate() terminates all workers added, useful to do quick clean up.
 <a name="set-logging"></a>
 ## setLogging(logging: boolean)
 
-setLogging() sets the logging flag, you can `setLogging(true)` to see detailed information, useful for debugging.
+`setLogging` sets the logging flag, you can `setLogging(true)` to see detailed information, useful for debugging.
 
 **Arguments:**
 
@@ -369,7 +375,8 @@ setLogging(true);
 <a name="recognize"></a>
 ## recognize(image, langs, options): Promise
 
-This function is depreciated and should be replaced with `worker.recognize` (see above). 
+> [!WARNING]  
+> This function is depreciated and should be replaced with `worker.recognize` (see above). 
 
 `recognize` works the same as `worker.recognize`, except that a new worker is created, loaded, and destroyed every time the function is called.
 
@@ -378,9 +385,10 @@ See [Tesseract.js](../src/Tesseract.js)
 <a name="detect"></a>
 ## detect(image, options): Promise
 
-This function is depreciated and should be replaced with `worker.detect` (see above). 
+> [!WARNING]  
+> This function is depreciated and should be replaced with `worker.detect` (see above). 
 
-Same background as recognize(), but it does detect instead.
+`detect` works the same as `worker.detect`, except that a new worker is created, loaded, and destroyed every time the function is called.
 
 See [Tesseract.js](../src/Tesseract.js)
 

docs/examples.md

@@ -37,7 +37,7 @@ const worker = await createWorker('eng', 1, {
 ```javascript
 const { createWorker } = require('tesseract.js');
 
-const worker = await createWorker('eng+chi_tra');
+const worker = await createWorker(['eng', 'chi_tra']);
 
 (async () => {
   const { data: { text } } = await worker.recognize('https://tesseract.projectnaptha.com/img/eng_bw.png');