Sprite API Reference

The sprite module provides Python bindings to the Go sprite generator.

Classes

SpriteGenerator

map_style.generator.sprite.SpriteGenerator

SpriteGenerator(verbose=False)

Manages sprite generation from icon libraries using native bindings.

Initialize the sprite generator.

PARAMETER	DESCRIPTION
`verbose`	Enable verbose output from sprite tool TYPE: `bool` DEFAULT: `False`

Source code in map_style/generator/sprite.py

def __init__(self, verbose: bool = False):
    """Initialize the sprite generator.

    Args:
        verbose: Enable verbose output from sprite tool
    """
    self._native = _get_native()
    self.verbose = verbose

create_icon_library

create_icon_library(
    icon_library_path,
    required_icons,
    icons_source_dir=None,
    raster_source_dir=None,
)

Create an icon library directory structure with manifest.

PARAMETER	DESCRIPTION
`icon_library_path`	Output path for the icon library TYPE: `Path`
`required_icons`	List of required icon definitions TYPE: `list[dict[str, Any]]`
`icons_source_dir`	Source directory containing SVG icons TYPE: `Path \| None` DEFAULT: `None`
`raster_source_dir`	Source directory containing raster/PNG icons TYPE: `Path \| None` DEFAULT: `None`

Source code in map_style/generator/sprite.py

def create_icon_library(
    self,
    icon_library_path: Path,
    required_icons: list[dict[str, Any]],
    icons_source_dir: Path | None = None,
    raster_source_dir: Path | None = None,
) -> None:
    """Create an icon library directory structure with manifest.

    Args:
        icon_library_path: Output path for the icon library
        required_icons: List of required icon definitions
        icons_source_dir: Source directory containing SVG icons
        raster_source_dir: Source directory containing raster/PNG icons
    """
    icon_library_path.mkdir(parents=True, exist_ok=True)

    # Write manifest.json
    manifest_path = icon_library_path / "manifest.json"
    manifest_path.write_text(json.dumps({"required": required_icons}, indent=2))

    # Copy icon directories if provided
    if icons_source_dir and icons_source_dir.exists():
        icons_dest = icon_library_path / "icons"
        shutil.copytree(icons_source_dir, icons_dest, dirs_exist_ok=True)

    if raster_source_dir and raster_source_dir.exists():
        raster_dest = icon_library_path / "raster"
        shutil.copytree(raster_source_dir, raster_dest, dirs_exist_ok=True)

generate_sprite

generate_sprite(icon_library_path, output_dir)

Generate sprite images and metadata from icon library.

PARAMETER	DESCRIPTION
`icon_library_path`	Path to the icon library directory TYPE: `Path`
`output_dir`	Directory where sprite files will be generated TYPE: `Path`

RAISES	DESCRIPTION
`SpriteGenerationError`	If sprite generation fails

Source code in map_style/generator/sprite.py

def generate_sprite(
    self,
    icon_library_path: Path,
    output_dir: Path,
) -> None:
    """Generate sprite images and metadata from icon library.

    Args:
        icon_library_path: Path to the icon library directory
        output_dir: Directory where sprite files will be generated

    Raises:
        SpriteGenerationError: If sprite generation fails
    """
    if not icon_library_path.exists():
        raise FileNotFoundError(f"Icon library not found at {icon_library_path}")

    output_dir.mkdir(parents=True, exist_ok=True)
    self._native.generate_sprite(icon_library_path, output_dir, self.verbose)

validate_sprite_output

validate_sprite_output(output_dir)

Validate that sprite generation produced expected outputs.

PARAMETER	DESCRIPTION
`output_dir`	Directory to check for sprite files TYPE: `Path`

RETURNS	DESCRIPTION
`bool`	True if all expected files exist

Source code in map_style/generator/sprite.py

def validate_sprite_output(self, output_dir: Path) -> bool:
    """Validate that sprite generation produced expected outputs.

    Args:
        output_dir: Directory to check for sprite files

    Returns:
        True if all expected files exist
    """
    return self._native.validate_output(output_dir)

slice_sprite

slice_sprite(sprite_path, output_dir)

Slice an existing sprite into individual PNG files.

PARAMETER	DESCRIPTION
`sprite_path`	Path to the sprite PNG file TYPE: `Path`
`output_dir`	Directory where individual icons will be saved TYPE: `Path`

Source code in map_style/generator/sprite.py

def slice_sprite(self, sprite_path: Path, output_dir: Path) -> None:
    """Slice an existing sprite into individual PNG files.

    Args:
        sprite_path: Path to the sprite PNG file
        output_dir: Directory where individual icons will be saved
    """
    self._native.slice_sprite(sprite_path, output_dir)

