npm package: @mattrayner/vuforia-recognition
Description: Use the Vuforia SDK to detect ImageTarget(s) and VuMark(s) on iOS and Android
Author: Matthew Rayner
Latest version: 1.0.1

# @capacitor-community/vuforia-recognition

Use the Vuforia SDK to detect ImageTarget(s) and VuMark(s) on iOS and Android

## Install

```bash
npm install @capacitor-community/vuforia-recognition
npx cap sync
```

## Setup Steps

* Folder structure

Create test app

```
npm install @mattrayner/vuforia-recognition  
npx cap sync
```

### iOS

* Bridging file setup
* Add image

#### Notes

Trying to get VuMesh detected is a dick:
    - Try bridging file... Done
    - Add VuforiaEngine.framework/Headers to the Search Paths for headers, clieck 'ALL' at the top of the build settings page to see this

### Android

#### local.properties SDK location

You may need to set your local Android SDK location to build the plugin uncomment the sample file (configured for MAC)

#### AndroidManifest.xml

Add the dollowing within the `<application>` tag. Update the !!!PACKAGE!!! value to match your projects

```
<activity
            android:name=".VuforiaActivity"
            android:configChanges="orientation|keyboardHidden|screenSize"
            android:rotationAnimation="seamless"
            android:label="@string/title_activity_vuforia"
            android:parentActivityName=".MainActivity"
            android:theme="@style/FullscreenTheme">
            <meta-data
                android:name="android.support.PARENT_ACTIVITY"
                android:value="!!!PACKAGE!!!.MainActivity" />
        </activity>
```


Add this after the `</application>` tag but before the `</manifest>` tag

```
<!-- Permissions -->
    <uses-feature android:glEsVersion="0x00030001" android:required="true" />

    <uses-feature android:name="android.hardware.camera" />

    <!--
        Required by Vuforia: Add this permission to get access to the camera.
    -->
    <uses-permission android:name="android.permission.CAMERA" />

    <!--
        Required by Vuforia: Add this permission to access IMU sensors at high rate
        for device tracker functionality on Android 12+.
    -->
    <uses-permission android:name="android.permission.HIGH_SAMPLING_RATE_SENSORS" />

    <!--
        Required by Vuforia: Add this permission to allow checking of network.
    -->
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

    <!--
        Required by Vuforia: Add this permission to allow opening network sockets.
    -->
    <uses-permission android:name="android.permission.INTERNET"/>
```

## API

<docgen-index>

