{"id":20852398,"url":"https://github.com/dimdengd/chrome-lens-ocr","last_synced_at":"2025-05-16T10:06:03.720Z","repository":{"id":220665869,"uuid":"752248117","full_name":"dimdenGD/chrome-lens-ocr","owner":"dimdenGD","description":"Library to use Google Lens OCR for free, via API used in Chromium.","archived":false,"fork":false,"pushed_at":"2025-01-04T15:32:44.000Z","size":332,"stargazers_count":209,"open_issues_count":9,"forks_count":13,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-05-06T20:51:48.617Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dimdenGD.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"patreon":"dimdendev","custom":["https://dimden.dev/donate"]}},"created_at":"2024-02-03T13:27:37.000Z","updated_at":"2025-05-06T12:03:59.000Z","dependencies_parsed_at":null,"dependency_job_id":"c3491a5e-7747-4bc4-9d29-fe0add79fd72","html_url":"https://github.com/dimdenGD/chrome-lens-ocr","commit_stats":null,"previous_names":["dimdengd/chrome-lens-ocr"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dimdenGD%2Fchrome-lens-ocr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dimdenGD%2Fchrome-lens-ocr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dimdenGD%2Fchrome-lens-ocr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dimdenGD%2Fchrome-lens-ocr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dimdenGD","download_url":"https://codeload.github.com/dimdenGD/chrome-lens-ocr/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254509477,"owners_count":22082891,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-18T03:17:32.539Z","updated_at":"2025-05-16T10:06:03.701Z","avatar_url":"https://github.com/dimdenGD.png","language":"JavaScript","funding_links":["https://patreon.com/dimdendev","https://dimden.dev/donate"],"categories":[],"sub_categories":[],"readme":"# Chrome Lens OCR\nLibrary to use Google Lens OCR for free, via API used in Chromium. This doesn't require running a headless browser, and is much faster than using Puppeteer or similar.\nIt's set up to work without any options, there's no need to be authorized (no need for Google account!).\n\n## Installation\n```bash\nnpm install chrome-lens-ocr\n```\n\n## Usage\n```javascript\nimport Lens from 'chrome-lens-ocr';\nimport { inspect } from 'util';\n\nconst lens = new Lens();\nconst log = data =\u003e console.log(inspect(data, { depth: null, colors: true }));\n\nlens.scanByFile('shrimple.png').then(log).catch(console.error);\nlens.scanByBuffer(Buffer.from('...')).then(log).catch(console.error);\n// fetches image and then scans it\nlens.scanByURL('https://lune.dimden.dev/7949f833fa42.png').then(log).catch(console.error);\n```\nAll methods above return `LensResult` object (see docs below). In case error happened during the process, `LensError` will be thrown.\n\n![Example output](https://lune.dimden.dev/1454b73026ab.png)\n\n## API\nAll of the classes are exported. `Lens` is the default export, and `LensCore`, `LensResult`, `Segment`, `BoundingBox` and `LensError` are named exports.\n### class Lens extends LensCore\n#### `constructor(options?: Object): Lens`\nCreates a new instance of Lens. `options` is optional.\n\n#### `scanByFile(path: String): Promise\u003cLensResult\u003e`\nScans an image from a file.\n\n#### `scanByBuffer(buffer: Buffer): Promise\u003cLensResult\u003e`\nScans an image from a buffer.\n\n### class LensCore\nThis is the core class, which is extended by `Lens`. You can use it if you want to use the library in environments that don't support Node.js APIs, as it doesn't include `scanByFile` and `scanByBuffer` methods. Keep in mind that `Lens` class extends `LensCore`, so all methods and properties of `LensCore` are available in `Lens`.\n\n#### `constructor(options?: Object, fetch?: Function): LensCore`\nCreates a new instance of LensCore. `options` is optional. `fetch` is function that will be used to send requests, by default it's `fetch` from global scope.\n\n#### `scanByURL(url: String): Promise\u003cLensResult\u003e`\nFetches an image from a remote URL, and scans it.\n\n#### `scanByData(data: Uint8Array, mime: String, originalDimensions: Array): Promise\u003cLensResult\u003e`\nScans an image from a Uint8Array. `originalDimensions` is array of `[width, height]` format. You must provide width and height of image before it was resized to get accurate pixel coordinates. You should only use this method if you're using the library in environments that don't support Node.js APIs, because it doesn't automatically resize images to less than 1000x1000 dimensions, like methods in `Lens` do.\n\n#### `updateOptions(options: Object): void`\nUpdates the options for the instance.\n\n#### `fetch(options?: RequestInit \u0026 { endpoint: String } = {}, originalDimensions: Array): Promise\u003cLensResult\u003e`\nInternal method to send a request to the API. You can use it to send a custom request, but you'll have to handle the formdata and dimensions yourself. Original dimensions (`[width, height]`) are used to calculate pixel coordinates of the text. You should supply dimensions before any resizing (hence 'original') if you want to get correct coordinates for original image.\n\n#### `cookies`\nThis property contains object with cookies that are set for the instance. You can use it to save and load cookies to avoid doing the consent process every time.\n\n### Options object\nOptions can be empty, or contain the following (default values):\n```javascript\n{\n  chromeVersion: '124.0.6367.60', // Version of Chromium to \"use\"\n  userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36', // user agent to use, major Chrome version should match the previous value\n  headers: {}, // you can add headers here, they'll override the default ones\n  fetchOptions: {}, // options to pass to fetch function (like agent, dispatcher, etc.)\n}\n```\n\n### class LensResult\nInstance of this class is is returned by all scan methods. It contains the following properties:\n```javascript\n{\n  language: String, // language of the text in 2-letter format\n  segments: Array\u003cSegment\u003e\n}\n```\n\n### class Segment\nInstance of this class is contained in `LensResult`'s `segments` property. It contains the following properties:\n```javascript\n{\n  text: String, // text of the segment\n  boundingBox: BoundingBox,\n}\n```\n\n### class BoundingBox\nInstance of this class is contained in `Segment`'s `boundingBox` property. It contains the following properties:\n```javascript\n{\n  centerPerX: Number, // center of the bounding box on X axis, in % of the image width\n  centerPerY: Number, // center of the bounding box on Y axis, in % of the image height\n  perWidth: Number, // width of the bounding box, in % of the image width\n  perHeight: Number, // height of the bounding box, in % of the image height\n  pixelCoords: {\n    x: Number, // top-left corner X coordinate, in pixels\n    y: Number, // top-left corner Y coordinate, in pixels\n    width: Number, // width of the bounding box, in pixels\n    height: Number, // height of the bounding box, in pixels\n  }\n}\n```\n\n### class LensError extends Error\nInstance of this class is thrown when an error happens during the process. It contains the following properties:\n```javascript\n{\n  name: \"LensError\"\n  message: String, // error message\n  code: String, // error code\n  headers: HeadersList, // headers of the response\n  body: String, // body of the response\n}\n```\n\n## Using proxy\nBy default, this library uses undici's fetch to make requests. You can use undici dispatcher to proxy requests. Here's an example:\n```javascript\nimport Lens from 'chrome-lens-ocr';\nimport { ProxyAgent } from 'undici';\n\nconst lens = new Lens({\n  fetchOptions: {\n    dispatcher: new ProxyAgent('http://user:pass@example.com:8080')\n  }\n});\n```\nIf you use core class with different fetch function, you can pass different options instead of `dispatcher` in `fetchOptions` (for example `agent` for node-fetch).\n\n## Using your cookies\nYou can use your own cookies to be authorized in Google. This is optional. Here's an example:\n```javascript\nimport Lens from 'chrome-lens-ocr';\n\nconst lens = new Lens({\n    headers: {\n        // 'cookie' is the only 'special' header that can also accept an object, all other headers should be strings\n        'cookie': '__Secure-ENID=17.SE=-dizH-; NID=511=---bcDwC4fo0--lgfi0n2-' // way #1\n        'cookie': { // way #2, better because you can set expiration date and it will be automatically handled, all 3 fields are required in this way\n            '__Secure-ENID': {\n                name: '__Secure-ENID',\n                value: '17.SE=-dizH-',\n                expires: 1634025600,\n            },\n            'NID': {\n                name: 'NID',\n                value: '511=---bcDwC4fo0--lgfi0n2-',\n                expires: 1634025600,\n            }\n        }\n    }\n});\n```\n\n## Using in other environments\nYou can use this library in environments that don't support Node.js APIs by importing only the core, which doesn't include `scanByFile` and `scanByBuffer` methods. Instead, it has `scanByData` method, which accepts a `Uint8Array`, mime type and original image dimensions. Here's an example:\n```javascript\nimport LensCore from 'chrome-lens-ocr/src/core.js';\n\nconst lens = new LensCore();\nlens.scanByData(new Uint8Array([41, 40, 236, 244, 151, 101, 118, 16, 37, 138, 199, 229, 2, 75, 33]) 'image/png', [1280, 720]);\n```\nBut in this case, you'll need to handle resizing images to less than 1000x1000 dimensions yourself, as larger images aren't supported by Google Lens.\n\n## Additional information\nIn some of the EU countries, using any Google services requires cookie consent. This library handles it automatically, but it's pretty slow on first scan of the instance. So if you make a lot of new instances or always need it to be fast on first launch, you need to save cookies somewhere to avoid this. There's an example of how to do it in [cli.js](https://github.com/dimdenGD/chrome-lens-ocr/blob/main/cli.js).\n\n## Custom Sharex OCR\nIt's possible to use this package with Sharex to OCR images using Google Lens API, instead of bad default OCR in Sharex. Please refer to [SHAREX.md](https://github.com/dimdenGD/chrome-lens-ocr/blob/main/SHAREX.md) for instructions.\n\n## CLI Usage\nYou may install this package globally by adding -g on install:\n```bash\nnpm install -g chrome-lens-ocr\n```\nDoing this will allow you to use the OCR from a terminal.\n```\nUsage: chrome-lens-ocr [-d] ./path/to/image.png\n       -d   Do not copy text to clipboard\n```\nExample:\n```bash\nchrome-lens-ocr ./shrimple.png\nchrome-lens-ocr -d ./shrimple.png\nchrome-lens-ocr -d https://lune.dimden.dev/7949f833fa42.png\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdimdengd%2Fchrome-lens-ocr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdimdengd%2Fchrome-lens-ocr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdimdengd%2Fchrome-lens-ocr/lists"}