capacitor-card-scanner 0.3.3 → 0.3.4

package/android/src/main/java/pt/tcgclassifier/cardscanner/CardDetector.java

@@ -1,418 +1,523 @@
-package pt.tcgclassifier.cardscanner;
-
-import android.graphics.Bitmap;
-import android.graphics.Matrix;
-import android.graphics.Rect;
-import android.graphics.RectF;
-import android.os.SystemClock;
-import android.util.Base64;
-import androidx.annotation.NonNull;
-import androidx.annotation.Nullable;
-import androidx.camera.core.ImageAnalysis;
-import androidx.camera.core.ImageProxy;
-import com.getcapacitor.JSArray;
-import com.getcapacitor.JSObject;
-import com.getcapacitor.Logger;
-import com.google.android.gms.tasks.Tasks;
-import com.google.mlkit.vision.common.InputImage;
-import com.google.mlkit.vision.objects.DetectedObject;
-import com.google.mlkit.vision.objects.ObjectDetection;
-import com.google.mlkit.vision.objects.ObjectDetector;
-import com.google.mlkit.vision.objects.defaults.ObjectDetectorOptions;
-import com.google.mlkit.vision.text.Text;
-import com.google.mlkit.vision.text.TextRecognition;
-import com.google.mlkit.vision.text.TextRecognizer;
-import com.google.mlkit.vision.text.latin.TextRecognizerOptions;
-import java.io.ByteArrayOutputStream;
-import java.text.Normalizer;
-import java.util.ArrayList;
-import java.util.Arrays;
-import java.util.Comparator;
-import java.util.List;
-import java.util.Locale;
-import java.util.regex.Matcher;
-import java.util.regex.Pattern;
-
-/**
- * Locates the card in every camera frame (for the on-screen rectangle) and,
- * every {@code intervalMs}, runs OCR inside it. A card is reported once the
- * same collector number (or name) has been read on several consecutive runs.
- */
-public class CardDetector implements ImageAnalysis.Analyzer {
-
-    public interface Listener {
-        void onCardDetected(JSObject result);
-    }
-
-    /** Tuning knobs, all overridable from JS through startDetection(). */
-    public static class Options {
-
-        /** Minimum time between two OCR runs. */
-        public long intervalMs = 300;
-        /** Consecutive OCR runs that must agree before a card is reported. */
-        public int stableFrames = 2;
-        /** Include a JPEG of the card in the event. */
-        public boolean includeImage = false;
-        /** Expected width / height of an upright card (63 x 88 mm). */
-        public float cardAspectRatio = 63f / 88f;
-        /** Allowed relative deviation from cardAspectRatio (0.15 = +/-15%). */
-        public float aspectTolerance = 0.15f;
-        /** Smallest card size, as a fraction of the frame area. */
-        public float minCardArea = 0.08f;
-        /** Largest card size, as a fraction of the frame area. */
-        public float maxCardArea = 0.9f;
-        /** Only run OCR when a card-shaped object is visible. */
-        public boolean requireCard = true;
-        /** Label every detected object with its area/ratio and the filter that rejected it. */
-        public boolean debug = false;
-        /** Outline (in grey) the objects that were not accepted as a card. */
-        public boolean showRejected = true;
-        /** How long the card must be out of view before the same card can be reported again. */
-        public long repeatAfterMs = 1500;
-        /** The name is looked for only in the first N lines of the card (top to bottom). */
-        public int nameLines = 3;
-        /**
-         * Words/phrases that are never the card name (card types, subtypes...).
-         * A line made only of these words is skipped; "Energy Retrieval" is still a name.
-         */
-        public List<String> reservedWords = Arrays.asList(
-            "Basic", "Stage 1", "Stage 2", "Trainer", "Item", "Supporter", "Stadium",
-            "Energy", "Special Energy", "Basic Energy", "Pokémon", "Pokémon Tool"
-        );
-        /** Lines starting with any of these are never the card name. */
-        public List<String> reservedPrefixes = Arrays.asList("Evolves from", "HP");
-    }
-
-    /** An object found by ML Kit, with the values the card filters were checked against. */
-    public static class Candidate {
-
-        /** Bounds normalized (0-1) to the upright frame. */
-        public final RectF box;
-        /** Fraction of the frame area. */
-        public final float area;
-        /** Width / height. */
-        public final float ratio;
-        /** Null when accepted, otherwise the filter that rejected it ("area" or "ratio"). */
-        @Nullable
-        public final String rejectedBy;
-
-        Candidate(RectF box, float area, float ratio, @Nullable String rejectedBy) {
-            this.box = box;
-            this.area = area;
-            this.ratio = ratio;
-            this.rejectedBy = rejectedBy;
-        }
-
-        public String label() {
-            String s = String.format(Locale.US, "a=%.2f r=%.2f", area, ratio);
-            return rejectedBy == null ? s : s + " x" + rejectedBy;
-        }
-    }
-
-    public interface BoxListener {
-        /**
-         * @param card card bounds normalized (0-1) to the upright frame, or null when no card is visible
-         * @param candidates every detected object, accepted or not
-         */
-        void onDetections(@Nullable RectF card, List<Candidate> candidates, int frameWidth, int frameHeight);
-    }
-
-    // e.g. "025/165", "SV001/SV122", "TG05/TG30", "GG01/GG70"
-    private static final Pattern NUMBER = Pattern.compile("\\b([A-Za-z]{0,4}\\d{1,3}[a-z]?)\\s*/\\s*([A-Za-z]{0,4}\\d{1,3})\\b");
-    private static final Pattern HP_SUFFIX = Pattern.compile("\\s*HP\\s*\\d+\\s*$", Pattern.CASE_INSENSITIVE);
-    private static final Pattern LETTER = Pattern.compile("\\p{L}");
-    /** Names at least this similar are treated as the same card. */
-    private static final float SAME_NAME_SIMILARITY = 0.8f;
-    /** Extra margin around the detected card before running OCR. */
-    private static final float CROP_MARGIN = 0.04f;
-
-    private final ObjectDetector objectDetector = ObjectDetection.getClient(
-        new ObjectDetectorOptions.Builder().setDetectorMode(ObjectDetectorOptions.STREAM_MODE).build()
-    );
-    private final TextRecognizer recognizer = TextRecognition.getClient(TextRecognizerOptions.DEFAULT_OPTIONS);
-    private final Options options;
-    private final Listener listener;
-    /** reservedWords / reservedPrefixes, normalized; words longest first. */
-    private final List<String> reservedWords = new ArrayList<>();
-    private final List<String> reservedPrefixes = new ArrayList<>();
-    private volatile BoxListener boxListener;
-
-    // Only touched from the analyzer thread.
-    private long lastOcrAt;
-    private long lastSeenAt;
-    private String candidateKey;
-    private int candidateCount;
-    // Last reported card. A reading is the same card if either its name or its
-    // number matches, because OCR does not read the number on every frame.
-    private String lastEmittedName;
-    private String lastEmittedNumber;
-
-    public CardDetector(Options options, Listener listener) {
-        this.options = options;
-        this.options.stableFrames = Math.max(1, options.stableFrames);
-        this.options.nameLines = Math.max(1, options.nameLines);
-        this.listener = listener;
-        for (String w : options.reservedWords) {
-            String n = normalize(w);
-            if (!n.isEmpty()) reservedWords.add(n);
-        }
-        // Longest first, so "Pokémon Tool" is removed before "Pokémon".
-        reservedWords.sort(Comparator.comparingInt(String::length).reversed());
-        for (String p : options.reservedPrefixes) {
-            String n = normalize(p);
-            if (!n.isEmpty()) reservedPrefixes.add(n);
-        }
-    }
-
-    public boolean isDebug() {
-        return options.debug;
-    }
-
-    public boolean isShowRejected() {
-        return options.showRejected;
-    }
-
-    public void setBoxListener(BoxListener boxListener) {
-        this.boxListener = boxListener;
-    }
-
-    public void close() {
-        objectDetector.close();
-        recognizer.close();
-    }
-
-    @Override
-    public void analyze(@NonNull ImageProxy image) {
-        long now = SystemClock.elapsedRealtime();
-        Bitmap upright;
-        try {
-            // Rotate once, so both detectors and all coordinates share the same upright frame.
-            upright = rotate(image.toBitmap(), image.getImageInfo().getRotationDegrees());
-        } finally {
-            image.close();
-        }
-        int frameW = upright.getWidth();
-        int frameH = upright.getHeight();
-
-        try {
-            List<DetectedObject> objects = Tasks.await(objectDetector.process(InputImage.fromBitmap(upright, 0)));
-            List<Candidate> candidates = new ArrayList<>();
-            Rect card = pickCard(objects, frameW, frameH, candidates);
-            RectF cardBox = card == null ? null : normalize(card, frameW, frameH);
-            // The card counts as "in view" while its outline is visible, even if
-            // its text is not readable on this frame.
-            if (card != null) lastSeenAt = now;
-            BoxListener bl = boxListener;
-            if (bl != null) bl.onDetections(cardBox, candidates, frameW, frameH);
-
-            if (now - lastOcrAt < options.intervalMs) return;
-            lastOcrAt = now;
-
-            if (card == null && options.requireCard) {
-                noCardRead(now);
-                return;
-            }
-
-            Bitmap region = card == null ? upright : crop(upright, card);
-            Text text = Tasks.await(recognizer.process(InputImage.fromBitmap(region, 0)));
-            handle(text, region, cardBox, now);
-        } catch (Exception e) {
-            Logger.error("CardDetector", "Detection failed", e);
-        }
-    }
-
-    /**
-     * The biggest detected object with the size and upright proportions of a card.
-     * Every object, accepted or not, is added to {@code candidates}.
-     */
-    @Nullable
-    private Rect pickCard(List<DetectedObject> objects, int frameW, int frameH, List<Candidate> candidates) {
-        float frameArea = (float) frameW * frameH;
-        float minRatio = options.cardAspectRatio * (1f - options.aspectTolerance);
-        float maxRatio = options.cardAspectRatio * (1f + options.aspectTolerance);
-        Rect best = null;
-        long bestArea = 0;
-        for (DetectedObject o : objects) {
-            Rect r = new Rect(o.getBoundingBox());
-            if (!r.intersect(0, 0, frameW, frameH) || r.height() == 0) continue;
-
-            long area = (long) r.width() * r.height();
-            float fraction = area / frameArea;
-            float ratio = r.width() / (float) r.height();
-            String rejectedBy = null;
-            if (fraction < options.minCardArea || fraction > options.maxCardArea) {
-                rejectedBy = "area";
-            } else if (ratio < minRatio || ratio > maxRatio) {
-                rejectedBy = "ratio";
-            }
-            candidates.add(new Candidate(normalize(r, frameW, frameH), fraction, ratio, rejectedBy));
-            if (rejectedBy != null) continue;
-
-            if (area > bestArea) {
-                best = r;
-                bestArea = area;
-            }
-        }
-        return best;
-    }
-
-    private static RectF normalize(Rect r, int frameW, int frameH) {
-        return new RectF(r.left / (float) frameW, r.top / (float) frameH, r.right / (float) frameW, r.bottom / (float) frameH);
-    }
-
-    private static Bitmap rotate(Bitmap bitmap, int rotation) {
-        if (rotation == 0) return bitmap;
-        Matrix matrix = new Matrix();
-        matrix.postRotate(rotation);
-        return Bitmap.createBitmap(bitmap, 0, 0, bitmap.getWidth(), bitmap.getHeight(), matrix, true);
-    }
-
-    private static Bitmap crop(Bitmap bitmap, Rect card) {
-        int mx = Math.round(card.width() * CROP_MARGIN);
-        int my = Math.round(card.height() * CROP_MARGIN);
-        int left = Math.max(0, card.left - mx);
-        int top = Math.max(0, card.top - my);
-        int right = Math.min(bitmap.getWidth(), card.right + mx);
-        int bottom = Math.min(bitmap.getHeight(), card.bottom + my);
-        return Bitmap.createBitmap(bitmap, left, top, right - left, bottom - top);
-    }
-
-    private void handle(Text text, Bitmap region, @Nullable RectF cardBox, long now) {
-        float w = region.getWidth();
-        float h = region.getHeight();
-        JSArray lines = new JSArray();
-        String number = null;
-        List<Text.Line> ordered = new ArrayList<>();
-
-        for (Text.TextBlock block : text.getTextBlocks()) {
-            for (Text.Line line : block.getLines()) {
-                String s = line.getText().trim();
-                Rect r = line.getBoundingBox();
-                if (s.isEmpty() || r == null) continue;
-
-                JSObject item = new JSObject();
-                item.put("text", s);
-                item.put("box", box(r.left / w, r.top / h, r.width() / w, r.height() / h));
-                lines.put(item);
-
-                if (number == null) {
-                    Matcher m = NUMBER.matcher(s);
-                    if (m.find()) number = m.group(1) + "/" + m.group(2);
-                }
-                ordered.add(line);
-            }
-        }
-        String name = findName(ordered);
-
-        String key = number != null ? number : name;
-        if (key == null) {
-            noCardRead(now);
-            return;
-        }
-        lastSeenAt = now;
-
-        if (key.equals(candidateKey)) {
-            candidateCount++;
-        } else {
-            candidateKey = key;
-            candidateCount = 1;
-        }
-        if (candidateCount < options.stableFrames || isLastEmitted(name, number)) return;
-        lastEmittedName = name;
-        lastEmittedNumber = number;
-
-        JSObject result = new JSObject();
-        result.put("name", name);
-        result.put("collectorNumber", number);
-        result.put("text", text.getText());
-        result.put("lines", lines);
-        if (cardBox != null) {
-            result.put("cardBox", box(cardBox.left, cardBox.top, cardBox.width(), cardBox.height()));
-        }
-        if (options.includeImage) {
-            ByteArrayOutputStream out = new ByteArrayOutputStream();
-            region.compress(Bitmap.CompressFormat.JPEG, 80, out);
-            result.put("image", Base64.encodeToString(out.toByteArray(), Base64.NO_WRAP));
-        }
-        listener.onCardDetected(result);
-    }
-
-    private void noCardRead(long now) {
-        candidateKey = null;
-        candidateCount = 0;
-        if (now - lastSeenAt > options.repeatAfterMs) {
-            lastEmittedName = null;
-            lastEmittedNumber = null;
-        }
-    }
-
-    private boolean isLastEmitted(String name, String number) {
-        if (number != null && number.equals(lastEmittedNumber)) return true;
-        return name != null && lastEmittedName != null && similarity(name, lastEmittedName) >= SAME_NAME_SIMILARITY;
-    }
-
-    /** 0-1 similarity (LCS based), so an OCR slip like "Evolutlon" still matches "Evolution". */
-    private static float similarity(String a, String b) {
-        a = a.toLowerCase(Locale.ROOT);
-        b = b.toLowerCase(Locale.ROOT);
-        if (a.equals(b)) return 1f;
-        int[] prev = new int[b.length() + 1];
-        int[] cur = new int[b.length() + 1];
-        for (int i = 1; i <= a.length(); i++) {
-            for (int j = 1; j <= b.length(); j++) {
-                cur[j] = a.charAt(i - 1) == b.charAt(j - 1) ? prev[j - 1] + 1 : Math.max(prev[j], cur[j - 1]);
-            }
-            int[] tmp = prev;
-            prev = cur;
-            cur = tmp;
-        }
-        return 2f * prev[b.length()] / (a.length() + b.length());
-    }
-
-    private static JSObject box(float x, float y, float width, float height) {
-        JSObject box = new JSObject();
-        box.put("x", x);
-        box.put("y", y);
-        box.put("width", width);
-        box.put("height", height);
-        return box;
-    }
-
-    /** First line, among the top {@code nameLines}, that is not made of reserved words. */
-    @Nullable
-    private String findName(List<Text.Line> lines) {
-        lines.sort(Comparator.comparingInt(l -> l.getBoundingBox().top));
-        for (int i = 0; i < lines.size() && i < options.nameLines; i++) {
-            String s = HP_SUFFIX.matcher(lines.get(i).getText().trim()).replaceAll("").trim();
-            if (!isReserved(s) && countLetters(s) >= 3) return s;
-        }
-        return null;
-    }
-
-    private boolean isReserved(String line) {
-        String rest = " " + normalize(line) + " ";
-        for (String w : reservedWords) {
-            rest = rest.replace(" " + w + " ", " ");
-        }
-        rest = rest.trim();
-        if (countLetters(rest) < 3) return true;
-        // Checked after removing reserved words, so "STAGE 1 Evolves from Pichu" is caught too.
-        for (String p : reservedPrefixes) {
-            if (rest.equals(p) || rest.startsWith(p + " ")) return true;
-        }
-        return false;
-    }
-
-    /** Upper case, no accents, only letters/digits separated by single spaces. */
-    private static String normalize(String s) {
-        String n = Normalizer.normalize(s, Normalizer.Form.NFD).replaceAll("\\p{M}", "");
-        return n.toUpperCase(Locale.ROOT).replaceAll("[^\\p{L}\\p{Nd}]+", " ").trim();
-    }
-
-    private static int countLetters(String s) {
-        Matcher m = LETTER.matcher(s);
-        int letters = 0;
-        while (m.find()) letters++;
-        return letters;
-    }
-}
+package pt.tcgclassifier.cardscanner;
+
+import android.graphics.Bitmap;
+import android.graphics.Color;
+import android.graphics.Matrix;
+import android.graphics.Rect;
+import android.graphics.RectF;
+import android.os.SystemClock;
+import android.util.Base64;
+import androidx.annotation.NonNull;
+import androidx.annotation.Nullable;
+import androidx.camera.core.ImageAnalysis;
+import androidx.camera.core.ImageProxy;
+import com.getcapacitor.JSArray;
+import com.getcapacitor.JSObject;
+import com.getcapacitor.Logger;
+import com.google.android.gms.tasks.Tasks;
+import com.google.mlkit.vision.common.InputImage;
+import com.google.mlkit.vision.objects.DetectedObject;
+import com.google.mlkit.vision.objects.ObjectDetection;
+import com.google.mlkit.vision.objects.ObjectDetector;
+import com.google.mlkit.vision.objects.defaults.ObjectDetectorOptions;
+import com.google.mlkit.vision.text.Text;
+import com.google.mlkit.vision.text.TextRecognition;
+import com.google.mlkit.vision.text.TextRecognizer;
+import com.google.mlkit.vision.text.latin.TextRecognizerOptions;
+import java.io.ByteArrayOutputStream;
+import java.text.Normalizer;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Comparator;
+import java.util.List;
+import java.util.Locale;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+/**
+ * Locates the card in every camera frame (for the on-screen rectangle) and,
+ * every {@code intervalMs}, runs OCR inside it. A card is reported once the
+ * same collector number (or name) has been read on several consecutive runs.
+ */
+public class CardDetector implements ImageAnalysis.Analyzer {
+
+    public interface Listener {
+        void onCardDetected(JSObject result);
+    }
+
+    /** Tuning knobs, all overridable from JS through startDetection(). */
+    public static class Options {
+
+        /** Minimum time between two OCR runs. */
+        public long intervalMs = 300;
+        /** Consecutive OCR runs that must agree before a card is reported. */
+        public int stableFrames = 2;
+        /** Include a JPEG of the card in the event. */
+        public boolean includeImage = false;
+        /** Expected width / height of an upright card (63 x 88 mm). */
+        public float cardAspectRatio = 63f / 88f;
+        /** Allowed relative deviation from cardAspectRatio (0.15 = +/-15%). */
+        public float aspectTolerance = 0.15f;
+        /** Smallest card size, as a fraction of the frame area. */
+        public float minCardArea = 0.08f;
+        /** Largest card size, as a fraction of the frame area. */
+        public float maxCardArea = 0.9f;
+        /** Only run OCR when a card-shaped object is visible. */
+        public boolean requireCard = true;
+        /** Label every detected object with its area/ratio and the filter that rejected it. */
+        public boolean debug = false;
+        /** Outline (in grey) the objects that were not accepted as a card. */
+        public boolean showRejected = true;
+        /** How long the card must be out of view before the same card can be reported again. */
+        public long repeatAfterMs = 1500;
+        /**
+         * While the card outline stays in view (gaps shorter than this are
+         * tolerated), at most one card is reported, even if later readings
+         * give a different name. A longer gap means a new card is in view.
+         */
+        public long cardGapMs = 500;
+        /**
+         * Two card images whose perceptual hashes differ in at most this many
+         * bits (of 64) are the same card. Lets a card slid over another one be
+         * reported, and a card that stays in view be reported only once.
+         */
+        public int sameCardMaxDistance = 16;
+        /** The name is looked for only in the first N lines of the card (top to bottom). */
+        public int nameLines = 3;
+        /**
+         * Words/phrases that are never the card name (card types, subtypes...).
+         * A line made only of these words is skipped; "Energy Retrieval" is still a name.
+         */
+        public List<String> reservedWords = Arrays.asList(
+            "Basic", "Stage", "Stage 1", "Stage 2", "Trainer", "Item", "Supporter", "Stadium",
+            "Energy", "Special Energy", "Basic Energy", "Pokémon", "Pokémon Tool", "Tera"
+        );
+        /** Lines starting with any of these are never the card name. */
+        public List<String> reservedPrefixes = Arrays.asList("Evolves from", "HP");
+    }
+
+    /** An object found by ML Kit, with the values the card filters were checked against. */
+    public static class Candidate {
+
+        /** Bounds normalized (0-1) to the upright frame. */
+        public final RectF box;
+        /** Fraction of the frame area. */
+        public final float area;
+        /** Width / height. */
+        public final float ratio;
+        /** Null when accepted, otherwise the filter that rejected it ("area" or "ratio"). */
+        @Nullable
+        public final String rejectedBy;
+
+        Candidate(RectF box, float area, float ratio, @Nullable String rejectedBy) {
+            this.box = box;
+            this.area = area;
+            this.ratio = ratio;
+            this.rejectedBy = rejectedBy;
+        }
+
+        public String label() {
+            String s = String.format(Locale.US, "a=%.2f r=%.2f", area, ratio);
+            return rejectedBy == null ? s : s + " x" + rejectedBy;
+        }
+    }
+
+    public interface BoxListener {
+        /**
+         * @param card card bounds normalized (0-1) to the upright frame, or null when no card is visible
+         * @param candidates every detected object, accepted or not
+         */
+        void onDetections(@Nullable RectF card, List<Candidate> candidates, int frameWidth, int frameHeight);
+    }
+
+    // e.g. "025/165", "SV001/SV122", "TG05/TG30", "GG01/GG70"
+    private static final Pattern NUMBER = Pattern.compile("\\b([A-Za-z]{0,4}\\d{1,3}[a-z]?)\\s*/\\s*([A-Za-z]{0,4}\\d{1,3})\\b");
+    private static final Pattern HP_SUFFIX = Pattern.compile("\\s*HP\\s*\\d+\\s*$", Pattern.CASE_INSENSITIVE);
+    private static final Pattern LETTER = Pattern.compile("\\p{L}");
+    /** Names at least this similar are treated as the same card. */
+    private static final float SAME_NAME_SIMILARITY = 0.8f;
+    /** Extra margin around the detected card before running OCR. */
+    private static final float CROP_MARGIN = 0.04f;
+
+    private final ObjectDetector objectDetector = ObjectDetection.getClient(
+        new ObjectDetectorOptions.Builder().setDetectorMode(ObjectDetectorOptions.STREAM_MODE).build()
+    );
+    private final TextRecognizer recognizer = TextRecognition.getClient(TextRecognizerOptions.DEFAULT_OPTIONS);
+    private final Options options;
+    private final Listener listener;
+    /** reservedWords / reservedPrefixes, normalized; words longest first. */
+    private final List<String> reservedWords = new ArrayList<>();
+    private final List<String> reservedPrefixes = new ArrayList<>();
+    private volatile BoxListener boxListener;
+
+    // Only touched from the analyzer thread.
+    private long lastOcrAt;
+    private long lastSeenAt;
+    /** Last frame with a card outline, and whether that card was already reported. */
+    private long lastCardAt;
+    private boolean reportedInView;
+    private String candidateKey;
+    private int candidateCount;
+    // Last reported card. A reading is the same card if either its name or its
+    // number matches, because OCR does not read the number on every frame.
+    private String lastEmittedName;
+    private String lastEmittedNumber;
+    /** Perceptual hash of the last reported card image, or null. */
+    private Long lastEmittedHash;
+
+    public CardDetector(Options options, Listener listener) {
+        this.options = options;
+        this.options.stableFrames = Math.max(1, options.stableFrames);
+        this.options.nameLines = Math.max(1, options.nameLines);
+        this.listener = listener;
+        for (String w : options.reservedWords) {
+            String n = normalize(w);
+            if (!n.isEmpty()) reservedWords.add(n);
+        }
+        // Longest first, so "Pokémon Tool" is removed before "Pokémon".
+        reservedWords.sort(Comparator.comparingInt(String::length).reversed());
+        for (String p : options.reservedPrefixes) {
+            String n = normalize(p);
+            if (!n.isEmpty()) reservedPrefixes.add(n);
+        }
+    }
+
+    public boolean isDebug() {
+        return options.debug;
+    }
+
+    public boolean isShowRejected() {
+        return options.showRejected;
+    }
+
+    public void setBoxListener(BoxListener boxListener) {
+        this.boxListener = boxListener;
+    }
+
+    public void close() {
+        objectDetector.close();
+        recognizer.close();
+    }
+
+    @Override
+    public void analyze(@NonNull ImageProxy image) {
+        long now = SystemClock.elapsedRealtime();
+        Bitmap upright;
+        try {
+            // Rotate once, so both detectors and all coordinates share the same upright frame.
+            upright = rotate(image.toBitmap(), image.getImageInfo().getRotationDegrees());
+        } finally {
+            image.close();
+        }
+        int frameW = upright.getWidth();
+        int frameH = upright.getHeight();
+
+        try {
+            List<DetectedObject> objects = Tasks.await(objectDetector.process(InputImage.fromBitmap(upright, 0)));
+            List<Candidate> candidates = new ArrayList<>();
+            Rect card = pickCard(objects, frameW, frameH, candidates);
+            RectF cardBox = card == null ? null : normalize(card, frameW, frameH);
+            // The card counts as "in view" while its outline is visible, even if
+            // its text is not readable on this frame.
+            if (card != null) {
+                // A gap in the outline means the card left (or was swapped).
+                if (now - lastCardAt > options.cardGapMs) reportedInView = false;
+                lastCardAt = now;
+                lastSeenAt = now;
+            }
+            BoxListener bl = boxListener;
+            if (bl != null) bl.onDetections(cardBox, candidates, frameW, frameH);
+
+            if (now - lastOcrAt < options.intervalMs) return;
+            lastOcrAt = now;
+
+            if (card == null && options.requireCard) {
+                noCardRead(now);
+                return;
+            }
+
+            Bitmap region = card == null ? upright : crop(upright, card);
+            Text text = Tasks.await(recognizer.process(InputImage.fromBitmap(region, 0)));
+            handle(text, region, cardBox, now);
+        } catch (Exception e) {
+            Logger.error("CardDetector", "Detection failed", e);
+        }
+    }
+
+    /**
+     * The biggest detected object with the size and upright proportions of a card.
+     * Every object, accepted or not, is added to {@code candidates}.
+     */
+    @Nullable
+    private Rect pickCard(List<DetectedObject> objects, int frameW, int frameH, List<Candidate> candidates) {
+        float frameArea = (float) frameW * frameH;
+        float minRatio = options.cardAspectRatio * (1f - options.aspectTolerance);
+        float maxRatio = options.cardAspectRatio * (1f + options.aspectTolerance);
+        Rect best = null;
+        long bestArea = 0;
+        for (DetectedObject o : objects) {
+            Rect r = new Rect(o.getBoundingBox());
+            if (!r.intersect(0, 0, frameW, frameH) || r.height() == 0) continue;
+
+            long area = (long) r.width() * r.height();
+            float fraction = area / frameArea;
+            float ratio = r.width() / (float) r.height();
+            String rejectedBy = null;
+            if (fraction < options.minCardArea || fraction > options.maxCardArea) {
+                rejectedBy = "area";
+            } else if (ratio < minRatio || ratio > maxRatio) {
+                rejectedBy = "ratio";
+            }
+            candidates.add(new Candidate(normalize(r, frameW, frameH), fraction, ratio, rejectedBy));
+            if (rejectedBy != null) continue;
+
+            if (area > bestArea) {
+                best = r;
+                bestArea = area;
+            }
+        }
+        return best;
+    }
+
+    private static RectF normalize(Rect r, int frameW, int frameH) {
+        return new RectF(r.left / (float) frameW, r.top / (float) frameH, r.right / (float) frameW, r.bottom / (float) frameH);
+    }
+
+    private static Bitmap rotate(Bitmap bitmap, int rotation) {
+        if (rotation == 0) return bitmap;
+        Matrix matrix = new Matrix();
+        matrix.postRotate(rotation);
+        return Bitmap.createBitmap(bitmap, 0, 0, bitmap.getWidth(), bitmap.getHeight(), matrix, true);
+    }
+
+    private static Bitmap crop(Bitmap bitmap, Rect card) {
+        int mx = Math.round(card.width() * CROP_MARGIN);
+        int my = Math.round(card.height() * CROP_MARGIN);
+        int left = Math.max(0, card.left - mx);
+        int top = Math.max(0, card.top - my);
+        int right = Math.min(bitmap.getWidth(), card.right + mx);
+        int bottom = Math.min(bitmap.getHeight(), card.bottom + my);
+        return Bitmap.createBitmap(bitmap, left, top, right - left, bottom - top);
+    }
+
+    private void handle(Text text, Bitmap region, @Nullable RectF cardBox, long now) {
+        float w = region.getWidth();
+        float h = region.getHeight();
+        JSArray lines = new JSArray();
+        String number = null;
+        List<Text.Line> ordered = new ArrayList<>();
+
+        for (Text.TextBlock block : text.getTextBlocks()) {
+            for (Text.Line line : block.getLines()) {
+                String s = line.getText().trim();
+                Rect r = line.getBoundingBox();
+                if (s.isEmpty() || r == null) continue;
+
+                JSObject item = new JSObject();
+                item.put("text", s);
+                item.put("box", box(r.left / w, r.top / h, r.width() / w, r.height() / h));
+                lines.put(item);
+
+                if (number == null) {
+                    Matcher m = NUMBER.matcher(s);
+                    if (m.find()) number = m.group(1) + "/" + m.group(2);
+                }
+                ordered.add(line);
+            }
+        }
+        String name = findName(ordered);
+
+        String key = number != null ? number : name;
+        if (key == null) {
+            noCardRead(now);
+            return;
+        }
+        lastSeenAt = now;
+
+        if (key.equals(candidateKey)) {
+            candidateCount++;
+        } else {
+            candidateKey = key;
+            candidateCount = 1;
+        }
+        if (candidateCount < options.stableFrames) return;
+        long hash = imageHash(region);
+        if (isSameCardAsLast(name, number, hash, cardBox != null)) return;
+        reportedInView = cardBox != null;
+        lastEmittedName = name;
+        lastEmittedNumber = number;
+        lastEmittedHash = hash;
+
+        JSObject result = new JSObject();
+        result.put("name", name);
+        result.put("collectorNumber", number);
+        result.put("imageHash", String.format(Locale.ROOT, "%016x", hash));
+        result.put("text", text.getText());
+        result.put("lines", lines);
+        if (cardBox != null) {
+            result.put("cardBox", box(cardBox.left, cardBox.top, cardBox.width(), cardBox.height()));
+        }
+        if (options.includeImage) {
+            ByteArrayOutputStream out = new ByteArrayOutputStream();
+            region.compress(Bitmap.CompressFormat.JPEG, 80, out);
+            result.put("image", Base64.encodeToString(out.toByteArray(), Base64.NO_WRAP));
+        }
+        listener.onCardDetected(result);
+    }
+
+    private void noCardRead(long now) {
+        candidateKey = null;
+        candidateCount = 0;
+        if (now - lastSeenAt > options.repeatAfterMs) {
+            lastEmittedName = null;
+            lastEmittedNumber = null;
+            lastEmittedHash = null;
+        }
+    }
+
+    /**
+     * Whether this reading is the card that was just reported. The image hash
+     * decides first; the text (number, then name) guards against glare making
+     * the same card look different.
+     */
+    private boolean isSameCardAsLast(String name, String number, long hash, boolean cardInView) {
+        if (lastEmittedHash == null) {
+            // Nothing to compare the picture with: one event per card in view.
+            return isLastEmitted(name, number) || (cardInView && reportedInView);
+        }
+        if (Long.bitCount(hash ^ lastEmittedHash) <= options.sameCardMaxDistance) return true;
+
+        // The picture changed: a new card, unless the text says it is the same one.
+        if (number != null && lastEmittedNumber != null) return number.equals(lastEmittedNumber);
+        return isLastEmitted(name, number);
+    }
+
+    /**
+     * 64-bit difference hash: the card split into 9x8 cells, each cell's average
+     * grey level, one bit per "is this cell brighter than its right neighbour".
+     * Averaging matters: sampling single pixels makes the hash unstable. On real
+     * photos the same card differed by 9-13 bits and different cards by 32+.
+     */
+    private static long imageHash(Bitmap bitmap) {
+        int w = bitmap.getWidth();
+        int h = bitmap.getHeight();
+        int[] pixels = new int[w * h];
+        bitmap.getPixels(pixels, 0, w, 0, 0, w, h);
+        // Sampling ~100 points per side is plenty for 9x8 averages.
+        int step = Math.max(1, Math.min(w, h) / 100);
+
+        float[][] cells = new float[8][9];
+        for (int cy = 0; cy < 8; cy++) {
+            int y0 = cy * h / 8;
+            int y1 = (cy + 1) * h / 8;
+            for (int cx = 0; cx < 9; cx++) {
+                int x0 = cx * w / 9;
+                int x1 = (cx + 1) * w / 9;
+                long sum = 0;
+                int count = 0;
+                for (int y = y0; y < y1; y += step) {
+                    for (int x = x0; x < x1; x += step) {
+                        sum += grey(pixels[y * w + x]);
+                        count++;
+                    }
+                }
+                cells[cy][cx] = count == 0 ? 0 : (float) sum / count;
+            }
+        }
+
+        long hash = 0;
+        for (int y = 0; y < 8; y++) {
+            for (int x = 0; x < 8; x++) {
+                hash <<= 1;
+                if (cells[y][x] > cells[y][x + 1]) hash |= 1;
+            }
+        }
+        return hash;
+    }
+
+    private static int grey(int color) {
+        return (Color.red(color) * 299 + Color.green(color) * 587 + Color.blue(color) * 114) / 1000;
+    }
+
+    private boolean isLastEmitted(String name, String number) {
+        if (number != null && number.equals(lastEmittedNumber)) return true;
+        return name != null && lastEmittedName != null && similarity(name, lastEmittedName) >= SAME_NAME_SIMILARITY;
+    }
+
+    /** 0-1 similarity (LCS based), so an OCR slip like "Evolutlon" still matches "Evolution". */
+    private static float similarity(String a, String b) {
+        a = a.toLowerCase(Locale.ROOT);
+        b = b.toLowerCase(Locale.ROOT);
+        if (a.equals(b)) return 1f;
+        int[] prev = new int[b.length() + 1];
+        int[] cur = new int[b.length() + 1];
+        for (int i = 1; i <= a.length(); i++) {
+            for (int j = 1; j <= b.length(); j++) {
+                cur[j] = a.charAt(i - 1) == b.charAt(j - 1) ? prev[j - 1] + 1 : Math.max(prev[j], cur[j - 1]);
+            }
+            int[] tmp = prev;
+            prev = cur;
+            cur = tmp;
+        }
+        return 2f * prev[b.length()] / (a.length() + b.length());
+    }
+
+    private static JSObject box(float x, float y, float width, float height) {
+        JSObject box = new JSObject();
+        box.put("x", x);
+        box.put("y", y);
+        box.put("width", width);
+        box.put("height", height);
+        return box;
+    }
+
+    /** First line, among the top {@code nameLines}, that is not made of reserved words. */
+    @Nullable
+    private String findName(List<Text.Line> lines) {
+        lines.sort(Comparator.comparingInt(l -> l.getBoundingBox().top));
+        for (int i = 0; i < lines.size() && i < options.nameLines; i++) {
+            String s = HP_SUFFIX.matcher(lines.get(i).getText().trim()).replaceAll("").trim();
+            if (!isReserved(s) && countLetters(s) >= 3) return s;
+        }
+        return null;
+    }
+
+    private boolean isReserved(String line) {
+        String normalized = normalize(line);
+
+        // Printed labels are often read without spaces ("STAGE1"), so check both ways.
+        String compact = normalized.replace(" ", "");
+        for (String w : reservedWords) {
+            compact = compact.replace(w.replace(" ", ""), "");
+        }
+        if (countLetters(compact) < 3) return true;
+
+        String rest = " " + normalized + " ";
+        for (String w : reservedWords) {
+            rest = rest.replace(" " + w + " ", " ");
+        }
+        rest = rest.trim();
+        if (countLetters(rest) < 3) return true;
+        // Checked after removing reserved words, so "STAGE 1 Evolves from Pichu" is caught too.
+        String restCompact = rest.replace(" ", "");
+        for (String p : reservedPrefixes) {
+            if (rest.equals(p) || rest.startsWith(p + " ")) return true;
+            // Multi-word prefixes read without spaces ("Evolvesfrom Pichu").
+            if (p.contains(" ") && restCompact.startsWith(p.replace(" ", ""))) return true;
+        }
+        return false;
+    }
+
+    /** Upper case, no accents, only letters/digits separated by single spaces. */
+    private static String normalize(String s) {
+        String n = Normalizer.normalize(s, Normalizer.Form.NFD).replaceAll("\\p{M}", "");
+        return n.toUpperCase(Locale.ROOT).replaceAll("[^\\p{L}\\p{Nd}]+", " ").trim();
+    }
+
+    private static int countLetters(String s) {
+        Matcher m = LETTER.matcher(s);
+        int letters = 0;
+        while (m.find()) letters++;
+        return letters;
+    }
+}