Package Exports

apexify.js

Readme

🎨 ApexPainter - Advanced Canvas Rendering Library

The Ultimate TypeScript Canvas Library for Node.js

Create stunning visuals with professional-grade canvas rendering, image processing, and text effects

✨ Features Overview

🖼️ Advanced Image Processing

Professional Filters: 22+ filters including blur, sharpen, vintage, cinematic effects
Shape Drawing: 8+ shapes (rectangle, circle, heart, star, polygon, etc.)
Gradient Support: Linear and radial gradients for fills and strokes
Shadow & Stroke Effects: Customizable shadows and strokes for all shapes
Rotation & Positioning: Full control over image placement and rotation

🎨 Rich Background System

Multiple Background Types: Solid colors, gradients, custom images
Pattern Overlays: 12+ built-in patterns (grid, dots, stripes, hexagons, etc.)
Custom Patterns: Use your own images as repeating patterns
Blend Modes: 11+ blend modes for professional compositing
Noise Effects: Add texture with customizable noise intensity

📝 Enhanced Text Rendering

Font Management: Custom fonts, sizes, families, and styles
Text Decorations: Bold, italic, underline, overline, strikethrough, highlight
Advanced Effects: Glow, shadow, stroke with gradient support
Spacing Control: Letter spacing, word spacing, line height
Text Wrapping: Automatic text wrapping with size constraints
Rotation: Full 360° text rotation support

🔧 Professional Tools

Chart Generation: Bar charts, pie charts, line charts
GIF Creation: Animated GIFs from image sequences
Format Conversion: Convert between PNG, JPEG, WebP, and more
Image Manipulation: Crop, resize, background removal
Color Detection: Extract and analyze colors from images

🚀 Quick Start

Installation

npm install apexify

Basic Usage

import { ApexPainter } from 'apexify';

const painter = new ApexPainter();

// Create a canvas with gradient background
const canvas = await painter.createCanvas({
  width: 800,
  height: 600,
  gradientBg: {
    type: 'linear',
    colors: [
      { color: '#FF6B6B', position: 0 },
      { color: '#4ECDC4', position: 0.5 },
      { color: '#45B7D1', position: 1 }
    ],
    direction: { x1: 0, y1: 0, x2: 800, y2: 600 }
  },
  shadow: {
    color: '#000',
    offsetX: 10,
    offsetY: 10,
    blur: 20
  },
  borderRadius: 20
});

// Add a beautiful heart shape (single object)
const heartImage = await painter.createImage({
  source: 'heart',
  x: 300,
  y: 200,
  width: 200,
  height: 200,
  shape: {
    fill: true,
    gradient: {
      type: 'radial',
      colors: [
        { color: '#FF6B6B', position: 0 },
        { color: '#FF1744', position: 1 }
      ],
      center: { x: 100, y: 100 },
      radius: 100
    }
  },
  shadow: {
    color: '#000',
    offsetX: 15,
    offsetY: 15,
    blur: 25
  },
  stroke: {
    color: '#FFF',
    width: 5
  }
}, canvas.buffer);

// Add stunning text (single object)
const textImage = await painter.createText({
  text: 'ApexPainter',
  x: 400,
  y: 450,
  fontSize: 48,
  fontFamily: 'Arial',
  bold: true,
  gradient: {
    type: 'linear',
    colors: [
      { color: '#FFD700', position: 0 },
      { color: '#FF6B6B', position: 1 }
    ],
    direction: { x1: 0, y1: 0, x2: 300, y2: 0 }
  },
  glow: {
    color: '#FFD700',
    intensity: 0.8,
    opacity: 0.9
  },
  shadow: {
    color: '#000',
    offsetX: 8,
    offsetY: 8,
    blur: 15
  },
  stroke: {
    color: '#FFF',
    width: 3
  }
}, heartImage);

// Save the result
fs.writeFileSync('beautiful-artwork.png', textImage);

📝 Flexible Array Support

Both createImage() and createText() methods accept single objects OR arrays of objects:

