bx-image: Image Manipulation

Installation

install-bx-module bx-image
# CommandBox
box install bx-image

Three APIs

BIF API

Reading & Writing

// Read from file
img = ImageRead( "/app/uploads/photo.jpg" )

// Read from URL
img = ImageRead( "https://example.com/image.png" )

// Create blank image
img = ImageNew( "", 800, 600, "rgb", "white" )

// Write to file
ImageWrite( img, "/app/output/result.jpg", 0.9 )  // quality 0-1 for JPG

// Get image info
info = ImageInfo( img )   // Returns: width, height, colormodel, source, ...
writeOutput( info.width & "x" & info.height )

Resizing & Cropping

// Resize to specific dimensions (may distort aspect ratio)
ImageResize( img, 800, 600 )

// Resize width only (height auto-scales)
ImageResize( img, 800, "" )

// Scale to fit within bounds (preserves aspect ratio, adds white bars)
ImageScaleToFit( img, 800, 600 )

// Crop to region (x, y, width, height)
ImageCrop( img, 100, 50, 400, 300 )

Transformations

// Rotate by degrees (positive = clockwise)
ImageRotate( img, 90 )

// Flip horizontally or vertically
ImageFlip( img, "horizontal" )   // "horizontal", "vertical"

// Grayscale
ImageGrayScale( img )

// Blur
ImageBlur( img, 3 )              // radius

// Sharpen
ImageSharpen( img )

// Add border
imageAddBorder( img, 5, "black" )

// Draw text on image
imageDrawText( img, "Copyright 2025", 10, 590, { font: "Arial", size: 14, color: "white" } )

Copy & Paste

// Copy a region
region = imageCopy( img, 0, 0, 400, 300 )

// Paste into a different image at position (x, y)
imagePaste( target, region, 100, 100 )

Fluent BoxImage API

// Chained processing pipeline
ImageNew( "/app/uploads/original.jpg" )
    .resize( 800, 600 )
    .rotate( 90 )
    .grayScale()
    .blur( 2 )
    .write( "/app/thumbnails/thumb.jpg", 0.85 )

Fluent Thumbnailing

function makeThumbnail( sourcePath, destPath ) {
    ImageNew( sourcePath )
        .scaleToFit( 200, 200 )
        .addBorder( 2, "##eeeeee" )
        .write( destPath )
}

Component API

<!-- Read -->
<bx:image action="read" source="/uploads/photo.jpg" name="myImage">

<!-- Resize -->
<bx:image action="resize" source="#myImage#" width="400" height="300">

<!-- Write -->
<bx:image action="write" source="#myImage#" destination="/thumbnails/thumb.jpg" quality="0.9">

<!-- One-step read, resize, write -->
<bx:image action="resize" source="/uploads/photo.jpg" destination="/thumbs/thumb.jpg" width="200" height="">

<!-- Send to browser -->
<bx:image action="writeToBrowser" source="#myImage#">

Multi-Format Thumbnail Generator

function processUpload( uploadPath, baseName ) {
    var sizes = [
        { name: "thumb",  w: 150, h: 150 },
        { name: "medium", w: 600, h: 0 },
        { name: "large",  w: 1200, h: 0 }
    ]

    for ( var size of sizes ) {
        var img = ImageRead( uploadPath )
        if ( size.h > 0 ) {
            ImageScaleToFit( img, size.w, size.h )
        } else {
            ImageResize( img, size.w, "" )
        }
        ImageWrite( img, "/app/images/#size.name#/#baseName#.jpg", 0.85 )
    }
}

Watermarking

function addWatermark( imagePath, outputPath ) {
    var img = ImageRead( imagePath )
    var info = ImageInfo( img )
    imageDrawText(
        img,
        "© My Company",
        info.width - 200,
        info.height - 30,
        { font: "Arial", size: 16, color: "white", style: "bold" }
    )
    ImageWrite( img, outputPath, 0.9 )
}

Common Pitfalls

• ✅ ImageResize() modifies the image in-place — assign/use immediately after
• ❌ ImageScaleToFit adds padding; ImageResize may distort — choose based on need
• ✅ JPG quality is 0.0–1.0 (1.0 = best quality, largest file)
• ❌ PNG doesn't support quality parameter (lossless format)
• ✅ Use ImageNew("") to create a blank canvas, then use draw functions
• ❌ Operating on very large images without resizing first will cause memory issues