GroomLab

Game export

Hair cards with LODs and baked texture maps, and strand exports for Unreal's groom system, Unity and glTF, including color patterns and feathers.

Hair cards with baked maps
Cards follow the groom's clumps; maps are baked from its own strands.

Cards

Add a Cards node (Add Node > Games) at the point in the graph that should be converted to cards, or run groomlab.create_cards(groom, lod="mid"). Cards are placed along the groom's clumps and shape, and their textures are baked from the groom's own strands. To lay one card along each guide instead (a card per curve), set the node's Cards From to Guides and link a Guides node to its guides input (drawing the link sets it; create_cards(groom, from_guides=True) does both).

The top of the node's panel shows the cards' cost and has Show cards, Show textures, LOD, Bake Maps, Bake Scalp and the exports, in view however far its parameters scroll. While a bake runs, the panel shows a wait cursor, greys out its buttons and says what it is baking.

  • LODs: Hero, Mid and Low set a triangle budget (about 50k, 15k and 4k) and a matching card layout. Lower levels use fewer cards of the same size, so the silhouette is preserved.
  • Shading consistency: in the viewport, cards are lit like the strands (normals, highlight and ambient), and each card is tinted with its own strands' color, root to tip, while the textures stay shared across cards. The exports carry the same data: the normals, and the tint as a vertex color (glTF: _TINT).
  • Baked maps: depth, coverage, tangent, attribute, color and AO, in Unreal's hair card texture layout.
  • Stable atlas: after a bake, cards rebuilt by later edits keep their place in the atlas. A node whose maps are out of date shows an orange badge.
  • Bake Scalp bakes the hair near the skin into the scalp's UVs, with a hair cap mesh, so low LODs don't show bare skin between cards.
  • Cards that don't pass through each other (the Cards node's Separation section): Feather Separation (off by default; cards saved before GroomLab 0.34 keep 0.05) pushes feather cards that cross or nearly touch apart along their normals, so overlapping feathers lie on each other instead of clipping; Separation does the same for hair cards (off by default). The gap is a share of the narrower card's width, the roots stay where they are, and only the mesh moves: the baked maps stay valid. Separation Iterations (8) settles crowded cards further. (SelfCollide separates strands, not cards.)
  • Braids become tubes: a braid from a Braid node gets its own geometry, set by the Cards node's Braid Cards. Sections (the default) gives each of its sections a tube that winds over and under the others as the hair does, so the weave is in the mesh and shows from every side; each tube's texture is its section's hair, unrolled around it. Tube wraps one tube around the whole braid, and Cross gives the crossed flat cards of earlier versions. Braid Sides sets the quads around each tube (6 by default), and the level of detail sets how closely a tube follows its section's turns. The hair going into a braid (fed hair lying along the scalp, a box braid's gather at the root) gets flat cards of its own, from the scalp into the braid.
  • Cards are always built from the full groom; the viewport preview density does not affect them.

Export card maps

Export Maps... on the Cards node (or GroomLab > Export > Card Maps...) writes the cards' texture maps the way your engine wants them, in one click. In the app it is the Card maps target of the Export panel; in Blender, Card Maps... in the GroomLab panel.

  1. Pick a Preset: Unreal Hair Cards, Unreal (packed), Unity HDRP Hair, Separate maps (all), or one of your own.
  2. Set the Resolution (any size up to 8192; the atlas is square), the Format (TGA, PNG, TIFF or EXR) and the Bit depth (8 or 16 for PNG and TIFF; 16-bit half or 32-bit float for EXR; TIFF also 32-bit float).
  3. Leave Padding on Full: every map but the coverage spreads its colors past the strands all the way, each card's meeting its neighbours' halfway, so even the smallest mip maps hold the hair's colors and nothing dark bleeds into the edges. A number of texels limits it. Supersampling 2x or 4x bakes the maps larger and scales them down for smoother edges (slower).
  4. Choose the folder and the name, and click Export. Thumbnails of the written maps appear under the button.

The Unreal Hair Cards preset as 8-bit TGA writes the same files as Bake Maps, byte for byte. Exporting never changes the groom's own bake (what its cards view shows).

The maps

MapWhat it isChannels
depthHow far the strands lie off the card: 0.5 on the card, higher in front (Unreal's Depth; FiberShop's Height)1
coverageOpacity (the alpha): how much of each texel the strands cover1
tangentThe strands' direction in card space as Unreal reads it: x across, y root to tip, z out of the card3
flowThe same direction as a two-channel flow map in the texture (x across, y root to tip up the texture)2
normalA tangent-space normal of the strands as round fibers: facing out of the card at a strand's center and turning toward its sides at the edges. OpenGL or DirectX green, set per preset3
colorThe strands' color (albedo)3
aoAmbient occlusion: 1 where the hair is open, darker under other hair1
root0 at each strand's root, 1 at its tip (Unreal's CoordU)1
seedA random value per strand (Unreal's Seed)1
idA random value per clump (the strands' clump; per card without one)1
rootuvWhere each strand grows on the scalp: its UV there2
specularShine: brightest at the root and about 40% duller at the tip, varied per strand by ±15% and dimmed where occluded1
translucencyHow much hair the light passes through: the strands over each texel, softened over a few texels. Higher where the hair is denser, so it works as a thickness map; invert it for a transmission mask1
iridescenceA FeatherColor's iridescence (0 without one)1

Every data value is written 0 to 1 in every format (a direction as 0.5 + 0.5 × its component), so a material reads PNG, TGA, TIFF and EXR files the same way. Only color depends on the file's color space: Auto writes it sRGB in TGA, PNG and TIFF and linear in EXR.

Presets

PresetFiles (R, G, B, A)
Unreal Hair Cards (TGA)Depth, Coverage, Tangent (xyz), Attribute (root U, root V, seed, root to tip), Color (RGB, plus the iridescence in alpha when the groom has any), AO, AO_world (the whole groom's AO, in the second UV set)
Unreal (packed) (TGA)Color (RGB + AO in alpha), AO_world (in the second UV set), Data (depth, root to tip, seed, coverage), Tangent (xyz)
Unity HDRP Hair (PNG)BaseColor (RGB + coverage), Normal (OpenGL), Mask (0, AO, root to tip, specular as smoothness), AO_world (in the second UV set), Tangent (xyz), Data (depth, ID, translucency)
Separate maps (all) (PNG)Every map in its own file: Albedo, Alpha, Depth, Direction (flow), Tangent, Normal, Root, ID, Seed, AO, AO_world, Specular, Translucency, RootUV, and Iridescence when the groom has any

The Unreal presets use DirectX normals; Unity and Separate maps use OpenGL normals.

Packing your own

Open Advanced to see the packing table: one row per output file, with its name (the {map} in the file name), four channels R, G, B and A, and a color space. Each channel takes a map's channel (depth, tangent.x, color.r...), a constant 0 or 1, or nothing (a file with only R is grayscale; with A it is RGBA). Check inv to write 1 minus the value. Add File and Remove File change the rows. Any edit switches the preset to Custom.

Type a name beside Save as Preset to keep it. Presets are JSON files in Documents/GroomLab/card_presets, shared by Maya, the app and Blender; send the file to share one. Folders listed in GROOMLAB_CARD_PRESET_PATH are read too (for a studio's shared presets). Delete removes a preset of yours. File names sets the naming template, with {name}, {map} and {res} (default {name}_{map}).

{
  "name": "My packed",
  "format": "png",
  "bitDepth": 8,
  "normal": "directx",
  "files": [
    {"map": "Mask", "channels": ["depth", "root", "id", "coverage"]},
    {"map": "Color", "channels": ["color.r", "color.g", "color.b", "1-ao"], "colorSpace": "srgb"}
  ]
}

A channel name ending in ? (iridescence?) is left out when the groom doesn't have that data.

groomlab.bake_card_maps(groom, preset="Unity HDRP Hair", resolution=4096, format="png", bit_depth=16,
                        directory="C:/game/hair", name="hair")
groomlab.card_map_presets()        # every preset, as dicts
groomlab.card_map_sources()        # the maps and their channels
groomlab.save_card_map_preset("My packed", preset_dict)

The color map

The Color map holds the strands' authored base color/albedo. Use it with aiStandardHair's Base Color, Unreal's Hair shading model, or whenever the texture must preserve the authored color independently of a particular light and shader. Lighting and hair-BSDF appearance are never baked into the color map.

The Color map is sRGB, with Rec.709 primaries, as engines expect. In Maya, colors are in the scene's rendering space (ACEScg under ACES), so the bake converts them to Rec.709 exactly once. A file node set to sRGB converts them back to the scene space; engines read the same Rec.709 color. As with every sRGB texture, colors outside the Rec.709 gamut cannot be represented without clipping; use a wide-gamut linear format when that data must be preserved.

In the engine

  • Unreal: import the maps with sRGB on only for color (the Color map, and the Color of the packed preset, whose alpha stays linear). Set the data maps (Depth, Coverage, Tangent, Attribute, AO, Data) to sRGB off with the Masks or Linear Color compression. With Unreal Hair Cards, set the textures on the groom asset's Cards LOD; the Hair Attributes node reads them. Unreal (packed) is for a hair card material of your own (Hair shading model, Masked).
  • Unity HDRP: import BaseColor as sRGB with alpha as transparency; set Normal to Normal map (OpenGL, Unity's convention); set Mask, Tangent and Data with sRGB (Color Texture) off. Mask follows the Lit mask map layout, so its G (AO) and A (smoothness) work with the Lit and Hair shader graphs as they are.
  • Bit depth: 8-bit is enough for color, coverage and AO. Use 16-bit PNG or EXR for depth and directions on hero assets to avoid banding.

Export targets

TargetMenuOutput
Unreal cardsCards node > Export Unreal Cards... (or GroomLab > Export > Unreal Cards...)_cards.fbx, the seven maps, the hair cap and a JSON describing the channels
Unreal strandsGroomLab > Export > Unreal Groom...Alembic in Unreal's groom schema, with guides for simulation
Unity cardsGroomLab > Export > Unity Cards...FBX (Y up, meters), PNG maps and suggested HDRP and URP materials
Unity strandsGroomLab > Export > Unity Strands (.abc)...Alembic for Unity's strand hair package
glTF cardsGroomLab > Export > glTF Cards....glb with embedded maps, one mesh per LOD
Card mapsCards node > Export Maps... (or GroomLab > Export > Card Maps...)The maps as a preset packs them: TGA, PNG, TIFF or EXR, up to 8K (Export card maps)

When several LODs are exported into one folder, file names end in _hero, _mid or _low.

groomlab.create_cards(groom, lod="hero")
groomlab.export_cards_unreal(groom, "C:/game/hair", "hair", lod="hero")
groomlab.export_cards_gltf(groom, lods=["hero", "mid", "low"])
groomlab.export_unreal_groom(groom, "C:/game/hair.abc")

Importing the groom into Unreal

Import the .abc in Unreal as a Groom with the default conversion settings (Rotation 0, 0, 0; Scale 1, 1, 1). No rotation or flip is needed: the export writes the strands in Unreal's own space (Z up, left-handed, centimeters), turned from your scene's the way Unreal's FBX importer turns a mesh from the same scene (a Y-up scene's (x, y, z) becomes (x, z, y), a Z-up one's (x, -y, z); Blender's meters become centimeters). So the groom lines up with the head imported as FBX from the same scene, with that importer's defaults too.

For hair that follows the character, import the head as a skeletal mesh, create a Groom Binding from the groom to it, and set the binding on the Groom component. In Blender the groom is in the scalp object's local space: apply the scalp's transforms (or leave it at the origin) before exporting the head and the groom.

Unreal groom attributes

The Unreal groom export writes the attributes Unreal's groom importer reads, as arbGeomParams: groom_version_major / groom_version_minor, groom_group_name, groom_group_id (from the groupId attribute), groom_id, groom_width (per point), groom_root_uv (with scalp UVs), groom_color (per point, with a color node: the hair's appearance, what it looks like, see Base color and appearance), groom_roughness (with HairColor's roughness), groom_clump_id (with a Clump), groom_iridescence (with FeatherColor iridescence) and groom_guide on the guide curves. It also writes the 64-bit strand ID as groomlab_strand_id_low / groomlab_strand_id_high. Other GroomLab attributes, including Attribute node output, are not written to the Unreal groom file.

Color patterns in engines

Bands, FeatherColor patterns and HairColor tips are per-point colors, and FeatherColor's iridescence is a per-point mask (Color patterns):

TargetColorsIridescence
Unreal strandsgroom_color per vertexgroom_iridescence per vertex; with Iridescence as AO (iridescence_as_ao=True) also groom_ao, which the Hair Attributes material node exposes
Cards (Unreal, glTF, Unity)Baked into the Color map as base color/albedo, without viewport lighting or hair-BSDF shading (a feather's card is its vane laid flat, so its patterns map directly)The Color map's alpha (Unreal; RGBA only then); Unity's Mask map red channel; glTF: not carried
Unity strandsOne color per strand (Cd, as in GroomLab's Alembic; bands and patterns along a strand are not carried)Not carried
glTF cardsThe baked _BaseColor and each card's _TINTNot carried (the alpha is the coverage)

The repository's docs/UNREAL_HAIR_MATERIAL.md describes an Unreal material (for strands and cards) that mixes in the iridescent color by that mask, with the hue rotated by the view angle; tools/unreal/groomlab_hair_material.json describes the same graph node by node.

Feathers in engines

  • As cards: groomlab.create_feather_cards(groom, lod="mid") creates one alpha-tested strip per feather, with both vanes and the rachis baked into its texture, and similar feathers sharing a few textures. Each card is folded along a spine so lifted or cupped vanes form a V. Flatten (featherFlatten, 1 by default) keeps each card in one plane with one fold per half, so its quads are flat and the texture shows no facets; lower it to follow the barbs' twists more closely (cards saved before GroomLab 0.34 keep 0). Unreal, Unity and glTF export them.
  • As strands: the rachis becomes a mesh to skin with the character, and the barbs are strands rooted on it.
    • Unreal: groomlab.create_rachis_mesh, export_rachis and export_unreal_groom.
    • Unity: GroomLab > Export > Unity Feathers... writes the strands, the rachis FBX and a manifest of the Hair Asset settings.

On this page