imagpt

ImaGpt

ImaGpt is a powerful and intuitive image manipulation library for Node.js, built on top of the Canvas API using @napi-rs/canvas. It provides a simple interface to create, edit, and enhance images programmatically.

With ImaGpt, you can:

• Load images from local files or URLs
• Set background colors
• Add styled text
• Draw shapes (rectangles, triangles, circles, and lines)
• Crop and resize images
• Merge layers
• Export the results as files or buffers

This library is designed to be both beginner-friendly and versatile enough for advanced use cases, making it a valuable tool for developers and potentially for integration with Large Language Models (LLMs) for automated image generation tasks.

Installation

To get started with ImaGpt, you'll need Node.js installed on your system. Then, install the package via NPM or Yarn:

npm install imagpt

or

yarn add imagpt

System Dependencies

ImaGpt relies on @napi-rs/canvas, which may require additional system dependencies depending on your operating system. For example, on Ubuntu, install the following:

sudo apt-get install build-essential libcairo2-dev libpango1.0-dev libjpeg-dev libgif-dev librsvg2-dev

For other operating systems, refer to the @napi-rs/canvas documentation for specific requirements.

Usage

Below are some practical examples to demonstrate how to use ImaGpt's core features.

Creating a New Image with Background and Text

const { ImaGpt } = require('imagpt');

async function createImage() {
  const img = new ImaGpt(800, 600); // Create a canvas of 800x600 pixels
  img.BgColor('#ffffff'); // Set a white background

  await img.AddText({
    text: 'Hello, World!',
    fontSize: 48,
    x: 400,
    y: 300,
    align: 'center',
    color: '#000000',
  });

  await img.ToFile('output.png'); // Save the result as a PNG file
}

createImage();

Adding a Watermark to an Image from a URL

const { ImaGpt } = require('imagpt');

async function addWatermark() {
  const img = new ImaGpt(800, 600);
  await img.LoadImageHttp('https://example.com/image.jpg', {}); // Load an image from a URL

  await img.AddText({
    text: 'Watermark',
    fontSize: 24,
    x: 700,
    y: 550,
    align: 'right',
    color: '#ffffff',
  });

  await img.ToFile('watermarked.png');
}

addWatermark();

Using Positions for Easy Text Placement

const { ImaGpt } = require('imagpt');

async function positionExample() {
  const img = new ImaGpt(800, 600);
  img.BgColor('#000000'); // Set a black background

  await img.AddText({
    text: 'Top Left',
    fontSize: 24,
    position: 'topLeft', // Automatically position text at the top-left corner
    color: '#ffffff',
  });

  await img.AddText({
    text: 'Bottom Right',
    fontSize: 24,
    position: 'bottomRight', // Automatically position text at the bottom-right corner
    color: '#ffffff',
  });

  await img.ToFile('positions.png');
}

positionExample();

API Reference

The ImaGpt class provides a variety of methods for image manipulation. Below is a detailed list of available methods, their parameters, and their functionality.

new ImaGpt(width: number, height: number)

Initializes a new ImaGpt instance with the specified canvas dimensions.

Parameters:

• width: The width of the canvas in pixels.
• height: The height of the canvas in pixels.

LoadImageLocal(filePath: string, options: { posX?: number; posY?: number; imageWidth?: number; imageHeight?: number })

Loads an image from a local file and draws it onto the canvas.

Parameters:

• filePath: Path to the local image file.
• options:
  • posX (optional): X-coordinate to place the image (default: 0).
  • posY (optional): Y-coordinate to place the image (default: 0).
  • imageWidth (optional): Width to scale the image.
  • imageHeight (optional): Height to scale the image.

Returns: Promise - The updated ImaGpt instance.

LoadImageHttp(uri: string, options: { posX?: number; posY?: number; imageWidth?: number; imageHeight?: number })

Loads an image from a URL and draws it onto the canvas.

Parameters:

• uri: URL of the image.
• options: Same as LoadImageLocal.

Returns: Promise - The updated ImaGpt instance.

BgColor(color: string)

Sets the background color of the canvas.

Parameters:

