# Effect Engine API

All available functions for usage.

# API Overview

Function Returns Comment
hyperion.ledCount Integer Get the current led count from the led layout
hyperion.latchTime Integer Get the current active latchtime in ms.
hyperion.imageWidth() Integer Get the current image width, calculate positions for elements at the coordinate system
hyperion.imageHeight() Integer Get the current image height,calculate positions for elements at the coordinate system
hyperion.imageCRotate() - Rotates the coordinate system at the center (0,0) by the given angle. See hyperion.imageCRotate()
hyperion.imageCOffset() - Add a offset to the coordinate system. See hyperion.imageCOffset()
hyperion.imageCShear() - Shear the coordinate system. See hyperion.imageCShear()
hyperion.imageResetT() - Resets all coordination system modifications done with hyperion.imageCRotate(), hyperion.imageCOffset(), hyperion.imageCShear()
hyperion.imageMinSize() - See hyperion.imageMinSize()
hyperion.abort() Boolean If true, hyperion requests an effect abort, used in a while loop to repeat effect calculations and writing
hyperion.imageConicalGradient() - See hyperion.imageConicalGradient()
hyperion.imageRadialGradient() - See hyperion.imageRadialGradient()
hyperion.imageLinearGradient() - See hyperion.imageLinearGradient()
hyperion.imageDrawLine() - See hyperion.imageDrawLine()
hyperion.imageDrawPoint() - See hyperion.imageDrawPoint()
hyperion.imageDrawPolygon() - See hyperion.imageDrawPolygon()
hyperion.imageDrawPie() - See hyperion.imageDrawPie()
hyperion.imageDrawRect() - See hyperion.imageDrawRect()
hyperion.imageSolidFill() - See hyperion.imageSolidFill()
hyperion.imageShow() - Hyperion shows the image you created with other hyperion.image* functions before. This is always the last step after you created the image with other hyperion.image* function
hyperion.imageSetPixel() - See hyperion.imageSetPixel()
hyperion.imageGetPixel() Tuple A Python tuple RGB values for the requested position. See hyperion.imageGetPixel()
hyperion.imageSave() Integer Create a snapshot of the current effect image and returns an ID. To display the snapshot do hyperion.imageShow(ID). Snapshots are the current state of the picture
hyperion.setColor() - Not recommended, read why! See hyperion.setColor()
hyperion.setImage() - hyperion.setImage(width, height, RGB_bytearray)

# hyperion.imageMinSize()

As the hyperion.imageWidth() and hyperion.imageHeight() scales with the led layout, you could define a minimum size to get more pixels to work with. Keep in mind that the ratio between width/height depends always on user led setup, you can't force it.

WARNING

Should be called before you start painting!

hyperion.imageMinSize(pixelX,pixelY)

Argument Type Comment
pixelX Integer Minimum Pixels at the x-axis of the image to draw on with hyperion.image* functions
pixelY Integer Minimum Pixels at the y-axis of the image to draw on with hyperion.image* functions

# hyperion.imageCRotate()

Rotates the coordinate system at the center which is 0 at the x-axis and 0 at the y-axis by the given angle clockwise. Note: If you want to move the center of the coordinate system you could use hyperion.imageCOffset(). The rotation is kept until the effect ends.
hyperion.imageCRotate(angle)

Argument Type Comment
angle Integer Angle of the rotation between 0 and 360, clockwise

# hyperion.imageCOffset()

Add offset to the coordinate system at the x-axis and y-axis.

WARNING

Changes at the coordinate system results in weird behavior of some shorter versions of other hyperion.image* drawing functions

hyperion.imageCOffset(offsetX, offsetY)

Argument Type Comment
offsetX Integer Offset which is added to the coordinate system at the x-axis. Positive value moves to the right, negative to the left
offsetY Integer Offset which is added to the coordinate system at the y-axis. Positive value moves to the right, negative to the left

# hyperion.imageCShear()

Shears the coordinate system at the vertical and horizontal. More info to shearing here: Shear Mapping

WARNING

Changes at the coordinate system results in weird behavior of some shorter versions of other hyperion.image* drawing functions

hyperion.imageCShear(sh, sv)

Argument Type Comment
sh Integer Horizontal pixels to shear
sv Integer Vertical pixels to shear.

# hyperion.imageConicalGradient()

Draws a conical gradient on the image, all arguments are required. Add the arguments in the order of rows below. Short explanation for conical gradient at the QT docs: Conical Gradient
hyperion.imageConicalGradient(startX, startY, width, height, centerX, centerY, angle, bytearray)

