@qvac/ocr-ggml 0.0.1 → 0.1.1

package/test/integration/full-ocr-suite.test.js

@@ -0,0 +1,83 @@
+'use strict'
+
+const { OcrGgml } = require('../..')
+const test = require('brittle')
+const { isMobile, getImagePath, ensureModelPath } = require('./utils')
+
+test('Full OCR test suite', { timeout: 40 * 60 * 1000, skip: isMobile }, async function (t) {
+  const detectorPath = await ensureModelPath('detector_craft')
+  const recognizerPath = await ensureModelPath('recognizer_latin')
+
+  const testCases = [
+    {
+      imagePath: '/test/images/basic_test.bmp',
+      expectedTexts: ['tilted', 'normal', 'vertical'],
+      options: { paragraph: false }
+    },
+    {
+      imagePath: '/test/images/basic_test.jpg',
+      expectedTexts: ['tilted', 'normal', 'vertical'],
+      options: { paragraph: false }
+    },
+    {
+      imagePath: '/test/images/basic_test.png',
+      expectedTexts: ['tilted', 'normal', 'vertical'],
+      options: { paragraph: false }
+    },
+    {
+      imagePath: '/test/images/english.bmp',
+      expectedTexts: ['health', 'world', 'water', 'hands', 'symptoms'],
+      options: { paragraph: false }
+    }
+  ]
+
+  const ocrGgml = new OcrGgml({
+    params: {
+      pathDetector: detectorPath,
+      pathRecognizer: recognizerPath,
+      langList: ['en']
+    },
+    opts: { stats: true }
+  })
+
+  await ocrGgml.load()
+  t.pass('OCR model loaded')
+
+  try {
+    for (const testCase of testCases) {
+      const imagePath = getImagePath(testCase.imagePath)
+      t.comment('\n\nImage Path: ' + testCase.imagePath)
+
+      const response = await ocrGgml.run({ path: imagePath, options: testCase.options })
+
+      await response
+        .onUpdate(output => {
+          t.ok(Array.isArray(output), testCase.imagePath + ': output should be an array')
+          const texts = output.map(o => o[1])
+          t.comment('Detected texts: ' + JSON.stringify(texts))
+
+          for (const expected of testCase.expectedTexts) {
+            const found = texts.some(w => w.toLowerCase().includes(expected.toLowerCase()))
+            t.ok(found, testCase.imagePath + `: should detect "${expected}"`)
+          }
+        })
+        .onError(error => {
+          t.fail(testCase.imagePath + ': unexpected error: ' + JSON.stringify(error))
+        })
+        .await()
+
+      t.comment('OCR processing complete for ' + testCase.imagePath)
+      await new Promise(resolve => setTimeout(resolve, 2000))
+    }
+  } catch (err) {
+    t.fail('Error running test suite: ' + err)
+  } finally {
+    try {
+      await ocrGgml.unload()
+      t.comment('Successfully unloaded model')
+    } catch (err) {
+      t.comment('unload() failed: ' + err.message)
+    }
+    await new Promise(resolve => setTimeout(resolve, 2000))
+  }
+})

package/test/integration/image-formats.test.js

