Edit Guides Operator

Overview

Edit Guides is the main hub for editing and managing the guides and hair strands in an Ornatrix hair object. You can interactively plant new guides, delete guides, change their shape in various ways, brush them, and perform other operations which are done by hand instead of parametrically. You can work directly with guide roots, guide vertices or manipulate them using one of several brush contexts available.

This operator is broken down into three main sections (or levels) of guide editing. Using these three methods together should allow you to produce any arbitrary hair volume shape, which can then be fine-tuned using hair state modifiers.

Edit Guides also provide tools for guide management like Strand Groups and Stand Channels which allow to apply and filter and apply different effects based on group patterns and paint masking, as well as shading effects in supported render engines.

Ornatrix Maya V3 grooming workflow

Getting started

Select your hair shape and show the hair stack. Use Ornatrix Menu to find the Edit Guides operator button. Click this button to add the Edit Guides operator at the current position of the hair operator stack.

General parameters

These parameters are present in all editing modes or if no editing mode is selected. In other words, they are always displayed in the Attribute Editor.

The parameters in each Ornatrix operator are separated into different categories, Edit Guides operator is separated as Edit Guides, Interpolation Options, Guide Options, Guide Operations, Roots, Guides, Strand Groups, Soft Selection and Channels.

Edit Guides

Edit Modes
Here you will find the two Edit Mode buttons. These two buttons will set the operator into its Strand or Control Point mode, while activating one of the brush contexts will activate the Brushing mode. In each editing mode you will have different ways to interact with and modify the strands.

The editing modes will also allow you to select guides or hair strands by clicking and dragging on the viewport as with any other object. The amount of selected guides will be shown at the bottom of this section. Find more details about the different editing modes in the Roots and Guides sections.
Note If you have one or more hair strands selected press F button at any time to focus the view on their roots.
Apply Amount Parameters
Those parameter will blend the changes made by the current Edit Guides operator using a slider, a ramp curve, a texture multiplier map or a strand channel. It can be used to dial the changes down and can be animated to achieve blending effects between different poses of a hairstyle or isolate the changes to a particular Strand Channel. Multiple Edit Guides operators can be stacked on top of each other for strand change layering. |=. Using the Apply Amount parameters |
Skip Hair Update While Dragging
When on, only guide edits will be displayed while mouse is down and hair will be updated only when mouse is released. Use this option to speed up guide editing for very dense hair.

Interpolation Options

This sections contains options related to strand interpolation when using a brush context.

Change Tracking

Surface
Changes made to strands are recorded and stored relative to the base surface. Adding or changing input strands will interpolate the existing changes based on surface position thus preserving and applying changes to new strands.
Strand
Changes made to strands are recorded and stored relative to strand ids. Each strand has a unique id and it will be used to keep track of the changes to that strand. The same strand will always be affected by a change, but modifying the input strands may not result in comparable output result because of changes to input strand ids.

Interpolation

When Surface change tracking option is used this determines how changes stored in this operator are assigned to the hair strands.

Closest Neighbor
Closest change on the surface is found for each input hair strand and used to modify this strand's properties. This method is fastest but can result in some sharp changes.
Triangulation
Up to three closest changes on the surface are found for each input hair strand and interpolated to produce the modifications for the strand. This is similar how Hair from Guides operator interpolates hairs from guides. This option is slower but produces smooth results, especially for strand shape edits.

Input Root Interpolation

Re-target Changes
Normally, if the amount of guides is changed by inserting, deleting them or changing the guide interpolation the changes made in Edit Guides will be destroyed. You can mitigate that by using the Re-target function after you made those changes. Ornatrix will try to blend the new guides with the rest, preserving any existing Strand Groups in the process.
Note: This option is only useful if the Multi-Resolution feature is not being used.

Using Re-Target Changes

Note 2: The parameters in this section do not affect the hair interpolation settings set in Hair from Guides.

Guide Options

This section contains several options related to guide visualization and interaction.

Created Strand Length
Determines the length of newly created strands.

Ignore Backfacing Strands
When on, any guides which are facing away from viewport camera will not be selectable or affected by the brushes.

Show Color Guides
When on, a different color is assigned to each guide based on the strand groups previously created.

