Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
110 changes: 52 additions & 58 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ visualization, and multi-touch gesture math.
focus on products and UI while the library manages the underlying AR
infrastructure.

``` js
```js
import { createARView } from 'capacitor-arcore';

const ar = createARView({
Expand All @@ -55,42 +55,41 @@ to scale, and twist with two fingers to rotate**.

## Features

- **Surface detection** with dotted plane feedback and a placement
reticle
- **Tap-to-place** GLB/GLTF models
- **Pinch-to-scale** and **two-finger rotation**
- **Model switching** without losing placement, scale, or rotation
- **Model preloading and caching** for faster product switching
- **Runtime colors and textures**
- **AR screenshot capture**
- **React DOM overlays** over immersive AR
- **WebXR + Three.js** browser AR
- **Native Android ARCore bridge**
- High-level API with lower-level controls available when needed
- **Surface detection** with dotted plane feedback and a placement reticle
- **Tap-to-place** GLB/GLTF models
- **Pinch-to-scale** and **two-finger rotation**
- **Model switching** without losing placement, scale, or rotation
- **Model preloading and caching** for faster product switching
- **Runtime colors and textures**
- **AR screenshot capture**
- **React DOM overlays** over immersive AR
- **WebXR + Three.js** browser AR
- **Native Android ARCore bridge**
- High-level API with lower-level controls available when needed

## Installation

``` bash
```bash
npm install capacitor-arcore
```

For Capacitor applications:

``` bash
```bash
npx cap sync
```

### Requirements

- Node.js and npm
- Capacitor 8.x when used in a Capacitor application
- ARCore-capable Android device for native/device AR
- WebXR-capable Chrome/Chromium for browser AR
- HTTPS for WebXR testing on physical devices
- Node.js and npm
- Capacitor 8.x when used in a Capacitor application
- ARCore-capable Android device for native/device AR
- WebXR-capable Chrome/Chromium for browser AR
- HTTPS for WebXR testing on physical devices

## Quick Start

``` js
```js
import { createARView } from 'capacitor-arcore';

const ar = createARView({
Expand All @@ -117,7 +116,7 @@ ar.enableCustomization({

### Place once, switch products in place

``` js
```js
await ar.placeModel('/models/sofa.glb');

// Preserves the existing AR placement and transform
Expand All @@ -126,7 +125,7 @@ await ar.switchModel('/models/chair.glb');

### Customize materials

``` js
```js
ar.addTextures({
beige: '/textures/beige-fabric.jpg',
olive: '/textures/olive-fabric.jpg',
Expand All @@ -139,7 +138,7 @@ await ar.setColor('#68705b');

### Capture the AR view

``` js
```js
const screenshot = await ar.takeScreenshot({
format: 'png',
includeReticle: false,
Expand All @@ -156,7 +155,7 @@ Your React interface can remain normal DOM above the AR experience.
Elements marked with `data-ui="true"` are ignored by the AR gesture
layer:

``` jsx
```jsx
<button data-ui="true" onClick={() => ar.switchModel('/models/chair.glb')}>
Chair
</button>
Expand All @@ -168,30 +167,29 @@ model.

## Platform Support

Platform Status
---------------------------- --------------------------------------
Android + Chrome WebXR ✅ Supported browser AR path
Capacitor Android / ARCore ✅ Native bridge included
Desktop browser 🛠 Development / capability dependent
iOS / ARKit 📋 Planned
| Platform | Status |
| --- | --- |
| Android + Chrome WebXR | ✅ Supported browser AR path |
| Capacitor Android / ARCore | ✅ Native bridge included |
| Desktop browser | 🛠 Development / capability dependent |
| iOS / ARKit | 📋 Planned |

## Example App

The repository includes an [`example/`](example/) React/Vite application
demonstrating:
The repository includes an [`example/`](example/) React/Vite application demonstrating:

- surface detection and placement feedback
- furniture placement
- gesture interaction
- model switching
- product customization
- screenshot capture
- React DOM overlays
- HTTPS testing on a physical Android device
- surface detection and placement feedback
- furniture placement
- gesture interaction
- model switching
- product customization
- screenshot capture
- React DOM overlays
- HTTPS testing on a physical Android device

Run it with:

``` bash
```bash
cd example
npm install
npm run dev:https
Expand All @@ -201,17 +199,14 @@ npm run dev:https

Detailed documentation lives outside the README:

- [`API.md`](docs/API.md) --- API reference and advanced usage
- [`INSTALLATION.md`](docs/INSTALLATION.md) --- installation and
integration
- [`PHONE_TESTING.md`](docs/PHONE_TESTING.md) --- physical-device
testing
- [`HTTPS_SETUP.md`](docs/HTTPS_SETUP.md) --- local HTTPS and LAN
setup
- [`API.md`](docs/API.md) — API reference and advanced usage
- [`INSTALLATION.md`](docs/INSTALLATION.md) — installation and integration
- [`PHONE_TESTING.md`](docs/PHONE_TESTING.md) — physical-device testing
- [`HTTPS_SETUP.md`](docs/HTTPS_SETUP.md) — local HTTPS and LAN setup

## Project Structure

``` text
```text
arcore-react/
├── android/ # Native Android / ARCore implementation
├── src/ # Public SDK, ARView, gestures, hooks and WebXR engine
Expand All @@ -227,12 +222,12 @@ arcore-react/

For production AR experiences:

- Prefer optimized binary `.glb` models.
- Compress and resize textures for mobile hardware.
- Preload likely next models with `preloadModels()`.
- Avoid restarting the AR session when switching products.
- Keep expensive React/DOM work outside the XR frame loop.
- Test on the lowest-spec device you intend to support.
- Prefer optimized binary `.glb` models.
- Compress and resize textures for mobile hardware.
- Preload likely next models with `preloadModels()`.
- Avoid restarting the AR session when switching products.
- Keep expensive React/DOM work outside the XR frame loop.
- Test on the lowest-spec device you intend to support.

Surface acquisition and low-light tracking ultimately depend on the
device camera, sensors, ARCore/WebXR implementation, and environment.
Expand All @@ -253,6 +248,5 @@ Released under the [MIT License](LICENSE).
------------------------------------------------------------------------

<div align="center">
**Build AR experiences like application features --- not XR
infrastructure.**
**Build AR experiences like application features — not XR infrastructure.**
</div>
Loading