// ✅ Single Object
await painter.createImage({
  source: 'heart',
  x: 100, y: 100,
  width: 200, height: 200,
  shape: { fill: true, color: '#ff6b6b' }
}, canvasBuffer);

// ✅ Array of Objects
await painter.createImage([
  {
    source: 'rectangle',
    x: 50, y: 50,
    width: 100, height: 80,
    shape: { fill: true, color: '#ff6b6b' }
  },
  {
    source: 'circle',
    x: 200, y: 50,
    width: 80, height: 80,
    shape: { fill: true, color: '#4ecdc4' }
  },
  {
    source: 'star',
    x: 350, y: 50,
    width: 80, height: 80,
    shape: { fill: true, color: '#45b7d1' }
  }
], canvasBuffer);

// ✅ Single Text Object
await painter.createText({
  text: 'Hello World',
  x: 100, y: 100,
  fontSize: 24,
  color: '#ff6b6b'
}, canvasBuffer);

// ✅ Array of Text Objects
await painter.createText([
  {
    text: 'Title',
    x: 100, y: 50,
    fontSize: 32,
    bold: true,
    color: '#2c3e50'
  },
  {
    text: 'Subtitle',
    x: 100, y: 100,
    fontSize: 18,
    color: '#666'
  },
  {
    text: 'Body text with effects',
    x: 100, y: 150,
    fontSize: 14,
    color: '#333',
    glow: { color: '#ffd700', intensity: 0.5 },
    shadow: { color: '#000', offsetX: 2, offsetY: 2, blur: 4 }
  }
], canvasBuffer);

🎨 Advanced Stroke Styles

All stroke properties now support 6 different stroke styles:

// ✅ Basic Stroke Styles
await painter.createImage({
  source: 'rectangle',
  x: 100, y: 100,
  width: 200, height: 150,
  shape: { fill: true, color: '#ffffff' },
  stroke: {
    color: '#ff6b6b',
    width: 8,
    style: 'dashed'  // solid, dashed, dotted, groove, ridge, double
  }
}, canvasBuffer);

// ✅ Gradient Strokes with Styles
await painter.createImage({
  source: 'circle',
  x: 200, y: 200,
  width: 150, height: 150,
  shape: { fill: true, color: '#ffffff' },
  stroke: {
    gradient: {
      type: 'linear',
      colors: [
        { stop: 0, color: '#ff6b6b' },
        { stop: 1, color: '#4ecdc4' }
      ]
    },
    width: 6,
    style: 'ridge'  // Works with all styles!
  }
}, canvasBuffer);

// ✅ Text Strokes with Styles
await painter.createText({
  text: 'Styled Text',
  x: 100, y: 100,
  fontSize: 32,
  color: '#ffffff',
  stroke: {
    color: '#ff6b6b',
    width: 4,
    style: 'double'  // All 6 styles supported!
  }
}, canvasBuffer);

Available Stroke Styles:

solid - Clean solid line (default)
dashed - Dashed line pattern
dotted - Dotted line pattern
groove - 3D grooved effect (dark outer, light inner)
ridge - 3D ridged effect (light outer, dark inner)
double - Double parallel lines

🔤 Organized Font Management

Text fonts are now organized in a clean font object structure:

// ✅ New Font Object Structure
await painter.createText({
  text: 'Organized Font',
  x: 100, y: 100,
  font: {
    size: 24,           // Font size in pixels
    family: 'Arial',    // Font family name
    name: 'customFont', // Custom font name (for registration)
    path: './fonts/custom.ttf' // Path to custom font file
  },
  color: '#333333',
  bold: true,
  italic: true
}, canvasBuffer);

// ✅ Backward Compatibility (Legacy Properties)
await painter.createText({
  text: 'Legacy Font Properties',
  x: 100, y: 150,
  fontSize: 24,         // Still works!
  fontFamily: 'Arial',  // Still works!
  fontName: 'customFont', // Still works!
  fontPath: './fonts/custom.ttf', // Still works!
  color: '#333333'
}, canvasBuffer);

