Progrimage Lua Documentation

number math.round(number n)

Rounds the number to the nearest integer using math.floor(n + 0.5).

---

number math.clamp(number n, number min, number max)

Clamps the number between min and max using math.min(math.max(n, min), max).

vector2 vec2(number? x, number? y)

Creates a vector2.
If called as vec2(), returns vec2(0, 0).
If called as vec2(number n), returns vec2(n, n).
If called as vec2(number x, number y), returns vec2(x, y).

---

vector3 vec3(number? x, number? y, number? z)

Creates a vector3.
If called as vec3(), returns vec3(0, 0, 0).
If called as vec3(number n), returns vec3(n, n, n).
If called as vec3(number x, number y), returns vec3(x, y, 0).
If called as vec3(number x, number y, number z), returns vec3(x, y, z).

---

vector4 vec4(number? x, number? y, number? z, number? w)

Creates a vector4.
If called as vec4(), returns vec4(0, 0, 0, 0).
If called as vec4(number n), returns vec4(n, n, n, n).
If called as vec4(number x, number y), returns vec4(x, y, 0, 0).
If called as vec4(number x, number y, number z), returns vec4(x, y, z, 0).
If called as vec4(number x, number y, number w), returns vec4(x, y, z, w).

vector2 input.getMousePosCanvas()

Gets the mouse position in canvas coordinates.
This is slightly expensive because it calls a C# method.

---

vector2 input.getMousePosScreen()

Gets the mouse position in screen coordinates.
This is slightly expensive because it calls a C# method.

---

boolean input.isMouseDown()

Returns true if the left mouse button is down as long as a normal tool should react. Returns false if the mouse was pressed outside of the canvas, while over a menu, or while the window was unfocused.
This is slightly expensive because it calls a C# method.

---

boolean input.isMouse2Down()

Returns true if the right mouse button is down. Follows the same rules as input.isMouseDown().

---

boolean input.isMouseInCanvas()

Returns true if mouse is within the canvas bounds and not blocked by another window or menu.
This is slightly expensive because it calls a C# method.

Important: make sure to call LuaImage:dispose() when done with an image to free up memory.

Note: LuaImages cannot be used to as keys to tables due to them being wrapper objects to an internal class and may sometimes be recreated.

---

LuaImage:blur(number? sigma)

Blurs the image with the given sigma or a default sigma of 3.

---

LuaImage:clear(vector3? or vector4? color)

Sets all pixels in the image to the given color. If no color is provided, it will use 0,0,0,0.

---

LuaImage:clear(vector3 or vector4 color, number x, number y, number width, number height) or
LuaImage:clear(vector3 or vector4 color, vector2 pos, vector2 size)

Sets all pixels in the rectangle to the given color.

---

LuaImage:clone()

Clones the image.

---

LuaImage:dispose()

Disposes of the image and frees up memory. Make sure to call this when done with an image.

---

LuaImage:drawArc(vector3 or vector4 color, vector2 center, vector2 radius, number thickness, number startAngle, number angleDelta)

Draws an arc on the image.

---

LuaImage:drawImage(LuaImage overlay, bool? expand)

Draws the overlay image on top of this image. The positions of the two images are used for the drawing position. Pass true to expand the image when drawing if needed. Default to false.

---

LuaImage:drawImage(LuaImage overlay, number x, number y, bool? expand) or
LuaImage:drawImage(LuaImage overlay, vector2 pos, bool? expand)

Draws the overlay image on top of this image at the specified position. Pass true to expand the image when drawing if needed. Default to false.

---

LuaImage:drawLine(vector3 or vector4 color, number thickness, number x1, number y1, number x2, number y2) or
LuaImage:drawLine(vector3 or vector4 color, number thickness, vector2 start, vector2 stop)

Draws a line on the image.

---

LuaImage:drawMask(LuaImage mask)

Multiplies the alpha of this image with the alpha of the mask. The positions of the two images are used for the drawing position. E.g. if a pixel in the mask has an alpha of 0, the pixel in this image will then have an alpha of 0. If the mask has 255, then the pixel in this image will be unmodified.

---

LuaImage:drawMask(LuaImage mask, number x, number y) or
LuaImage:drawMask(LuaImage mask, vector2 pos)

Multiplies the alpha of this image with the alpha of the mask. E.g. if a pixel in the mask has an alpha of 0, the pixel in this image will then have an alpha of 0. If the mask has 255, then the pixel in this image will be unmodified.

---

LuaImage:drawOval(vector3 or vector4 color, number thickness, number x, number y, number width, number height) or
LuaImage:drawOval(vector3 or vector4 color, number thickness, vector2 pos, vector2 size)

