Skip to content

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

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.

ParameterTypeDescription
pngImageBufferThe image.
languagesTesseractLanguage[]Languages to recognize, for example ['deu', 'eng'].

Returns: Promise<Page>, the Tesseract.js recognition result; the recognized text is in text · Availability: Server

ocrFromPngs(pngImages: Buffer[], languages: TesseractLanguage[]): Promise<Page[]>

Recognizes the text in several images, one after the other, as ocrFromPng() does.

ParameterTypeDescription
pngImagesBuffer[]The images.
languagesTesseractLanguage[]Languages to recognize.

Returns: Promise<Page[]>, one result per image, in the same order · Availability: Server

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.

ParameterTypeDescription
pdfBufferThe PDF.
languagesTesseractLanguage[]Languages to recognize.
optionsPdfToImageOptionsRendering options, as for Sys.Pdf.toPngImages(). Default scale: 2.

Returns: Promise<Page[]>, one result per PDF page · Availability: Server

getImageType(bufferOrBase64: Buffer | string): "png" | "jpeg"

Detects the image format from the first bytes of the data.

ParameterTypeDescription
bufferOrBase64Buffer | stringThe 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(bufferOrBase64: Buffer | string): boolean

Checks whether the data is a PNG or JPEG image. Other image formats return false.

ParameterTypeDescription
bufferOrBase64Buffer | stringThe data, as a Buffer or Base64 string.

Returns: boolean · Availability: Server

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.

ParameterTypeDescription
bufferOrBase64s(Buffer | string)[]Images or PDFs, each as a Buffer or Base64 string.
filterPredicate(qrCode: QrCode) => booleanKeeps 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]?.data
iterateOverPointsInPolygon(polygon: Point[], fn: (point: Point) => void): void

Calls a function for every point with integer coordinates inside a polygon, for example to paint over an area of a Jimp image.

ParameterTypeDescription
polygonPoint[]Corners of the polygon, in order.
fn(point: Point) => voidCalled once per point inside the polygon.

Returns: void · Availability: Server

isPointInPolygon(point: Point, polygon: Point[]): boolean

Checks whether a point lies inside a polygon, using the ray casting algorithm.

ParameterTypeDescription
pointPointPoint to test.
polygonPoint[]Corners of the polygon, in order.

Returns: boolean · Availability: Server

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.

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

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

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

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.

FieldTypeRequiredDescription
inputIndexnumberYesIndex of the input in bufferOrBase64s.
pageIndexnumberYesIndex of the PDF page, 0 for images.

Availability: Server

interface Point {
x: number
y: number
}

A point in pixel coordinates.

Availability: Server