The following APIs will enable you to identify entities (faces and/or celebrities) from images.

## Set up your backend

Run `amplify add predictions`, then use the following answers:

```console
? Please select from one of the categories below (Use arrow keys)
  `Identify`
? What would you like to identify? (Use arrow keys)
  `Identify Entities`
? Provide a friendly name for your resource
  `identifyEntities`
? Would you like use the default configuration? (Use arrow keys)
  `Default Configuration`
? Who should have access? (Use arrow keys)
  `Auth and Guest users`
```

Run `amplify push` to create the resources in the cloud.

## Working with the API

### Detect entities in an image

To detect general entities like facial features, landmarks etc, default configuration from CLI workflow will suffice (i.e. celebrity detection enabled & entity identification from collection disabled).

Amplify will now detect general entity features when `IdentifyActionType.DETECT_ENTITIES` is passed in. Results are mapped to `IdentifyEntitiesResult`. For example:

<BlockSwitcher>
<Block name="Java">

```java
public void detectEntities(Bitmap image) {
  Amplify.Predictions.identify(
    IdentifyActionType.DETECT_ENTITIES,
    image,
    result -> {
      IdentifyEntitiesResult identifyResult = (IdentifyEntitiesResult) result;
      EntityDetails metadata = identifyResult.getEntities().get(0);
      Log.i("MyAmplifyApp", metadata.getBox().toShortString());
    },
    error -> Log.e("MyAmplifyApp", "Entity detection failed", error)
  );
}
```

</Block>
<Block name="Kotlin - Callbacks">

```kotlin
fun detectEntities(image: Bitmap) {
  Amplify.Predictions.identify(IdentifyActionType.DETECT_ENTITIES, image,
    { result ->
      val identifyResult = result as IdentifyEntitiesResult
      val metadata = identifyResult.entities.firstOrNull()
      Log.i("MyAmplifyApp", "${metadata?.box?.toShortString()}")
    },
    { Log.e("MyAmplifyApp", "Entity detection failed", it) }
  )
}
```

</Block>
<Block name="Kotlin - Coroutines">

```kotlin
suspend fun detectEntities(image: Bitmap) {
  try {
    val result = Amplify.Predictions.identify(IdentifyActionType.DETECT_ENTITIES, image)
    val identifyResult = result as IdentifyEntitiesResult
    val value = identifyResult.entities.firstOrNull()?.box?.toShortString()
    Log.i("MyAmplifyApp", "$value")
  } catch (error: PredictionsException) {
    Log.e("MyAmplifyApp", "Entity detection failed", error)
  }
}
```

</Block>
<Block name="RxJava">

```java
public void detectEntities(Bitmap image) {
  RxAmplify.Predictions.identify(IdentifyActionType.DETECT_ENTITIES, image)
    .subscribe(
      result -> {
        IdentifyEntitiesResult identifyResult = (IdentifyEntitiesResult) result;
        EntityDetails metadata = identifyResult.getEntities().get(0);
        Log.i("MyAmplifyApp", metadata.getBox().toShortString());
      },
      error -> Log.e("MyAmplifyApp", "Entity detection failed", error)
    );
}
```

</Block>
</BlockSwitcher>

