PAA format¶

The armaio.paa package provides facilities for reading the PAA texture format. The implementations are based on the information on the Community Wiki PAA page.

The module supports all PAA types available in the TexView application.

Examples¶

Decoding a mipmap¶

from armaio.paa import PaaFile, PaaSwizzleTagg, swizzle_channels

paa = PaaFile.read("texture_co.paa")
mip0 = paa.mipmaps[0]
rgba = mip0.decode(paa.format)
swizzle = paa.get_tagg(PaaSwizzleTagg)
if swizzle:
    rgba = swizzle_channels(
        rgba,
        swizzle_red=swizzle.red
        swizzle_green=swizzle.green
        swizzle_blue=swizzle.blue
        swizzle_alpha=swizzle.alpha
    )

Using convenience function¶

from armaio.paa import PaaFile

paa = PaaFile.read("texture_co.paa")
rgba = paa.decode()

Functions¶

Decoding¶

Note

The implementations of the S3TC DXT1/BC1 and DXT5/BC3 decoding algorithms are based on publically available documentation:

armaio.paa.decode_dxt1(width: int, height: int, data: bytes | bytearray) → ndarray[tuple[Any, ...], dtype[uint8]]¶

Decodes texture data compressed with the S3TC DXT1/BC1 algorithm.

Parameters:

width (int) – Texture width in pixels
height (int) – Texture height in pixels
data (bytes) – DXT1 encoded binary data

Raises:

DxtError – Could not decompress texture due to an error

Returns:

Decoded RGBA image data

Return type:

ndarray

armaio.paa.decode_dxt5(width: int, height: int, data: bytes | bytearray) → ndarray[tuple[Any, ...], dtype[uint8]]¶

Decodes texture data compressed with the S3TC DXT5/BC3 algorithm.

Parameters:

width (int) – Texture width in pixels
height (int) – Texture height in pixels
data (bytes) – DXT5 encoded binary data

Raises:

DxtError – Could not decompress texture due to an error

Returns:

Decoded RGBA image data

Return type:

ndarray

Note

The implementations of the bit packed decodings are based on the Community Wiki

armaio.paa.decode_argb8888(width: int, height: int, data: bytes | bytearray) → ndarray[tuple[Any, ...], dtype[uint8]]¶

Decodes texture data encoded as 8-bit RGBA (ARGB8888).

The source data is expected to be packed into one 32-bit unsigned integer per pixel.

Channel layout: AAAAAAAA RRRRRRRR GGGGGGGG BBBBBBBB

Parameters:

width (int) – Decoded texture width
height (int) – Decoded texture height
data (bytes | bytearray) – Encoded binary data

Returns:

Decoded RGBA image data

Return type:

ndarray

armaio.paa.decode_argb1555(width: int, height: int, data: bytes | bytearray) → ndarray[tuple[Any, ...], dtype[uint8]]¶

Decodes texture data encoded as 5-bit RGB with binary alpha (ARGB1555).

The source data is expected to be packed into one 16-bit unsigned integer per pixel.

Channel layout: A RRRRR GGGGG BBBBB

Parameters:

width (int) – Decoded texture width
height (int) – Decoded texture height
data (bytes | bytearray) – Encoded binary data

Returns:

Decoded RGBA image data

Return type:

ndarray

armaio.paa.decode_argb4444(width: int, height: int, data: bytes | bytearray) → ndarray[tuple[Any, ...], dtype[uint8]]¶

Decodes texture data encoded as 4-bit RGBA (ARGB4444).

The source data is expected to be packed into one 16-bit unsigned integer per pixel.

Channel layout: AAAA RRRR GGGG BBBB

Parameters:

width (int) – Decoded texture width
height (int) – Decoded texture height
data (bytes | bytearray) – Encoded binary data

Returns:

Decoded RGBA image data

Return type:

ndarray

armaio.paa.decode_ai88(width: int, height: int, data: bytes | bytearray) → ndarray[tuple[Any, ...], dtype[uint8]]¶

Decodes texture data encoded as 8-bit grayscale (intensity) with 8-bit alpha (AI88).

The source data is expected to be packed into one 16-bit unsigned integer per pixel.

Channel layout: AAAAAAAA IIIIIIII

