GroomLab

Guides & brushes

The guide hierarchy (primary and child guides), tube guides (shaped tubes and Fill Tubes), guide groups with show/hide and color, freezing and soloing guides, the grooming brushes and their settings, and how a groom scales with its scalp.

Guides are the curves you shape by hand; the render strands are interpolated between them. The basic workflow:

  1. Open GroomLab > Groom Tools, pick Place and click or drag on the scalp.
  2. Shape the guides with Comb, then refine them with the other Shape brushes.
  3. Select some guides and choose Edit Guides > Children to generate child guides inside their tubes.
  4. Continue brushing; the strands update with every stroke.
A wolf's guides in the viewport over its fur
Every guide group, child groups too, is drawn in a hue of its own, starting from a hue of the groom's own.

In the app and in Blender

App: the Groom Tools dock on the left in Groom mode has the same tabs, tool grid, tool card and lists as Maya's, with Select and Freeze last. The keys below work without installing anything: B + drag, M + drag, Alt+Shift+X, Page Up / Page Down, S for Select, Esc to leave the brush, Alt + drag to move the camera with any brush. There is no marking menu. See GroomLab app.

Blender: press N in the 3D viewport and open the GroomLab tab: Groom Tools has the same tabs, tool grid, tool card and Guide groups list. B + drag, M + drag, Page Up / Page Down and S work as here; Y opens a pie menu in place of the marking menu, and Esc or right-click cancels a stroke. See Blender.

The hierarchy

