capacitor-card-scanner 0.2.0 → 0.3.1

package/README.md

@@ -328,16 +328,18 @@ 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>              |
-| **`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>               |
+| 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> | Every object found is always outlined: red when accepted as a card, grey when rejected. With `debug`, each outline is also labelled with its area (`a`), width/height ratio (`r`) and the filter that rejected it. Use it to tune the filters above. | <code>false</code>              |
+| **`showRejected`**    | <code>boolean</code> | Outline (in grey) the objects that were not accepted as a card. The accepted card is always outlined in red.                                                                                                                                         | <code>true</code>               |
 
 
 #### PluginListenerHandle

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

@@ -24,7 +24,9 @@ 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.List;
+import java.util.Locale;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 
@@ -58,13 +60,44 @@ public class CardDetector implements ImageAnalysis.Analyzer {
         public float maxCardArea = 0.9f;
         /** Only run OCR when a card-shaped object is visible. */
         public boolean requireCard = true;
+        /** Label every detected object with its area/ratio and the filter that rejected it. */
+        public boolean debug = false;
+        /** Outline (in grey) the objects that were not accepted as a card. */
+        public boolean showRejected = true;
+    }
+
+    /** 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 box card bounds normalized (0-1) to the upright frame, or null when no card is visible
+         * @param card card bounds normalized (0-1) to the upright frame, or null when no card is visible
+         * @param candidates every detected object, accepted or not
          */
-        void onBox(@Nullable RectF box, int frameWidth, int frameHeight);
+        void onDetections(@Nullable RectF card, List<Candidate> candidates, int frameWidth, int frameHeight);
     }
 
     // e.g. "025/165", "SV001/SV122", "TG05/TG30", "GG01/GG70"
@@ -101,6 +134,14 @@ public class CardDetector implements ImageAnalysis.Analyzer {
         this.listener = listener;
     }
 
+    public boolean isDebug() {
+        return options.debug;
+    }
+
+    public boolean isShowRejected() {
+        return options.showRejected;
+    }
+
     public void setBoxListener(BoxListener boxListener) {
         this.boxListener = boxListener;
     }
@@ -113,27 +154,23 @@ public class CardDetector implements ImageAnalysis.Analyzer {
     @Override
     public void analyze(@NonNull ImageProxy image) {
         long now = SystemClock.elapsedRealtime();
-        int rotation = image.getImageInfo().getRotationDegrees();
-        Bitmap raw;
+        Bitmap upright;
         try {
-            raw = image.toBitmap();
+            // 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 = rotation % 180 == 0 ? raw.getWidth() : raw.getHeight();
-        int frameH = rotation % 180 == 0 ? raw.getHeight() : raw.getWidth();
+        int frameW = upright.getWidth();
+        int frameH = upright.getHeight();
 
         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
-            );
+            List<DetectedObject> objects = Tasks.await(objectDetector.process(InputImage.fromBitmap(upright, 0)));
+            List<Candidate> candidates = new ArrayList<>();
+            Rect card = pickCard(objects, frameW, frameH, candidates);
+            RectF cardBox = card == null ? null : normalize(card, frameW, frameH);
             BoxListener bl = boxListener;
-            if (bl != null) bl.onBox(cardBox, frameW, frameH);
+            if (bl != null) bl.onDetections(cardBox, candidates, frameW, frameH);
 
             if (now - lastOcrAt < options.intervalMs) return;
             lastOcrAt = now;
@@ -143,7 +180,6 @@ public class CardDetector implements ImageAnalysis.Analyzer {
                 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);
@@ -152,9 +188,12 @@ public class CardDetector implements ImageAnalysis.Analyzer {
         }
     }
 
-    /** The biggest detected object with the size and upright proportions of a card. */
+    /**
+     * The biggest detected object with the size and upright proportions of a card.
+     * Every object, accepted or not, is added to {@code candidates}.
+     */
     @Nullable
-    private Rect pickCard(List<DetectedObject> objects, int frameW, int frameH) {
+    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);
@@ -166,10 +205,15 @@ public class CardDetector implements ImageAnalysis.Analyzer {
 
             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;
+            String rejectedBy = null;
+            if (fraction < options.minCardArea || fraction > options.maxCardArea) {
+                rejectedBy = "area";
+            } else if (ratio < minRatio || ratio > maxRatio) {
+                rejectedBy = "ratio";
+            }
+            candidates.add(new Candidate(normalize(r, frameW, frameH), fraction, ratio, rejectedBy));
+            if (rejectedBy != null) continue;
 
             if (area > bestArea) {
                 best = r;
@@ -179,6 +223,10 @@ public class CardDetector implements ImageAnalysis.Analyzer {
         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();

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

@@ -151,10 +151,12 @@ public class CardScanner {
         closeDetector();
         detector = newDetector;
         DetectionOverlay target = overlay;
-        detector.setBoxListener((box, frameW, frameH) ->
+        target.setShowLabels(newDetector.isDebug());
+        target.setShowRejected(newDetector.isShowRejected());
+        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,164 +1,166 @@
-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);
-
-        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 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);
+        options.showRejected = call.getBoolean("showRejected", options.showRejected);
+
+        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

@@ -1,82 +1,127 @@
-package pt.tcgclassifier.cardscanner;
-
-import android.content.Context;
-import android.graphics.Canvas;
-import android.graphics.Color;
-import android.graphics.Paint;
-import android.graphics.RectF;
-import android.os.SystemClock;
-import android.view.View;
-import androidx.annotation.Nullable;
-
-/**
- * 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.
- */
-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 float radius;
-    private final RectF drawRect = new RectF();
-
-    @Nullable
-    private RectF box;
-    private int frameWidth;
-    private int frameHeight;
-    private boolean mirror;
-    private long lastBoxAt;
-
-    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);
-    }
-
-    public void setMirror(boolean mirror) {
-        this.mirror = mirror;
-    }
-
-    /** Must be called on the UI thread. */
-    public void setBox(@Nullable RectF box, int frameWidth, int frameHeight) {
-        long now = SystemClock.uptimeMillis();
-        if (box == null) {
-            if (this.box == null || now - lastBoxAt < HIDE_AFTER_MS) return;
-        } else {
-            lastBoxAt = now;
-        }
-        this.box = box;
-        this.frameWidth = frameWidth;
-        this.frameHeight = frameHeight;
-        invalidate();
-    }
-
-    public void clear() {
-        box = null;
-        invalidate();
-    }
-
-    @Override
-    protected void onDraw(Canvas canvas) {
-        if (box == null || frameWidth == 0 || frameHeight == 0) return;
-
-        float vw = getWidth();
-        float vh = getHeight();
-        float scale = Math.max(vw / frameWidth, vh / frameHeight);
-        float sw = frameWidth * scale;
-        float sh = frameHeight * scale;
-        float dx = (vw - sw) / 2f;
-        float dy = (vh - sh) / 2f;
-
-        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 pt.tcgclassifier.cardscanner;
+
+import android.content.Context;
+import android.graphics.Canvas;
+import android.graphics.Color;
+import android.graphics.Paint;
+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. Objects that are not accepted as a card
+ * are drawn in grey; with labels on, each one shows its area/ratio.
+ */
+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 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 card;
+    private List<CardDetector.Candidate> candidates = Collections.emptyList();
+    private int frameWidth;
+    private int frameHeight;
+    private boolean mirror;
+    private boolean showLabels;
+    private boolean showRejected = true;
+    private long lastCardAt;
+
+    public DetectionOverlay(Context context) {
+        super(context);
+        float density = context.getResources().getDisplayMetrics().density;
+        radius = 8 * 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) {
+        this.mirror = mirror;
+    }
+
+    public void setShowLabels(boolean showLabels) {
+        this.showLabels = showLabels;
+    }
+
+    public void setShowRejected(boolean showRejected) {
+        this.showRejected = showRejected;
+    }
+
+    /** Must be called on the UI thread. */
+    public void setDetections(@Nullable RectF card, List<CardDetector.Candidate> candidates, int frameWidth, int frameHeight) {
+        long now = SystemClock.uptimeMillis();
+        if (card != null) {
+            lastCardAt = now;
+            this.card = card;
+        } else if (now - lastCardAt >= HIDE_AFTER_MS) {
+            this.card = null;
+        }
+        this.candidates = candidates;
+        this.frameWidth = frameWidth;
+        this.frameHeight = frameHeight;
+        invalidate();
+    }
+
+    public void clear() {
+        card = null;
+        candidates = Collections.emptyList();
+        invalidate();
+    }
+
+    @Override
+    protected void onDraw(Canvas canvas) {
+        if (frameWidth == 0 || frameHeight == 0) return;
+
+        for (CardDetector.Candidate c : candidates) {
+            if (c.rejectedBy != null && !showRejected) continue;
+            map(c.box);
+            canvas.drawRoundRect(drawRect, radius, radius, c.rejectedBy == null ? cardPaint : rejectedPaint);
+            if (showLabels) {
+                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);
+        float sw = frameWidth * scale;
+        float sh = frameHeight * scale;
+        float dx = (vw - sw) / 2f;
+        float dy = (vh - sh) / 2f;
+
+        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);
+    }
+}

package/dist/docs.json

@@ -396,6 +396,30 @@
           "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": "Every object found is always outlined: red when accepted as a card, grey\nwhen rejected. With `debug`, each outline is also labelled with its area\n(`a`), width/height ratio (`r`) and the filter that rejected it. Use it to\ntune the filters above.",
+          "complexTypes": [],
+          "type": "boolean | undefined"
+        },
+        {
+          "name": "showRejected",
+          "tags": [
+            {
+              "text": "true",
+              "name": "default"
+            }
+          ],
+          "docs": "Outline (in grey) the objects that were not accepted as a card.\nThe accepted card is always outlined in red.",
+          "complexTypes": [],
+          "type": "boolean | undefined"
         }
       ]
     },

package/dist/esm/definitions.d.ts

@@ -76,6 +76,20 @@ export interface DetectionOptions {
      * @default true
      */
     requireCard?: boolean;
+    /**
+     * Every object found is always outlined: red when accepted as a card, grey
+     * when rejected. With `debug`, each outline is also labelled with its area
+     * (`a`), width/height ratio (`r`) and the filter that rejected it. Use it to
+     * tune the filters above.
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Outline (in grey) the objects that were not accepted as a card.
+     * The accepted card is always outlined in red.
+     * @default true
+     */
+    showRejected?: 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   * 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"]}
+{"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   * Every object found is always outlined: red when accepted as a card, grey\n   * when rejected. With `debug`, each outline is also labelled with its area\n   * (`a`), width/height ratio (`r`) and the filter that rejected it. Use it to\n   * tune the filters above.\n   * @default false\n   */\n  debug?: boolean;\n  /**\n   * Outline (in grey) the objects that were not accepted as a card.\n   * The accepted card is always outlined in red.\n   * @default true\n   */\n  showRejected?: 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.2.0",
+  "version": "0.3.1",
   "description": "Recognize a pokemon card with camera open in background",
   "main": "dist/plugin.cjs.js",
   "module": "dist/esm/index.js",