Repository Public License
1// ORIX Secure2// File: Packages/ORIXMediaCleanup/Tests/ORIXMediaCleanupTests/FingerprintTests.swift3// Description: Perceptual-hash behaviour measured on programmatic images: distances per transformation and precision / recall4// of similar-photo grouping on a synthetic set with known ground truth.5//6// Author: Simon-Pierre Boucher7// Contact: contact@spboucher.ai8import CoreGraphics9import Foundation10import Testing11@testable import ORIXMediaCleanup1213@Suite("Perceptual fingerprints")14struct FingerprintTests {15 struct Transformation: Sendable {16 var name: String17 var mustMatch: Bool?18 var apply: @Sendable (CGImage) -> CGImage19 }2021 static let transformations: [Transformation] = [22 Transformation(name: "identical copy", mustMatch: true) { TestImages.mapPixels($0) { _, _, _ in } },23 Transformation(name: "JPEG q=0.90", mustMatch: true) { TestImages.jpeg($0, quality: 0.9) },24 Transformation(name: "JPEG q=0.60", mustMatch: true) { TestImages.jpeg($0, quality: 0.6) },25 Transformation(name: "JPEG q=0.35", mustMatch: true) { TestImages.jpeg($0, quality: 0.35) },26 Transformation(name: "resize 50 %", mustMatch: true) { TestImages.resized($0, scale: 0.5) },27 Transformation(name: "resize 150 %", mustMatch: true) { TestImages.resized($0, scale: 1.5) },28 Transformation(name: "brightness +18", mustMatch: nil) { TestImages.brightened($0, by: 18) },29 Transformation(name: "crop 2 %", mustMatch: nil) { TestImages.cropped($0, fraction: 0.02) },30 Transformation(name: "shift 2 %", mustMatch: nil) { TestImages.shifted($0, fraction: 0.02) },31 Transformation(name: "red/blue swapped", mustMatch: false) { TestImages.colorSwapped($0) },32 ]3334 @Test("Hamming distance")35 func hamming() {36 #expect(ImageFingerprint.hammingDistance(0, 0) == 0)37 #expect(ImageFingerprint.hammingDistance(0, .max) == 64)38 #expect(ImageFingerprint.hammingDistance(0b1011, 0b0010) == 2)39 }4041 @Test("Fingerprint is deterministic and well-formed")42 func deterministic() {43 let image = TestImages.scene(seed: 7)44 let a = TestImages.fingerprint(image)45 let b = TestImages.fingerprint(image)46 #expect(a == b)47 #expect(a.colorSignature.count == ImageFingerprint.colorSignatureLength)48 #expect(a.pHash & 1 == 0)49 #expect(a.colorDistance(to: a) == 0)50 let malformed = ImageFingerprint(dHash: 0, pHash: 0, meanLuma: 0, colorSignature: [1, 2])51 #expect(a.colorDistance(to: malformed) == 255)52 }5354 @Test("A uniform brightness offset does not move the colour distance; other colours do")55 func colourDistance() {56 let base = Fixture.fingerprint(d: 1, signature: (0..<48).map { UInt8(40 + $0 * 3) })57 let brighter = Fixture.fingerprint(d: 1, signature: (0..<48).map { UInt8(60 + $0 * 3) })58 #expect(base.colorDistance(to: brighter) == 0)59 var swapped = base.colorSignature60 for cell in 0..<16 { swapped.swapAt(cell * 3, cell * 3 + 2) }61 #expect(base.colorDistance(to: Fixture.fingerprint(d: 1, signature: swapped)) > 0)62 }6364 @Test("Distances by transformation (measured and printed)")65 func distancesByTransformation() {66 let analyzer = CleanupAnalyzer()67 let seeds = (1...60).map { UInt64($0) }68 let originals = seeds.map { TestImages.scene(seed: $0) }69 let fingerprints = originals.map(TestImages.fingerprint)70 print("FINGERPRINT DISTANCES over \(seeds.count) scenes — mean / p95 / max (dHash, pHash, colour, luma), match rate at default thresholds")71 for transformation in Self.transformations {72 var d: [Int] = [], p: [Int] = [], c: [Int] = [], l: [Int] = []73 var matched = 074 for (index, original) in originals.enumerated() {75 let variant = TestImages.fingerprint(transformation.apply(original))76 d.append(fingerprints[index].dHashDistance(to: variant))77 p.append(fingerprints[index].pHashDistance(to: variant))78 c.append(fingerprints[index].colorDistance(to: variant))79 l.append(fingerprints[index].lumaDifference(to: variant))80 if analyzer.areSimilar(fingerprints[index], variant) { matched += 1 }81 }82 let rate = Double(matched) / Double(seeds.count)83 print(" \(transformation.name.padding(toLength: 18, withPad: " ", startingAt: 0)) d \(Self.stats(d)) p \(Self.stats(p)) colour \(Self.stats(c)) luma \(Self.stats(l)) match \(String(format: "%.2f", rate))")84 switch transformation.mustMatch {85 case .some(true): #expect(rate >= 0.95, "\(transformation.name)")86 case .some(false): #expect(matched == 0, "\(transformation.name)")87 case .none: break88 }89 if transformation.mustMatch == false {90 print(" smallest colour distance of a red/blue swap: \(c.min() ?? -1) (threshold \(analyzer.configuration.colorThreshold)); pairs within both hash thresholds: \(zip(d, p).filter { $0 <= 8 && $1 <= 10 }.count) of \(d.count)")91 }92 if transformation.name == "identical copy" {93 #expect(d.max() == 0)94 #expect(p.max() == 0)95 }96 }97 // Unrelated scenes: every pair of different seeds.98 var d: [Int] = [], p: [Int] = []99 var matched = 0100 for i in 0..<fingerprints.count {101 for j in (i + 1)..<fingerprints.count {102 d.append(fingerprints[i].dHashDistance(to: fingerprints[j]))103 p.append(fingerprints[i].pHashDistance(to: fingerprints[j]))104 if analyzer.areSimilar(fingerprints[i], fingerprints[j]) { matched += 1 }105 }106 }107 print(" unrelated pairs d min \(d.min() ?? -1) mean \(d.reduce(0, +) / d.count) p min \(p.min() ?? -1) mean \(p.reduce(0, +) / p.count) matches \(matched) of \(d.count)")108 #expect(matched == 0)109 }110111 @Test("Noise images are unrelated to each other")112 func noiseUnrelated() {113 let analyzer = CleanupAnalyzer()114 let prints = (0..<20).map { TestImages.fingerprint(TestImages.noise(seed: UInt64(1000 + $0))) }115 for i in 0..<prints.count {116 for j in (i + 1)..<prints.count {117 let similar = analyzer.areSimilar(prints[i], prints[j])118 #expect(!similar)119 }120 }121 }122123 @Test("Degenerate images do not crash")124 func degenerate() {125 let tiny = TestImages.context(width: 1, height: 1).makeImage()!126 #expect(ImageFingerprinter.fingerprint(of: tiny) != nil)127 let flat = TestImages.context(width: 64, height: 64)128 flat.setFillColor(gray: 0.3, alpha: 1)129 flat.fill(CGRect(x: 0, y: 0, width: 64, height: 64))130 let print = ImageFingerprinter.fingerprint(of: flat.makeImage()!)131 #expect(print?.dHash == 0)132 let wide = TestImages.resized(TestImages.scene(seed: 3, width: 900, height: 30), scale: 1)133 #expect(ImageFingerprinter.fingerprint(of: wide) != nil)134 }135136 @Test("Grouping precision and recall on 360 synthetic photos")137 func precisionRecall() async throws {138 let seeds = (1...40).map { UInt64($0 + 500) }139 let positive = Self.transformations.filter { $0.mustMatch == true } + Self.transformations.filter { $0.name == "brightness +18" }140 struct Sample { var id: String; var seed: UInt64; var role: String; var fingerprint: ImageFingerprint }141 var samples: [Sample] = []142 for seed in seeds {143 let original = TestImages.scene(seed: seed)144 samples.append(Sample(id: "s\(seed)-original", seed: seed, role: "original", fingerprint: TestImages.fingerprint(original)))145 for transformation in positive {146 samples.append(Sample(id: "s\(seed)-\(transformation.name)", seed: seed, role: transformation.name, fingerprint: TestImages.fingerprint(transformation.apply(original))))147 }148 // Same structure, other colours: its own class, must not join its origin.149 samples.append(Sample(id: "s\(seed)-swapped", seed: seed + 1_000_000, role: "swapped", fingerprint: TestImages.fingerprint(TestImages.colorSwapped(original))))150 }151 #expect(samples.count >= 300)152 // All photos in one capture session, 5 s apart, in a shuffled order so different scenes are interleaved.153 var rng = SeededGenerator(seed: 99)154 let order = samples.indices.shuffled(using: &rng)155 var items: [MediaItem] = []156 var seedOf: [String: UInt64] = [:]157 var roleOf: [String: String] = [:]158 for (position, index) in order.enumerated() {159 let sample = samples[index]160 items.append(Fixture.photo(sample.id, at: Double(position) * 5, fingerprint: sample.fingerprint, width: 256, height: 192))161 seedOf[sample.id] = sample.seed162 roleOf[sample.id] = sample.role163 }164 let analysis = try await CleanupAnalyzer().analyze(items)165 let groups = analysis.groups(in: .similar) + analysis.groups(in: .burstLike) + analysis.groups(in: .probableDuplicates)166 var groupOf: [String: String] = [:]167 var groupedPairs = 0, correctPairs = 0, mixedGroups = 0168 for group in groups {169 let ids = group.items.map { $0.id }170 for id in ids { groupOf[id] = group.id }171 if Set(ids.compactMap { seedOf[$0] }).count > 1 { mixedGroups += 1 }172 for i in 0..<ids.count {173 for j in (i + 1)..<ids.count {174 groupedPairs += 1175 if seedOf[ids[i]] == seedOf[ids[j]] { correctPairs += 1 }176 }177 }178 }179 // Recall per role: the variant is in the same group as its original.180 var found: [String: Int] = [:]181 var reencodeFound = 0, reencodeTotal = 0182 for sample in samples where sample.role != "original" && sample.role != "swapped" {183 let together = groupOf[sample.id] != nil && groupOf[sample.id] == groupOf["s\(sample.seed)-original"]184 if together { found[sample.role, default: 0] += 1 }185 if sample.role.hasPrefix("JPEG") || sample.role.hasPrefix("resize") {186 reencodeTotal += 1187 if together { reencodeFound += 1 }188 }189 }190 let possiblePairs = seeds.count * (positive.count + 1) * positive.count / 2191 let precision = groupedPairs == 0 ? 1 : Double(correctPairs) / Double(groupedPairs)192 let pairRecall = Double(correctPairs) / Double(possiblePairs)193 let recall = Double(reencodeFound) / Double(reencodeTotal)194 print("GROUPING on \(samples.count) images (\(seeds.count) scenes): groups \(groups.count), mixed-scene groups \(mixedGroups), pair precision \(String(format: "%.3f", precision)), pair recall \(String(format: "%.3f", pairRecall)), re-encode/resize recall \(String(format: "%.3f", recall))")195 for transformation in positive {196 print(" recall \(transformation.name): \(found[transformation.name, default: 0])/\(seeds.count)")197 }198 #expect(mixedGroups == 0)199 #expect(precision == 1)200 #expect(recall >= 0.9)201 let swappedWithOrigin = samples.filter { $0.role == "swapped" }.filter { sample in202 guard let group = groupOf[sample.id] else { return false }203 return group == groupOf["s\(sample.seed - 1_000_000)-original"]204 }205 #expect(swappedWithOrigin.isEmpty)206 }207208 static func stats(_ values: [Int]) -> String {209 let sorted = values.sorted()210 let mean = Double(sorted.reduce(0, +)) / Double(sorted.count)211 let p95 = sorted[min(sorted.count - 1, Int(Double(sorted.count) * 0.95))]212 return String(format: "%4.1f/%2d/%2d", mean, p95, sorted.last ?? 0)213 }214}215