Parameters:

width (int) – Decoded texture width
height (int) – Decoded texture height
data (bytes | bytearray) – Encoded binary data

Returns:

Decoded RGBA image data

Return type:

ndarray

Utilities¶

armaio.paa.swizzle_channels(data: ndarray[tuple[Any, ...], dtype[uint8]], *, swizzle_red: PaaSwizzle = PaaSwizzle.RED, swizzle_green: PaaSwizzle = PaaSwizzle.GREEN, swizzle_blue: PaaSwizzle = PaaSwizzle.BLUE, swizzle_alpha: PaaSwizzle = PaaSwizzle.ALPHA) → ndarray[tuple[Any, ...], dtype[uint8]]¶

Process swizzling commands on decoded RGBA data.

Example:

data = np.stack(
    (
        np.zeros((16, 16), dtype=np.uint8),
        np.zeros((16, 16), dtype=np.uint8),
        np.zeros((16, 16), dtype=np.uint8),
        np.ones((16, 16), dtype=np.uint8)
    ),
    2,
    dtype=np.uint8
)

data = swizzle_channels(
    data,
    swizzle_red=PaaSwizzle.INVERTED_ALPHA
    swizzle_alpha=PaaSwizzle.INVERTED_RED
)

Parameters:

data (ndarray) – Decoded RGBA data
swizzle_red (PaaSwizzle, optional) – Red swizzle, defaults to PaaSwizzle.RED
swizzle_green (PaaSwizzle, optional) – Green swizzle, defaults to PaaSwizzle.GREEN
swizzle_blue (PaaSwizzle, optional) – Blue swizzle, defaults to PaaSwizzle.BLUE
swizzle_alpha (PaaSwizzle, optional) – Alpha swizzle, defaults to PaaSwizzle.ALPHA

Returns:

Swizzled RGBA data

Return type:

ndarray

Exceptions¶

class armaio.paa.PaaError¶: Exception raised upon PAA reader and decoding errors.

class armaio.paa.DxtError¶: Expection raised upon DXT decoding errors.

Enumerations¶

class armaio.paa.PaaFormat(*values)¶

Pixel color encoding format.

ARGB1555 = 5461¶: 5-bit RGB channels with 1-bit alpha.

ARGB4444 = 17476¶: 4-bit RGBA channels.

ARGB8888 = 34952¶: 8-bit RGBA channels.

DXT1 = 65281¶: S3TC BC1/DXT1 compressed.

DXT2 = 65282¶: S3TC BC2/DXT2 compressed with premultiplied alpha (NOT SUPPORTED).

DXT3 = 65283¶: S3TC BC2/DXT3 compressed (NOT SUPPORTED).

DXT4 = 65284¶: S3TC BC3/DXT4 compressed with premultiplied alpha (NOT SUPPORTED).

DXT5 = 65285¶: S3TC BC3/DXT5 compressed.

GRAY = 32896¶: 8-bit gray with 8-bit alpha.

class armaio.paa.PaaAlphaFlag(*values)¶

Alpha interpolation flag.

BINARY = 2¶: Binary alpha.

INTERPOLATED = 1¶: Smooth alpha.

NONE = 0¶: No alpha handling.

class armaio.paa.PaaSwizzle(*values)¶

Channel swizzling command.

ALPHA = 0¶: Copy to alpha channel.

BLANK_BLACK = 9¶: Blank over with black (NOT SUPPORTED).

BLANK_WHITE = 8¶: Blank over with white (NOT SUPPORTED).

BLUE = 3¶: Copy to blue channel.

GREEN = 2¶: Copy to green channel.

INVERTED_ALPHA = 4¶: Invert and copy to alpha channel.

INVERTED_BLUE = 7¶: Invert and copy to blue channel.

INVERTED_GREEN = 6¶: Invert and copy to green channel.

INVERTED_RED = 5¶: Invert and copy to red channel.

RED = 1¶: Copy to red channel.

Classes¶

class armaio.paa.PaaTagg¶: Generic interface definition for TAGG types.

class armaio.paa.PaaUnknownTagg(signature: str, raw: bytes)¶

Container for unknown TAGG data.

Parameters:

signature (str) – TAGG name
raw (bytes) – Raw bytes read from file

