Migration Guide

Guide for migrating from Adobe ColdFusion or Lucee image functions to BoxLang Image Module.

Compatibility Overview

The BoxLang Image Module aims for high compatibility with Adobe ColdFusion and Lucee image functions. Most code should work with minimal or no changes.

Compatibility Matrix

Feature

Adobe CF

Lucee

BoxLang

Notes

ImageNew()

✅

Full compatibility

ImageRead()

✅

Full compatibility

ImageWrite()

✅

Full compatibility

ImageResize()

✅

Full compatibility

ImageRotate()

✅

Full compatibility

ImageCrop()

✅

Full compatibility

ImageFlip()

✅

Full compatibility

ImageBlur()

✅

Full compatibility

ImageSharpen()

✅

Full compatibility

ImageGrayScale()

✅

Full compatibility

ImageNegative()

✅

Full compatibility

ImageOverlay()

✅

Full compatibility

ImagePaste()

✅

Full compatibility

ImageAddBorder()

✅

Full compatibility

ImageScaleToFit()

✅

Full compatibility

ImageDrawLine()

✅

Full compatibility

ImageDrawRect()

✅

Full compatibility

ImageDrawOval()

✅

Full compatibility

ImageDrawText()

✅

Full compatibility

ImageSetDrawingColor()

✅

Full compatibility

ImageGetExifMetadata()

✅

Full compatibility

ImageGetIPTCMetadata()

✅

Full compatibility

ImageInfo()

✅

Full compatibility

IsImage()

✅

Full compatibility

IsImageFile()

✅

Full compatibility

Member Functions

✅

CF11+, Lucee 4.5+

Image Component

✅

<cfimage> → <bx:image>

CAPTCHA

✅

⚠️

Planned for future release

ImageFilter()

✅

⚠️

Planned for future release

ImageXOR()

✅

⚠️

Planned for future release

Legend:

✅ Fully supported
⚠️ Partial support or planned for future release
❌ Not supported

Syntax Differences

BIF vs Member Functions

Both Adobe ColdFusion (11+) and Lucee support member function syntax. BoxLang maintains this compatibility:

Adobe CF / Lucee / BoxLang (all compatible):

// BIF syntax
img = ImageNew("photo.jpg");
ImageResize(img, 800, 600);
ImageWrite(img, "resized.jpg");

// Member function syntax (CF11+, Lucee 4.5+, BoxLang)
img = ImageNew("photo.jpg");
img.resize(800, 600);
img.write("resized.jpg");

No changes needed - both syntaxes work identically in BoxLang.

Component Tag Syntax

The main difference is the tag prefix:

Adobe ColdFusion / Lucee:

<cfimage action="read" source="photo.jpg" name="myImage">
<cfimage action="resize" source="#myImage#" width="800" height="600">
<cfimage action="write" source="#myImage#" destination="resized.jpg">

BoxLang:

<bx:image action="read" source="photo.jpg" name="myImage" />
<bx:image action="resize" source="#myImage#" width="800" height="600" />
<bx:image action="write" source="#myImage#" destination="resized.jpg" />

Migration: Simple find/replace: <cfimage → <bx:image

Function Mapping

Most functions have identical names and signatures between platforms:

Direct 1:1 Mappings

These functions work identically in CF, Lucee, and BoxLang:

Function

Lucee

BoxLang

Notes

ImageNew()

✅

No changes

ImageRead()

✅

No changes

ImageWrite()

✅

No changes

ImageResize()

✅

No changes

ImageRotate()

✅

No changes

ImageCrop()

✅

No changes

ImageFlip()

✅

No changes

ImageBlur()

✅

No changes

ImageSharpen()

✅

No changes

ImageGrayScale()

✅

No changes

ImageNegative()

✅

No changes

ImagePaste()

✅

No changes

ImageCopy()

✅

No changes

ImageGetWidth()

✅

No changes

ImageGetHeight()

✅

No changes

ImageInfo()

✅

No changes

Parameter Differences

ImageNew()

Adobe CF:

img = ImageNew("", 800, 600, "rgb", "white");

