srctools.vtf

Reads and writes Valve’s texture format, VTF.

This is designed to be used with the Python Imaging Library to do the editing of pixels or saving/loading standard image files.

To compress to DXT formats, this uses the libsquish library.

class srctools.vtf.VTF(
width: int,
height: int,
version: ~typing.Tuple[int,
int] = (7,
5),
ref: VecBase | Vec_tuple | ~typing.Tuple[float,
float,
float] = FrozenVec(0,
0,
0),
frames: int = 1,
bump_scale: float = 1.0,
sheet_info: ~typing.Mapping[int,
SheetSequence] = srctools.EmptyMapping,
flags: ~srctools.vtf.VTFFlags = <VTFFlags.EMPTY: 0>,
fmt: ~srctools.vtf.ImageFormats = <ImageFormats[00] RGBA8888: r=8,
g=8,
b=8,
a=8,
size=32>,
thumb_fmt: ~srctools.vtf.ImageFormats = <ImageFormats[13] DXT1: size=64>,
depth: int = 1,
)

Valve Texture Format files, used in the Source Engine.

width: int

The width of the texture. This must be a power of two, but does not need to match the height.

height: int

The height of the texture. This must be a power of two, but does not need to match the width.

depth: int

The “depth” of the texture, used to produce a volumetric texture that has data for a space. This is mutually exclusive with VTFFlags.ENVMAP - it must be 1 for cubemaps.

version: Tuple[int, int]

The version number of the file. Supported versions vary from (7, 2) - (7, 5).

reflectivity: Vec

An average of the colors in the texture, used to tint light bounced off surfaces.

resources: Dict[ResourceID | bytes, Resource]

In version 7.3+, arbitrary resources may be stored in a VTF. ResourceID are defined by Valve, but any 4-byte ID may be used.

sheet_info: Dict[int, SheetSequence]

Textures used for particle system sprites may have this resource, defining subareas to randomly pick from when rendering.

flags: VTFFlags

Bitflags specifying behaviours and how the texture was compiled.

frame_count: int

The number of frames, greater than one for an animated texture.

first_frame_index: int

This field appears unused.

format: ImageFormats

The image format to use for the main image.

low_format: ImageFormats

The image format to use for a small thumbnail, usually ≤ 16×16. This is usually DXT1.

mipmap_count: int

The total number of mipmaps in the image.

classmethod read(file: IO[bytes]) → VTF

Read in a VTF file.

save(
file: IO[bytes],
version: Tuple[int, int] | None = None,
sheet_seq_version: int = 1,
asw_or_later: bool = True,
) → None

Write out the VTF file to this.

If a version is specified, this overrides the one in the object. The particle system version needs to be specified here. If ATI1N or ATI2N used, whether the engine is ASW or later needs to be specified.

load() → None

Fully load all image frames from the VTF.

This allows closing the file stream.

clear_mipmaps(*, after: int = 0) → None

Erase the contents of all mipmaps smaller than the given size.

When saved or compute_mipmaps() is called, these empty mipmaps will be recomputed from the largest mipmap. By default this clears all but the largest mipmap.

compute_mipmaps(
filter: FilterMode = FilterMode.BILINEAR,
) → None

Regenerate all mipmaps that have previously been cleared.

get(
*,
frame: int = 0,
depth: int = 0,
side: CubeSide | None = None,
mipmap: int = 0,
) → Frame

Get a specific image frame.

If the texture is a cubemap, a side must be provided and depth must be 0.

class srctools.vtf.Frame(width: int, height: int)

A single frame of a VTF. This should not be constructed independently.

This is lazy, so it will only read from the file when actually used.

load() → None

If the image has not been loaded, load it from the file stream.

clear() → None

This clears the contents of the frame.

If the VTF is saved, this will be generated from the larger mipmaps.

fill(
r: int = 0,
g: int = 0,
b: int = 0,
a: int = 255,
) → None

Fill the frame with the specified colour.

copy_from(source: Frame) → None
copy_from(
source: bytes | bytearray | 'array[int]' | memoryview,
format: ImageFormats = ImageFormats.RGBA8888,
) → None

Overwrite this frame with other data.

The source can be another Frame, or any buffer with bytes-format data.

rescale_from(
larger: Frame,
filter: FilterMode = FilterMode.BILINEAR,
) → None

Regenerate this image from the next mipmap.

The larger image must either have the same dimension, or exactly double.

to_PIL() → PIL_Image

Convert the given frame into a PIL image.

Requires Pillow to be installed.

to_tkinter(
tk: tkinter.Misc | None = None,
*,
bg: Tuple[int, int, int] | None = None,
) → tkinter.PhotoImage

Convert the given frame into a Tkinter PhotoImage.

If bg is set, the image will be composited onto this background. Otherwise, alpha is ignored.

to_wx_image(
bg: Tuple[int, int, int] | None = None,
) → Any

Convert the given frame into a wxPython wx.Image.

This requires wxPython to be installed. If bg is set, the image will be composited onto this background. Otherwise, alpha is ignored.

to_wx_bitmap(
bg: Tuple[int, int, int] | None = None,
) → Any

Convert the given frame into a wxPython wx.Bitmap.

This requires wxPython to be installed. If bg is set, the image will be composited onto this background. Otherwise, alpha is ignored.

class srctools.vtf.FilterMode(
value,
names=None,
*,
module=None,
qualname=None,
type=None,
start=1,
boundary=None,
)

Bases: Enum

The algorithm to use for generating mipmaps.

NEAREST = 0

Alias: UPPER_LEFT

Just use the upper-left pixel.

UPPER_RIGHT = 1

