turash/bugulma/frontend/lib/pixel-art/README.md

# Pixel Art Library

A comprehensive TypeScript library for creating pixel-perfect icons, logos, and sprites using HTML5 Canvas API. Optimized for performance with efficient algorithms and batch operations.

## Features

- 🎨 **Pixel-Perfect Rendering** - Crisp, clean pixel art with no anti-aliasing
- ⚡ **Performance Optimized** - Batch pixel operations, color caching, and efficient algorithms
- 🎨 **Color Palette Management** - Predefined and custom color palettes with caching
- 🎨 **Shape Helpers** - Easy-to-use functions for common shapes
- 🎨 **Gradient Support** - Linear and radial gradients
- 🎨 **Layer System** - Compose complex icons from multiple layers
- 🎨 **Type-Safe** - Full TypeScript support
- 🌐 **Browser Compatible** - Enhanced cross-browser support for pixel rendering
- 📐 **Advanced Algorithms** - Bresenham line algorithm, midpoint circle algorithm

## Installation

The library is already included in the project. Import from:

```typescript
import { PixelArtRenderer, PALETTES, createCircle } from '@/lib/pixel-art';
```

## Quick Start

### Basic Usage

```typescript
import { PixelArtRenderer, PALETTES, createCircle } from '@/lib/pixel-art';

const canvas = document.createElement('canvas');
const ctx = canvas.getContext('2d')!;

const renderer = new PixelArtRenderer(ctx, { width: 32, height: 32, scale: 2 }, PALETTES.warm);

// Draw a circle
renderer.circle(createCircle(16, 16, 10), renderer.color('crustLight'));
```

### React Component Example

```tsx
import React, { useRef, useEffect } from 'react';
import { PixelArtRenderer, PALETTES, createCircle } from '@/lib/pixel-art';

const MyIcon: React.FC<{ size?: number }> = ({ size = 64 }) => {
  const canvasRef = useRef<HTMLCanvasElement>(null);

  useEffect(() => {
    const canvas = canvasRef.current;
    if (!canvas) return;

    const ctx = canvas.getContext('2d');
    if (!ctx) return;

    const renderer = new PixelArtRenderer(
      ctx,
      { width: 32, height: 32, scale: size / 32 },
      PALETTES.warm
    );

    renderer.clear();
    renderer.circle(createCircle(16, 16, 10), renderer.color('crustLight'));
  }, [size]);

  return (
    <canvas ref={canvasRef} width={size} height={size} style={{ imageRendering: 'pixelated' }} />
  );
};
```

## API Reference

### PixelArtRenderer

Main rendering class for pixel art.

#### Constructor

```typescript
new PixelArtRenderer(
  ctx: CanvasRenderingContext2D,
  config: PixelArtConfig,
  palette?: ColorPalette
)
```

#### Methods

**Basic Drawing:**

- `clear()` - Clear the canvas
- `pixel(x, y, color, alpha?)` - Draw a single pixel (with bounds checking)
- `pixels(points[])` - Draw multiple pixels efficiently using ImageData batch operations
- `rect(rect, color, alpha?)` - Draw a rectangle
- `rectOutline(rect, color, lineWidth?, alpha?)` - Draw rectangle outline
- `circle(circle, color, alpha?)` - Draw a filled circle (optimized midpoint algorithm)
- `circleOutline(circle, color, lineWidth?, alpha?)` - Draw circle outline
- `triangle(triangle, color, alpha?)` - Draw a triangle
- `triangleOutline(triangle, color, lineWidth?, alpha?)` - Draw triangle outline
- `polygon(points[], color, alpha?)` - Draw a filled polygon (scanline algorithm)
- `line(from, to, color, lineWidth?, alpha?)` - Draw a line (Bresenham algorithm for pixel-perfect lines)

**Gradients:**

- `linearGradient(gradient, shape, alpha?)` - Draw with linear gradient
- `radialGradient(gradient, shape, alpha?)` - Draw with radial gradient

**Advanced:**

- `drawLayers(layers)` - Draw multiple layers with blend modes
- `sprite(data, palette)` - Draw sprite from 2D array
- `pattern(pattern, bounds)` - Draw custom pattern (optimized for batch operations)
- `getImageData()` - Get current canvas as ImageData for processing
- `putImageData(imageData, dx?, dy?)` - Draw ImageData to canvas

