All pages
Powered by GitBook
2 of 55

Image Manipulation

BoxLang has an extensive and awesome image manipulation library that allows you to create and manipulate images with easy syntax. We cannot see every detail about image manipulation, but it is necessary to understand that this functionality is easy in BoxLang and exists.

Apart from core image functions, all functions can be applied to an image object as member functions. Yes, BoxLang allows you to deal with image objects natively.

# For Operating Systems using our Quick Installer.
install-bx-module bx-image

# Using CommandBox to install for web servers.
box install bx-image
imgObj = imageRead("https://example.com/company-logo.png");
imgObj.resize(50,50);
bx:image action="writeToBrowser" source=imgObj;

imgObj = imageRead("https://example.com/company-logo.png");
imgObj.blur(5);
bx:image action="writeToBrowser" source=imgObj;

imgObj = imageRead("https://example.com/company-logo.png");
imgObj.rotate(90);
bx:image action="writeToBrowser" source=imgObj;

imgObj = imageRead("https://example.com/company-logo.png");
info = imgObj.info();
writeDump(info);

Contributed Functions/Components

The image module has a wide variety of BIFs to aid in manipulating images. You can find individual BIF documentation by following the below link.

Built-in FunctionsComponents

GitHub Repository and Reporting Issues

Visit the GitHub repository for release notes. You can also file a bug report or improvement suggestion via Jira.

Reference

Built-in Functions

ImageClearRect

Clears a rectangular region of an image using the configured background color. This BIF allows you to specify the position and size of the rectangle to clear in BoxLang.

Syntax

ImageClearRect(name, x, y, width, height)

Arguments

Name
Type
Required
Description

name

any

Yes

The image or the name of a variable referencing an image to operate on.

x

numeric

Yes

X coordinate of the upper left corner of the rectangle.

y

numeric

Yes

Y coordinate of the upper left corner of the rectangle.

width

numeric

Yes

The width of the rectangle.

height

numeric

Yes

The height of the rectangle.

Returns

  • BoxImage: The modified BoxImage instance with the cleared rectangle.

Description

ImageClearRect clears a rectangular region of the specified image, starting at the given (x, y) coordinates and extending to the specified width and height. The cleared area uses the image's configured background color. The image can be passed directly or referenced by variable name.

Example

// Clear a 100x50 rectangle at position (10, 20)
img = ImageClearRect(myImage, 10, 20, 100, 50);

See Also

  • ImageFillRect

  • ImageDrawRect

Notes

  • All arguments are required.

  • The image can be passed as a BoxImage object or as a variable name referencing an image.

  • The cleared region uses the image's background color.

ImageBlur

Blurs an image by a specified radius. This BIF allows you to apply a blur effect to an image in BoxLang, controlling the strength of the blur.

Syntax

ImageBlur(name [, blurRadius])

Arguments

Name
Type
Required
Default
Description

name

any

Yes

The image or the name of a variable referencing an image to operate on.

blurRadius

numeric

No

3

The amount to blur the image. Higher values produce a stronger blur effect.

Returns

  • BoxImage: The modified BoxImage instance with the blur applied.

Description

ImageBlur applies a blur effect to the specified image. The blur radius controls the strength of the blur; higher values result in a more pronounced blur. The image can be passed directly or referenced by variable name.

Example

// Blur an image with the default radius (3)
img = ImageBlur(myImage);

// Blur an image with a radius of 10
img = ImageBlur(myImage, 10);

See Also

  • ImageSharpen

  • ImageAddBorder

Notes

  • The default blur radius is 3 if not specified.

  • The image can be passed as a BoxImage object or as a variable name referencing an image.

ImageCopy

Copies a rectangular region of an image and draws it at a new location. This BIF allows you to specify the source area and the destination offset in BoxLang.

Syntax

ImageCopy(name, x, y, width, height [, dx] [, dy])

Arguments

Name
Type
Required
Default
Description

name

any

Yes

The image or the name of a variable referencing an image to operate on.

x

numeric

Yes

The x coordinate of the rectangular area of the image to copy.

y

numeric

Yes

The y coordinate of the rectangular area of the image to copy.

width

numeric

Yes

The width of the rectangular area of the image to copy.

height

numeric

Yes

The height of the rectangular area of the image to copy.

dx

numeric

No

0

The amount to shift the x coordinate when drawing the copied area.

dy

numeric

No

0

The amount to shift the y coordinate when drawing the copied area.

Returns

  • BoxImage: The modified BoxImage instance with the copied region drawn at the new location.

Description

ImageCopy copies a rectangular region from the specified image, starting at (x, y) with the given width and height, and draws it at a new location offset by (dx, dy). The image can be passed directly or referenced by variable name.

Example

// Copy a 100x50 region at (10, 20) and draw it at (110, 70)
img = ImageCopy(myImage, 10, 20, 100, 50, 100, 50);

// Copy a region and draw it at the same location (no offset)
img = ImageCopy(myImage, 10, 20, 100, 50);

See Also

  • ImageClearRect

  • ImageDrawRect

Notes

  • The image can be passed as a BoxImage object or as a variable name referencing an image.

  • The default offset is (0, 0) if dx and dy are not specified.

ImageDrawArc

Draws an arc on an image. This BIF allows you to specify the position, size, angles, and whether the arc is filled in BoxLang.

Syntax

ImageDrawArc(name, x, y, width, height, startAngle, archAngle [, filled])

Arguments

Name
Type
Required
Default
Description

name

any

Yes

The image or the name of a variable referencing an image to operate on.

x

numeric

Yes

The x coordinate of the upper left corner of the bounding rectangle for the arc.

y

numeric

Yes

The y coordinate of the upper left corner of the bounding rectangle for the arc.

width

numeric

Yes

The width of the bounding rectangle for the arc.

height

numeric

Yes

The height of the bounding rectangle for the arc.

startAngle

numeric

Yes

The starting angle of the arc in degrees.

archAngle

numeric

Yes

The angular extent of the arc in degrees.

filled

boolean

No

false

Whether the arc should be filled.

Returns

  • BoxImage: The modified BoxImage instance with the arc drawn.

Description

ImageDrawArc draws an arc on the specified image, using the provided bounding rectangle, start angle, and angular extent. The arc can be filled or just outlined, depending on the filled argument. The image can be passed directly or referenced by variable name.

Example

// Draw a filled arc
img = ImageDrawArc(myImage, 10, 20, 100, 50, 0, 180, true);

// Draw an outlined arc
img = ImageDrawArc(myImage, 10, 20, 100, 50, 45, 90);

See Also

  • ImageDrawRect

  • ImageDrawEllipse

Notes

  • All arguments except filled are required.

  • The image can be passed as a BoxImage object or as a variable name referencing an image.

  • Angles are specified in degrees.

  • The arc is drawn within the bounding rectangle defined by (x, y, width, height).

ImageCrop

Crops an image to a specified rectangular area. This BIF allows you to select a region of an image to keep, discarding the rest, in BoxLang.

Syntax

ImageCrop(name, x, y, width, height)

Arguments

Name
Type
Required
Description

name

any

Yes

The image or the name of a variable referencing an image to operate on.

x

numeric

Yes

The x coordinate of the upper left corner of the crop area.

y

numeric

Yes

The y coordinate of the upper left corner of the crop area.

width

numeric

Yes

The width of the crop area.

height

numeric

Yes

The height of the crop area.

Returns

  • BoxImage: The modified BoxImage instance cropped to the specified area.

Description

ImageCrop crops the specified image to a rectangular region, starting at (x, y) and extending to the given width and height. Only the selected area will remain visible after the operation. The image can be passed directly or referenced by variable name.

Example

// Crop a 100x50 region at position (10, 20)
img = ImageCrop(myImage, 10, 20, 100, 50);

See Also

  • ImageResize

  • ImageCopy

Notes

  • All arguments are required.

  • The image can be passed as a BoxImage object or as a variable name referencing an image.