BoxLang:

// Preferred (no empty string)
img = ImageNew(800, 600, "rgb", "white");

// Also works (CF-compatible)
img = ImageNew("", 800, 600, "rgb", "white");

Migration: Remove empty string first parameter (optional).

ImageRotate()

All platforms support the same syntax:

// Basic rotation
img.rotate(45);

// Rotation around point
img.rotate(45, x, y);

No changes needed.

ImageResize()

Adobe CF / Lucee:

ImageResize(img, 800, 600, "highestQuality");

BoxLang:

ImageResize(img, 800, 600, "highQuality");

Migration: "highestQuality" → "highQuality" (or use "bicubic").

Interpolation values:

Adobe CF

BoxLang

Notes

"nearest"

No change

"bilinear"

No change

"bicubic"

No change

"highestQuality"

"highQuality"

Name difference

"highQuality"

No change

"mediumQuality"

"bilinear"

Use bilinear

"highestPerformance"

"nearest"

Use nearest

Component Differences

Component Name

Adobe CF / Lucee:

<cfimage action="read" source="photo.jpg" name="img">

BoxLang:

<bx:image action="read" source="photo.jpg" name="img" />

Supported Actions

Action

Lucee

BoxLang

Notes

border

✅

No changes

captcha

✅

⚠️

Planned

convert

✅

No changes

info

✅

No changes

read

✅

No changes

resize

✅

No changes

rotate

✅

No changes

write

✅

No changes

writeToBrowser

✅

No changes

Action-Specific Attributes

Most attributes are identical across platforms:

Read:

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

Resize:

<bx:image action="resize"
    source="#myImage#"
    width="800"
    height="600"
    interpolation="highQuality" />

Write:

<bx:image action="write"
    source="#myImage#"
    destination="output.jpg"
    quality="0.85" />

Known Limitations

Not Yet Implemented

These features exist in Adobe CF/Lucee but are planned for future BoxLang releases:

CAPTCHA generation - <bx:image action="captcha"> not yet available
ImageFilter() - Custom Java filter application
ImageXOR() - XOR blending operation
ImageSetAlpha() - Alpha channel manipulation (use setDrawingTransparency() as alternative)

Platform-Specific Differences

Font Rendering

Font rendering may vary slightly across platforms/OS:

// Works on all platforms, but rendering may differ
img.drawText("Hello World", 100, 100, {
    font: "Arial",
    size: 24,
    style: "bold"
});

Solution: Test font output on target platform, use web-safe fonts.

Color Models

BoxLang supports standard color models:

Color Model

Lucee

BoxLang

RGB

✅

ARGB

✅

Grayscale

✅

CMYK

⚠️

❌

Migration: Convert CMYK images to RGB before processing.

Migration Checklist

Pre-Migration Assessment

Identify all image manipulation code (BIFs, components, member functions)
Check for CAPTCHA usage (needs alternative in BoxLang)
Check for ImageFilter() usage (needs alternative)
Review custom interpolation values (highestQuality → highQuality)
Identify CMYK images (convert to RGB)

Migration Steps

Replace component tags:

# Find and replace
<cfimage → <bx:image
</cfimage> → </bx:image>

Update interpolation values:

// Before
img.resize(800, 600, "highestQuality");

// After
img.resize(800, 600, "highQuality");

Test CAPTCHA alternatives: If using CAPTCHA, implement alternative until BoxLang support is added:
```
// Alternative: Use external CAPTCHA service
// or implement custom text-based CAPTCHA
```

Verify font rendering: Test text drawing on target platform:

img.drawText("Test", 100, 100, {
    font: "Arial",  // Use web-safe fonts
    size: 24
});

Test metadata extraction: EXIF/IPTC should work identically:
```
exif = img.getExifMetadata();
iptc = img.getIPTCMetadata();
```

Post-Migration Testing

Verify all images load correctly
Check resize/crop operations
Validate drawing operations (text, shapes)
Test metadata extraction (EXIF/IPTC)
Verify file format conversions
Check error handling

Common Migration Patterns

Pattern 1: Simple Resize