**Color Management:**

- `color(colorName)` - Get color from palette (cached for performance)
- `setPalette(palette)` - Update palette and clear cache
- `clearColorCache()` - Clear color cache manually

### Shape Helpers

- `createRect(x, y, width, height)` - Create rectangle
- `createCircle(x, y, radius)` - Create circle
- `createTriangle(p1, p2, p3)` - Create triangle
- `createEquilateralTriangle(centerX, centerY, size)` - Create equilateral triangle
- `createPoint(x, y)` - Create point
- `createStar(centerX, centerY, outerRadius, innerRadius, points)` - Create star
- `createHeart(centerX, centerY, size)` - Create heart shape
- `createDiamond(centerX, centerY, width, height)` - Create diamond

### Color Palettes

Predefined palettes:

- `PALETTES.warm` - Warm tones (gold, brown, red)
- `PALETTES.cool` - Cool tones (blue, cyan)
- `PALETTES.earth` - Earth tones (brown, green, beige)
- `PALETTES.vibrant` - Vibrant colors
- `PALETTES.monochrome` - Black and white

#### Custom Palette

```typescript
import { createPalette } from '@/lib/pixel-art';

const myPalette = createPalette('Custom', {
  primary: '#FF0000',
  secondary: '#00FF00',
  accent: '#0000FF',
});
```

## Examples

### Creating a Simple Icon

```typescript
const renderer = new PixelArtRenderer(ctx, { width: 32, height: 32 }, PALETTES.warm);

// Background
renderer.rect({ x: 0, y: 0, width: 32, height: 32 }, renderer.color('background'));

// Main shape
renderer.circle(createCircle(16, 16, 12), renderer.color('crustLight'));

// Details
renderer.circle(createCircle(16, 16, 8), renderer.color('meatLight'));
```

### Using Gradients

```typescript
const gradient: LinearGradient = {
  x1: 0,
  y1: 0,
  x2: 32,
  y2: 32,
  stops: [
    { offset: 0, color: renderer.color('crustLight') },
    { offset: 1, color: renderer.color('crustDark') },
  ],
};

renderer.linearGradient(gradient, createRect(0, 0, 32, 32));
```

### Layer System

```typescript
const layers: PixelArtLayer[] = [
  {
    name: 'background',
    draw: (ctx) => {
      renderer.rect({ x: 0, y: 0, width: 32, height: 32 }, renderer.color('background'));
    },
  },
  {
    name: 'foreground',
    opacity: 0.8,
    draw: (ctx) => {
      renderer.circle(createCircle(16, 16, 10), renderer.color('crustLight'));
    },
  },
];

renderer.drawLayers(layers);
```

## Performance Tips

1. **Batch Operations** - Use `pixels()` method for drawing many pixels at once (automatically used by `pattern()` for large patterns)
2. **Color Caching** - Colors are automatically cached; use `setPalette()` when changing palettes
3. **Efficient Algorithms** - Lines use Bresenham's algorithm, circles use midpoint algorithm for optimal performance
4. **ImageData Operations** - Use `getImageData()` and `putImageData()` for advanced effects and filters

## Best Practices

1. **Use Logical Coordinates** - Work in logical pixel space (e.g., 32x32), let the renderer handle scaling
2. **Reuse Palettes** - Define palettes once and reuse across icons (caching improves performance)
3. **Layer Composition** - Break complex icons into layers for maintainability
4. **Pixel-Perfect** - Keep `antialiasing: false` for crisp pixel art
5. **Type Safety** - Use TypeScript types for all shapes and configurations
6. **Batch When Possible** - For drawing many pixels, use `pixels()` instead of multiple `pixel()` calls
7. **Browser Compatibility** - The library automatically handles cross-browser pixel rendering differences

## Architecture

```
lib/pixel-art/
├── index.ts          # Main exports
├── types.ts          # TypeScript type definitions
├── renderer.ts       # Core rendering engine
├── palettes.ts       # Color palette management
├── shapes.ts         # Shape helper functions
└── README.md         # This file
```

## License

Part of the Turash (Native Land) project.