Draws an outlined oval on the image.

---

LuaImage:drawRect(vector3 or vector4 color, number thickness, number x, number y, number width, number height) or
LuaImage:drawRect(vector3 or vector4 color, number thickness, vector2 pos, vector2 size)

Draws an outlined rectangle on the image.

---

LuaImage:drawReplace(LuaImage overlay, bool? expand)

Draws the overlay image on top of this image but replaces the pixels instend of blending them. The positions of the two images are used for the drawing position. Pass true to expand the image when drawing if needed. Default to false.

---

LuaImage:drawReplace(LuaImage overlay, number x, number y, bool? expand) or
LuaImage:drawReplace(LuaImage overlay, vector2 pos, bool? expand)

Draws the overlay image on top of this image but replaces the pixels instend of blending them. Pass true to expand the image when drawing if needed. Default to false.

---

LuaImage:drawCubicCurve(vector3 or vector4 color, number thickness, vector2 p1, vector2 p2, vector2 p3, vector2 p4)

Draws a cubic Bézier curve on the image.

---

LuaImage:drawPolygon(vector3 or vector4 color, number thickness, table points)

Draws an outlined polygon on the image. The table is a set of vector2s.

---

LuaImage:drawQuadraticCurve(vector3 or vector4 color, number thickness, vector2 p1, vector2 p2, vector2 p3)

Draws a quadratic Bézier curve on the image.

---

LuaImage:expandToContain(number x, number y, number width, number height) or
LuaImage:expandToContain(vector2 pos, vector2 size)

If the given bounds are not fully encapsulated by the image, it will be repositioned and resized to contain it.

---

LuaImage:fillOval(vector3 or vector4 color, number x, number y, number width, number height) or
LuaImage:fillOval(vector3 or vector4 color, vector2 pos, vector2 size)

Draws a filled oval on the image.

---

LuaImage:fillPolygon(vector3 or vector4 color, table points)

Draws a filled polygon on the image. The table is a set of vector2s.

---

LuaImage:fillRect(vector3 or vector4 color, number x, number y, number width, number height) or
LuaImage:fillRect(vector3 or vector4 color, vector2 pos, vector2 size)

Draws a filled rectangle on the image.

---

vector4 LuaImage:getPixel(number x, number y) or
vector4 LuaImage:getPixel(vector2 pos)

Gets the color of a pixel as a vector4.
This function is slightly expensive because it calls a C# method.

---

table LuaImage:getPixels()

Get a table containing vector4s of the image's pixels.
This function is expensive but may provide performance improvements if each pixel needs to be accessed or set multiple times.
Indexed by tbl[x+1][y+1].

---

LuaImage LuaImage:getSubimage(number x, number y, number width, number height) or
LuaImage LuaImage:getSubimage(vector2 pos, vector2 size)

Gets a subimage at the position and size.

---

number LuaImage.height

Get or set the height of the image.

---

vector2 LuaImage.pos

Get or set the position of the image.

---

LuaImage:resize(number width, number height, string? samplingMode) or
LuaImage:resize(vector2 size, string? samplingMode)

Resizes the image. If the sampling mode is not provided, it will default to bicubic.
Passing 0 for width or height (not both) will preserve the aspect ratio.
Valid sampling modes are:

• bicubic - Commonly used algorithm that preserves sharpness better than triangle (bilinear) interpolation.
• box - When downscaling, the pixels will average and merge together. Similar to nearest neighbor when upscaling.
• boxp - Custom sampling method. Upscaling is bilinear/triangle. Downscaling is box but the edge pixels are treated as non-full pixels when not fully contained by the area being sampled.
• catmullrom - Cubic filter that produces a reasonably sharp edge, but without the pronounced gradient change on large scale image enlargements that a Lagrange filter can produce.
• hermite - Smoothed triangular interpolation filter that rounds off strong edges while preserving flat color levels in the original image.
• lanczos2 - Lanczos kernel sampler that implements smooth interpolation with a radius of 2 pixels. Gives sharper results than others when downsampling. All of this applies to the rest of the Lanczos sampling modes.
• lanczos3 - Lanczos kernel algorithm with a radius of 3.
• lanczos5 - Lanczos kernel algorithm with a radius of 5.
• lanczos8 - Lanczos kernel algorithm with a radius of 8.
• mitchell - Mitchell-Netravali sampling mode. Yields a very good equilibrium between detail preservation (sharpness) and smoothness.
• nearestneighbor - Selects the closest pixel to the new pixel's position. Good for pixel art and scaling up without making the enlarged pixels blurry.
• robidoux - Very good equilibrium between detail preservation (sharpness) and smoothness.
• robidouxsharp - Sharpened version of robidoux sampling mode.
• spline - Cubic algorithm similar to Mitchell-Netravali but with smoother results.
• triangle - Bilinear sampling. Interpolates pixels linearly between 4 corner pixels.
• welch - High speed algorithm that gives very sharpened results.

