Sys.Image
Sys.Image reads content from images in server-side code: text through OCR (optical character recognition) with Tesseract, and QR codes from images and PDF pages. It also detects whether data is a PNG or JPEG image, and gives access to the Jimp, jsQR and ImageMagick libraries for editing images.
Functions that take Buffer | string accept the image either as a Buffer or as a Base64 string.
Availability: Server
Functions
Section titled “Functions”ocrFromPng()
Section titled “ocrFromPng()”ocrFromPng(pngImage: Buffer, languages: TesseractLanguage[]): Promise<Page>Recognizes the text in an image with Tesseract.js (npm package tesseract.js, version ^5.0.3). Despite the name, any image format Tesseract can read is accepted. Lowgile keeps one OCR worker per language combination and stops it after 60 seconds without use.
| Parameter | Type | Description |
|---|---|---|
pngImage | Buffer | The image. |
languages | TesseractLanguage[] | Languages to recognize, for example ['deu', 'eng']. |
Returns: Promise<Page>, the Tesseract.js recognition result; the recognized text is in text · Availability: Server
ocrFromPngs()
Section titled “ocrFromPngs()”ocrFromPngs(pngImages: Buffer[], languages: TesseractLanguage[]): Promise<Page[]>Recognizes the text in several images, one after the other, as ocrFromPng() does.
| Parameter | Type | Description |
|---|---|---|
pngImages | Buffer[] | The images. |
languages | TesseractLanguage[] | Languages to recognize. |
Returns: Promise<Page[]>, one result per image, in the same order · Availability: Server
ocrFromPdf()
Section titled “ocrFromPdf()”ocrFromPdf(pdf: Buffer, languages: TesseractLanguage[], options?: PdfToImageOptions): Promise<Page[]>Renders every page of a PDF as an image and recognizes its text. Use it for scanned PDFs that contain no text layer; Sys.Pdf.isScannedPdf() tells you whether that is the case.
| Parameter | Type | Description |
|---|---|---|
pdf | Buffer | The PDF. |
languages | TesseractLanguage[] | Languages to recognize. |
options | PdfToImageOptions | Rendering options, as for Sys.Pdf.toPngImages(). Default scale: 2. |
Returns: Promise<Page[]>, one result per PDF page · Availability: Server
getImageType()
Section titled “getImageType()”getImageType(bufferOrBase64: Buffer | string): "png" | "jpeg"Detects the image format from the first bytes of the data.
| Parameter | Type | Description |
|---|---|---|
bufferOrBase64 | Buffer | string | The data, as a Buffer or Base64 string. |
Returns: "png" | "jpeg" · Availability: Server
Note
For data that is neither PNG nor JPEG, the function returns null, although the declared return type does not include it.
isImage()
Section titled “isImage()”isImage(bufferOrBase64: Buffer | string): booleanChecks whether the data is a PNG or JPEG image. Other image formats return false.
| Parameter | Type | Description |
|---|---|---|
bufferOrBase64 | Buffer | string | The data, as a Buffer or Base64 string. |
Returns: boolean · Availability: Server
getQrCodes()
Section titled “getQrCodes()”getQrCodes(bufferOrBase64s: (Buffer | string)[], filterPredicate?: (qrCode: QrCode) => boolean): Promise<QrCode[]>Finds all QR codes in a list of images and PDFs. PDFs are rendered page by page first. Several QR codes on the same image or page are all found.
| Parameter | Type | Description |
|---|---|---|
bufferOrBase64s | (Buffer | string)[] | Images or PDFs, each as a Buffer or Base64 string. |
filterPredicate | (qrCode: QrCode) => boolean | Keeps only the QR codes for which it returns true. |
Returns: Promise<QrCode[]> · Availability: Server
const codes = await Sys.Image.getQrCodes([pdfBuffer], (code) => code.data.startsWith('SPC'))const firstPayload = codes[0]?.dataiterateOverPointsInPolygon()
Section titled “iterateOverPointsInPolygon()”iterateOverPointsInPolygon(polygon: Point[], fn: (point: Point) => void): voidCalls a function for every point with integer coordinates inside a polygon, for example to paint over an area of a Jimp image.
| Parameter | Type | Description |
|---|---|---|
polygon | Point[] | Corners of the polygon, in order. |
fn | (point: Point) => void | Called once per point inside the polygon. |
Returns: void · Availability: Server
isPointInPolygon()
Section titled “isPointInPolygon()”isPointInPolygon(point: Point, polygon: Point[]): booleanChecks whether a point lies inside a polygon, using the ray casting algorithm.
| Parameter | Type | Description |
|---|---|---|
point | Point | Point to test. |
polygon | Point[] | Corners of the polygon, in order. |
Returns: boolean · Availability: Server
jsQR()
Section titled “jsQR()”The QR code decoder of the jsQR library (npm package jsqr, version ^1.4.0), re-exported as is. It decodes one QR code from raw RGBA pixel data; getQrCodes() is easier to use for files.
const code = Sys.Image.jsQR(new Uint8ClampedArray(image.bitmap.data), image.bitmap.width, image.bitmap.height)Returns: QRCode | null · Availability: Server
Note
The type declarations bundled for the jsqr package contain only the QRCode type, not the function, so calls to jsQR() are not checked against its parameters.
imageMagick()
Section titled “imageMagick()”The imageMagick function of the imagemagick-nodejs package (version ^0.2.2), re-exported as is. It wraps the ImageMagick command-line tool, which must be installed on the server.
const thumbnail = await Sys.Image.imageMagick(imageBuffer).resize(200).toBuffer()Returns: ImageMagick · Availability: Server
Classes
Section titled “Classes”The image class of the Jimp library (npm package jimp, version ^1.6.0), re-exported as is. Use it to read, resize, crop and write images in JavaScript, without external tools.
const image = await Sys.Image.Jimp.read(imageBuffer)image.resize({ w: 800 })const png = await image.getBuffer('image/png')Availability: Server
TesseractLanguage
Section titled “TesseractLanguage”type TesseractLanguage = 'afr' | 'amh' | 'ara' | … | 'eng' | … | 'yid'A Tesseract language code: a three-letter ISO 639-2 code such as eng or deu, or a variant such as chi_sim, chi_tra or srp_latn. The type lists 102 codes.
Availability: Server
QrCode
Section titled “QrCode”interface QrCode extends QRCode { inputIndex: number pageIndex: number}A QR code found by getQrCodes(): jsQR’s QRCode result, with the decoded text in data, the raw bytes in binaryData and the corner positions in location, plus where the code was found.
| Field | Type | Required | Description |
|---|---|---|---|
inputIndex | number | Yes | Index of the input in bufferOrBase64s. |
pageIndex | number | Yes | Index of the PDF page, 0 for images. |
Availability: Server
interface Point { x: number y: number}A point in pixel coordinates.
Availability: Server