ImageDrawBeveledRect

Draws a beveled rectangle on an image. This BIF allows you to specify the position, size, whether the bevel is raised, and whether the rectangle is filled in BoxLang.

Syntax

ImageDrawBeveledRect(name, x, y, width, height, raised [, filled])

Arguments

Name
Type
Required
Default
Description

name

any

Yes

The image or the name of a variable referencing an image to operate on.

x

numeric

Yes

The x coordinate of the upper left corner of the rectangle.

y

numeric

Yes

The y coordinate of the upper left corner of the rectangle.

width

numeric

Yes

The width of the rectangle.

height

numeric

Yes

The height of the rectangle.

raised

boolean

Yes

Whether the bevel is raised (true) or lowered (false).

filled

boolean

Yes

false

Whether the rectangle should be filled.

Returns

  • BoxImage: The modified BoxImage instance with the beveled rectangle drawn.

Description

ImageDrawBeveledRect draws a beveled rectangle on the specified image, using the provided position, size, and bevel style. The rectangle can be filled or just outlined, depending on the filled argument. The image can be passed directly or referenced by variable name.

Example

// Draw a filled, raised beveled rectangle
img = ImageDrawBeveledRect(myImage, 10, 20, 100, 50, true, true);

// Draw an outlined, lowered beveled rectangle
img = ImageDrawBeveledRect(myImage, 10, 20, 100, 50, false);

See Also

  • ImageDrawRect

  • ImageDrawArc

Notes

  • All arguments except filled are required.

  • The image can be passed as a BoxImage object or as a variable name referencing an image.

  • The bevel style is controlled by the raised argument.

  • The rectangle is drawn at (x, y) with the specified width and height.

ImageDrawCubicCurve

Draws a cubic Bézier curve on an image. This BIF allows you to specify the start point, two control points, and the end point for the curve in BoxLang.

Syntax

ImageDrawCubicCurve(name, x1, y1, ctrlx1, ctrly1, ctrlx2, ctrly2, x2, y2)

Arguments

Name
Type
Required
Description

name

any

Yes

The image or the name of a variable referencing an image to operate on.

x1

numeric

Yes

The x coordinate of the start point of the curve.

y1

numeric

Yes

The y coordinate of the start point of the curve.

ctrlx1

numeric

Yes

The x coordinate of the first control point.

ctrly1

numeric

Yes

The y coordinate of the first control point.

ctrlx2

numeric

Yes

The x coordinate of the second control point.

ctrly2

numeric

Yes

The y coordinate of the second control point.

x2

numeric

Yes

The x coordinate of the end point of the curve.

y2

numeric

Yes

The y coordinate of the end point of the curve.

Returns

  • BoxImage: The modified BoxImage instance with the cubic curve drawn.

Description

ImageDrawCubicCurve draws a cubic Bézier curve on the specified image, using the provided start point, two control points, and end point. The image can be passed directly or referenced by variable name.

Example

// Draw a cubic Bézier curve
img = ImageDrawCubicCurve(myImage, 10, 20, 30, 40, 50, 60, 70, 80);

See Also

  • ImageDrawQuadCurve

  • ImageDrawLine

Notes

  • All arguments are required.

  • The image can be passed as a BoxImage object or as a variable name referencing an image.

  • The curve is defined by the start point (x1, y1), control points (ctrlx1, ctrly1) and (ctrlx2, ctrly2), and end point (x2, y2).

ImageDrawLine

Draws a straight line on an image. This BIF allows you to specify the start and end points for the line in BoxLang.

Syntax

ImageDrawLine(name, x1, y1, x2, y2)

Arguments

Name
Type
Required
Description

name

any

Yes

The image or the name of a variable referencing an image to operate on.

x1

numeric

Yes

The x coordinate of the start point of the line.

y1

numeric

Yes

The y coordinate of the start point of the line.

x2

numeric

Yes

The x coordinate of the end point of the line.

y2

numeric

Yes

The y coordinate of the end point of the line.

Returns

  • BoxImage: The modified BoxImage instance with the line drawn.

Description

ImageDrawLine draws a straight line on the specified image, using the provided start and end points. The image can be passed directly or referenced by variable name.

Example

// Draw a line from (10, 20) to (100, 50)
img = ImageDrawLine(myImage, 10, 20, 100, 50);

See Also

  • ImageDrawCubicCurve

  • ImageDrawQuadCurve

Notes

  • All arguments are required.

  • The image can be passed as a BoxImage object or as a variable name referencing an image.

  • The line is drawn from (x1, y1) to (x2, y2).

ImageDrawOval

Draws an oval (ellipse) on an image. This BIF allows you to specify the position, size, and whether the oval is filled in BoxLang.

Syntax

ImageDrawOval(name, x, y, width, height [, filled])

Arguments

Name
Type
Required
Default
Description

name

any

Yes

The image or the name of a variable referencing an image to operate on.

x

numeric

Yes

The x coordinate of the upper left corner of the bounding rectangle for the oval.

y

numeric

Yes

The y coordinate of the upper left corner of the bounding rectangle for the oval.

width

numeric

Yes

The width of the bounding rectangle for the oval.

height

numeric

Yes

The height of the bounding rectangle for the oval.

filled

boolean

No

false

Whether the oval should be filled.

Returns

  • BoxImage: The modified BoxImage instance with the oval drawn.

Description

ImageDrawOval draws an oval (ellipse) on the specified image, using the provided bounding rectangle. The oval can be filled or just outlined, depending on the filled argument. The image can be passed directly or referenced by variable name.

Example

// Draw a filled oval
img = ImageDrawOval(myImage, 10, 20, 100, 50, true);

// Draw an outlined oval
img = ImageDrawOval(myImage, 10, 20, 100, 50);

See Also

  • ImageDrawRect

  • ImageDrawArc

Notes

  • All arguments except filled are required.

  • The image can be passed as a BoxImage object or as a variable name referencing an image.

  • The oval is drawn within the bounding rectangle defined by (x, y, width, height).

ImageDrawLines

Draws multiple connected lines or a polygon on an image. This BIF allows you to specify arrays of x and y coordinates, and optionally draw a filled polygon in BoxLang.

Syntax

ImageDrawLines(name, xCoords, yCoords [, isPolygon] [, filled])

Arguments

Name
Type
Required
Default
Description

name

any

Yes

The image or the name of a variable referencing an image to operate on.

xCoords

array

Yes

Array of x coordinates for the points.

yCoords

array

Yes

Array of y coordinates for the points.

isPolygon

boolean

No

false

If true, draws a closed polygon; if false, draws open lines.

filled

boolean

No

false

If true and isPolygon is true, fills the polygon.

Returns

  • BoxImage: The modified BoxImage instance with the lines or polygon drawn.

Description

ImageDrawLines draws a series of connected lines on the specified image, using the provided arrays of x and y coordinates. If isPolygon is true, the lines are closed to form a polygon, which can be filled if filled is also true. The image can be passed directly or referenced by variable name.

Example

// Draw open lines connecting points
img = ImageDrawLines(myImage, [10, 50, 100], [20, 60, 80]);

// Draw a filled triangle
img = ImageDrawLines(myImage, [10, 50, 100], [20, 60, 80], true, true);

See Also

  • ImageDrawLine

  • ImageDrawPolygon

Notes

  • The xCoords and yCoords arrays must be of equal length.

  • The image can be passed as a BoxImage object or as a variable name referencing an image.

  • If isPolygon is true and filled is true, the polygon will be filled.

ImageDrawPoint

Draws a single point on an image. This BIF allows you to specify the position of the point in BoxLang.

Syntax

ImageDrawPoint(name, x, y)

Arguments

Name
Type
Required
Description

name

any

Yes

The image or the name of a variable referencing an image to operate on.

x

numeric

Yes

The x coordinate of the point.

y

numeric

Yes

The y coordinate of the point.

Returns

  • BoxImage: The modified BoxImage instance with the point drawn.