Adobe CF / Lucee:

img = ImageRead("photo.jpg");
ImageResize(img, 800, 600);
ImageWrite(img, "resized.jpg");

BoxLang (no changes):

img = ImageRead("photo.jpg");
ImageResize(img, 800, 600);
ImageWrite(img, "resized.jpg");

Pattern 2: Thumbnail with Crop

Adobe CF / Lucee:

img = ImageRead("photo.jpg");
ImageScaleToFit(img, 200, 200);
ImageAddBorder(img, 2, "gray");
ImageWrite(img, "thumb.jpg");

BoxLang (no changes):

img = ImageRead("photo.jpg");
ImageScaleToFit(img, 200, 200);
ImageAddBorder(img, 2, "gray");
ImageWrite(img, "thumb.jpg");

Pattern 3: Member Function Chaining

Adobe CF 11+ / Lucee 4.5+:

img = ImageNew("photo.jpg")
    .resize(800, 600)
    .blur(3)
    .sharpen(1);

img.write("processed.jpg");

BoxLang (no changes):

img = ImageNew("photo.jpg")
    .resize(800, 600)
    .blur(3)
    .sharpen(1);

img.write("processed.jpg");

Pattern 4: Watermarking

Adobe CF / Lucee:

photo = ImageNew("photo.jpg");
logo = ImageNew("logo.png");
ImageScaleToFit(logo, 100, 100);
ImagePaste(photo, logo, 20, 20);
ImageWrite(photo, "watermarked.jpg");

BoxLang (no changes):

photo = ImageNew("photo.jpg");
logo = ImageNew("logo.png");
ImageScaleToFit(logo, 100, 100);
ImagePaste(photo, logo, 20, 20);
ImageWrite(photo, "watermarked.jpg");

Pattern 5: Component Usage

Adobe CF / Lucee:

<cfimage action="read" source="photo.jpg" name="myImage">
<cfimage action="resize" source="#myImage#" width="800" height="600">
<cfimage action="border" source="#myImage#" thickness="5" color="black">
<cfimage action="write" source="#myImage#" destination="final.jpg">

BoxLang (tag name change only):

<bx:image action="read" source="photo.jpg" name="myImage" />
<bx:image action="resize" source="#myImage#" width="800" height="600" />
<bx:image action="border" source="#myImage#" thickness="5" color="black" />
<bx:image action="write" source="#myImage#" destination="final.jpg" />

Pattern 6: EXIF Metadata

Adobe CF / Lucee:

img = ImageNew("photo.jpg");
exif = ImageGetExifMetadata(img);
camera = exif["Model"];
iso = exif["ISO Speed Ratings"];

BoxLang (no changes):

img = ImageNew("photo.jpg");
exif = ImageGetExifMetadata(img);
camera = exif["Model"];
iso = exif["ISO Speed Ratings"];

Advanced Migration

Custom Image Processing Pipeline

Adobe CF / Lucee:

function processPhoto(sourcePath, outputPath) {
    img = ImageRead(sourcePath);

    // Resize to max 1920px
    if (ImageGetWidth(img) > 1920) {
        ImageScaleToFit(img, 1920, 1920, "highestQuality");
    }

    // Enhance
    ImageSharpen(img, 0.5);

    // Add watermark
    logo = ImageNew("logo.png");
    ImageScaleToFit(logo, 100, 100);
    ImagePaste(img, logo,
        ImageGetWidth(img) - 120,
        ImageGetHeight(img) - 120,
        50
    );

    ImageWrite(img, outputPath, 0.85);
}

BoxLang (change interpolation only):

function processPhoto(sourcePath, outputPath) {
    img = ImageRead(sourcePath);

    // Resize to max 1920px
    if (ImageGetWidth(img) > 1920) {
        ImageScaleToFit(img, 1920, 1920, "highQuality");  // Changed
    }

    // Enhance
    ImageSharpen(img, 0.5);

    // Add watermark
    logo = ImageNew("logo.png");
    ImageScaleToFit(logo, 100, 100);
    ImagePaste(img, logo,
        ImageGetWidth(img) - 120,
        ImageGetHeight(img) - 120,
        50
    );

    ImageWrite(img, outputPath, 0.85);
}