Show Vertex Ticks
When ON, points making up the guides will be displayed.

Hide Guides

Guides Width
This parameter is used to change the width of the guides for better visualization.

Guide Operations

This section includes functions for guide management.

Hide
This button will hide the selected guides.

Unhide All
Use this button to reveal the hidden guides.

Freeze
This function is very useful when dealing with a lot of guides and you want to isolate which guides are affected by the brush tools without selecting or hiding them every time.

Unfreeze All
Used to Unfreeze all guides after you are done editing.

Delete Selected Strands
Deletes the selected guides or hair strands.
Note: Ornatrix has a custom way of handling element deletion in shapes. The keyboard Delete button should not be used to delete guides or strands, this action will remove the selected operator. Therefore, you need to use this button instead.

Push Away From Mesh
Used to prevent guide intersection with surface. Use this feature to set a certain distance between each guide vertex and the distribution mesh.
Push Away Distance parameter determines the distance. While the Push Away from Mesh button only runs this operation once, Auto Push Away From Surface will run the operation after each brush stroke, setting the distance to the value previously specified.
- Note: This feature will use the actual distribution surface as collision mesh, it does not allow you to use a different mesh for collision. This means that if the hair is distributed on just a hair scalp extracted from the main character mesh you may get some unexpected result caused by an incomplete surface. If you want to use a custom mesh for collision use the Push Away From Surface operator instead.

Adopt From Stack Top
Captures the current guide shape from the top of the stack into this modifier. Guides will be edited to look like current modifier stack result.

Using Adopt from Stack Top

Roots

The Root section of Edit Guides is designed to work directly with hair roots. There are some fundamental concepts that usually apply to roots such as roots are always located relative to either a surface or object. In most uses, you will deal with roots that are located relative to faces.

The Root level have options to plant, remove, rotate and import splines curves as Ornatrix guides. You can select and deselect roots inside the viewport like you would vertices, faces, or edges on a mesh using standard selection tools. Once selected, you can use the transform tools to move the guides along the surface of the current distribution mesh. This may be needed to tweak the exact position of guides after they were automatically generated by Ornatrix.

Plant Guide Tool
Adds additional guides to your hair object. After activating the tool, click on top of the distribution mesh surface to plant new roots at these locations. This tool works as any other Maya native tool, so you can drop the tool pressing the Enter or Q key.
- Plant Guide Tool options:
  Adopt Shape
  When this option is on, newly planted guides will use the same shape as the selected guide to the location where mouse was clicked.
  The closest strands will only be looked up from current strand selection. For example, if only one strand is selected then its shape will always be copied for the newly planted strands. If you want to always have the closest strand shape used then select all strands before planting new strands. Newly created strands are not selected by default.
  Guide Length
  When Adopt shape option is off newly planted guides will be straight. This option controls the length of newly planted guides.
  Point Count
  Determines the point count for the newly planted guides.
- Additional Information
  Any strand data such as strand channels and strand groups will be inherited from the source strand into the planted strand when Adopt Shape option is used.
  The unique strand id for the planted strands will be generated based on the surface dependency information (mesh face index and barycentric coordinate).
  The options for this tool are available in Maya's tool settings dialog.
  
  Using the Plant Guide tool

Rotate Strands
When using Mesh from Strands to convert the hairs to polygon mesh, this tool allows you to manually rotate a strand or a group of strands.

Import Multiple Curves
Opens up a list with all the curve objects in the scene, then you can select and import groups of curves to use as guides in the current hair object. The import dialog have some options to customize the import process.
- Import Multiple Curves options:
  Distance Threshold
  If imported curves are further than this value from existing guides they will be added as new guides. Otherwise, existing guides will be updated will their shape.
  Custom Point Count
  When ON, imported curves will have a specific number of points, otherwise they will have the same number of points as the rest of the existing guides.

Modify Roots

Guides

This section deals with everything related to the direct manipulation of strand shapes when working in Edit Control Points mode. The term "direct manipulation" in this case means editing of strand vertices much like you would edit vertices of a mesh. Of course doing that alone would be a nightmare; that is why a set of tools is introduced to organize these strand vertices and manipulate them in a very intuitive manner.

