drawdown-arcore-depth

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. asks the inspector to align the 1.3 m DrawDown tag with a centre crosshair;
4. acquires ARCore 16-bit depth frames locally;
5. finds the contiguous depth surface around the crosshair and estimates left/right trunk boundaries from the depth discontinuity;
6. converts those boundaries back into CPU image coordinates using ARCore coordinate transforms;
7. combines camera intrinsics with the apparent width to return compact DBH observations;
8. 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({
  tagDictionary: 'DICT_6X6_250',
  tagId: 0,
  tagSizeCm: 10,
  targetHeightM: 1.3,
}): Promise<{ started: boolean }>

captureDbhSweep({
  durationMs: 3000,
  minObservations: 5,
  maxObservations: 10,
  retainFrames: false,
}): Promise<{
  observations: Array<{
    frontSurfaceDepthM: number;
    focalLengthXPx: number;
    trunkWidthPx: number;
    rangeSource: 'arcore_depth16';
    trackingConfidence?: number;
    boundaryConfidence?: 'high' | 'medium' | 'low';
    depthMadM?: number;
    timestampMs?: number;
  }>;
  deviceModel?: string;
  arcoreVersion?: string;
}>

stopDbhSession(): Promise<void>

This matches the DrawDownArCoreDepth adapter already prepared in DrawDown.

Installation

From a local tarball:

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

Or, after publishing the package to a registry:

npm install drawdown-arcore-depth
npx cap sync android

Then import it if direct typed access is wanted:

import { DrawDownArCoreDepth } from '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.