Batch Processing

Adobe CF / Lucee / BoxLang (identical):

function batchResize(sourceDir, targetDir, maxWidth, maxHeight) {
    files = directoryList(sourceDir, false, "path");

    for (file in files) {
        if (IsImageFile(file)) {
            img = ImageNew(file);
            img.scaleToFit(maxWidth, maxHeight);

            filename = getFileFromPath(file);
            img.write("#targetDir#/#filename#");
        }
    }
}

Performance Considerations

Memory Usage

All platforms handle images similarly:

// Load large image
img = ImageNew("large-photo.jpg");  // ~10MB

// Process
img.resize(800, 600);  // Memory efficient

// Release (automatic GC)
img = null;

Optimization Tips

Same best practices apply across all platforms:

Resize early: Reduce dimensions before heavy processing
Reuse images: Copy instead of reloading
Chain operations: Use member functions for cleaner code
Format selection: Use JPEG for photos, PNG for graphics
Quality settings: Balance file size vs. quality

Troubleshooting

Common Issues

Issue: "Function not found"

Cause: Typo in function name

Solution: Check function spelling (case-insensitive but verify)

// Wrong
ImageGrayScale(img);  // Note spelling

// Correct
ImageGrayScale(img);

Issue: "Invalid image object"

Cause: Passing variable name instead of image object

Solution: Pass actual image object

// Wrong
ImageResize("myImage", 800, 600);

// Correct
ImageResize(myImage, 800, 600);
// Or
myImage.resize(800, 600);

Issue: Font rendering differs

Cause: Platform/OS font differences

Solution: Use web-safe fonts, test on target platform

// More portable
img.drawText("Text", 100, 100, {
    font: "Arial",  // Web-safe
    size: 24
});

Additional Resources

BoxLang Documentation - Core BoxLang language reference
Adobe ColdFusion Image Functions - Original CF documentation
Lucee Image Functions - Lucee image function reference
Getting Started Guide - BoxLang image basics
BIF Reference - Complete function reference
Advanced Examples - Real-world use cases

Summary

Migration Complexity: Low

Most Adobe ColdFusion and Lucee image code will work in BoxLang with minimal or no changes:

✅ No changes needed:

BIF function names and signatures
Member function syntax
Parameter order and types
Return values
EXIF/IPTC metadata extraction
Drawing operations
Color handling

⚠️ Minor changes:

Component tags: <cfimage> → <bx:image>
Interpolation: "highestQuality" → "highQuality"

❌ Not yet available:

CAPTCHA generation
ImageFilter()
ImageXOR()

Migration time estimate: 1-2 hours for typical applications.

Next Steps

Getting Started - Learn BoxLang image basics
BIF Reference - Complete function reference
Advanced Examples - Real-world patterns

PreviousAdvanced Examples NextReference

Last updated 6 days ago

Was this helpful?

Table of Contents

Compatibility Overview

Compatibility Matrix

Syntax Differences

BIF vs Member Functions

Component Tag Syntax

Function Mapping

Direct 1:1 Mappings

Parameter Differences

ImageNew()

ImageRotate()

ImageResize()

Component Differences

Component Name

Supported Actions

Action-Specific Attributes

Known Limitations

Not Yet Implemented

Platform-Specific Differences

Font Rendering

Color Models

Migration Checklist

Pre-Migration Assessment

Migration Steps

Post-Migration Testing

Common Migration Patterns

Pattern 1: Simple Resize

Pattern 2: Thumbnail with Crop

Pattern 3: Member Function Chaining

Pattern 4: Watermarking

Pattern 5: Component Usage

Pattern 6: EXIF Metadata

Advanced Migration

Custom Image Processing Pipeline

Batch Processing

Performance Considerations

Memory Usage

Optimization Tips

Troubleshooting

Common Issues

Issue: "Function not found"

Issue: "Invalid image object"

Issue: Font rendering differs

Additional Resources

Summary

Next Steps