Primary guides are the top level. Child guides are generated inside each parent's tube (the volume around a guide in which its children are placed), grandchildren inside the children's tubes, to any depth. A child stores its shape relative to its parent, so editing a parent moves and reshapes all its descendants.

  • Generate children: select guides, set the count in the box beside Edit Guides (in the picked group's box under Guide groups) and choose Edit Guides > Children. Only the selected parents get children (with no selection, the group picked in the list). Select children and repeat for grandchildren.
  • Place children by hand: click a child group in the Guide groups list and use Place or Draw; each new child is parented to the nearest guide of the parent group.
  • Restructure: Reparent... (move the selected children under another parent) and Promote / Demote... (move a group one level up, or under a sibling group) in Edit Guides change the hierarchy while keeping the guides' shapes.
  • Segments: the field in the picked group's box under Guide groups shows the point count of the selected guides, else of the picked group's (of every guide with All groups picked). Dragging it resamples them live; releasing applies it as one undo step. Frozen guides keep theirs. Resampling a whole group also sets the segments its new guides get from then on: drawn, placed, from curves, baked, and children generated into it (the group's tooltip shows it). Selected guides resampled get a count of their own: the group's count changing later leaves them as they are, until you resample them to the group's count again, or right-click the group > Reset Segments (every guide of the group back to its count, frozen ones kept). Give guides more segments before combing tight curls.
  • Which guides drive the strands: by default Interpolate uses each group's deepest level. Where a group has children, the strands are interpolated from the children, and the primaries shape the strands through them; a group without children drives the strands itself (Interpolate).

Tube guides

Every guide has a tube: the volume around it that its children are generated in and that Interpolate's Fill Tubes fills with strands. Shaping tubes gives anime and cartoon hair, Pixar style locks and spikes: each lock is shaped as a whole and its strands stay inside it to the tip, with no mesh to model.

A tube is one shape carried along the guide, changed along the way by its sections:

  • Shape: round, ribbon (a rounded rectangle), teardrop (round against the scalp, pointed away from it) or blade (pointed at both edges), or a custom shape from the groom's shape library (below). One per tube. Picking a shape for a guide lays its tube flat on the head: at twist 0 its width runs along the scalp, across the way the guide lies, and its height off it.
  • Width: half the section's width, in scene units (a round tube's radius).
  • Aspect: the section's height over its width. 1 draws the shape as designed; toward 0 it flattens into a ribbon.
  • Twist: the angle the section is turned to at that point, in radians (not accumulated: 0 at the root and 3.14 at the tip turns it half a turn along the guide).

Width, aspect and twist are each a list of values spaced evenly from root to tip, blended between (one value applies along the whole guide). The tube turns with the guide: its sections follow the guide's frames, so bending a guide carries its tube and everything inside it.

Sections follow the head. A shaped tube's sections also turn to lie as the scalp does, all along the guide: where the guide runs over the head (within a couple of section widths of the scalp), twist 0 keeps the section's width along the scalp and its height off it, however the guide curves round the head, so a ribbon combed over the head stays flat on it instead of drifting on its side. Farther from the scalp the sections carry on as they left it (a lock hanging off the head keeps its way), blending smoothly in between; twist turns the section from there. A plain round tube is left as it is (its children and strands as before).

Custom shapes (the shape library). Each groom has a library of custom tube shapes, saved with its guides (in the scene and in .groom files). A custom shape is an outline drawn by control points in the section's square, -1 to 1 across and up with the guide through the middle: a smooth curve through them (Smooth, the default) or straight edges with sharp corners. Guides take a library shape by name just as they take a built-in one, and everything follows its outline exactly as with a built-in: children are made inside it, Fill Tubes fills it, clumps stay in it, the wires draw it. Editing a shape changes every guide using it at once (one undo step). An outline must not cross itself and must surround its center (where the guide runs): edits that break either are refused with a message saying what to fix. Saved points are fitted into the square, so a shape drawn small comes back filling it. A guide whose library shape is missing (a hand-edited file) loads round, with a warning.

Children follow the tube. Children are generated inside the shape's outline, not a disc, and keep their place in its sections: flatten a tube and its children flatten with it, twist it and they twist, taper it and they gather. A child's own tube is its parent's, narrower (Tube scale), lying the same way. Children of a shaped tube whose guide leaves the head at a slant root on its footprint (the root section laid flat on the scalp, as its strands do), spread over the section's area rather than squeezed onto a line across it; guides within 30 degrees of standing straight up keep their children's roots as before, and plain round tubes keep theirs.

Setting up. Fill Tubes on the Interpolate node is all it takes (the Tube locks (anime) preset, under Hair in the Presets menu, has it on, with soft clumps that follow the tubes): place guides, then shape their tubes with the Tube brush. A Clump after it follows the tubes by itself.

Fill Tubes. Turn on Interpolate's fillTubes and every strand rooted inside a guide's tube's footprint (the root section laid flat on the scalp round the guide's root, so it covers the section's whole area however steeply or shallowly the guide leaves the head) takes its place in the tube's cross-section and keeps it from root to tip: the hair fills the tube exactly, flattening, twisting and tapering with it, and is as long as the guide. Within a few widths of the root each strand rises from its footprint into the tube. Strands rooted in no tube are interpolated from the guides as usual, so tubes can cover the whole scalp or only some locks. The tubes of every guide level fill, whatever level the Guides node hands Interpolate: where tubes of several levels hold a root (a child's tube inside its parent's), the deepest one takes the strand, so the child's tube fills its own footprint and the parent's tube the rest of its. A Guides node's exclude leaves its groups' tubes out too. Where tubes of one level overlap, a strand takes the tube it lies most centrally in. Strands in a tube carry tubeId (which tube), tubeU and tubeV (their place in its section, -1 to 1).

Tube Blend (Interpolate's tubeBlend, 25% by default) is the tubes' soft edge, as a share of each tube's half-width at its root. A strand rooted just outside a tube, within that distance of its outline (measured on the footprint, equally thick all round however flat the tube), leans from its usual shape toward riding the tube: all the way at the outline, none at the band's edge, smoothly between. So there is no seam between the hair filling a tube and the hair around it, nor round a child's tube inside its parent's. Strands past the band are exactly as without Fill Tubes. 0 gives a hard edge.

Clumps in tube space. A Clump after it (with followTubes, on by default: nothing to set) picks each tube's clumps among the tube's strands and clumps a strand only toward its own tube's centers, so clumps stay inside the tube and flatten, twist and taper with it.

New guides take the chosen shape. A guide you place or draw (symmetry's mirror guide too) gets the shape chosen in the Tube block of the Place and Draw cards (a built-in or a library shape; round until you pick one), and, with Match nearby on, its width, flatness and twist blended from the two nearest guides' (the nearer counting more), so a new lock starts as thick and as flat as the locks round it. With no guides around (or Match nearby off), it takes the block's Width, Flatness and Twist. In Python: brush_tool("place", tube={"shape": "leaf", "width": 0.1}) (and brush_stroke(..., tube=...)); placement_tube() reads it back.

Scatter fills tube footprints. A Scatter with guideRadius keeps roots only near the guides; round a guide with a shaped tube that means its footprint (the root section laid on the scalp, plus tubeMargin, a share of the half-width as Tube Blend measures; 0 by default: exactly the footprint) instead of a disc round its root, so a wide blade's or a ribbon's footprint fills evenly at the scatter's density, upright or lying low. Guides without a shaped tube keep the disc of guideRadius.

Shaping tubes in Maya. Pick the Tube brush (Groom Tools > Tools > Tube). While it is on, the tubes of every guide it can shape (shown and not frozen) draw as wires: the outline of each section at every guide point, where the brush paints, and lines along the tube through the shape's corners (a blade's points and crests, a ribbon's corners, a teardrop's point), so the shape reads. The selected guides' tubes draw brighter.

  • Width, Flatness, Twist (in Maya at the top of the Brush block). Drag over guides to paint their tubes near the brush, each section by the brush's falloff (and the Root to tip curve) at its guide point. Width grows the tubes (a negative strength shrinks them), Flatness flattens them toward a ribbon (negative: rounds them back), Twist turns them about the guide (negative: the other way). The first stroke on a tube gives it one section per guide point, so you shape it point by point. Symmetry, frozen and soloed guides work as with every brush; each stroke is one undo step.

  • Shaded (off by default) draws the tubes as shaded surfaces, open at the tip, easier to judge a tube's root, mid and tip profiles; Wireframe (on by default) draws them as see-through wires, over the surfaces when both are on. In Maya they sit under Visibility (groomLabBrushCtx -tubeShaded true -tubeWireframe false); in Blender and the app at the top of the Profile block.

  • Always visible (Maya, the end of Visibility, off by default) keeps the tubes drawn as set there with every other tool too (Comb, Select, ...), not only the Tube tool (groomLabBrushCtx -tubesAlwaysVisible true).

  • Selecting tubes with Ctrl+Shift solos them: the other tubes stay drawn, dimmed (their wires and shaded surfaces dark), and so do their guides, so the selected ones, orange, stand out.

  • The Tube tool's card has no Applies to block: its Mirror is at the bottom of Brush.

  • Colors (Maya, on by default) colors each tube in its root tube's color (see Root tubes below), or, a tube of no root tube, in a color of its own. With Shaded on the color goes on the shaded surfaces and the wires stay gray; with it off, on the wires. The selected tubes' wires stay orange. (groomLabBrushCtx -tubeColors false turns it off.) While the Tube tool's tubes are drawn, the guides of root tubes are drawn in their root's color too, not their group's (a split tube's and every child guide's: the color of the level 1 tube it comes from).

  • Ctrl does the opposite: it shrinks, rounds or untwists the tubes.

  • Shift+drag smooths what the brush paints: the channel picked (width, flatness or twist) of the sections under the brush, each evened out toward its neighbours along the guide. The guides' shape stays as it is. (With the other guide brushes Shift+drag smooths the guides.)

  • The tool cards' tube blocks. Each guide keeps its own tube. The Shape and Select cards have Profile and Selected guides, which edit only their targets: the selected guides (select them with Select), or with none selected the soloed ones (left unfrozen while the rest are frozen). They follow every change of the selection or solo.

    • Profile: three pickers, Root, Mid and Tip, each with its own Apply. Pick a shape (the built-ins, then the library's; Mixed while the targets' differ there) and every target takes it; Apply gives the row's shape to all of them again. The tube's outline changes smoothly from the root's shape to the mid's (halfway along) and on to the tip's, the outlines matched along their edges so each profile is exactly its own shape at its place. The Root, Mid and Tip buttons pick which profile the shape editor shows. Under each row, Length (in percent) sets how much of the tube is exactly that profile's shape (the root's from the root, the mid's around the middle, the tip's up to the tip); between the held stretches the shape changes smoothly, and where two of them meet it changes at once. Mid set to Between changes straight from the root's shape to the tip's; Tip set to As root comes back to the root's shape. The strands filling the tube, its children and its clumps all follow the changing outline. Under the pickers, the shape editor shows the profile picked last. With no guides selected or soloed, the block lists the profiles the groom's guides use (and how many guides use each): pick one to edit it in the shape editor, and every guide using it follows, as the root, mid or tip profile. The app and Blender have the same rows (Blender's shape editor shows the root's profile; the library list picks another shape to edit).
    • Selected guides: the targets' Width (the tubes scaled so the first one's widest section is that wide; their taper and painted detail kept), Flatness and Twist (the same from root to tip). Smooth in the block's header evens out the targets' tubes along their guides: the Current channel (the one the brush paints) or All channels (its arrow's menu).
    • Tube (the Place and Draw cards): the shape new guides get, with a small preview, and its Width, Flatness and Twist (used where no guides are near to blend from). Profiles are edited with the Tube brush.

    Each change is one undo step. Fill Tubes and Tube Blend are the Interpolate node's settings (fillTubes, tubeBlend), in the Graph Editor.

  • The shape editor (in the Profile block): a square showing the chosen shape's outline, the guide at the cross, its height (off the scalp) up. A built-in shows read-only: Duplicate (in the block's header) copies it into the library as a new shape (the targets take it). A library shape's points drag (the groom shows the change live while you drag; letting go saves it, one undo step, every guide using it following); click the outline between two points to add one; right-click a point to remove it (three stay at least). Mirror (on by default) keeps the left and right sides alike: a point and its mirror image move, come and go together, points on the middle line stay on it. Smooth switches between a smooth curve and straight edges. The block's header has the library's glyphs: New (a circle to start from), Rename (type the name in place, Enter), Duplicate and Delete (click twice; its guides become round). None of these opens a dialog.

Seeing tubes. Turn on Display Tubes in the groom's Attribute Editor (displayTubes; in the app, Tubes in the Display panel) to draw every guide's tube with its shape and sections.

From Python (Maya), one undo step per call:

import groomlab
# A flat ribbon that turns a quarter turn and tapers, on two guides.
groomlab.set_tube(groom, guides=ids, shape="ribbon", width=[0.4, 0.1], aspect=0.2, twist=[0.0, 1.57])
groomlab.set_tube(groom, group="primary", samples=8)  # 8 sections along each tube, to shape finely
groomlab.get_tube(groom, ids[0])  # {"shape": "ribbon", "width": [...], "aspect": [...], "twist": [...]}
groomlab.scale_tube(groom, 1.5, guides=ids)  # every width times 1.5, the taper kept
groomlab.smooth_tube(groom, guides=ids, channel="flatness", passes=3)  # or "width", "twist", "all" (None)
groomlab.set_fill_tubes(groom, on=True, blend=0.25)  # Fill Tubes and Tube Blend on every Interpolate
groomlab.fill_tubes(groom)  # {"fillTubes": True, "tubeBlend": 0.25}, or None without an Interpolate
groomlab.brush_stroke(groom, "shape", points, radius=0.3, tube_channel="flatness")  # a scripted stroke
# The shape library: custom outlines, (u, v) control points in the -1..1 square, in order round it.
groomlab.add_tube_shape(groom, "leaf", [(0, 1), (-0.6, 0.2), (0, -1), (0.6, 0.2)], smooth=True)
groomlab.set_tube(groom, guides=ids, shape="leaf")  # guides take it by name
# Root, mid and tip profiles: the outline blends root to mid to tip ("" unsets the mid or tip).
groomlab.set_tube(groom, guides=ids, shape="round", mid_shape="leaf", tip_shape="blade")
groomlab.set_tube(groom, guides=ids, root_hold=0.2, mid_hold=0.1, tip_hold=0.3, mid_at=0.6)  # where each holds
groomlab.set_tube_shape_points(groom, "leaf", points)  # every guide using it follows (smooth= too)
groomlab.tube_shapes(groom)  # the built-ins and the library: name, builtin, points, smooth, users
groomlab.rename_tube_shape(groom, "leaf", "petal")
groomlab.remove_tube_shape(groom, "petal")  # its guides become round; returns how many
groomlab.preview_tube_shape(groom, "leaf", points)  # shown live, nothing stored (end_guide_preview)
groomlab.tube_targets(groom)  # what Profile and Selected guides edit: the selected guides, else the soloed ones

set_tube takes guides, group or level (default: the selected guides) and any of width, aspect, twist, shape, mid_shape, tip_shape and samples; what you leave out stays. The command underneath is groomLabGuides -setTube <json> (its keys: shape, midShape, tipShape, width, aspect, twist, samples, scaleWidth, and smooth (width, aspect, twist or all) with passes) and -tube <id>; the library is -tubeShapes (a query, JSON), -editTubeShape <json> ({"op": "add" | "set" | "rename" | "remove", "name", "points", "smooth", "to"}, one undo step) and -previewTubeShape <json> (live, no undo step), and -tubeTargets gives the panel's targets. The brush takes -placeTube <json> (Place and Draw) and tube_channel (width, flatness, twist; -tubeChannel on groomLabBrushCtx and groomLabBrushStroke). Fill Tubes and tube-space clumps run on the CPU; the GPU preview hands those nodes to it. The shape editor is in Maya and the app; Blender has the same blocks and lists the library, without the outline editor yet.

Tubes drawn root first (Maya)

The Tube tool's Tube roots section draws a tube the way Tonic does: its root first.

  • Draw root: click the root's outline on the scalp, one CV at a time (drag to move the CV just placed; Undo CV takes one back). Near another root tube a CV snaps onto its CVs or edges (Snap to neighbours), so the tubes meet with no gap. Clicking the first CV again closes the outline.

  • With Draw guide before extrude (on by default) the root's middle then shows as a CV: drag from it out to draw the tube's guide, as the Draw tool draws one. The stroke is smoothed over a quarter of the root's size, so the hand's shakes go while bends, curls and spirals about as wide as the tube stay. The guide's points are spaced evenly, as many as its length and turns need (about one per root width, and no span turning more than 15°), times Point density: a short stroke gets few. A stroke leaving the root nearly flat along the scalp starts at most 50° off the scalp's normal and bends into it. Where the stroke dips into the head (it is drawn on the view's plane), the guide is popped out there, a third of the root's size over the scalp (from nothing at the root to all of it two root sizes out), the lift spread smoothly along it, so it rises gently over the scalp while its bends, curls and course elsewhere stay as drawn. On release the tube is made and the next root can be drawn. Off, the tube goes straight off the scalp, Length long. Undoing the tube just made (Ctrl+Z) brings its outline back, ready to draw its path again.

  • The tube's root section is exactly the drawn outline (straight edges between the CVs; a library shape of its own, rootTube_<n>, removed when the last guide taking it is deleted), narrowing to Tip width of it at the tip. The tube is swept from its root along the path with no twist: its sections don't roll to lie along the scalp as other shaped tubes' do. Its root footprint (where Scatter and Fill Tubes put the tube's hair) is the outline drawn, fixed on the scalp: laid along the scalp itself, not the guide, so combing or leaning the guide never turns or moves it. It is made 1.5% larger so sealed neighbours overlap a little rather than leave a crack; a strand in the overlap goes to the root it was drawn inside, one in a crack or just past an edge to the nearest root, and one its root's split tubes leave out to the nearest of them.

  • Each root tube keeps its own hair with no region map: Fill Tubes gives every strand rooted in a root's area to that root's tubes, and Clump's followTubes keeps it in that root's clumps. (A region map you paint yourself still works as usual, for the strands outside every tube.)

  • A root's CVs are kept on the scalp itself, apart from its guide: combing, brushing, retwisting or resizing the tube never moves them, nor the area its hair roots in. Only Edit roots changes them.

  • Every root shows on the scalp in its own color, the same as its tubes and guides are drawn (Draw root shows the other roots' CVs too, dimmed, the points a new CV snaps onto, and edges the root being drawn green; entering it with a deeper level of the tube hierarchy picked shows and picks level 1, where a new root tube's guide belongs), half see-through, with its CVs as large dots drawn over its edges. The roots sit in the scene like the scalp: the hair and the guides in front of them hide them. A root being edited or selected has thicker green edges; its CVs stay the same.

  • Edit roots shows the root tubes' outlines, filled, and their CVs (the selected guides' tubes, or every root tube with none selected), the guides hidden. Drag CVs on the scalp:

    • A CV shared with a neighbour moves with it.
    • With Snap to neighbours a CV snaps onto another root's CVs and edges, never onto its own root's.
    • Ctrl+click an edge to add a CV there, on every outline sharing that edge.
    • Ctrl+click a CV to take it out of the root edged green only; a neighbour sealed to it keeps its own. A root keeps at least 3 CVs.
    • Undo CV takes back the last CV move. Maya's Ctrl+Z undoes the scene, not a CV move; a root it changes shows as the scene now has it.

    The roots whose CVs you last touched are edged green. Finish edit moves each changed tube to its new root, refits its section (its taper and what brushes painted kept) and updates the regions, in one undo step. A root that can't take its new outline keeps its old one and the status line says why; the edit finishes either way. Leaving the tool any other way (another tool, Draw root, Select root) finishes the edit too, so no edit is lost.

  • Select root shows every root's middle. Click one to select its root (edged green), Shift+click to add roots or take one out, and drag a selected one to move them all over the scalp as one; with Snap to neighbours their CVs sealed onto a root not selected stay put while the others slide. Their tubes and hierarchies move with them on release, in one undo step. Duplicate makes the selected roots follow the cursor over the scalp; a click sets copies down there, with copies of their tubes and the tube hierarchies under them. Delete removes the selected roots, their tubes and hierarchies.

  • Clicking Draw root or Select root again leaves that mode; Finish edit applies the edits and leaves (Ctrl+Z takes them back in one step).

from groomlab import root_tubes
guide = root_tubes.make_root_tube(groom, outline_points, path=None, length=2.0, taper=0.5)
root_tubes.edit_root_tube(groom, guide, moved_points)
root_tubes.update_regions(groom)

Tube hierarchy

The Tube tool's Tube hierarchy block subdivides tubes, level by level. Add splits each selected tube (or, with none selected, every tube of the base group) into two tubes side by side across its longer side, sharing its root shape, in the next level's group (<base>_L2, <base>_L3, ... up to level 9); pressing it again splits those in two (2 to 4, and on). The numbered buttons show one level at a time (the other levels' groups hidden) and pick its group, so the Tube tool and the brushes edit that level's tubes. Every level's tubes follow their parent: shaping a level 1 tube carries all the smaller tubes inside it, while each smaller tube keeps its own edits. Remove undoes a split: with tubes selected, only theirs (a split tube loses its deepest split tubes; a split tube goes back into its parent with its siblings), with none the deepest level everywhere. Add likewise splits only the selected tubes when some are. A slid guide stays its own tube's clump center wherever its root moves within its root. Every tube split from a root tube, and every guide under it, belongs to that root, so the smaller tubes' hair stays inside the root they came from. Fill Tubes fills a strand rooted in a level 1 tube only with that tube's own smaller tubes, never a neighbour's (a split tube's corners may reach past its level 1 tube's outline).

root_tubes.add_tube_level(groom)                   # every leaf tube split in two
root_tubes.show_tube_level(groom, "rootTubes", 2)  # level 2 shown and returned
groomlab.generate_children(groom, "tubes", count=2, split=True)  # the split itself (-split true)

The Tube tool's card is long, so each of its sections (Brush, Paints, Profile, Selected guides, Tube roots, Tube hierarchy, Applies to) folds away: click its chevron or its title. Which sections are folded is remembered when you switch tools and the next time Maya starts.

Guide groups

Guides belong to named guide groups. A group is either a top-level group of primary guides (primary by default, braids...) or a child group whose guides are children of the guides in its parent group. Groups are listed in Groom Tools > Tools > Guide groups, under the tool card (always open): one row per group with its color dot, its name (indented under its parent), its guide count and an eye. The section header shows how many there are, Isolate (the eye) and + (a new group). Under the list, the picked group's box has rename, select and delete, its Segments, and Edit Guides with the children count.

ActionHow
Create a group+ in the section header (New Group): a name and a parent (None for a top-level group, or a parent group for a child group).
Make it the active groupClick its row in the list. Brushes only edit the active group's guides, and Place and Draw add guides to it. In Maya, clicking the picked group again goes back to All groups, which brushes every guide. Page Up / Page Down step one level up or down.
RenameDouble-click the name, or rename. Guides node params that name the group are updated.
Show / hideThe row's eye. The guides' eye at the top of the Groom Tools hides or shows every group of the groom at once (The current groom).
ColorThe row's dot shows the color the group draws in: filled when it has a color of its own, a ring for its automatic one. Right-click the row > Color... to pick a color, Default Color to clear it. Every group without its own color, child groups too, gets a hue of its own, well apart from its parent's and its siblings'. To see a painted guide layer instead, set Guide Color (Display > Guides) to Painted Layer. The automatic colors start from a hue of the groom's own, from its name (the Maya transform, the Blender object, the app's file name), so two grooms side by side differ; the same name gives the same colors in Maya, Blender and the app.
Select its guidesselect, or right-click > Select Guides.
Deletedelete: the group, its child groups and their guides. The dialog lists graph nodes that use the group.
MirrorEdit Guides > Mirror Group... copies a top-level group to the other side.

Isolate, the eye in the Guide groups header, draws the active group and its child groups at full color and dims every other group.

Hidden groups are not drawn, not affected by brushes and not picked by the Select tool. Hiding does not change the groom: the guides still drive their strands. Hiding applies to the named group only, not to its child groups.

In the graph, groups are referenced by name: a Guides node's group and exclude params choose which groups feed Interpolate, and a Group node with by guideGroup makes a strand mask from the strands nearest a group's guides (Restricting a node). Groups, and the guides in them, are saved with the scene and in .groom files; hidden state and group colors are stored on the Maya node (hiddenGuideGroups, guideGroupColors) and not in the .groom file.

groomlab.list_guide_groups(groom)                      # [{name, parent, depth, count}, ...]
groomlab.add_guide_group(groom, "bangs", parent=None)
groomlab.rename_guide_group(groom, "bangs", "fringe")
groomlab.show_guide_group(groom, "primary", visible=False)
groomlab.set_guide_group_color(groom, "fringe", (1.0, 0.5, 0.2))
groomlab.select_guides(groom, group="fringe")
groomlab.guide_ids(groom, "fringe")                    # the group's guide IDs

A guide's group is set when it is created (the active group for Place and Draw, the child group for Edit Guides > Children). There is no command to move existing guides to another group.

Freeze and solo

Freezing protects guides from brushes. The freeze state is a per-guide value from 0 to 1, the freeze mask; brushes scale their effect on each guide by 1 minus its freeze value, so a partial value gives a partial effect. Child guides inherit their parent's freeze value. Frozen guides are drawn blue. Freezing does not affect the strands.

  • Freeze (a brush in the Guides category) paints the freeze mask; Ctrl unfreezes. Unfreeze All, next to it, clears the mask on every guide.
  • Select solos: the selected guides stay live, all others are frozen, and a click on nothing unfreezes all.
  • Solo new guides (Place and Draw settings, off by default): each guide you place stays live and all others are frozen, so you can shape it immediately.
  • With Symmetry on, the mirrored guides are soloed too. Each of these is one undo step.
  • Freeze exact guides: the freeze mask is a guide map named freeze. Select guides, then in the Paint tab pick freeze, set Value to 1 and click Fill, which fills the selected guides only. From Python: groomlab.freeze_guides(groom, guides) (the selected guides by default; value=0 unfreezes) and groomlab.unfreeze_all(groom).

To freeze a whole group, select its guides (select in the group list) and fill freeze, or in Python groomlab.freeze_guides(groom, groomlab.guide_ids(groom, "fringe")).

Detailing at higher density

A typical way to work from coarse to fine:

  1. Groom the primary guides with the primary group active, until the overall shape is right.
  2. Generate children (Edit Guides > Children), then make the child group active. Brushes now only affect the children, and the primaries stay as they are.
  3. Hide the primary group if its curves get in the way, or turn on Isolate to dim it.
  4. Solo areas while detailing: with the Select tool, drag over the guides to work on, and everything else is frozen. A click on empty space releases them.
  5. Editing a primary later still carries its children, with their detail, along with it.

For more density than hand-placed children, interpolate dense guides procedurally with a ToGuides node and edit them with a Sculpt node, whose edits survive upstream changes (Other main nodes).

Brushes

Select the groom and pick a brush. The radius is in screen pixels, strokes act in screen space, and each drag is one undo step. The brushes are the same, in the same order, in Maya, the app and Blender.

CategoryBrushEffect
CreatePlaceClick for one guide, drag to place several (at least Spacing apart). New guides take the shape of the nearby guides (Match nearby guides).
DrawPress on the scalp and draw the guide's shape.
PartDraw a part line; interpolation does not blend guides across it.
FlowDraw direction arrows and whorls for short hair without guides (see below).
ShapeCombThe main shaping brush: drags guides along the stroke with roots pinned. With Stretch on, combing also lengthens or shortens them.
SlideMoves roots along the scalp; the guides keep their shape.
SmoothRemoves kinks (Straighten: relaxes guides toward a straight line instead).
Lift, SwingRaise guides off the scalp; turn them around their root.
AttractPulls tips together (negative strength pushes them apart).
TubePaints guides' tubes near the brush: Width, Flatness or Twist (a negative strength: the opposite); its card's Profile and Selected guides set the selected guides' tube shape, width, flatness and twist.
TrimCut, Length, EraseCut guides where the brush touches; lengthen or shorten them uniformly; delete guides, part lines or flow arrows (not the scattered hair: see below).
Length KeysScale guide lengths from keys you place on the scalp, blended smoothly between them (see Length Keys).
Paint (in the Paint tab)PaintPaints the map picked in the Paint tab, including the maps that drive settings such as density and width (see below, and Painting maps).
GuidesSelect, FreezeSelect guides; paint the freeze mask. Unfreeze All is next to them.

Painting a setting (density, width, length, clumping...). In the Paint tab, click + New Map and set For to the setting: Density, Width, Length, Clump strength, Curl, Noise amplitude, Flyaways, or Other setting... for any other mappable parameter. GroomLab creates a white map (so nothing changes yet), connects it to the setting, selects it and starts the Paint brush on it, all in one undo step. If the setting already reads a map, that map is selected instead. A stroke paints toward the Value (1 is the setting's full value); Ctrl paints toward 0: thinner hair on the width map, no hair on the density map. For example, to thin the sideburns, create the map for Density and Ctrl+paint over them.

Erasing hair. The Erase brush removes guides (with their children), part lines and flow arrows, so it does nothing on a groom whose hair comes from the Scatter alone. To take hair away, paint the density map holding Ctrl (Paint tab > + New Map > For: Density); paint it back without Ctrl.

Length Keys

Length Keys (Trim) scales guide lengths from keys you place on the scalp: longer on the legs, shorter at the paws, a fringe that runs from short to long. Each key holds a scale (x1.5: half as long again). Between keys the scale blends smoothly over the whole scalp, measured along the skin, so a key on one side of an ear does not reach through to the other. There is no reach to set: each key's influence ends where its neighbours' begins, and away from all of them the scale eases back to x1, so guides far from your keys stay as they are.

  • Click on the scalp to place a key. A new key takes the scale already there, so placing one changes nothing. The first key is x1: a hold. Put x1 keys round an area to fence it in.
  • Drag a key to move it over the scalp. Ctrl+click deletes it.
  • Right-drag a key up or down to scale it (Maya: middle-drag, since Maya's right button opens its marking menus). Dragging up doubles it every 150 pixels.
  • The guides preview at their new lengths until you Apply (one undo step; Enter in the app and Blender) or Cancel (Esc).

Each key is labelled with its scale and the length it gives the guide nearest it. The Keys box shows the selected key's Key scale and Key length (type a length and the scale is set to match), Scale or Trim (a guide scaled about its root, so curls keep their shape, or cut and extended at the tip, so curls keep their size), Delete Key and Clear. Only the selected guides change, else the soloed ones (the ones not frozen). With symmetry on, the mirrored keys act too and show on the other side; topology symmetry puts each key at its partner spot on the scalp.

The keys are saved with the groom. Apply bakes their scales into the guides and sets the keys back to x1, so you can come back, drag a key and apply again without scaling twice.

Keys

  • Ctrl does the brush's opposite: Length shortens, Lift lays guides down, Twist turns the other way, Attract pushes apart, Shape shrinks, Cut grows. Painting, it paints toward 0 (Ctrl+Paint on the density map removes hair, Ctrl+Freeze unfreezes). Comb, Slide, Smooth and Erase have no opposite.
  • Shift+drag smooths with any brush: with Comb, Length or another guide brush it smooths the guides (as the Smooth brush, at the brush's radius and strength); painting maps or the freeze mask, it smooths the paint; with the Tube brush, the tube channel it paints.
  • Ctrl+Shift+drag with a Shape or Trim brush (Comb, Slide, Smooth, Lift, Swing, Attract, Tube, Cut, Length, Erase) paints guides into the selection: the guides the brush passes over are added, and when you let go every other guide is frozen, so the next strokes work on those alone. Drag over no guide to clear the selection and unfreeze everything; a click on nothing changes nothing. Press the two keys in either order. The Select tool still has its lasso, box and click (see Freeze and solo).
  • Alt+Shift+X turns symmetry on or off, after GroomLab > Install GroomLab Hotkeys.
  • B + drag sets the radius, M + drag the strength, after GroomLab > Install GroomLab Hotkeys (or middle-drag and Shift+middle-drag).
  • Page Up and Page Down step the active group up or down a level.
  • Y + click opens a marking menu, after GroomLab > Install GroomLab Hotkeys.
  • Tablet pen pressure scales the strength.

GroomLab > Help > Keyboard Shortcuts lists every key (the same table as the app and Blender) and marks the ones that need the GroomLab hotkey set. Install GroomLab Hotkeys shows which keys it changed and the hotkey set it switched from.

The Groom Tools panel
The Groom Tools: the tool tiles, the picked tool's card, then the tab's list.

The current groom and what shows

One groom is current: the Groom Tools, the Graph Editor and every brush work on it.

  • Pick it in the list at the top of the Groom Tools or in the Graph Editor's groom list: both move together. Selecting a groom in the viewport or the Outliner makes it current too. A picked groom stays current while you select a scalp, curves or anything else.
  • Pin the Graph Editor (the pin beside its groom list) to keep it on its groom while the Groom Tools move on to another one; its list then changes only the graph. Unpin it and it shows the current groom again. The pin lasts for the session.
  • The eyes beside the list: the first shows or hides the hair (the strands, and whatever the groom grows on them: instances, scales, cards, strand meshes; the groom's Display Hair), the second the guides (every guide group at once, with their tubes, dots, selection, parts and flow arrows; the groom's Display Guides). Each leaves the other as it is: hide the hair to see the guides alone, the guides to judge the hair. Both are viewport switches: renders and exports always have the hair. Shift+click an eye, or right-click it for Show All / Hide All, to do it for every groom in the scene.
  • GroomLab > Display has Show All Hair, Hide All Hair, Show All Guides and Hide All Guides. With the GroomLab hotkey set, Alt+Shift+G turns every groom's guides off, and on again. (To hide a whole groom, hide its node as any other: Ctrl+H.)
groomlab.set_current_groom(groom)        # what a pick in either list does
groomlab.active_groom()                  # the current groom
groomlab.set_guides_visible(groom, False)
groomlab.set_all_guides_visible(True)    # every groom's (GroomLab > Display)
groomlab.set_hair_visible(groom, False)  # the strands alone (displayHair)
groomlab.set_all_hair_visible(True)

In the app and in Blender

App: one groom per window, so the list is its name; the hair's eye and the guides' eye work the same (the hair goes and comes back at once, without evaluating), and View > Guides On/Off (Alt+Shift+G) and GroomLab > Display show or hide the guides.

Blender: the groom at the top of the Groom Tools is the Graph Editor's too, and making a groom's scalp the active object makes it current. The eyes are the same (Shift+click or right-click: every groom): the hair's eye hides the hair object in the viewport (its render visibility stays), the guides' eye the guides; the node editor's pin keeps a Graph Editor on its groom.

Brush settings

The Groom Tools scroll as one panel. At the top are the groom header, the tabs and the tool grid: labeled tiles of one size, as many to a row as the panel's width holds (at most four; on the Paint tab, one full-width Paint button over the maps). Right under the grid is the tab's list: Guide groups on the Tools tab, the maps on Paint, the layers on Correctives, the photos on Photos. The picked tool's card sits under the list: only its settings (hover a tile for the tool's whole hint and the gestures), in blocks, always in this order and each only when the tool uses it:

  1. Brush: how the stroke feels.
  2. The tool's own block, named after what it sets: Paint (Mode, Value and Fill, the stamp), New guides and Tube (Place, Draw), Visibility, Profile and Selected guides (Shape; tube guides), Selection (Select), Erases (Erase), Keys (Length Keys), Flow and Parts.
  3. Applies to: where the stroke lands.

With no tool picked, the card says how to start.

SettingBlockEffect
Radius, StrengthBrushBrush radius (pixels) and the amount applied per dab. Strength (±): a negative strength reverses the brushes that work in both directions.
FalloffBrushHow the effect fades toward the brush edge: 0 hard, 1 soft from the center out.
SmoothBrushPainting: how much Shift+drag smooths per stamp (past 1: several passes).
PressureBrushA tablet's pen pressure scales the strength.
Keep off scalpBrushGuides never go below the scalp; points pushed under it slide along it.
StretchBrush (Comb)Combing lengthens or shortens guides as you pull, instead of keeping their length.
Falloff curveBrushThe falloff as a curve, center (left) to edge (right), shown under the chips while it is on. Right-click it for presets.
Root to tipBrushHow much of the strength each part of a guide receives, root (left) to tip (right); for example, style the ends and leave the roots.
Guides / Parts / FlowApplies toWhat a shaping brush moves: guides, part lines, flow arrows.
MirrorApplies toSymmetry: mirrors every stroke across world X, or with Topology across the scalp's own left and right (for a head that is rotated, animated or not quite symmetric). Alt+Shift+X toggles it (in Maya, with the GroomLab hotkey set).

A stroke never reaches what is on the far side of the head from the camera (guides, parts, flow arrows or paint), and brushes work on every unfrozen guide of the picked group; to brush only some guides, Ctrl+Shift+drag them into the selection (the rest freeze) or freeze the others. How the strands draw while you sculpt is the groom's setting: Attribute Editor > Sculpting (the app: Properties > Sculpting; Blender: While sculpting under the Groom Tools).

Selection

Select selects guides with a lasso or a click: Shift toggles, Ctrl deselects, Ctrl+Shift adds. Its settings include a Soft radius for soft selection. Edit Guides has Mirror Selection and Clear Selection.

Symmetry

  • Symmetric grooming: turn on Symmetry (Mirror in the tool card's Applies to block, or Alt+Shift+X) and every stroke is mirrored. While it is on, a red line on the scalp shows the mirror plane (with Topology, the scalp's middle loop) for as long as a brush is on, the cursor anywhere.
  • Mirroring one side: groom one side, then use Edit Guides > Mirror Group... or Sync +X → -X. Sync also copies children, hand edits, locks and painted attributes.

Parting

Pick Part and draw along the parting on the scalp. Interpolation no longer blends guides across the line, and a Part node opens the gap (its width sets how far). If the parting is already combed into the guides, set the Part node's partsFrom to auto instead; it detects the parts where the hair splits, with no drawing needed.

Short hair without guides

For vellus hair, brows and short fur, the Flow brush grooms a direction field: drag arrows on the scalp (drag over arrows to comb them, Ctrl to erase), or click to place whorls and other singular points that hair turns around. A Flow node lays the strands along the field. See Fur & feathers.

The arrows and sinks are kept on the groom itself, not in the Flow node, so they stay when you delete or replace the node. The Flow tool's card counts them ("34 arrows · 2 sinks"). To remove them all, click Clear All there, or use GroomLab > Utilities > Delete All Flow Arrows (one undo step). To remove some, use Erase with Flow ticked, or Ctrl+drag with the Flow brush.

Scaling a groom

A groom scales with its scalp, like an object parented to it. Scale the head up 2x and the hair is the same hair 2x as big: lengths, widths, clump sizes and the guides' shapes double, the density drops to a quarter so the strand count stays the same, and curl frequency halves. The stored values do not change; the Graph Editor shows the values at the size the groom was groomed at.

  • The readout. Attribute Editor > Inputs > Groom Scale shows how much the groom is scaled now: 1.00x at the size it was groomed at. In the standalone app it is in the Display panel.
  • Scale Source (Attribute Editor > Inputs; Display panel in the app; groomlab.set_scale_source(groom, "area" | "transform" | "off")) says what the scale follows:
    • Surface Area (the default): the scalp's surface area at the scene's start frame. Scaling the scalp's transform and Freeze Transformations give the same result (the groom does not jump when you freeze), and a scalp replaced by a higher or lower resolution version of the same surface stays at 1x. Editing or remodelling the mesh to another size scales the groom too; when that happens GroomLab says so once, in the Script Editor and in the view (the app: its status message): "GroomLab: the scalp's area changed 12%: the groom scaled x1.06. Set Scale Reference to keep its sizes."
    • Transform Only: the scale of the scalp's transform (and its rig's root joint) at the start frame, nothing else. Remodelling the mesh leaves the groom as it is. But Freeze Transformations resets the transform's scale to 1, so the groom goes back to 1x with it.
    • In short: Surface Area survives Freeze Transformations; Transform Only survives remodelling. In the standalone app (no transforms) Transform Only keeps the scale the groom opened with.
    • Off: sizes stay in scene units whatever the scalp's size, and a bigger scalp grows more strands at the same density.
  • Animation after the start frame (a squash, blend shapes) does not change the scale. Nor does posing a rig at the start frame, when the groom has a rest mesh (a skinned scalp gets one): the scale is measured without the pose's stretch, so raising an arm keeps it, while scaling the rig scales the groom.
  • Rigs. Scaling a rig at its root scales the skinned scalp, and the groom with it. Surface Area measures the skinned mesh, not its original shape; Transform Only reads the root joint's scale.
  • Set Scale Reference. Makes the scalp's size now the groom's 1x (the button next to the readout, or groomlab.set_scale_reference(groom)), for both sources. Use it when you scaled or remodelled the scalp on purpose and want the groom to keep its sizes in scene units at the new size.
  • Transfers keep the size shown by default; Fit groom to the new scalp's size in the Transfer window treats the new scalp as the old one resized, so the groom scales with it (see Transfer to a new scalp).
  • Presets and new nodes are fitted to the size the groom is at 1x, so they match the values already in the graph.
  • Simulation. Gravity and collision distances scale too, so a scaled groom moves like the unscaled one scaled. Changing the scale drops the simulated frames; a bake made at another scale no longer matches and is simulated again.
  • Groom files keep the source and the reference sizes (scaleSource, scaleReference, scaleTransformReference), so exports, renders and the standalone app scale the groom the same way.

On this page