# Relottie Extract Features API - Analyze Lottie Usage
Use relottie-extract-features to analyze Lottie feature usage, understand complexity, optimize, and check for specific features.

# API Reference: `@lottiefiles/relottie-extract-features`

`@lottiefiles/relottie-extract-features` is a utility plugin for relottie designed to analyze a Lottie animation's [LAST](/docs/tools/relottie/guides/working-with-last) tree and determine which features are actively used.

This information is attached to the processed [VFile](https://github.com/vfile/vfile) and can be useful for understanding animation complexity, identifying opportunities for optimization (by finding unused elements), or checking for the usage of specific features.

## Installation

Install the package alongside `@lottiefiles/relottie`:

```bash
npm install @lottiefiles/relottie-extract-features
# or
yarn add @lottiefiles/relottie-extract-features
```

## Usage

Add the plugin to your relottie pipeline using `.use()`. After processing, the feature usage data will be available on the `data['extract-features']` property of the resulting VFile object.

```typescript
import { relottie } from "@lottiefiles/relottie";
import relottieExtractFeatures, { type ExtractFeaturesFileData } from "@lottiefiles/relottie-extract-features";

// Example Lottie using an image layer (ty: 2)
const inputLottie = '{ "v":"5.5.7", "layers": [ { "nm": "foo", "mn": "bar", "ddd": 0, "ty": 2 } ] }';

async function extractFeatures() {
  try {
    // Process with the plugin
    const file = await relottie().use(relottieExtractFeatures).process(inputLottie);

    // Type assertion to access the data
    const fileData = file.data as ExtractFeaturesFileData;
    const featureData = fileData["extract-features"]; // Access the data

    if (featureData?.used) {
      console.log("Feature Usage Data (Map):", featureData.used);

      // Example: Check usage of a specific feature
      const imageLayerUsage = featureData.used.get("layer-image"); // Title from LAST spec
      if (imageLayerUsage) {
        console.log(`\nImage Layer Usage:`);
        console.log(`  - Used count: ${imageLayerUsage.y}`);
        console.log(`  - Unused count: ${imageLayerUsage.n}`);
      }
    } else {
      console.log("No feature usage data extracted.");
    }
  } catch (error) {
    console.error("Error processing Lottie or extracting features:", error);
  }
}

extractFeatures();
```

## Output Data (`vfile.data['extract-features']`)

The plugin attaches an object to `vfile.data['extract-features']`. The structure, based on the `ExtractFeaturesFileData` interface shown in the source documentation, is:

```typescript
interface ExtractFeaturesFileData extends Data {
  // Data from vfile
  "extract-features": {
    used: Used; // A Map detailing feature usage
  };
}

// Type for the Map value
type Used = Map<
  AnyTitle, // Key: The feature's semantic title (string) from the LAST spec
  {
    /** Total count of times the feature was present but unused */
    n: number; // (UsedCount)
    /** Map detailing usage counts within specific parent node titles */
    parents: Map<AnyTitle, { n: number; y: number }>;
    /** Total count of times the feature was used */
    y: number; // (UsedCount)
  }
>;

// AnyTitle represents the semantic titles defined in LAST (e.g., 'layer-image', 'transform-opacity')
type AnyTitle = string;
```

- **`used`**: A JavaScript `Map` object.
  - **Keys:** Strings representing the semantic `title` of a Lottie feature as defined in the [LAST Specification](/docs/tools/relottie/guides/working-with-last) (e.g., `'layer-image'`, `'shape-rect'`, `'transform-opacity'`). It is highly recommended to use the `TITLES` object exported from `@lottiefiles/last` for robustly referencing these titles (e.g., `TITLES.object.layerImage`).
  - **Values:** An object containing usage counts for that specific feature:
    - `y`: The total number of times this feature was considered **used** in the animation.
    - `n`: The total number of times this feature was present but considered **unused** (e.g., a property present but set to a default value that has no effect).
    - `parents`: Another `Map` providing context on where the feature was used/unused.
      - **Keys:** Strings representing the semantic `title` of parent Lottie features (again, from the [LAST Specification](/docs/tools/relottie/guides/working-with-last) and ideally referenced via `TITLES`).
      - **Values:** An object containing the used (`y`) and unused (`n`) counts of the primary feature specifically within that parent context.

## Options

The source documentation for `@lottiefiles/relottie-extract-features` does not specify any configuration options for the plugin. It likely operates with default analysis behavior.

## Next Steps

- Understand the feature titles used as keys in the `used` and `parents` maps by consulting the [**Guide: Working with LAST**](/docs/tools/relottie/guides/working-with-last) and using the `TITLES` object from `@lottiefiles/last`.
- See how to extract general metadata: [`@lottiefiles/relottie-metadata`](/docs/tools/relottie/api/relottie-metadata).
- Learn how to modify Lottie files based on analysis: [Modifying Lottie Files Guide](/docs/tools/relottie/guides/modifying-lottie-files).