// ✅ Mixed Usage (New Object Takes Priority)
await painter.createText({
  text: 'Mixed Usage',
  x: 100, y: 200,
  font: {
    size: 28,
    family: 'Georgia'
  },
  fontSize: 24,        // Ignored (font.size takes priority)
  fontFamily: 'Arial', // Ignored (font.family takes priority)
  color: '#333333'
}, canvasBuffer);

Font Object Properties:

size - Font size in pixels (replaces fontSize)
family - Font family name (replaces fontFamily)
name - Custom font name for registration (replaces fontName)
path - Path to custom font file (replaces fontPath)

Benefits:

Cleaner Structure: All font properties in one organized object
Better IntelliSense: IDE autocomplete for font properties
Backward Compatible: Legacy properties still work
Priority System: New font object overrides legacy properties

🌈 Advanced Text Gradient Features

Text effects now support gradients for enhanced visual appeal:

// ✅ Gradient Glow
await painter.createText({
  text: 'Gradient Glow Text',
  x: 100, y: 100,
  fontSize: 32,
  color: '#ffffff',
  glow: {
    gradient: {
      type: 'linear',
      colors: [
        { stop: 0, color: '#ff6b6b' },
        { stop: 1, color: '#4ecdc4' }
      ]
    },
    intensity: 15,
    opacity: 0.9
  }
}, canvasBuffer);

// ✅ Gradient Highlight
await painter.createText({
  text: 'Gradient Highlight',
  x: 100, y: 150,
  fontSize: 24,
  color: '#000000',
  highlight: {
    gradient: {
      type: 'radial',
      colors: [
        { stop: 0, color: '#ffd700' },
        { stop: 1, color: '#ff6b6b' }
      ]
    },
    opacity: 0.6
  }
}, canvasBuffer);

// ✅ Gradient Text Decorations
await painter.createText({
  text: 'Styled Decorations',
  x: 100, y: 200,
  fontSize: 28,
  color: '#ffffff',
  underline: {
    gradient: {
      type: 'linear',
      colors: [
        { stop: 0, color: '#ff6b6b' },
        { stop: 1, color: '#4ecdc4' }
      ]
    },
    width: 4
  },
  overline: {
    gradient: {
      type: 'linear',
      colors: [
        { stop: 0, color: '#feca57' },
        { stop: 1, color: '#ff9ff3' }
      ]
    },
    width: 3
  },
  strikethrough: {
    gradient: {
      type: 'linear',
      colors: [
        { stop: 0, color: '#96ceb4' },
        { stop: 1, color: '#45b7d1' }
      ]
    },
    width: 5
  }
}, canvasBuffer);

// ✅ Backward Compatibility (Simple Boolean)
await painter.createText({
  text: 'Simple Decorations',
  x: 100, y: 250,
  fontSize: 24,
  color: '#ffffff',
  underline: true,        // Uses default color
  overline: true,         // Uses default color  
  strikethrough: true     // Uses default color
}, canvasBuffer);

Gradient Support:

Glow: Gradient glow effects with intensity and opacity
Highlight: Gradient background highlights
Underline: Custom gradient underlines with width control
Overline: Custom gradient overlines with width control
Strikethrough: Custom gradient strikethrough with width control
Backward Compatible: Simple boolean values still work

🎯 Real-World Examples

🏢 Business Cards & Marketing Materials

// Create a professional business card
const businessCard = await painter.createCanvas({
  width: 400,
  height: 250,
  gradientBg: {
    type: 'linear',
    colors: [
      { color: '#2C3E50', position: 0 },
      { color: '#34495E', position: 1 }
    ],
    direction: { x1: 0, y1: 0, x2: 400, y2: 250 }
  },
  patternBg: {
    type: 'dots',
    color: '#FFF',
    opacity: 0.1,
    size: 5,
    spacing: 20
  }
});