• color: A CSS-compatible color string (e.g., #ffffff, rgb(255, 255, 255)).

Returns: ImaGpt - The updated ImaGpt instance.

ToFile(name: string, format?: 'png' | 'jpeg', path?: string | undefined)

Saves the current canvas to a file.

Parameters:

• name: The filename (e.g., output.png).
• format (optional): Image format ('png' or 'jpeg', default: 'png').
• path (optional): Directory path to save the file.

Returns: Promise.

AddText(options: TextOptions)

Adds text to the canvas with customizable styling and positioning.

Parameters:

• options:
  • position (optional): A Positions value for automatic placement (e.g., 'center', 'topLeft').
  • text: The text to display.
  • fontSize: Size of the font in pixels.
  • style (optional): Font style ('bold', 'italic', 'normal').
  • x: X-coordinate for text placement.
  • y: Y-coordinate for text placement.
  • font (optional): Font family (e.g., 'Arial').
  • color (optional): Text color (e.g., #000000).
  • align (optional): Text alignment ('center', 'left', 'right').
  • maxWidth (optional): Maximum width for text wrapping.
  • maxLines (optional): Maximum number of lines.

Returns: Promise - The updated ImaGpt instance.

AddTextBox(options: TextBoxOptions)

Adds a text box to the canvas, extending TextOptions with size constraints.

Parameters:

• options: Extends TextOptions with:
  • maxWidth: Maximum width of the text box.
  • maxHeight: Maximum height of the text box.

Returns: Promise - The updated ImaGpt instance.

MergeLayer(layer: ImaGpt | Canvas, options: { position: Positions; x?: number; y?: number })

Merges another ImaGpt instance or Canvas onto the current canvas.

Parameters:

• layer: The ImaGpt instance or Canvas to merge.
• options:
  • position: A Positions value for automatic placement.
  • x (optional): X-coordinate offset.
  • y (optional): Y-coordinate offset.

Returns: Promise - The updated ImaGpt instance.

Resize(height: number, width: number)

Resizes the canvas to the specified dimensions.

Parameters:

• height: New height in pixels.
• width: New width in pixels.

Returns: Promise - The updated ImaGpt instance.

CropCircle(radius?: number)

Crops the canvas into a circle.

Parameters:

• radius (optional): Radius of the circle (default: half the smaller dimension).

Returns: Promise - The updated ImaGpt instance.

CropRectangle(height?: number, width?: number | undefined)

Crops the canvas into a rectangle.

Parameters:

• height (optional): Height of the rectangle.
• width (optional): Width of the rectangle.

Returns: Promise - The updated ImaGpt instance.

DrawLine(options: { color: string; width: number; checkpoints: { x: number; y: number }[] })

Draws a line on the canvas through specified checkpoints.

Parameters:

• options:
  • color: Line color.
  • width: Line thickness in pixels.
  • checkpoints: Array of { x, y } coordinates.

Returns: Promise - The updated ImaGpt instance.

AddRect(options: { x: number; y: number; width: number; height: number; color: string; position?: Positions })

Draws a filled rectangle on the canvas.

Parameters:

• options:
  • x: X-coordinate.
  • y: Y-coordinate.
  • width: Rectangle width.
  • height: Rectangle height.
  • color: Fill color.
  • position (optional): A Positions value for automatic placement.

Returns: Promise - The updated ImaGpt instance.

AddTriangle(options: { x1: number; y1: number; x2: number; y2: number; x3: number; y3: number; color: string })

Draws a filled triangle on the canvas.

Parameters:

• options:
  • x1, y1: First vertex coordinates.
  • x2, y2: Second vertex coordinates.
  • x3, y3: Third vertex coordinates.
  • color: Fill color.

Returns: Promise - The updated ImaGpt instance.

AddCircle(options: { x: number; y: number; radius: number; color: string })

Draws a filled circle on the canvas.

Parameters:

• options:
  • x: Center X-coordinate.
  • y: Center Y-coordinate.
  • radius: Circle radius.
  • color: Fill color.

Returns: Promise - The updated ImaGpt instance.

ToCanvas()

Returns the underlying Canvas object.

Returns: Promise.

ExportBuffer()

Exports the current canvas as a Buffer.

Returns: Promise.

Positions

The Positions type is used for automatic element placement and can be one of:

• 'center'
• 'topLeft'
• 'topRight'
• 'bottomLeft'
• 'bottomRight'
• 'middleLeft'
• 'middleRight'

These values simplify positioning text, shapes, or layers relative to the canvas.

Dependencies

ImaGpt depends on:

• @napi-rs/canvas: A Node.js binding for the Canvas API.

Ensure that any system-level dependencies required by @napi-rs/canvas are installed.

Contributing

Contributions are welcome! Feel free to open an issue or submit a pull request on GitHub to report bugs, suggest features, or improve the library.

License

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