Argument Type Comment
startX Integer Defines the start point at the x-axis of the rectangle that contains the gradient
startY Integer Defines the start point at the y-axis of the rectangle that contains the gradient
width Integer Defines the width of the rectangle
height Integer Defines the height of the rectangle
centerX Integer Defines the center of the gradient at the x-axis. For the center of the picture use hyperion.imageWidth()*0.5, don't forget to surround it with int() or round()
centerY Integer Defines the center of the gradient at the y-axis. For the center of the picture use hyperion.imageHeight()*0.5, don't forget to surround it with int() or round()
angle Integer Defines the angle from 0 to 360. Used to rotate the gradient at the center point.
bytearray ByteArray bytearray of (position,red,green,blue,alpha,position,red,green,blue,alpha,...). Could be repeated as often you need it, all values have ranges from 0 to 255. The position is a point where the red green blue values are assigned.
Example: bytearray([0,255,0,0,255,255,0,255,0,255]) - this is a gradient which starts at 0 with color 255,0,0 and alpha 255 and ends at position 255 with color 0,255,0 and alpha 255. The colors in between are interpolation, so this example is a color shift from red to green from 0° to 360°.

Shorter versions of hyperion.imageConicalGradient()

hyperion.imageConicalGradient(centerX, centerY, angle, bytearray) -> startX and startY are 0 and the width/height is max. -> Entire image

# hyperion.imageRadialGradient()

Draws a radial gradient on the image. Add the arguments in the order of rows below. All arguments are required. Short description at QT Docs: Radial Gradient
hyperion.imageRadialGradient(startX, startY, width, height, centerX, centerY, radius, focalX, focalY, focalRadius, bytearray, spread)

Argument Type Comment
startX Integer start point at the x-axis of the rectangle which contains the gradient.
startY Integer start point at the y-axis of the rectangle which contains the gradient.
width Integer width of the rectangle.
height Integer height of the rectangle.
centerX Integer Defines the center at the x-axis of the gradient. For the center of the picture use hyperion.imageWidth()*0.5, don't forget to surround it with int() or round()
centerY Integer Defines the center at the y-axis of the gradient. For the center of the picture use hyperion.imageHeight()*0.5, don't forget to surround it with int() or round()
radius Integer Defines the radius of the gradient in pixels
focalX Integer Defines the focal point at the x-axis
focalY Integer Defines the focal point at the y-axis
focalRadius Integer Defines the radius of the focal point
bytearray ByteArray bytearray of (position,red,green,blue,position,red,green,blue,...). Could be repeated as often you need it, all values have ranges from 0 to 255. The position is a point where the red green blue values are assigned
Example: bytearray([0,255,0,0,255,0,255,0]) - this is a gradient which starts at 0 with color 255,0,0 and ends at position 255 with color 0,255,0. The colors in between are interpolation, so this example is a color shift from red to green.
spread Integer Defines the spread method outside the gradient. Available spread modes are:
0 -> The area is filled with the closest stop color
1 -> The gradient is reflected outside the gradient area
2 -> The gradient is repeated outside the gradient area
Please note that outside means inside the rectangle but outside of the gradient start and end points, so if these points are the same, you don't see the spread mode. A picture to the spread modes can you find here: Spread modes

Shorter versions of hyperion.imageRadialGradient()

  • hyperion.imageRadialGradient(startX, startY, width, height, centerX, centerY, radius, bytearray, spread) -> focalX, focalY, focalRadius get their values from centerX, centerY and radius
  • hyperion.imageRadialGradient(centerX, centerY, radius, focalX, focalY, focalRadius, bytearray, spread) -> startX and startY are 0
  • hyperion.imageRadialGradient(centerX, centerY, radius, bytearray, spread) -> startX and startY are 0 & focalX, focalY, focalRadius get their values from centerX, centerY and radius

# hyperion.imageLinearGradient()

Draws a linear gradient on the image. Add the arguments in the order of rows below. All arguments are required. Short description at QT Docs: Linear Gradient
hyperion.imageLinearGradient(startRX, startRY, width, height, startX, startY, endX, endY, bytearray, spread)