// Add company logo (star shape)
const logo = await painter.createImage({
  source: 'star',
  x: 50,
  y: 50,
  width: 60,
  height: 60,
  fill: true,
  color: '#FFD700',
  shadow: { color: '#000', offsetX: 3, offsetY: 3, blur: 8 }
}, businessCard.buffer);

// Add company name
const companyText = await painter.createText({
  text: 'ACME Corp',
  x: 130,
  y: 80,
  fontSize: 24,
  fontFamily: 'Arial',
  bold: true,
  color: '#FFF',
  shadow: { color: '#000', offsetX: 2, offsetY: 2, blur: 4 }
}, logo);

// Add contact info
const contactText = await painter.createText({
  text: 'john@acme.com\n+1 (555) 123-4567',
  x: 50,
  y: 150,
  fontSize: 14,
  fontFamily: 'Arial',
  color: '#BDC3C7',
  lineHeight: 1.5
}, companyText);

🎮 Game UI Elements

// Create a game button
const gameButton = await painter.createCanvas({
  width: 200,
  height: 60,
  gradientBg: {
    type: 'linear',
    colors: [
      { color: '#FF6B6B', position: 0 },
      { color: '#FF1744', position: 1 }
    ],
    direction: { x1: 0, y1: 0, x2: 200, y2: 60 }
  },
  shadow: {
    color: '#000',
    offsetX: 5,
    offsetY: 5,
    blur: 15
  },
  borderRadius: 30
});

// Add button text with glow effect
const buttonText = await painter.createText({
  text: 'PLAY NOW',
  x: 100,
  y: 35,
  fontSize: 20,
  fontFamily: 'Arial',
  bold: true,
  color: '#FFF',
  textAlign: 'center',
  textBaseline: 'middle',
  glow: {
    color: '#FFD700',
    intensity: 0.6,
    opacity: 0.8
  },
  shadow: {
    color: '#000',
    offsetX: 2,
    offsetY: 2,
    blur: 4
  }
}, gameButton.buffer);

📚 API Reference

Core Methods

Method	Description	Parameters
`createCanvas()`	Create a new canvas with background	`CanvasConfig`
`createImage()`	Add shapes/images to canvas	`ImageProperties \| ImageProperties[]`
`createText()`	Add text to canvas	`TextProperties \| TextProperties[]`
`createChart()`	Generate charts	`ChartConfig`
`createGIF()`	Create animated GIFs	`GIFConfig`

🔄 Flexible Parameters

Both createImage() and createText() methods accept:

Single Object: ImageProperties or TextProperties
Array of Objects: ImageProperties[] or TextProperties[]

This allows you to add multiple elements in one call for better performance and cleaner code.

Shape Types

rectangle - Standard rectangle
square - Perfect square
circle - Perfect circle
triangle - Equilateral triangle
trapezium - Trapezoid shape
star - 5-pointed star
heart - Heart shape with bezier curves
polygon - Custom polygon

Pattern Types

grid - Grid pattern
dots - Dot pattern
diagonal - Diagonal lines
stripes - Horizontal/vertical stripes
waves - Wave pattern
crosses - Cross pattern
hexagons - Hexagonal pattern
checkerboard - Checkerboard pattern
diamonds - Diamond pattern
triangles - Triangle pattern
stars - Star pattern
polka - Polka dot pattern
custom - Custom image pattern

🤝 Contributing

We welcome contributions! Here's how you can help:

Report Bugs: Found a bug? Open an issue with detailed information
Feature Requests: Have an idea? We'd love to hear it!
Code Contributions: Submit pull requests for improvements
Documentation: Help improve our docs and examples

Development Setup

# Clone the repository
git clone https://github.com/your-username/apexify.git

# Install dependencies
npm install

# Run tests
npm test

# Build the project
npm run build

📞 Support & Community

Join Our Discord Community

Documentation & Resources

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

@napi-rs/canvas - High-performance canvas rendering
Sharp - Professional image processing
Jimp - JavaScript image manipulation
TypeScript - Type-safe development

Made with ❤️ by Jedi Studio

Create stunning visuals with ApexPainter - The ultimate canvas library for Node.js

apexify.js