capacitor-card-scanner 0.1.0 → 0.3.0

package/README.md

@@ -328,11 +328,17 @@ requestPermissions() => Promise<PermissionStatus>
 
 #### DetectionOptions
 
-| Prop               | Type                 | Description                                                                                                 | Default            |
-| ------------------ | -------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------ |
-| **`intervalMs`**   | <code>number</code>  | Minimum time between two OCR runs, in milliseconds. The red rectangle is updated on every frame regardless. | <code>300</code>   |
-| **`stableFrames`** | <code>number</code>  | How many consecutive OCR runs must read the same card before `cardDetected` fires.                          | <code>2</code>     |
-| **`includeImage`** | <code>boolean</code> | Include a JPEG of the detected card in the event.                                                           | <code>false</code> |
+| Prop                  | Type                 | Description                                                                                                                                                                                               | Default                         |
+| --------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
+| **`intervalMs`**      | <code>number</code>  | Minimum time between two OCR runs, in milliseconds. The red rectangle is updated on every frame regardless.                                                                                               | <code>300</code>                |
+| **`stableFrames`**    | <code>number</code>  | How many consecutive OCR runs must read the same card before `cardDetected` fires.                                                                                                                        | <code>2</code>                  |
+| **`includeImage`**    | <code>boolean</code> | Include a JPEG of the detected card in the event.                                                                                                                                                         | <code>false</code>              |
+| **`cardAspectRatio`** | <code>number</code>  | Expected width / height of an upright card. Only upright cards are detected; a card lying sideways falls outside the tolerance.                                                                           | <code>0.716 (63 x 88 mm)</code> |
+| **`aspectTolerance`** | <code>number</code>  | Allowed relative deviation from `cardAspectRatio` (0.15 = ±15%). Increase it if tilted cards are not detected.                                                                                            | <code>0.15</code>               |
+| **`minCardArea`**     | <code>number</code>  | Smallest card size, as a fraction of the camera frame (0-1).                                                                                                                                              | <code>0.08</code>               |
+| **`maxCardArea`**     | <code>number</code>  | Largest card size, as a fraction of the camera frame (0-1).                                                                                                                                               | <code>0.9</code>                |
+| **`requireCard`**     | <code>boolean</code> | Only read text when a card-shaped object is visible. When false, the whole frame is read if no card is found.                                                                                             | <code>true</code>               |
+| **`debug`**           | <code>boolean</code> | Draw every object found, labelled with its area (`a`) and width/height ratio (`r`): red when accepted as a card, grey when rejected (with the filter that rejected it). Use it to tune the filters above. | <code>false</code>              |
 
 
 #### PluginListenerHandle

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