As a result of passing in an image, the bounding box ([`android.graphics.RectF`](https://developer.android.com/reference/android/graphics/RectF)) that captures detected entity will be printed to the console.

### Detect pre-determined entities in an image

You can also match entities from a pre-created [Amazon Rekognition Collection](https://docs.aws.amazon.com/rekognition/latest/dg/collections.html) in Amplify. To access this feature, you must used advanced configuration in Amplify CLI:

Run `amplify add predictions`, then use the following answers:

```console
? Please select from one of the categories below (Use arrow keys)
  `Identify`
? What would you like to identify? (Use arrow keys)
  `Identify Entities`
? Provide a friendly name for your resource
  `identifyEntities`
? Would you like use the default configuration? (Use arrow keys)
  `Advanced Configuration`
? Would you like to enable celebrity detection? (Y/n)
  `Y`
? Would you like to identify entities from a collection of images? (y/N)
  `Y`
? How many entities would you like to identify? (50)
  `10`
? Would you like to allow users to add images to this collection? (Use arrow keys)
  `Yes`
? Who should have access? (Use arrow keys)
  `Auth and Guest users`
```

Run `amplify push` to create the resources in the cloud

**Note**: If entity detection was already configured, run `amplify update predictions` to reconfigure as necessary.

The value of `collectionId` is the name of your collection, which can be created directly via CLI. The value of `maxEntities` must be a number greater than `0` or less than `51` (50 is the max number of entities Rekognition can detect from a collection). If either value of `collectionId` or `maxEntities` is invalid, then `identify` will just detect entities in general with facial features, landmarks, etc.

If both `collectionId` and `maxEntities` are properly configured, then Amplify will detect entity matches from the Rekognition Collection in your app. Results are mapped to `IdentifyEntityMatchesResult`. For example:

<BlockSwitcher>
<Block name="Java">

```java
public void detectEntities(Bitmap image) {
  Amplify.Predictions.identify(
    IdentifyActionType.DETECT_ENTITIES,
    image,
    result -> {
      IdentifyEntityMatchesResult identifyResult = (IdentifyEntityMatchesResult) result;
      EntityMatch match = identifyResult.getEntityMatches().get(0);
      Log.i("AmplifyQuickstart", match.getExternalImageId());
    },
    error -> Log.e("AmplifyQuickstart", "Identify failed", error)
  );
}
```

</Block>
<Block name="Kotlin - Callbacks">

```kotlin
fun detectEntities(image: Bitmap) {
  Amplify.Predictions.identify(IdentifyActionType.DETECT_ENTITIES, image,
    { result ->
      val identifyResult = result as IdentifyEntityMatchesResult
      val match = identifyResult.entityMatches.firstOrNull()
      Log.i("AmplifyQuickstart", "${match?.externalImageId}");
    },
    { Log.e("AmplifyQuickstart", "Identify failed", it) }
  )
}
```

</Block>
<Block name="Kotlin - Coroutines">

```kotlin
suspend fun detectEntities(image: Bitmap) {
  try {
    val result = Amplify.Predictions.identify(IdentifyActionType.DETECT_ENTITIES, image)
    val identifyResult = result as IdentifyEntityMatchesResult
    val imageId = identifyResult.entityMatches.firstOrNull()?.externalImageId
    Log.i("MyAmplifyApp", "$imageId")
  } catch (error: PredictionsException) {
    Log.e("MyAmplifyApp", "Identify failed", error)
  }
}
```

</Block>
<Block name="RxJava">

```java
public void detectEntities(Bitmap image) {
  RxAmplify.Predictions.identify(IdentifyActionType.DETECT_ENTITIES, image)
    .subscribe(
      result -> {
        IdentifyEntityMatchesResult identifyResult = (IdentifyEntityMatchesResult) result;
        EntityMatch match = identifyResult.getEntityMatches().get(0);
        Log.i("AmplifyQuickstart", match.getExternalImageId());
      },
      error -> Log.e("AmplifyQuickstart", "Identify failed", error)
    );
}
```

</Block>
</BlockSwitcher>

### Detecting Celebrities

To detect celebrities you can pass in `IdentifyActionType.DETECT_CELEBRITIES`.  Results are mapped to `IdentifyCelebritiesResult`.  For example:

<BlockSwitcher>
<Block name="Java">

```java
public void detectCelebs(Bitmap image) {
  Amplify.Predictions.identify(
    IdentifyActionType.DETECT_CELEBRITIES,
    image,
    result -> {
      IdentifyCelebritiesResult identifyResult = (IdentifyCelebritiesResult) result;
      CelebrityDetails metadata = identifyResult.getCelebrities().get(0);
      Log.i("MyAmplifyApp", metadata.getCelebrity().getName());
    },
    error -> Log.e("MyAmplifyApp", "Identify failed", error)
  );
}
```

</Block>
<Block name="Kotlin - Callbacks">

```kotlin
fun detectCelebs(image: Bitmap) {
  Amplify.Predictions.identify(IdentifyActionType.DETECT_CELEBRITIES, image,
    { result ->
      val identifyResult = result as IdentifyCelebritiesResult
      val metadata = identifyResult.celebrities.firstOrNull()
      Log.i("MyAmplifyApp", "${metadata?.celebrity?.name}")
    },
    { Log.e("MyAmplifyApp", "Identify failed", it) }
  )
}
```

</Block>
<Block name="Kotlin - Coroutines">

```kotlin
suspend fun detectCelebs(image: Bitmap) {
  try {
    val result = Amplify.Predictions.identify(IdentifyActionType.DETECT_CELEBRITIES, image)
    val identifyResult = result as IdentifyCelebritiesResult
    val celebrityName = identifyResult.celebrities.firstOrNull()?.celebrity?.name
    Log.i("MyAmplifyApp", "$celebrityName")
  } catch (error: PredictionsException) {
    Log.e("MyAmplifyApp", "Identify failed", error)
  }
}
```

</Block>
<Block name="RxJava">

```java
public void detectCelebs(Bitmap image) {
  RxAmplify.Predictions.identify(IdentifyActionType.DETECT_CELEBRITIES, image)
    .subscribe(
      result -> {
        IdentifyCelebritiesResult identifyResult = (IdentifyCelebritiesResult) result;
        CelebrityDetails metadata = identifyResult.getCelebrities().get(0);
        Log.i("MyAmplifyApp", metadata.getCelebrity().getName());
      },
      error -> Log.e("MyAmplifyApp", "Identify failed", error)
    );
}
```

</Block>
</BlockSwitcher>

As a result of passing in an image, `identify` will return the name of a detected celebrity.