GroomLab

Utilities

Converting between guides, strands and Maya curves or meshes, starting from existing curves, transferring a groom to a new scalp, copying graphs between grooms, relinking missing files, colliders and themes.

These commands are in GroomLab > Utilities. They act on the active groom (Find Missing Files: the selected grooms), and each is one undo step.

Conversions

CommandResult
Guides to CurvesOne NURBS curve per guide, tagged with its guide ID.
Curves to Guides...Tagged curves update their own guide in place; any other curve becomes a new guide.
Strands to Curves...The evaluated strands as plain Maya curves (20,000 by default), with their attributes.
To Mesh...A snapshot of the groom as one mesh, with UVs: the strands as tubes or ribbons, the scales as their plates, feathers as barbs and rachis, cards, instances. For a mesh that follows the animation, see The groom as a mesh.
Bake Node to Guides...The groom's output, or any node's strands or guides, converted to brushable guides. To keep them procedural instead, use a ToGuides followed by a Sculpt node (Node graph).

To edit guides with Maya tools: Guides to Curves, edit the curves (CVs, lattices, a sculpt deformer), then Curves to Guides....

Modeled hair tubes

Hair modeled as polygon tubes (open quad tubes, no caps; a pointed tip is fine) comes into GroomLab two ways, in Maya. Both read a tube as smooth mesh preview draws it (the 3 key) and work on every tube of the selected meshes (or groups).

Tubes to Curves... makes curves from the tubes:

  • Tube Shape: a curve along each lengthwise edge run, a point per edge loop.
  • Tube Center: a curve through the middle of each tube. Add center volume fills the tube with that many curves (the center one and rings around it, evenly laid out, staying inside the tube from root to tip).
  • Add to the selected groom makes them guides in their own groups (tubesShape, tubesCenter; new numbered groups each time, or Add to existing guide groups). Convert to Maya curves leaves them in the scene, grouped in the Outliner.
  • Count bevels as one curve: edge loops or runs held close together to keep a crease make one curve.
  • Keep each tube's hair to its own guides (adding to a groom): a guide map, tubes, gives each tube's guides a value of their own, and an Interpolate without a regionMap takes it, so each strand blends only the guides of the tube rooted nearest it, never a neighbouring tube's (Regions).

Convert Tubes to GroomLab Tubes makes one tube guide per modeled tube, to keep shaping with GroomLab's tools:

  • The guide is rooted on the scalp under the tube's root loop and leaves it straight out, so the root section lies on the scalp as the loop does.
  • The tube's shape is the root loop: a point per root vertex, a smooth curve through them, added to the groom's tube shape library under the mesh's name (converting again reuses it).
  • Along the tube only its thickness is matched: each section is as wide and as flat as the modeled tube there, and turns as its edges do. Where the modeled sections part from the root's shape (a lock that rounds out), the sections are drawn a little wider, so the hair filling them does not read thinner than the mesh did.
  • A progress bar shows how far along it is; Esc cancels it (nothing is changed).

Delete All Flow Arrows

Removes every flow arrow and sink from the active groom in one undo step, and reports how many were removed. The arrows are kept on the groom (laid with the Flow tool), not in the Flow node. The Flow tool's card counts them and has the same command as Clear All. See Short hair without guides.

The groom as a mesh

