capacitor-card-scanner 0.1.0 → 0.2.0

package/README.md

@@ -328,11 +328,16 @@ 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>               |
 
 
 #### PluginListenerHandle

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

@@ -1,249 +1,283 @@
-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.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);
+    }
+
+    /** 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;
+    }
+
+    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;
+    /** 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();
+        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 < options.intervalMs) return;
+            lastOcrAt = now;
+
+            if (card == null && options.requireCard) {
+                noCardRead(now);
+                return;
+            }
+
+            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 with the size and upright proportions of a card. */
+    @Nullable
+    private Rect pickCard(List<DetectedObject> objects, int frameW, int frameH) {
+        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;
+            if (fraction < options.minCardArea || fraction > options.maxCardArea) continue;
+
+            float ratio = r.width() / (float) r.height();
+            if (ratio < minRatio || ratio > maxRatio) continue;
+
+            if (area > bestArea) {
+                best = r;
+                bestArea = area;
+            }
+        }
+        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) {
+            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/CardScannerPlugin.java

@@ -91,12 +91,17 @@ public class CardScannerPlugin extends Plugin {
     @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)
-        );
+        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);
+
+        CardDetector detector = new CardDetector(options, result -> notifyListeners("cardDetected", result));
         getActivity().runOnUiThread(() -> {
             try {
                 implementation.startDetection(detector);

package/dist/docs.json

@@ -336,6 +336,66 @@
           "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"
         }
       ]
     },

package/dist/esm/definitions.d.ts

@@ -48,6 +48,34 @@ 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;
 }
 /** 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\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.2.0",
   "description": "Recognize a pokemon card with camera open in background",
   "main": "dist/plugin.cjs.js",
   "module": "dist/esm/index.js",