API Reference: @lottiefiles/relottie-extract-features

@lottiefiles/relottie-extract-features is a utility plugin for relottie designed to analyze a Lottie animation's LAST tree and determine which features are actively used.

This information is attached to the processed 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:

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.

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:

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 (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 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 and using the TITLES object from @lottiefiles/last.

• See how to extract general metadata: @lottiefiles/relottie-metadata.

• Learn how to modify Lottie files based on analysis: Modifying Lottie Files Guide.