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);
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 FunctionsComponentsVisit the GitHub repository for release notes. You can also file a bug report or improvement suggestion via Jira.
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.
ImageClearRect(name, x, y, width, height)
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.
BoxImage: The modified BoxImage instance with the cleared rectangle.
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.
// Clear a 100x50 rectangle at position (10, 20)
img = ImageClearRect(myImage, 10, 20, 100, 50);
ImageFillRect
ImageDrawRect
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.
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.
ImageBlur(name [, blurRadius])
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.
BoxImage: The modified BoxImage instance with the blur applied.
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.
// Blur an image with the default radius (3)
img = ImageBlur(myImage);
// Blur an image with a radius of 10
img = ImageBlur(myImage, 10);
ImageSharpen
ImageAddBorder
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.
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.
ImageCopy(name, x, y, width, height [, dx] [, dy])
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.
BoxImage: The modified BoxImage instance with the copied region drawn at the new location.
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.
// 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);
ImageClearRect
ImageDrawRect
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.
Draws an arc on an image. This BIF allows you to specify the position, size, angles, and whether the arc is filled in BoxLang.
ImageDrawArc(name, x, y, width, height, startAngle, archAngle [, filled])
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.
BoxImage: The modified BoxImage instance with the arc drawn.
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.
// 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);
ImageDrawRect
ImageDrawEllipse
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).
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.
ImageCrop(name, x, y, width, height)
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.
BoxImage: The modified BoxImage instance cropped to the specified area.
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.
// Crop a 100x50 region at position (10, 20)
img = ImageCrop(myImage, 10, 20, 100, 50);
ImageResize
ImageCopy
All arguments are required.
The image can be passed as a BoxImage object or as a variable name referencing an image.
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.
ImageDrawBeveledRect(name, x, y, width, height, raised [, filled])
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.
BoxImage: The modified BoxImage instance with the beveled rectangle drawn.
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.
// 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);
ImageDrawRect
ImageDrawArc
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.
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.
ImageDrawCubicCurve(name, x1, y1, ctrlx1, ctrly1, ctrlx2, ctrly2, x2, y2)
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.
BoxImage: The modified BoxImage instance with the cubic curve drawn.
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.
// Draw a cubic Bézier curve
img = ImageDrawCubicCurve(myImage, 10, 20, 30, 40, 50, 60, 70, 80);
ImageDrawQuadCurve
ImageDrawLine
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).
Draws a straight line on an image. This BIF allows you to specify the start and end points for the line in BoxLang.
ImageDrawLine(name, x1, y1, x2, y2)
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.
BoxImage: The modified BoxImage instance with the line drawn.
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.
// Draw a line from (10, 20) to (100, 50)
img = ImageDrawLine(myImage, 10, 20, 100, 50);
ImageDrawCubicCurve
ImageDrawQuadCurve
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).
Draws an oval (ellipse) on an image. This BIF allows you to specify the position, size, and whether the oval is filled in BoxLang.
ImageDrawOval(name, x, y, width, height [, filled])
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.
BoxImage: The modified BoxImage instance with the oval drawn.
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.
// Draw a filled oval
img = ImageDrawOval(myImage, 10, 20, 100, 50, true);
// Draw an outlined oval
img = ImageDrawOval(myImage, 10, 20, 100, 50);
ImageDrawRect
ImageDrawArc
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).
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.
ImageDrawLines(name, xCoords, yCoords [, isPolygon] [, filled])
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.
BoxImage: The modified BoxImage instance with the lines or polygon drawn.
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.
// 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);
ImageDrawLine
ImageDrawPolygon
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.
Draws a single point on an image. This BIF allows you to specify the position of the point in BoxLang.
ImageDrawPoint(name, x, y)
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.
BoxImage: The modified BoxImage instance with the point drawn.
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.
// Draw a point at (10, 20)
img = ImageDrawPoint(myImage, 10, 20);
ImageDrawLine
ImageDrawRect
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).
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.
ImageDrawQuadraticCurve(name, ctrlx1, ctrly1, x1, y1, x2, y2)
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.
BoxImage: The modified BoxImage instance with the quadratic curve drawn.
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.
// Draw a quadratic Bézier curve
img = ImageDrawQuadraticCurve(myImage, 30, 40, 10, 20, 70, 80);
ImageDrawCubicCurve
ImageDrawLine
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).
Draws a rectangle on an image. This BIF allows you to specify the position, size, and whether the rectangle is filled in BoxLang.
ImageDrawRect(name, x, y, width, height [, filled])
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.
BoxImage: The modified BoxImage instance with the rectangle drawn.
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.
// Draw a filled rectangle
img = ImageDrawRect(myImage, 10, 20, 100, 50, true);
// Draw an outlined rectangle
img = ImageDrawRect(myImage, 10, 20, 100, 50);
ImageDrawOval
ImageDrawArc
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.
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.
ImageDrawRoundRect(name, x, y, width, height, arcWidth, arcHeight [, filled])
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.
BoxImage: The modified BoxImage instance with the rounded rectangle drawn.
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.
// 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);
ImageDrawRect
ImageDrawOval
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.
Draws text on an image. This BIF allows you to specify the text, position, and optional attributes for rendering text in BoxLang.
ImageDrawText(name, str, x, y [, attributeCollection])
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).
BoxImage: The modified BoxImage instance with the text drawn.
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.
// 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);
ImageDrawRect
ImageDrawPoint
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.
Flips or transposes an image. This BIF allows you to specify the type of flip or transpose operation to apply in BoxLang.
ImageFlip(name, transpose)
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").
BoxImage: The modified BoxImage instance after the flip or transpose operation.
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.
// Flip an image horizontally
img = ImageFlip(myImage, "horizontal");
// Rotate an image 90 degrees
img = ImageFlip(myImage, "rotate90");
ImageRotate
ImageCrop
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.
Returns the raw binary data (blob) of an image. This BIF allows you to extract the image as a byte array in BoxLang.
ImageGetBlob(name)
name
any
Yes
The image or the name of a variable referencing an image to operate on.
byte[]: The raw binary data (blob) of the image.
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.
// Get the binary data of an image
blob = ImageGetBlob(myImage);
ImageRead
ImageWrite
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.
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.
ImageGetBufferedImage(name)
name
any
Yes
The image or the name of a variable referencing an image to operate on.
BufferedImage: The underlying Java BufferedImage
object for the image.
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.
// Get the BufferedImage object from a BoxImage
buffered = ImageGetBufferedImage(myImage);
ImageGetBlob
ImageRead
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.
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.
ImageGetExifMetaData(name)
name
any
Yes
The image or the name of a variable referencing an image, or a file path to an image.
IStruct: A struct containing the EXIF metadata from the image.
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.
// Get EXIF metadata from a BoxImage
meta = ImageGetExifMetaData(myImage);
// Get EXIF metadata from an image file path
meta = ImageGetExifMetaData("/path/to/image.jpg");
ImageGetBlob
ImageRead
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.
Returns the height (in pixels) of an image. This BIF allows you to retrieve the vertical dimension of an image in BoxLang.
ImageGetHeight(name)
name
any
Yes
The image or the name of a variable referencing an image to operate on.
Integer: The height of the image in pixels.
ImageGetHeight
returns the height (number of pixels vertically) of the specified image. The image can be passed directly or referenced by variable name.
// Get the height of an image
height = ImageGetHeight(myImage);
ImageGetWidth
ImageResize
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.
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.
ImageGetIPTCMetadata(name)
name
any
Yes
The image or the name of a variable referencing an image, or a file path to an image.
IStruct: A struct containing the IPTC metadata from the image.
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.
// Get IPTC metadata from a BoxImage
meta = ImageGetIPTCMetadata(myImage);
// Get IPTC metadata from an image file path
meta = ImageGetIPTCMetadata("/path/to/image.jpg");
ImageGetExifMetaData
ImageGetBlob
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.
Returns the width (in pixels) of an image. This BIF allows you to retrieve the horizontal dimension of an image in BoxLang.
ImageGetWidth(name)
name
any
Yes
The image or the name of a variable referencing an image to operate on.
Integer: The width of the image in pixels.
ImageGetWidth
returns the width (number of pixels horizontally) of the specified image. The image can be passed directly or referenced by variable name.
// Get the width of an image
width = ImageGetWidth(myImage);
ImageGetHeight
ImageResize
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.
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.
ImageGetIPTCTag(name, tagName)
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").
Object: The value of the specified IPTC tag, or null
if not present.
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.
// 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");
ImageGetIPTCMetadata
ImageGetExifMetaData
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.
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.
ImageInfo(name)
name
any
Yes
The image or the name of a variable referencing an image to operate on.
IStruct: A struct containing general information about the image.
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.
// Get image info
info = ImageInfo(myImage);
// info might contain { width: 800, height: 600, format: "jpg", colorModel: "RGB" }
ImageGetWidth
ImageGetHeight
ImageGetExifMetaData
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.
Converts an image to grayscale. This BIF allows you to remove color and produce a black-and-white version of an image in BoxLang.
ImageGrayScale(name)
ImageGreyScale(name)
name
any
Yes
The image or the name of a variable referencing an image to operate on.
BoxImage: The modified BoxImage instance in grayscale.
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.
// Convert an image to grayscale
grayImg = ImageGrayScale(myImage);
// Or using the alias
grayImg = ImageGreyScale(myImage);
ImageInvert
ImageBlur
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.
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.
ImageNegative(name)
name
any
Yes
The image or the name of a variable referencing an image to operate on.
BoxImage: The modified BoxImage instance with inverted colors.
ImageNegative
inverts the colors of the specified image, producing a photographic negative effect. The image can be passed directly or referenced by variable name.
// Create a negative of an image
negImg = ImageNegative(myImage);
ImageGrayScale
ImageInvert
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( source [, width] [, height] [, imageType] [, color] )
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.
BoxImage
— The newly created image object.
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.
// 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 );
ImageCopy
ImageInfo
ImageGetWidth
ImageGetHeight
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( image1, image2 [, rule] [, transparency] )
Or as a member:
someImage.overlay( imageToDraw [, rule] [, transparency] )
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).
BoxImage
— The base image with the overlay applied.
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.
// 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 );
ImageCopy
ImageDrawImage
ImageNew
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( image1, image2 [, x] [, y] )
ImageDrawImage( image1, image2 [, x] [, y] )
Or as a member:
someImage.paste( imageToDraw [, x] [, y] )
someImage.drawImage( imageToDraw [, x] [, y] )
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.
BoxImage
— The base image with the pasted image applied.
Pastes one image (image2
) onto another (image1
) at the specified coordinates. Useful for combining images, adding watermarks, or overlaying graphics at precise locations.
// 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 );
ImageOverlay
ImageCopy
ImageNew
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( path )
path
String
Yes
The file path or URL to the image to read.
BoxImage
— The image object loaded from the specified path.
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.
// Load an image from a file
img = ImageRead( "images/photo.png" );
// Load an image from a URL
img = ImageRead( "https://example.com/image.jpg" );
ImageNew
ImageCopy
ImageGetWidth
ImageGetHeight
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( name, width, height [, interpolation] [, blurFactor] )
Or as a member:
someImage.resize( width, height [, interpolation] [, blurFactor] )
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.
BoxImage
— The resized image object.
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.
// 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 );
ImageCrop
ImageFlip
ImageGrayScale
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( string )
string
String
Yes
The base64-encoded string representing the image data.
BoxImage
— The image object decoded from the base64 string.
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.
// Load an image from a base64 string
img = ImageReadBase64( myBase64String );
ImageRead
ImageNew
ImageGetBlob
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( name, angle )
Or as a member:
someImage.rotate( angle )
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.
BoxImage
— The rotated image object.
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.
// 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 );
ImageResize
ImageFlip
ImageCrop
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( name, angle [, x] [, y] )
Or as a member:
someImage.rotateDrawingAxis( angle [, x] [, y] )
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.
BoxImage
— The rotated image object.
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.
// Rotate image 90 degrees around axis (100, 50)
result = ImageRotateDrawingAxis( myImage, 90, 100, 50 );
// As a member function
myImage.rotateDrawingAxis( 45, 200, 100 );
ImageRotate
ImageResize
ImageFlip
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( name, width [, height] [, interpolation] )
Or as a member:
someImage.scaleToFit( width [, height] [, interpolation] )
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").
BoxImage
— The scaled image object.
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.
// 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" );
ImageResize
ImageCrop
ImageRotate
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( name [, antialias] )
Or as a member:
someImage.setAntiAliasing( [antialias] )
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.
BoxImage
— The image object with updated anti-aliasing setting.
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.
// Enable anti-aliasing
result = ImageSetAntiAliasing( myImage, true );
// Disable anti-aliasing
result = ImageSetAntiAliasing( myImage, false );
// As a member function
myImage.setAntiAliasing( true );
ImageDrawText
ImageDrawLine
ImageResize
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( name, color )
Or as a member:
someImage.setBackgroundColor( color )
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").
BoxImage
— The image object with updated background color.
Sets the background color of the specified image. Useful for preparing images for compositing, overlays, or ensuring a consistent background before further processing.
// 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" );
ImageSetAntiAliasing
ImageDrawRect
ImageNew
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( name, color )
Or as a member:
someImage.setDrawingColor( color )
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").
BoxImage
— The image object with updated drawing color.
Sets the drawing color for the specified image. This color will be used for subsequent drawing operations such as lines, shapes, and text.
// 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" );
ImageSetBackgroundColor
ImageDrawLine
ImageDrawText
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( name [, attributeCollection] )
Or as a member:
someImage.setDrawingStroke( [attributeCollection] )
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).
BoxImage
— The image object with updated drawing stroke settings.
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.
// 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 } );
ImageSetDrawingColor
ImageDrawLine
ImageDrawRect
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( name, percent )
Or as a member:
someImage.setDrawingTransparency( percent )
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.
BoxImage
— The image object with updated drawing transparency.
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.
// Set drawing transparency to 50%
result = ImageSetDrawingTransparency( myImage, 50 );
// As a member function
myImage.setDrawingTransparency( 75 );
ImageSetDrawingColor
ImageSetDrawingStroke
ImageDrawText
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( name [, gain] )
Or as a member:
someImage.sharpen( [gain] )
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.
BoxImage
— The sharpened image object.
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.
// 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 );
ImageBlur
ImageGrayScale
ImageResize
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( name, amount [, direction] )
Or as a member:
someImage.shear( amount [, direction] )
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".
BoxImage
— The sheared image object.
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.
// 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" );
ImageRotate
ImageResize
ImageFlip
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( name, x, y )
Or as a member:
someImage.shearDrawingAxis( x, y )
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.
BoxImage
— The sheared image object.
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.
// 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 );
ImageShear
ImageRotateDrawingAxis
ImageResize
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( name [, path] )
Or as a member:
someImage.write( [path] )
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.
BoxImage
— The image object after writing to disk.
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.
// Write image to a specific file
ImageWrite( myImage, "output/photo.png" );
// As a member function
myImage.write( "output/edited.png" );
ImageRead
ImageNew
ImageGetBlob
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( value )
value
any
Yes
The value to check if it is a BoxImage object.
Boolean
— Returns true
if the value is a BoxImage object, otherwise false
.
Determines whether the provided value is a BoxImage object. Useful for type checking before performing image operations.
// Check if a variable is an image
if ( IsImage( myVar ) ) {
// Safe to use image BIFs
myVar.flip();
}
ImageNew
ImageCopy
ImageGetWidth
Returns true
only for BoxImage objects.
Use this BIF to validate variables before calling image-related functions.
IsImageFile( value )
value
any
Yes
The file path or URL to check if it is an image file.
Boolean
— Returns true
if the value is a valid image file or URL, otherwise false
.
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.
// 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" );
}
IsImage
ImageRead
ImageNew
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.
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.
GetReadableImageFormats()
This BIF does not accept any arguments.
Array: An array of strings, each representing a readable image format name (e.g., "png", "jpg", "gif").
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.
formats = GetReadableImageFormats();
// formats might be ["png", "jpg", "gif", ...]
GetWritableImageFormats
ImageRead
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( name, format )
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").
String
— The base64-encoded string representing the image in the specified format.
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.
// Encode image as base64 PNG
base64String = ImageWriteBase64( myImage, "png" );
// Encode image as base64 JPEG
base64String = ImageWriteBase64( myImage, "jpg" );
ImageReadBase64
ImageWrite
ImageGetBlob
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.
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.
GetWriteableImageFormats()
This BIF does not accept any arguments.
Array: An array of strings, each representing a writeable image format name (e.g., "png", "jpg", "gif").
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.
formats = GetWriteableImageFormats();
// formats might be ["png", "jpg", "gif", ...]
GetReadableImageFormats
ImageWrite
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.
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.
ImageAddBorder(name, thickness [, color] [, borderType])
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
.
BoxImage: The modified BoxImage instance with the border applied.
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.
// Add a 10px black border to an image
img = ImageAddBorder(myImage, 10);
// Add a 5px red constant border
img = ImageAddBorder(myImage, 5, "red", "constant");
ImageResize
ImageCrop
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.
<bx:Image action="read" source="images/photo.png" name="myImage" />
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.
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.
<!-- 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" />
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.
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.