Description

ImageDrawPoint draws a single point on the specified image at the given (x, y) coordinates. The image can be passed directly or referenced by variable name.

Example

// Draw a point at (10, 20)
img = ImageDrawPoint(myImage, 10, 20);

See Also

  • ImageDrawLine

  • ImageDrawRect

Notes

  • All arguments are required.

  • The image can be passed as a BoxImage object or as a variable name referencing an image.

  • The point is drawn as a 1x1 filled rectangle at (x, y).

ImageDrawQuadraticCurve

Draws a quadratic Bézier curve on an image. This BIF allows you to specify the control point, start point, and end point for the curve in BoxLang.

Syntax

ImageDrawQuadraticCurve(name, ctrlx1, ctrly1, x1, y1, x2, y2)

Arguments

Name
Type
Required
Description

name

any

Yes

The image or the name of a variable referencing an image to operate on.

ctrlx1

numeric

Yes

The x coordinate of the control point.

ctrly1

numeric

Yes

The y coordinate of the control point.

x1

numeric

Yes

The x coordinate of the start point of the curve.

y1

numeric

Yes

The y coordinate of the start point of the curve.

x2

numeric

Yes

The x coordinate of the end point of the curve.

y2

numeric

Yes

The y coordinate of the end point of the curve.

Returns

  • BoxImage: The modified BoxImage instance with the quadratic curve drawn.

Description

ImageDrawQuadraticCurve draws a quadratic Bézier curve on the specified image, using the provided control point, start point, and end point. The image can be passed directly or referenced by variable name.

Example

// Draw a quadratic Bézier curve
img = ImageDrawQuadraticCurve(myImage, 30, 40, 10, 20, 70, 80);

See Also

  • ImageDrawCubicCurve

  • ImageDrawLine

Notes

  • All arguments are required.

  • The image can be passed as a BoxImage object or as a variable name referencing an image.

  • The curve is defined by the control point (ctrlx1, ctrly1), start point (x1, y1), and end point (x2, y2).

ImageDrawRect

Draws a rectangle on an image. This BIF allows you to specify the position, size, and whether the rectangle is filled in BoxLang.

Syntax

ImageDrawRect(name, x, y, width, height [, filled])

Arguments

Name
Type
Required
Default
Description

name

any

Yes

The image or the name of a variable referencing an image to operate on.

x

numeric

Yes

The x coordinate of the upper left corner of the rectangle.

y

numeric

Yes

The y coordinate of the upper left corner of the rectangle.

width

numeric

Yes

The width of the rectangle.

height

numeric

Yes

The height of the rectangle.

filled

boolean

No

false

Whether the rectangle should be filled.

Returns

  • BoxImage: The modified BoxImage instance with the rectangle drawn.

Description

ImageDrawRect draws a rectangle on the specified image, using the provided position and size. The rectangle can be filled or just outlined, depending on the filled argument. The image can be passed directly or referenced by variable name.

Example

// Draw a filled rectangle
img = ImageDrawRect(myImage, 10, 20, 100, 50, true);

// Draw an outlined rectangle
img = ImageDrawRect(myImage, 10, 20, 100, 50);

See Also

  • ImageDrawOval

  • ImageDrawArc

Notes

  • All arguments except filled are required.

  • The image can be passed as a BoxImage object or as a variable name referencing an image.

  • The rectangle is drawn at (x, y) with the specified width and height.

ImageDrawRoundRect

Draws a rounded rectangle on an image. This BIF allows you to specify the position, size, corner arc dimensions, and whether the rectangle is filled in BoxLang.

Syntax

ImageDrawRoundRect(name, x, y, width, height, arcWidth, arcHeight [, filled])

Arguments

Name
Type
Required
Default
Description

name

any

Yes

The image or the name of a variable referencing an image to operate on.

x

numeric

Yes

The x coordinate of the upper left corner of the rectangle.

y

numeric

Yes

The y coordinate of the upper left corner of the rectangle.

width

numeric

Yes

The width of the rectangle.

height

numeric

Yes

The height of the rectangle.

arcWidth

numeric

Yes

The horizontal diameter of the arc at the four corners.

arcHeight

numeric

Yes

The vertical diameter of the arc at the four corners.

filled

boolean

No

false

Whether the rectangle should be filled.

Returns

  • BoxImage: The modified BoxImage instance with the rounded rectangle drawn.

Description

ImageDrawRoundRect draws a rectangle with rounded corners on the specified image, using the provided position, size, and arc dimensions. The rectangle can be filled or just outlined, depending on the filled argument. The image can be passed directly or referenced by variable name.

Example

// Draw a filled rounded rectangle
img = ImageDrawRoundRect(myImage, 10, 20, 100, 50, 20, 20, true);

// Draw an outlined rounded rectangle
img = ImageDrawRoundRect(myImage, 10, 20, 100, 50, 20, 20);

See Also

  • ImageDrawRect

  • ImageDrawOval

Notes

  • All arguments except filled are required.

  • The image can be passed as a BoxImage object or as a variable name referencing an image.

  • The rectangle is drawn at (x, y) with the specified width, height, and corner arc dimensions.

ImageDrawText

Draws text on an image. This BIF allows you to specify the text, position, and optional attributes for rendering text in BoxLang.

Syntax

ImageDrawText(name, str, x, y [, attributeCollection])

Arguments

Name
Type
Required
Default
Description

name

any

Yes

The image or the name of a variable referencing an image to operate on.

str

string

Yes

The text string to draw.

x

numeric

Yes

The x coordinate for the text position.

y

numeric

Yes

The y coordinate for the text position.

attributeCollection

struct

No

Optional struct of attributes for text rendering (e.g., font, size, color).

Returns

  • BoxImage: The modified BoxImage instance with the text drawn.

Description

ImageDrawText draws a string of text on the specified image at the given (x, y) coordinates. You can optionally provide an attribute collection struct to control font, size, color, and other text rendering options. The image can be passed directly or referenced by variable name.

Example

// Draw text at (10, 20)
img = ImageDrawText(myImage, "Hello World", 10, 20);

// Draw text with attributes
attrs = { font: "Arial", size: 24, color: "red" };
img = ImageDrawText(myImage, "Hello World", 10, 20, attrs);

See Also

  • ImageDrawRect

  • ImageDrawPoint

Notes

  • All arguments except attributeCollection are required.

  • The image can be passed as a BoxImage object or as a variable name referencing an image.

  • The attribute collection struct can include font, size, color, and other text properties.

ImageFlip

Flips or transposes an image. This BIF allows you to specify the type of flip or transpose operation to apply in BoxLang.

Syntax

ImageFlip(name, transpose)

Arguments

Name
Type
Required
Description

name

any

Yes

The image or the name of a variable referencing an image to operate on.

transpose

string

Yes

The type of flip or transpose operation (e.g., "horizontal", "vertical", "rotate90", "rotate180", "rotate270").

Returns

  • BoxImage: The modified BoxImage instance after the flip or transpose operation.

Description

ImageFlip flips or transposes the specified image according to the given operation. Supported values for transpose typically include:

  • horizontal: Flip the image horizontally (mirror left/right)

  • vertical: Flip the image vertically (mirror top/bottom)

  • rotate90: Rotate the image 90 degrees

  • rotate180: Rotate the image 180 degrees

  • rotate270: Rotate the image 270 degrees

The image can be passed directly or referenced by variable name.

Example

// Flip an image horizontally
img = ImageFlip(myImage, "horizontal");

// Rotate an image 90 degrees
img = ImageFlip(myImage, "rotate90");

See Also

  • ImageRotate

  • ImageCrop

Notes

  • All arguments are required.

  • The image can be passed as a BoxImage object or as a variable name referencing an image.

  • Supported transpose values may vary depending on implementation.

ImageGetBlob

Returns the raw binary data (blob) of an image. This BIF allows you to extract the image as a byte array in BoxLang.

Syntax

ImageGetBlob(name)

