pdq-wasm/dist/esm/pdq.d.ts

WebAssembly bindings for Meta's PDQ perceptual image hashing algorithm

/**
 * PDQ (Perceptual Hash) WebAssembly bindings
 *
 * Copyright (c) Meta Platforms, Inc. and affiliates (original algorithm)
 * Copyright (c) 2025 (WebAssembly bindings)
 */
import type { PDQHash, PDQHashResult, ImageData, PDQOptions, PDQWorkerOptions, SimilarityMatch, LoggerFunction } from './types';
/**
 * PDQ WebAssembly implementation
 */
export declare class PDQ {
    private static module;
    private static initPromise;
    private static loggerFn;
    private static ignoreInvalidFlag;
    /**
     * Set a custom logger function to log PDQ operations
     * @param logger Function that receives log messages
     * @returns PDQ class for method chaining
     *
     * @example
     * PDQ.logger((msg) => console.log('[PDQ]', msg));
     */
    static setLogger(logger: LoggerFunction): typeof PDQ;
    /**
     * Enable console logging (convenience method)
     * @returns PDQ class for method chaining
     *
     * @example
     * PDQ.consoleLog();
     */
    static consoleLog(): typeof PDQ;
    /**
     * Disable logging
     * @returns PDQ class for method chaining
     */
    static disableLogging(): typeof PDQ;
    /**
     * Enable ignore invalid mode - log errors instead of throwing
     * @returns PDQ class for method chaining
     *
     * @example
     * PDQ.ignoreInvalid().consoleLog();
     */
    static ignoreInvalid(): typeof PDQ;
    /**
     * Disable ignore invalid mode - throw errors normally
     * @returns PDQ class for method chaining
     */
    static throwOnInvalid(): typeof PDQ;
    /**
     * Internal logging method
     */
    private static log;
    /**
     * Internal error handling method
     * Either throws or logs based on ignoreInvalidFlag
     */
    private static handleError;
    /**
     * Initialize the WASM module
     * Must be called before using any PDQ functions
     *
     * @param options Configuration options
     * @param options.wasmUrl URL to load WASM module from (browser only, defaults to CDN)
     *
     * @example
     * // Node.js (uses bundled WASM)
     * await PDQ.init();
     *
     * @example
     * // Browser (automatically uses CDN)
     * await PDQ.init();
     *
     * @example
     * // Browser with custom URL
     * await PDQ.init({
     *   wasmUrl: '/assets/pdq.wasm'
     * });
     */
    static init(options?: PDQOptions): Promise<void>;
    /**
     * Initialize the WASM module in a Web Worker environment
     * Must be called before using any PDQ functions in a worker
     *
     * @param options Worker initialization options
     * @param options.wasmUrl URL to the WASM file
     * @param options.wasmJsUrl URL to the WASM JavaScript glue code (optional, defaults to wasmUrl.replace('.wasm', '.js'))
     *
     * @example
     * // In a Web Worker
     * await PDQ.initWorker({
     *   wasmUrl: 'https://unpkg.com/pdq-wasm@0.3.3/wasm/pdq.wasm'
     * });
     *
     * @example
     * // With custom JS glue code URL
     * await PDQ.initWorker({
     *   wasmUrl: '/wasm/pdq.wasm',
     *   wasmJsUrl: '/wasm/pdq.js'
     * });
     */
    static initWorker(options: PDQWorkerOptions): Promise<void>;
    /**
     * Try loading WASM factory using importScripts (for classic workers)
     */
    private static tryLoadViaImportScripts;
    /**
     * Try loading WASM factory using dynamic import (for ES module workers)
     */
    private static tryLoadViaDynamicImport;
    /**
     * Load WASM factory using appropriate method for the worker environment
     */
    private static loadWorkerFactory;
    /**
     * Ensure the module is initialized
     */
    private static ensureInit;
    /**
     * Hash image data and return PDQ hash with quality score
     *
     * @param imageData Image pixel data (RGB or grayscale)
     * @returns PDQ hash and quality score
     */
    static hash(imageData: ImageData): PDQHashResult;
    /**
     * Calculate Hamming distance between two PDQ hashes
     * Returns a value from 0 (identical) to 256 (completely different)
     *
     * @param hash1 First PDQ hash
     * @param hash2 Second PDQ hash
     * @returns Hamming distance (0-256)
     */
    static hammingDistance(hash1: PDQHash, hash2: PDQHash): number;
    /**
     * Convert a PDQ hash to hexadecimal string representation
     *
     * @param hash PDQ hash bytes
     * @returns Hexadecimal string (64 characters)
     */
    static toHex(hash: PDQHash): string;
    /**
     * Convert a hexadecimal string to PDQ hash bytes
     *
     * @param hex Hexadecimal string (64 characters)
     * @returns PDQ hash bytes
     */
    static fromHex(hex: string): PDQHash;
    /**
     * Check if two hashes are similar based on a threshold
     *
     * @param hash1 First PDQ hash
     * @param hash2 Second PDQ hash
     * @param threshold Maximum Hamming distance to consider similar (default: 31)
     * @returns True if hashes are similar
     */
    static areSimilar(hash1: PDQHash, hash2: PDQHash, threshold?: number): boolean;
    /**
     * Get similarity percentage between two hashes (0-100)
     *
     * @param hash1 First PDQ hash
     * @param hash2 Second PDQ hash
     * @returns Similarity percentage (0 = completely different, 100 = identical)
     */
    static similarity(hash1: PDQHash, hash2: PDQHash): number;
    /**
     * Order an array of hashes by similarity to a reference hash
     * Returns hashes sorted from most similar to least similar
     *
     * @param referenceHash The reference hash to compare against
     * @param hashes Array of hashes to order
     * @param includeIndex Whether to include original array index (default: false)
     * @returns Array of SimilarityMatch objects ordered by distance (ascending)
     */
    static orderBySimilarity(referenceHash: PDQHash, hashes: PDQHash[], includeIndex?: boolean): SimilarityMatch[];
}
export default PDQ;
//# sourceMappingURL=pdq.d.ts.map