simvx.core.atlas

Texture atlas, sprite sheet, and atlas packing utilities.

Provides AtlasTexture (sub-region reference), TextureAtlas (named region container), SpriteSheet (grid-based uniform frames), and pack_atlas (shelf-based rectangle packer). These are the foundation for batched 2D sprite rendering.

Module Contents

Classes

AtlasTexture	Reference to a rectangular region within a texture atlas.
TextureAtlas	Texture atlas with named regions for batched sprite rendering.
SpriteSheet	Grid-based sprite sheet with uniform frame size.

Functions

pack_atlas

Pack rectangles into a minimal atlas using a shelf algorithm.

Data

log
__all__

API

simvx.core.atlas.log

‘getLogger(…)’

simvx.core.atlas.__all__

[‘AtlasTexture’, ‘TextureAtlas’, ‘SpriteSheet’, ‘pack_atlas’]

class simvx.core.atlas.AtlasTexture(atlas: simvx.core.atlas.TextureAtlas | str | None = None, region: tuple[int, int, int, int] = (0, 0, 0, 0), margin: tuple[int, int, int, int] = (0, 0, 0, 0))

Reference to a rectangular region within a texture atlas.

Used by Sprite2D, AnimatedSprite2D, and NinePatchRect to render a portion of a shared atlas texture.

Initialization

__slots__

(‘atlas’, ‘region’, ‘margin’)

property x: int

property y: int

property width: int

property height: int

get_uv_rect(atlas_width: int, atlas_height: int) → tuple[float, float, float, float]

Return normalised UV coordinates (u0, v0, u1, v1) for this region.

__repr__() → str

__eq__(other: object) → bool

class simvx.core.atlas.TextureAtlas(width: int = 0, height: int = 0, texture_path: str | None = None)

Texture atlas with named regions for batched sprite rendering.

Can be created manually by adding regions, or auto-packed from a set of individual image files/sizes via :func:pack_atlas.

Initialization

add_region(name: str, x: int, y: int, w: int, h: int) → simvx.core.atlas.AtlasTexture

Add a named region to the atlas. Returns the AtlasTexture.

get_region(name: str) → simvx.core.atlas.AtlasTexture | None

Look up a named region.

remove_region(name: str) → bool

Remove a named region. Returns True if it existed.

has_region(name: str) → bool

Check whether a named region exists.

property region_count: int

property region_names: list[str]

get_uv(name: str) → tuple[float, float, float, float]

Convenience: normalised UV rect for a named region.

__repr__() → str

class simvx.core.atlas.SpriteSheet(texture_path: str | None = None, frame_width: int = 0, frame_height: int = 0, columns: int = 0, rows: int = 0, margin: int = 0, spacing: int = 0)

Bases: simvx.core.atlas.TextureAtlas

Grid-based sprite sheet with uniform frame size.

Auto-generates AtlasTexture regions for each cell in a grid layout. Used for character animations, tile sets, icon grids.

Regions are named frame_0, frame_1, … in row-major order.

Initialization

property frame_count: int

get_frame(index: int) → simvx.core.atlas.AtlasTexture | None

Get the AtlasTexture for frame at index.

get_frame_rect(index: int) → tuple[int, int, int, int]

Get (x, y, w, h) for frame at index. Returns (0,0,0,0) if out of range.

get_frame_uv(index: int) → tuple[float, float, float, float]

Normalised UV rect for a frame by index.

__repr__() → str

add_region(name: str, x: int, y: int, w: int, h: int) → simvx.core.atlas.AtlasTexture

get_region(name: str) → simvx.core.atlas.AtlasTexture | None

remove_region(name: str) → bool

has_region(name: str) → bool

property region_count: int

property region_names: list[str]

get_uv(name: str) → tuple[float, float, float, float]

simvx.core.atlas.pack_atlas(sizes: list[tuple[str, int, int]], padding: int = 1) → tuple[int, int, dict[str, tuple[int, int, int, int]]]

Pack rectangles into a minimal atlas using a shelf algorithm.

Items are sorted by height (descending) then placed in rows. The resulting atlas dimensions are rounded up to the next power of two for GPU friendliness.

Args: sizes: List of (name, width, height) for each item to pack. padding: Pixels between packed items (and around the border).

Returns: (atlas_width, atlas_height, regions) where regions maps name -> (x, y, w, h).