Arguments

Name
Type
Required
Description

name

any

Yes

The image or the name of a variable referencing an image to operate on.

Returns

  • byte[]: The raw binary data (blob) of the image.

Description

ImageGetBlob extracts the raw binary data from the specified image. This is useful for saving the image to disk, sending it over a network, or further processing. The image can be passed directly or referenced by variable name.

Example

// Get the binary data of an image
blob = ImageGetBlob(myImage);

See Also

  • ImageRead

  • ImageWrite

Notes

  • The image can be passed as a BoxImage object or as a variable name referencing an image.

  • The returned value is a byte array representing the image data.

ImageGetBufferedImage

Returns the underlying Java BufferedImage object for an image. This BIF allows advanced users to access the raw Java image object in BoxLang for direct manipulation or integration with Java APIs.

Syntax

ImageGetBufferedImage(name)

Arguments

Name
Type
Required
Description

name

any

Yes

The image or the name of a variable referencing an image to operate on.

Returns

  • BufferedImage: The underlying Java BufferedImage object for the image.

Description

ImageGetBufferedImage returns the Java BufferedImage object associated with the specified image. This is useful for advanced operations, interoperability with Java libraries, or custom image processing. The image can be passed directly or referenced by variable name.

Example

// Get the BufferedImage object from a BoxImage
buffered = ImageGetBufferedImage(myImage);

See Also

  • ImageGetBlob

  • ImageRead

Notes

  • The image can be passed as a BoxImage object or as a variable name referencing an image.

  • The returned value is a Java BufferedImage object, which may require Java interop for further use.

ImageGetExifMetaData

Returns the EXIF metadata from an image. This BIF allows you to extract camera and image metadata in BoxLang, such as date taken, camera model, orientation, and more.

Syntax

ImageGetExifMetaData(name)

Arguments

Name
Type
Required
Description

name

any

Yes

The image or the name of a variable referencing an image, or a file path to an image.

Returns

  • IStruct: A struct containing the EXIF metadata from the image.

Description

ImageGetExifMetaData extracts EXIF metadata from the specified image. You can pass a BoxImage object, a variable name referencing an image, or a file path string. The returned struct contains key-value pairs for available EXIF metadata fields, such as camera make/model, date/time, orientation, GPS info, and more.

Example

// Get EXIF metadata from a BoxImage
meta = ImageGetExifMetaData(myImage);

// Get EXIF metadata from an image file path
meta = ImageGetExifMetaData("/path/to/image.jpg");

See Also

  • ImageGetBlob

  • ImageRead

Notes

  • The image can be passed as a BoxImage object, a variable name referencing an image, or a file path string.

  • If the image cannot be read or metadata cannot be processed, an error is thrown.

  • The returned struct contains only available EXIF fields for the image.

ImageGetHeight

Returns the height (in pixels) of an image. This BIF allows you to retrieve the vertical dimension of an image in BoxLang.

Syntax

ImageGetHeight(name)

Arguments

Name
Type
Required
Description

name

any

Yes

The image or the name of a variable referencing an image to operate on.

Returns

  • Integer: The height of the image in pixels.

Description

ImageGetHeight returns the height (number of pixels vertically) of the specified image. The image can be passed directly or referenced by variable name.

Example

// Get the height of an image
height = ImageGetHeight(myImage);

See Also

  • ImageGetWidth

  • ImageResize

Notes

  • The image can be passed as a BoxImage object or as a variable name referencing an image.

  • The returned value is the height in pixels.

ImageGetIPTCMetadata

Returns the IPTC metadata from an image. This BIF allows you to extract professional image metadata in BoxLang, such as copyright, author, headline, and more.

Syntax

ImageGetIPTCMetadata(name)

Arguments

Name
Type
Required
Description

name

any

Yes

The image or the name of a variable referencing an image, or a file path to an image.

Returns

  • IStruct: A struct containing the IPTC metadata from the image.

Description

ImageGetIPTCMetadata extracts IPTC metadata from the specified image. You can pass a BoxImage object, a variable name referencing an image, or a file path string. The returned struct contains key-value pairs for available IPTC metadata fields, such as copyright, author, headline, caption, keywords, and more.

Example

// Get IPTC metadata from a BoxImage
meta = ImageGetIPTCMetadata(myImage);

// Get IPTC metadata from an image file path
meta = ImageGetIPTCMetadata("/path/to/image.jpg");

See Also

  • ImageGetExifMetaData

  • ImageGetBlob

Notes

  • The image can be passed as a BoxImage object, a variable name referencing an image, or a file path string.

  • If the image cannot be read or metadata cannot be processed, an error is thrown.

  • The returned struct contains only available IPTC fields for the image.

ImageGetWidth

Returns the width (in pixels) of an image. This BIF allows you to retrieve the horizontal dimension of an image in BoxLang.

Syntax

ImageGetWidth(name)

Arguments

Name
Type
Required
Description

name

any

Yes

The image or the name of a variable referencing an image to operate on.

Returns

  • Integer: The width of the image in pixels.

Description

ImageGetWidth returns the width (number of pixels horizontally) of the specified image. The image can be passed directly or referenced by variable name.

Example

// Get the width of an image
width = ImageGetWidth(myImage);

See Also

  • ImageGetHeight

  • ImageResize

Notes

  • The image can be passed as a BoxImage object or as a variable name referencing an image.

  • The returned value is the width in pixels.

ImageGetIPTCTag

Returns the value of a specific IPTC metadata tag from an image. This BIF allows you to extract a single IPTC field in BoxLang, such as copyright, author, headline, or any other IPTC tag.

Syntax

ImageGetIPTCTag(name, tagName)

Arguments

Name
Type
Required
Description

name

any

Yes

The image or the name of a variable referencing an image, or a file path to an image.

tagName

string

Yes

The name of the IPTC tag to retrieve (e.g., "Copyright", "Author", "Headline").

Returns

  • Object: The value of the specified IPTC tag, or null if not present.

Description

ImageGetIPTCTag extracts the value of a specific IPTC metadata tag from the specified image. You can pass a BoxImage object, a variable name referencing an image, or a file path string. The tag name should match the IPTC field you want to retrieve.

Example

// Get the copyright tag from a BoxImage
copyright = ImageGetIPTCTag(myImage, "Copyright");

// Get the headline tag from an image file path
headline = ImageGetIPTCTag("/path/to/image.jpg", "Headline");

See Also

  • ImageGetIPTCMetadata

  • ImageGetExifMetaData

Notes

  • The image can be passed as a BoxImage object, a variable name referencing an image, or a file path string.

  • If the image cannot be read or the tag is not present, null is returned.

  • Tag names are case-sensitive and must match the IPTC field name.

ImageInfo

Returns general information about an image. This BIF allows you to retrieve a struct of image properties in BoxLang, such as width, height, format, color model, and more.

Syntax

ImageInfo(name)

Arguments

Name
Type
Required
Description

name

any

Yes

The image or the name of a variable referencing an image to operate on.

Returns

  • IStruct: A struct containing general information about the image.

Description

ImageInfo returns a struct with general properties of the specified image. Typical fields include width, height, format, color model, and other metadata. The image can be passed directly or referenced by variable name.

Example

// Get image info
info = ImageInfo(myImage);
// info might contain { width: 800, height: 600, format: "jpg", colorModel: "RGB" }

See Also

  • ImageGetWidth

  • ImageGetHeight

  • ImageGetExifMetaData

Notes

  • The image can be passed as a BoxImage object or as a variable name referencing an image.

  • The returned struct contains general image properties and may vary by image type.

ImageGrayScale / ImageGreyScale

Converts an image to grayscale. This BIF allows you to remove color and produce a black-and-white version of an image in BoxLang.

Syntax

ImageGrayScale(name)
ImageGreyScale(name)

Arguments

Name
Type
Required
Description

name

any

Yes

The image or the name of a variable referencing an image to operate on.

