React Native

Dimensioning (React Native)

This guide documents the React Native surface for the Vision SDK's 3D box dimensioning feature. It covers integration, usage, gating, modes, troubleshooting, known limitations, and links to source files.

Contents

• Quick overview
• Installation & permissions
• Device capability gating
• VisionDimensioning helpers
• DimensioningView component API and examples
• Modes, model prefetching, and team-id requirements
• Telemetry & privacy
• Troubleshooting
• Source references

# Quick overview

• Dimensioning provides approximate length × width × height measurements for detected boxes using ARKit + LiDAR and optional segmentation refinement (YOLO + SAM2).
• The React Native package exposes:
  • DimensioningView — native view component that emits onCapture and onError (iOS only).
  • VisionDimensioning.deviceCapabilities() — inspect device support.
  • VisionDimensioning.prefetchModels() — warm CoreML models used by the segmentation pipeline.

Always gate UI with deviceCapabilities() to avoid mounting the native view on unsupported devices.

# Installation

Dimensioning ships with react-native-vision-sdk.

        npm install react-native-vision-sdk
# or
yarn add react-native-vision-sdk

      

No additional RN packages are required, but ensure your iOS build has the Vision SDK dimensioning subspec available (see native integration notes in the SDK docs).

# Info.plist

Add camera and LiDAR usage descriptions to Info.plist:

        <key>NSCameraUsageDescription</key>
<string>Camera access is required to measure package dimensions.</string>
<key>Privacy - LiDAR Usage Description</key>
<string>LiDAR access is required for accurate 3D measurement.</string>

      

No extra ARKit permission keys are required beyond these usage descriptions.

# Device capability gating

Dimensioning only runs usefully on LiDAR-equipped iOS devices. Use the capability helper to gate rendering:

        import { VisionDimensioning } from 'react-native-vision-sdk';

async function canUseDimensioning() {
  const caps = await VisionDimensioning.deviceCapabilities();
  return caps.lidar && caps.arWorldTracking;
}

      

On simulator and unsupported Android devices the helper returns all-false flags; the native view will either emit an error (LidarUnavailable) or render a placeholder.

# VisionDimensioning helpers

• deviceCapabilities(): Promise<DimensioningCapabilities> — returns { lidar: boolean, arWorldTracking: boolean, sceneReconstruction: boolean }.
• prefetchModels(): Promise<void> — idempotent warm-up for bundled CoreML models.

Usage tips:

• Call prefetchModels() once on app startup (after configuring your API key if you plan to use mode="online").
• deviceCapabilities() is safe to call cross-platform (stubbed on Android).

# DimensioningView component

Location: react-native-vision-sdk (DimensioningView implementation)

Props summary:

• mode?: 'offline' | 'online' — processing mode (default: 'offline').
• measurementUnit?: string — requested unit; currently the React Native wrapper returns captures in centimeters (cm) regardless of this prop.
• maximumTrackCount?: number — default 5.
• onCapture?: (measurement: DimensioningMeasurement) => void — fired on a stable capture (iOS only).
• onError?: (error: DimensioningError) => void — fired on native errors (iOS only).

Important: measurementUnit is currently not honored by the React Native wrapper — captures are returned in cm.

# Example — basic usage

        import React, { useEffect, useState } from 'react';
import { Text } from 'react-native';
import { DimensioningView, VisionDimensioning } from 'react-native-vision-sdk';

export default function RNDimensioningScreen() {
  const [supported, setSupported] = useState(false);

  useEffect(() => {
    VisionDimensioning.deviceCapabilities().then(c => setSupported(c.lidar));
  }, []);

  if (!supported) return <Text>Dimensioning not supported on this device</Text>;

  return (
    <DimensioningView
      mode="offline"
      maximumTrackCount={3}
      onCapture={(m) => console.log('measurement', m)}
      onError={(e) => console.warn('dimensioning error', e)}
      style={{ flex: 1 }}
    />
  );
}

      

# Example — prefetch models on startup

        useEffect(() => {
  VisionDimensioning.prefetchModels().catch(() => {});
}, []);

      

# Event payloads

onCapture receives a DimensioningMeasurement object with fields:

• id, timestamp (Unix seconds)
• length, width, height and their unit strings
• distanceFromCamera and unit
• confidence (0.0–1.0)
• usedCloudSAM (boolean) — whether cloud SAM refinement was used

onError receives { code: number, message: string, reason?: string }. See the DimensioningError types exported by react-native-vision-sdk for error code details.

# Modes & CoreML model notes

• offline: segmentation/refinement runs locally where possible or pipeline falls back to LiDAR-only.
• online: uses cloud SAM refinement and requires an API key to be configured before starting sessions.

CoreML models used by the segmentation pipeline are encrypted and scoped to PackageX's Apple Developer Team Id 964GRVV3N7. Runtime behavior:

• If the consuming app's DEVELOPMENT_TEAM matches 964GRVV3N7, Core ML fetches per-model decryption keys on first launch (one-time network) and caches them.
• If the team id does not match, decryption fails and the SDK falls back to LiDAR-only measurements. Logs will include CoreML decryption errors.

If you plan to distribute dimensioning-enabled builds outside PackageX CI, coordinate signing/team settings with the SDK owners.

# Telemetry & privacy

Dimensioning telemetry routes through the SDK's analytics (same pipeline as other features). The segmentation pipeline suppresses direct MVDimensioning PostHog routing; all telemetry flows to the SDK sink.

Consider documenting telemetry behavior in your app privacy disclosures if you enable dimensioning.

# Troubleshooting

• Models fail to decrypt: ensure DEVELOPMENT_TEAM is 964GRVV3N7 and device had network access on first launch.
• LidarUnavailable on-device: verify you are on a LiDAR-capable device (e.g., iPhone 12 Pro+), and ARKit session permissions are intact.
• Simulator: dimensioning will not function on simulator — deviceCapabilities() returns false and mounting DimensioningView will emit an error.
• Android: the module is stubbed; do not rely on DimensioningView events there.

# Known limitations

• iOS-only; Android shows a placeholder view.
• measurementUnit prop is currently ignored by the React Native wrapper; captures are returned in centimeters.
• CoreML model encryption ties the runtime to a specific Apple Developer Team id.

# Source references

• React Native SDK: react-native-vision-sdk (DimensioningView, types, helpers)
• iOS native module: packagexlabs/vision-sdk-ios (VisionSDKDimensioning)
• CocoaPods: pod 'VisionSDK/Dimensioning' subspec in the iOS SDK distribution