classmethod read(stream: IO[bytes]) → Self¶

Reads an unknown TAGG from a binary stream.

Parameters:: stream (IO[bytes]) – Source binary stream
Returns:: Read TAGG
Return type:: Self

property data: bytes¶

Returns:: Raw data
Return type:: bytes

property signature: str¶

Returns:: Signature string
Return type:: str

class armaio.paa.PaaAverageColorTagg(red: int, green: int, blue: int, alpha: int)¶

Container to store the average color metadata.

Parameters:

red (int) – Red component
green (int) – Green component
blue (int) – Blue component
alpha (int) – Alpha component

classmethod read(stream: IO[bytes]) → Self¶

Reads the average color metadata TAGG from a binary stream.

Parameters:: stream (IO[bytes]) – Source binary stream
Raises:: PaaError – The metadata could not be read due to invalid data
Returns:: Average color metadata
Return type:: Self

property alpha: int¶

Returns:: Alpha component
Return type:: int

property blue: int¶

Returns:: Blue component
Return type:: int

property color: tuple[int, int, int, int]¶

Returns:: RGBA
Return type:: tuple[int, int, int, int]

property green: int¶

Returns:: Green component
Return type:: int

property red: int¶

Returns:: Red component
Return type:: int

property signature: str¶

Returns:: Signature string
Return type:: str

class armaio.paa.PaaMaxColorTagg(red: int, green: int, blue: int, alpha: int)¶

Container to store the maximum color metadata.

Although this is usually present in most PAA files, the actual data is (255, 255, 255, 255) which might not be consistent with the actual file contents. TexView recalculates the actual maximum color from the decoded image data.

Parameters:

red (int) – Red component
green (int) – Green component
blue (int) – Blue component
alpha (int) – Alpha component

classmethod read(stream: IO[bytes]) → Self¶

Reads the maximum color metadata TAGG from a binary stream.

Parameters:: stream (IO[bytes]) – Source binary stream
Raises:: PaaError – The metadata could not be read due to invalid data
Returns:: Maximum color metadata
Return type:: Self

property alpha: int¶

Returns:: Alpha component
Return type:: int

property blue: int¶

Returns:: Blue component
Return type:: int

property color: tuple[int, int, int, int]¶

Returns:: RGBA
Return type:: tuple[int, int, int, int]

property green: int¶

Returns:: Green component
Return type:: int

property red: int¶

Returns:: Red component
Return type:: int

property signature: str¶

Returns:: Signature string
Return type:: str

class armaio.paa.PaaFlagTagg(value: PaaAlphaFlag)¶

Container to store the alpha mode flag.

This flag must be present in textures that are supposed to have any transparencey. If this flag is not present, the assigned model faces are not marked for alpha handling during the binarization of P3Ds.

Parameters:: value (PaaAlphaFlag) – Alpha mode flag

classmethod read(stream: IO[bytes]) → Self¶

Reads the alpha flag metadata from a binary stream.

Parameters:: stream (IO[bytes]) – Source binary stream
Raises:: PaaError – The flag could not be read due to invalid data
Returns:: Alpha mode flag
Return type:: Self

property signature: str¶

Returns:: Signature string
Return type:: str

property value: PaaAlphaFlag¶

Returns:: Alpha mode flag value
Return type:: PaaAlphaFlag

class armaio.paa.PaaSwizzleTagg(red: PaaSwizzle, green: PaaSwizzle, blue: PaaSwizzle, alpha: PaaSwizzle)¶

Container to store the channel swizzling commands.

The swizzle data is ignored by the game engine, it is only used in TexView to reverse the swizzling done during the PNG->PAA conversion. It is used for the sole purpose of visual presentation to the users.

Parameters:

red (PaaSwizzle) – Red swizzle
green (PaaSwizzle) – Green swizzle
blue (PaaSwizzle) – Blue swizzle
alpha (PaaSwizzle) – Alpha swizzle

classmethod read(stream: IO[bytes]) → Self¶

Reads the channel swizzling commands from a binary stream.

Parameters:: stream (IO[bytes]) – Source binary stream
Raises:: PaaError – The swizzling could not be read due to invalid data
Returns:: Channel swizzling commands
Return type:: Self