Returns

  • BoxImage: The modified BoxImage instance in grayscale.

Description

ImageGrayScale (also available as ImageGreyScale) converts the specified image to grayscale, removing all color information. The image can be passed directly or referenced by variable name.

Example

// Convert an image to grayscale
grayImg = ImageGrayScale(myImage);
// Or using the alias
grayImg = ImageGreyScale(myImage);

See Also

  • ImageInvert

  • ImageBlur

Notes

  • The image can be passed as a BoxImage object or as a variable name referencing an image.

  • Both grayScale and greyScale member methods are available for BoxImage objects.

ImageNegative

Inverts the colors of an image to produce a photographic negative. This BIF allows you to create a negative version of an image in BoxLang.

Syntax

ImageNegative(name)

Arguments

Name
Type
Required
Description

name

any

Yes

The image or the name of a variable referencing an image to operate on.

Returns

  • BoxImage: The modified BoxImage instance with inverted colors.

Description

ImageNegative inverts the colors of the specified image, producing a photographic negative effect. The image can be passed directly or referenced by variable name.

Example

// Create a negative of an image
negImg = ImageNegative(myImage);

See Also

  • ImageGrayScale

  • ImageInvert

Notes

  • The image can be passed as a BoxImage object or as a variable name referencing an image.

  • The negative effect is applied to all color channels.

ImageNew

Syntax

ImageNew( source [, width] [, height] [, imageType] [, color] )

Arguments

Name
Type
Required
Default
Description

source

any

Yes

The source for the image. Can be a file path, URL, BufferedImage, BoxImage, or empty string.

width

numeric

No

Width of the new image (required if creating a blank image).

height

numeric

No

Height of the new image (required if creating a blank image).

imageType

string

No

Type of image to create (e.g., "RGB", "ARGB").

color

string

No

black

Background color for a new blank image.

Returns

BoxImage — The newly created image object.

Description

Creates a new image from a variety of sources:

  • If source is a file path or URL, loads the image from that location.

  • If source is a BufferedImage, wraps it in a BoxImage.

  • If source is a BoxImage, returns a copy of it.

  • If source is an empty string, creates a blank image using the provided width, height, imageType, and color arguments.

Example

// Create from file path
img = ImageNew( "images/photo.png" );

// Create from URL
img = ImageNew( "https://example.com/image.jpg" );

// Create blank image
img = ImageNew( "", 400, 300, "RGB", "white" );

// Copy an existing BoxImage
imgCopy = ImageNew( img );

Related BIFs

  • ImageCopy

  • ImageInfo

  • ImageGetWidth

  • ImageGetHeight

Notes

  • If creating a blank image, width and height are required.

  • The imageType should match supported types (e.g., "RGB", "ARGB").

  • If loading from a file or URL fails, an error is thrown.

  • The default color for blank images is black unless specified.

ImageOverlay

Syntax

ImageOverlay( image1, image2 [, rule] [, transparency] )

Or as a member:

someImage.overlay( imageToDraw [, rule] [, transparency] )

Arguments

Name
Type
Required
Default
Description

image1

any

Yes

The base image to overlay onto. Can be a BoxImage object or image name.

image2

any

Yes

The image to overlay. Can be a BoxImage object or image name.

rule

string

No

SRC_OVER

The compositing rule for overlay (e.g., "SRC_OVER", "SRC_ATOP").

transparency

numeric

No

0.25

The transparency level for the overlay (0.0 = fully transparent, 1.0 = opaque).

Returns

BoxImage — The base image with the overlay applied.

Description

Overlays one image (image2) onto another (image1) using the specified compositing rule and transparency. This allows for blending images with various effects, such as watermarking or combining graphics.

Example

// Overlay image2 onto image1 with default rule and transparency
result = ImageOverlay( image1, image2 );

// Overlay with custom rule and transparency
result = ImageOverlay( image1, image2, "SRC_ATOP", 0.5 );

// As a member function
image1.overlay( image2, "SRC_OVER", 0.75 );

Related BIFs

  • ImageCopy

  • ImageDrawImage

  • ImageNew

Notes

  • Both image1 and image2 can be BoxImage objects or the names of images in the current context.

  • The rule argument determines how the overlay is composited. Common values include "SRC_OVER" and "SRC_ATOP".

  • The operation modifies the base image in place when used as a member function.

  • Returns the modified image object for chaining or further processing.

ImagePaste

Syntax

ImagePaste( image1, image2 [, x] [, y] )
ImageDrawImage( image1, image2 [, x] [, y] )

Or as a member:

someImage.paste( imageToDraw [, x] [, y] )
someImage.drawImage( imageToDraw [, x] [, y] )

Arguments

Name
Type
Required
Default
Description

image1

any

Yes

The base image to paste onto. Can be a BoxImage object or image name.

image2

any

Yes

The image to paste. Can be a BoxImage object or image name.

x

numeric

No

0

The x-coordinate where the image will be pasted.

y

numeric

No

0

The y-coordinate where the image will be pasted.

Returns

BoxImage — The base image with the pasted image applied.

Description

Pastes one image (image2) onto another (image1) at the specified coordinates. Useful for combining images, adding watermarks, or overlaying graphics at precise locations.

Example

// Paste image2 onto image1 at (100, 50)
result = ImagePaste( image1, image2, 100, 50 );

// Using the alias
result = ImageDrawImage( image1, image2, 200, 75 );

// As a member function
image1.paste( image2, 10, 10 );
image1.drawImage( image2, 0, 0 );

Related BIFs

  • ImageOverlay

  • ImageCopy

  • ImageNew

Notes

  • Both image1 and image2 can be BoxImage objects or the names of images in the current context.

  • The default coordinates are (0, 0) if not specified.

  • The operation modifies the base image in place when used as a member function.

  • Returns the modified image object for chaining or further processing.

  • This BIF is also available as ImageDrawImage and as member functions paste and drawImage.

ImageRead

Syntax

ImageRead( path )

Arguments

Name
Type
Required
Description

path

String

Yes

The file path or URL to the image to read.

Returns

BoxImage — The image object loaded from the specified path.

Description

Loads an image from a file path or URL and returns it as a BoxImage object. This BIF is used to import images into BoxLang for further processing or manipulation.

Example

// Load an image from a file
img = ImageRead( "images/photo.png" );

// Load an image from a URL
img = ImageRead( "https://example.com/image.jpg" );

Related BIFs

  • ImageNew

  • ImageCopy

  • ImageGetWidth

  • ImageGetHeight

Notes

  • The path argument must be a non-empty string representing a valid file path or URL.

  • If the image cannot be loaded, an error is thrown.

  • Returns a BoxImage object for use in other image BIFs.

ImageResize

Syntax

ImageResize( name, width, height [, interpolation] [, blurFactor] )

Or as a member:

someImage.resize( width, height [, interpolation] [, blurFactor] )

Arguments

Name
Type
Required
Default
Description

name

any

Yes

The image to resize. Can be a BoxImage object or image name.

width

numeric

Yes

The target width for the resized image.

height

numeric

Yes

The target height for the resized image.

interpolation

String

No

bilinear

The interpolation method (e.g., "bilinear", "nearest").

blurFactor

numeric

No

1

The blur factor to apply during resizing.

Returns

BoxImage — The resized image object.

Description

Resizes an image to the specified width and height using the chosen interpolation method and blur factor. Useful for scaling images up or down while controlling quality and smoothing.

Example

// Resize image to 200x100 using default interpolation and blur
result = ImageResize( myImage, 200, 100 );

// Resize with custom interpolation and blur factor
result = ImageResize( myImage, 400, 300, "nearest", 2 );

// As a member function
myImage.resize( 800, 600, "bilinear", 1 );

Related BIFs

  • ImageCrop

  • ImageFlip

  • ImageGrayScale

Notes

  • The name argument can be a BoxImage object or the name of an image variable in the current context.

  • Supported interpolation methods may include "bilinear", "nearest", and others.

  • The operation modifies the image in place when used as a member function.

  • Returns the modified image object for chaining or further processing.

