# React Native AR 

A comprehensive React Native AR package providing seamless augmented reality capabilities across iOS and Android platforms. This package enables developers to create rich, interactive AR experiences with advanced features such as anchoring, persistence, contextual recommendations, adaptive lighting, and more.

![React Native AR Demo](generated-icon.png)

## Features

- 🚀 **Cross-Platform Compatibility**: Works seamlessly on iOS (ARKit) and Android (ARCore)
- 🔍 **Advanced AR Features**: Plane detection, raycasting, occlusion, and depth sensing
- 📱 **Interactive AR Elements**: Tap-to-place objects with customizable placement animations
- 🎭 **Object Animations**: Built-in animation utilities for AR object transformations
- 🌟 **Adaptive Lighting**: Real-world lighting estimation for realistic rendering
- 📍 **AR Anchoring System**: Create, manage, and track anchors in AR space
- ☁️ **Persistence Options**: Session, device, and cloud-based AR experience persistence
- 🔄 **Sharing Capabilities**: Share AR experiences between devices with cloud anchors
- 🔍 **Contextual Recommendations**: Environment analysis for suggesting appropriate 3D objects
- 📲 **Haptic Feedback**: Enhanced user experience with haptic feedback integration

## Requirements

### iOS
- iOS 12.0+
- ARKit-compatible device
- Xcode 14+
- CocoaPods

### Android
- Android API level 24+ (Android 7.0 Nougat and above)
- ARCore-supported device
- Android Studio 4.0+

## Installation

```bash
npm install react-native-ar react-native-haptic-feedback
# or
yarn add react-native-ar react-native-haptic-feedback
```

### iOS Setup

```bash
cd ios && pod install
```

Make sure to add the following to your Info.plist:

```xml
<key>NSCameraUsageDescription</key>
<string>This app requires camera access to use augmented reality features</string>
```

### Android Setup

Make sure your app's build.gradle has minSdkVersion 24 or higher.

Add the following to your AndroidManifest.xml:

```xml
<uses-permission android:name="android.permission.CAMERA" />
<uses-feature android:name="android.hardware.camera.ar" android:required="true"/>

<application>
    ...
    <meta-data android:name="com.google.ar.core" android:value="required" />
</application>
```

## Basic Usage

```jsx
import React, { useState, useRef } from 'react';
import { View, Button, StyleSheet } from 'react-native';
import { 
  ARView, 
  ARSessionManager, 
  ARTrackingState, 
  ARObjectModel 
} from 'react-native-ar';

export default function SimpleARExample() {
  const [isTracking, setIsTracking] = useState(false);
  const sessionManagerRef = useRef(null);

  const handleTrackingUpdated = (state) => {
    setIsTracking(state === ARTrackingState.NORMAL);
  };

  const handleTap = async (event) => {
    if (!sessionManagerRef.current || !isTracking) return;
    
    const model = {
      id: 'cube',
      source: require('./assets/models/cube.glb'),
      scale: { x: 0.2, y: 0.2, z: 0.2 },
      position: event.position,
    };
    
    await sessionManagerRef.current.placeObject(model);
  };

  return (
    <View style={styles.container}>
      <ARView
        style={styles.arView}
        onTap={handleTap}
        onTrackingUpdated={handleTrackingUpdated}
        onSessionManagerCreated={(manager) => {
          sessionManagerRef.current = manager;
        }}
      />
      
      <View style={styles.controls}>
        <Button 
          title="Reset Session" 
          disabled={!isTracking}
          onPress={() => sessionManagerRef.current?.resetSession()} 
        />
      </View>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
  arView: {
    flex: 1,
  },
  controls: {
    position: 'absolute',
    bottom: 20,
    left: 20,
    right: 20,
  },
});
```

## Advanced Features

### Contextual Recommendations

The package includes a powerful AR environmental analysis system that can detect surfaces, room types, and provide contextual object recommendations.

```jsx
import { ARContextualRecommender } from 'react-native-ar';

// Initialize recommender
const recommender = new ARContextualRecommender();

// Get recommendations based on environment analysis
const handleAnalyzeEnvironment = async () => {
  const analysis = await recommender.analyzeEnvironment();
  const recommendations = await recommender.getRecommendations({
    environmentContext: analysis.context,
    maxResults: 5,
    categories: ['furniture', 'decoration']
  });
  
  setRecommendedObjects(recommendations);
};
```

### Persistent AR with Anchors

Create persistent AR experiences with various anchor types:

```jsx
import { ARAnchorManager, ARAnchorType, ARPersistenceLevel } from 'react-native-ar';

// Initialize anchor manager
const anchorManager = new ARAnchorManager();

// Create a persistent point anchor
const createAnchor = async (position) => {
  const anchor = await anchorManager.createAnchor({
    type: ARAnchorType.POINT,
    position,
    persistenceLevel: ARPersistenceLevel.DEVICE
  });
  
  // Associate content with this anchor
  await anchorManager.attachContentToAnchor(anchor.id, {
    modelId: 'virtual_plant',
    scale: { x: 1, y: 1, z: 1 }
  });
  
  return anchor;
};

// Find previously created anchors
const loadAnchors = async () => {
  const anchors = await anchorManager.findAnchors({
    persistenceLevel: ARPersistenceLevel.DEVICE
  });
  
  // Restore content for each anchor
  anchors.forEach(anchor => {
    anchorManager.loadAnchorContent(anchor.id);
  });
};
```

## Documentation

For detailed documentation and API reference, see:

- [Getting Started Guide](./docs/GETTING_STARTED.md)
- [AR Anchors & Persistence](./docs/ANCHORS_PERSISTENCE.md)
- [Contextual Recommendations](./docs/CONTEXTUAL_RECOMMENDATIONS.md)
- [API Reference](./docs/API_REFERENCE.md)

## Examples

The package includes several example applications demonstrating various features:

- Basic AR Object Placement
- Depth & Occlusion
- Model Loading & Animations
- Persistent AR Experiences
- Contextual Recommendations
- Adaptive Lighting & Shadows
- Haptic Feedback Integration

Check the [example](./example) directory for complete source code.

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.