API¶

The following classes are exposed by the API. Note that methods and properties which expect a TilePosition, TileSize, or PixelPosition as input will also accept a plain tuple as input so long as the element order is the same.

Main classes:

TileManager - Manages all the tiles being displayed on a hardware matrix.
Tile - Handles the data and pixel-coloring needs of a single tile.
PixelColor - The color of a single matrix pixel.
NTNeoPixelMatrix - Represents a NeoPixel matrix.
NTRGBMatrix - Represents an RGB matrix.

Supporting classes:

MatrixSize - The size of a hardware matrix (cols, rows).
TileSize - The size of a tile (cols, rows).
TilePosition - The position of a tile inside the larger hardware matrix (x, y).
PixelPosition - The position of a pixel inside a tile (x, y).
exceptions.NeoTilesError - Exception raised when neotiles encounters a problem.

The Examples page shows how to use these classes.

Main classes¶

TileManager¶

class neotiles.TileManager(matrix, draw_fps=10)[source]¶

Manages all the tiles displayed on a hardware matrix (either a neopixel matrix or an RGB matrix).

TileManager is the only class in neotiles which affects the actual hardware matrix.

Example usage:

from neotiles import TileManager
from neotiles.matrixes import NTNeoPixelMatrix

tiles = TileManager(NTNeoPixelMatrix(size=(8, 8), led_pin=18))

Or with an RGB matrix:

from neotiles import TileManager
from neotiles.matrixes import NTRGBMatrix

tiles = TileManager(NTRGBMatrix(rows=32, chain=2))

Animation:

The draw_fps (draw frames per second) parameter controls how many times per second the animation loop – which runs in a separate thread – will call draw_hardware_matrix() which in turn calls all the tiles’ Tile.draw() methods. If draw_fps=None then the matrix will not be drawn automatically and you must call draw_hardware_matrix() manually.

The animation loop will attempt to re-draw the matrix at a rate of draw_fps times per second. This rate may or may not be achieved depending on whatever else the CPU is doing, including the compute load created by the tiles’ Tile.draw() methods.

The animation loop assumes that something else will be sending data to the tiles via the Tile.data attribute or the TileManager.send_data_to_tiles() method. If that isn’t happening then the animation loop will likely keep re-drawing the matrix with the same unchanging pixel colors.

Parameters:	matrix – (`NTNeoPixelMatrix` \| `NTRGBMatrix`) The matrix being managed. draw_fps – (int\|None) The frame rate for the drawing animation loop.

register_tile(tile, size=None, root=None)¶

Registers a tile with the TileManager. Registering a tile allows its pixels to be drawn by the TileManager to the hardware matrix.

Parameters:	tile – (`Tile`) The tile to register. size – (`TileSize`) Size of the tile (in cols and rows). root – (`TilePosition`) Position of the top left corner of the tile within the hardware matrix.

deregister_tile(tile)¶

Deregisters a tile from the tile manager. Deregistered tiles will no longer be drawn to the hardware matrix.

If deregistering the tile results in no tiles being registered with the manager then the matrix-drawing animation loop will be stopped automatically.

Parameters:	tile – (`Tile`) The tile being deregistered.
Returns:	(int) The number of tiles removed.

send_data_to_tiles(data)¶

Sends data to all registered tiles. The data will not be sent to any tile which has its Tile.is_accepting_data attribute set to False.

Parameters:	data – (any) Input data.

draw_hardware_matrix()¶

Calls each tile’s Tile.draw() method to ensure that each tile’s pixels are up to date, with the result being displayed on the hardware matrix.

If the TileManager’s draw_fps is not None then this method will also trigger the animation loop if it’s not already running. This means that you only need to call draw_hardware_matrix once if you’ve enabled animation, as the animation loop will ensure that the matrix is updated via each tile’s Tile.draw() method once per animation frame.

draw_stop()¶: Stop the matrix-drawing animation loop.

clear_hardware_matrix()¶: Clears the hardware matrix (sets all pixels to PixelColor(0, 0, 0, 0)).

brightness¶

(int) Get or set the brightness of the matrix display. Range of: acceptable values will depend on the matrix type.

matrix_size¶: (MatrixSize) Get the size of the matrix.

tiles¶: Get all registered tiles as a list of Tile objects.

tiles_meta¶

Get all information on all registered tiles.

Tile information is returned as a list of dictionaries which contain the root and tile_object keys (TilePosition and Tile objects respectively).

If you just want the registered Tile instances then use tiles instead.

pixels¶

Get the tile manager’s current pixel colors, which is a combination of the current pixel colors of all the tiles being managed by the TileManager.

The colors are returned as a two-dimensional list (with the same dimensions as matrix_size) of PixelColor objects.

Tile¶