ImageReadBase64

Syntax

ImageReadBase64( string )

Arguments

Name
Type
Required
Description

string

String

Yes

The base64-encoded string representing the image data.

Returns

BoxImage — The image object decoded from the base64 string.

Description

Decodes a base64-encoded string into an image and returns it as a BoxImage object. This BIF is useful for importing images that are stored or transmitted as base64 strings, such as those embedded in data URIs or received from APIs.

Example

// Load an image from a base64 string
img = ImageReadBase64( myBase64String );

Related BIFs

  • ImageRead

  • ImageNew

  • ImageGetBlob

Notes

  • The string argument must be a non-empty base64-encoded string representing valid image data.

  • If the image cannot be decoded, an error is thrown.

  • Returns a BoxImage object for use in other image BIFs.

ImageRotate

Syntax

ImageRotate( name, angle )

Or as a member:

someImage.rotate( angle )

Arguments

Name
Type
Required
Description

name

any

Yes

The image to rotate. Can be a BoxImage object or image name.

angle

numeric

Yes

The angle (in degrees) to rotate the image.

Returns

BoxImage — The rotated image object.

Description

Rotates an image by the specified angle (in degrees). Positive values rotate clockwise, negative values rotate counterclockwise. Useful for correcting orientation or creating rotated graphics.

Example

// Rotate image 90 degrees clockwise
result = ImageRotate( myImage, 90 );

// Rotate image 45 degrees counterclockwise
result = ImageRotate( myImage, -45 );

// As a member function
myImage.rotate( 180 );

Related BIFs

  • ImageResize

  • ImageFlip

  • ImageCrop

Notes

  • The name argument can be a BoxImage object or the name of an image variable in the current context.

  • The operation modifies the image in place when used as a member function.

  • Returns the modified image object for chaining or further processing.

  • Only the angle argument is supported; x and y arguments are not implemented.

ImageRotateDrawingAxis

Syntax

ImageRotateDrawingAxis( name, angle [, x] [, y] )

Or as a member:

someImage.rotateDrawingAxis( angle [, x] [, y] )

Arguments

Name
Type
Required
Default
Description

name

any

Yes

The image to rotate. Can be a BoxImage object or image name.

angle

numeric

Yes

The angle (in degrees) to rotate the image.

x

numeric

No

0

The x-coordinate of the rotation axis.

y

numeric

No

0

The y-coordinate of the rotation axis.

Returns

BoxImage — The rotated image object.

Description

Rotates an image by the specified angle (in degrees) around a custom axis defined by the x and y coordinates. Useful for advanced graphics operations where rotation needs to occur around a specific point rather than the default center.

Example

// Rotate image 90 degrees around axis (100, 50)
result = ImageRotateDrawingAxis( myImage, 90, 100, 50 );

// As a member function
myImage.rotateDrawingAxis( 45, 200, 100 );

Related BIFs

  • ImageRotate

  • ImageResize

  • ImageFlip

Notes

  • The name argument can be a BoxImage object or the name of an image variable in the current context.

  • The operation modifies the image in place when used as a member function.

  • Returns the modified image object for chaining or further processing.

  • The x and y arguments specify the axis of rotation; defaults to (0, 0) if not provided.

ImageScaleToFit

Syntax

ImageScaleToFit( name, width [, height] [, interpolation] )

Or as a member:

someImage.scaleToFit( width [, height] [, interpolation] )

Arguments

Name
Type
Required
Default
Description

name

any

Yes

The image to scale. Can be a BoxImage object or image name.

width

any

Yes

The target width for scaling.

height

any

No

The target height for scaling (optional; if omitted, scales by width).

interpolation

String

No

bilinear

The interpolation method (e.g., "bilinear", "nearest").

Returns

BoxImage — The scaled image object.

Description

Scales an image to fit the specified width or height, maintaining the aspect ratio. If both width and height are provided, width takes precedence. The interpolation method controls the quality of scaling.

Example

// Scale image to fit width 400
result = ImageScaleToFit( myImage, 400 );

// Scale image to fit height 300
result = ImageScaleToFit( myImage, null, 300 );

// Scale with custom interpolation
result = ImageScaleToFit( myImage, 800, null, "nearest" );

// As a member function
myImage.scaleToFit( 600, null, "bilinear" );

Related BIFs

  • ImageResize

  • ImageCrop

  • ImageRotate

Notes

  • The name argument can be a BoxImage object or the name of an image variable in the current context.

  • If both width and height are provided, width is used for scaling.

  • Supported interpolation methods may include "bilinear", "nearest", and others.

  • The operation modifies the image in place when used as a member function.

  • Returns the modified image object for chaining or further processing.

ImageSetAntiAliasing

Syntax

ImageSetAntiAliasing( name [, antialias] )

Or as a member:

someImage.setAntiAliasing( [antialias] )

Arguments

Name
Type
Required
Default
Description

name

any

Yes

The image to set anti-aliasing for. Can be a BoxImage object or image name.

antialias

boolean

No

true

Whether to enable (true) or disable (false) anti-aliasing.

Returns

BoxImage — The image object with updated anti-aliasing setting.

Description

Enables or disables anti-aliasing for the specified image. Anti-aliasing smooths the edges of graphics and text, improving visual quality when drawing or transforming images.

Example

// Enable anti-aliasing
result = ImageSetAntiAliasing( myImage, true );

// Disable anti-aliasing
result = ImageSetAntiAliasing( myImage, false );

// As a member function
myImage.setAntiAliasing( true );

Related BIFs

  • ImageDrawText

  • ImageDrawLine

  • ImageResize

Notes

  • The name argument can be a BoxImage object or the name of an image variable in the current context.

  • The operation modifies the image in place when used as a member function.

  • Returns the modified image object for chaining or further processing.

  • Anti-aliasing is recommended for smoother graphics and text rendering.

ImageSetBackgroundColor

Syntax

ImageSetBackgroundColor( name, color )

Or as a member:

someImage.setBackgroundColor( color )

Arguments

Name
Type
Required
Description

name

any

Yes

The image to set the background color for. Can be a BoxImage object or image name.

color

String

Yes

The background color to set (e.g., "white", "#FF0000").

Returns

BoxImage — The image object with updated background color.

Description

Sets the background color of the specified image. Useful for preparing images for compositing, overlays, or ensuring a consistent background before further processing.

Example

// Set background color to white
result = ImageSetBackgroundColor( myImage, "white" );

// Set background color using hex value
result = ImageSetBackgroundColor( myImage, "#00FF00" );

// As a member function
myImage.setBackgroundColor( "black" );

Related BIFs

  • ImageSetAntiAliasing

  • ImageDrawRect

  • ImageNew

Notes

  • The name argument can be a BoxImage object or the name of an image variable in the current context.

  • The operation modifies the image in place when used as a member function.

  • Returns the modified image object for chaining or further processing.

  • The color argument accepts named colors or hex color codes.

ImageSetDrawingColor

Syntax

ImageSetDrawingColor( name, color )

Or as a member:

someImage.setDrawingColor( color )

Arguments

Name
Type
Required
Description

name

any

Yes

The image to set the drawing color for. Can be a BoxImage object or image name.

color

String

Yes

The drawing color to set (e.g., "red", "#0000FF").

Returns

BoxImage — The image object with updated drawing color.

Description

Sets the drawing color for the specified image. This color will be used for subsequent drawing operations such as lines, shapes, and text.

Example

// Set drawing color to blue
result = ImageSetDrawingColor( myImage, "blue" );

// Set drawing color using hex value
result = ImageSetDrawingColor( myImage, "#FF00FF" );

// As a member function
myImage.setDrawingColor( "green" );

Related BIFs

  • ImageSetBackgroundColor

  • ImageDrawLine

  • ImageDrawText