@@ -1,249 +1,324 @@
-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.util.List;
-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);
-    }
-
-    public interface BoxListener {
-        /**
-         * @param box card bounds normalized (0-1) to the upright frame, or null when no card is visible
-         */
-        void onBox(@Nullable RectF box, 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 HEADER = Pattern.compile(
-        "^(basic|stage\\s*\\d|trainer|item|supporter|stadium|energy|pok[eé]mon|evolves|hp\\b)",
-        Pattern.CASE_INSENSITIVE
-    );
-    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}");
-    /** After this long without reading a card, the same card can be reported again. */
-    private static final long RESET_AFTER_MS = 1500;
-    /** Objects smaller than this fraction of the frame are ignored. */
-    private static final float MIN_CARD_AREA = 0.08f;
-    /** 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 long intervalMs;
-    private final int stableFrames;
-    private final boolean includeImage;
-    private final Listener listener;
-    private volatile BoxListener boxListener;
-
-    // Only touched from the analyzer thread.
-    private long lastOcrAt;
-    private long lastSeenAt;
-    private String candidateKey;
-    private int candidateCount;
-    private String lastEmittedKey;
-
-    public CardDetector(long intervalMs, int stableFrames, boolean includeImage, Listener listener) {
-        this.intervalMs = intervalMs;
-        this.stableFrames = Math.max(1, stableFrames);
-        this.includeImage = includeImage;
-        this.listener = listener;
-    }
-
-    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();
-        int rotation = image.getImageInfo().getRotationDegrees();
-        Bitmap raw;
-        try {
-            raw = image.toBitmap();
-        } finally {
-            image.close();
-        }
-        int frameW = rotation % 180 == 0 ? raw.getWidth() : raw.getHeight();
-        int frameH = rotation % 180 == 0 ? raw.getHeight() : raw.getWidth();
-
-        try {
-            List<DetectedObject> objects = Tasks.await(objectDetector.process(InputImage.fromBitmap(raw, rotation)));
-            Rect card = pickCard(objects, frameW, frameH);
-            RectF cardBox = card == null ? null : new RectF(
-                card.left / (float) frameW,
-                card.top / (float) frameH,
-                card.right / (float) frameW,
-                card.bottom / (float) frameH
-            );
-            BoxListener bl = boxListener;
-            if (bl != null) bl.onBox(cardBox, frameW, frameH);
-
-            if (now - lastOcrAt < intervalMs) return;
-            lastOcrAt = now;
-
-            Bitmap upright = rotate(raw, rotation);
-            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, if it is large enough to be a card held close to the camera. */
-    @Nullable
-    private static Rect pickCard(List<DetectedObject> objects, int frameW, int frameH) {
-        Rect best = null;
-        long bestArea = 0;
-        for (DetectedObject o : objects) {
-            Rect r = new Rect(o.getBoundingBox());
-            if (!r.intersect(0, 0, frameW, frameH)) continue;
-            long area = (long) r.width() * r.height();
-            if (area > bestArea) {
-                best = r;
-                bestArea = area;
-            }
-        }
-        if (best == null || bestArea < MIN_CARD_AREA * frameW * frameH) return null;
-        return best;
-    }
-
-    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;
-        String name = null;
-        int nameTop = Integer.MAX_VALUE;
-
-        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);
-                }
-                if (r.top < nameTop && isNameCandidate(s)) {
-                    name = HP_SUFFIX.matcher(s).replaceAll("").trim();
-                    nameTop = r.top;
-                }
-            }
-        }
-
-        String key = number != null ? number : name;
-        if (key == null) {
-            candidateKey = null;
-            candidateCount = 0;
-            if (now - lastSeenAt > RESET_AFTER_MS) lastEmittedKey = null;
-            return;
-        }
-        lastSeenAt = now;
-
-        if (key.equals(candidateKey)) {
-            candidateCount++;
-        } else {
-            candidateKey = key;
-            candidateCount = 1;
-        }
-        if (candidateCount < stableFrames || key.equals(lastEmittedKey)) return;
-        lastEmittedKey = key;
-
-        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 (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 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;
-    }
-
-    private static boolean isNameCandidate(String s) {
-        if (HEADER.matcher(s).find()) return false;
-        Matcher m = LETTER.matcher(s);
-        int letters = 0;
-        while (m.find()) letters++;
-        return letters >= 3;
-    }
-}
+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.util.ArrayList;
+import java.util.Collections;
+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;
+        /** Report every detected object (with its area/ratio) so the overlay can show why it was rejected. */
+        public boolean debug = false;
+    }
+
+    /** 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; empty unless debug is on
+         */
+        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 HEADER = Pattern.compile(
+        "^(basic|stage\\s*\\d|trainer|item|supporter|stadium|energy|pok[eé]mon|evolves|hp\\b)",
+        Pattern.CASE_INSENSITIVE
+    );
+    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}");
+    /** After this long without reading a card, the same card can be reported again. */
+    private static final long RESET_AFTER_MS = 1500;
+    /** 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;
+    private volatile BoxListener boxListener;
+
+    // Only touched from the analyzer thread.
+    private long lastOcrAt;
+    private long lastSeenAt;
+    private String candidateKey;
+    private int candidateCount;
+    private String lastEmittedKey;
+
+    public CardDetector(Options options, Listener listener) {
+        this.options = options;
+        this.options.stableFrames = Math.max(1, options.stableFrames);
+        this.listener = listener;
+    }
+
+    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 = options.debug ? new ArrayList<>() : Collections.emptyList();
+            Rect card = pickCard(objects, frameW, frameH, candidates);
+            RectF cardBox = card == null ? null : normalize(card, frameW, frameH);
+            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.
+     * When debug is on, every object 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";
+            }
+            if (options.debug) {
+                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;
+        String name = null;
+        int nameTop = Integer.MAX_VALUE;
+
+        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);
+                }
+                if (r.top < nameTop && isNameCandidate(s)) {
+                    name = HP_SUFFIX.matcher(s).replaceAll("").trim();
+                    nameTop = r.top;
+                }
+            }
+        }
+
+        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 || key.equals(lastEmittedKey)) return;
+        lastEmittedKey = key;
+
+        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 > RESET_AFTER_MS) lastEmittedKey = null;
+    }
+
+    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;
+    }
+
+    private static boolean isNameCandidate(String s) {
+        if (HEADER.matcher(s).find()) return false;
+        Matcher m = LETTER.matcher(s);
+        int letters = 0;
+        while (m.find()) letters++;
+        return letters >= 3;
+    }
+}

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

@@ -151,10 +151,10 @@ public class CardScanner {
         closeDetector();
         detector = newDetector;
         DetectionOverlay target = overlay;
-        detector.setBoxListener((box, frameW, frameH) ->
+        detector.setBoxListener((card, candidates, frameW, frameH) ->
             target.post(() -> {
                 // Ignore frames that arrive after detection was stopped or restarted.
-                if (detector == newDetector) target.setBox(box, frameW, frameH);
+                if (detector == newDetector) target.setDetections(card, candidates, frameW, frameH);
             })
         );
         bind();

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

@@ -1,159 +1,165 @@
-package pt.tcgclassifier.cardscanner;
-
-import android.Manifest;
-import com.getcapacitor.JSObject;
-import com.getcapacitor.PermissionState;
-import com.getcapacitor.Plugin;
-import com.getcapacitor.PluginCall;
-import com.getcapacitor.PluginMethod;
-import com.getcapacitor.annotation.CapacitorPlugin;
-import com.getcapacitor.annotation.Permission;
-import com.getcapacitor.annotation.PermissionCallback;
-
-@CapacitorPlugin(name = "CardScanner", permissions = { @Permission(strings = { Manifest.permission.CAMERA }, alias = CardScannerPlugin.CAMERA) })
-public class CardScannerPlugin extends Plugin {
-
-    static final String CAMERA = "camera";
-
-    private CardScanner implementation;
-
-    @Override
-    public void load() {
-        implementation = new CardScanner(getActivity(), getBridge().getWebView());
-    }
-
-    @Override
-    protected void handleOnDestroy() {
-        getActivity().runOnUiThread(() -> implementation.stop());
-    }
-
-    @PluginMethod
-    public void start(PluginCall call) {
-        if (getPermissionState(CAMERA) != PermissionState.GRANTED) {
-            requestPermissionForAlias(CAMERA, call, "cameraPermsCallback");
-            return;
-        }
-        doStart(call);
-    }
-
-    @PermissionCallback
-    private void cameraPermsCallback(PluginCall call) {
-        if (getPermissionState(CAMERA) == PermissionState.GRANTED) {
-            doStart(call);
-        } else {
-            call.reject("Camera permission denied", "PERMISSION_DENIED");
-        }
-    }
-
-    private void doStart(PluginCall call) {
-        boolean front = "front".equals(call.getString("position", "rear"));
-        getActivity().runOnUiThread(() -> implementation.start(front, voidCallback(call)));
-    }
-
-    @PluginMethod
-    public void stop(PluginCall call) {
-        getActivity().runOnUiThread(() -> {
-            implementation.stop();
-            call.resolve();
-        });
-    }
-
-    @PluginMethod
-    public void flip(PluginCall call) {
-        if (!ensureRunning(call)) return;
-        getActivity().runOnUiThread(() -> implementation.flip(voidCallback(call)));
-    }
-
-    @PluginMethod
-    public void capture(PluginCall call) {
-        if (!ensureRunning(call)) return;
-        int quality = Math.max(0, Math.min(100, call.getInt("quality", 85)));
-        implementation.capture(
-            quality,
-            new CardScanner.Callback<>() {
-                @Override
-                public void onSuccess(CardScanner.Photo photo) {
-                    JSObject ret = new JSObject();
-                    ret.put("base64", photo.base64);
-                    ret.put("width", photo.width);
-                    ret.put("height", photo.height);
-                    call.resolve(ret);
-                }
-
-                @Override
-                public void onError(String message, Exception e) {
-                    call.reject(message, e);
-                }
-            }
-        );
-    }
-
-    @PluginMethod
-    public void startDetection(PluginCall call) {
-        if (!ensureRunning(call)) return;
-        CardDetector detector = new CardDetector(
-            call.getInt("intervalMs", 300),
-            call.getInt("stableFrames", 2),
-            Boolean.TRUE.equals(call.getBoolean("includeImage", false)),
-            result -> notifyListeners("cardDetected", result)
-        );
-        getActivity().runOnUiThread(() -> {
-            try {
-                implementation.startDetection(detector);
-                call.resolve();
-            } catch (Exception e) {
-                detector.close();
-                call.reject("Failed to start detection: " + e.getMessage(), e);
-            }
-        });
-    }
-
-    @PluginMethod
-    public void stopDetection(PluginCall call) {
-        getActivity().runOnUiThread(() -> {
-            implementation.stopDetection();
-            call.resolve();
-        });
-    }
-
-    @PluginMethod
-    public void setTorch(PluginCall call) {
-        if (!ensureRunning(call)) return;
-        implementation.setTorch(Boolean.TRUE.equals(call.getBoolean("enabled", false)));
-        call.resolve();
-    }
-
-    @PluginMethod
-    public void setZoom(PluginCall call) {
-        if (!ensureRunning(call)) return;
-        Float ratio = call.getFloat("ratio");
-        if (ratio == null) {
-            call.reject("Missing 'ratio'");
-            return;
-        }
-        implementation.setZoom(ratio);
-        call.resolve();
-    }
-
-    private boolean ensureRunning(PluginCall call) {
-        if (!implementation.isRunning()) {
-            call.reject("Camera is not running", "NOT_RUNNING");
-            return false;
-        }
-        return true;
-    }
-
-    private CardScanner.Callback<Void> voidCallback(PluginCall call) {
-        return new CardScanner.Callback<>() {
-            @Override
-            public void onSuccess(Void result) {
-                call.resolve();
-            }
-
-            @Override
-            public void onError(String message, Exception e) {
-                call.reject(message, e);
-            }
-        };
-    }
-}
+package pt.tcgclassifier.cardscanner;
+
+import android.Manifest;
+import com.getcapacitor.JSObject;
+import com.getcapacitor.PermissionState;
+import com.getcapacitor.Plugin;
+import com.getcapacitor.PluginCall;
+import com.getcapacitor.PluginMethod;
+import com.getcapacitor.annotation.CapacitorPlugin;
+import com.getcapacitor.annotation.Permission;
+import com.getcapacitor.annotation.PermissionCallback;
+
+@CapacitorPlugin(name = "CardScanner", permissions = { @Permission(strings = { Manifest.permission.CAMERA }, alias = CardScannerPlugin.CAMERA) })
+public class CardScannerPlugin extends Plugin {
+
+    static final String CAMERA = "camera";
+
+    private CardScanner implementation;
+
+    @Override
+    public void load() {
+        implementation = new CardScanner(getActivity(), getBridge().getWebView());
+    }
+
+    @Override
+    protected void handleOnDestroy() {
+        getActivity().runOnUiThread(() -> implementation.stop());
+    }
+
+    @PluginMethod
+    public void start(PluginCall call) {
+        if (getPermissionState(CAMERA) != PermissionState.GRANTED) {
+            requestPermissionForAlias(CAMERA, call, "cameraPermsCallback");
+            return;
+        }
+        doStart(call);
+    }
+
+    @PermissionCallback
+    private void cameraPermsCallback(PluginCall call) {
+        if (getPermissionState(CAMERA) == PermissionState.GRANTED) {
+            doStart(call);
+        } else {
+            call.reject("Camera permission denied", "PERMISSION_DENIED");
+        }
+    }
+
+    private void doStart(PluginCall call) {
+        boolean front = "front".equals(call.getString("position", "rear"));
+        getActivity().runOnUiThread(() -> implementation.start(front, voidCallback(call)));
+    }
+
+    @PluginMethod
+    public void stop(PluginCall call) {
+        getActivity().runOnUiThread(() -> {
+            implementation.stop();
+            call.resolve();
+        });
+    }
+
+    @PluginMethod
+    public void flip(PluginCall call) {
+        if (!ensureRunning(call)) return;
+        getActivity().runOnUiThread(() -> implementation.flip(voidCallback(call)));
+    }
+
+    @PluginMethod
+    public void capture(PluginCall call) {
+        if (!ensureRunning(call)) return;
+        int quality = Math.max(0, Math.min(100, call.getInt("quality", 85)));
+        implementation.capture(
+            quality,
+            new CardScanner.Callback<>() {
+                @Override
+                public void onSuccess(CardScanner.Photo photo) {
+                    JSObject ret = new JSObject();
+                    ret.put("base64", photo.base64);
+                    ret.put("width", photo.width);
+                    ret.put("height", photo.height);
+                    call.resolve(ret);
+                }
+
+                @Override
+                public void onError(String message, Exception e) {
+                    call.reject(message, e);
+                }
+            }
+        );
+    }
+
+    @PluginMethod
+    public void startDetection(PluginCall call) {
+        if (!ensureRunning(call)) return;
+        CardDetector.Options options = new CardDetector.Options();
+        options.intervalMs = call.getInt("intervalMs", (int) options.intervalMs);
+        options.stableFrames = call.getInt("stableFrames", options.stableFrames);
+        options.includeImage = call.getBoolean("includeImage", options.includeImage);
+        options.cardAspectRatio = call.getFloat("cardAspectRatio", options.cardAspectRatio);
+        options.aspectTolerance = call.getFloat("aspectTolerance", options.aspectTolerance);
+        options.minCardArea = call.getFloat("minCardArea", options.minCardArea);
+        options.maxCardArea = call.getFloat("maxCardArea", options.maxCardArea);
+        options.requireCard = call.getBoolean("requireCard", options.requireCard);
+        options.debug = call.getBoolean("debug", options.debug);
+
+        CardDetector detector = new CardDetector(options, result -> notifyListeners("cardDetected", result));
+        getActivity().runOnUiThread(() -> {
+            try {
+                implementation.startDetection(detector);
+                call.resolve();
+            } catch (Exception e) {
+                detector.close();
+                call.reject("Failed to start detection: " + e.getMessage(), e);
+            }
+        });
+    }
+
+    @PluginMethod
+    public void stopDetection(PluginCall call) {
+        getActivity().runOnUiThread(() -> {
+            implementation.stopDetection();
+            call.resolve();
+        });
+    }
+
+    @PluginMethod
+    public void setTorch(PluginCall call) {
+        if (!ensureRunning(call)) return;
+        implementation.setTorch(Boolean.TRUE.equals(call.getBoolean("enabled", false)));
+        call.resolve();
+    }
+
+    @PluginMethod
+    public void setZoom(PluginCall call) {
+        if (!ensureRunning(call)) return;
+        Float ratio = call.getFloat("ratio");
+        if (ratio == null) {
+            call.reject("Missing 'ratio'");
+            return;
+        }
+        implementation.setZoom(ratio);
+        call.resolve();
+    }
+
+    private boolean ensureRunning(PluginCall call) {
+        if (!implementation.isRunning()) {
+            call.reject("Camera is not running", "NOT_RUNNING");
+            return false;
+        }
+        return true;
+    }
+
+    private CardScanner.Callback<Void> voidCallback(PluginCall call) {
+        return new CardScanner.Callback<>() {
+            @Override
+            public void onSuccess(Void result) {
+                call.resolve();
+            }
+
+            @Override
+            public void onError(String message, Exception e) {
+                call.reject(message, e);
+            }
+        };
+    }
+}

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

@@ -8,35 +8,52 @@ import android.graphics.RectF;
 import android.os.SystemClock;
 import android.view.View;
 import androidx.annotation.Nullable;
+import java.util.Collections;
+import java.util.List;
 
 /**
  * Draws a red rectangle around the detected card. Sits between the camera
  * preview and the (transparent) WebView, and maps frame coordinates the same
- * way PreviewView's FILL_CENTER does.
+ * way PreviewView's FILL_CENTER does. In debug mode it also draws every object
+ * ML Kit found, labelled with its area/ratio (grey when rejected).
  */
 public class DetectionOverlay extends View {
 
     /** Keep the rectangle this long after the card was last seen, to avoid flicker. */
     private static final long HIDE_AFTER_MS = 300;
 
-    private final Paint paint = new Paint(Paint.ANTI_ALIAS_FLAG);
+    private final Paint cardPaint = new Paint(Paint.ANTI_ALIAS_FLAG);
+    private final Paint rejectedPaint = new Paint(Paint.ANTI_ALIAS_FLAG);
+    private final Paint labelPaint = new Paint(Paint.ANTI_ALIAS_FLAG);
     private final float radius;
+    private final float labelPadding;
     private final RectF drawRect = new RectF();
 
     @Nullable
-    private RectF box;
+    private RectF card;
+    private List<CardDetector.Candidate> candidates = Collections.emptyList();
     private int frameWidth;
     private int frameHeight;
     private boolean mirror;
-    private long lastBoxAt;
+    private long lastCardAt;
 
     public DetectionOverlay(Context context) {
         super(context);
         float density = context.getResources().getDisplayMetrics().density;
         radius = 8 * density;
-        paint.setColor(Color.RED);
-        paint.setStyle(Paint.Style.STROKE);
-        paint.setStrokeWidth(3 * density);
+        labelPadding = 4 * density;
+
+        cardPaint.setColor(Color.RED);
+        cardPaint.setStyle(Paint.Style.STROKE);
+        cardPaint.setStrokeWidth(3 * density);
+
+        rejectedPaint.setColor(Color.argb(200, 180, 180, 180));
+        rejectedPaint.setStyle(Paint.Style.STROKE);
+        rejectedPaint.setStrokeWidth(2 * density);
+
+        labelPaint.setColor(Color.WHITE);
+        labelPaint.setTextSize(13 * density);
+        labelPaint.setShadowLayer(3 * density, 0, 0, Color.BLACK);
     }
 
     public void setMirror(boolean mirror) {
@@ -44,28 +61,44 @@ public class DetectionOverlay extends View {
     }
 
     /** Must be called on the UI thread. */
-    public void setBox(@Nullable RectF box, int frameWidth, int frameHeight) {
+    public void setDetections(@Nullable RectF card, List<CardDetector.Candidate> candidates, int frameWidth, int frameHeight) {
         long now = SystemClock.uptimeMillis();
-        if (box == null) {
-            if (this.box == null || now - lastBoxAt < HIDE_AFTER_MS) return;
-        } else {
-            lastBoxAt = now;
+        if (card != null) {
+            lastCardAt = now;
+            this.card = card;
+        } else if (now - lastCardAt >= HIDE_AFTER_MS) {
+            this.card = null;
         }
-        this.box = box;
+        this.candidates = candidates;
         this.frameWidth = frameWidth;
         this.frameHeight = frameHeight;
         invalidate();
     }
 
     public void clear() {
-        box = null;
+        card = null;
+        candidates = Collections.emptyList();
         invalidate();
     }
 
     @Override
     protected void onDraw(Canvas canvas) {
-        if (box == null || frameWidth == 0 || frameHeight == 0) return;
+        if (frameWidth == 0 || frameHeight == 0) return;
+
+        for (CardDetector.Candidate c : candidates) {
+            map(c.box);
+            canvas.drawRoundRect(drawRect, radius, radius, c.rejectedBy == null ? cardPaint : rejectedPaint);
+            canvas.drawText(c.label(), drawRect.left + labelPadding, drawRect.top - labelPadding, labelPaint);
+        }
+
+        if (card != null) {
+            map(card);
+            canvas.drawRoundRect(drawRect, radius, radius, cardPaint);
+        }
+    }
 
+    /** Maps a normalized frame rectangle into drawRect, in view coordinates. */
+    private void map(RectF box) {
         float vw = getWidth();
         float vh = getHeight();
         float scale = Math.max(vw / frameWidth, vh / frameHeight);
@@ -77,6 +110,5 @@ public class DetectionOverlay extends View {
         float left = mirror ? 1f - box.right : box.left;
         float right = mirror ? 1f - box.left : box.right;
         drawRect.set(dx + left * sw, dy + box.top * sh, dx + right * sw, dy + box.bottom * sh);
-        canvas.drawRoundRect(drawRect, radius, radius, paint);
     }
 }

package/dist/docs.json

@@ -336,6 +336,78 @@
           "docs": "Include a JPEG of the detected card in the event.",
           "complexTypes": [],
           "type": "boolean | undefined"
+        },
+        {
+          "name": "cardAspectRatio",
+          "tags": [
+            {
+              "text": "0.716 (63 x 88 mm)",
+              "name": "default"
+            }
+          ],
+          "docs": "Expected width / height of an upright card. Only upright cards are\ndetected; a card lying sideways falls outside the tolerance.",
+          "complexTypes": [],
+          "type": "number | undefined"
+        },
+        {
+          "name": "aspectTolerance",
+          "tags": [
+            {
+              "text": "0.15",
+              "name": "default"
+            }
+          ],
+          "docs": "Allowed relative deviation from `cardAspectRatio` (0.15 = ±15%).\nIncrease it if tilted cards are not detected.",
+          "complexTypes": [],
+          "type": "number | undefined"
+        },
+        {
+          "name": "minCardArea",
+          "tags": [
+            {
+              "text": "0.08",
+              "name": "default"
+            }
+          ],
+          "docs": "Smallest card size, as a fraction of the camera frame (0-1).",
+          "complexTypes": [],
+          "type": "number | undefined"
+        },
+        {
+          "name": "maxCardArea",
+          "tags": [
+            {
+              "text": "0.9",
+              "name": "default"
+            }
+          ],
+          "docs": "Largest card size, as a fraction of the camera frame (0-1).",
+          "complexTypes": [],
+          "type": "number | undefined"
+        },
+        {
+          "name": "requireCard",
+          "tags": [
+            {
+              "text": "true",
+              "name": "default"
+            }
+          ],
+          "docs": "Only read text when a card-shaped object is visible. When false, the whole\nframe is read if no card is found.",
+          "complexTypes": [],
+          "type": "boolean | undefined"
+        },
+        {
+          "name": "debug",
+          "tags": [
+            {
+              "text": "false",
+              "name": "default"
+            }
+          ],
+          "docs": "Draw every object found, labelled with its area (`a`) and width/height\nratio (`r`): red when accepted as a card, grey when rejected (with the\nfilter that rejected it). Use it to tune the filters above.",
+          "complexTypes": [],
+          "type": "boolean | undefined"
         }
       ]
     },

package/dist/esm/definitions.d.ts

@@ -48,6 +48,41 @@ export interface DetectionOptions {
      * @default false
      */
     includeImage?: boolean;
+    /**
+     * Expected width / height of an upright card. Only upright cards are
+     * detected; a card lying sideways falls outside the tolerance.
+     * @default 0.716 (63 x 88 mm)
+     */
+    cardAspectRatio?: number;
+    /**
+     * Allowed relative deviation from `cardAspectRatio` (0.15 = ±15%).
+     * Increase it if tilted cards are not detected.
+     * @default 0.15
+     */
+    aspectTolerance?: number;
+    /**
+     * Smallest card size, as a fraction of the camera frame (0-1).
+     * @default 0.08
+     */
+    minCardArea?: number;
+    /**
+     * Largest card size, as a fraction of the camera frame (0-1).
+     * @default 0.9
+     */
+    maxCardArea?: number;
+    /**
+     * Only read text when a card-shaped object is visible. When false, the whole
+     * frame is read if no card is found.
+     * @default true
+     */
+    requireCard?: boolean;
+    /**
+     * Draw every object found, labelled with its area (`a`) and width/height
+     * ratio (`r`): red when accepted as a card, grey when rejected (with the
+     * filter that rejected it). Use it to tune the filters above.
+     * @default false
+     */
+    debug?: boolean;
 }
 /** Normalized rectangle (0-1). */
 export interface Box {

package/dist/esm/definitions.js.map

@@ -1 +1 @@
-{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["import type { PermissionState, PluginListenerHandle } from '@capacitor/core';\n\nexport type CameraPosition = 'rear' | 'front';\n\nexport interface StartOptions {\n  /**\n   * Which camera to use.\n   * @default 'rear'\n   */\n  position?: CameraPosition;\n}\n\nexport interface CaptureOptions {\n  /**\n   * JPEG quality (0-100).\n   * @default 85\n   */\n  quality?: number;\n}\n\nexport interface CaptureResult {\n  /** Base64 encoded JPEG (without the `data:` prefix). */\n  base64: string;\n  width: number;\n  height: number;\n}\n\nexport interface TorchOptions {\n  enabled: boolean;\n}\n\nexport interface ZoomOptions {\n  /** Zoom ratio, clamped between the camera's min and max. */\n  ratio: number;\n}\n\nexport interface PermissionStatus {\n  camera: PermissionState;\n}\n\nexport interface DetectionOptions {\n  /**\n   * Minimum time between two OCR runs, in milliseconds.\n   * The red rectangle is updated on every frame regardless.\n   * @default 300\n   */\n  intervalMs?: number;\n  /**\n   * How many consecutive OCR runs must read the same card before\n   * `cardDetected` fires.\n   * @default 2\n   */\n  stableFrames?: number;\n  /**\n   * Include a JPEG of the detected card in the event.\n   * @default false\n   */\n  includeImage?: boolean;\n}\n\n/** Normalized rectangle (0-1). */\nexport interface Box {\n  x: number;\n  y: number;\n  width: number;\n  height: number;\n}\n\nexport interface TextLine {\n  text: string;\n  /** Position inside the card image. */\n  box: Box;\n}\n\nexport interface CardDetectedEvent {\n  /** Best guess for the card name (topmost line of text on the card). */\n  name?: string;\n  /** Collector number, e.g. `025/165`. */\n  collectorNumber?: string;\n  /** All text read on the card. */\n  text: string;\n  lines: TextLine[];\n  /** Where the card is in the camera frame. Missing if no card outline was found. */\n  cardBox?: Box;\n  /** Base64 JPEG of the card, when `includeImage` is true. */\n  image?: string;\n}\n\nexport interface CardScannerPlugin {\n  /**\n   * Opens the camera **behind** the WebView. The WebView background is made\n   * transparent, so the HTML page must also use transparent backgrounds\n   * where the camera should be visible.\n   */\n  start(options?: StartOptions): Promise<void>;\n\n  /** Stops the camera and removes the preview. */\n  stop(): Promise<void>;\n\n  /** Takes a photo from the running camera. */\n  capture(options?: CaptureOptions): Promise<CaptureResult>;\n\n  /** Turns the flashlight on/off. */\n  setTorch(options: TorchOptions): Promise<void>;\n\n  /** Sets the zoom ratio. */\n  setZoom(options: ZoomOptions): Promise<void>;\n\n  /** Switches between the rear and front camera. */\n  flip(): Promise<void>;\n\n  /**\n   * Starts looking for cards: draws a red rectangle around the card and reads\n   * its text, emitting `cardDetected`. Requires `start()` first. Android only.\n   */\n  startDetection(options?: DetectionOptions): Promise<void>;\n\n  /** Stops card detection and hides the rectangle. */\n  stopDetection(): Promise<void>;\n\n  /** Fired once per card, when its text has been read consistently. */\n  addListener(eventName: 'cardDetected', listener: (event: CardDetectedEvent) => void): Promise<PluginListenerHandle>;\n\n  removeAllListeners(): Promise<void>;\n\n  checkPermissions(): Promise<PermissionStatus>;\n\n  requestPermissions(): Promise<PermissionStatus>;\n}\n"]}
+{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["import type { PermissionState, PluginListenerHandle } from '@capacitor/core';\n\nexport type CameraPosition = 'rear' | 'front';\n\nexport interface StartOptions {\n  /**\n   * Which camera to use.\n   * @default 'rear'\n   */\n  position?: CameraPosition;\n}\n\nexport interface CaptureOptions {\n  /**\n   * JPEG quality (0-100).\n   * @default 85\n   */\n  quality?: number;\n}\n\nexport interface CaptureResult {\n  /** Base64 encoded JPEG (without the `data:` prefix). */\n  base64: string;\n  width: number;\n  height: number;\n}\n\nexport interface TorchOptions {\n  enabled: boolean;\n}\n\nexport interface ZoomOptions {\n  /** Zoom ratio, clamped between the camera's min and max. */\n  ratio: number;\n}\n\nexport interface PermissionStatus {\n  camera: PermissionState;\n}\n\nexport interface DetectionOptions {\n  /**\n   * Minimum time between two OCR runs, in milliseconds.\n   * The red rectangle is updated on every frame regardless.\n   * @default 300\n   */\n  intervalMs?: number;\n  /**\n   * How many consecutive OCR runs must read the same card before\n   * `cardDetected` fires.\n   * @default 2\n   */\n  stableFrames?: number;\n  /**\n   * Include a JPEG of the detected card in the event.\n   * @default false\n   */\n  includeImage?: boolean;\n  /**\n   * Expected width / height of an upright card. Only upright cards are\n   * detected; a card lying sideways falls outside the tolerance.\n   * @default 0.716 (63 x 88 mm)\n   */\n  cardAspectRatio?: number;\n  /**\n   * Allowed relative deviation from `cardAspectRatio` (0.15 = ±15%).\n   * Increase it if tilted cards are not detected.\n   * @default 0.15\n   */\n  aspectTolerance?: number;\n  /**\n   * Smallest card size, as a fraction of the camera frame (0-1).\n   * @default 0.08\n   */\n  minCardArea?: number;\n  /**\n   * Largest card size, as a fraction of the camera frame (0-1).\n   * @default 0.9\n   */\n  maxCardArea?: number;\n  /**\n   * Only read text when a card-shaped object is visible. When false, the whole\n   * frame is read if no card is found.\n   * @default true\n   */\n  requireCard?: boolean;\n  /**\n   * Draw every object found, labelled with its area (`a`) and width/height\n   * ratio (`r`): red when accepted as a card, grey when rejected (with the\n   * filter that rejected it). Use it to tune the filters above.\n   * @default false\n   */\n  debug?: boolean;\n}\n\n/** Normalized rectangle (0-1). */\nexport interface Box {\n  x: number;\n  y: number;\n  width: number;\n  height: number;\n}\n\nexport interface TextLine {\n  text: string;\n  /** Position inside the card image. */\n  box: Box;\n}\n\nexport interface CardDetectedEvent {\n  /** Best guess for the card name (topmost line of text on the card). */\n  name?: string;\n  /** Collector number, e.g. `025/165`. */\n  collectorNumber?: string;\n  /** All text read on the card. */\n  text: string;\n  lines: TextLine[];\n  /** Where the card is in the camera frame. Missing if no card outline was found. */\n  cardBox?: Box;\n  /** Base64 JPEG of the card, when `includeImage` is true. */\n  image?: string;\n}\n\nexport interface CardScannerPlugin {\n  /**\n   * Opens the camera **behind** the WebView. The WebView background is made\n   * transparent, so the HTML page must also use transparent backgrounds\n   * where the camera should be visible.\n   */\n  start(options?: StartOptions): Promise<void>;\n\n  /** Stops the camera and removes the preview. */\n  stop(): Promise<void>;\n\n  /** Takes a photo from the running camera. */\n  capture(options?: CaptureOptions): Promise<CaptureResult>;\n\n  /** Turns the flashlight on/off. */\n  setTorch(options: TorchOptions): Promise<void>;\n\n  /** Sets the zoom ratio. */\n  setZoom(options: ZoomOptions): Promise<void>;\n\n  /** Switches between the rear and front camera. */\n  flip(): Promise<void>;\n\n  /**\n   * Starts looking for cards: draws a red rectangle around the card and reads\n   * its text, emitting `cardDetected`. Requires `start()` first. Android only.\n   */\n  startDetection(options?: DetectionOptions): Promise<void>;\n\n  /** Stops card detection and hides the rectangle. */\n  stopDetection(): Promise<void>;\n\n  /** Fired once per card, when its text has been read consistently. */\n  addListener(eventName: 'cardDetected', listener: (event: CardDetectedEvent) => void): Promise<PluginListenerHandle>;\n\n  removeAllListeners(): Promise<void>;\n\n  checkPermissions(): Promise<PermissionStatus>;\n\n  requestPermissions(): Promise<PermissionStatus>;\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "capacitor-card-scanner",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Recognize a pokemon card with camera open in background",
   "main": "dist/plugin.cjs.js",
   "module": "dist/esm/index.js",