@@ -0,0 +1,168 @@
+'use strict'
+
+const { OcrGgml } = require('../..')
+const test = require('brittle')
+const { isMobile, getImagePath, ensureModelPath } = require('./utils')
+
+const MOBILE_TIMEOUT = 600 * 1000 // 10 minutes for mobile
+const DESKTOP_TIMEOUT = 120 * 1000 // 2 minutes for desktop
+const TEST_TIMEOUT = isMobile ? MOBILE_TIMEOUT : DESKTOP_TIMEOUT
+
+const IMAGE_FORMAT_EXPECTED_TEXTS = ['tilted', 'normal', 'vertical']
+
+test('OCR processes JPEG images correctly', { timeout: TEST_TIMEOUT }, async function (t) {
+  const detectorPath = await ensureModelPath('detector_craft')
+  const recognizerPath = await ensureModelPath('recognizer_latin')
+  const imagePath = getImagePath('/test/images/basic_test.jpg')
+
+  t.comment('Testing JPEG format with image: ' + imagePath)
+
+  const ocrGgml = new OcrGgml({
+    params: {
+      pathDetector: detectorPath,
+      pathRecognizer: recognizerPath,
+      langList: ['en']
+    },
+    opts: { stats: true }
+  })
+
+  await ocrGgml.load()
+
+  try {
+    const response = await ocrGgml.run({
+      path: imagePath,
+      options: { paragraph: false }
+    })
+
+    await response
+      .onUpdate(output => {
+        t.ok(Array.isArray(output), 'JPEG: output should be an array')
+        t.ok(output.length === IMAGE_FORMAT_EXPECTED_TEXTS.length, `JPEG: output length should be ${IMAGE_FORMAT_EXPECTED_TEXTS.length}, got ${output.length}`)
+
+        const texts = output.map(o => o[1])
+        t.comment('JPEG output texts: ' + JSON.stringify(texts))
+
+        for (let i = 0; i < IMAGE_FORMAT_EXPECTED_TEXTS.length; i++) {
+          t.ok(texts.includes(IMAGE_FORMAT_EXPECTED_TEXTS[i]), `JPEG: should contain text "${IMAGE_FORMAT_EXPECTED_TEXTS[i]}"`)
+        }
+      })
+      .onError(error => {
+        t.fail('JPEG: unexpected error: ' + JSON.stringify(error))
+      })
+      .await()
+
+    t.pass('JPEG format processing completed successfully')
+  } finally {
+    await ocrGgml.unload()
+    await new Promise(resolve => setTimeout(resolve, 1000))
+  }
+})
+
+test('OCR processes PNG images correctly', { timeout: TEST_TIMEOUT }, async function (t) {
+  const detectorPath = await ensureModelPath('detector_craft')
+  const recognizerPath = await ensureModelPath('recognizer_latin')
+  const imagePath = getImagePath('/test/images/basic_test.png')
+
+  t.comment('Testing PNG format with image: ' + imagePath)
+
+  const ocrGgml = new OcrGgml({
+    params: {
+      pathDetector: detectorPath,
+      pathRecognizer: recognizerPath,
+      langList: ['en']
+    },
+    opts: { stats: true }
+  })
+
+  await ocrGgml.load()
+
+  try {
+    const response = await ocrGgml.run({
+      path: imagePath,
+      options: { paragraph: false }
+    })
+
+    await response
+      .onUpdate(output => {
+        t.ok(Array.isArray(output), 'PNG: output should be an array')
+        t.ok(output.length === IMAGE_FORMAT_EXPECTED_TEXTS.length, `PNG: output length should be ${IMAGE_FORMAT_EXPECTED_TEXTS.length}, got ${output.length}`)
+
+        const texts = output.map(o => o[1])
+        t.comment('PNG output texts: ' + JSON.stringify(texts))
+
+        for (let i = 0; i < IMAGE_FORMAT_EXPECTED_TEXTS.length; i++) {
+          t.ok(texts.includes(IMAGE_FORMAT_EXPECTED_TEXTS[i]), `PNG: should contain text "${IMAGE_FORMAT_EXPECTED_TEXTS[i]}"`)
+        }
+      })
+      .onError(error => {
+        t.fail('PNG: unexpected error: ' + JSON.stringify(error))
+      })
+      .await()
+
+    t.pass('PNG format processing completed successfully')
+  } finally {
+    await ocrGgml.unload()
+    await new Promise(resolve => setTimeout(resolve, 1000))
+  }
+})
+
+test('BMP and JPEG produce consistent results', { timeout: TEST_TIMEOUT }, async function (t) {
+  const detectorPath = await ensureModelPath('detector_craft')
+  const recognizerPath = await ensureModelPath('recognizer_latin')
+  const bmpPath = getImagePath('/test/images/basic_test.bmp')
+  const jpgPath = getImagePath('/test/images/basic_test.jpg')
+
+  const ocrGgml = new OcrGgml({
+    params: {
+      pathDetector: detectorPath,
+      pathRecognizer: recognizerPath,
+      langList: ['en']
+    },
+    opts: { stats: true }
+  })
+
+  await ocrGgml.load()
+
+  let bmpTexts = []
+  let jpegTexts = []
+
+  try {
+    const bmpResponse = await ocrGgml.run({
+      path: bmpPath,
+      options: { paragraph: false }
+    })
+
+    await bmpResponse
+      .onUpdate(output => {
+        bmpTexts = output.map(o => o[1]).sort()
+      })
+      .await()
+
+    await new Promise(resolve => setTimeout(resolve, 2000))
+
+    const jpegResponse = await ocrGgml.run({
+      path: jpgPath,
+      options: { paragraph: false }
+    })
+
+    await jpegResponse
+      .onUpdate(output => {
+        jpegTexts = output.map(o => o[1]).sort()
+      })
+      .await()
+
+    t.comment('BMP texts: ' + JSON.stringify(bmpTexts))
+    t.comment('JPEG texts: ' + JSON.stringify(jpegTexts))
+
+    t.ok(bmpTexts.length === jpegTexts.length, 'BMP and JPEG should detect same number of text regions')
+
+    for (const text of bmpTexts) {
+      t.ok(jpegTexts.includes(text), `JPEG should also detect text "${text}" found in BMP`)
+    }
+
+    t.pass('BMP and JPEG produce consistent results')
+  } finally {
+    await ocrGgml.unload()
+    await new Promise(resolve => setTimeout(resolve, 1000))
+  }
+})

