Userdata

class picopod.Userdata(datatype, width=None, height=None, data=None)

Bases: Generic

Represents a Picotron userdata object.

__init__(datatype, width=None, height=None, data=None)

Construct a new userdata object.

Parameters:

  • datatype (str|DataType) –

    The type of each data value, as either a string or a DataType.

    If this is a string, the accepted values mirror Picotron. Somewhat confusingly, the sign prefix is ignored, so i8 will always be unsigned and u16 will always be signed. This is for compatibility with Picotron.

    • u8/i8: Unsigned 8-bit integers.

    • u16/i16: Signed 16-bit integers.

    • u32/i32: Signed 32-bit integers.

    • u64/i64: Signed 64-bit integers.

    • f64: 64-bit floating-point numbers.

  • width (int, optional) –

    The number of columns in the data. Must be greater than zero.

    If None or unspecified, data must be set and the userdata’s width will be set to the length of the data.

  • height (int, optional) – If the userdata is two-dimensional, the number of rows in the data. Must be greater than zero if specified.

  • data (optional) –

    The data to initialize the userdata with. This can be a byte string or any iterable sequence like a list. If not provided, the userdata is zero-initialized.

    If width or height is provided, the data’s length must equal width * height or this will raise a UserdataError.

Raises:

  • UnrecognizedTypeError – The datatype string does not match a known data type.

  • ValueError – The width or height is less than 1.

property datatype

The DataType of each value.

property width

The number of columns in the data.

property height

The number of rows in the data if it is 2D, otherwise None.

classmethod read_raw(stream, datatype, width, height, byteorder='big')

Read a raw uncompressed userdata payload from a stream.

Parameters:

  • stream (IO[bytes]) – The stream to read from.

  • datatype (DataType|str) – The type of each data value (can be a string or DataType).

  • width (int) – The number of columns in the userdata.

  • height (int, optional) – The number of rows in the userdata.

  • byteorder (str, optional) – The byte order of each element. Defaults to “big”.

Returns:

The userdata that was read.

Raises:

UnrecognizedTypeError – The datatype string does not match a known data type.

write_raw(stream, byteorder='big')

Write the userdata’s payload to a stream as raw uncompressed bytes.

Parameters:

  • stream (IO[bytes]) – The stream to write to.

  • byteorder (str) – The byte order of each element. Defaults to “big”.

static read_pxu(stream)

Read PXU-framed userdata from a stream and decompresses it if necessary.

Parameters:

stream (IO[bytes]) – The stream to read from.

Returns:

The userdata that was read.

write_pxu(stream, compression_hint=Compression.MTF)

Write PXU-framed userdata to a stream and compress it as requested.

Parameters:

  • stream (IO[bytes]) – The stream to write to.

  • compression_hint (Compression, optional) – A hint for the type of compression to use. If the data type does not support the requested compression, the hint will be ignored. Defaults to MTF.

static from_str(datatype, width, height, payload)

Decode a userdata payload string.

For int-based userdata, the string must contain the bytes for each integer in big-endian hexadecimal. For float userdata, it must contain floats separated by commas.

Parameters:

  • datatype (DataType|str) – The userdata type to decode as.

  • width (int) – The number of columns in the userdata.

  • height (int, optional) – The number of rows in the userdata.

  • payload (str) – The payload string.

Returns:

The decoded userdata.

Raises:

UnrecognizedTypeError – The datatype string does not match a known data type.

to_str()

Encode a userdata payload string.

For int-based userdata, the string will contain the bytes for each integer in big-endian hexadecimal. For float userdata, it will contain floats separated by commas.

Returns:

The encoded string.

static from_rgb(width, height, rgb, palette=PICOTRON_PALETTE)

Convert an RGB image into indexed userdata.

This is the reverse of to_rgb(); every color in the image must exactly match one of the colors in the palette or else this will fail.

Refer to Picopod’s encode_image example for a demonstration of how to quantize an arbitrary image using Pillow.

Parameters:

  • width (int) – The number of columns in the image.

  • height (int) – The number of rows in the image:

  • rgb (Sequence[int]) – A sequence of R, G, B values for each pixel.

  • palette (list[tuple[int, int, int]], optional) – A list of (R, G, B) tuples to look up each pixel in. Defaults to the standard Picotron palette if not given.

Returns:

A userdata object where each byte is a palette index for a pixel.

Raises:

  • InvalidColorError – A color was not present in the palette.

  • ValueError – The image size is invalid or does not match the data.

to_rgb(palette=PICOTRON_PALETTE)

Convert an indexed image into RGB.

Parameters:

palette (list[tuple[int, int, int]], optional) – A list of (R, G, B) tuples to index with each value in the userdata. Defaults to the standard Picotron palette if not given.

Returns:

A byte string of R, G, B values for each pixel.

Raises:

InvalidColorError – A color was not present in the palette.