class neotiles.Tile(default_color=None, animate=True)[source]¶

Handles the data processing and pixel coloring for a single tile.

Parameters:	default_color – (`PixelColor`) Default color for all pixels in the tile. animate – (bool) Whether the tile is animating and should be included in the TileManager’s animation loop.

This class by default displays a random RGBW color inside the tile and ignores any incoming data on the data attribute.

This class will normally be subclassed to implement more useful data-based pixel coloring. Subclasses will usually override the draw() method to process the data last sent to the tile and then call the set_pixel() method to set the color of each pixel in the tile. Tiles are primarily responsible for setting their own pixel colors.

Subclassing example, overriding the draw method:

from neotiles import PixelColor, Tile

# Define our own MyRGBTile class.
class MyRGBTile(Tile):
    def draw(self):
        # Determine our display color based on the tile's data
        # We expect the data to be one of 'red', 'green', 'blue'.
        if self.data == 'red':
            display_color = PixelColor(255, 0, 0, 0)
        elif self.data == 'green':
            display_color = PixelColor(0, 255, 0, 0)
        elif self.data == 'blue':
            display_color = PixelColor(0, 0, 255, 0)
        else:
            display_color = PixelColor(0, 0, 0, 0)

        # Set every pixel in the tile to the display color.
        for row in range(self.size.rows):
            for col in range(self.size.cols):
                self.set_pixel((col, row), display_color)

Animating tiles:

If animate=True then the tile’s draw() method will be called for every frame by the TileManager that the tile is registered with. Tiles will only animate if animate=True and if the tile’s TileManager has set its anim_fps to a non-None integer value.

Tile size:

Tiles are instantiated with a default size of (1, 1). Tiles are then given their size when registered with a TileManager (via TileManager.register_tile()).

This means that when subclassing from Tile, the subclass will not know its size in the __init__ method. When initial tile state needs to be aware of its size then implement the on_size_set() method.

Subclasses can access their tile size via the size attribute (a TileSize object). This is useful when drawing the tile as the draw() method needs to know the dimensions of the tile. The size attribute is also how the tile can access its size when implementing on_size_set().

clear()¶: Clears the tile by setting all the tile’s pixels to PixelColor(0, 0, 0, 0). This does not update the pixels on the hardware neopixel matrix.

draw()¶

Sets the pixel color of all the pixels in the tile, usually based on the data currently associated with the tile.

Note that setting the pixel colors for the tile does not affect the pixels on the hardware neopixel matrix. See set_pixel() for more information.

This method is usually overridden by subclasses and is called automatically by the TileManager object that the tile is registered with.

It’s usually a good idea to break out of the draw method if the tile’s data is None as that usually means there’s no data to process yet (unless data of None means something in your case):

def draw(self):
    if self.data is None:
        return

    # Draw something...

on_size_set()¶

Called when size is set.

This method is usually overridden (when necessary) by subclasses and is called automatically whenever the size attribute is set.

set_pixel(pos, color)¶

Sets the pixel at the given pos in the tile to the given color.

This is only updating the pixel color of a virtual pixel within the tile and is not updating the actual neopixel hardware. The neopixel hardware is updated separately by TileManager.draw_hardware_matrix().

Parameters:	pos – (`PixelPosition`) Tile pixel to set the color of. color – (`PixelColor`) Color to assign.

animate¶

(bool) Get or set whether the tile will be included in the TileManager’s animation loop.

Setting this attribute to True will result in the TileManager calling the tile’s draw() method for every frame it its animation loop.

data¶

Get or set the data associated with the tile.

This attribute can either be set manually, or will be set automatically via TileManager.send_data_to_tiles() on the TileManager object the tile is registered with.

The data assigned to the data attribute can be anything, so long as the tile knows how to interpret it (which is usually done in the draw() method).

Note that a this does not make a copy of the data. This means that if you assign (say) a list or a dictionary to the data attribute then the tile is sharing that data with whatever initially created it.

default_color¶: (PixelColor) Get or set the default color for the tile. This is usually ignored, assuming the tile is painting its own pixel colors.

is_accepting_data¶

(bool) Get or set whether the tile is accepting data.

You can set this attribute to False if you want your tile to ignore any attempts to update its data before it has finished any longer-term rendering task it might be working on.

pixels¶

Get the tile’s current pixel colors.

The colors are returned as a two-dimensional list (with the same dimensions as size) of PixelColor objects.

size¶

(TileSize) Get or set the size of the tile.

This attribute will be set automatically by the TileManager object the tile is registered with.

visible¶

(bool) Get or set whether the tile is visible.

Visible tiles will be displayed on the neopixel matrix by the TileManager.