package/test/integration/large-images.test.js

@@ -0,0 +1,81 @@
+'use strict'
+
+const { OcrGgml } = require('../..')
+const test = require('brittle')
+const { isMobile, getImagePath, ensureModelPath } = require('./utils')
+
+const MOBILE_TIMEOUT = 600 * 1000 // 10 minutes for mobile
+const DESKTOP_TIMEOUT = 120 * 1000 // 2 minutes for desktop
+const TEST_TIMEOUT = isMobile ? MOBILE_TIMEOUT : DESKTOP_TIMEOUT
+
+/**
+ * Test for internal image resizing.
+ * Images larger than 1200px are resized internally, but bounding box
+ * coordinates should be returned in original image space.
+ */
+test('Large images are resized internally with coordinates in original space', { timeout: TEST_TIMEOUT }, async function (t) {
+  const detectorPath = await ensureModelPath('detector_craft')
+  const recognizerPath = await ensureModelPath('recognizer_latin')
+
+  // unrecognizable_text.bmp is 2467x128 - long axis crosses the 1200px threshold
+  const imagePath = getImagePath('/test/images/unrecognizable_text.bmp')
+  const originalImageWidth = 2467
+  const originalImageHeight = 128
+
+  t.comment('Testing internal resize with image: ' + imagePath + ' (' + originalImageWidth + 'x' + originalImageHeight + ')')
+
+  const ocrGgml = new OcrGgml({
+    params: {
+      pathDetector: detectorPath,
+      pathRecognizer: recognizerPath,
+      langList: ['en']
+    },
+    opts: { stats: true }
+  })
+
+  await ocrGgml.load()
+
+  try {
+    const response = await ocrGgml.run({
+      path: imagePath,
+      options: { paragraph: false }
+    })
+
+    await response
+      .onUpdate(output => {
+        t.ok(Array.isArray(output), 'output should be an array')
+        t.ok(output.length > 0, 'should detect at least one text region')
+        t.comment('Detected ' + output.length + ' text regions')
+
+        // Check that coordinates are in original image space (can exceed 1200)
+        let hasCoordBeyondResizeThreshold = false
+        let maxX = 0
+        let maxY = 0
+
+        for (const item of output) {
+          const coords = item[0] // [[x1,y1], [x2,y2], [x3,y3], [x4,y4]]
+          for (const point of coords) {
+            if (point[0] > maxX) maxX = point[0]
+            if (point[1] > maxY) maxY = point[1]
+            if (point[0] > 1200 || point[1] > 1200) {
+              hasCoordBeyondResizeThreshold = true
+            }
+          }
+        }
+
+        t.comment('Max X coordinate: ' + maxX.toFixed(1) + ', Max Y coordinate: ' + maxY.toFixed(1))
+        t.ok(hasCoordBeyondResizeThreshold, 'coordinates should be in original image space (some coords > 1200)')
+        t.ok(maxX <= originalImageWidth, 'max X should not exceed original image width')
+        t.ok(maxY <= originalImageHeight, 'max Y should not exceed original image height')
+      })
+      .onError(error => {
+        t.fail('unexpected error: ' + JSON.stringify(error))
+      })
+      .await()
+
+    t.pass('Large image resize test completed successfully')
+  } finally {
+    await ocrGgml.unload()
+    await new Promise(resolve => setTimeout(resolve, 1000))
+  }
+})