property alpha: PaaSwizzle¶

Returns:: Alpha swizzling
Return type:: PaaSwizzle

property blue: PaaSwizzle¶

Returns:: Blue swizzling
Return type:: PaaSwizzle

property commands: tuple[PaaSwizzle, PaaSwizzle, PaaSwizzle, PaaSwizzle]¶

RGBA channel copy commands.

Returns:: RGBA swizzling
Return type:: tuple[PaaSwizzle, …]

property green: PaaSwizzle¶

Returns:: Green swizzling
Return type:: PaaSwizzle

property red: PaaSwizzle¶

Returns:: Red swizzling
Return type:: PaaSwizzle

property signature: str¶

Returns:: Signature string
Return type:: str

class armaio.paa.PaaOffsetTagg(offsets: tuple[int, ...])¶

Container to store the byte offsets of the stored mipmaps.

At most 16 mipmap addresses can be stored. In practice a PAA contains less than that.

Parameters:: offsets (tuple[int, ...]) – Mipmap byte offsets from start of file

classmethod read(stream: IO[bytes]) → Self¶

Reads the 16 mipmap byte offsets from a binary stream.

Parameters:: stream (IO[bytes]) – Source binary stream
Raises:: PaaError – The offsets could not be read due to invalid data
Returns:: Mipmap offsets
Return type:: Self

property offsets: tuple[int, ...]¶

Returns:: Offsets from beginning of file
Return type:: tuple[int, …]

property signature: str¶

Returns:: Signature string
Return type:: str

class armaio.paa.PaaMipmap¶

Texture mipmap data container.

classmethod read(stream: IO[bytes]) → Self¶

Reads a mipmap data block from a binary stream.

Parameters:: stream (IO[bytes]) – Source binary stream
Returns:: Mipmap data
Return type:: Self

decode(format: PaaFormat) → ndarray[tuple[Any, ...], dtype[uint8]]¶

Decodes the encoded mipmap pixel data according to the given format.

All internal conditional or uncondition compression is handled automatically.

Parameters:: format (PaaFormat) – Encoding format
Raises:: PaaError – Unsupported PAA format
Returns:: Decoded RGBA data
Return type:: ndarray

property height: int¶

Returns:: Texture height in pixels
Return type:: int

property width: int¶

Returns:: Texture width in pixels
Return type:: int

class armaio.paa.PaaFile¶

Container for PAA texture format data.

classmethod read(stream: IO[bytes]) → Self¶

Reads the file structure of a PAA texture from a binary stream.

Parameters:: stream (IO[bytes]) – Source binary stream
Raises:: PaaError – Unsupported PAA format or unexpected EOF
Returns:: Texture data
Return type:: Self

classmethod read_file(filepath: str) → Self¶

Reads a PAA file at the specified path.

Parameters:: filepath (str) – Path to PAA file
Returns:: Texture data
Return type:: Self

decode(mipmap: int = 0) → ndarray[tuple[Any, ...], dtype[uint8]]¶

Decodes a specific mipmap of the PAA.

Channel swizzling is performed if relevant metadata is present in the file. Alpha mode metadata is ignored.

Parameters:: mipmap (int, optional) – Index of the mipmap to decode, defaults to 0
Returns:: Decoded RGBA data
Return type:: ndarray

get_tagg(taggtype: type[_T]) → _T | None¶

Retrieves a TAGG of a specific type.

If the same type of TAGG is present multiple times (does not normally happen in practice), the first instance is returned.

Parameters:: taggtype (type[_T]) – TAGG type to retrieve
Returns:: TAGG if present
Return type:: _T | None

is_alpha() → bool¶

Checks if the file contains an alpha mode flag signaling transparency.

Returns:: Texture has transparency
Return type:: bool

property format: PaaFormat¶

Returns:: Pixel data format
Return type:: PaaFormat

property mipmaps: tuple[PaaMipmap, ...]¶

Returns:: Texture mipmaps
Return type:: tuple[PaaMipmap, …]

property source: str | None¶

Returns:: Source file path
Return type:: str | None

property taggs: tuple[PaaTagg, ...]¶

Returns:: Metadata TAGGs
Return type:: tuple[PaaTagg, …]