andrewmahar-drawdown-arcore-depth

Version 0.1.11 responds to the 11 September 2026 Oakleigh Forest field tests on a Samsung S24. Those tests showed that the timed sweep and Raw Depth stream were working, but the trunk often appeared at confidence below the existing 64/255 anchor threshold while distant background pixels could carry higher confidence. 0.1.11 therefore keeps confidence >=64 as the normal path, adds a conservative confidence >=32 candidate-only foreground path, and promotes those weaker candidates only when the same foreground depth band persists across a strict multi-frame temporal cluster. Manual tape DBH remains authoritative; ARCore remains experimental QC only.

Android-only Capacitor 8 bridge for the DrawDown experimental ARCore DBH quality-control workflow.

Purpose

The plugin exposes local ARCore Depth measurements to a Capacitor app without requiring cloud services, video storage, LiDAR, Cloud Anchors, Geospatial APIs, or server-side inference.

It is deliberately narrow. During a short DBH sweep it:

1. opens a native ARCore camera preview;
2. enables Config.DepthMode.AUTOMATIC;
3. uses the RFID/NFC tag only to identify the 1.3 m DBH plane;
4. shows HOLD/READY tracking guidance while the inspector positions the phone at the left edge of the trunk, without disabling Start Sweep;
5. starts both the Raw Depth capture and a visible 5-second countdown when the inspector taps Start Sweep;
6. provides a visible Cancel control and back-key escape path from the native overlay;
7. samples the left-to-right sweep and first uses normal Raw Depth anchors at confidence >=64;
8. when no such foreground anchor exists, allows confidence 32–63 points to become candidates only;
9. promotes weaker candidates only when at least five depth-consistent observations persist over >=700 ms with a near-consecutive run of at least four sampled frames and <=0.08 m depth MAD;
10. estimates left/right trunk boundaries and combines camera intrinsics with apparent width to return compact DBH observations;
11. discards all intermediate frames.

The plugin does not calculate carbon and does not replace the forestry diameter tape. In DrawDown, manualDbhCm remains authoritative; the ARCore result is experimental QC evidence only.

Capacitor contract

The native plugin registers as:

DrawDownArCoreDepth

Methods:

checkSupport(): Promise<{
  isSupported: boolean;
  hasDepthApi: boolean;
  pluginVersion?: string;
  message?: string;
}>

startDbhSession({
  anchorType: 'rfid_tag',
  targetHeightM: 1.3,
}): Promise<{ started: boolean }>

captureDbhSweep({
  durationMs: 5000,
  minObservations: 5,
  maxObservations: 10,
  retainFrames: false,
}): Promise<{
  observations: Array<{
    frontSurfaceDepthM: number;
    focalLengthXPx: number;
    trunkWidthPx: number;
    rangeSource: 'arcore_raw_depth' | 'arcore_depth16';
    trackingConfidence?: number;
    boundaryConfidence?: 'high' | 'medium' | 'low';
    boundarySource?: 'raw_depth' | 'smooth_depth';
    depthMadM?: number;
    rawAnchorConfidence?: number;
    weakForegroundCandidate?: boolean;
    temporallyPromoted?: boolean;
    timestampMs?: number;
  }>;
  deviceModel?: string;
  arcoreVersion?: string;
  pluginVersion?: string;
  methodVersion?: string;
  inspectorStartedSweep?: boolean;
  sweepDurationMs?: number;
  rawBoundaryCount?: number;
  trackingReadyHoldMs?: number;
  trackingReadyAtSweepStart?: boolean;
  temporalForegroundCluster?: {
    weakCandidateObservationCount?: number;
    temporallyPromotedWeakCount?: number;
    longestConsecutiveFrameRun?: number;
    foregroundClusterRawAnchorConfidenceMedian?: number;
  };
}>

stopDbhSession(): Promise<void>

This matches the DrawDownArCoreDepth adapter already prepared in DrawDown.

Installation

From a local tarball:

npm install ./andrewmahar-drawdown-arcore-depth-0.1.12.tgz
npx cap sync android

Or, after publishing the package to a registry:

npm install andrewmahar-drawdown-arcore-depth
npx cap sync android

Then import it if direct typed access is wanted:

import { DrawDownArCoreDepth } from 'andrewmahar-drawdown-arcore-depth';

The current DrawDown adapter can also resolve the registered native plugin by its Capacitor name.

Android requirements

• Capacitor 8
• Android min SDK 24+
• ARCore-supported Android device
• device support for the ARCore Depth API
• Google Play Services for AR installed and current
• camera permission

The plugin declares ARCore and ARCore Depth as optional features so the wider DrawDown app can still install on unsupported devices. The app must runtime-gate the experimental DBH feature with checkSupport().

Offline behaviour

The measurement path is local:

ARCore camera
  -> local depth map
  -> local boundary sampling
  -> compact numeric observations
  -> DrawDown on-device DBH aggregation
  -> offline sync queue

No internet connection is required for the sweep itself.

Storage behaviour

retainFrames: true is rejected by design.

The plugin retains no sweep video and no routine RGB/depth frames. Only compact numeric observations are returned to DrawDown. DrawDown can continue to retain its normal single inspection photograph separately.

Measurement geometry

The plugin returns:

• front-surface z-depth to the trunk around the crosshair;
• apparent trunk width in CPU-image pixels;
• an effective focal length along the actual measured width axis.

The DrawDown application then applies the existing GreenLens-style tangent/cylinder correction rather than treating the trunk as a flat plane.

