@muellertek/pixel-data/README.md

Extract pixel data from images in React Native using Expo. A lightweight library for accessing raw pixel data from images in React Native applications using Expo's 2D context.

# @muellertek/pixel-data

A lightweight library for accessing raw pixel data from images in React Native applications using Expo's 2D context.

## Features

- Extract pixel data from images in React Native
- Works with Expo's 2D context
- TypeScript support
- Simple and intuitive API
- Lightweight and performant

## Installation

```bash
npm install @muellertek/pixel-data
# or
yarn add @muellertek/pixel-data
```

## Prerequisites

This package requires the following peer dependencies:
- expo >= 52.0.0
- expo-2d-context >= 0.0.4
- expo-asset >= 9.0.0
- expo-gl >= 15.0.0
- react >= 18.0.0
- react-native >= 0.70.0

## Usage

```typescript
import { getPixelData, PixelDataSource } from '@muellertek/pixel-data';
import { Asset } from 'expo-asset';
import Expo2DContext from 'expo-2d-context';

// Load an image asset
const imageAsset = await Asset.loadAsync(require('./path/to/image.png'));

// Create a source object
const source: PixelDataSource = {
  asset: imageAsset[0],
  width: 100,  // Desired width
  height: 100  // Desired height
};

// Get the pixel data
const pixelData = await getPixelData({
  expo2dContext: new Expo2DContext(gl, {}),
  source
});

// Access the pixel data
console.log(pixelData.data); // Uint8ClampedArray containing RGBA values
```

## API Reference

### Types

```typescript
interface PixelDataSource {
  asset: Asset;
  width: number;
  height: number;
}

interface PixelDataResult {
  asset: Asset;
  width: number;
  height: number;
  data: Uint8ClampedArray;
}

interface GetPixelDataParams {
  expo2dContext: Expo2DContext;
  source: PixelDataSource;
}
```

### Functions

#### getPixelData

```typescript
async function getPixelData(params: GetPixelDataParams): Promise<PixelDataResult>
```

Extracts pixel data from an image asset using Expo's 2D context.

**Parameters:**
- `params`: Object containing:
  - `expo2dContext`: An instance of Expo2DContext
  - `source`: PixelDataSource object containing the image asset and dimensions

**Returns:**
- Promise resolving to a PixelDataResult object containing:
  - The original asset
  - The dimensions used
  - A Uint8ClampedArray containing the RGBA pixel data

**Throws:**
- `PixelDataError`: If required parameters are missing or invalid
- `PixelDataError`: If the asset fails to load
- `PixelDataError`: If image data extraction fails

## Error Handling

The library throws `PixelDataError` for various error conditions:

```typescript
try {
  const pixelData = await getPixelData({ expo2dContext, source });
} catch (error) {
  if (error instanceof PixelDataError) {
    console.error('Pixel data error:', error.message);
  } else {
    console.error('Unexpected error:', error);
  }
}
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT © Michael Mueller