package/test/integration/lifecycle.test.js

@@ -0,0 +1,269 @@
+'use strict'
+
+const { OcrGgml } = require('../..')
+const test = require('brittle')
+const { isMobile, getImagePath, ensureModelPath } = require('./utils')
+
+const MOBILE_TIMEOUT = 600 * 1000
+const DESKTOP_TIMEOUT = 120 * 1000
+const TEST_TIMEOUT = isMobile ? MOBILE_TIMEOUT : DESKTOP_TIMEOUT
+
+async function createAndLoadOcr (t) {
+  const detectorPath = await ensureModelPath('detector_craft')
+  const recognizerPath = await ensureModelPath('recognizer_latin')
+  const imagePath = getImagePath('/test/images/basic_test.bmp')
+
+  const ocrGgml = new OcrGgml({
+    params: {
+      pathDetector: detectorPath,
+      pathRecognizer: recognizerPath,
+      langList: ['en']
+    },
+    opts: { stats: true }
+  })
+
+  return { ocrGgml, imagePath }
+}
+
+test('Load, run, unload - basic lifecycle', { timeout: TEST_TIMEOUT }, async function (t) {
+  const { ocrGgml, imagePath } = await createAndLoadOcr(t)
+
+  await ocrGgml.load()
+  t.pass('Model loaded successfully')
+
+  try {
+    const response = await ocrGgml.run({
+      path: imagePath,
+      options: { paragraph: false }
+    })
+
+    await response
+      .onUpdate(output => {
+        t.ok(Array.isArray(output), 'Output should be an array')
+        t.ok(output.length > 0, 'Should detect at least one text region')
+      })
+      .onError(error => {
+        t.fail('Unexpected error: ' + JSON.stringify(error))
+      })
+      .await()
+
+    t.pass('Run completed successfully')
+  } finally {
+    await ocrGgml.unload()
+    t.pass('Unload completed successfully')
+    await new Promise(resolve => setTimeout(resolve, 1000))
+  }
+})
+
+test('Load, unload, reload - model can be reloaded after unload', { timeout: TEST_TIMEOUT * 2 }, async function (t) {
+  const { ocrGgml, imagePath } = await createAndLoadOcr(t)
+
+  // First load
+  await ocrGgml.load()
+  t.pass('First load successful')
+
+  const response1 = await ocrGgml.run({
+    path: imagePath,
+    options: { paragraph: false }
+  })
+
+  let firstRunTexts = []
+  await response1
+    .onUpdate(output => {
+      firstRunTexts = output.map(o => o[1])
+    })
+    .await()
+
+  t.ok(firstRunTexts.length > 0, 'First run should produce output')
+  t.comment('First run texts: ' + JSON.stringify(firstRunTexts))
+
+  // Unload
+  await ocrGgml.unload()
+  t.pass('Unload successful')
+  await new Promise(resolve => setTimeout(resolve, 2000))
+
+  // Reload
+  await ocrGgml.load()
+  t.pass('Reload successful')
+
+  try {
+    const response2 = await ocrGgml.run({
+      path: imagePath,
+      options: { paragraph: false }
+    })
+
+    let secondRunTexts = []
+    await response2
+      .onUpdate(output => {
+        secondRunTexts = output.map(o => o[1])
+      })
+      .await()
+
+    t.ok(secondRunTexts.length > 0, 'Second run after reload should produce output')
+    t.comment('Second run texts: ' + JSON.stringify(secondRunTexts))
+
+    t.is(firstRunTexts.length, secondRunTexts.length, 'Both runs should detect same number of regions')
+    for (const text of firstRunTexts) {
+      t.ok(secondRunTexts.includes(text), `Reloaded model should detect "${text}"`)
+    }
+
+    t.pass('Model reload produced consistent results')
+  } finally {
+    await ocrGgml.unload()
+    await new Promise(resolve => setTimeout(resolve, 1000))
+  }
+})
+
+test('Double unload does not crash', { timeout: TEST_TIMEOUT }, async function (t) {
+  const { ocrGgml } = await createAndLoadOcr(t)
+
+  await ocrGgml.load()
+  t.pass('Model loaded')
+
+  await ocrGgml.unload()
+  t.pass('First unload successful')
+
+  try {
+    await ocrGgml.unload()
+    t.pass('Second unload did not throw')
+  } catch (err) {
+    t.comment('Second unload threw: ' + err.message)
+    t.pass('Second unload threw an error (acceptable behavior)')
+  }
+
+  await new Promise(resolve => setTimeout(resolve, 1000))
+})
+
+test('Run before load throws error', { timeout: TEST_TIMEOUT }, async function (t) {
+  const detectorPath = await ensureModelPath('detector_craft')
+  const recognizerPath = await ensureModelPath('recognizer_latin')
+  const imagePath = getImagePath('/test/images/basic_test.bmp')
+
+  const ocrGgml = new OcrGgml({
+    params: {
+      pathDetector: detectorPath,
+      pathRecognizer: recognizerPath,
+      langList: ['en']
+    }
+  })
+
+  try {
+    await ocrGgml.run({
+      path: imagePath,
+      options: { paragraph: false }
+    })
+    t.fail('Should have thrown when running before load')
+  } catch (err) {
+    t.ok(err, 'Should throw an error when running before load')
+    t.comment('Error: ' + err.message)
+    t.pass('Correctly prevented run before load')
+  }
+})
+
+test('Run after unload throws error', { timeout: TEST_TIMEOUT }, async function (t) {
+  const { ocrGgml, imagePath } = await createAndLoadOcr(t)
+
+  await ocrGgml.load()
+  await ocrGgml.unload()
+  await new Promise(resolve => setTimeout(resolve, 1000))
+
+  try {
+    await ocrGgml.run({
+      path: imagePath,
+      options: { paragraph: false }
+    })
+    t.fail('Should have thrown when running after unload')
+  } catch (err) {
+    t.ok(err, 'Should throw an error when running after unload')
+    t.comment('Error: ' + err.message)
+    t.pass('Correctly prevented run after unload')
+  }
+})
+
+test('Cancellation during inference does not crash', { timeout: TEST_TIMEOUT }, async function (t) {
+  const { ocrGgml, imagePath } = await createAndLoadOcr(t)
+
+  await ocrGgml.load()
+
+  try {
+    const response = await ocrGgml.run({
+      path: imagePath,
+      options: { paragraph: false }
+    })
+
+    // Cancel immediately after starting
+    if (ocrGgml.addon && ocrGgml.addon.cancel) {
+      await ocrGgml.addon.cancel()
+      t.pass('Cancel called without crashing')
+    } else {
+      t.comment('addon.cancel not available, skipping cancel test')
+    }
+
+    // After cancel, the response may never settle (no JobEnded event).
+    // Race against a short timeout so we don't hang the whole suite.
+    const CANCEL_WAIT_MS = 5000
+    try {
+      await Promise.race([
+        response.await(),
+        new Promise(function (resolve, reject) {
+          setTimeout(function () { reject(new Error('cancel: response did not settle')) }, CANCEL_WAIT_MS)
+        })
+      ])
+      t.comment('Response completed despite cancel (inference may have finished first)')
+    } catch (err) {
+      t.comment('Response after cancel: ' + err.message)
+    }
+
+    t.pass('Cancellation handled gracefully')
+  } finally {
+    try {
+      await ocrGgml.unload()
+    } catch (err) {
+      t.comment('Unload after cancel: ' + err.message)
+    }
+    await new Promise(resolve => setTimeout(resolve, 1000))
+  }
+})
+
+test('Performance parameters are accepted without error', { timeout: TEST_TIMEOUT }, async function (t) {
+  const detectorPath = await ensureModelPath('detector_craft')
+  const recognizerPath = await ensureModelPath('recognizer_latin')
+  const imagePath = getImagePath('/test/images/basic_test.bmp')
+
+  const ocrGgml = new OcrGgml({
+    params: {
+      pathDetector: detectorPath,
+      pathRecognizer: recognizerPath,
+      langList: ['en'],
+      magRatio: 1.5,
+      recognizerBatchSize: 4,
+      lowConfidenceThreshold: 0.3
+    },
+    opts: { stats: true }
+  })
+
+  await ocrGgml.load()
+
+  try {
+    const response = await ocrGgml.run({
+      path: imagePath,
+      options: { paragraph: false }
+    })
+
+    await response
+      .onUpdate(output => {
+        t.ok(Array.isArray(output), 'Output with custom params should be an array')
+        t.ok(output.length > 0, 'Should still detect text with custom performance params')
+        t.comment('Detected ' + output.length + ' regions with custom performance params')
+      })
+      .onError(error => {
+        t.fail('Unexpected error with performance params: ' + JSON.stringify(error))
+      })
+      .await()
+
+    t.pass('Performance parameters accepted and inference completed')
+  } finally {
+    await ocrGgml.unload()
+    await new Promise(resolve => setTimeout(resolve, 1000))
+  }
+})