A special IK solver system is used to simplify the task of moving strands. The reason for an IK system is to preserve strand length while editing. Human hair has a very high strength ratio and thus virtually doesn't stretch along its direction. Note that even if you do want hair to stretch (for example if you're doing a length variant hairstyle and would like to form both shape and length at the same time), you can turn off strand length preservation and deal with stretching as well as moving.

To manipulate strands special helpers are used - Control points. Control points can be thought of as vertices located somewhere on hair. Like other vertices in a mesh they can be moved, rotated, and scaled individually or as a group in all transform spaces (world/object/screen etc.). You have the full control over the position of control points along the strand and the influence that they have on each strand.

[Insert gif or video]

Control Point Position
Determines the position of the control point or manipulation handle along the strand. Use this slider to position the control point where you want to make the strand deformation.

Control Point Influence
Determines the range of influence of the control point or manipulation handle. Imagine this value as a soft selection range, but instead it works in a per strand point basis.

Preserve Strand Lengths
When on, strands will not be stretched or compressed during brushing.

Ik Iterations
Determines how many times IK solver will iterate before converging on a solution. Generally the higher this value is the slower IK solver will act.

Preserve Strand Geometry
When on, a special algorithm is used for comb, grab, and smooth brushes which affects the whole strand alone its length by calculating the best fit to current stroke while minimizing changes to the strand shapes.

Resample Strands
When on the points on strands will be re-positioned to be equidistant after each brush stroke. This can be useful to retain strands smoothness.

Elastic Mode

Strand Groups

This sections contains tools for creation and management of strand groups.

A strand group is an integer value assigned to each guide or hair strand. Strands belonging to a specific group can be edited separately by various Ornatrix modifiers. Various Ornatrix modifiers provide an option to specify the group index which it will apply to. You can use multiple modifiers to separately style hairs belonging to different groups. See Working with Strand Groups for additional details.

Use Strand Groups
Activate this option to allow the use and creation of strand groups in the selected Edit Guides operator.
Display Strand Groups
Every strand group will have a unique color assigned to it. By default these colors will only affect the guides, not the hair. When this option it's on, the strand group colors will be displayed directly on the hair strands.
Strand Group
Enter the strand group index that you want to assign to the selected guides.
Assign
Assign the strand group index or indices entered in the Strand Group box to the selected guides.
Assign Unique
Assign the next available strand group index to the selected guides. For example, if index 1 has already been used, this command will assign index #2 to the selected guides.
Select by order:
This section includes commands to select the previous index and next index based on the currently selected group.
Select by Group
When on, if you select a single strand that belongs to a strand group, the whole group will be selected.

Strand Channels

This sections contains the tool for creation and management of strand channels.

Strand Channels are additional data added to guides or hair strands in the form of black to white values. Strand channels can be used to control other parameters on all Ornatrix operators, like hair frizz, hair width etc. See Working with Strand Channels for additional details.

Here you will find tools to create or modify strand channels. Channels inside an Edit Guides operator are created non-destructively. This means that any channels already existing before the modifier is applied will not be affected if this modifier is later removed. However, existing channels can be removed by this modifier down the modifier pipeline.

Current Channel Value
Use this slider to choose a value between 0 and 1 or black to white. This is the value that will be assigned to the selected guides when you click the Assign Value button.

Permanent Channel Display
By default the black and white values assigned or painted on the guides in strand channels will be only visible on the guides, and only when an Edit Guides operator is selected in the hair stack. When this option it's on, the strand channel values will be displayed directly on the hair strands and regardless of the selection.

Display Channel Overlay
When Permanent Channel Display it's on, this menu allows you to choose how the channel values will be displayed.
- Single-channel display(greyscale)
  Allows you to display channels that are composed of a single channel.
- Multi-channel display(color)
  Allows you to display channels that are composed of three channels to form other colors: R, G, B.

Strand Channels box
This box contains the list of created channels by category: Per-Strand Channels and Per-Vertex Channels. You can create new channels using the Add button and newly created channels will appear inside this box. Select the Per-Strand channel category and then click Add to create a Per-Strand channel. If you want to create a Per-Vertex channel select the Per-Vertex channel category instead. There are also buttons to Delete, Rename and Select all the channels.

Assign Value
Assign the float value chosen in the Current Channel Value slider to the selected guides.

