drawdown-arcore-depth 0.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DrawDown
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE.md

@@ -0,0 +1,7 @@
+# Notices
+
+This plugin depends on Google ARCore (`com.google.ar:core`). Use of ARCore is subject to Google's ARCore Additional Terms of Service and user-privacy requirements.
+
+The plugin does not use Cloud Anchors, Geospatial APIs, VPS, or any network-based AR service. Its DBH sweep uses the local ARCore Depth API and transient in-memory processing.
+
+ARCore depth is an experimental QC input for DrawDown. It must not replace the authoritative forestry diameter-tape measurement unless a future validation and methodology decision explicitly changes that policy.

package/README.md

@@ -0,0 +1,190 @@
+# 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:
+
+```ts
+DrawDownArCoreDepth
+```
+
+Methods:
+
+```ts
+checkSupport(): Promise<{
+  isSupported: boolean;
+  hasDepthApi: boolean;
+  pluginVersion?: string;
+  message?: string;
+}>
+```
+
+```ts
+startDbhSession({
+  tagDictionary: 'DICT_6X6_250',
+  tagId: 0,
+  tagSizeCm: 10,
+  targetHeightM: 1.3,
+}): Promise<{ started: boolean }>
+```
+
+```ts
+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;
+}>
+```
+
+```ts
+stopDbhSession(): Promise<void>
+```
+
+This matches the `DrawDownArCoreDepth` adapter already prepared in DrawDown.
+
+## Installation
+
+From a local tarball:
+
+```bash
+npm install ./drawdown-arcore-depth-0.1.1.tgz
+npx cap sync android
+```
+
+Or, after publishing the package to a registry:
+
+```bash
+npm install drawdown-arcore-depth
+npx cap sync android
+```
+
+Then import it if direct typed access is wanted:
+
+```ts
+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:
+
+```text
+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:
+
+```gradle
+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.

package/android/build.gradle

@@ -0,0 +1,42 @@
+ext {
+    junitVersion = project.hasProperty('junitVersion') ? rootProject.ext.junitVersion : '4.13.2'
+    androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.7.0'
+}
+
+buildscript {
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath 'com.android.tools.build:gradle:8.13.0'
+    }
+}
+
+apply plugin: 'com.android.library'
+
+android {
+    namespace 'org.drawdown.arcoredepth'
+    compileSdk project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 36
+
+    defaultConfig {
+        minSdk project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 24
+        consumerProguardFiles 'consumer-rules.pro'
+    }
+
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_21
+        targetCompatibility JavaVersion.VERSION_21
+    }
+}
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+dependencies {
+    implementation project(':capacitor-android')
+    implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
+    implementation 'com.google.ar:core:1.54.0'
+}

package/android/consumer-rules.pro

@@ -0,0 +1 @@
+# No reflection-based plugin classes beyond Capacitor's normal discovery.

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,11 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <uses-permission android:name="android.permission.CAMERA" />
+
+    <!-- AR is optional for the overall DrawDown app; the plugin checks at runtime. -->
+    <uses-feature android:name="android.hardware.camera.ar" android:required="false" />
+    <uses-feature android:name="com.google.ar.core.depth" android:required="false" />
+
+    <application>
+        <meta-data android:name="com.google.ar.core" android:value="optional" />
+    </application>
+</manifest>

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

@@ -0,0 +1,202 @@
+package org.drawdown.arcoredepth;
+
+import android.opengl.GLES11Ext;
+import android.opengl.GLES20;
+import android.opengl.GLSurfaceView;
+import android.view.Display;
+
+import com.google.ar.core.Coordinates2d;
+import com.google.ar.core.Frame;
+import com.google.ar.core.Session;
+
+import java.nio.ByteBuffer;
+import java.nio.ByteOrder;
+import java.nio.FloatBuffer;
+
+import javax.microedition.khronos.egl.EGLConfig;
+import javax.microedition.khronos.opengles.GL10;
+
+final class ArCameraRenderer implements GLSurfaceView.Renderer {
+    interface Callback {
+        void onRendererReady(int textureId);
+        void onFrame(Frame frame, int viewWidth, int viewHeight);
+        int getDisplayRotation();
+    }
+
+    private static final String VERTEX_SHADER =
+            "attribute vec4 aPosition;\n" +
+            "attribute vec2 aTexCoord;\n" +
+            "varying vec2 vTexCoord;\n" +
+            "void main() { gl_Position = aPosition; vTexCoord = aTexCoord; }";
+
+    private static final String FRAGMENT_SHADER =
+            "#extension GL_OES_EGL_image_external : require\n" +
+            "precision mediump float;\n" +
+            "varying vec2 vTexCoord;\n" +
+            "uniform samplerExternalOES uTexture;\n" +
+            "void main() { gl_FragColor = texture2D(uTexture, vTexCoord); }";
+
+    private final Session session;
+    private final Callback callback;
+
+    private final FloatBuffer positions;
+    private final FloatBuffer inputUv;
+    private final FloatBuffer transformedUv;
+
+    private int textureId = -1;
+    private int program = -1;
+    private int viewWidth = 1;
+    private int viewHeight = 1;
+
+    ArCameraRenderer(Session session, Callback callback) {
+        this.session = session;
+        this.callback = callback;
+
+        positions = directFloatBuffer(new float[] {
+                -1f, -1f,
+                 1f, -1f,
+                -1f,  1f,
+                 1f,  1f
+        });
+        inputUv = directFloatBuffer(new float[] {
+                0f, 1f,
+                1f, 1f,
+                0f, 0f,
+                1f, 0f
+        });
+        transformedUv = ByteBuffer.allocateDirect(8 * 4)
+                .order(ByteOrder.nativeOrder())
+                .asFloatBuffer();
+    }
+
+    @Override
+    public void onSurfaceCreated(GL10 gl, EGLConfig config) {
+        int[] textures = new int[1];
+        GLES20.glGenTextures(1, textures, 0);
+        textureId = textures[0];
+        GLES20.glBindTexture(GLES11Ext.GL_TEXTURE_EXTERNAL_OES, textureId);
+        GLES20.glTexParameteri(GLES11Ext.GL_TEXTURE_EXTERNAL_OES, GLES20.GL_TEXTURE_MIN_FILTER, GLES20.GL_LINEAR);
+        GLES20.glTexParameteri(GLES11Ext.GL_TEXTURE_EXTERNAL_OES, GLES20.GL_TEXTURE_MAG_FILTER, GLES20.GL_LINEAR);
+        GLES20.glTexParameteri(GLES11Ext.GL_TEXTURE_EXTERNAL_OES, GLES20.GL_TEXTURE_WRAP_S, GLES20.GL_CLAMP_TO_EDGE);
+        GLES20.glTexParameteri(GLES11Ext.GL_TEXTURE_EXTERNAL_OES, GLES20.GL_TEXTURE_WRAP_T, GLES20.GL_CLAMP_TO_EDGE);
+
+        program = createProgram(VERTEX_SHADER, FRAGMENT_SHADER);
+        session.setCameraTextureName(textureId);
+        callback.onRendererReady(textureId);
+    }
+
+    @Override
+    public void onSurfaceChanged(GL10 gl, int width, int height) {
+        viewWidth = Math.max(1, width);
+        viewHeight = Math.max(1, height);
+        GLES20.glViewport(0, 0, viewWidth, viewHeight);
+        session.setDisplayGeometry(callback.getDisplayRotation(), viewWidth, viewHeight);
+    }
+
+    @Override
+    public void onDrawFrame(GL10 gl) {
+        GLES20.glClear(GLES20.GL_COLOR_BUFFER_BIT | GLES20.GL_DEPTH_BUFFER_BIT);
+        try {
+            session.setCameraTextureName(textureId);
+            session.setDisplayGeometry(callback.getDisplayRotation(), viewWidth, viewHeight);
+            Frame frame = session.update();
+            updateUv(frame);
+            drawCamera();
+            callback.onFrame(frame, viewWidth, viewHeight);
+        } catch (Exception ignored) {
+            // Session lifecycle transitions can briefly make update unavailable.
+        }
+    }
+
+    private void updateUv(Frame frame) {
+        try {
+            inputUv.position(0);
+            transformedUv.position(0);
+            frame.transformCoordinates2d(
+                    Coordinates2d.VIEW_NORMALIZED,
+                    inputUv,
+                    Coordinates2d.TEXTURE_NORMALIZED,
+                    transformedUv);
+            transformedUv.position(0);
+        } catch (Exception e) {
+            transformedUv.position(0);
+            transformedUv.put(new float[] {
+                    0f, 1f,
+                    1f, 1f,
+                    0f, 0f,
+                    1f, 0f
+            });
+            transformedUv.position(0);
+        }
+    }
+
+    private void drawCamera() {
+        if (program <= 0 || textureId <= 0) {
+            return;
+        }
+        GLES20.glDisable(GLES20.GL_DEPTH_TEST);
+        GLES20.glUseProgram(program);
+
+        int posLocation = GLES20.glGetAttribLocation(program, "aPosition");
+        int uvLocation = GLES20.glGetAttribLocation(program, "aTexCoord");
+        int textureLocation = GLES20.glGetUniformLocation(program, "uTexture");
+
+        positions.position(0);
+        transformedUv.position(0);
+        GLES20.glEnableVertexAttribArray(posLocation);
+        GLES20.glVertexAttribPointer(posLocation, 2, GLES20.GL_FLOAT, false, 0, positions);
+        GLES20.glEnableVertexAttribArray(uvLocation);
+        GLES20.glVertexAttribPointer(uvLocation, 2, GLES20.GL_FLOAT, false, 0, transformedUv);
+
+        GLES20.glActiveTexture(GLES20.GL_TEXTURE0);
+        GLES20.glBindTexture(GLES11Ext.GL_TEXTURE_EXTERNAL_OES, textureId);
+        GLES20.glUniform1i(textureLocation, 0);
+        GLES20.glDrawArrays(GLES20.GL_TRIANGLE_STRIP, 0, 4);
+
+        GLES20.glDisableVertexAttribArray(posLocation);
+        GLES20.glDisableVertexAttribArray(uvLocation);
+    }
+
+    private static FloatBuffer directFloatBuffer(float[] values) {
+        FloatBuffer buffer = ByteBuffer.allocateDirect(values.length * 4)
+                .order(ByteOrder.nativeOrder())
+                .asFloatBuffer();
+        buffer.put(values);
+        buffer.position(0);
+        return buffer;
+    }
+
+    private static int createProgram(String vertexSource, String fragmentSource) {
+        int vertex = compileShader(GLES20.GL_VERTEX_SHADER, vertexSource);
+        int fragment = compileShader(GLES20.GL_FRAGMENT_SHADER, fragmentSource);
+        if (vertex == 0 || fragment == 0) {
+            return 0;
+        }
+        int program = GLES20.glCreateProgram();
+        GLES20.glAttachShader(program, vertex);
+        GLES20.glAttachShader(program, fragment);
+        GLES20.glLinkProgram(program);
+        int[] linked = new int[1];
+        GLES20.glGetProgramiv(program, GLES20.GL_LINK_STATUS, linked, 0);
+        GLES20.glDeleteShader(vertex);
+        GLES20.glDeleteShader(fragment);
+        if (linked[0] == 0) {
+            GLES20.glDeleteProgram(program);
+            return 0;
+        }
+        return program;
+    }
+
+    private static int compileShader(int type, String source) {
+        int shader = GLES20.glCreateShader(type);
+        GLES20.glShaderSource(shader, source);
+        GLES20.glCompileShader(shader);
+        int[] compiled = new int[1];
+        GLES20.glGetShaderiv(shader, GLES20.GL_COMPILE_STATUS, compiled, 0);
+        if (compiled[0] == 0) {
+            GLES20.glDeleteShader(shader);
+            return 0;
+        }
+        return shader;
+    }
+}

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

@@ -0,0 +1,46 @@
+package org.drawdown.arcoredepth;
+
+import com.getcapacitor.JSObject;
+
+final class DepthObservation {
+    final double frontSurfaceDepthM;
+    final double effectiveFocalLengthPx;
+    final double trunkWidthPx;
+    final String rangeSource;
+    final double trackingConfidence;
+    final String boundaryConfidence;
+    final double depthMadM;
+    final long timestampMs;
+
+    DepthObservation(
+            double frontSurfaceDepthM,
+            double effectiveFocalLengthPx,
+            double trunkWidthPx,
+            String rangeSource,
+            double trackingConfidence,
+            String boundaryConfidence,
+            double depthMadM,
+            long timestampMs) {
+        this.frontSurfaceDepthM = frontSurfaceDepthM;
+        this.effectiveFocalLengthPx = effectiveFocalLengthPx;
+        this.trunkWidthPx = trunkWidthPx;
+        this.rangeSource = rangeSource;
+        this.trackingConfidence = trackingConfidence;
+        this.boundaryConfidence = boundaryConfidence;
+        this.depthMadM = depthMadM;
+        this.timestampMs = timestampMs;
+    }
+
+    JSObject toJsObject() {
+        JSObject out = new JSObject();
+        out.put("frontSurfaceDepthM", frontSurfaceDepthM);
+        out.put("focalLengthXPx", effectiveFocalLengthPx);
+        out.put("trunkWidthPx", trunkWidthPx);
+        out.put("rangeSource", rangeSource);
+        out.put("trackingConfidence", trackingConfidence);
+        out.put("boundaryConfidence", boundaryConfidence);
+        out.put("depthMadM", depthMadM);
+        out.put("timestampMs", timestampMs);
+        return out;
+    }
+}