Just use the upper-right pixel.

LOWER_LEFT = 2

Just use the lower-left pixel.

LOWER_RIGHT = 3

Just use the lower-right pixel.

BILINEAR = 4

Alias: AVERAGE

Average the four pixels together.

class srctools.vtf.ResourceID(
value,
names=None,
*,
module=None,
qualname=None,
type=None,
start=1,
boundary=None,
)

Bases: bytes, Enum

For VTF format 7.3+, there is an extensible resource system.

These are the IDs defined by Valve, but any 4-byte ID may be used.

LOW_RES = b'\x01\x00\x00'

The low-res thumbnail. This is in a fixed position in earlier versions.

HIGH_RES = b'0\x00\x00'
PARTICLE_SHEET = b'\x10\x00\x00'

Used for particle spritesheets, decoded into .sheet_info

CRC = b'CRC'

Cyclic Redundancy Checksum.

LOD_SETTINGS = b'LOD'

Allows forcing specific mipmaps to be used for ‘medium’ shader settings.

EXTRA_FLAGS = b'TSO'

4 extra bytes of bitflags.

KEYVALUES = b'KVD'

Block of keyvalues data.

class srctools.vtf.CubeSide(
value,
names=None,
*,
module=None,
qualname=None,
type=None,
start=1,
boundary=None,
)

Bases: Enum

The sides of a cubemap texture.

RIGHT = 0
LEFT = 1
BACK = 2
FRONT = 3
UP = 4
DOWN = 5
SPHERE = 6
class srctools.vtf.ImageFormats(
value,
names=None,
*,
module=None,
qualname=None,
type=None,
start=1,
boundary=None,
)

Bases: Enum

All VTF image formats, with their data sizes in the value.

RGBA8888 = (8, 8, 8, 8, 32, 0)
ABGR8888 = (8, 8, 8, 8, 32, 1)
RGB888 = (8, 8, 8, 0, 24, 2)
BGR888 = (8, 8, 8, 0, 24, 3)
RGB565 = (5, 6, 5, 0, 16, 4)
I8 = (8, 8, 8, 0, 8, 5)
IA88 = (8, 8, 8, 8, 16, 6)
P8 = (0, 0, 0, 0, 0, 7)
A8 = (0, 0, 0, 8, 8, 8)
RGB888_BLUESCREEN = (8, 8, 8, 0, 24, 9)
BGR888_BLUESCREEN = (8, 8, 8, 0, 24, 10)
ARGB8888 = (8, 8, 8, 8, 32, 11)
BGRA8888 = (8, 8, 8, 8, 32, 12)
DXT1 = (0, 0, 0, 0, 64, 13)
DXT3 = (0, 0, 0, 0, 128, 14)
DXT5 = (0, 0, 0, 0, 128, 15)
BGRX8888 = (8, 8, 8, 8, 32, 16)
BGR565 = (5, 6, 5, 0, 16, 17)
BGRX5551 = (5, 5, 5, 1, 16, 18)
BGRA4444 = (4, 4, 4, 4, 16, 19)
DXT1_ONEBITALPHA = (0, 0, 0, 0, 64, 20)
BGRA5551 = (5, 5, 5, 1, 16, 21)
UV88 = (0, 0, 0, 0, 16, 22)
UVWQ8888 = (0, 0, 0, 0, 32, 23)
RGBA16161616F = (16, 16, 16, 16, 64, 24)
RGBA16161616 = (16, 16, 16, 16, 64, 25)
UVLX8888 = (0, 0, 0, 0, 32, 26)
NONE = (0, 0, 0, 0, 0, 27)
ATI1N = (0, 0, 0, 0, 64, 28)
ATI2N = (0, 0, 0, 0, 128, 29)
is_compressed

Checks if the format is compressed in 4x4 blocks.

frame_size = <function ImageFormats.frame_size>
bin_value = <function ImageFormats.bin_value>
class srctools.vtf.VTFFlags(
value,
names=None,
*,
module=None,
qualname=None,
type=None,
start=1,
boundary=None,
)

Bases: Flag

The various image flags that may be set.

EMPTY = 0
POINT_SAMPLE = 1
TRILINEAR = 2
CLAMP_S = 4
CLAMP_T = 8
ANISOTROPIC = 16
HINT_DXT5 = 32
PWL_CORRECTED = 64
NORMAL = 128
NO_MIP = 256
NO_LOD = 512
ALL_MIPS = 1024
PROCEDURAL = 2048
ONEBITALPHA = 4096
EIGHTBITALPHA = 8192
ENVMAP = 16384
RENDER_TARGET = 32768
DEPTH_RENDER_TARGET = 65536
NO_DEBUG_OVERRIDE = 131072
SINGLE_COPY = 262144
PRE_SRGB = 524288
NO_DEPTH_BUFFER = 8388608
CLAMP_U = 33554432
VERTEX_TEXTURE = 67108864
SS_BUMP = 134217728
BORDER = 536870912
class srctools.vtf.Resource(flags: int, data: bytes | int)

An arbitary resource contained in a VTF file.

This can either be a 32-bit unsigned integer (stored right in the header), or a block of binary data.

class srctools.vtf.SheetSequence(
frames: List[Tuple[float, TexCoord, TexCoord, TexCoord, TexCoord]],
clamp: bool,
duration: float,
)

VTFs may contain a number of sequences using different parts of the image.

classmethod from_resource(
data: bytes,
) → Dict[int, SheetSequence]

Decode from the resource data.

classmethod make_data(
sequences: Mapping[int, SheetSequence],
version: int = 0,
) → bytes

Write out the binary form of this.