Global

Members

(constant) DEFAULT_CHARSET :string

Description:

• Standard character set ordered from densest (darkest) to sparsest (lightest).

Source:

• filters/ascii.js, line 6

Type:

• string

(constant) ImageAreaSelector

Description:

• ImageAreaSelector - An interactive image cropping tool.

  Displays an image with a draggable selection box to define a crop area. The selected crop area can be dragged to another part of the image before applying. Constraints applied: image boundaries, optional aspect ratio, and prevents negative dimensions.

Source:

• react/ImageAreaSelector.tsx, line 289

Example

```tsx
const [crop, setCrop] = useState<CropArea>({ x: 0, y: 0, width: 0, height: 0 });

<ImageAreaSelector
  src="image.jpg"
  aspect={16 / 9}
  lineColor="#00ff00"
  onCropChange={setCrop}
/>
```

(constant) ImageCropper

Description:

• ImageCropper - A complete image cropping interface with explicit apply.

  Combines the ImageAreaSelector for interactive crop area selection with LuminaCanvas for rendering the applied crop in the same component after the user clicks Apply.

  Props summary (not exhaustive):

  • src: Image source (string | File | HTMLImageElement | HTMLCanvasElement | ImageData | null)
  • onCropComplete: Callback when crop is finalized (receives Blob or DataURL)
  • onError: Callback for processing errors
  • aspectRatio: Optional aspect ratio to enforce (width / height)
  • outputFormat: 'blob' | 'dataUrl'
  • showPreview: show the applied crop result in place after Apply. Set false for parent-managed previews.
  • allowReset: show reset button
  • allowResize: show resize handles on the selected crop area
  • applyButtonClassName / applyButtonStyle: Customize the Apply button class/style
  • resetButtonClassName / resetButtonStyle: Customize the Reset button class/style
  • selector* and *ClassName/*Style props: Theme overlay, handles, controls, and error states
  • onApply / onReset: Optional callbacks fired when Apply or Reset are clicked. If the callback returns false (or a Promise that resolves to false), the default behavior is aborted.

  Accessibility notes:

  • Keyboard support is available for an existing crop region (arrow move, Shift+arrow larger move, Alt+arrow resize, Enter confirm, Escape clear).
  • Pointer interactions (dragging/handles) remain primary for geometric selection.

Source:

• react/ImageCropper.tsx, line 159

Example

```tsx
<ImageCropper
  src="photo.jpg"
  aspectRatio={16 / 9}
  outputFormat="blob"
  applyButtonClassName="primary-btn"
  resetButtonStyle={{ backgroundColor: '#fff' }}
  onApply={(crop) =>  validate crop or return false to prevent default }
  onReset={() => /* do custom reset; return false to prevent default }
/>
```

(constant) LUMA_B :number

Description:

• Luminance weight for the Blue channel

Source:

• filters/grayscale.js, line 17

Type:

• number

(constant) LUMA_G :number

Description:

• Luminance weight for the Green channel

Source:

• filters/grayscale.js, line 14

Type:

• number

(constant) LUMA_R :number

Description:

• Luminance weight for the Red channel

Source:

• filters/grayscale.js, line 11

Type:

• number

(constant) LuminaCanvas

Description:

• LuminaCanvas - A declarative React component to render LuminaJS processed images on a canvas.

  This component handles the rendering of image transformations directly onto an HTML <canvas>. It provides a powerful, prop-driven interface to apply image edits like crop, resize, and various filters. You can also access the resulting generated image using the getImage callback prop.

Source:

• react/LuminaCanvas.tsx, line 37

Example

```tsx
function App() {
  const handleImage = (dataUrl) => console.log('Generated Image:', dataUrl);

  return (
    <LuminaCanvas
      source="photo.jpg"
      brightness={20}
      sepia={true}
      resize={{ width: 500, height: 500 }}
      outputType="dataUrl"
      getImage={handleImage}
      width={500} // standard canvas attribute
      height={500} // standard canvas attribute
    />
  );
}
```

(constant) applyConvolution

Description:

• Generic Convolution Engine Performance notes:

  • Convolution traverses almost every pixel and applies kernel math per pixel.
  • Repeated passes or large images can block the main thread.
  • Prefer resizing before convolution when running live previews.

Source:

• filters/convolution.js, line 1

(constant) edgeDetection

Source:

• filters/edgeDetection.js, line 3

(constant) emboss

Source:

• filters/emboss.js, line 3

(constant) sharpen

Source:

• filters/sharpen.js, line 3

Methods

ImageCropperExample()

Description:

• Complete image cropper example demonstrating:

  • Basic cropping with ImageCropper component
  • Resizing an existing crop area with selection handles
  • Custom aspect ratios
  • Handling the cropped result
  • Combining ImageAreaSelector with useLumina for custom workflows

Source:

• react/ImageCropperExample.tsx, line 4

applyEditingOptions(chain, options)

Description:

• Applies the provided ImageEditingOptions to a Lumina instance.

Source:

• react/types.ts, line 20

Parameters:

Returns:

ascii(imageData, optionsopt) → {string}

Description:

• Converts the provided ImageData into an ASCII string representation.

  Note: For best results, the input ImageData should be relatively low resolution (e.g., 50-100 pixels wide), as each pixel maps to a single character.

Source:

• filters/ascii.js, line 12

Example

const { getResizedImageData } = Lumina;
const smallData = getResizedImageData(image, 80, 40);
const textOutput = ascii(smallData);
console.log(textOutput);

Parameters:

Returns:

Type

string

assertBrowserEnvironment(operation)

Description:

• Throws a deterministic error in non-browser runtimes.

Source:

• core/runtime.js, line 21

Parameters:

backgroundBlur(imageData, optionsopt) → {ImageData}

Description:

• Applies a background blur effect to a copy of the provided ImageData.

  Performance notes:

  • This filter is heavier than plain blur because it computes a full blur pass and then composites per pixel with distance-based weighting.
  • Large source images can noticeably block the main thread.
  • For interactive focus controls, use a smaller preview resolution first, then apply full-resolution processing only for final output.

Source:

• filters/backgroundBlur.js, line 9

Example

const portrait = backgroundBlur(imageData, { sigma: 8, focusRadius: 100 });

Parameters:

Returns:

Type

ImageData

blur(imageData, radius) → {ImageData}

Description:

• Applies a box blur filter to a copy of the provided ImageData. This implementation uses a two-pass box blur algorithm (horizontal then vertical) for better performance.

  Performance notes:

  • Runtime cost grows with image dimensions and blur radius.
  • Large images can block the main thread during interactive use.
  • For responsive UIs, resize first (preview), then run full-resolution blur only on final export.

Source:

• filters/blur.js, line 6

Example

const blurredData = blur(imageData, 3);

Parameters:

Returns:

Type

ImageData

brightness(imageData, level) → {ImageData}

Description:

• Applies a brightness filter to a copy of the provided ImageData.

Source:

• filters/brightness.js, line 8

Example

const brightData = brightness(imageData, 50);

Parameters:

Returns:

Type

ImageData

canvasToBlob(canvas, mimeTypeopt, qualityopt) → {Promise.<Blob>}

Description:

• Converts a canvas element to a Blob asynchronously. A convenience wrapper around the native canvas.toBlob callback API.

Source:

• core/canvas.js, line 124

Example

const blob = await canvasToBlob(canvas, 'image/jpeg', 0.85);
const url = URL.createObjectURL(blob);

Parameters:

Throws:

Rejects if the browser fails to encode the canvas.

Type

Error

Returns:

Type

Promise.<Blob>

clamp(value, min, max) → {number}

Description:

• Clamps a numeric value to a given inclusive range [min, max].

Source:

• utils/helpers.js, line 8

Example

clamp(300, 0, 255); // → 255
clamp(-10, 0, 255); // → 0
clamp(128, 0, 255); // → 128

Parameters:

Returns:

Type

number

contrast(imageData, level) → {ImageData}

Description:

• Applies a contrast filter to a copy of the provided ImageData.

Source:

• filters/contrast.js, line 8

Example

const highContrastData = contrast(imageData, 30);

Parameters:

Returns:

Type

ImageData

createOffscreenCanvas(width, height) → {CanvasContext}

Description:

• Creates an offscreen canvas sized to the given dimensions.

Source:

• core/canvas.js, line 16

Parameters:

Returns:

Type

CanvasContext

crop(source, x, y, width, height) → {HTMLCanvasElement}

Description:

• Crops an image or canvas. Returns a new canvas with the cropped content.

Source:

• core/canvas.js, line 199

Parameters:

Returns:

Type

HTMLCanvasElement

gaussianBlur(imageData, sigma) → {ImageData}

Description:

• Applies a Gaussian blur filter to a copy of the provided ImageData. This implementation uses a two-pass separable convolution for better performance.

  Performance notes:

  • Runtime increases with image size and sigma.
  • Sigma also increases kernel radius (ceil(sigma * 3)), which raises compute cost.
  • On large images this can block the main thread; prefer preview resizing and/or Web Worker offload.

Source:

• filters/gaussianBlur.js, line 6

Example

const blurredData = gaussianBlur(imageData, 3.5);

Parameters:

Returns:

Type

ImageData

getPixelData(image) → {Object}

Description:

• Draws an HTMLImageElement onto an offscreen canvas and returns the raw pixel data as an ImageData object.

  The returned ImageData.data is a flat Uint8ClampedArray of RGBA values: [R, G, B, A, R, G, B, A, ...], where each channel is in the range [0, 255].

Source:

• core/canvas.js, line 43

Example

const img = await loadImage('photo.jpg');
const { imageData, canvas } = getPixelData(img);
// imageData.data => Uint8ClampedArray [R, G, B, A, ...]

Parameters:

Throws:

Throws if the image has zero dimensions or if the canvas context cannot be obtained (e.g. context already in use).

Type

Error

Returns:

Type

Object

getResizedImageData(image, width, height) → {ImageData}

Description:

• Extracts ImageData from an image after resizing it to the specified dimensions. Useful for filters that require downsampling, like ASCII art.

Source:

• core/canvas.js, line 159

Parameters:

Returns:

Type

ImageData

grayscale(imageData) → {ImageData}

Description:

• Applies a grayscale filter to a cloned copy of the provided ImageData.

  Each pixel's RGB channels are replaced with the luminance value Y, computed via the BT.601 formula. The alpha channel is preserved unchanged.

  Performance notes:

  • Pixel array length is cached before the loop to avoid repeated property lookups.
  • The loop increments by 4 on every iteration (one full RGBA pixel per step), eliminating redundant index arithmetic.
  • A new ImageData is returned; the original is never mutated.

Source:

• filters/grayscale.js, line 19

Example

import { loadImage }    from '../core/loader.js';
import { getPixelData, putPixelData, canvasToBlob } from '../core/canvas.js';
import { grayscale }    from '../filters/grayscale.js';

const img              = await loadImage(file);
const { imageData, canvas } = getPixelData(img);
const grayData         = grayscale(imageData);

putPixelData(canvas, grayData);
const blob = await canvasToBlob(canvas);

Parameters:

Returns:

Type

ImageData

instanceOfGlobal(value, globalName) → {boolean}

Description:

• Safe instanceof check for browser globals that may be undefined in SSR.

Source:

• core/runtime.js, line 37

Parameters:

Returns:

Type

boolean

isBrowserEnvironment() → {boolean}

Description:

• Returns true when canvas/DOM primitives are available. Evaluated at call time so test environments that install globals later still behave like a browser runtime.

Source:

• core/runtime.js, line 5

Returns:

Type

boolean

isImageFile(value) → {boolean}

Description:

• Returns true if the provided value is a File object whose MIME type indicates an image format.

Source:

• utils/helpers.js, line 25

Example

isImageFile(event.target.files[0]); // → true / false

Parameters:

Returns:

Type

boolean

loadFromFile(file) → {Promise.<HTMLImageElement>}

Description:

• Loads an image from a File object by creating a temporary object URL. The object URL is revoked automatically after the image has loaded to prevent memory leaks.

Source:

• core/loader.js, line 43

Parameters:

Throws:

• Rejects if the provided File is not a valid image MIME type.

  Type

  TypeError

• Rejects if the image fails to load from the generated object URL.

  Type

  Error

Returns:

Type

Promise.<HTMLImageElement>

loadFromURL(url) → {Promise.<HTMLImageElement>}

Description:

• Loads an image from a URL string.

Source:

• core/loader.js, line 9

Parameters:

Throws:

Rejects if the image fails to load (e.g. 404, CORS block).

Type

Error

Returns:

Type

Promise.<HTMLImageElement>

loadImage(source) → {Promise.<HTMLImageElement>}

Description:

• Loads an image from either a URL string or a File object, returning a Promise that resolves to an HTMLImageElement.

  This is the primary entry point for image ingestion in LuminaJS.

Source:

• core/loader.js, line 102

Examples

// Load from URL
const img = await loadImage('<image url string>');

// Load from File input
const [file] = event.target.files;
const img = await loadImage(file);

Parameters:

Throws:

Rejects if source is neither a string nor a File.

Type

TypeError

Returns:

Type

Promise.<HTMLImageElement>

lumina(source) → {Lumina}

Description:

• Initiates a chainable processing sequence.

Source:

• index.js, line 36

Parameters:

Returns:

Type

Lumina

putPixelData(canvas, imageData) → {void}

Description:

• Writes an ImageData object back onto a canvas element, replacing its current contents. This is the inverse of getPixelData and is used to commit mutated pixel data back to a drawable surface.

Source:

• core/canvas.js, line 93

Example

const { imageData, canvas } = getPixelData(img);
// ... mutate imageData.data ...
putPixelData(canvas, imageData);
const dataURL = canvas.toDataURL('image/png');

Parameters:

Throws:

Throws if a 2D context cannot be obtained from the canvas.

Type

Error

Returns:

Type

void

resize(source, width, height) → {HTMLCanvasElement}

Description:

• Resizes an image or canvas to new dimensions. Returns a new canvas with the resized content.

Source:

• core/canvas.js, line 179

Parameters:

Returns:

Type

HTMLCanvasElement

sepia(imageData) → {ImageData}

Description:

• Applies a sepia filter to a copy of the provided ImageData.

Source:

• filters/sepia.js, line 8

Example

const sepiaData = sepia(imageData);

Parameters:

Returns:

Type

ImageData

useLumina(options) → {UseLuminaResult.<T>}

Description:

• useLumina - A powerful and declarative React hook for image processing.

  This hook manages the entire lifecycle of an image, applying advanced filters and transformations seamlessly while providing loading and error states. You can process images via explicit props, or utilize the operations callback for more complex chainable API logic.

Source:

• react/useLumina.ts, line 28

Example

```tsx
const { result, loading, getImage } = useLumina({
  source: 'photo.jpg',
  grayscale: true,
  brightness: 20,
  outputType: 'dataUrl',
  deps: [] // dependencies that trigger a re-run
});

// Get the image on demand (e.g., in an onClick handler)
const uploadImage = async () => {
  const blob = await getImage('blob');
  await api.upload(blob);
};
```

Parameters:

Returns:

Type

UseLuminaResult.<T>

watermark(imageData, text, optionsopt) → {ImageData}

Description:

• Applies a text watermark to a copy of the provided ImageData.

Source:

• filters/watermark.js, line 8

Example

const watermarked = watermark(imageData, '© LuminaJS', { x: 20, y: 20, color: 'white' });

Parameters:

Returns:

Type

ImageData

Type Definitions

CanvasContext

Source:

• core/canvas.js, line 10

Properties:

Type:

• Object