Notes

  • The name argument can be a BoxImage object or the name of an image variable in the current context.

  • The operation modifies the image in place when used as a member function.

  • Returns the modified image object for chaining or further processing.

  • The color argument accepts named colors or hex color codes.

ImageSetDrawingStroke

Syntax

ImageSetDrawingStroke( name [, attributeCollection] )

Or as a member:

someImage.setDrawingStroke( [attributeCollection] )

Arguments

Name
Type
Required
Description

name

any

Yes

The image to set the drawing stroke for. Can be a BoxImage object or image name.

attributeCollection

struct

No

A struct of stroke attributes (e.g., thickness, dash pattern).

Returns

BoxImage — The image object with updated drawing stroke settings.

Description

Sets the drawing stroke attributes for the specified image. Stroke attributes control how lines and shapes are drawn, such as thickness, dash patterns, and more.

Example

// Set stroke thickness to 5
result = ImageSetDrawingStroke( myImage, { thickness: 5 } );

// Set stroke with dash pattern
result = ImageSetDrawingStroke( myImage, { thickness: 3, dash: [4, 2] } );

// As a member function
myImage.setDrawingStroke( { thickness: 2 } );

Related BIFs

  • ImageSetDrawingColor

  • ImageDrawLine

  • ImageDrawRect

Notes

  • The name argument can be a BoxImage object or the name of an image variable in the current context.

  • The operation modifies the image in place when used as a member function.

  • Returns the modified image object for chaining or further processing.

  • The attributeCollection struct can include keys like thickness, dash, and other stroke properties.

ImageSetDrawingTransparency

Syntax

ImageSetDrawingTransparency( name, percent )

Or as a member:

someImage.setDrawingTransparency( percent )

Arguments

Name
Type
Required
Description

name

any

Yes

The image to set drawing transparency for. Can be a BoxImage object or image name.

percent

numeric

Yes

The transparency percentage (0-100) for drawing operations.

Returns

BoxImage — The image object with updated drawing transparency.

Description

Sets the drawing transparency for the specified image. This affects the opacity of subsequent drawing operations (lines, shapes, text) on the image. A value of 0 is fully transparent, 100 is fully opaque.

Example

// Set drawing transparency to 50%
result = ImageSetDrawingTransparency( myImage, 50 );

// As a member function
myImage.setDrawingTransparency( 75 );

Related BIFs

  • ImageSetDrawingColor

  • ImageSetDrawingStroke

  • ImageDrawText

Notes

  • The name argument can be a BoxImage object or the name of an image variable in the current context.

  • The operation modifies the image in place when used as a member function.

  • Returns the modified image object for chaining or further processing.

  • The percent argument should be between 0 and 100.

ImageSharpen

Syntax

ImageSharpen( name [, gain] )

Or as a member:

someImage.sharpen( [gain] )

Arguments

Name
Type
Required
Default
Description

name

any

Yes

The image to sharpen. Can be a BoxImage object or image name.

gain

numeric

No

1

The sharpening gain factor. Higher values increase sharpness.

Returns

BoxImage — The sharpened image object.

Description

Applies a sharpening filter to the specified image. The gain argument controls the intensity of the sharpening effect. Useful for enhancing image details and improving clarity.

Example

// Sharpen image with default gain
result = ImageSharpen( myImage );

// Sharpen image with custom gain
result = ImageSharpen( myImage, 2.5 );

// As a member function
myImage.sharpen( 1.5 );

Related BIFs

  • ImageBlur

  • ImageGrayScale

  • ImageResize

Notes

  • The name argument can be a BoxImage object or the name of an image variable in the current context.

  • The operation modifies the image in place when used as a member function.

  • Returns the modified image object for chaining or further processing.

  • The gain argument should be a positive number; higher values produce a stronger sharpening effect.

ImageShear

Syntax

ImageShear( name, amount [, direction] )

Or as a member:

someImage.shear( amount [, direction] )

Arguments

Name
Type
Required
Default
Description

name

any

Yes

The image to shear. Can be a BoxImage object or image name.

amount

numeric

Yes

The amount of shear to apply.

direction

string

No

horizontal

The direction of shear: "horizontal" or "vertical".

Returns

BoxImage — The sheared image object.

Description

Applies a shear transformation to the specified image. Shearing distorts the image along the horizontal or vertical axis by the given amount, creating a slanted effect.

Example

// Shear image horizontally by 0.5
result = ImageShear( myImage, 0.5 );

// Shear image vertically by 0.3
result = ImageShear( myImage, 0.3, "vertical" );

// As a member function
myImage.shear( 0.2, "horizontal" );

Related BIFs

  • ImageRotate

  • ImageResize

  • ImageFlip

Notes

  • The name argument can be a BoxImage object or the name of an image variable in the current context.

  • The operation modifies the image in place when used as a member function.

  • Returns the modified image object for chaining or further processing.

  • The direction argument must be either "horizontal" or "vertical".

ImageShearDrawingAxis

Syntax

ImageShearDrawingAxis( name, x, y )

Or as a member:

someImage.shearDrawingAxis( x, y )

Arguments

Name
Type
Required
Default
Description

name

any

Yes

The image to shear. Can be a BoxImage object or image name.

x

numeric

Yes

0

The shear amount along the x-axis.

y

numeric

Yes

0

The shear amount along the y-axis.

Returns

BoxImage — The sheared image object.

Description

Applies a shear transformation to the specified image along custom axes. The x and y arguments control the amount of shear along the horizontal and vertical axes, respectively. Useful for advanced graphics effects and custom distortions.

Example

// Shear image by 0.5 along x-axis and 0.2 along y-axis
result = ImageShearDrawingAxis( myImage, 0.5, 0.2 );

// As a member function
myImage.shearDrawingAxis( 0.3, 0.1 );

Related BIFs

  • ImageShear

  • ImageRotateDrawingAxis

  • ImageResize

Notes

  • The name argument can be a BoxImage object or the name of an image variable in the current context.

  • The operation modifies the image in place when used as a member function.

  • Returns the modified image object for chaining or further processing.

  • The x and y arguments specify the shear amount along each axis.

ImageWrite

Syntax

ImageWrite( name [, path] )

Or as a member:

someImage.write( [path] )

Arguments

Name
Type
Required
Description

name

any

Yes

The image to write. Can be a BoxImage object or image name.

path

String

No

The file path to write the image to. If omitted, uses the image's current path or default.

Returns

BoxImage — The image object after writing to disk.

Description

Writes the specified image to disk at the given file path. If no path is provided, the image is saved to its current or default location. Useful for exporting images after processing or manipulation.

Example

// Write image to a specific file
ImageWrite( myImage, "output/photo.png" );

// As a member function
myImage.write( "output/edited.png" );

Related BIFs

  • ImageRead

  • ImageNew

  • ImageGetBlob

Notes

  • The name argument can be a BoxImage object or the name of an image variable in the current context.

  • The operation writes the image to disk and returns the image object for chaining or further processing.

  • The path argument should be a valid file path. If omitted, the image is saved to its default location.

IsImage

Syntax

IsImage( value )

Arguments

Name
Type
Required
Description

value

any

Yes

The value to check if it is a BoxImage object.

Returns

Boolean — Returns true if the value is a BoxImage object, otherwise false.

Description

Determines whether the provided value is a BoxImage object. Useful for type checking before performing image operations.

Example

// Check if a variable is an image
if ( IsImage( myVar ) ) {
    // Safe to use image BIFs
    myVar.flip();
}

Related BIFs

  • ImageNew

  • ImageCopy

  • ImageGetWidth

Notes

  • Returns true only for BoxImage objects.

  • Use this BIF to validate variables before calling image-related functions.

IsImageFile

Syntax

IsImageFile( value )

Arguments

Name
Type
Required
Description

value

any

Yes

The file path or URL to check if it is an image file.

Returns

Boolean — Returns true if the value is a valid image file or URL, otherwise false.

Description

Determines whether the provided value is a valid image file or image URL. Useful for validating file paths or URLs before attempting to read or process images.

