Difference between revisions of "Humanoid Rig Requirements for IK"
m (Fix github issue link) |
|||
(38 intermediate revisions by 5 users not shown) | |||
Line 4: | Line 4: | ||
When you import a rigged model to try and turn it into an avatar. It can be confusing to know what's required and what's not for best results. This page exists to help you understand the requirements. | When you import a rigged model to try and turn it into an avatar. It can be confusing to know what's required and what's not for best results. This page exists to help you understand the requirements. | ||
− | + | = Support Formats = <!--T:9--> | |
If you have a rigged model, that's compatible with other VR Platforms such as VRChat etc, then it should work out of the box. Just try importing the avatar. | If you have a rigged model, that's compatible with other VR Platforms such as VRChat etc, then it should work out of the box. Just try importing the avatar. | ||
<!--T:10--> | <!--T:10--> | ||
− | As a reminder, we '''don't''' currently support the importing of <code>.unitypackage</code> files. | + | As a reminder, we '''don't''' currently support the importing of <code>.unitypackage</code> / <code>.vrm</code> / <code>.asset</code> / <code>.mesh</code> / <code>.prefab</code> files. |
<!--T:11--> | <!--T:11--> | ||
Line 15: | Line 15: | ||
* GLTF | * GLTF | ||
− | + | = Overall Rig/Model Requirements = <!--T:12--> | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | == Bone Requirements | + | == General Guidance == <!--T:49--> |
+ | * Your model should be in an A-pose or T-Pose. | ||
+ | * The Orientation (forward facing direction) of your model should be along the positive Z axis. | ||
+ | ** A flipped Z axis can be detected but might contain bugs. | ||
+ | ** As a quick validation for this: | ||
+ | *** Check the "Force T-pose" option in the advanced import settings. If hands are crossed, rotate 180 degrees along the Z (up-down) axis. If one hand is in front and the other hand is in back, rotate 90 degrees along the Z (up-down) axis. | ||
+ | |||
+ | == Ignoring Bones == <!--T:47--> | ||
+ | Sometimes, you might want to ignore a bone in the IK process within Neos. Luckily you can do this. Simple add <code><NoIK></code>('''case insensitive''') to the Bone's name '''anywhere within the bone's name'''. This bone will then not be considered for IK purposes. It's children will though. This is often useful for twist bones or clothing/hair bones that are being detected as skeletal/IK bones. | ||
+ | |||
+ | <!--T:48--> | ||
+ | {| class="wikitable" | ||
+ | !Bone Name | ||
+ | !Used in IK? | ||
+ | !Notes | ||
+ | |- | ||
+ | | Right Hand | ||
+ | | ✅ | ||
+ | | Flagged as a Right Hand | ||
+ | |- | ||
+ | | <No'''_'''IK> Right Hand | ||
+ | | ✅ | ||
+ | | Flagged as a Right Hand | ||
+ | |- | ||
+ | | <NoIK> Right Hand | ||
+ | | ❌ | ||
+ | | '''Ignored by IK''' | ||
+ | |- | ||
+ | | Right Hand <NoIK> | ||
+ | | ❌ | ||
+ | | '''Ignored by IK''' | ||
+ | |- | ||
+ | | Right Hand <noik> | ||
+ | | ❌ | ||
+ | | '''Ignored by IK''' | ||
+ | |- | ||
+ | | Right Hand <NOIK> | ||
+ | | ❌ | ||
+ | | '''Ignored by IK''' | ||
+ | |- | ||
+ | | bo<nOiK>ne | ||
+ | | ❌ | ||
+ | | '''Ignored by IK''' | ||
+ | |- | ||
+ | | One day I went to the park, the park had <noik> | ||
+ | | ❌ | ||
+ | | '''Ignored by IK''' | ||
+ | |} | ||
+ | |||
+ | = Bone Requirements = <!--T:13--> | ||
When you import a model, Neos uses pattern matching and heuristics to figure out the layout of your Model's Bones. This means that bone names are largely case insensitive and can have additional data around the name. As an example "hips", "Hips", "HIPS" and "cheese_hips" should all be detected as the model's hip bone. The heuristics are also forgiving of spaces so "upper arm" and "upperarm" should also be flagged correctly as an "Upper Arm" bone. | When you import a model, Neos uses pattern matching and heuristics to figure out the layout of your Model's Bones. This means that bone names are largely case insensitive and can have additional data around the name. As an example "hips", "Hips", "HIPS" and "cheese_hips" should all be detected as the model's hip bone. The heuristics are also forgiving of spaces so "upper arm" and "upperarm" should also be flagged correctly as an "Upper Arm" bone. | ||
Line 34: | Line 78: | ||
If this is too much detail you can also skip to a [[#Overall Summary|summary]] or [[#Example Rig|download a sample rig]] | If this is too much detail you can also skip to a [[#Overall Summary|summary]] or [[#Example Rig|download a sample rig]] | ||
− | + | == Central Spine/Hips == <!--T:17--> | |
<!--T:18--> | <!--T:18--> | ||
− | The root of the model's armature | + | The root of the model's armature should be a single hips bone, that faces upwards, see the table below for valid names for it. |
<!--T:19--> | <!--T:19--> | ||
Line 51: | Line 95: | ||
!Part | !Part | ||
!Alternative Names | !Alternative Names | ||
+ | !Invalid Names ('''Do Not Use''')❌ | ||
|- | |- | ||
|1st | |1st | ||
|Hips | |Hips | ||
|hips, pelvis, root | |hips, pelvis, root | ||
+ | |style="background-color:#FAC9C9;"| hip | ||
|- | |- | ||
|2nd | |2nd | ||
|Spine | |Spine | ||
|spine, chest | |spine, chest | ||
+ | |style="background-color:#FAC9C9;"| | ||
|- | |- | ||
|3rd | |3rd | ||
|Chest | |Chest | ||
− | |chest, upper chest, ribcage | + | |chest, upper chest, ribcage, spine1, spine2 |
+ | |style="background-color:#FAC9C9;"| | ||
|- | |- | ||
|4th | |4th | ||
|Neck | |Neck | ||
|neck | |neck | ||
+ | |style="background-color:#FAC9C9;"| | ||
|- | |- | ||
|5th | |5th | ||
|Head | |Head | ||
|head | |head | ||
+ | |style="background-color:#FAC9C9;"| | ||
|} | |} | ||
− | === Shoulders and Arms | + | === Upper Chests === <!--T:53--> |
+ | Many Avatars have an extra bone segments in the central spine, that's usually called "Upper Chest" or "Spine2". | ||
+ | # Hips | ||
+ | # '''Spine''' | ||
+ | # '''Chest''' (Sometimes called Spine1) | ||
+ | # '''Upper Chest''' (Sometimes called Spine2) | ||
+ | # Neck | ||
+ | # Head | ||
+ | |||
+ | <!--T:54--> | ||
+ | These are '''NOT required, but we still support these.''' In these cases the "middle" "Spine" bone will be ignored for the purposes of IK. | ||
+ | |||
+ | == Shoulders and Arms == <!--T:22--> | ||
Two arms should be attached to the "Chest" bone from above, one for each side of the model. Use the letters "L" and "R" to indicate which side of the model the arm is on. These are also case insentive so "l" and "r" are ok. | Two arms should be attached to the "Chest" bone from above, one for each side of the model. Use the letters "L" and "R" to indicate which side of the model the arm is on. These are also case insentive so "l" and "r" are ok. | ||
Line 105: | Line 167: | ||
|} | |} | ||
− | + | == Hands == <!--T:26--> | |
<!--T:27--> | <!--T:27--> | ||
Line 111: | Line 173: | ||
<!--T:28--> | <!--T:28--> | ||
− | Hands can appear quite complex but they don't need to be. Before we move onto bone names keep in mind the following: | + | Hands can appear quite complex but they don't need to be. '''Before we move onto bone names''' keep in mind the following: |
* Fingers | * Fingers | ||
− | ** Each finger must have at least two segments. | + | ** Each finger '''must have''' at least two segments. |
− | ** | + | ** But we support up to 4 segments per finger: |
+ | *** Metacarpal | ||
+ | *** Proximal | ||
+ | *** Intermediate | ||
+ | *** Distal | ||
** We need '''at least 3 Fingers''' to identify a hand | ** We need '''at least 3 Fingers''' to identify a hand | ||
* Thumbs | * Thumbs | ||
Line 120: | Line 186: | ||
<!--T:29--> | <!--T:29--> | ||
− | Additionally | + | Additionally, if your model has 5 fingers, we'll use geometric detection to figure out what your bones are called. This process looks at the rig and can figure out which finger is which. |
<!--T:30--> | <!--T:30--> | ||
Line 172: | Line 238: | ||
|} | |} | ||
− | + | === Finger Identification === <!--T:45--> | |
Neos uses the following code to try and find what your fingers are: | Neos uses the following code to try and find what your fingers are: | ||
− | <pre | + | <pre> |
public static FingerType? NameToFingerType(List<string> names) | public static FingerType? NameToFingerType(List<string> names) | ||
{ | { | ||
Line 188: | Line 254: | ||
return FingerType.Pinky; | return FingerType.Pinky; | ||
− | return null; | + | <!--T:46--> |
+ | return null; | ||
} | } | ||
− | + | </pre> | |
As you can see its quite flexible and forgiving. | As you can see its quite flexible and forgiving. | ||
− | + | == Legs == <!--T:35--> | |
Legs are simple compared to everything else. Each leg should be connected to the Hip bone. Use the letters "L" and "R" to indicate which side of the model the arm is on. These are also case insensitive so "l" and "r" are ok. | Legs are simple compared to everything else. Each leg should be connected to the Hip bone. Use the letters "L" and "R" to indicate which side of the model the arm is on. These are also case insensitive so "l" and "r" are ok. | ||
Line 222: | Line 289: | ||
|} | |} | ||
− | === Heads | + | === Digitigrade Legs === <!--T:55--> |
− | Heads are simple, but some data is available to help you in a few areas: | + | Neos '''does not''' support Digitigrade legs natively. Many community members have created systems to support them. An example of this can be found in [https://youtu.be/DXx_YsMEyFI| Shrike's Video] |
− | + | ||
− | + | == Heads == <!--T:38--> | |
− | + | Heads are simple, but some data is available to help you in a few areas. | |
− | + | ||
+ | === Eyes === <!--T:51--> | ||
+ | Neos sets up avatars with automatic eye movements and if you have a compatible headset [[Eye Tracking]] is supported. For this to work you'll need eye bones named like so: | ||
+ | {| class="wikitable" | ||
+ | !Part | ||
+ | !Compatible Names('''Case Insensitive''') | ||
+ | |- | ||
+ | |Left Eye | ||
+ | |LeftEye, Left Eye, Eye.L,Eye_L | ||
+ | |- | ||
+ | |Right Eye | ||
+ | |RightEye, Right Eye, Eye.R,Eye_R | ||
+ | |} | ||
+ | |||
+ | === Jaws === <!--T:52--> | ||
+ | Jaw bone based animations are possible in Neos, but are less common due to [[Visemes|Blendshape/Viseme support]], If you'd still like to use a Jaw bone name it "Jaw"('''Case Insensitive'''). | ||
− | <!--T:39--> | + | === [[Visemes]] === <!--T:39--> |
− | Visemes are covered elsewhere as they aren't associated with the rig of a model. | + | [[Visemes]] are covered elsewhere as they aren't associated with the rig or bones of a model. |
<!--T:40--> | <!--T:40--> | ||
[[File:HumanoidRigHead.png|thumb|200px|Example head rig layout]] | [[File:HumanoidRigHead.png|thumb|200px|Example head rig layout]] | ||
− | + | = Overall Summary = <!--T:41--> | |
Here are some photos of a summary of the example rig. See above for more detailed notes: | Here are some photos of a summary of the example rig. See above for more detailed notes: | ||
Line 242: | Line 324: | ||
[[File:HumanoidRigOverallHierarchy.png|250px|Example overall rig hierarchy shown in blender]] | [[File:HumanoidRigOverallHierarchy.png|250px|Example overall rig hierarchy shown in blender]] | ||
− | + | = Example Rig = <!--T:43--> | |
− | A sample Blender rig can be found here: [https:// | + | A sample Blender rig can be found here: [https://www.dropbox.com/s/0wwgpplnv2fofbf/Neos_bone_structure_Example_v3.blend?dl=0 Download from Dropbox]. |
− | + | = Supported Tools = <!--T:44--> | |
− | * Mixamo rigs work well. | + | * [https://www.mixamo.com/| Mixamo] generated rigs work well and without any changes. |
+ | * [https://readyplayer.me/| Ready Player Me] avatars work well and without any changes. | ||
+ | ** There is however, some issues with some [https://github.com/Neos-Metaverse/NeosPublic/issues/3849 | Ready Player Me outfits]. | ||
</translate> | </translate> |
Latest revision as of 23:00, 22 April 2023
When you import a rigged model to try and turn it into an avatar. It can be confusing to know what's required and what's not for best results. This page exists to help you understand the requirements.
Support Formats
If you have a rigged model, that's compatible with other VR Platforms such as VRChat etc, then it should work out of the box. Just try importing the avatar.
As a reminder, we don't currently support the importing of .unitypackage
/ .vrm
/ .asset
/ .mesh
/ .prefab
files.
Supported Humanoid Avatar formats:
- FBX
- GLTF
Overall Rig/Model Requirements
General Guidance
- Your model should be in an A-pose or T-Pose.
- The Orientation (forward facing direction) of your model should be along the positive Z axis.
- A flipped Z axis can be detected but might contain bugs.
- As a quick validation for this:
- Check the "Force T-pose" option in the advanced import settings. If hands are crossed, rotate 180 degrees along the Z (up-down) axis. If one hand is in front and the other hand is in back, rotate 90 degrees along the Z (up-down) axis.
Ignoring Bones
Sometimes, you might want to ignore a bone in the IK process within Neos. Luckily you can do this. Simple add <NoIK>
(case insensitive) to the Bone's name anywhere within the bone's name. This bone will then not be considered for IK purposes. It's children will though. This is often useful for twist bones or clothing/hair bones that are being detected as skeletal/IK bones.
Bone Name | Used in IK? | Notes |
---|---|---|
Right Hand | ✅ | Flagged as a Right Hand |
<No_IK> Right Hand | ✅ | Flagged as a Right Hand |
<NoIK> Right Hand | ❌ | Ignored by IK |
Right Hand <NoIK> | ❌ | Ignored by IK |
Right Hand <noik> | ❌ | Ignored by IK |
Right Hand <NOIK> | ❌ | Ignored by IK |
bo<nOiK>ne | ❌ | Ignored by IK |
One day I went to the park, the park had <noik> | ❌ | Ignored by IK |
Bone Requirements
When you import a model, Neos uses pattern matching and heuristics to figure out the layout of your Model's Bones. This means that bone names are largely case insensitive and can have additional data around the name. As an example "hips", "Hips", "HIPS" and "cheese_hips" should all be detected as the model's hip bone. The heuristics are also forgiving of spaces so "upper arm" and "upperarm" should also be flagged correctly as an "Upper Arm" bone.
This is quite good at picking up a variety of rigs but to help you can follow this format.
An extensive guide is presented below, with a key information for each segment of the body.
If this is too much detail you can also skip to a summary or download a sample rig
Central Spine/Hips
The root of the model's armature should be a single hips bone, that faces upwards, see the table below for valid names for it.
Following the hips should be a chain that leads from the hips upwards: Hips -> Spine -> Chest -> Neck -> Head.
So in summary:
Order | Part | Alternative Names | Invalid Names (Do Not Use)❌ |
---|---|---|---|
1st | Hips | hips, pelvis, root | hip |
2nd | Spine | spine, chest | |
3rd | Chest | chest, upper chest, ribcage, spine1, spine2 | |
4th | Neck | neck | |
5th | Head | head |
Upper Chests
Many Avatars have an extra bone segments in the central spine, that's usually called "Upper Chest" or "Spine2".
- Hips
- Spine
- Chest (Sometimes called Spine1)
- Upper Chest (Sometimes called Spine2)
- Neck
- Head
These are NOT required, but we still support these. In these cases the "middle" "Spine" bone will be ignored for the purposes of IK.
Shoulders and Arms
Two arms should be attached to the "Chest" bone from above, one for each side of the model. Use the letters "L" and "R" to indicate which side of the model the arm is on. These are also case insentive so "l" and "r" are ok.
The order should follow: Shoulder -> Upper Arm -> Lower Arm -> Hand. We'll cover fingers in another segment.
Order | Part | Alternative Names |
---|---|---|
1st | Shoulder | shoulder, clavicle, collar, collarbone |
2nd | Upper Arm | upperarm, upper arm, arm, bicep |
3rd | Lower Arm | fore arm, forearm, lower arm, lowerarm, elbow |
4th | Hand | hand, wrist, palm |
Hands
Hands can appear quite complex but they don't need to be. Before we move onto bone names keep in mind the following:
- Fingers
- Each finger must have at least two segments.
- But we support up to 4 segments per finger:
- Metacarpal
- Proximal
- Intermediate
- Distal
- We need at least 3 Fingers to identify a hand
- Thumbs
- We need an identifiable thumb.
Additionally, if your model has 5 fingers, we'll use geometric detection to figure out what your bones are called. This process looks at the rig and can figure out which finger is which.
Even with these things in mind, you may want to setup the fingers manually. So as with other segments here are some comments on the names of the bones.
For each finger: <fingername>1 -> <fingername>2 -> <fingername>3 -> <fingername>4
Where the finger names are:
- Thumb
- Index
- Middle
- Ring
- Pinky
Or explained in a table:
Finger Number | Finger Name | Alternative Names | Example Structure |
---|---|---|---|
1 | Thumb | thumb1.L -> thumb2.L -> thumb3.L -> thumb4.L
| |
2 | Index | point, pointer | index1.L -> index2.L -> index3.L -> index4.L
|
3 | Middle | middle1.L -> middle2.L -> middle3.L -> middle4.L
| |
4 | Ring | ring1.L -> ring2.L -> ring3.L -> ring4.L
| |
5 | Pinky | little | pinky1.L -> pinky2.L -> pinky3.L -> pinky4.L
|
Finger Identification
Neos uses the following code to try and find what your fingers are:
public static FingerType? NameToFingerType(List<string> names) { if (names.Contains("thumb") || names.Contains("th") || names.Contains("thm") || names.Contains("thmb")) return FingerType.Thumb; else if (names.Contains("index") || names.Contains("point") || names.Contains("in") || names.Contains("ind")) return FingerType.Index; else if (names.Contains("middle") || names.Contains("mid") || names.Contains("mi")) return FingerType.Middle; else if (names.Contains("ring") || names.Contains("ri") || names.Contains("rin")) return FingerType.Ring; else if (names.Contains("pinky") || names.Contains("little") || names.Contains("pi") || names.Contains("pin") || names.Contains("pnk")) return FingerType.Pinky; return null; }
As you can see its quite flexible and forgiving.
Legs
Legs are simple compared to everything else. Each leg should be connected to the Hip bone. Use the letters "L" and "R" to indicate which side of the model the arm is on. These are also case insensitive so "l" and "r" are ok.
Order | Part | Alternative Names |
---|---|---|
1st | Upper Leg | upper leg, upleg, thigh, upperleg, hipL, hipR |
2nd | Lower Leg | leg, calf, knee, shin |
3rd | Foot | foot, ankle |
4th | Toes | toe, toes, ball, toebase, toes |
Digitigrade Legs
Neos does not support Digitigrade legs natively. Many community members have created systems to support them. An example of this can be found in Shrike's Video
Heads
Heads are simple, but some data is available to help you in a few areas.
Eyes
Neos sets up avatars with automatic eye movements and if you have a compatible headset Eye Tracking is supported. For this to work you'll need eye bones named like so:
Part | Compatible Names(Case Insensitive) |
---|---|
Left Eye | LeftEye, Left Eye, Eye.L,Eye_L |
Right Eye | RightEye, Right Eye, Eye.R,Eye_R |
Jaws
Jaw bone based animations are possible in Neos, but are less common due to Blendshape/Viseme support, If you'd still like to use a Jaw bone name it "Jaw"(Case Insensitive).
Visemes
Visemes are covered elsewhere as they aren't associated with the rig or bones of a model.
Overall Summary
Here are some photos of a summary of the example rig. See above for more detailed notes:
Example Rig
A sample Blender rig can be found here: Download from Dropbox.
Supported Tools
- Mixamo generated rigs work well and without any changes.
- Ready Player Me avatars work well and without any changes.
- There is however, some issues with some | Ready Player Me outfits.