If visible is set to False then the tile will not be displayed on the neopixel matrix by the TileManaer, but the tile’s draw() method will still be called. This allows for tile state (often maintained in the draw method) to be updated even if the tile is temporarily invisible.

PixelColor¶

class neotiles.PixelColor(red=0, green=0, blue=0, white=None, normalized=None)[source]¶

Represents a single neopixel color (either RGB or RGBW).

The red, blue, green, and white components can either be between 0 and 1 (normalized), or between 0 and 255. PixelColor will attempt to determine automatically whether the components are normalized, but this can be forced with normalized.

All object attributes are read-only.

Parameters:	red – (float\|int) Red component. green – (float\|int) Green component. blue – (float\|int) Blue component. white – (float\|int) White component (set to `None` if RGB only). normalized – (bool) Whether the color is normalized (will be guessed if `None`).

red¶: (float|int) The red component.

green¶: (float|int) The green component.

blue¶: (float|int) The blue component.

white¶: (float|int) The white component.

is_normalized¶: (bool) Whether the color is normalized.

is_rgb¶: (bool) Whether the color is RGB only.

is_rgbw¶: (bool) Whether the color is RGBW.

components¶: The color as a tuple of RGB(W) component values. Values will either be normalized or denormalized to match is_normalized.

components_normalized¶: The color as a tuple of normalized RGB(W) component values.

components_denormalized¶: The color as a tuple of denormalized RGB(W) component values.

hardware_components¶: The color as a tuple of integers suitable for passing to Adafruit_NeoPixel.setPixelColorRGB() for display on neopixel hardware.

hardware_int¶: The color as an integer suitable for passing to Adafruit_NeoPixel.setPixelColor() for display on neopixel hardware.

matrixes.NTNeoPixelMatrix¶

class neotiles.matrixes.NTNeoPixelMatrix(size=None, led_pin=None, led_freq_hz=800000, led_dma=5, led_brightness=64, led_invert=False, strip_type=<class 'sphinx.ext.autodoc.WS2811_STRIP_GRB'>)[source]¶

Represents a NeoPixel matrix.

You must specify a size matching your neopixel matrix (e.g. (8, 8)) as well as the led_pin you’re using to talk to it (e.g. 18). The other parameters can usually be left at their defaults. For more information on the other parameters look at the Adafruit_NeoPixel class in the neopixel module.

If your RGB values appear to be mixed up (e.g. red is showing as green) then try using a different strip_type. You can see a list of valid strip type constants here (look for _STRIP_ in the constant name): https://docs.rs/ws281x/0.1.0/ws281x/ffi/index.html. Specify a strip type like this: strip_type=ws.WS2811_STRIP_GRB. For this to work you’ll need to import ws (which comes with the neopixel module) into your code.

Parameters:	size – (`MatrixSize`) Size of the neopixel matrix. led_pin – (int) The pin you’re using to talk to your neopixel matrix. led_freq_hz – (int) LED frequency. led_dma – (int) LED DMA. led_brightness – (int) Brightness of the matrix display (0-255). led_invert – (bool) Whether to invert the LEDs. strip_type – (int) Neopixel strip type.
Raises:	`exceptions.NeoTilesError` if `matrix_size` or `led_pin` are not specified.

matrixes.NTRGBMatrix¶

class neotiles.matrixes.NTRGBMatrix(options=None, **kwargs)[source]¶

Represents an RGB Matrix.

If no options are passed in then the matrix will be initialized with default options. These options can be overridden either with options (which should be an RGBMatrixOptions object as provided by the rgbmatrix module); or individual options can be passed into the constructor.

For example, the following are equivalent:

from rgbmatrix import RGBMatrixOptions

options = RGBMatrixOptions()
options.chain_length = 2
options.gpio_slowdown = 3

NTRGBMatrix(options=options)

and:

NTRGBMatrix(chain_length=2, gpio_slowdown=3)

Parameters:	options – (RGBMatrixOptions) Matrix options. kwargs – (*) Individual matrix options.

Supporting classes¶

The following supporting classes can be useful but you don’t need to use them.

MatrixSize¶

class neotiles.MatrixSize(cols, rows)[source]¶

cols¶: Alias for field number 0

rows¶: Alias for field number 1

TileSize¶

class neotiles.TileSize(cols, rows)[source]¶

cols¶: Alias for field number 0

rows¶: Alias for field number 1

TilePosition¶

class neotiles.TilePosition(x, y)[source]¶

x¶: Alias for field number 0

y¶: Alias for field number 1

PixelPosition¶

class neotiles.PixelPosition(x, y)[source]¶

x¶: Alias for field number 0

y¶: Alias for field number 1

neotiles.NeoTilesError¶

class neotiles.exceptions.NeoTilesError[source]¶: Parent exception class for neotiles errors.