Example

// Check if a file is an image
if ( IsImageFile( "images/photo.png" ) ) {
    img = ImageRead( "images/photo.png" );
}

// Check if a URL is an image
if ( IsImageFile( "https://example.com/image.jpg" ) ) {
    img = ImageRead( "https://example.com/image.jpg" );
}

Related BIFs

  • IsImage

  • ImageRead

  • ImageNew

Notes

  • Returns true for valid image files or URLs that can be read as images.

  • Returns false if the file or URL is not a valid image or cannot be read.

  • Use this BIF to validate paths before calling image-related functions.

GetReadableImageFormats

Returns an array of readable image formats supported by the underlying Java ImageIO library. This BIF is useful for determining which image formats can be read (imported) in BoxLang on the current platform.

Syntax

GetReadableImageFormats()

Arguments

This BIF does not accept any arguments.

Returns

  • Array: An array of strings, each representing a readable image format name (e.g., "png", "jpg", "gif").

Description

GetReadableImageFormats queries the Java ImageIO subsystem for all image formats that can be read (decoded) in the current environment. The returned array contains the format names as strings. This is useful for dynamically checking which image types are supported for reading, especially in environments where available formats may vary.

Example

formats = GetReadableImageFormats();
// formats might be ["png", "jpg", "gif", ...]

See Also

  • GetWritableImageFormats

  • ImageRead

Notes

  • The list of formats depends on the Java runtime and any installed imageio plugins.

  • Common formats include "png", "jpg", "gif", but may include others depending on the environment.

ImageWriteBase64

Syntax

ImageWriteBase64( name, format )

Arguments

Name
Type
Required
Description

name

any

Yes

The image to encode. Can be a BoxImage object or image name.

format

String

Yes

The image format for encoding (e.g., "png", "jpg").

Returns

String — The base64-encoded string representing the image in the specified format.

Description

Encodes the specified image as a base64 string in the given format. Useful for embedding images in HTML, transmitting via APIs, or storing images as text.

Example

// Encode image as base64 PNG
base64String = ImageWriteBase64( myImage, "png" );

// Encode image as base64 JPEG
base64String = ImageWriteBase64( myImage, "jpg" );

Related BIFs

  • ImageReadBase64

  • ImageWrite

  • ImageGetBlob

Notes

  • The name argument can be a BoxImage object or the name of an image variable in the current context.

  • The format argument should be a valid image format supported by BoxLang (e.g., "png", "jpg").

  • Returns a base64-encoded string suitable for embedding or transmission.

  • If encoding fails, an error is thrown.

GetWriteableImageFormats

Returns an array of writeable image formats supported by the underlying Java ImageIO library. This BIF is useful for determining which image formats can be written (exported) in BoxLang on the current platform.

Syntax

GetWriteableImageFormats()

Arguments

This BIF does not accept any arguments.

Returns

  • Array: An array of strings, each representing a writeable image format name (e.g., "png", "jpg", "gif").

Description

GetWriteableImageFormats queries the Java ImageIO subsystem for all image formats that can be written (encoded) in the current environment. The returned array contains the format names as strings. This is useful for dynamically checking which image types are supported for writing, especially in environments where available formats may vary.

Example

formats = GetWriteableImageFormats();
// formats might be ["png", "jpg", "gif", ...]

See Also

  • GetReadableImageFormats

  • ImageWrite

Notes

  • The list of formats depends on the Java runtime and any installed imageio plugins.

  • Common formats include "png", "jpg", "gif", but may include others depending on the environment.

ImageAddBorder

Adds a border to an image. This BIF allows you to specify the thickness, color, and type of border to apply to an image in BoxLang.

Syntax

ImageAddBorder(name, thickness [, color] [, borderType])

Arguments

Name
Type
Required
Default
Description

name

any

Yes

The image or the name of a variable referencing an image to operate on.

thickness

numeric

Yes

Border thickness (in pixels).

color

string

No

"black"

Border color: hex value or constant color name.

borderType

string

No

Border type: one of zero, constant, copy, reflect, or wrap.

Returns

  • BoxImage: The modified BoxImage instance with the border applied.

Description

ImageAddBorder adds a border around the specified image. You can control the thickness and color of the border, as well as the border type. The image can be passed directly or referenced by variable name. The border type determines how the border is generated:

  • zero: Border pixels are set to zero.

  • constant: Border pixels are set to the specified color.

  • copy: Border pixels are copied from the edge of the image.

  • reflect: Border pixels are a reflection of the image edge.

  • wrap: Border pixels wrap around from the opposite edge.

Example

// Add a 10px black border to an image
img = ImageAddBorder(myImage, 10);

// Add a 5px red constant border
img = ImageAddBorder(myImage, 5, "red", "constant");

See Also

  • ImageResize

  • ImageCrop

Notes

  • The default border color is black if not specified.

  • The default border type is implementation-dependent if not specified.

  • The image can be passed as a BoxImage object or as a variable name referencing an image.

Components

Image

Syntax

<bx:Image action="read" source="images/photo.png" name="myImage" />

Attributes

Name
Type
Required
Default
Description

action

string

Yes

The action to perform. One of: border, captcha, convert, info, read, resize, rotate, write, writeToBrowser.

angle

string

No

The angle for rotation (used with rotate action).

color

string

No

The color for border or other actions.

destination

string

No

The file path to write the image to (used with write action).

difficulty

string

No

Difficulty level for captcha generation.

fontSize

string

No

Font size for text/captcha.

format

string

No

Image format for writing/converting.

height

numeric

No

Height for resizing or creating images.

isBase64

string

No

If true, treats the source as a base64 string.

name

string

No

The variable name to assign the image to in the context.

overwrite

boolean

No

false

Whether to overwrite the destination file if it exists.

quality

string

No

Image quality for writing/converting.

source

any

No

The source of the image (file path, URL, or base64 string).

structName

string

No

The name of the struct to assign image info to (used with info action).

text

string

No

Text for captcha or drawing.

thickness

string

No

Border thickness.

width

numeric

No

Width for resizing or creating images.

fonts

string

No

Font(s) for text/captcha.

interpolation

string

No

Interpolation method for resizing.

Description

The Image component provides a flexible interface for image processing tasks in BoxLang. It supports reading, writing, resizing, rotating, adding borders, generating captchas, and extracting image info. The component is invoked using HTML-like syntax and accepts a variety of attributes to control its behavior.

Example

<!-- Read an image and assign to context -->
<bx:Image action="read" source="images/photo.png" name="myImage" />

<!-- Resize an image -->
<bx:Image action="resize" source="images/photo.png" width="400" height="300" name="resizedImage" />

<!-- Add a border to an image -->
<bx:Image action="border" source="images/photo.png" color="red" thickness="5" name="borderedImage" />

<!-- Write an image to disk -->
<bx:Image action="write" source="images/photo.png" destination="output/photo.png" overwrite="true" />

<!-- Get image info and assign to a struct -->
<bx:Image action="info" source="images/photo.png" structName="imgInfo" />

Actions

  • read: Loads an image from a file, URL, or base64 string.

  • resize: Resizes the image to the specified width and height.

  • rotate: Rotates the image by the specified angle.

  • border: Adds a border to the image with specified color and thickness.

  • write: Writes the image to the specified destination path.

  • convert: Converts the image format and writes if possible.

  • info: Extracts EXIF metadata and assigns to a struct.

  • captcha: Generates a captcha image (attributes: text, difficulty, fontSize, fonts).

  • writeToBrowser: Writes the image directly to the browser output.

Notes

  • The source attribute can be a file path, URL, or base64 string (set isBase64 to true for base64).

  • The name attribute assigns the resulting image to a variable in the context for further use.

  • The component does not allow a body; all configuration is via attributes.

  • Errors are thrown for unknown actions or invalid attribute combinations.

  • For advanced use, see the BoxLang image module documentation for more details on supported actions and attributes.