To Mesh... makes a static mesh of the current frame. Make picks what it is made of: auto (the scales when the groom has some, else instances, else cards, else feathers, else the strands), strands, scales, feathers, cards or instances. The faces are quads wherever the shape allows (a scale's tip, a tube's tip and a prototype's own triangles stay triangles).

  • Strands: a tube (Tube sides around, the tip closed) or a flat ribbon along each strand, as wide as the strand times Width scale. UVs run across the strand (u) and from root (v 0) to tip (v 1); Per-strand UVs adds a second UV set, strandUVs, with each strand in its own cell of a grid. Beyond At most strands, the strands are thinned by strand ID, the same ones a lower density keeps.
  • Scales: every scale's plate, bent onto the skin as it renders, with the plates' UVs. A scale whose prototype is one of your scene's meshes comes out as a flat quad.
  • Feathers: the barbs as tubes or ribbons, and the rachis (shaft) tubes.
  • Cards: a Cards node's cards (put the ToMesh after it), as quads with the atlas UVs the cards export with.
  • Instances: every instance's mesh where it sits: an Instance node's scene mesh (or a Scales node's plates), each one a copy of its prototype with the prototype's UVs.

For a mesh that follows the animation, add a ToMesh node in the Graph Editor. The groom draws its mesh in the viewport at once, in place of the strands (Show mesh in the node's panel, the groom's displayMesh, switches back to the strands). The mesh shows what the node receives, so its position decides what it includes: after a Simulate's Interpolate it moves with the simulation, and before a Noise it leaves the frizz out. It follows the scalp (with Follow scalp on), Simulate (live or baked), keyed params and graph edits. A tube mesh keeps its vertices and faces from frame to frame; only the points move. Changing the node's density, strand count, style or sides rebuilds it. Each ToMesh node passes its strands on unchanged, and all of them share one mesh.

Mesh in Scene in the node's panel makes a Maya mesh connected to the groom's outMesh (or selects the one already there), to sculpt or model further or to cache: export it with Maya's Alembic export (Cache > Alembic Cache > Export Selection to Alembic, or AbcExport -frameRange 1 120 -uvWrite -root |hair_mesh -file hair.abc). While that mesh exists, it shows the mesh instead of the groom. Export Mesh... writes the node's mesh at this frame as an OBJ, FBX or Alembic file, for ZBrush, baking or 3D printing.

From Python:

import groomlab
groomlab.to_mesh(groom, make="scales")                                 # a snapshot
node = groomlab.add_to_mesh(groom, after="interpolate", style="ribbon")  # live, drawn by the groom
mesh = groomlab.to_mesh_shape(groom)                                   # Mesh in Scene
groomlab.export_mesh(groom, "scales.obj", node=node)                   # Export Mesh...

Tube meshes are heavy: 4 sides make about 4 vertices per strand point, so 20,000 strands of 16 points are 1.3 million vertices. A mesh of the full groom is meant for renderers and tools without curve support, or for a few hero strands. Game engines usually use guide-driven strands (Unreal grooms) or hair cards instead (Game export).

Start from existing curves

  • Maya curves: select the scalp and the curves, then Create Groom from Selection. Or add them later with Edit Guides > From Curves under Guide groups.
  • Alembic curves (from Houdini or XGen): GroomLab > Import > Alembic Curves..., or groomlab.import_guides_from_alembic(groom, path). In the app and Blender, an ImportCurves node reads an Alembic file's curves.

Transfer to a new scalp

To move a groom to a new sculpt, a retopologized head or another character, open Utilities > Transfer Groom to Scalp... (the same in the app and Blender; the app's Properties > Inputs Scalp row has a transfer button too). The groom's scalp is shown on the left and the mesh picked in New scalp on the right, each in its own view (Alt moves the camera).

Pick a Method:

MethodFor
Closest pointThe new mesh where the old one was (a new sculpt in place).
Fit boundsThe same shape elsewhere or of another size.
Markers: alignThe same head moved, turned or scaled. 3 marker pairs or more.
Markers: warpAnother character: a head of other proportions, mapped feature to feature. 4 pairs or more.
UVBoth meshes share their UV layout (a retopology). Exact, no markers.

Markers work as in Wrap: click a point on each mesh. Pair N is the Nth point on the left and the Nth on the right, in any click order (five on the old head, then five on the new, or alternating).

  • A point without its partner yet shows as a hollow ring; it fills in once paired.
  • Ctrl+click deletes a point and its partner, and both sides renumber.
  • Drag a point to slide it; hover one to light its partner.
  • Ctrl+Z / Ctrl+Y in the window undo and redo marker edits; Symmetry mirrors each new point across the mesh's middle.
  • Ears, temples, crown, nape and brow make good pairs; six to ten are plenty for a warp.
  • The pairs are saved with the groom (and in .groom files), so a later transfer reuses them.

Guides, parts, flow arrows and painted maps are all transferred through the mapping; each guide is rotated and scaled with the surface around its root (Keep guide lengths disables the scaling). Copy mesh color sets also copies Maya color sets. While it transfers, the window shows a wait cursor, greys out its buttons and says what it is doing. One Ctrl+Z in Maya undoes the whole transfer, and the window updates accordingly.

By default the groom keeps the size it shows: on a bigger head the hair keeps its lengths and the same density covers more skin. Fit groom to the new scalp's size treats the new scalp as the old one resized instead: the groom's scale grows with the scalp's area (Scaling a groom), so lengths, widths and clumps follow, the strand count stays the same and the guides scale about their roots (the mapping only turns them). In Python: groomlab.transfer_groom(groom, "bigHead", fit_size=True).

Without the window: click Pick on the Scalp row of the groom's Attribute Editor, or choose the mesh in the Scalp node's Mesh field (closest point method).

groomlab.transfer_groom(groom, "newHead")                                  # closest point
groomlab.transfer_groom(groom, "bigCat", method="bounds")                  # another size or place
groomlab.transfer_groom(groom, "otherHead", method="markersWarp",
                        markers=[("head.vtx[12]", "otherHead.vtx[40]"), ...])

Copy Graph to Other Grooms

Pin (or select first) the source groom, select the target grooms and choose Copy Graph to Other Grooms.... Choose whether to keep or replace their guides; Copy painted maps also copies the maps the graph reads.

Find Missing Files

After a failed copy or a moved project, Find Missing Files... relinks the files the selected grooms (or every groom) cannot find: texture maps, images and Alembic files referenced in the graph, guide caches and groom files. Pick a folder; it searches it and its subfolders for files of the same name.

  • Names compare without case on Windows.
  • When several files share a name, the one whose folders best match the stored path is used. If none matches, the file is reported as ambiguous and not relinked.
  • The Script Editor lists every file relinked, ambiguous or still missing. It is one undo step.
groomlab.missing_files(groom)                         # what is missing, by kind
groomlab.find_missing_files([groom], "D:/recovered")  # relinked, still_missing, ambiguous

Collect Files

Collect Files copies every file the selected grooms (or every groom) use from outside the scene's folder into its groomlab folder (masks, caches, cards and exports, under each groom's name) and points the grooms at the copies, kept relative. The scene's folder then holds everything, ready for Archive Scene, a zip or another machine. Files already inside stay where they are; a missing file is listed in the Script Editor (Find Missing Files relinks it). Save the scene first. It is one undo step (the copies stay).

groomlab.collect_files()   # copied, missing, inside

Files in a pipeline

Every file a groom uses shows in Maya's File Path Editor (Windows > General Editors) under GroomLab: its texture maps, the images and Alembic files its graph reads, its guide cache, Simulate bakes, card bake and the groom file it renders from. Repath them there or with Replace String and the groom follows, its paths kept relative to the scene.

Farm submitters, publish and archive scripts can collect them too (Maya's own Archive Scene only sees Maya's node types):

for groom in cmds.ls(type="groomLabShape"):
    for f in groomlab.file_dependencies(groom):      # kind, key, path, resolved, exists
        print(f["resolved"])
groomlab.repath_file(groom, "map", "density", "/publish/hair/density.png")

Each file is a small groomLabFile node connected to its groom (ls -type groomLabFile, the path in its fileName), kept in step as the groom changes and before every save.

Colliders

Click Pick on the Collider row of the Attribute Editor's Inputs, then click the body, collar or hat in the viewport or the Outliner (groomlab.add_collider(groom, mesh)). The button reads Cancel while waiting; Esc cancels. GroomLab adds a ColliderMesh node and a Collide node before the output. Animated collision meshes are evaluated per frame in the viewport, renders and exports.

In the Graph Editor, a Scalp or ColliderMesh node's panel has a Mesh field: a menu of the scene's meshes, the same pick button and Select. Choosing a mesh there reconnects the scalp or that collider, as the Attribute Editor does.

Themes

A theme sets the colors of the Groom Tools, the Graph Editor, GroomLab's windows and the viewport's guides. Pick one in GroomLab > Theme, or Theme in the Groom Tools' More menu or the Graph Editor's Edit menu. It applies at once and is remembered across sessions.

ThemeLook
Charcoal (default)Graphite greys with each section on a soft card, one iris-violet accent for what is on or chosen; the Inter font, pill tabs, sentence-case section titles.
PlayfulCharcoal with bright primaries: colored tool icons and node headers, rounder corners, a blue accent.
StudioLow-key DCC greys, small corners, one steel-blue accent.
PaperLight: warm paper and ink with one deep teal, for bright rooms and reading the groom against light.

To make your own, choose Theme > New Theme from Current... in the Groom Tools or the Graph Editor: it copies the active theme to a JSON file in your themes folder. Edit its colors, then Theme > Reload Theme. In Python:

from groomlab.ui import theme
path = theme.create_theme("mine", base="charcoal")  # a copy to edit
theme.set_theme("mine")

A theme can set only some keys; the rest come from the theme it names in "extends" (Playful by default).

On this page