pdf-oxide-fips 0.3.47

package/lib/managers/ocr-manager.js

@@ -0,0 +1,582 @@
+/**
+ * OcrManager - Canonical OCR Manager (merged from 3 implementations)
+ *
+ * Consolidates:
+ * - src/ocr-manager.ts (simple API with setLanguage, extractText, analyzePage)
+ * - src/managers/ocr-compliance-cache.ts OCRManager (engine lifecycle)
+ * - src/managers/ocr-manager-typed.ts OCRManager (full TypeScript, FFI-wired)
+ *
+ * Provides optical character recognition operations with complete type safety,
+ * proper error handling, and full FFI integration.
+ */
+import { promises as fs } from 'fs';
+import { dirname } from 'path';
+import { BaseManager, OcrLanguage, } from '../types/manager-types.js';
+// Re-export types for convenience
+export { OcrLanguage };
+/**
+ * OCR detection modes for accuracy/speed tradeoff
+ */
+export var OcrDetectionMode;
+(function (OcrDetectionMode) {
+    OcrDetectionMode["Accurate"] = "accurate";
+    OcrDetectionMode["Fast"] = "fast";
+    OcrDetectionMode["Balanced"] = "balanced";
+})(OcrDetectionMode || (OcrDetectionMode = {}));
+/**
+ * Canonical OcrManager - Comprehensive OCR with full TypeScript support
+ *
+ * Features:
+ * - Full text recognition with confidence scoring
+ * - Batch page processing with skip optimization
+ * - Text region detection with coordinates
+ * - Multi-language support
+ * - Comprehensive event emission
+ * - Automatic resource cleanup
+ * - Legacy API compatibility (setLanguage, extractText, analyzePage, etc.)
+ */
+export class OcrManager extends BaseManager {
+    constructor(document, options) {
+        super(document, options);
+        this.ocrEngine = null;
+        this.currentLanguage = OcrLanguage.ENGLISH;
+        this.preprocessingType = 'auto';
+        try {
+            this.native = require('../../index.node');
+        }
+        catch {
+            this.native = null;
+        }
+    }
+    // ==========================================================================
+    // Engine Lifecycle (from typed version)
+    // ==========================================================================
+    /**
+     * Initialize OCR engine with specified configuration
+     */
+    async initializeEngine(detectionThreshold = 0.5, recognitionThreshold = 0.5, maxSideLen = 960, useGpu = false, gpuDeviceId = 0) {
+        try {
+            this.recordOperation();
+            if (this.ocrEngine) {
+                return true;
+            }
+            this.ocrEngine = await this.document?.createOcrEngine(detectionThreshold, recognitionThreshold, maxSideLen, useGpu, gpuDeviceId);
+            if (this.ocrEngine) {
+                this.emit('ocr-engine-initialized', {
+                    useGpu,
+                    gpuDeviceId,
+                    detectionThreshold,
+                    recognitionThreshold,
+                });
+                return true;
+            }
+            return false;
+        }
+        catch (error) {
+            this.recordError(error instanceof Error ? error : new Error(String(error)));
+            throw error;
+        }
+    }
+    /**
+     * Destroy OCR engine and free resources
+     */
+    async destroyOcrEngine() {
+        try {
+            this.recordOperation();
+            if (this.ocrEngine) {
+                await this.document?.destroyOcrEngine(this.ocrEngine);
+                this.ocrEngine = null;
+                this.emit('ocr-engine-destroyed', { timestamp: Date.now() });
+            }
+        }
+        catch (error) {
+            this.recordError(error instanceof Error ? error : new Error(String(error)));
+            throw error;
+        }
+    }
+    // ==========================================================================
+    // Core Recognition (from typed version)
+    // ==========================================================================
+    /**
+     * Check if page needs OCR processing
+     */
+    async pageNeedsOcr(pageIndex) {
+        try {
+            this.recordOperation();
+            return (await this.document?.pageNeedsOcr(pageIndex)) || false;
+        }
+        catch (error) {
+            this.recordError(error instanceof Error ? error : new Error(String(error)));
+            throw error;
+        }
+    }
+    /**
+     * Recognize text on a page with full confidence scoring
+     */
+    async recognizePage(pageIndex) {
+        try {
+            this.recordOperation();
+            if (!this.ocrEngine) {
+                throw new Error('OCR engine not initialized. Call initializeEngine() first.');
+            }
+            const text = await this.document?.recognizePage(pageIndex, this.ocrEngine);
+            this.emit('page-recognized', {
+                pageIndex,
+                textLength: text?.length || 0,
+                timestamp: Date.now(),
+            });
+            return text || '';
+        }
+        catch (error) {
+            this.recordError(error instanceof Error ? error : new Error(String(error)));
+            throw error;
+        }
+    }
+    /**
+     * Get OCR confidence score for a page
+     */
+    async getOcrConfidence(pageIndex) {
+        try {
+            this.recordOperation();
+            if (!this.ocrEngine) {
+                return 0;
+            }
+            return (await this.document?.getOcrConfidence(pageIndex)) || 0;
+        }
+        catch (error) {
+            this.recordError(error instanceof Error ? error : new Error(String(error)));
+            throw error;
+        }
+    }
+    /**
+     * Detect text regions on a page with bounding boxes
+     */
+    async detectTextRegions(pageIndex) {
+        try {
+            this.recordOperation();
+            if (!this.ocrEngine) {
+                return [];
+            }
+            const regions = await this.document?.detectTextRegions(pageIndex, this.ocrEngine);
+            return regions || [];
+        }
+        catch (error) {
+            this.recordError(error instanceof Error ? error : new Error(String(error)));
+            throw error;
+        }
+    }
+    // ==========================================================================
+    // Language Configuration (from typed + root versions)
+    // ==========================================================================
+    /**
+     * Set OCR language for recognition (FFI-wired)
+     */
+    async setOcrLanguage(language) {
+        try {
+            this.recordOperation();
+            if (!this.ocrEngine) {
+                throw new Error('OCR engine not initialized');
+            }
+            const result = await this.document?.setOcrLanguage(this.ocrEngine, language);
+            if (result) {
+                this.currentLanguage = language || OcrLanguage.ENGLISH;
+                this.emit('language-changed', {
+                    language,
+                    timestamp: Date.now(),
+                });
+            }
+            return !!result;
+        }
+        catch (error) {
+            this.recordError(error instanceof Error ? error : new Error(String(error)));
+            throw error;
+        }
+    }
+    /**
+     * Sets the OCR language (convenience alias for setOcrLanguage)
+     * From root-level OCRManager
+     */
+    setLanguage(language) {
+        this.currentLanguage = language;
+        this.invalidateCache('ocr');
+        this.emit('languageChanged', language);
+    }
+    /**
+     * Gets the current OCR language
+     * From root-level OCRManager
+     */
+    getLanguage() {
+        return this.currentLanguage;
+    }
+    /**
+     * Get available OCR languages
+     */
+    async getAvailableLanguages() {
+        try {
+            this.recordOperation();
+            const languages = (await this.document?.getAvailableLanguages()) || Object.values(OcrLanguage);
+            return languages;
+        }
+        catch (error) {
+            this.recordError(error instanceof Error ? error : new Error(String(error)));
+            throw error;
+        }
+    }
+    // ==========================================================================
+    // Processing & Export (from typed version)
+    // ==========================================================================
+    /**
+     * Preprocess page before OCR for better recognition
+     */
+    async preprocessPage(pageIndex, preprocessingType = 'auto') {
+        try {
+            this.recordOperation();
+            const result = await this.document?.preprocessPage(pageIndex, preprocessingType);
+            this.preprocessingType = preprocessingType;
+            this.emit('page-preprocessed', {
+                pageIndex,
+                type: preprocessingType,
+                timestamp: Date.now(),
+            });
+            return !!result;
+        }
+        catch (error) {
+            this.recordError(error instanceof Error ? error : new Error(String(error)));
+            throw error;
+        }
+    }
+    /**
+     * Export OCR text to file
+     */
+    async exportOcrText(pageIndex, filePath, format = 'txt') {
+        try {
+            this.recordOperation();
+            const text = await this.recognizePage(pageIndex);
+            await fs.mkdir(dirname(filePath), { recursive: true });
+            let content;
+            switch (format) {
+                case 'json':
+                    content = JSON.stringify({ pageIndex, text, timestamp: Date.now() }, null, 2);
+                    break;
+                case 'xml':
+                    content = `<?xml version="1.0"?>\n<page index="${pageIndex}">\n${text
+                        .split('\n')
+                        .map((line) => `  <line>${line}</line>`)
+                        .join('\n')}\n</page>`;
+                    break;
+                default:
+                    content = text;
+            }
+            await fs.writeFile(filePath, content, 'utf8');
+            this.emit('text-exported', {
+                pageIndex,
+                filePath,
+                format,
+                size: content.length,
+                timestamp: Date.now(),
+            });
+            return true;
+        }
+        catch (error) {
+            this.recordError(error instanceof Error ? error : new Error(String(error)));
+            throw error;
+        }
+    }
+    // ==========================================================================
+    // Statistics & Batch (from typed version)
+    // ==========================================================================
+    /**
+     * Get comprehensive OCR statistics for a page
+     */
+    async getOcrStatistics(pageIndex) {
+        try {
+            this.recordOperation();
+            const text = await this.recognizePage(pageIndex);
+            const confidence = await this.getOcrConfidence(pageIndex);
+            const regions = await this.detectTextRegions(pageIndex);
+            return {
+                pageIndex,
+                text,
+                confidence,
+                regionCount: regions.length,
+            };
+        }
+        catch (error) {
+            this.recordError(error instanceof Error ? error : new Error(String(error)));
+            throw error;
+        }
+    }
+    /**
+     * Batch recognize multiple pages
+     */
+    async batchRecognizePages(startPage, endPage) {
+        try {
+            this.recordOperation();
+            const results = new Map();
+            for (let i = startPage; i <= endPage; i++) {
+                const text = await this.recognizePage(i);
+                results.set(i, text);
+            }
+            this.emit('batch-recognized', {
+                startPage,
+                endPage,
+                pageCount: endPage - startPage + 1,
+                totalCharacters: Array.from(results.values()).reduce((s, t) => s + t.length, 0),
+                timestamp: Date.now(),
+            });
+            return results;
+        }
+        catch (error) {
+            this.recordError(error instanceof Error ? error : new Error(String(error)));
+            throw error;
+        }
+    }
+    /**
+     * Extract OCR text with aggregated statistics from page range (FFI-wired)
+     */
+    async extractPageRange(startPage, endPage, skipNonScanned = true) {
+        try {
+            this.recordOperation();
+            if (!this.ocrEngine) {
+                throw new Error('OCR engine not initialized');
+            }
+            let totalSpans = 0;
+            let confidenceSum = 0;
+            let skippedPages = 0;
+            for (let pageIdx = startPage; pageIdx <= endPage; pageIdx++) {
+                try {
+                    if (skipNonScanned) {
+                        const needsOcr = await this.pageNeedsOcr(pageIdx);
+                        if (!needsOcr) {
+                            skippedPages++;
+                            continue;
+                        }
+                    }
+                    const text = await this.recognizePage(pageIdx);
+                    const confidence = await this.getOcrConfidence(pageIdx);
+                    const regions = await this.detectTextRegions(pageIdx);
+                    totalSpans += Math.max(regions.length, text ? 1 : 0);
+                    confidenceSum += confidence;
+                }
+                catch { }
+            }
+            const processedPages = endPage - startPage + 1 - skippedPages;
+            const avgConfidence = processedPages > 0 ? confidenceSum / processedPages : 0;
+            const result = {
+                startPage,
+                endPage,
+                totalPages: endPage - startPage + 1,
+                totalSpans,
+                averageConfidence: avgConfidence,
+                skippedPages,
+            };
+            this.emit('page-range-extracted', {
+                ...result,
+                timestamp: Date.now(),
+            });
+            this.setCached(`ocr-batch:${startPage}-${endPage}`, result);
+            return result;
+        }
+        catch (error) {
+            this.recordError(error instanceof Error ? error : new Error(String(error)));
+            throw error;
+        }
+    }
+    // ==========================================================================
+    // Engine Status & Configuration (from typed version)
+    // ==========================================================================
+    /**
+     * Get OCR engine status and configuration
+     */
+    async getEngineStatus() {
+        try {
+            this.recordOperation();
+            if (!this.ocrEngine) {
+                return 'not_initialized';
+            }
+            return (await this.document?.getEngineStatus(this.ocrEngine)) || 'unknown';
+        }
+        catch (error) {
+            this.recordError(error instanceof Error ? error : new Error(String(error)));
+            throw error;
+        }
+    }
+    /**
+     * Get current OCR configuration
+     */
+    getConfiguration() {
+        return {
+            language: this.currentLanguage,
+            preprocessingType: this.preprocessingType,
+            engineInitialized: !!this.ocrEngine,
+        };
+    }
+    // ==========================================================================
+    // Methods from root-level OCRManager
+    // ==========================================================================
+    /**
+     * Extracts text from a page (convenience alias for recognizePage)
+     * From root-level OCRManager
+     */
+    async extractText(pageIndex, config) {
+        const cacheKey = `ocr:text:${pageIndex}:${this.currentLanguage}`;
+        const cached = this.getCached(cacheKey);
+        if (cached !== undefined) {
+            return cached;
+        }
+        let result = '';
+        if (this.document?.extractText) {
+            result = this.document.extractText(pageIndex) || '';
+        }
+        this.setCached(cacheKey, result);
+        this.emit('textExtracted', pageIndex, result.length);
+        return result;
+    }
+    /**
+     * Analyzes a page and returns detailed results
+     * From root-level OCRManager
+     */
+    async analyzePage(pageIndex, config) {
+        const cacheKey = `ocr:analysis:${pageIndex}:${this.currentLanguage}`;
+        const cached = this.getCached(cacheKey);
+        if (cached !== undefined) {
+            return cached;
+        }
+        let text = '';
+        let needsOcr = false;
+        if (this.document?.extractText) {
+            text = this.document.extractText(pageIndex) || '';
+            needsOcr = !text || text.trim().length < 10;
+        }
+        const result = {
+            pageIndex,
+            needsOcr,
+            confidence: needsOcr ? 0.0 : 0.95,
+            spanCount: text.split(' ').length || 0,
+            text,
+        };
+        this.setCached(cacheKey, result);
+        this.emit('pageAnalyzed', pageIndex, result);
+        return result;
+    }
+    /**
+     * Performs OCR analysis on all pages in the document
+     * From root-level OCRManager
+     */
+    async analyzeDocument(config) {
+        const cacheKey = `ocr:document:${this.currentLanguage}`;
+        const cached = this.getCached(cacheKey);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const results = [];
+        const pageCount = this.document?.pageCount || 0;
+        for (let i = 0; i < pageCount; i++) {
+            const analysis = await this.analyzePage(i, config);
+            results.push(analysis);
+            this.emit('pageProcessed', i + 1, pageCount);
+        }
+        this.setCached(cacheKey, results);
+        this.emit('documentAnalyzed', results.length);
+        return results;
+    }
+    /**
+     * Extracts text spans with bounding boxes for a page
+     * From root-level OCRManager
+     */
+    async extractSpans(pageIndex, config) {
+        const cacheKey = `ocr:spans:${pageIndex}:${this.currentLanguage}`;
+        const cached = this.getCached(cacheKey);
+        if (cached !== undefined) {
+            return cached;
+        }
+        let spans = [];
+        if (this.native?.extract_spans) {
+            try {
+                const spansJson = this.native.extract_spans(pageIndex) ?? [];
+                spans = spansJson.length > 0 ? spansJson.map((json) => JSON.parse(json)) : [];
+            }
+            catch {
+                spans = [];
+            }
+        }
+        this.setCached(cacheKey, spans);
+        this.emit('spansExtracted', { page: pageIndex, count: spans.length });
+        return spans;
+    }
+    /**
+     * Checks if OCR is available/installed
+     * From root-level OCRManager
+     */
+    async isAvailable() {
+        const cacheKey = 'ocr:available';
+        const cached = this.getCached(cacheKey);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const result = this.native ? true : false;
+        this.setCached(cacheKey, result);
+        return result;
+    }
+    /**
+     * Gets OCR engine version
+     * From root-level OCRManager
+     */
+    async getVersion() {
+        const cacheKey = 'ocr:version';
+        const cached = this.getCached(cacheKey);
+        if (cached !== undefined) {
+            return cached;
+        }
+        let version = '0.0.0';
+        if (this.native?.get_ocr_version) {
+            try {
+                version = this.native.get_ocr_version() ?? '0.0.0';
+            }
+            catch {
+                version = '0.0.0';
+            }
+        }
+        this.setCached(cacheKey, version);
+        return version;
+    }
+    // ==========================================================================
+    // Cache Operations (from root-level OCRManager)
+    // ==========================================================================
+    /**
+     * Clears the result cache
+     */
+    clearCache() {
+        this.invalidateCache();
+        this.emit('cacheCleared');
+    }
+    /**
+     * Gets cache statistics
+     */
+    getCacheStats() {
+        return {
+            cacheSize: this.cache.size,
+            entries: Array.from(this.cache.keys()),
+        };
+    }
+    // ==========================================================================
+    // Cleanup
+    // ==========================================================================
+    /**
+     * Cleanup on destroy
+     */
+    async destroy() {
+        try {
+            await this.destroyOcrEngine();
+            this.invalidateCache();
+            this.removeAllListeners();
+            this.initialized = false;
+        }
+        catch (error) {
+            console.error('Error during OCR manager cleanup:', error);
+        }
+    }
+}
+/** @deprecated Use OcrManager instead */
+export const OCRManager = OcrManager;
+export default OcrManager;