---

LuaImage:setPixel(number x, number y, vector3 or vector4 color) or
LuaImage:setPixel(vector2 pos, vector3 or vector4 color)

Sets the color of a pixel.
This function is slightly expensive because it calls a C# method.

---

LuaImage:setPixels(table pixels)

Sets the pixels of the image. The table must be either vector3s or vector4s and not contain any keys other than integer coordinates.
This function is expensive but may provide performance improvements if each pixel needs to be accessed or set multiple times.

---

vector2 LuaImage.size

Get or set the size of the image.

---

LuaImage:tint(vector3 or vector4 color)

Multiplies the pixels of this image by the color, including alpha. The color can be bigger than 255 to brighten the image.

---

number LuaImage.width

Get or set the width of the image.

---

number LuaImage.x

Get or set the x position of the image.

---

number LuaImage.y

Get or set the y position of the image.

Important: LuaLayer:update() must be called to update the layer after modifying it. This also calls render.update().

Important: LuaLayer:dispose() must be called when done with the layer to dispose of it and free up memory.

Note: LuaLayers cannot be used to as keys to tables due to them being wrapper objects to an internal class and may sometimes be recreated.

---

LuaLayer:dispose()

Disposes of the layer and its image, and frees up memory. Make sure to call this when done with the layer.

---

LuaImage LuaLayer.image

Get or set the layer's LuaImage.

---

number LuaLayer.height

Get or set the height of the layer's LuaImage.

---

vector2 LuaLayer.pos

Get or set the position of the layer's LuaImage.

---

LuaLayer:setActive()

Makes this the active layer.

---

vector2 LuaLayer.size

Get or set the size of the layer's LuaImage.

---

LuaLayer:update()

Updates the Layer's composites and tells the renderer to update. This must be called after changing anything with the layer. Automatically calls render.update().

---

number LuaLayer.width

Get or set the width of the layer's LuaImage.

---

number LuaLayer.x

Get or set the x position of the layer's LuaImage.

---

number LuaLayer.y

Get or set the y position of the layer's LuaImage.

function LuaUndoAction.undo

Get or set the undo callback function.

---

function LuaUndoAction.redo

Get or set the redo callback function.

---

LuaUndoAction:remove()

Removes this LuaUndoAction from the undo history.

---

LuaUndoRegion:remove()

Removes this LuaUndoRegion from the undo history.

---

Important: render.update() must be called to tell the renderer to update. This is automatically called by LuaLayer:update() and Lua Composite's Run(LuaImage).

---

render.beginStroke(vector2 pos)

Starts the stroke on the active layer.

---

render.continueStroke(vector2 pos)

Moves continues the current stroke.

---

LuaImage render.createImage(number width, number height)

Creates a new image.

---

LuaLayer render.createLayer(number width, number height)

Creates a new layer.

---

render.endStroke(boolean erase)

Finishes the current stroke. Pass false to draw and true to erase.

---

LuaLayer render.getActiveLayer()

Gets the active layer.

---

vector2 render.getCanvasPos()

Gets the position of the canvas in the window.

---

vector2 render.getCanvasSize()

Gets the size of the canvas.

---

vector2 render.getMousePosCanvas()

Gets the mouse position in canvas coordinates.

---

vector2 render.getMousePosScreen()

Gets the mouse position in screen coordinates.

---

vector4 render.getStrokeColor()

Gets the stroke color.

---

number render.getStrokeSize()

Gets the stroke size.

---

number render.getZoom()

Gets the zoom of the rendered canvas.

---

render.setActiveLayer(LuaLayer layer)

Sets the active layer.

---

render.setStrokeColor(vector3 or vector4 color)

Sets the stroke color.

---

render.setStrokeSize(number diameter)

Sets the stroke size.

---

render.update()

Tells the program to update the rendered image. This is automatically called by LuaLayer:update() and Lua Composite's Run(LuaImage).

timer.create(string name, number repetitions, number interval, function callback)

Creates a timer that will run the callback on an interval.
The value passed for repetitions is how many times the callback will be run in total. Pass 0 to repeat infinitely.
Will pass how much extra time over the target interval elapsed to the callback function.
The timer will adjust after each run to account for the extra time.

---

number timer.frameTime

The time the last frame took to process in seconds.

