imgmod v1.0.1

ImgMod

ImgMod is a lightweight JavaScript library for creating and modifying PNG, JPG, or GIF images. It works by using native GWD bindings and g-imglib to modify images in hex format.

Installation

You can install the package using npm:

npm install imgmod

This library will only work on Windows as it implements the following GWD binaries:

getdims
got 
tstp 
gowig
pth

The required GWD executables should come prepackaged with installation, and do not need to be downloaded.

Usage

To initialize an Image class, use the following methods:

const { Image } = require('imgmod');

const blankImage = await Image.Blank(200, 200); //specify dimensions in width, height order
const localImage = await Image.From('./myImage.png');

Creating a random image:

const {
    Image,
    Utils
} = require('imgmod');

async function createImage() {
    const newImage = await Image.Blank(200, 200);

    newImage.pixels().forEach(position => {
	    //position is an Array containing the pixels x and y value; [x, y]
        newImage.setPixel(...position, Utils.Colors.Random())
    })

    await newImage.exportAs('image.png')
    await newImage.exportAs('image.jpg')
    await newImage.exportAs('image.gif')
}

createImage();

Modifying an existing image:

const {
    Image,
    Utils
} = require('imgmod');

async function createImage() {
    const newImage = await Image.From('./mountains.jpg');

    newImage.fillRect(0, 0, 30, 30, new Utils.Color(255, 0, 0, 0))

    const imageBuffer = newImage.asBuffer(type="PNG");
    return imageBuffer;
}

createImage();

Retrieving image information:

const {
    Image,
} = require('imgmod');

async function getImageDimensions() {
    const newImage = await Image.From('./classroom.gif');
    
    const width = newImage.width;
    const height = newImage.height;
    
    console.log(`Dimensions: ${width}x${height}`)
}

getImageDimensions()

Filetype conversions:

const {
    Image,
} = require('imgmod');

async function convertFiletype() {
    const originalImage = await Image.From('./original.png');
    
    const JPG = originalImage.asBuffer("JPG");
    const GIF = originalImage.asBuffer("GIF");
    const HexFormat = originalImage.toString(); //Universal hex format, see "Mechanism"
}

convertFiletype()

ImgMod.Color

Structure:

ImgMod.Color : {
	R: Number,
	G: Number,
	B: Number,
	A: Number
}

Examples:

const {
    Utils,
} = require('imgmod');
const { Color } = Utils;

const RedColor = new Color(255, 0, 0, 255);
const GreenColor = new Color().fromArray([0, 255, 0]);
const BlueColor = new Color(0, 0, 0xFF, 0xFF);
const RandomColor = Utils.Colors.Random();

Internal Mechanisms

ImgMod works using the GWD (GoWindowsData) API to convert images to Universal Hex Format, translate image formats, and compile hex format to an image file.

The Universal Hex Format is a format in which RGBA values (in hexadecimal) for each pixel of an image are separated by spaces. E.g., FF 00 00 FF FF 00 00 FF FF 00 00 FF FF 00 00 FF FF 00 00 FF FF 00 00 FF

The g-imglib dependency of ImgMod simply splits the hex format data by spaces and chunks values into groups of 4 (RGBA) to form a 2D image data array.

This Array is similar to an HTML Canvas ImageData array, and individual pixels can be modified by calculating their index based on x and y position.

GWD Binaries

pth (pngtohex) translates a PNG image to the previously specified hexadecimal format.

pth -input=image.png -output=image.hex

tstp (texttopng) translates hex format to a PNG image.

tstp -input=image.hex -output=image.png

getdims (getdimensions) gets the dimensions of a PNG image, and outputs in the format WxH.

getdims -input=image.png #e.g. 1920x1080

got (gotranslate) translates images between formats, and enables multi-format support for ImgMod

got -input=image.png -output=image.jpg
# OR
got -input=image.jpg -output=image.png # and so on

All other GWD functions only support PNG file, making got the backbone for multi-format support. gowig (gowithimagegrayscale) converts an image HEX file to a grayscaled image HEX file. It is rarely used.

gowig -input=image.hex -output=image_grey.hex

All other GWD functions only support PNG file, making got the backbone for multi-format support.

ImgMod and ImgLib simply converts an image to png, grabs its hex, modifies it, and saves it as a temporary PNG before finally translating the format if needed to create an output file.