SpriteGenerationError

map_style.generator.sprite.SpriteGenerationError

Bases: Exception

Raised when sprite generation fails.

Functions

build_required_icons

map_style.generator.sprite.build_required_icons

build_required_icons(
    icon_names,
    raster_icons=None,
    stretchable_icons=None,
    casing_overrides=None,
)

Build required icons list for sprite manifest.

PARAMETER	DESCRIPTION
`icon_names`	Set of icon names to include TYPE: `set[str]`
`raster_icons`	Set of icon names that should be raster (not SDF) TYPE: `set[str] \| None` DEFAULT: `None`
`stretchable_icons`	Map of icon name to corner inset for stretchable SDF icons TYPE: `dict[str, float] \| None` DEFAULT: `None`
`casing_overrides`	Map of icon name to casing kind ("square", "circle", or "none") TYPE: `dict[str, str] \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`list[dict[str, Any]]`	List of icon definitions for manifest.json

Source code in map_style/generator/sprite.py

def build_required_icons(
    icon_names: set[str],
    raster_icons: set[str] | None = None,
    stretchable_icons: dict[str, float] | None = None,
    casing_overrides: dict[str, str] | None = None,
) -> list[dict[str, Any]]:
    """Build required icons list for sprite manifest.

    Args:
        icon_names: Set of icon names to include
        raster_icons: Set of icon names that should be raster (not SDF)
        stretchable_icons: Map of icon name to corner inset for stretchable SDF icons
        casing_overrides: Map of icon name to casing kind ("square", "circle", or "none")

    Returns:
        List of icon definitions for manifest.json
    """
    raster_icons = raster_icons or set()
    stretchable_icons = stretchable_icons or {}
    casing_overrides = casing_overrides or {}
    required_icons = []

    # Add SDF icons
    for name in sorted(icon_names - raster_icons):
        if name:  # Skip empty names
            entry: dict[str, Any] = {"name": name, "raster": False}
            if name in stretchable_icons:
                entry["stretchable"] = True
                entry["cornerInset"] = stretchable_icons[name]
                entry["padding"] = 0
            if name in casing_overrides:
                entry["casing"] = casing_overrides[name]
            required_icons.append(entry)

    # Add raster icons
    for name in sorted(raster_icons):
        if name:  # Skip empty names
            required_icons.append({"name": name, "raster": True})

    return required_icons

Usage Examples

Basic Sprite Generation

"""Basic sprite generation from an existing icon library."""

from pathlib import Path

from map_style.generator.sprite import SpriteGenerator

gen = SpriteGenerator(verbose=True)

# Generate from existing icon library
gen.generate_sprite(
    icon_library_path=Path("icons.iconLibrary"),
    output_dir=Path("dist/sprites"),
)

Creating an Icon Library

"""Full icon library workflow: define icons, create library, generate sprites."""

from pathlib import Path

from map_style.generator.sprite import SpriteGenerator, build_required_icons

gen = SpriteGenerator()

# Define required icons
icons = {"restaurant", "hospital", "school"}
required = build_required_icons(icons)

# Create icon library structure
gen.create_icon_library(
    icon_library_path=Path("build/icons.iconLibrary"),
    required_icons=required,
    icons_source_dir=Path("assets/icons"),
)

# Generate sprites
gen.generate_sprite(
    icon_library_path=Path("build/icons.iconLibrary"),
    output_dir=Path("dist/sprites"),
)

Validating Output

"""Validating sprite generation output."""

from pathlib import Path

from map_style.generator.sprite import SpriteGenerator

gen = SpriteGenerator()
output_dir = Path("dist/sprites")

gen.generate_sprite(
    icon_library_path=Path("icons.iconLibrary"),
    output_dir=output_dir,
)

if gen.validate_sprite_output(output_dir):
    print("All sprite files generated successfully")
else:
    print("Warning: Some sprite files may be missing")

Slicing Existing Sprites

"""Slicing an existing sprite sheet into individual PNG files."""

from pathlib import Path

from map_style.generator.sprite import SpriteGenerator

gen = SpriteGenerator()

# Extract individual icons from sprite sheet
gen.slice_sprite(
    sprite_path=Path("sprites/[email protected]"),
    output_dir=Path("extracted_icons"),
)

Environment Variables

Variable	Description
`PYSPRITE_LIB`	Override path to native sprite library

Native Library

The sprite generator uses a Go library compiled as a C-shared library. The library is automatically located in:

Path specified by PYSPRITE_LIB environment variable
sprite/dist/libpysprite.{so,dylib,dll}
generator/lib/libpysprite.{so,dylib,dll}

If the native library is not found, a FileNotFoundError is raised with build instructions.