---

number timer.frameStartTime

The time the current frame began processing in seconds.

---

number timer.frameStartTimeClock

The time the current frame began processing based on os.clock() which has less precision than timer.frameStartTime.

---

timer.remove(string name)

Deletes the timer.

---

timer.setCallback(string name, function callback)

Sets the timer's callback.

---

timer.setInterval(string name, number interval)

Sets the timer's interval.

---

timer.setRepetitions(string name, number repetitions)

Sets the timer's repetition limit.

---

boolean timer.shouldYield()

Returns true if the calling code should yield. This is determined by checking if the processing time has exceeded os.clock() - timer.frameStartTimeClock > 0.0126666667.

---

timer.simple(number delay, function callback)

Starts a timer that will run the call back of the specified amount of seconds. Will pass how much extra time over the target delay elapsed to the callback function.

LuaUndoAction util.createUndoAction(function undoCallback, function redoCallback)

Creates a LuaUndoAction undo history item and returns it. When undoing, the undoCallback function is ran. When redoing, the redoCallback function is ran.

---

LuaUndoRegion util.createUndoRegion(LuaLayer layer, vector2 pos, vector2 size)

Creates a LuaUndoRegion undo history item and returns it. Use this in tool scripts and call it before modifying the layer. When called, it will copy the specified region of the image. When undoing, the LuaUndoRegion will copy the region of the current image and restore to the previous copy. When redoing, it will overwrite the region with the copy made when undoing.

---

You can get and set the x and y components by indexing like vec[1] or vec[2].

---

vector2 vector2:ceil()

Rounds the vector2 up to integers.

---

number vector2:distance(vector2 vec)

Gets the distance between 2 vector2s.

---

number vector2:distanceSqr()

Gets the squared distance between 2 vector2s. This is faster to compute than vector2:distance(vector2).

---

number vector2:dot(vector2 vec)

Gets the dot product between 2 vector2s.

---

vector2 vector2:floor()

Rounds the vector2 down to integers.

---

number vector2:length()

Gets the length of the vector2.

---

number vector2:lengthSqr()

Gets the squared length of the vector2. This is faster to compute than vector2:length().

---

vector2 vector2:max(vector2 vec)

Returns a vector2 with the largest components of the 2 vectors.

---

vector2 vector2:min(vector2 vec)

Returns a vector2 with the lowest components of the 2 vectors.

---

vector2 vector2:perpendicular()

Gets a perpendicular vector2 pointing to the right.

---

vector2 vector2:round()

Rounds the vector2 to the nearest integer values.

---

vector3 vector2:toVec3(number? z)

Calls vec3(self[1], self[2], z).
If z is not passed, acts like vec3(self[1], self[2]).

---

vector4 vector2:toVec4(number? z, number? w)

Calls vec4(self[1], self[2], z, w).
The parameters are optional.

---

Vector2 also supports addition, subtraction, multiplication, division, exponents, and modulos with numbers and other vector2s, as well as negation, concatenation, tostring(vector2), and checking if 2 vector2s are equal.

Note: color is stored as RGB 0-255.
You can get and set the x, y, and z components by indexing like vec[1], vec[2], or vec[3].

---

vector3 vector3:blendColor(vector3 or vector4 over)

Alpha blends the input color over itself.

---

vector3 vector3:ceil()

Rounds the vector3 up to integers.

---

vector3 vector3:cross(vector3 vec)

Gets the cross product of 2 vector3s.

---

number vector3:distance(vector3 vec)

Gets the distance between 2 vector3s.

---

number vector3:distanceSqr()

Gets the squared distance between 2 vector3s. This is faster to compute than vector3:distance(vector3).

---

number vector3:dot(vector3 vec)

Gets the dot product between 2 vector3s.

---

vector3 vector3:floor()

Rounds the vector3 down to integers.

---

vector3 vector3:hslToRgb()

Converts an HSL color to RGB.
H = [0 => 360]
S = [0 => 1]
L = [0 => 1]

---

vector3 vector3:hsvToRgb()

Converts an HSV color to RGB.
H = [0 => 360]
S = [0 => 1]
V = [0 => 1]

---

number vector3:length()

Gets the length of the vector3.

---

number vector3:lengthSqr()

Gets the squared length of the vector3. This is faster to compute than vector3:length().

---

vector3 vector3:max(vector3 vec)

Returns a vector3 with the largest components of the 2 vectors.

---

vector3 vector3:min(vector3 vec)

Returns a vector3 with the lowest components of the 2 vectors.

---

vector3 vector3:round()

Rounds the vector3 to the nearest integer values.

---

