npm package: @jimmyclchu/image-palette
Description: Extract color palettes from images with multiple algorithms and output formats
Author: Jimmy Chu
Latest version: 1.0.0

# Image Palette

Extract color palettes from images using different algorithms. Works in both browser and Node.js.

## Installation

```bash
npm install @jimmyclchu/image-palette
```

For Node.js, you'll also need canvas:

```bash
npm install canvas
```

## Quick Start

```javascript
import { extractPalette } from '@jimmyclchu/image-palette';

// Basic usage
const colors = await extractPalette('path/to/image.jpg');
console.log(colors); // ['#ff5733', '#33ff57', '#3357ff', ...]

// With options
const palette = await extractPalette(imageFile, {
  colorCount: 8,
  algorithm: 'k-means',
  format: 'rgb'
});
```

## Algorithms

- **median-cut** (default) - Fast and reliable
- **k-means** - Higher quality, slower
- **octree** - Good color diversity
- **dominant** - Simple frequency-based extraction

## Options

```javascript
{
  colorCount: 5,           // Number of colors to extract
  algorithm: 'median-cut', // Algorithm to use
  format: 'hex',           // 'hex', 'rgb', or 'hsl'
  preset: 'custom',        // 'fast', 'quality', or 'custom'
  
  // K-means specific
  seed: 42,                // For reproducible results
  iterations: 50,          // Number of iterations
  
  // Filtering
  filters: {
    minDistance: 0.1,      // Minimum color difference (0-1)
    excludeDark: 0.2,      // Exclude colors darker than threshold
    excludeLight: 0.8,     // Exclude colors lighter than threshold
    excludeGrayscale: true // Remove grayscale colors
  },
  
  // Output
  includeMetadata: false   // Include frequency and pixel count data
}
```

## Input Types

**Browser:**
- `HTMLImageElement`
- `HTMLCanvasElement` 
- `File` / `Blob`
- Base64 strings
- Image URLs

**Node.js:**
- File paths
- `Buffer` objects
- Base64 strings

## Examples

### Different Output Formats

```javascript
// Hex colors (default)
const hex = await extractPalette(image, { format: 'hex' });
// ['#ff5733', '#33ff57', '#3357ff']

// RGB objects
const rgb = await extractPalette(image, { format: 'rgb' });
// [{ r: 255, g: 87, b: 51 }, { r: 51, g: 255, b: 87 }]

// HSL objects
const hsl = await extractPalette(image, { format: 'hsl' });
// [{ h: 9, s: 100, l: 60 }, { h: 129, s: 100, l: 60 }]
```

### With Metadata

```javascript
const palette = await extractPalette(image, { 
  includeMetadata: true,
  colorCount: 5
});

console.log(palette);
// [
//   { color: '#ff5733', frequency: 0.34, pixels: 1247 },
//   { color: '#33ff57', frequency: 0.28, pixels: 1031 },
//   ...
// ]
```

### Performance Presets

```javascript
// Fast extraction
const fastColors = await extractPalette(image, { preset: 'fast' });

// Higher quality
const qualityColors = await extractPalette(image, { preset: 'quality' });
```

### Advanced Filtering

```javascript
const filtered = await extractPalette(image, {
  colorCount: 10,
  filters: {
    minDistance: 0.15,     // Colors must be 15% different
    excludeDark: 0.1,      // No very dark colors
    excludeLight: 0.9,     // No very light colors
    excludeGrayscale: true // No gray colors
  }
});
```

### Browser File Upload

```javascript
const input = document.querySelector('input[type="file"]');
input.addEventListener('change', async (e) => {
  const file = e.target.files[0];
  const colors = await extractPalette(file, { colorCount: 6 });
  console.log(colors);
});
```

### Node.js File Processing

```javascript
import { extractPalette } from '@jimmyclchu/image-palette';
import fs from 'fs';

// From file path
const colors1 = await extractPalette('./photo.jpg');

// From buffer
const buffer = fs.readFileSync('./photo.png');
const colors2 = await extractPalette(buffer);
```

## License

MIT