drawdown-arcore-depth 0.1.4 → 0.1.5

package/README.md

@@ -188,3 +188,8 @@ No ArUco marker is required by the native ARCore workflow. The existing RFID/NFC
 ## v0.1.4 Raw Depth field fix
 
 The DBH sampler now anchors front-surface range with ARCore Raw Depth plus the matching confidence image (confidence >= 128). Smoothed Depth is used only after a high-confidence foreground tree range has been established, to fill the trunk surface for multi-row boundary estimation. This prevents distant outdoor background depth from being mistaken for the trunk.
+
+
+## 0.1.5 diagnostic sweep
+
+Version 0.1.5 keeps the 0.1.4 Raw Depth DBH acceptance geometry unchanged and adds compact native sweep diagnostics. `captureDbhSweep()` now reports per-stage frame counts and `nativeRejectionCounts` so zero-observation field failures can be diagnosed without retaining camera or depth frames.

package/android/src/main/java/org/drawdown/arcoredepth/DepthObservationSampler.java

@@ -39,29 +39,69 @@ final class DepthObservationSampler {
     private static final double MIN_TARGET_DEPTH_MM = 500.0;
     private static final double MAX_TARGET_DEPTH_MM = 5000.0;
 
-    DepthObservation sample(Frame frame, Camera camera, int viewWidth, int viewHeight) {
+    DepthSampleResult sample(Frame frame, Camera camera, int viewWidth, int viewHeight) {
+        boolean trackingFrame = false;
+        boolean rawDepthFrame = false;
+        boolean mappedCenterReached = false;
+        boolean rawAnchorReached = false;
+        boolean rawPatchReached = false;
+        boolean smoothDepthMatchReached = false;
+        boolean boundaryConsensusReached = false;
+
         if (camera.getTrackingState() != TrackingState.TRACKING) {
-            return null;
+            return DepthSampleResult.failure(
+                    "tracking_not_tracking",
+                    false, false, false, false, false, false, false);
         }
+        trackingFrame = true;
+
+        Image rawDepth = null;
+        Image rawConfidence = null;
+        Image smoothDepth = null;
+        try {
+            try {
+                rawDepth = frame.acquireRawDepthImage16Bits();
+                rawDepthFrame = true;
+            } catch (NotYetAvailableException e) {
+                return DepthSampleResult.failure(
+                        "raw_depth_not_yet_available",
+                        trackingFrame, false, false, false, false, false, false);
+            }
+
+            try {
+                rawConfidence = frame.acquireRawDepthConfidenceImage();
+            } catch (NotYetAvailableException e) {
+                return DepthSampleResult.failure(
+                        "raw_confidence_not_available",
+                        trackingFrame, rawDepthFrame, false, false, false, false, false);
+            }
 
-        try (
-                Image rawDepth = frame.acquireRawDepthImage16Bits();
-                Image rawConfidence = frame.acquireRawDepthConfidenceImage();
-                Image smoothDepth = frame.acquireDepthImage16Bits()) {
+            try {
+                smoothDepth = frame.acquireDepthImage16Bits();
+            } catch (NotYetAvailableException e) {
+                return DepthSampleResult.failure(
+                        "smooth_depth_not_available",
+                        trackingFrame, rawDepthFrame, false, false, false, false, false);
+            }
 
             CameraIntrinsics intrinsics = camera.getImageIntrinsics();
             float[] focal = intrinsics.getFocalLength();
             int[] imageDimensions = intrinsics.getImageDimensions();
             if (focal == null || focal.length < 2 || imageDimensions == null || imageDimensions.length < 2) {
-                return null;
+                return DepthSampleResult.failure(
+                        "image_intrinsics_missing",
+                        trackingFrame, rawDepthFrame, false, false, false, false, false);
             }
 
-            // ARCore documents raw depth, confidence and smoothed depth as the same size.
+            // Keep the 0.1.4 geometry assumptions unchanged; 0.1.5 only makes
+            // failures observable instead of silently returning null.
             if (rawDepth.getWidth() != rawConfidence.getWidth()
                     || rawDepth.getHeight() != rawConfidence.getHeight()
                     || rawDepth.getWidth() != smoothDepth.getWidth()
                     || rawDepth.getHeight() != smoothDepth.getHeight()) {
-                return null;
+                return DepthSampleResult.failure(
+                        "image_size_mismatch",
+                        trackingFrame, rawDepthFrame, false, false, false, false, false);
             }
 
             float[] viewCenter = new float[] { viewWidth / 2f, viewHeight / 2f };
@@ -74,13 +114,19 @@ final class DepthObservationSampler {
 
             int[] mappedCenter = imageToDepth(frame, rawDepth, imageCenter[0], imageCenter[1]);
             if (mappedCenter == null) {
-                return null;
+                return DepthSampleResult.failure(
+                        "image_to_depth_mapping_failed",
+                        trackingFrame, rawDepthFrame, false, false, false, false, false);
             }
+            mappedCenterReached = true;
 
             RawAnchor anchor = findRawAnchor(rawDepth, rawConfidence, mappedCenter[0], mappedCenter[1]);
             if (anchor == null) {
-                return null;
+                return DepthSampleResult.failure(
+                        "no_confident_raw_anchor",
+                        trackingFrame, rawDepthFrame, mappedCenterReached, false, false, false, false);
             }
+            rawAnchorReached = true;
 
             double rawToleranceMm = clamp(anchor.depthMm * 0.10, 100.0, 250.0);
             List<Integer> rawPatch = collectConfidentRawPatch(
@@ -92,13 +138,18 @@ final class DepthObservationSampler {
                     rawToleranceMm,
                     anchor.depthMm);
             if (rawPatch.size() < MIN_RAW_PATCH_SAMPLES) {
-                return null;
+                return DepthSampleResult.failure(
+                        "insufficient_raw_patch_samples",
+                        trackingFrame, rawDepthFrame, mappedCenterReached, rawAnchorReached, false, false, false);
             }
+            rawPatchReached = true;
 
             double centerDepthMm = median(rawPatch);
             double centerMadMm = mad(rawPatch, centerDepthMm);
             if (centerDepthMm < MIN_TARGET_DEPTH_MM || centerDepthMm > MAX_TARGET_DEPTH_MM) {
-                return null;
+                return DepthSampleResult.failure(
+                        "target_depth_out_of_range",
+                        trackingFrame, rawDepthFrame, mappedCenterReached, rawAnchorReached, rawPatchReached, false, false);
             }
 
             // Locate the foreground surface in the smoothed depth image, but only
@@ -111,8 +162,11 @@ final class DepthObservationSampler {
                     centerDepthMm,
                     clamp(centerDepthMm * 0.10, 100.0, 250.0));
             if (centerX < 0) {
-                return null;
+                return DepthSampleResult.failure(
+                        "no_smooth_depth_match",
+                        trackingFrame, rawDepthFrame, mappedCenterReached, rawAnchorReached, rawPatchReached, false, false);
             }
+            smoothDepthMatchReached = true;
 
             double toleranceMm = clamp(centerDepthMm * 0.08, 80.0, 220.0);
             Boundary boundary = findConsensusBoundary(
@@ -122,28 +176,41 @@ final class DepthObservationSampler {
                     centerDepthMm,
                     toleranceMm);
             if (boundary == null || boundary.rightX - boundary.leftX < 3) {
-                return null;
+                return DepthSampleResult.failure(
+                        "boundary_no_consensus",
+                        trackingFrame, rawDepthFrame, mappedCenterReached, rawAnchorReached, rawPatchReached, smoothDepthMatchReached, false);
             }
+            boundaryConsensusReached = true;
 
             int depthWidth = smoothDepth.getWidth();
             int boundaryWidth = boundary.rightX - boundary.leftX;
             if (boundary.leftX <= EDGE_MARGIN_PX
-                    || boundary.rightX >= depthWidth - 1 - EDGE_MARGIN_PX
-                    || boundaryWidth > depthWidth * MAX_TRUNK_WIDTH_FRACTION) {
-                return null;
+                    || boundary.rightX >= depthWidth - 1 - EDGE_MARGIN_PX) {
+                return DepthSampleResult.failure(
+                        "boundary_touches_edge",
+                        trackingFrame, rawDepthFrame, mappedCenterReached, rawAnchorReached, rawPatchReached, smoothDepthMatchReached, boundaryConsensusReached);
+            }
+            if (boundaryWidth > depthWidth * MAX_TRUNK_WIDTH_FRACTION) {
+                return DepthSampleResult.failure(
+                        "boundary_too_wide",
+                        trackingFrame, rawDepthFrame, mappedCenterReached, rawAnchorReached, rawPatchReached, smoothDepthMatchReached, boundaryConsensusReached);
             }
 
             float[] leftImage = depthToImage(frame, smoothDepth, boundary.leftX, anchor.y);
             float[] rightImage = depthToImage(frame, smoothDepth, boundary.rightX, anchor.y);
             if (leftImage == null || rightImage == null) {
-                return null;
+                return DepthSampleResult.failure(
+                        "depth_to_image_mapping_failed",
+                        trackingFrame, rawDepthFrame, mappedCenterReached, rawAnchorReached, rawPatchReached, smoothDepthMatchReached, boundaryConsensusReached);
             }
 
             double dx = rightImage[0] - leftImage[0];
             double dy = rightImage[1] - leftImage[1];
             double imageWidthPx = Math.hypot(dx, dy);
             if (!Double.isFinite(imageWidthPx) || imageWidthPx < 8.0) {
-                return null;
+                return DepthSampleResult.failure(
+                        "image_width_too_small",
+                        trackingFrame, rawDepthFrame, mappedCenterReached, rawAnchorReached, rawPatchReached, smoothDepthMatchReached, boundaryConsensusReached);
             }
 
             double normalizedAngularWidth = Math.sqrt(
@@ -152,7 +219,9 @@ final class DepthObservationSampler {
             if (!Double.isFinite(normalizedAngularWidth)
                     || normalizedAngularWidth <= 0.0
                     || normalizedAngularWidth > 0.95) {
-                return null;
+                return DepthSampleResult.failure(
+                        "angular_width_invalid",
+                        trackingFrame, rawDepthFrame, mappedCenterReached, rawAnchorReached, rawPatchReached, smoothDepthMatchReached, boundaryConsensusReached);
             }
 
             double effectiveFocalPx = imageWidthPx / normalizedAngularWidth;
@@ -178,7 +247,7 @@ final class DepthObservationSampler {
                 boundaryConfidence = "low";
             }
 
-            return new DepthObservation(
+            DepthObservation observation = new DepthObservation(
                     centerDepthMm / 1000.0,
                     effectiveFocalPx,
                     imageWidthPx,
@@ -187,10 +256,21 @@ final class DepthObservationSampler {
                     boundaryConfidence,
                     centerMadMm / 1000.0,
                     System.currentTimeMillis());
-        } catch (NotYetAvailableException e) {
-            return null;
+            return DepthSampleResult.success(observation);
         } catch (Exception e) {
-            return null;
+            return DepthSampleResult.failure(
+                    "unexpected_exception",
+                    trackingFrame,
+                    rawDepthFrame,
+                    mappedCenterReached,
+                    rawAnchorReached,
+                    rawPatchReached,
+                    smoothDepthMatchReached,
+                    boundaryConsensusReached);
+        } finally {
+            if (smoothDepth != null) smoothDepth.close();
+            if (rawConfidence != null) rawConfidence.close();
+            if (rawDepth != null) rawDepth.close();
         }
     }
 

package/android/src/main/java/org/drawdown/arcoredepth/DepthSampleResult.java

@@ -0,0 +1,64 @@
+package org.drawdown.arcoredepth;
+
+/**
+ * One attempted native ARCore sample. A failed sample carries a stable reason
+ * plus milestone flags so the sweep can explain where frames are being lost
+ * without persisting camera/depth frames.
+ */
+final class DepthSampleResult {
+    final DepthObservation observation;
+    final String rejectionReason;
+    final boolean trackingFrame;
+    final boolean rawDepthFrame;
+    final boolean mappedCenter;
+    final boolean rawAnchor;
+    final boolean rawPatch;
+    final boolean smoothDepthMatch;
+    final boolean boundaryConsensus;
+
+    DepthSampleResult(
+            DepthObservation observation,
+            String rejectionReason,
+            boolean trackingFrame,
+            boolean rawDepthFrame,
+            boolean mappedCenter,
+            boolean rawAnchor,
+            boolean rawPatch,
+            boolean smoothDepthMatch,
+            boolean boundaryConsensus) {
+        this.observation = observation;
+        this.rejectionReason = rejectionReason;
+        this.trackingFrame = trackingFrame;
+        this.rawDepthFrame = rawDepthFrame;
+        this.mappedCenter = mappedCenter;
+        this.rawAnchor = rawAnchor;
+        this.rawPatch = rawPatch;
+        this.smoothDepthMatch = smoothDepthMatch;
+        this.boundaryConsensus = boundaryConsensus;
+    }
+
+    static DepthSampleResult failure(
+            String reason,
+            boolean trackingFrame,
+            boolean rawDepthFrame,
+            boolean mappedCenter,
+            boolean rawAnchor,
+            boolean rawPatch,
+            boolean smoothDepthMatch,
+            boolean boundaryConsensus) {
+        return new DepthSampleResult(
+                null,
+                reason,
+                trackingFrame,
+                rawDepthFrame,
+                mappedCenter,
+                rawAnchor,
+                rawPatch,
+                smoothDepthMatch,
+                boundaryConsensus);
+    }
+
+    static DepthSampleResult success(DepthObservation observation) {
+        return new DepthSampleResult(observation, null, true, true, true, true, true, true, true);
+    }
+}

package/android/src/main/java/org/drawdown/arcoredepth/DrawDownArCoreDepthPlugin.java

@@ -36,7 +36,9 @@ import com.google.ar.core.exceptions.UnavailableUserDeclinedInstallationExceptio
 import android.opengl.GLSurfaceView;
 
 import java.util.ArrayList;
+import java.util.LinkedHashMap;
 import java.util.List;
+import java.util.Map;
 
 @CapacitorPlugin(
         name = "DrawDownArCoreDepth",
@@ -44,7 +46,8 @@ import java.util.List;
                 @Permission(alias = "camera", strings = { Manifest.permission.CAMERA })
         })
 public class DrawDownArCoreDepthPlugin extends Plugin {
-    private static final String PLUGIN_VERSION = "0.1.4";
+    private static final String PLUGIN_VERSION = "0.1.5";
+    private static final String METHOD_VERSION = "arcore-raw-depth-cylinder-v4-diagnostics";
     private static final long WARMUP_MS = 1200L;
 
     private final Handler mainHandler = new Handler(Looper.getMainLooper());
@@ -68,6 +71,15 @@ public class DrawDownArCoreDepthPlugin extends Plugin {
     private int maxObservations = 10;
     private int minObservations = 5;
     private final List<DepthObservation> sweepObservations = new ArrayList<>();
+    private final Map<String, Integer> sweepRejectionCounts = new LinkedHashMap<>();
+    private int totalFrameCount = 0;
+    private int trackingFrameCount = 0;
+    private int rawDepthFrameCount = 0;
+    private int mappedCenterCount = 0;
+    private int rawAnchorCount = 0;
+    private int rawPatchCount = 0;
+    private int smoothDepthMatchCount = 0;
+    private int boundaryConsensusCount = 0;
 
     @PluginMethod
     public void checkSupport(PluginCall call) {
@@ -251,6 +263,15 @@ public class DrawDownArCoreDepthPlugin extends Plugin {
 
             pendingSweepCall = call;
             sweepObservations.clear();
+            sweepRejectionCounts.clear();
+            totalFrameCount = 0;
+            trackingFrameCount = 0;
+            rawDepthFrameCount = 0;
+            mappedCenterCount = 0;
+            rawAnchorCount = 0;
+            rawPatchCount = 0;
+            smoothDepthMatchCount = 0;
+            boundaryConsensusCount = 0;
             minObservations = requestedMin;
             maxObservations = requestedMax;
             sampleIntervalMs = Math.max(100L, durationMs / Math.max(1, requestedMax * 2));
@@ -372,32 +393,61 @@ public class DrawDownArCoreDepthPlugin extends Plugin {
 
         try {
             Camera camera = frame.getCamera();
-            DepthObservation observation = sampler.sample(frame, camera, viewWidth, viewHeight);
-            if (observation == null) {
-                return;
-            }
+            DepthSampleResult sampleResult = sampler.sample(frame, camera, viewWidth, viewHeight);
 
             boolean reachedMax = false;
             synchronized (sweepLock) {
                 if (!sweepActive || pendingSweepCall == null) {
                     return;
                 }
-                sweepObservations.add(observation);
-                reachedMax = sweepObservations.size() >= maxObservations;
+                totalFrameCount += 1;
+                if (sampleResult.trackingFrame) trackingFrameCount += 1;
+                if (sampleResult.rawDepthFrame) rawDepthFrameCount += 1;
+                if (sampleResult.mappedCenter) mappedCenterCount += 1;
+                if (sampleResult.rawAnchor) rawAnchorCount += 1;
+                if (sampleResult.rawPatch) rawPatchCount += 1;
+                if (sampleResult.smoothDepthMatch) smoothDepthMatchCount += 1;
+                if (sampleResult.boundaryConsensus) boundaryConsensusCount += 1;
+
+                if (sampleResult.rejectionReason != null) {
+                    int current = sweepRejectionCounts.containsKey(sampleResult.rejectionReason)
+                            ? sweepRejectionCounts.get(sampleResult.rejectionReason)
+                            : 0;
+                    sweepRejectionCounts.put(sampleResult.rejectionReason, current + 1);
+                }
+
+                if (sampleResult.observation != null) {
+                    sweepObservations.add(sampleResult.observation);
+                    reachedMax = sweepObservations.size() >= maxObservations;
+                }
             }
 
             if (reachedMax) {
                 mainHandler.post(() -> finishSweep(false));
             }
         } catch (Exception ignored) {
-            // Invalid frames are simply skipped; the app's aggregate QA rejects
-            // a sweep with too few valid observations.
+            synchronized (sweepLock) {
+                totalFrameCount += 1;
+                int current = sweepRejectionCounts.containsKey("unexpected_exception")
+                        ? sweepRejectionCounts.get("unexpected_exception")
+                        : 0;
+                sweepRejectionCounts.put("unexpected_exception", current + 1);
+            }
         }
     }
 
     private void finishSweep(boolean stoppedByCaller) {
         PluginCall sweepCall;
         List<DepthObservation> observations;
+        Map<String, Integer> rejectionCounts;
+        int framesTotal;
+        int framesTracking;
+        int framesRawDepth;
+        int centersMapped;
+        int anchorsRaw;
+        int patchesRaw;
+        int matchesSmooth;
+        int boundariesConsensus;
         synchronized (sweepLock) {
             sweepCall = pendingSweepCall;
             if (sweepCall == null) {
@@ -407,7 +457,17 @@ public class DrawDownArCoreDepthPlugin extends Plugin {
             pendingSweepCall = null;
             sweepActive = false;
             observations = new ArrayList<>(sweepObservations);
+            rejectionCounts = new LinkedHashMap<>(sweepRejectionCounts);
+            framesTotal = totalFrameCount;
+            framesTracking = trackingFrameCount;
+            framesRawDepth = rawDepthFrameCount;
+            centersMapped = mappedCenterCount;
+            anchorsRaw = rawAnchorCount;
+            patchesRaw = rawPatchCount;
+            matchesSmooth = smoothDepthMatchCount;
+            boundariesConsensus = boundaryConsensusCount;
             sweepObservations.clear();
+            sweepRejectionCounts.clear();
         }
 
         JSArray observationArray = new JSArray();
@@ -415,12 +475,29 @@ public class DrawDownArCoreDepthPlugin extends Plugin {
             observationArray.put(observation.toJsObject());
         }
 
+        JSObject rejectionObject = new JSObject();
+        for (Map.Entry<String, Integer> entry : rejectionCounts.entrySet()) {
+            rejectionObject.put(entry.getKey(), entry.getValue());
+        }
+
         JSObject result = new JSObject();
         result.put("observations", observationArray);
         result.put("deviceModel", Build.MANUFACTURER + " " + Build.MODEL);
         result.put("arcoreVersion", installedArcoreVersion());
+        result.put("pluginVersion", PLUGIN_VERSION);
+        result.put("methodVersion", METHOD_VERSION);
         result.put("minimumRequested", minObservations);
         result.put("stoppedByCaller", stoppedByCaller);
+        result.put("totalFrameCount", framesTotal);
+        result.put("trackingFrameCount", framesTracking);
+        result.put("rawDepthFrameCount", framesRawDepth);
+        result.put("mappedCenterCount", centersMapped);
+        result.put("rawAnchorCount", anchorsRaw);
+        result.put("rawPatchCount", patchesRaw);
+        result.put("smoothDepthMatchCount", matchesSmooth);
+        result.put("boundaryConsensusCount", boundariesConsensus);
+        result.put("nativeValidObservationCount", observations.size());
+        result.put("nativeRejectionCounts", rejectionObject);
         sweepCall.resolve(result);
 
         if (!stoppedByCaller) {

package/dist/esm/definitions.d.ts

@@ -44,6 +44,18 @@ export interface CaptureDbhSweepResult {
     observations: DbhObservation[];
     deviceModel?: string;
     arcoreVersion?: string;
+    pluginVersion?: string;
+    methodVersion?: string;
+    totalFrameCount?: number;
+    trackingFrameCount?: number;
+    rawDepthFrameCount?: number;
+    mappedCenterCount?: number;
+    rawAnchorCount?: number;
+    rawPatchCount?: number;
+    smoothDepthMatchCount?: number;
+    boundaryConsensusCount?: number;
+    nativeValidObservationCount?: number;
+    nativeRejectionCounts?: Record<string, number>;
 }
 export interface DrawDownArCoreDepthPlugin {
     checkSupport(): Promise<SupportResult>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "drawdown-arcore-depth",
-  "version": "0.1.4",
-  "description": "Small Android-only Capacitor 8 bridge for ARCore Depth DBH observations.",
+  "version": "0.1.5",
+  "description": "Small Android-only Capacitor 8 bridge for ARCore Raw Depth DBH observations with native sweep diagnostics.",
   "main": "dist/plugin.cjs.js",
   "module": "dist/esm/index.js",
   "types": "dist/esm/index.d.ts",