package/lib/managers/optimization-manager.d.ts

@@ -0,0 +1,102 @@
+/**
+ * OptimizationManager - PDF Optimization Operations
+ *
+ * Provides document optimization capabilities including:
+ * - Font subsetting
+ * - Image downsampling
+ * - Object deduplication
+ * - Full optimization pipeline
+ *
+ * @since 1.0.0
+ */
+import { EventEmitter } from 'events';
+/**
+ * Result of an optimization operation.
+ */
+export interface OptimizationResult {
+    /** Whether the optimization succeeded */
+    readonly success: boolean;
+    /** Number of bytes saved */
+    readonly bytesSaved: number;
+    /** Original document size in bytes */
+    readonly originalSize: number;
+    /** Optimized document size in bytes */
+    readonly optimizedSize: number;
+    /** Compression ratio (0.0 - 1.0) */
+    readonly compressionRatio: number;
+}
+/**
+ * Manager for PDF optimization operations.
+ *
+ * Provides methods for reducing PDF file size through font subsetting,
+ * image downsampling, object deduplication, and combined optimization.
+ *
+ * @example
+ * ```typescript
+ * const optimizer = new OptimizationManager(document);
+ *
+ * // Subset fonts to remove unused glyphs
+ * const fontResult = await optimizer.subsetFonts();
+ * console.log(`Font subsetting saved ${fontResult.bytesSaved} bytes`);
+ *
+ * // Downsample high-resolution images
+ * const imageResult = await optimizer.downsampleImages(150, 80);
+ *
+ * // Full optimization pipeline
+ * const fullResult = await optimizer.optimizeFull(150, 80);
+ * console.log(`Total savings: ${fullResult.bytesSaved} bytes`);
+ * ```
+ */
+export declare class OptimizationManager extends EventEmitter {
+    private document;
+    private native;
+    constructor(document: any);
+    /**
+     * Subsets all embedded fonts in the document.
+     *
+     * Removes unused glyphs from embedded fonts, reducing file size
+     * while preserving visual fidelity for the characters actually used.
+     *
+     * @returns Optimization result with bytes saved
+     * @throws OptimizationException if the operation fails
+     */
+    subsetFonts(): Promise<OptimizationResult>;
+    /**
+     * Downsamples images in the document to reduce file size.
+     *
+     * @param dpi - Target resolution in dots per inch (default: 150)
+     * @param quality - JPEG quality for recompression (1-100, default: 80)
+     * @returns Optimization result with bytes saved
+     * @throws OptimizationException if the operation fails
+     */
+    downsampleImages(dpi?: number, quality?: number): Promise<OptimizationResult>;
+    /**
+     * Deduplicates identical objects in the document.
+     *
+     * Identifies and merges duplicate fonts, images, and other resources
+     * that appear multiple times in the document.
+     *
+     * @returns Optimization result with bytes saved
+     * @throws OptimizationException if the operation fails
+     */
+    deduplicate(): Promise<OptimizationResult>;
+    /**
+     * Runs the full optimization pipeline.
+     *
+     * Combines font subsetting, image downsampling, and object deduplication
+     * into a single operation for maximum file size reduction.
+     *
+     * @param dpi - Target image resolution in dots per inch (default: 150)
+     * @param quality - JPEG quality for recompression (1-100, default: 80)
+     * @returns Optimization result with total bytes saved
+     * @throws OptimizationException if the operation fails
+     */
+    optimizeFull(dpi?: number, quality?: number): Promise<OptimizationResult>;
+    private parseOptimizationResult;
+    private freeOptimizationResult;
+    /**
+     * Releases resources held by this manager.
+     */
+    destroy(): void;
+}
+export default OptimizationManager;