Select by Value
Allow you to select strands by its strand channel color values suing the Threshold slider to determine the range of values that you want to select.

Threshold
Allows you to select a range of values to be selected when using the Select by Value button.

Ensuring consistent results

Edit Guides operator works by referencing individual guides in your hair structure by their internal index. As such, it is important that once you perform edits with Edit Guides the count and order of input guides below in the operator stack remains the same.

The following could change guide count and order and cause your guide edits to become invalid:

Changing number of guides in Guides from Mesh operator
Changing distribution parameters such as method, map, and multiplier in Guides from Mesh operator

It is therefore a good practice to use the "remember root positions" option prior to making changes in the Edit Guides operator,

Scripting

MEL access

Use these functions to work with an instance of an Edit Guides shape:

// Prompts a dialog to add a new guide channel to specified guides shape
global proc OxAddRootChannel( string $attributeName );

// Deletes currently selected guides channel from specified guides shape
global proc OxDeleteRootChannel( string $attributeName );

// Prompts a dialog to rename selected guide channel in specified guides shape
global proc OxRenameRootChannel( string $attrName );

// Sets value for selected guide channel and currently selected guides
global proc OxSetSelectedRootChannelValues( string $attrName, float $value );

// Prompts a dialog to set values of selected guide channel in specified guides shape
global proc OxSetRootChannelValues( string $attrName );

// Deselects all guide channels
global proc OxDeselectRootChannel( string $nodeName );

OxEditGuides command

OxEditGuides MEL command can be used to perform various operations on a selected instance of EditGuidesShape in the scene. The command accepts one or more flags, which determine how the command edits the selected shape. The detailed syntax of the command is as follows:

OxEditGuides [-flag(s)]

Command flags