package/test/integration/ocr-basic.test.js

@@ -0,0 +1,70 @@
+'use strict'
+
+const { OcrGgml } = require('../..')
+const test = require('brittle')
+const { isMobile, platform, getImagePath, ensureModelPath, formatOCRPerformanceMetrics } = require('./utils')
+
+const MOBILE_TIMEOUT = 600 * 1000 // 10 minutes for mobile
+const DESKTOP_TIMEOUT = 120 * 1000 // 2 minutes for desktop
+const TEST_TIMEOUT = isMobile ? MOBILE_TIMEOUT : DESKTOP_TIMEOUT
+
+test('OCR basic test', { timeout: TEST_TIMEOUT }, async function (t) {
+  const detectorPath = await ensureModelPath('detector_craft')
+  const recognizerPath = await ensureModelPath('recognizer_latin')
+  const imagePath = getImagePath('/test/images/basic_test.bmp')
+
+  t.comment('Testing basic OCR with image: ' + imagePath)
+  t.comment('Platform: ' + platform + ', isMobile: ' + isMobile)
+
+  const ocrGgml = new OcrGgml({
+    params: {
+      pathDetector: detectorPath,
+      pathRecognizer: recognizerPath,
+      langList: ['en']
+    },
+    opts: { stats: true }
+  })
+
+  await ocrGgml.load()
+  t.pass('OCR model loaded successfully')
+
+  try {
+    const response = await ocrGgml.run({
+      path: imagePath,
+      options: { paragraph: false }
+    })
+
+    let outputTexts = []
+
+    await response
+      .onUpdate(output => {
+        t.ok(Array.isArray(output), 'output should be an array')
+        t.ok(output.length === 3, `output length should be 3, got ${output.length}`)
+        outputTexts = output.map(o => o[1])
+        t.ok(outputTexts.includes('tilted'), 'should contain "tilted"')
+        t.ok(outputTexts.includes('normal'), 'should contain "normal"')
+        t.ok(outputTexts.includes('vertical'), 'should contain "vertical"')
+      })
+      .onError(error => {
+        t.fail('unexpected error: ' + JSON.stringify(error))
+      })
+      .await()
+
+    // Display stats
+    const stats = response.stats || {}
+    t.comment('Native addon stats: ' + JSON.stringify(stats))
+    t.comment(formatOCRPerformanceMetrics('[EasyOCR basic_test] [CPU]', stats, outputTexts))
+
+    t.pass('OCR basic test completed successfully')
+  } catch (e) {
+    t.fail('OCR test failed: ' + e.message)
+    throw e
+  } finally {
+    try {
+      await ocrGgml.unload()
+    } catch (e) {
+      t.comment('unload() error: ' + e.message)
+    }
+    await new Promise(resolve => setTimeout(resolve, 1000))
+  }
+})