apexify.js 4.9.30 → 5.0.1

package/CHANGELOG.md

@@ -0,0 +1,137 @@
+# Changelog
+
+All notable changes to Apexify.js will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [5.0.0] - 2024-12-20
+
+### 🎉 Major Feature Release - Advanced Image & Canvas Features
+
+#### ✨ Added
+
+##### Background Enhancements
+- **Background Image Filters**: Apply filters directly to background images via `customBg.filters`
+- **Background Image Opacity**: Control background image transparency with `customBg.opacity`
+- **Video Backgrounds**: Support for video backgrounds with frame extraction via `videoBg` option
+  - Extract specific frames from videos
+  - Loop and autoplay support
+  - Opacity control for video backgrounds
+
+##### Image Processing Enhancements
+- **Image Masking**: Apply masks to images with multiple modes (`alpha`, `luminance`, `inverse`)
+- **Custom Clip Paths**: Define custom polygon clipping paths for images
+- **Image Distortion**: 
+  - Perspective distortion with 4-point control
+  - Bulge/pinch effects with intensity control
+  - Mesh warping with customizable grid control points
+- **Effects Stack**: Professional image effects
+  - Vignette effect with intensity and size control
+  - Lens flare with position and intensity
+  - Chromatic aberration effect
+  - Film grain effect
+- **Enhanced Filters**: 
+  - `filterIntensity` - Global intensity multiplier for all filters
+  - `filterOrder` - Control when filters are applied (`pre` or `post` transformation)
+
+##### Text Enhancements
+- **Text on Paths**: Render text along curves and paths
+  - Support for line, arc, bezier, and quadratic curve paths
+  - Offset control for text distance from path
+  - Automatic text distribution along path
+
+##### Custom Lines Enhancements
+- **Advanced Path Options**:
+  - Smooth path interpolation with tension control
+  - Bezier curve paths
+  - Catmull-Rom spline paths
+  - Closed path support
+- **Arrow Markers**: 
+  - Start and end arrows on lines
+  - Customizable arrow size and style (filled/outline)
+  - Color control for arrows
+- **Path Markers**: 
+  - Add markers at any position along a path (0-1)
+  - Multiple marker shapes: circle, square, diamond, arrow
+  - Customizable marker size and color
+- **Line Patterns**: 
+  - Built-in patterns: dots, dashes, custom segments
+  - Pattern offset control
+- **Line Textures**: Apply texture images to lines
+
+##### New Utility Methods
+- **Batch Operations**: `batch()` - Process multiple operations in parallel
+- **Chain Operations**: `chain()` - Chain operations sequentially
+- **Image Stitching**: `stitchImages()` - Stitch multiple images together
+  - Horizontal, vertical, and grid layouts
+  - Overlap and blend support
+  - Spacing control
+- **Collage Maker**: `createCollage()` - Create image collages
+  - Grid, masonry, carousel, and custom layouts
+  - Automatic spacing and alignment
+  - Background and border radius support
+- **Image Compression**: `compress()` - Compress images with quality control
+  - Support for JPEG, WebP, and AVIF formats
+  - Progressive JPEG support
+  - Max width/height constraints
+- **Color Palette Extraction**: `extractPalette()` - Extract color palettes from images
+  - Multiple algorithms: k-means, median-cut, octree
+  - Customizable color count
+  - Multiple output formats: hex, rgb, hsl
+- **Advanced Save Method**: `save()` - Save buffers to local files with extensive customization
+  - Multiple file formats: PNG, JPEG, WebP, AVIF, GIF
+  - Smart naming patterns: timestamp, counter, or custom
+  - Auto-create directories
+  - Quality control for JPEG/WebP
+  - Prefix/suffix support
+  - Overwrite protection with auto-renaming
+  - Batch saving with `saveMultiple()`
+  - Counter management with `resetSaveCounter()`
+
+#### 🔧 Technical Improvements
+- Added comprehensive TypeScript type definitions for all new features
+- Created utility modules for better code organization:
+  - `imageMasking.ts` - Image masking and distortion utilities
+  - `imageEffects.ts` - Image effects utilities
+  - `textPathRenderer.ts` - Text path rendering utilities
+  - `advancedLines.ts` - Advanced line drawing utilities
+  - `batchOperations.ts` - Batch and chain operation utilities
+  - `imageStitching.ts` - Image stitching and collage utilities
+  - `imageCompression.ts` - Image compression and palette extraction utilities
+- Enhanced error handling and validation
+- Improved type safety across all new features
+
+#### 📚 Documentation
+- Updated README with new features
+- Added comprehensive examples for all new features
+- Enhanced API documentation
+
+---
+
+## [4.9.28] - Previous Release
+
+### Features
+- Enhanced text renderer with decorations
+- Professional pattern system
+- Advanced gradient support
+- Comprehensive shape drawing
+- Chart generation capabilities
+- GIF creation support
+
+---
+
+## [4.9.0] - Initial Major Release
+
+### Features
+- Core canvas creation
+- Image and shape drawing
+- Text rendering
+- Basic filters and effects
+- Format conversion
+- Background removal
+
+---
+
+For a complete list of changes, please refer to the [GitHub repository](https://github.com/zenith-79/apexify.js).
+

package/README.md

@@ -6,7 +6,8 @@
 
 **The Ultimate TypeScript Canvas Library for Node.js**
 
-[![npm version](https://badge.fury.io/js/apexify.svg)](https://badge.fury.io/js/apexify)
+[![npm version](https://badge.fury.io/js/apexify.js.svg)](https://badge.fury.io/js/apexify.js)
+[![npm downloads](https://img.shields.io/npm/dt/apexify.js.svg)](https://www.npmjs.com/package/apexify.js)
 [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
 [![Node.js](https://img.shields.io/badge/Node.js-16%2B-green.svg)](https://nodejs.org/)
 [![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
@@ -19,13 +20,22 @@
 
 ### 🖼️ **Advanced Image Processing**
 - **Professional Filters**: 22+ filters including blur, sharpen, vintage, cinematic effects
+- **Image Masking**: Apply masks with alpha, luminance, or inverse modes
+- **Image Distortion**: Perspective, bulge, pinch, and mesh warping effects
+- **Effects Stack**: Vignette, lens flare, chromatic aberration, film grain
 - **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
+- **Image Stitching**: Combine multiple images into panoramas or grids
+- **Collage Maker**: Create beautiful collages with multiple layout options
+- **Image Compression**: Optimize images with quality control (JPEG, WebP, AVIF)
+- **Color Palette Extraction**: Extract color palettes using multiple algorithms
 
 ### 🎨 **Rich Background System**
 - **Multiple Background Types**: Solid colors, gradients, custom images
+- **Video Backgrounds**: Extract frames from videos for dynamic backgrounds
+- **Background Filters**: Apply filters directly to background 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
@@ -33,18 +43,29 @@
 
 ### 📝 **Enhanced Text Rendering**
 - **Font Management**: Custom fonts, sizes, families, and styles
+- **Text on Paths**: Render text along curves (line, arc, bezier, quadratic)
 - **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
 
+### 🎯 **Advanced Custom Lines**
+- **Smooth Paths**: Bezier, Catmull-Rom, and smooth interpolation
+- **Arrow Markers**: Customizable start/end arrows with multiple styles
+- **Path Markers**: Add markers at any position along paths
+- **Line Patterns**: Dots, dashes, and custom pattern segments
+- **Line Textures**: Apply texture images to lines
+
 ### 🔧 **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
+- **Format Conversion**: Convert between PNG, JPEG, WebP, AVIF, and more
 - **Image Manipulation**: Crop, resize, background removal
 - **Color Detection**: Extract and analyze colors from images
+- **Batch Operations**: Process multiple operations in parallel
+- **Chain Operations**: Chain operations sequentially for complex workflows
+- **Advanced File Saving**: Save buffers to local files with smart naming, format conversion, and batch support
 
 ---
 
@@ -149,10 +170,64 @@ const textImage = await painter.createText({
   }
 }, heartImage);
 
-// Save the result
-fs.writeFileSync('beautiful-artwork.png', textImage);
+// Save the result using the advanced save method
+const saveResult = await painter.save(textImage, {
+  directory: './output',
+  filename: 'beautiful-artwork',
+  format: 'png'
+});
+console.log(`Saved to: ${saveResult.path} (${saveResult.size} bytes)`);
+
+// Or use the simple approach (auto-generated filename)
+const autoSave = await painter.save(textImage);
+// Saves to: ./ApexPainter_output/20241220_143025_123.png
+```
+
+### 💾 **Advanced Save Method**
+
+The `save()` method provides powerful file saving capabilities with extensive customization:
+
+```typescript
+// Simple save with auto-generated timestamp name
+const canvas = await painter.createCanvas({ width: 800, height: 600 });
+const result = await painter.save(canvas.buffer);
+// Saves to: ./ApexPainter_output/20241220_143025_123.png
+
+// Custom filename and directory
+await painter.save(canvas.buffer, {
+  directory: './my-images',
+  filename: 'my-canvas',
+  format: 'jpg',
+  quality: 95
+});
+
+// Save with counter naming
+await painter.save(canvas.buffer, {
+  naming: 'counter',
+  prefix: 'image-',
+  counterStart: 1
+});
+// Saves to: ./ApexPainter_output/image-1.png, image-2.png, etc.
+
+// Save multiple buffers in batch
+const buffers = [canvas1.buffer, canvas2.buffer, canvas3.buffer];
+const results = await painter.saveMultiple(buffers, {
+  prefix: 'batch-',
+  naming: 'counter'
+});
+// Saves: batch-1.png, batch-2.png, batch-3.png
 ```
 
+**Save Options:**
+- `directory` - Output directory (default: `./ApexPainter_output`)
+- `filename` - Custom filename (auto-generated if not provided)
+- `format` - File format: `png`, `jpg`, `jpeg`, `webp`, `avif`, `gif` (default: `png`)
+- `quality` - Quality for JPEG/WebP (0-100, default: 90)
+- `naming` - Naming pattern: `timestamp`, `counter`, or `custom` (default: `timestamp`)
+- `prefix` / `suffix` - Add prefix/suffix to filenames
+- `overwrite` - Overwrite existing files (default: `false`, auto-renames if exists)
+- `createDirectory` - Auto-create directory if missing (default: `true`)
+
 ### 📝 **Flexible Array Support**
 
 Both `createImage()` and `createText()` methods accept **single objects** OR **arrays of objects**:
@@ -564,6 +639,9 @@ const buttonText = await painter.createText({
 | `createText()` | Add text to canvas | `TextProperties \| TextProperties[]` |
 | `createChart()` | Generate charts | `ChartConfig` |
 | `createGIF()` | Create animated GIFs | `GIFConfig` |
+| `save()` | Save buffer to local file with advanced options | `Buffer, SaveOptions?` |
+| `saveMultiple()` | Save multiple buffers in batch | `Buffer[], SaveOptions?` |
+| `resetSaveCounter()` | Reset the save counter for naming | `void` |
 
 ### 🔄 **Flexible Parameters**
 
@@ -602,6 +680,43 @@ This allows you to add multiple elements in one call for better performance and
 
 ---
 
+## 🆕 What's New in v4.9.30
+
+### 🎉 Major Feature Release
+
+#### Background Enhancements
+- ✨ **Video Backgrounds**: Use video frames as dynamic backgrounds
+- 🎨 **Background Filters**: Apply filters directly to background images
+- 🔧 **Background Opacity**: Control transparency of background images
+
+#### Image Processing
+- 🎭 **Image Masking**: Apply masks with multiple modes (alpha, luminance, inverse)
+- 🔄 **Image Distortion**: Perspective, bulge, pinch, and mesh warping
+- ✨ **Effects Stack**: Vignette, lens flare, chromatic aberration, film grain
+- 🎛️ **Enhanced Filters**: Filter intensity and order control
+
+#### Text Features
+- 📐 **Text on Paths**: Render text along curves and custom paths
+
+#### Custom Lines
+- ➡️ **Arrow Markers**: Start/end arrows with customizable styles
+- 📍 **Path Markers**: Add markers at any position along paths
+- 🎨 **Line Patterns**: Dots, dashes, and custom patterns
+- 🖼️ **Line Textures**: Apply texture images to lines
+
+#### New Utilities
+- ⚡ **Batch Operations**: Process multiple operations in parallel
+- 🔗 **Chain Operations**: Chain operations sequentially
+- 🖼️ **Image Stitching**: Combine images into panoramas
+- 🎨 **Collage Maker**: Create beautiful image collages
+- 📦 **Image Compression**: Optimize images with quality control
+- 🎨 **Color Palette Extraction**: Extract color palettes from images
+- 💾 **Advanced Save Method**: Save buffers to files with smart naming, format conversion, and batch support
+
+See [CHANGELOG.md](CHANGELOG.md) for complete details.
+
+---
+
 ## 🤝 Contributing
 
 We welcome contributions! Here's how you can help:

package/dist/cjs/Canvas/ApexPainter.d.ts

@@ -1,5 +1,5 @@
 import { PathLike } from "fs";
-import { OutputFormat, CanvasConfig, TextProperties, ImageProperties, GIFOptions, GIFResults, CustomOptions, cropOptions, Frame, ExtractFramesOptions, ResizeOptions, MaskOptions, BlendOptions } from "./utils/utils";
+import { OutputFormat, CanvasConfig, TextProperties, ImageProperties, GIFOptions, GIFResults, CustomOptions, cropOptions, GradientConfig, Frame, ExtractFramesOptions, ResizeOptions, MaskOptions, BlendOptions, ImageFilter, BatchOperation, ChainOperation, StitchOptions, CollageLayout, CompressionOptions, PaletteOptions, SaveOptions, SaveResult } from "./utils/utils";
 interface CanvasResults {
     buffer: Buffer;
     canvas: CanvasConfig;
@@ -7,146 +7,23 @@ interface CanvasResults {
 export declare class ApexPainter {
     #private;
     private format?;
+    private saveCounter;
     constructor({ type }?: OutputFormat);
-    /**
-     * Creates a canvas with the given configuration.
-     * Applies rotation, shadow, border effects, background, and stroke.
-     *
-     * @param canvas - Canvas configuration object containing:
-     *   - width: Canvas width in pixels
-     *   - height: Canvas height in pixels
-     *   - x: X position offset (default: 0)
-     *   - y: Y position offset (default: 0)
-     *   - colorBg: Solid color background (hex, rgb, rgba, hsl, etc.)
-     *   - gradientBg: Gradient background configuration
-     *   - customBg: Custom background image buffer
-     *   - zoom: Canvas zoom level (default: 1)
-     *   - pattern: Pattern background configuration
-     *   - noise: Noise effect configuration
-     *
-     * @returns Promise<CanvasResults> - Object containing canvas buffer and configuration
-     *
-     * @throws Error if canvas configuration is invalid or conflicting
-     *
-     * @example
-     * ```typescript
-     * const result = await painter.createCanvas({
-     *   width: 800,
-     *   height: 600,
-     *   colorBg: '#ffffff',
-     *   zoom: 1.5
-     * });
-     * const buffer = result.buffer;
-     * ```
-     */
     createCanvas(canvas: CanvasConfig): Promise<CanvasResults>;
-    /**
-     * Draws one or more images (or shapes) on an existing canvas buffer.
-     *
-     * @param images - Single ImageProperties object or array of ImageProperties containing:
-     *   - source: Image path/URL/Buffer or ShapeType ('rectangle', 'circle', etc.)
-     *   - x: X position on canvas
-     *   - y: Y position on canvas
-     *   - width: Image/shape width (optional, defaults to original size)
-     *   - height: Image/shape height (optional, defaults to original size)
-     *   - inherit: Use original image dimensions (boolean)
-     *   - fit: Image fitting mode ('fill', 'contain', 'cover', 'scale-down', 'none')
-     *   - align: Image alignment ('center', 'start', 'end')
-     *   - rotation: Rotation angle in degrees (default: 0)
-     *   - opacity: Opacity level 0-1 (default: 1)
-     *   - blur: Blur radius in pixels (default: 0)
-     *   - borderRadius: Border radius or 'circular' (default: 0)
-     *   - borderPosition: Border position ('all', 'top', 'bottom', 'left', 'right')
-     *   - filters: Array of image filters to apply
-     *   - shape: Shape properties (when source is a shape)
-     *   - shadow: Shadow configuration
-     *   - stroke: Stroke configuration
-     *   - boxBackground: Background behind image/shape
-     *
-     * @param canvasBuffer - Existing canvas buffer (Buffer) or CanvasResults object
-     *
-     * @returns Promise<Buffer> - Updated canvas buffer in PNG format
-     *
-     * @throws Error if source, x, or y are missing
-     *
-     * @example
-     * ```typescript
-     * const result = await painter.createImage([
-     *   {
-     *     source: 'rectangle',
-     *     x: 100, y: 100,
-     *     width: 200, height: 150,
-     *     shape: { fill: true, color: '#ff6b6b' },
-     *     shadow: { color: 'rgba(0,0,0,0.3)', offsetX: 5, offsetY: 5, blur: 10 }
-     *   }
-     * ], canvasBuffer);
-     * ```
-     */
     createImage(images: ImageProperties | ImageProperties[], canvasBuffer: CanvasResults | Buffer): Promise<Buffer>;
-    /**
-     * Creates text on an existing canvas buffer with enhanced styling options.
-     *
-     * @param textArray - Single TextProperties object or array of TextProperties containing:
-     *   - text: Text content to render (required)
-     *   - x: X position on canvas (required)
-     *   - y: Y position on canvas (required)
-     *   - fontPath: Path to custom font file (.ttf, .otf, .woff, etc.)
-     *   - fontName: Custom font name (used with fontPath)
-     *   - fontSize: Font size in pixels (default: 16)
-     *   - fontFamily: Font family name (e.g., 'Arial', 'Helvetica')
-     *   - bold: Make text bold (boolean)
-     *   - italic: Make text italic (boolean)
-     *   - underline: Add underline decoration (boolean)
-     *   - overline: Add overline decoration (boolean)
-     *   - strikethrough: Add strikethrough decoration (boolean)
-     *   - highlight: Highlight text with background color and opacity
-     *   - lineHeight: Line height multiplier (default: 1.4)
-     *   - letterSpacing: Space between letters in pixels
-     *   - wordSpacing: Space between words in pixels
-     *   - maxWidth: Maximum width for text wrapping
-     *   - maxHeight: Maximum height for text (truncates with ellipsis)
-     *   - textAlign: Horizontal text alignment ('left', 'center', 'right', 'start', 'end')
-     *   - textBaseline: Vertical text baseline ('alphabetic', 'bottom', 'hanging', 'ideographic', 'middle', 'top')
-     *   - color: Text color (hex, rgb, rgba, hsl, etc.)
-     *   - gradient: Gradient fill for text
-     *   - opacity: Text opacity (0-1, default: 1)
-     *   - glow: Text glow effect with color, intensity, and opacity
-     *   - shadow: Text shadow effect with color, offset, blur, and opacity
-     *   - stroke: Text stroke/outline with color, width, gradient, and opacity
-     *   - rotation: Text rotation in degrees
-     *
-     * @param canvasBuffer - Existing canvas buffer (Buffer) or CanvasResults object
-     *
-     * @returns Promise<Buffer> - Updated canvas buffer in PNG format
-     *
-     * @throws Error if text, x, or y are missing, or if canvas buffer is invalid
-     *
-     * @example
-     * ```typescript
-     * const result = await painter.createText([
-     *   {
-     *     text: "Hello World!",
-     *     x: 100, y: 100,
-     *     fontSize: 24,
-     *     bold: true,
-     *     color: '#ff6b6b',
-     *     shadow: { color: 'rgba(0,0,0,0.3)', offsetX: 2, offsetY: 2, blur: 4 },
-     *     underline: true,
-     *     highlight: { color: '#ffff00', opacity: 0.3 }
-     *   }
-     * ], canvasBuffer);
-     * ```
-     */
     createText(textArray: TextProperties | TextProperties[], canvasBuffer: CanvasResults | Buffer): Promise<Buffer>;
-    createCustom(options: CustomOptions[], buffer: CanvasResults | Buffer): Promise<Buffer>;
+    createCustom(options: CustomOptions | CustomOptions[], buffer: CanvasResults | Buffer): Promise<Buffer>;
     createGIF(gifFrames: {
         background: string;
         duration: number;
-    }[], options: GIFOptions): Promise<GIFResults | any>;
-    resize(resizeOptions: ResizeOptions): Promise<Buffer<ArrayBufferLike>>;
-    imgConverter(source: string, newExtension: string): Promise<Buffer<ArrayBufferLike>>;
-    effects(source: string, filters: any[]): Promise<Buffer<ArrayBufferLike>>;
-    colorsFilter(source: string, filterColor: any, opacity?: number): Promise<any>;
+    }[], options: GIFOptions): Promise<GIFResults | Buffer | string | Array<{
+        attachment: NodeJS.ReadableStream | any;
+        name: string;
+    }> | undefined>;
+    resize(resizeOptions: ResizeOptions): Promise<Buffer>;
+    imgConverter(source: string, newExtension: string): Promise<Buffer>;
+    effects(source: string, filters: ImageFilter[]): Promise<Buffer>;
+    colorsFilter(source: string, filterColor: string | GradientConfig, opacity?: number): Promise<Buffer>;
     colorAnalysis(source: string): Promise<{
         color: string;
         frequency: string;
@@ -155,24 +32,26 @@ export declare class ApexPainter {
         red: number;
         green: number;
         blue: number;
-    }): Promise<Buffer<ArrayBufferLike> | undefined>;
-    removeBackground(imageURL: string, apiKey: string): Promise<Buffer<ArrayBufferLike> | undefined>;
-    blend(layers: {
+    }): Promise<Buffer | undefined>;
+    removeBackground(imageURL: string, apiKey: string): Promise<Buffer | undefined>;
+    blend(layers: Array<{
         image: string | Buffer;
-        blendMode: 'source-over' | 'source-in' | 'source-out' | 'source-atop' | 'destination-over' | 'destination-in' | 'destination-out' | 'destination-atop' | 'lighter' | 'copy' | 'xor' | 'multiply' | 'screen' | 'overlay' | 'darken' | 'lighten' | 'color-dodge' | 'color-burn' | 'hard-light' | 'soft-light' | 'difference' | 'exclusion' | 'hue' | 'saturation' | 'color' | 'luminosity';
+        blendMode: GlobalCompositeOperation;
         position?: {
             x: number;
             y: number;
         };
         opacity?: number;
-    }[], baseImageBuffer: Buffer, defaultBlendMode?: 'source-over' | 'source-in' | 'source-out' | 'source-atop' | 'destination-over' | 'destination-in' | 'destination-out' | 'destination-atop' | 'lighter' | 'copy' | 'xor' | 'multiply' | 'screen' | 'overlay' | 'darken' | 'lighten' | 'color-dodge' | 'color-burn' | 'hard-light' | 'soft-light' | 'difference' | 'exclusion' | 'hue' | 'saturation' | 'color' | 'luminosity'): Promise<Buffer>;
-    createChart(data: any, type: {
+    }>, baseImageBuffer: Buffer, defaultBlendMode?: GlobalCompositeOperation): Promise<Buffer>;
+    createChart(data: unknown, type: {
         chartType: string;
         chartNumber: number;
-    }): Promise<Buffer<ArrayBufferLike> | undefined>;
+    }): Promise<Buffer>;
     cropImage(options: cropOptions): Promise<Buffer>;
-    private drawImage;
-    extractFrames(videoSource: string | Buffer, options: ExtractFramesOptions): Promise<any[]>;
+    extractFrames(videoSource: string | Buffer, options: ExtractFramesOptions): Promise<Array<{
+        source: string;
+        isRemote: boolean;
+    }>>;
     masking(source: string | Buffer | PathLike | Uint8Array, maskSource: string | Buffer | PathLike | Uint8Array, options?: MaskOptions): Promise<Buffer>;
     gradientBlend(source: string | Buffer | PathLike | Uint8Array, options: BlendOptions): Promise<Buffer>;
     animate(frames: Frame[], defaultDuration: number, defaultWidth?: number, defaultHeight?: number, options?: {
@@ -182,8 +61,142 @@ export declare class ApexPainter {
         onFrame?: (index: number) => void;
         onEnd?: () => void;
     }): Promise<Buffer[] | undefined>;
-    validHex(hexColor: string): any;
-    outPut(results: any): Promise<void | Buffer | string | Blob | Object | HTMLCanvasElement>;
+    /**
+     * Processes multiple operations in parallel
+     * @param operations - Array of operations to process
+     * @returns Array of result buffers
+     */
+    batch(operations: BatchOperation[]): Promise<Buffer[]>;
+    /**
+     * Chains multiple operations sequentially
+     * @param operations - Array of operations to chain
+     * @returns Final result buffer
+     */
+    chain(operations: ChainOperation[]): Promise<Buffer>;
+    /**
+     * Stitches multiple images together
+     * @param images - Array of image sources
+     * @param options - Stitching options
+     * @returns Stitched image buffer
+     */
+    stitchImages(images: Array<string | Buffer>, options?: StitchOptions): Promise<Buffer>;
+    /**
+     * Creates an image collage
+     * @param images - Array of image sources with optional dimensions
+     * @param layout - Collage layout configuration
+     * @returns Collage image buffer
+     */
+    createCollage(images: Array<{
+        source: string | Buffer;
+        width?: number;
+        height?: number;
+    }>, layout: CollageLayout): Promise<Buffer>;
+    /**
+     * Compresses an image with quality control
+     * @param image - Image source (path, URL, or Buffer)
+     * @param options - Compression options
+     * @returns Compressed image buffer
+     */
+    compress(image: string | Buffer, options?: CompressionOptions): Promise<Buffer>;
+    /**
+     * Extracts color palette from an image
+     * @param image - Image source (path, URL, or Buffer)
+     * @param options - Palette extraction options
+     * @returns Array of colors with percentages
+     */
+    extractPalette(image: string | Buffer, options?: PaletteOptions): Promise<Array<{
+        color: string;
+        percentage: number;
+    }>>;
+    /**
+     * Validates a hexadecimal color string.
+     * @param hexColor - Hexadecimal color string to validate (format: #RRGGBB)
+     * @returns True if the color is valid
+     * @throws Error if the color format is invalid
+     *
+     * @example
+     * ```typescript
+     * painter.validHex('#ff0000'); // true
+     * painter.validHex('#FF00FF'); // true
+     * painter.validHex('invalid'); // throws Error
+     * ```
+     */
+    validHex(hexColor: string): boolean;
+    /**
+     * Converts results to the configured output format.
+     * @param results - Buffer or result to convert
+     * @returns Converted result in the configured format
+     * @throws Error if format is unsupported or conversion fails
+     *
+     * @example
+     * ```typescript
+     * const painter = new ApexPainter({ type: 'base64' });
+     * const result = await painter.createCanvas({ width: 100, height: 100 });
+     * const base64String = await painter.outPut(result.buffer); // Returns base64 string
+     * ```
+     */
+    outPut(results: Buffer): Promise<Buffer | string | Blob | ArrayBuffer>;
+    /**
+     * Advanced save method to save buffers to local files with extensive customization options.
+     *
+     * @param buffer - Buffer to save (from createCanvas, createImage, createText, etc.)
+     * @param options - Save options for file path, format, naming, etc.
+     * @returns SaveResult with file path, name, size, and format
+     *
+     * @example
+     * ```typescript
+     * // Simple save with auto-generated name
+     * const canvas = await painter.createCanvas({ width: 800, height: 600 });
+     * const result = await painter.save(canvas.buffer);
+     * // Saves to: ./ApexPainter_output/20241220_143025_123.png
+     *
+     * // Custom filename and directory
+     * await painter.save(canvas.buffer, {
+     *   directory: './my-images',
+     *   filename: 'my-canvas',
+     *   format: 'jpg',
+     *   quality: 95
+     * });
+     *
+     * // Save with counter naming
+     * await painter.save(canvas.buffer, {
+     *   naming: 'counter',
+     *   prefix: 'image-',
+     *   counterStart: 1
+     * });
+     * // Saves to: ./ApexPainter_output/image-1.png, image-2.png, etc.
+     *
+     * // Save multiple buffers
+     * const buffers = [canvas1.buffer, canvas2.buffer, canvas3.buffer];
+     * const results = await painter.saveMultiple(buffers, {
+     *   prefix: 'batch-',
+     *   naming: 'counter'
+     * });
+     * ```
+     */
+    save(buffer: Buffer, options?: SaveOptions): Promise<SaveResult>;
+    /**
+     * Save multiple buffers at once with batch options.
+     *
+     * @param buffers - Array of buffers to save
+     * @param options - Save options (applied to all files)
+     * @returns Array of SaveResult objects
+     *
+     * @example
+     * ```typescript
+     * const canvas1 = await painter.createCanvas({ width: 800, height: 600 });
+     * const canvas2 = await painter.createCanvas({ width: 800, height: 600 });
+     * const results = await painter.saveMultiple([canvas1.buffer, canvas2.buffer], {
+     *   prefix: 'batch-',
+     *   naming: 'counter'
+     * });
+     * ```
+     */
+    saveMultiple(buffers: Buffer[], options?: SaveOptions): Promise<SaveResult[]>;
+    /**
+     * Reset the save counter (useful when using 'counter' naming).
+     */
+    resetSaveCounter(): void;
 }
 export {};
 //# sourceMappingURL=ApexPainter.d.ts.map