Argument Type Comment
startRX Integer start point at the x-axis of the rectangle which contains the gradient.
startRY Integer start point at the y-axis of the rectangle which contains the gradient.
width Integer width of the rectangle.
height Integer height of the rectangle.
startX Integer Defines the start at the x-axis for the gradient.
startY Integer Defines the start at the y-axis for the gradient.
endX Integer Defines the end at the x-axis for the gradient.
endY Integer Defines the end at the y-axis for the gradient.
bytearray ByteArray bytearray of (position,red,green,blue,alpha,position,red,green,blue,alpha,...). Could be repeated as often you need it, all values have ranges from 0 to 255. The position is a point where the red green blue values are assigned.
Example: bytearray([0,255,0,0,255,255,0,255,0,127]) this is a gradient which starts at 0 with color 255,0,0 and alpha 255 and ends at position 255 with color 0,255,0 and alpha 127. The colors in between are interpolation, so this example is a color shift from red to green.
spread Integer Defines the spread method outside the gradient. Available spread modes are:
0 -> The area is filled with the closest stop color
1 -> The gradient is reflected outside the gradient area
2 -> The gradient is repeated outside the gradient area
Please note that outside means inside the rectangle but outside of the gradient start and end points, so if these points are the same, you don't see the spread mode. A picture to the spread modes can you find here: Spread modes

Shorter versions of hyperion.imageLinearGradient()

hyperion.imageLinearGradient(startX, startY, endX, endY, bytearray, spread) -> The rectangle which contains the gradient defaults to the full image

# hyperion.imageDrawLine()

Draws a line at the image. All arguments are required, exception a for alpha. Add the arguments in the order of rows below.
hyperion.imageDrawLine(startX, startY, endX, endY, thick, r, g, b, a)

