The minimalistic document archiving platform.
feat(pdf-extractor): add support for 1-bit grayscale image extraction (#953)
Corentin Thomassetdb6badbc3cc1
diff --git a/.changeset/slow-cobras-count.md b/.changeset/slow-cobras-count.mdnew file mode 100644index 00000000..0290e81e--- /dev/null+++ b/.changeset/slow-cobras-count.md@@ -0,0 +1,6 @@+---+"@papra/lecture": minor+"@papra/app": patch+---++Added content extraction support for scanned PDFs images in 1-bit-per-pixel grayscale format.diff --git a/packages/lecture/fixtures/020-scanned-pdf-one-bit-per-pixel/020.expected.txt b/packages/lecture/fixtures/020-scanned-pdf-one-bit-per-pixel/020.expected.txtnew file mode 100644index 00000000..82c185e8--- /dev/null+++ b/packages/lecture/fixtures/020-scanned-pdf-one-bit-per-pixel/020.expected.txt@@ -0,0 +1,3 @@+Test document for 1-bit scanned PDF+This fixture tests GRAYSCALE_1BPP extraction.+Line three with some more text.\ No newline at end of filediff --git a/packages/lecture/fixtures/020-scanned-pdf-one-bit-per-pixel/020.input.pdf b/packages/lecture/fixtures/020-scanned-pdf-one-bit-per-pixel/020.input.pdfnew file mode 100644index 00000000..52d7a2c5Binary files /dev/null and b/packages/lecture/fixtures/020-scanned-pdf-one-bit-per-pixel/020.input.pdf differdiff --git a/packages/lecture/fixtures/021-scanned-pdf-one-bit-per-pixel-non-multiple-width/021.expected.txt b/packages/lecture/fixtures/021-scanned-pdf-one-bit-per-pixel-non-multiple-width/021.expected.txtnew file mode 100644index 00000000..5b369591--- /dev/null+++ b/packages/lecture/fixtures/021-scanned-pdf-one-bit-per-pixel-non-multiple-width/021.expected.txt@@ -0,0 +1 @@+Test 1bpp width non-multiple of 8\ No newline at end of filediff --git a/packages/lecture/fixtures/021-scanned-pdf-one-bit-per-pixel-non-multiple-width/021.input.pdf b/packages/lecture/fixtures/021-scanned-pdf-one-bit-per-pixel-non-multiple-width/021.input.pdfnew file mode 100644index 00000000..e44bc684Binary files /dev/null and b/packages/lecture/fixtures/021-scanned-pdf-one-bit-per-pixel-non-multiple-width/021.input.pdf differdiff --git a/packages/lecture/src/extractors/pdf.extractor.ts b/packages/lecture/src/extractors/pdf.extractor.tsindex df410417..0d42e540 100644--- a/packages/lecture/src/extractors/pdf.extractor.ts+++ b/packages/lecture/src/extractors/pdf.extractor.ts@@ -2,9 +2,10 @@ import type { PDFDocumentProxy } from 'unpdf/pdfjs';import type { Logger } from '../types';import { Buffer } from 'node:buffer';import canvas from '@napi-rs/canvas';-import sharp from 'sharp';-import { extractImages, extractText, getDocumentProxy, renderPageAsImage } from 'unpdf';+import { extractText, getDocumentProxy, getResolvedPDFJS, renderPageAsImage } from 'unpdf';import { defineTextExtractor } from '../extractors.models';+import { isValidPdfImage } from '../pdf/pdf.models';+import { pdfImageToBuffer } from '../pdf/pdf.usecases';import { createTesseractExtractor } from '../tesseract/tesseract.usecases';type OcrExtract = (imageBuffer: Buffer) => Promise<string>;@@ -18,45 +19,58 @@ async function extractPdfText({ pdf }: { pdf: PDFDocumentProxy }) {};}-async function ocrPdfEmbeddedImages({ pdf, pageCount, extract, logger }: { pdf: PDFDocumentProxy; pageCount: number; extract: OcrExtract; logger?: Logger }) {+// Inspired by unpdf's extractImages helper with added support for 1-bit grayscale images+async function ocrPdfImages({ pdf, pageCount, extract, logger }: { pdf: PDFDocumentProxy; pageCount: number; extract: OcrExtract; logger?: Logger }) {+ const { OPS } = await getResolvedPDFJS();const imageTexts: string[] = [];for (let pageIndex = 1; pageIndex <= pageCount; pageIndex++) {- const images = await extractImages(pdf, pageIndex);- const imageCount = images.length;+ const page = await pdf.getPage(pageIndex);+ const operatorList = await page.getOperatorList();+ let pageImageCount = 0;- if (imageCount === 0) {- logger?.debug({ pageIndex, pageCount }, 'No images found on PDF page for OCR.');- continue;- }+ for (let opIndex = 0; opIndex < operatorList.fnArray.length; opIndex++) {+ if (operatorList.fnArray[opIndex] !== OPS.paintImageXObject) {+ continue;+ }++ const imageKey = operatorList.argsArray[opIndex][0];++ if (!imageKey || typeof imageKey !== 'string') {+ logger?.warn({ pageIndex, pageCount, opIndex, imageKey }, 'Skipping PDF image with invalid image key for OCR.');+ continue;+ }++ const image = await new Promise(resolve => (imageKey.startsWith('g_') ? page.commonObjs : page.objs).get(imageKey, resolve));- logger?.debug({ pageIndex, pageCount, imageCount }, 'Extracted images from PDF page.');+ if (!isValidPdfImage(image)) {+ const get = (prop: string) => (image != null && typeof image === 'object' && prop in image ? image[prop] : undefined);++ logger?.warn({+ pageIndex,+ pageCount,+ imageKey,+ imageWidth: get('width'),+ imageHeight: get('height'),+ imageKind: get('kind'),+ }, 'Skipping unsupported PDF image for OCR.');+ continue;+ }++ pageImageCount++;+ logger?.debug({ pageIndex, pageCount, imageKey, imageWidth: image.width, imageHeight: image.height, imageKind: image.kind }, 'Extracting image from PDF page for OCR.');- for (const [imageIndex, image] of images.entries()) {const startTime = Date.now();- const imageBuffer = await sharp(image.data, {- raw: { width: image.width, height: image.height, channels: image.channels },- })- .png()- .toBuffer();-- const bufferDelay = Date.now() - startTime;- logger?.debug({- pageIndex,- pageCount,- imageIndex,- imageCount,- durationMs: bufferDelay,- imageWidth: image.width,- imageHeight: image.height,- imageSizeBytes: image.data.length,- }, 'Converted image to PNG buffer for OCR.');+ const imageBuffer = await pdfImageToBuffer(image);+ logger?.debug({ pageIndex, pageCount, durationMs: Date.now() - startTime }, 'Converted PDF image to PNG buffer for OCR.');const imageText = await extract(imageBuffer);- const ocrDelay = Date.now() - startTime - bufferDelay;- logger?.debug({ pageIndex, pageCount, imageIndex, imageCount, durationMs: ocrDelay }, 'Extracted text from image using OCR.');imageTexts.push(imageText);}++ if (pageImageCount === 0) {+ logger?.debug({ pageIndex, pageCount }, 'No images found on PDF page for OCR.');+ }}return { imageTexts };@@ -103,7 +117,7 @@ export const pdfExtractorDefinition = defineTextExtractor({const { extract, extractorType } = await createTesseractExtractor(config.tesseract);- const { imageTexts } = await ocrPdfEmbeddedImages({ pdf, pageCount, extract, logger });+ const { imageTexts } = await ocrPdfImages({ pdf, pageCount, extract, logger });if (imageTexts.length > 0) {logger?.info({ pageCount, imagesProcessedCount: imageTexts.length }, 'Completed OCR on PDF images.');diff --git a/packages/lecture/src/pdf/pdf.constants.ts b/packages/lecture/src/pdf/pdf.constants.tsnew file mode 100644index 00000000..8988b327--- /dev/null+++ b/packages/lecture/src/pdf/pdf.constants.ts@@ -0,0 +1,11 @@+export const IMAGE_KIND = {+ GRAYSCALE_1BPP: 1,+ RGB_24BPP: 2,+ RGBA_32BPP: 3,+} as const;++export const IMAGE_KIND_CHANNELS: Record<number, 1 | 3 | 4> = {+ [IMAGE_KIND.GRAYSCALE_1BPP]: 1,+ [IMAGE_KIND.RGB_24BPP]: 3,+ [IMAGE_KIND.RGBA_32BPP]: 4,+};diff --git a/packages/lecture/src/pdf/pdf.models.ts b/packages/lecture/src/pdf/pdf.models.tsnew file mode 100644index 00000000..baa83b88--- /dev/null+++ b/packages/lecture/src/pdf/pdf.models.ts@@ -0,0 +1,15 @@+import type { PdfRawImage } from './pdf.types';+import { IMAGE_KIND_CHANNELS } from './pdf.constants';++export function isValidPdfImage(image: unknown): image is PdfRawImage {+ return Boolean(image)+ && typeof image === 'object'+ && 'data' in image+ && 'width' in image+ && typeof image.width === 'number'+ && 'height' in image+ && typeof image.height === 'number'+ && 'kind' in image+ && typeof image.kind === 'number'+ && image.kind in IMAGE_KIND_CHANNELS;+}diff --git a/packages/lecture/src/pdf/pdf.types.ts b/packages/lecture/src/pdf/pdf.types.tsnew file mode 100644index 00000000..b2fc7dcb--- /dev/null+++ b/packages/lecture/src/pdf/pdf.types.ts@@ -0,0 +1 @@+export type PdfRawImage = { kind: number; width: number; height: number; data: Uint8Array };diff --git a/packages/lecture/src/pdf/pdf.usecases.test.ts b/packages/lecture/src/pdf/pdf.usecases.test.tsnew file mode 100644index 00000000..85f26d40--- /dev/null+++ b/packages/lecture/src/pdf/pdf.usecases.test.ts@@ -0,0 +1,86 @@+import { describe, expect, test } from 'vitest';+import { IMAGE_KIND } from './pdf.constants';+import { getNormalizedImageData } from './pdf.usecases';++describe('getNormalizedImageData', () => {+ describe('for GRAYSCALE_1BPP images, unpacks packed bits into one byte per pixel so that sharp can process the image', () => {+ test('each bit maps to 0 (black) or 255 (white), MSB first', () => {+ // width=8, height=2: no padding, each row is exactly 1 byte+ const image = {+ data: new Uint8Array([0xFF, 0x00]),+ width: 8,+ height: 2,+ kind: IMAGE_KIND.GRAYSCALE_1BPP,+ };++ const result = getNormalizedImageData(image);++ expect(Array.from(result)).toEqual([+ 255,+ 255,+ 255,+ 255,+ 255,+ 255,+ 255,+ 255, // row 0: all white+ 0,+ 0,+ 0,+ 0,+ 0,+ 0,+ 0,+ 0, // row 1: all black+ ]);+ });++ test(+ 'padding bits at the end of each row are skipped — '+ + 'PDF 1bpp scanlines are byte-aligned (ceil(width/8) bytes per row), '+ + 'so images whose width is not a multiple of 8 carry unused bits '+ + 'that must not bleed into the next row',+ () => {+ // width=9, height=2: 2 bytes per row, 7 padding bits at end of each row+ // Row 0: [0x00, 0x00] → 9 black pixels, 7 padding bits ignored+ // Row 1: [0xFF, 0x80] → 9 white pixels, 7 padding bits ignored+ const image = {+ data: new Uint8Array([0x00, 0x00, 0xFF, 0x80]),+ width: 9,+ height: 2,+ kind: IMAGE_KIND.GRAYSCALE_1BPP,+ };++ const result = getNormalizedImageData(image);++ expect(Array.from(result)).toEqual([+ 0,+ 0,+ 0,+ 0,+ 0,+ 0,+ 0,+ 0,+ 0, // row 0: all black+ 255,+ 255,+ 255,+ 255,+ 255,+ 255,+ 255,+ 255,+ 255, // row 1: all white+ ]);+ },+ );+ });++ test('passes image data through unchanged for non-1bpp formats (RGB, RGBA) since they are already byte-per-channel', () => {+ const data = new Uint8Array([255, 0, 0, 0, 255, 0]);+ const image = { data, width: 2, height: 1, kind: IMAGE_KIND.RGB_24BPP };++ expect(getNormalizedImageData(image)).toBe(data);+ });+});diff --git a/packages/lecture/src/pdf/pdf.usecases.ts b/packages/lecture/src/pdf/pdf.usecases.tsnew file mode 100644index 00000000..359b1b34--- /dev/null+++ b/packages/lecture/src/pdf/pdf.usecases.ts@@ -0,0 +1,39 @@+import type { Buffer } from 'node:buffer';+import type { PdfRawImage } from './pdf.types';+import sharp from 'sharp';+import { IMAGE_KIND, IMAGE_KIND_CHANNELS } from './pdf.constants';++export function getNormalizedImageData(image: PdfRawImage): Uint8Array {+ if (image.kind === IMAGE_KIND.GRAYSCALE_1BPP) {+ // Unpack 1-bit per pixel (MSB first) into 8-bit grayscale: bit 1 = white (255), bit 0 = black (0)+ // PDF 1bpp scanlines are byte-aligned: each row occupies ceil(width/8) bytes,+ // with unused padding bits at the end of each row that must be skipped.+ const unpacked = new Uint8Array(image.width * image.height);+ const rowBytes = Math.ceil(image.width / 8);++ for (let y = 0; y < image.height; y++) {+ const rowOffset = y * rowBytes;+ for (let x = 0; x < image.width; x++) {+ const byte = image.data[rowOffset + (x >> 3)] ?? 0;+ unpacked[y * image.width + x] = ((byte >> (7 - (x & 7))) & 1) ? 255 : 0;+ }+ }+ return unpacked;+ }++ return image.data;+}++export async function pdfImageToBuffer(image: PdfRawImage): Promise<Buffer> {+ const imageData = getNormalizedImageData(image);++ return sharp(imageData, {+ raw: {+ width: image.width,+ height: image.height,+ channels: IMAGE_KIND_CHANNELS[image.kind],+ },+ })+ .png()+ .toBuffer();+}