lottie-color-manager/README.md

A library for managing colors in Lottie animations

# Lottie Color Manager

A library for managing and transforming colors in Lottie animations.

## Installation

```bash
npm install lottie-color-manager
```

## Features

- 🎨 **Color Extraction**: Extract all unique colors from Lottie animations
- 🔄 **Color Transformation**: Replace colors in animations with tolerance-based matching
- 📊 **Color Analysis**: Analyze color usage and structure in animations
- 🛠️ **Type Safety**: Full TypeScript support with comprehensive type definitions
- 🎯 **Tolerance Matching**: Fuzzy color matching for similar colors

## Quick Start

```typescript
import { LottieColorManager } from 'lottie-color-manager';

// Basic color replacement
const colorMappings = [
  {
    baseColor: '#FF0000',    // Original red color
    newColor: '#00FF00',     // Replace with green
    tolerance: 0.1           // Color matching tolerance
  }
];

const modifiedAnimation = LottieColorManager.changeColors(
  lottieData, 
  colorMappings
);
```

## API Reference

### LottieColorManager

Main class for working with Lottie colors.

#### `changeColors(lottieData: any, colorMappings: ColorMapping[]): any`

Transforms colors in a Lottie animation based on provided color mappings.

**Parameters:**
- `lottieData`: The Lottie animation JSON data
- `colorMappings`: Array of color transformation rules

**Returns:** Modified Lottie animation data

**Example:**
```typescript
const colorMappings = [
  {
    baseColor: '#FF5733',
    newColor: '#33FF57',
    tolerance: 0.05
  },
  {
    baseColor: '#3357FF',
    newColor: '#FF3357',
    tolerance: 0.1
  }
];

const newAnimation = LottieColorManager.changeColors(lottieData, colorMappings);
```

#### `analyzeColors(lottieData: any): { uniqueColors: string[] }`

Analyzes and extracts all unique colors from a Lottie animation.

**Parameters:**
- `lottieData`: The Lottie animation JSON data

**Returns:** Object containing array of unique colors in HEX format

**Example:**
```typescript
const analysis = LottieColorManager.analyzeColors(lottieData);
console.log('Found colors:', analysis.uniqueColors);
// Output: ['#FF5733', '#33FF57', '#3357FF']
```

### ColorUtils

Utility class for color operations and conversions.

#### `hexToLottieColor(hex: string, alpha?: number): LottieColor`

Converts HEX color to Lottie color format.

```typescript
import { ColorUtils } from 'lottie-color-manager';

const lottieColor = ColorUtils.hexToLottieColor('#FF5733', 1.0);
// Returns: [1.0, 0.34, 0.2, 1.0]
```

#### `lottieColorToHex(color: LottieColor): string`

Converts Lottie color to HEX format.

```typescript
const hexColor = ColorUtils.lottieColorToHex([1.0, 0.34, 0.2, 1.0]);
// Returns: '#FF5733'
```

### Types

#### `ColorMapping`

Configuration for color transformation:

```typescript
interface ColorMapping {
  baseColor: string;    // HEX color to match (e.g., '#FF0000')
  tolerance: number;    // Matching tolerance (0.0 - 1.0)
  newColor: string;     // HEX color to replace with (e.g., '#00FF00')
}
```

#### `LottieColor`

Represents a color in Lottie format:

```typescript
type LottieColor = [number, number, number, number]; // [R, G, B, A] (0.0 - 1.0)
```

## Advanced Usage

### Color Tolerance

The tolerance parameter allows for fuzzy color matching, useful when dealing with slightly different shades:

```typescript
const colorMappings = [
  {
    baseColor: '#FF0000',
    newColor: '#00FF00',
    tolerance: 0.2  // Will match colors similar to red within 20% tolerance
  }
];
```

### Logging

Enable debugging to track color transformation process:

```typescript
import { Logger, LogLevel } from 'lottie-color-manager';

// Set log level for debugging
Logger.setLevel(LogLevel.DEBUG);

// Now all operations will log detailed information
const result = LottieColorManager.changeColors(lottieData, colorMappings);
```

## Error Handling

The library includes robust error handling and will return the original animation data if transformation fails:

```typescript
try {
  const modifiedAnimation = LottieColorManager.changeColors(lottieData, colorMappings);
  // Use modifiedAnimation
} catch (error) {
  console.error('Color transformation failed:', error);
  // Original lottieData is returned automatically on error
}
```

## Browser Support

This library works in all modern browsers that support:
- ES2015+ features
- JSON parsing/stringifying
- Map and Set data structures