V0.1 boundary method

This first field-test version intentionally avoids a heavy native OpenCV or neural-network dependency.

The inspector centres the tag on the crosshair. The plugin samples the local dense depth surface and walks left/right until the depth leaves the trunk-depth band. It scores boundary confidence from edge depth jumps, patch completeness, and depth MAD.

This is suitable for a controlled validation pilot against diameter tape. It is not yet an audit-grade claim. The purpose of the pilot is to quantify bias, MAE/RMSE, failure rates, device effects, and performance by DBH class before deciding whether to add RGB segmentation or a multi-view 3-D fit.

Field validation recommendation

For each test tree, retain:

• authoritative tape DBH;
• ARCore QC DBH;
• disagreement percentage;
• phone model and ARCore version;
• observation count and MAD;
• existing DrawDown inspection photo.

Test across tree size classes, bark types, light conditions, species, and several ARCore Depth-capable Android devices.

ARCore version

The Android library is currently pinned to:

implementation 'com.google.ar:core:1.54.0'

Review this pin deliberately rather than silently floating to a newer version, because measurement software should record and validate changes in the sensing stack.

Privacy / ARCore notice

Apps using ARCore need to comply with Google's ARCore user-privacy requirements. See NOTICE.md and Google's current ARCore documentation before production distribution.

License

MIT for this plugin source. Google ARCore itself is subject to Google's ARCore terms.

DrawDown field anchor (v0.1.2)

No ArUco marker is required by the native ARCore workflow. The existing RFID/NFC tree tag identifies the 1.3 m DBH plane. For the depth sweep, place the crosshair on exposed bark immediately beside the tag at the same height so the tag itself does not influence the depth boundary. Manual diameter tape remains authoritative.

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.6 diagnostic sweep

Version 0.1.6 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.

0.1.6 Raw Depth anchor diagnostics

0.1.6 keeps the 0.1.5 DBH acceptance algorithm unchanged and adds compact numeric diagnostics around the mapped crosshair at 10, 20 and 30 pixel radii. It reports non-zero/in-range Raw Depth counts, confidence threshold counts (64/96/128/160), the highest confidence in the eligible 0.5–5 m range and the associated depth. These diagnostics do not influence the accepted DBH result.

0.1.8 inspector-started sweep timer

0.1.8 deliberately keeps the 0.1.7 Raw Depth threshold, cylindrical geometry, boundary sampling and temporal foreground-cluster selection unchanged. The field-process change is isolated:

1. ARCore opens and starts tracking.
2. The inspector positions the phone about 1–1.5 m from the tree at the RFID-defined 1.3 m height, beginning at the left edge of the trunk.
3. After a short camera/depth readiness delay, the native Start Sweep button becomes active.
4. The inspector taps Start Sweep when ready.
5. The Raw Depth capture window starts immediately from that tap.
6. A large native countdown shows the remaining time from 5.0 s to 0.0 s at 0.1-second resolution.
7. The inspector moves left → right across the full trunk and aims to reach the right edge as the timer reaches zero.
8. Temporal-cluster analysis runs only after the full timed window completes.

The result records inspectorStartedSweep: true and sweepDurationMs: 5000 as compact provenance.

0.1.10 unblocked Start Sweep and exit controls

0.1.10 fixed the 0.1.9 field deadlock:

1. Start Sweep is always available once the native ARCore camera is open.
2. HOLD/READY remains visible tracking guidance but is not a hard gate.
3. The plugin records trackingReadyAtSweepStart for diagnosis.
4. The inspector-started 5.0 s countdown and left-to-right capture remain unchanged.
5. A visible Cancel control and Android back-key exit path allow the inspector to leave the native overlay safely.
6. The direct Raw Depth boundary method introduced in 0.1.9 remains unchanged.

0.1.11 temporal promotion of weak foreground candidates

The Oakleigh Forest 0.1.10 tests showed four complete 5-second sweeps with 24–31 Raw Depth frames out of 38 sampled frames, but zero accepted Raw Depth anchors. One test saw a plausible foreground depth around 0.9 m with confidence in the 30s, while stronger confidence could occur on distant background.

0.1.11 changes only foreground candidate selection and the evidence needed to promote it:

1. The existing confidence >=64 anchor path remains the preferred path.
2. If no >=64 anchor exists in the 0.7–2.5 m target range, confidence >=32 points may become weak foreground candidates.
3. Weak candidates use the same depth patch, multi-row Raw Depth boundary, width and spread guards, but at the candidate threshold so the trunk can reach temporal analysis.
4. A weak candidate is never accepted on the strength of one frame. A cluster containing weak candidates must contain at least 5 depth-consistent observations, span at least 700 ms, achieve a near-consecutive run of at least 4 sampled frames (allowing a one-frame miss), and keep depth MAD <= 0.08 m.
5. Only weak observations inside that accepted temporal cluster are marked temporallyPromoted: true. Their original rawAnchorConfidence and Raw Depth-derived confidence are retained; they are not inflated.
6. Direct Raw Depth boundaries remain capped below HIGH confidence until field validation.
7. Diagnostics now add confidence >=32 counts plus weak-candidate/promotion counts and longest consecutive run.
8. The 5-second manual Start Sweep, HOLD/READY guidance, Cancel/Back exit, no-frame-retention rule, and manual-tape authority are unchanged.

The DrawDown application should treat temporally promoted weak observations as low-confidence QC evidence only. They must never enter the authoritative DBH/AGB/carbon priority chain.