vector3 vector3:rgbToHsl()

Converts an RGB color to HSL.
H = [0 => 360]
S = [0 => 1]
L = [0 => 1]

---

vector3 vector3:rgbToHsv()

Converts an RGB color to HSV.
H = [0 => 360]
S = [0 => 1]
V = [0 => 1]

---

vector2 vector3:toVec2()

Calls vec2(self[1], self[2]).

---

vector4 vector3:toVec4(number? w)

Calls vec4(self[1], self[2], self[3], w).
If w is not passed, acts like vec4(self[1], self[2], self[4]).

---

Vector3 also supports addition, subtraction, multiplication, division, exponents, and modulos with numbers and other vector3s, as well as negation, concatenation, tostring(vector3), and checking if 2 vector3s are equal.

Note: color is stored as RGBA 0-255.
You can get and set the x, y, z, and w components by indexing like vec[1], vec[2], vec[3], or vec[4].

---

vector4 vector4:blendColor(vector3 or vector4 over)

Alpha blends the input color over itself.

---

vector4 vector4:ceil()

Rounds the vector4 up to integers.

---

number vector4:distance(vector4 vec)

Gets the distance between 2 vector4s.

---

number vector4:distanceSqr()

Gets the squared distance between 2 vector4s. This is faster to compute than vector4:distance(vector4).

---

number vector4:dot(vector4 vec)

Gets the dot product between 2 vector4s.

---

vector4 vector4:floor()

Rounds the vector4 down to integers.

---

vector4 vector4:hslToRgb()

Converts an HSLA color to RGBA.
H = [0 => 360]
S = [0 => 1]
L = [0 => 1]
A = [0 => 255]

---

vector4 vector4:hsvToRgb()

Converts an HSVA color to RGBA.
H = [0 => 360]
S = [0 => 1]
V = [0 => 1]
A = [0 => 255]

---

number vector4:length()

Gets the length of the vector4.

---

number vector4:lengthSqr()

Gets the squared length of the vector4. This is faster to compute than vector4:length().

---

vector4 vector4:max(vector4 vec)

Returns a vector4 with the largest components of the 2 vectors.

---

vector4 vector4:min(vector4 vec)

Returns a vector4 with the lowest components of the 2 vectors.

---

vector4 vector4:round()

Rounds the vector4 to the nearest integer values.

---

vector4 vector4:rgbToHsl()

Converts an RGBA color to HSLA.
H = [0 => 360]
S = [0 => 1]
L = [0 => 1]
A = [0 => 255]

---

vector4 vector4:rgbToHsv()

Converts an RGBA color to HSVA.
H = [0 => 360]
S = [0 => 1]
V = [0 => 1]
A = [0 => 255]

---

vector2 vector4:toVec2()

Calls vec2(self[1], self[2]).

---

vector3 vector4:toVec3()

Calls vec3(self[1], self[2], self[3]).

---

Vector4 also supports addition, subtraction, multiplication, division, exponents, and modulos with numbers and other vector4s, as well as negation, concatenation, tostring(vector4), and checking if 2 vector4s are equal.

OnDeselect()

Called when the tool is deselected.

---

OnLayerDeselect(LuaLayer layer)

Called when a layer is deselected.

---

OnLayerSelect(LuaLayer layer)

Called when a layer is selected.

---

OnMouseDown(vector2 mousePos)

Called when the user presses the left mouse button on the canvas. Passes the curor's canvas coordinates. Follows the same rules as input.isMouseDown().

---

OnMouse2Down(vector2 mousePos)

Called when the user presses the right mouse button on the canvas. Passes the curor's canvas coordinates. Follows the same rules as input.isMouseDown().

---

OnMouseEnterCanvas(vector2 mousePos)

Called when the user's cursor enters the canvas. Passes the curor's canvas coordinates.

---

OnMouseExitConvas(vector2 mousePos)

Called when the user's cursor exits the canvas. Passes the curor's canvas coordinates.

---

OnMouseUp(vector2 mousePos)

Called when the user releases the left mouse button. Passes the curor's canvas coordinates.

---

OnMouse2Up(vector2 mousePos)

Called when the user releases the right mouse button. Passes the curor's canvas coordinates.

---

OnMouseMoveCanvas(vector2 mousePos)

Called when the cursor's canvas position changes. Passes the curor's canvas coordinates.

---

OnMouseMoveScreen(vector2 mousePos)

Called when the user moves their mouse and passes the cursor's screen coordinates.

---

OnSelect()

Called when the tool is selected.

---

Update()

Called every frame after all other events.

Run(LuaImage image)

Called when the composite is run. Automatically calls render.update().