* [`startVuforia(...)`](#startvuforia)
* [`stopVuforia()`](#stopvuforia)
* [`addListener('vuforiaEvent', ...)`](#addlistenervuforiaevent)
* [`removeAllListeners()`](#removealllisteners)
* [Interfaces](#interfaces)

</docgen-index>

<docgen-api>
<!--Update the source file JSDoc comments and rerun docgen to update the docs below-->

### startVuforia(...)

```typescript
startVuforia(options: VuforiaStartOptions) => Promise<void>
```

Start a Vuforia session searching for Image Target(s) and VuMarks.

| Param         | Type                                                                |
| ------------- | ------------------------------------------------------------------- |
| **`options`** | <code><a href="#vuforiastartoptions">VuforiaStartOptions</a></code> |

**Since:** 1.0.0

--------------------


### stopVuforia()

```typescript
stopVuforia() => Promise<void>
```

Stop the current Vuforia session.

**But why?**

Well, you could pair this with a setTimeout to give users 
a certain amount of time to search for an image. Or you can pair it with
the `autostopOnImageFound` option within `startVuforia` to have more 
granular control over when the Vuforia camera actually stops.

**Since:** 1.0.0

--------------------


### addListener('vuforiaEvent', ...)

```typescript
addListener(eventName: 'vuforiaEvent', listenerFunc: (event: VuforiaEvent) => void) => Promise<PluginListenerHandle> & PluginListenerHandle
```

Add a listener for events within Vuforia.

| Param              | Type                                                                      |
| ------------------ | ------------------------------------------------------------------------- |
| **`eventName`**    | <code>'vuforiaEvent'</code>                                               |
| **`listenerFunc`** | <code>(event: <a href="#vuforiaevent">VuforiaEvent</a>) =&gt; void</code> |

**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt; & <a href="#pluginlistenerhandle">PluginListenerHandle</a></code>

**Since:** 1.0.0

--------------------


### removeAllListeners()

```typescript
removeAllListeners() => Promise<void>
```

Remove all event listeners

**Since:** 1.0.0

--------------------


### Interfaces


#### VuforiaStartOptions

Configuration object passed to Vuforia, used to configure license and detection.

**What if I don't want Image Target or VuMark recognition?**

Providing an empty target list for either Image Targets, or VuMarks will prevent 
detection of that type. You must provide either Image Targets, VuMarks, or both.
Not providing either will preent the plugin from running.

| Prop                             | Type                  | Description                                                              | Default           | Since |
| -------------------------------- | --------------------- | ------------------------------------------------------------------------ | ----------------- | ----- |
| **`vuforiaLicense`**             | <code>string</code>   | Vuforia license key from http://developer.vuforia.com.                   |                   | 1.0.0 |
| **`imageTargetDatabaseXmlFile`** | <code>string</code>   | Path to your Vuforia Image Target database (.xml) file.                  | <code>""</code>   | 1.0.0 |
| **`imageTargetTargetList`**      | <code>string[]</code> | List of targets within the database that you are searching for.          | <code>[]</code>   | 1.0.0 |
| **`vuMarkDatabaseXmlFile`**      | <code>string</code>   | Path to your Vuforia VuMark template database (.xml) file.               | <code>""</code>   | 1.0.0 |
| **`vuMarkTargetList`**           | <code>string[]</code> | List of VuMark templates within the database that you are searching for. | <code>[]</code>   | 1.0.0 |
| **`autostopOnImageFound`**       | <code>boolean</code>  | Should the Vuforia session end when a target has been found.             | <code>true</code> | 1.0.0 |


#### PluginListenerHandle

| Prop         | Type                                      |
| ------------ | ----------------------------------------- |
| **`remove`** | <code>() =&gt; Promise&lt;void&gt;</code> |


#### VuforiaEvent

Event object returned from within Vuforia when a target is found, or the session is manually closed.

| Prop         | Type                                                              | Description                            | Since |
| ------------ | ----------------------------------------------------------------- | -------------------------------------- | ----- |
| **`status`** | <code><a href="#vuforiaeventstatus">VuforiaEventStatus</a></code> | Object describing the event.           | 1.0.0 |
| **`result`** | <code><a href="#vuforiaeventresult">VuforiaEventResult</a></code> | Object containing the detected result. | 1.0.0 |


#### VuforiaEventStatus

| Prop                   | Type                 | Description                                       | Since |
| ---------------------- | -------------------- | ------------------------------------------------- | ----- |
| **`manuallyClosed`**   | <code>boolean</code> | Was the Vuforia session manually closed?          | 1.0.0 |
| **`imageTargetFound`** | <code>boolean</code> | Was an Image Target found?                        | 1.0.0 |
| **`vuMarkFound`**      | <code>boolean</code> | Was a VuMark found?                               | 1.0.0 |
| **`message`**          | <code>string</code>  | A brief message from Vufora describing the event. | 1.0.0 |


#### VuforiaEventResult

| Prop                  | Type                | Description                             | Default         | Since |
| --------------------- | ------------------- | --------------------------------------- | --------------- | ----- |
| **`imageTargetName`** | <code>string</code> | The Image Target name (if detected).    | <code>""</code> | 1.0.0 |
| **`vuMarkName`**      | <code>string</code> | The VuMark template name (if detected). | <code>""</code> | 1.0.0 |

</docgen-api>