Argument Type Comment
startX Integer start point at the x-axis. Relates to hyperion.imageWidth()
startY Integer start point at the y-axis. Relates to hyperion.imageHeight()
endX Integer end point at the x-axis. Relates to hyperion.imageWidth()
endY Integer end point at the y-axis. Relates to hyperion.imageHeight()
thick Integer Thickness of the line, should be calculated based on image height or width. But at least one Pixel. Example: max(int(0.1*hyperion.imageHeight(),1) is 10% of the image height.
r Integer red color from 0 to 255
g Integer green color from 0 to 255
b Integer blue color from 0 to 255
a Integer Optional alpha of the color from 0 to 255, if not provided, it's 255

Shorter versions of hyperion.imageLinearGradient()

hyperion.imageLinearGradient(startX, startY, endX, endY, bytearray, spread) -> The rectangle which contains the gradient defaults to the full image

# hyperion.imageDrawPoint()

Draws a point/dot at the image. All arguments are required, exception a for alpha. Add the arguments in the order of rows below.
hyperion.imageDrawPoint(x, y, thick, r, g, b, a)

Argument Type Comment
x Integer point position at the x-axis. Relates to hyperion.imageWidth()
y Integer point position at the y-axis. Relates to hyperion.imageHeight()
thick Integer Thickness of the point in pixel, should be calculated based on image height or width. But at least one Pixel. Example: max(int(0.1*hyperion.imageHeight(),1) is 10% of the image height.
r Integer red color from 0 to 255
g Integer green color from 0 to 255
b Integer blue color from 0 to 255
a Integer Optional alpha of the color from 0 to 255, if not provided, it's 255

Shorter versions of hyperion.imageDrawPoint()

hyperion.imageDrawPoint(x, y, thick, r, g, b) -> alpha defaults to 255

# hyperion.imageDrawPolygon()

Draws a polygon at the image and fills it with the specific color. Used for free forming (triangle, hexagon,... whatever you want ). All arguments are required, exception a for alpha. Add the arguments in the order of rows below.
hyperion.imageDrawPolygon(bytearray, r, g, b, a)

Argument Type Comment
bytearray ByteArray bytearray([point1X,point1Y,point2X,point2Y,point3X,point3Y,...]). Add pairs of X/Y coordinates to specific the corners of the polygon, each point has a X and a Y coordinate, you could add as much points as you need. The last point automatically connects to the first point.
r Integer red color from 0 to 255
g Integer green color from 0 to 255
b Integer blue color from 0 to 255
a Integer Optional alpha of the color from 0 to 255, if not provided, it's 255

Shorter versions of hyperion.imageDrawPolygon()

hyperion.imageDrawPolygon(bytearray, r, g, b) -> alpha defaults to 255

# hyperion.imageDrawPie()

Draws a pie (also known from pie charts) at the image and fills it with the specific color. All arguments are required, exception a for alpha. Add the arguments in the order of rows below.
hyperion.imageDrawPie(centerX, centerY, radius, startAngle, spanAngle, r, g, b, a)

Argument Type Comment
centerX Integer The center of the Pie at the x-axis
centerY Integer The center of the Pie at the y-axis
radius Integer radius of the Pie in Pixels
startAngle Integer start angle from 0 to 360. 0 is at 3 o'clock
spanAngle Integer span (wide) of the pie from -360 to 360 which starts at the startAngle, positive values are counter-clockwise, negative clockwise
r Integer red color from 0 to 255
g Integer green color from 0 to 255
b Integer blue color from 0 to 255
a Integer Optional alpha of the color from 0 to 255, if not provided, it's 255

Shorter versions of hyperion.imageDrawPie()

hyperion.imageDrawPie(centerX, centerY, radius, startAngle, spanAngle, r, g, b) -> alpha defaults to 255

# hyperion.imageDrawRect()

Draws a rectangle on the image. All arguments are required, exception a for alpha. Add the arguments in the order of rows below.
hyperion.imageDrawRect(startX, startY, width, height, thick, r, g, b, a,)

Argument Type Comment
startX Integer start point at the x-axis. Relates to hyperion.imageWidth()
startY Integer start point at the y-axis. Relates to hyperion.imageHeight()
width Integer width of the rectangle. Relates to hyperion.imageWidth()
height Integer height of the rectangle. Relates to hyperion.imageHeight()
thick Integer Thickness of the rectangle, a good start value is 1
r Integer define red color from 0 to 255
g Integer define green color from 0 to 255
b Integer define blue color from 0 to 255
a Integer Optional alpha of the color from 0 to 255, if not provided, it's 255

# hyperion.imageSolidFill()

Fill a specific part of the image with a solid color (or entire). All arguments are required. Add the arguments in the order of rows below.
hyperion.imageSolidFill(startX, startY, width, height, r, g, b, a)

Argument Type Comment
startX Integer start point at the x-axis. Relates to hyperion.imageWidth()
startY Integer start point at the y-axis. Relates to hyperion.imageHeight()
width Integer width of the fill area. Relates to hyperion.imageWidth()
height Integer height of the fill area. Relates to hyperion.imageHeight()
r Integer define red color from 0 to 255
g Integer define green color from 0 to 255
b Integer define blue color from 0 to 255
a Integer alpha of the color from 0 to 255

Shorter versions of hyperion.imageSolidFill()

  • hyperion.imageSolidFill(startX, startY, width, height, r, g, b) -> no alpha, defaults to 255
  • hyperion.imageSolidFill(r, g, b, a) -> startX and startY is 0, width and height is max. -> full image
  • hyperion.imageSolidFill(r, g, b) -> startX and startY is 0, width and height is max, alpha 255. -> full image

# hyperion.imageSetPixel()

Assign a color to a specific pixel position. All arguments are required. Add the arguments in the order of rows below.
hyperion.imageSetPixel(X, Y, r, g, b)

Argument Type Comment
X Integer pixel point at the x-axis. Relates to hyperion.imageWidth()
Y Integer pixel point at the y-axis. Relates to hyperion.imageHeight()
r Integer define red color from 0 to 255
g Integer define green color from 0 to 255
b Integer define blue color from 0 to 255

# hyperion.imageGetPixel()

Get a color of a specific pixel position. All arguments are required. Add the arguments in the order of rows below.
hyperion.imageGetPixel(X, Y)

Argument Type Comment
X Integer pixel point at the x-axis. Relates to hyperion.imageWidth()
Y Integer pixel point at the y-axis. Relates to hyperion.imageHeight()
Return Tuple Returns a Python Tuple of RGB values

# hyperion.setColor()

Set a single color to all leds by adding hyperion.setColor(255,0,0), all leds will be red. But it is also possible to send a bytearray of RGB values. Each RGB value in this bytearray represents one led.

  • Example 1: hyperion.setColor(bytearray([255,0,0])) The first led will be red
  • Example 2: hyperion.setColor(bytearray([255,0,0,0,255,0])) The first led will be red, the second is green
  • Example 3: hyperion.setColor(bytearray([255,0,0,0,255,0,255,255,255])) The first led will be red, the second is green, the third is white
  • You usually assign to all leds a color, therefore you need to know how much leds the user currently have. Get it with hyperion.ledCount

hyperion.setColor()

  • hyperion.setColor() function is not recommended to assign led colors, it doesn't work together with hyperion.image* functions
  • You don't know where is top/left/right/bottom and it doesn't work with matrix layouts!
  • Please consider to use the hyperion.image* functions instead to create amazing effects that scales with the user setup