-help
Prints a message containing the information found below
-init (-initialize) [int guideCount] [int perStrandChannelCount]
Initializes the change "delta" with specified guide and strand channel count. This is optional.
-eg (-edit) [int shapeChangeCount] For each change: [int strandId] [int pointCount] For each point: [Vector3 point]
Records a change to one or more guide shapes in form of an array of points
-eg2 (-edit2) [int shapeChangeCount] For each change: [int strandId] [int meshSurfaceFaceIndex] [Vector3 meshSurfaceBarycentricCoordinate] [int pointCount] For each point: [Vector3 point]
Records a change to one or more guide shapes in form of an array of points, at specified mesh surface coordinates. This separate function is needed to account for orientation of the strand during editing. This ensures subsequent edits will respect the same surface orientation.
-crc (-createRootChannels) [int count] For each: [string channelName]
Creates one or more per-strand channels with specified names
-drc (-deleteRootChannels) [int channelCount] For each: [int onFlag]
Deletes all per-strand channels which have the on flag set
-rcd (-changeRootChannelData) [int channelCount] [int strandCount] For each channel: For each strand: [float value]
Modifies per-strand channel data for all strands
-rcn (-renameRootChannels) [int channelCount] For each: [int channelIndex] [string newChannelName]
Renames specified per-strand channels to specified new names
-cvc (-createVertexChannels) [int count] For each: [string channelName]
Creates one or more per-vertex channels with specified names
-rvc (-renameVertexChannels) [int channelCount] For each: [int channelIndex] [string newChannelName]
Renames specified per-vertex channels to specified new names
-dvc (-deleteVertexChannels) [int channelCount] For each: [int onFlag]
Deletes all per-vertex channels which have the on flag set
-cg (-createGuides) [int count] For each: [int meshFaceIndex] [int firstVertexIndex] [int pointCount] [Vector3 meshBarycentricCoordinate]
Adds one or more new guides to specified surface position, using specified vertices. New vertices can be added prior to this command or existing vertices can be reused.
-cv (-createVertices) [int count] For each: [Vector3 position]
Appends specified vertices to the strands vertex array. These can be used in conjunction with -createGuides flag to add new strands.
-rm (-modifyRoots) [int count] For each: [int guideId] [bool isFaceIndexChanged] ([int faceIndex]) [bool isBarycentricCoordinateChanged] ([Vector3 barycentricCoordinate])
Changes the surface coordinate for one or more strand roots. Whether face index or barycentric coordinates has been changed needs to be specified. If they are not changed then their new values don't need to be specified.
Examples:
OxEditGuides -rm 1 0 1 0.3 0.3 0.3
OxEditGuides -rm 1 1 25 0
-ds (-deleteStrands) [int strandCount] For each: [int onFlag]
Deletes strands based on whether their on flag is set
Examples:
OxEditGuides -ds 10 0 0 0 0 1 1 0 0 1 0
-dg (-deleteStrands2) [int count] For each: [int strandId]
Deletes strands by their strand id
Example (delete strands 15 and 16):
OxEditGuides -ds 2 15 16
-vcd (-changeVertexChannelData) [int changeCount] For each change: [int strandId] [int changedChannelCount] For each channel: [int channelIndex] [int pointCount] For each point: [float value]
Modifies per-vertex channel data for one or more strands and channels
Examples:
OxEditGuides -vcd 1 15 1 0 2 0.5 0.6
-s (-selectStrands) [int count] For each: [int strandId]
Selects one or more strands by their id
Example (select strands 15 and 16):
OxEditGuides -s 2 15 16
-h (-hideStrands) [int count] For each: [int strandId]
Hides one or more strands by their id
Example (hide strands 15 and 16):
OxEditGuides -h 2 15 16
-f (-freezeStrands) [int count] For each: [int strandId]
Freezes one or more strands by their id
Example (freeze strands 15 and 16):
OxEditGuides -f 2 15 16
-sd (-changeStrandData) [int count] For each: [int strandId] [int channelCount] For each channel: [int channelIndex] [float value]
Sets per-strand channel data for specified strands and channels
Example (sets a value of 0.5 for 0th channel of strand 15):
OxEditGuides -sd 1 15 1 0 0.5
-sg (-changeStrandGroups) [int count] For each: [int strandId] [int strandGroup]
Sets strand groups to specified strands
Example (assigns group 5 to strand 15):
OxEditGuides -sg 1 15 5
-sr (-strandRotation) [int count] For each: [int strandId] [float rotationValue]
Sets strand rotations (twists around their stem) for specified strands
Example (assigns rotation of 0.2 to strand 15):
OxEditGuides -sr 1 15 0.2
-cid (-chunkId) [int chunkId]
For internal usage. Executes an internally defined command "chunk", for example during brushing operations. Chunks are used to reduce command size and thus speed up user interactions.
-q
Use in conjunction with chunkId flag to query the "full" version of the command for a specific chunk.
-cc
Commits accumulated editing changes. This may be required after multiple previous calls to finalize any changes.
-v (-version) [int value]
Specifies the current version of the command syntax. Should be absent if not sure (latest version will be assumed). Only some older flags require this flag for backward compatibility.

Calling OxEditGuides command from Pymel

There are multiple ways to call OxEditGuides command from Pymel:

Using a string containing the MEL command invocation:

import pymel.core as pm
pm.mel.eval( "OxEditGuides -vcd 1 1 1 0 2 0.2 0.1;" )

Using Pymel direct command invocation. Note that command arguments need to go first, and the command flag(s) need to go last:
```
pm.mel.OxEditGuides( 1, 1, 1, 0, 2, 0.2, 0.1, vcd = True )
```

Alternatively you can also list the flags as string arguments:

pm.mel.OxEditGuides( "vcd", 1, 1, 1, 0, 2, 0.2, 0.1 )

Writing custom brushes with Python

Aside from stock set of brushes Ornatrix allows you to easily create your own custom brushes through Python scripts. This is described at detail in the Writing Plugin Brushes section.

Troubleshooting

Roots and/or control points cannot be moved

Problem: When in Strand or Control Point editing mode selecting one or more strands and using transform tool has no effect.
Cause: Maya's soft selection mode it's on, which is incompatible with strand selection.
Solution: Use Ctrl/Command + B key shortcut to toggle off the soft selection mode.

Guides are corrupt and jumbled

Problem: After making edits and other operations within the scene Edit Guides messes up all of the guides.
Cause: The order and/or count of input guides has changed. Edits made to the guides are being applied to incorrect guides.
Solution: Make sure that you restore the same input guides parameters as they were when you made guide edits. See Ensuring consistent results section for more details.