img-duplicates/dist/lib.d.ts

Find duplicate images based on visual similarity

/**
 * Configuration options for the duplicate image detection algorithm.
 */
interface Options {
    /**
     * Size of the hash grid used for perceptual hashing.
     * Larger values provide more precision but require more processing time.
     * @default 8
     */
    hashSize?: number;
    /**
     * Maximum number of duplicate images to find for each source image.
     * @default 100
     */
    maxDuplicates?: number;
    /**
     * Maximum Hamming distance between image hashes to consider them as duplicates.
     * Lower values require higher visual similarity.
     * @default 5
     */
    maxDistance?: number;
}
/**
 * Finds duplicate images based on visual similarity using perceptual hashing.
 *
 * This function analyzes images using difference hashing (dHash) to create perceptual fingerprints
 * and then uses a k-d tree for efficient similarity matching. Images are considered duplicates
 * if their hash distance is within the specified threshold.
 *
 * @param source - Path to a directory containing images, or an array of paths to directories and/or image files
 * @param options - Configuration options for the duplicate detection algorithm
 * @param options.hashSize - Size of the hash grid (default: 8). Larger values provide more precision but slower processing
 * @param options.maxDuplicates - Maximum number of duplicates to find per image (default: 100)
 * @param options.maxDistance - Maximum Hamming distance between hashes to consider images as duplicates (default: 5). Lower values require higher similarity
 *
 * @returns Promise that resolves to an array of duplicate groups. Each group is an array of image objects
 *          containing path, width, and height. Images within each group are sorted by resolution (highest first).
 *
 * @throws {Error} When image metadata cannot be read or when source paths don't exist
 *
 * @example
 * ```typescript
 * // Find duplicates in a single directory
 * const duplicates = await findDuplicateImages('/path/to/images');
 *
 * // Find duplicates across multiple sources with custom settings
 * const duplicates = await findDuplicateImages(
 *   ['/path/to/dir1', '/path/to/dir2', '/path/to/image.jpg'],
 *   {
 *     hashSize: 16,     // Higher precision
 *     maxDistance: 3,   // Stricter similarity
 *     maxDuplicates: 5  // Limit results
 *   }
 * );
 *
 * // Process results
 * duplicates.forEach((group, index) => {
 *   console.log(`Duplicate group ${index + 1}:`);
 *   group.forEach((image, i) => {
 *     const isHighest = i === 0 ? '(highest resolution)' : '';
 *     console.log(`  ${image.path} [${image.width}x${image.height}] ${isHighest}`);
 *   });
 * });
 * ```
 *
 * @since 1.0.0
 */
declare function findDuplicateImages(source: string | string[], { hashSize, maxDuplicates, maxDistance, }?: Options): Promise<Array<Array<{
    path: string;
    width: number;
    height: number;
}>>>;

export { findDuplicateImages as default };
export = findDuplicateImages