df-portrait-compositor 0.1.0

Generate dwarf portraits from Dwarf Fortress sprite sheets

df-portrait-compositor

Generate dwarf portrait images from Dwarf Fortress (Steam/Premium) sprite sheets by parsing the game's graphics definition files, evaluating layer conditions against appearance data, and compositing the matching tiles with palette recoloring.

Features

• Parses DF's graphics_creatures_portrait_dwarf.txt into structured layer rules
• Evaluates 10+ condition types: caste, tissue color/length/shaping/curliness, body part modifiers (head broadness, nose shape, eye shape), equipment, syndromes (vampire, zombie, necromancer, ghost), and randomized part selection
• Implements DF's "first match wins" layer group logic for mutually exclusive alternatives
• Composites selected tiles onto an RGBA canvas with proper alpha blending
• Palette recoloring for skin and hair colors using DF's palette PNGs
• Appearance-hash-based caching so portraits only regenerate when the dwarf's look changes
• Deterministic random seed (from unit ID) for consistent clothing/feature variation

Installation

pip install df-portrait-compositor

Or install from source:

git clone https://github.com/Been012/df-portrait-compositor.git
cd df-portrait-compositor
pip install -e .

Requirements

• Python 3.11+
• Pillow
• A Dwarf Fortress Premium (Steam) installation (for the sprite sheet PNGs and graphics definition file)

Quick Start

from df_portrait_compositor import compose_portrait, DwarfAppearanceData

# Point to your DF install directory
df_install = r"C:\Program Files (x86)\Steam\steamapps\common\Dwarf Fortress"

# Build appearance data (all fields have sensible defaults)
appearance = DwarfAppearanceData(
    sex="female",
    skin_color="PEACH",
    hair_color="BROWN",
    hair_length=150,
    hair_shaping="BRAIDED",
    beard_length=0,
    head_broadness=120,
    eye_round_vs_narrow=80,
    nose_upturned=130,
    nose_broadness=90,
    random_seed=42,
)

# Compose and save
img = compose_portrait(df_install, appearance, scale=2)
img.save("portrait.png")

Using generate_portrait for Caching

If you are generating portraits for many dwarves, generate_portrait handles caching automatically. It takes a raw appearance dict and a cache directory, and only regenerates when appearance data changes:

from pathlib import Path
from df_portrait_compositor import generate_portrait

appearance_dict = {
    "sex": "male",
    "skin_color": "PEACH",
    "hair_color": "BLACK",
    "beard_color": "BLACK",
    "hair_length": 200,
    "beard_length": 300,
    "beard_shaping": "DOUBLE_BRAIDS",
    "head_broadness": 140,
    "nose_length": 160,
    "eyebrow_density": 130,
    "random_seed": 1001,
}

portrait_path = generate_portrait(
    df_install=r"C:\Program Files (x86)\Steam\steamapps\common\Dwarf Fortress",
    unit_id=1001,
    appearance=appearance_dict,
    cache_dir=Path("./portrait_cache"),
)
# Returns Path to the PNG, or None on failure

Getting Appearance Data from DFHack

The appearance fields map to data extracted from DF's internal structures via DFHack. You need a Lua script running inside DFHack to read each dwarf's:

• Sex: unit.sex (0 = female, 1 = male)
• Skin/hair/beard colors: Resolved from unit.appearance.colors via caste.color_modifiers and descriptor_color lookups
• Hair/beard length: From unit.appearance.tissue_length indexed through caste.bp_appearance.style_part_idx
• Hair/beard shaping: From unit.appearance.tissue_style (0=NEATLY_COMBED, 1=BRAIDED, 2=DOUBLE_BRAIDS, 3=PONY_TAIL, 4=CLEAN_SHAVEN)
• Body part modifiers (head broadness, nose shape, eye shape): From unit.appearance.bp_modifiers indexed through caste.bp_appearance.modifier_idx/part_idx
• Equipment: From unit.inventory items

The dfhack_scripts/ directory contains debug scripts that demonstrate how to read these values:

Script	Purpose
storyteller-debug-colors.lua	Dump color modifier values for all citizens
storyteller-debug-hair.lua	Identify tissue types and lengths for each styled tissue
storyteller-debug-bpmod.lua	Show body part appearance modifiers (density, broadness, etc.)

Tissue Length Index Layout

The indices into unit.appearance.tissue_length and unit.appearance.tissue_style vary by sex. The mapping is determined by caste.bp_appearance.style_part_idx and style_layer_idx, but for the default dwarf creature definition:

Male (caste index 1):

Index	Body Part	Tissue
0	HEAD	Hair
1	R_CHEEK	Beard (right cheek whiskers)
2	L_CHEEK	Beard (left cheek whiskers)
3	CHIN	Beard (chin whiskers)
4	LIP	Moustache
5	R_CHEEK	Sideburns
6	L_CHEEK	Sideburns

Female (caste index 0):

Index	Body Part	Tissue
0	HEAD	Hair

API Reference

Core Functions

compose_portrait(df_install, appearance, scale=2)

Compose a portrait from sprite sheet layers.

• df_install (str): Path to the Dwarf Fortress installation directory.
• appearance (DwarfAppearanceData): Dwarf appearance data for condition matching.
• scale (int): Upscale factor. 1 = 96px native, 2 = 192px (default).
• Returns: PIL.Image.Image (RGBA).

generate_portrait(df_install, unit_id, appearance, cache_dir=None)

Generate and cache a portrait PNG for a dwarf.

• df_install (str): Path to the DF installation directory.
• unit_id (int): Dwarf unit ID (used for filename and random seed).
• appearance (dict): Raw appearance dict (keys match DwarfAppearanceData fields).
• cache_dir (Path | None): Directory to store cached PNGs. Required for output.
• Returns: Path to the generated PNG, or None on failure.

Data Classes

DwarfAppearanceData

Dataclass holding all appearance attributes used for condition evaluation. All fields have defaults, so partial data still produces a portrait (with fewer layers).

Key fields: sex, skin_color, hair_color, beard_color, hair_length, hair_shaping, hair_curly, beard_length, beard_shaping, head_broadness, eye_round_vs_narrow, eye_deep_set, eyebrow_density, nose_upturned, nose_length, nose_broadness, is_vampire, is_zombie, is_necromancer, is_ghost, equipment, random_seed, age.

SelectedLayer

Dataclass representing a layer selected for rendering: tile_page, tile_x, tile_y, palette_name, palette_index, use_item_palette.

LayerRule

Dataclass representing a parsed layer rule from the graphics definition file, including all condition types.

Parser and Evaluator

parse_portrait_graphics(filepath)

Parse a DF portrait graphics definition file into a list of LayerRule objects.

evaluate_layers(rules, appearance)

Evaluate layer rules against appearance data and return matching SelectedLayer objects in render order.

Constants

TILE_SIZE

The native tile size in pixels (96).

License

MIT