npm package: @ltcode/color-extractor
Description: Extract dominant colors from images easily with JavaScript/TypeScript.
Author: Lucas Tiago
Latest version: 1.0.0

# @ltcode/color-extractor

Extract dominant colors from images easily using JavaScript/TypeScript. 
**Compatible with Node.js and Browsers!**

## Installation
```sh
npm install @ltcode/color-extractor
```

## Usage

### 📦 Node.js
```js
import { extractColors } from '@ltcode/color-extractor';

// Extract 5 dominant colors in hexadecimal format
const colors = await extractColors('path/to/image.jpg');
console.log(colors); // ['#ff8040', '#2a5d84', '#f4e8d0', ...]
```

### 🌐 Browser
```js
import { extractColors } from '@ltcode/color-extractor';

// File upload
const fileInput = document.querySelector('input[type="file"]');
fileInput.addEventListener('change', async (e) => {
  const file = e.target.files[0];
  const colors = await extractColors(file);
  console.log(colors);
});

// HTML image element
const img = document.querySelector('img');
const colors = await extractColors(img);

// Canvas
const canvas = document.querySelector('canvas');
const colors = await extractColors(canvas);

// Image URL (with CORS)
const colors = await extractColors('https://example.com/image.jpg');
```

### Advanced Options
```js
import { extractColors, extractDominantColor } from '@ltcode/color-extractor';

// Extract only the dominant color
const dominantColor = await extractDominantColor('image.jpg');

// Custom options
const colors = await extractColors('image.jpg', {
  maxColors: 8,        // Maximum number of colors (default: 5)
  quality: 5,          // Analysis quality (default: 10)
  format: 'rgb',       // Format: 'hex', 'rgb', 'hsl'
  ignoreLightColors: true,  // Ignore light colors
  ignoreDarkColors: false   // Ignore dark colors
});
```

### Using with Buffer (Node.js)
```js
import fs from 'fs/promises';
import { extractColors } from '@ltcode/color-extractor';

const imageBuffer = await fs.readFile('image.jpg');
const colors = await extractColors(imageBuffer);
```

### Drag & Drop in Browser
```js
const dropZone = document.getElementById('dropZone');

dropZone.addEventListener('drop', async (e) => {
  e.preventDefault();
  const files = e.dataTransfer.files;
  
  if (files.length > 0) {
    const colors = await extractColors(files[0]);
    displayColors(colors);
  }
});
```

## API

### `extractColors(input, options?)`
- **input**: 
  - **Node.js**: `string` (file path) | `Buffer`
  - **Browser**: `string` (URL) | `File` | `HTMLImageElement` | `HTMLCanvasElement` | `ImageData`
- **options**: `ColorExtractionOptions` - Configuration options
- **Returns**: `Promise<ColorResult[]>` - Array of colors

### `extractDominantColor(input, options?)`
- **input**: Same as `extractColors`
- **options**: `ColorExtractionOptions` - Configuration options
- **Returns**: `Promise<ColorResult | null>` - Dominant color

### `extractPalette(input, options?)`
Alias for `extractColors` - extracts complete color palette.

### Options (`ColorExtractionOptions`)
```ts
{
  maxColors?: number;        // Maximum colors (default: 5)
  quality?: number;          // Quality 1-50 (default: 10)
  format?: 'hex'|'rgb'|'hsl'; // Output format (default: 'hex')
  ignoreLightColors?: boolean; // Ignore light colors
  ignoreDarkColors?: boolean;  // Ignore dark colors
}
```

## Supported Environments
- ✅ **Node.js** 18+ (ES Modules)
- ✅ **Modern browsers** (Chrome, Firefox, Safari, Edge)
- ✅ **Bundlers** (Webpack, Vite, Rollup, Parcel)

## Image Formats
- **Node.js**: PNG, JPEG (basic implementation)
- **Browser**: All formats supported by the browser

## Browser Demo
Check out the [interactive demo](./examples/browser-demo.html) to test in your browser!

## Examples
See more examples in the [GitHub repository](https://github.com/ltcodedev/color-extractor)

## License
MIT