Working with SL Shapes

About this Document...

Content:

  • Export a Shape from Second Life.
  • Import a Shape to Blender.
  • Export the Mesh to Collada.
  • Import the Mesh to Second Life.

The Video content:

  • Export Shape from Second Life.
  • Import the Shape to Blender.
  • Modify the Mesh.
  • Export the modified Mesh to Second Life.

What does Avastar provide?

Avastar basically supports the creation of animate Models (Avatars&attachments) and the creation of animations. Therefore the tool adds various functions and user interface elements to Blender.

The full functionality of Avastar can be a bit overwhelming on first sight. You should be prepared to spend some time and patience to get it all working nicely for your projects.

What does this Document provide?

You learn how to get a visual exact copy of your Avatar’s Shape into Blender and modify the Shape by using the Appearance Sliders. Finally we move the modified Mesh back to Second Life.

This document only shows you how you transfer your Avatar between Second Life and Blender. What you actually do with your Avatar inside of Blender is only limited by your own creativity.

We expect that you have basic knowledge about Blender.

Export your Shape from SL or OpenSim

The procedure to export the Character shape may vary depending on which viewer you actually use. We use the default SL Viewer.

How to export your Shape from SL

Enable the Develop Menu

Ensure that you have the Develop Menu in your menu bar. If you can not see this entry, you can enable it by pressing CTRL+ALT+Q (on Windows)

Call Appearance to XML

Open the Develop menu and proceed to the Avatar entry
From Avatar proceed to Character tests
And from Character tests proceed to Appearance to XML

By now your current Shape data has been copied to a local file on your computer. You find this file in your application folder. For me (on Windows 7) it is in:

C:\Users\gaia\AppData\Roaming\Second Life\logs\Gaia_Clary_nnn.xml

(where nnn is a number)

Note: the file path contains your Windows user name (mine is gaia) and your SL user name.

Import the Shape to Blender

How to Load your Shape into Blender

Suppose you start a fresh Project with an empty scene. You already have downloaded your personal Shape from Second Life as a local Shape file (in XML Format). All that you want is to create a new Avastar character with exactly this shape.

For this purpose we offer the XML Shape importer within the regular Blender Import menu (Also see the map in the zoom icon in the upper right corner of this page):

File -> Import -> Shape as Avastar

The Importer first opens a file selector where you select the XML shape that you want to import.

When you click the Import button then the tool creates a new Avastar character, and finally applies the imported shape to the new character.

reference-005

Load Shape into existing Avastar

Loading a Shape file into your existing Avastar works almost identical to the previous scenario. The only difference is that now you already have an Avastar character in the scene. You select the Avastar character, and then you call the Shape importer just as described above.

The Shape importer figures that you have selected an Avastar Armature and automatically applies the imported shape to the selected rig instead of creating a new Avastar

Avatar Shape IO Panel

The Shape importer is also accessible directly from the user interface, in the Object properties of the Avastar Armature:

  • Go to object mode.
  • Select the Rig (RMB on the yellow circles around the mesh).
  • Open the Properties window.
  • Navigate to the “Object” properties.

There you find a panel Avatar Shape IO. This panel displays a Preset selector and a subpanel with 4 main functions:

The Avatar Shape IO Options

Load Shape (Import a shape)

This function allows you to upload a Shape that you have previously exported from your online world: In most viewers there is a shape export option hidden in the advanced menu (“Advanced” -> “Character” -> “Carter Tests” -> “Appearance to XML”). This will silently create a file called:

[application_folder]\Roaming\Second Life\logs

This file contains your current shape and can be loaded into Avastar, where [application_folder] is the viewer’s application data folder. For Windows this folder is located at:

C:\Users\<username>\AppData

Save Shape to

By default this function creates a new Shape file with your current shape settings. This file can later be used for Load Shape (see above). Right besides the function you find a selector for the save destination.
As mentioned above the default option is to save to File. But you can also save to a Blender textblock. In that case the slider values can be found in the Blender text editor panel. The values correspond to the shape settings in the SL viewer.

Note: Some viewers support the upload of shape file to SL (e.g. Firestorm, Singularity). To see the file, switch to the Blender Text editor and locate Shape for: Avatar (Avatar stands for the name of the Armature). Useful when you need to update the shape in SL with the values from blender.

Refresh Shape:

This resets the Avastar meshes to the current Shape values. Useful together with the new custom shape key function. Also if you messed up the Avastar meshes (by editing them) you can return the mesh back to the current shape slider values.
Warning: if you added or removed vertices from the Avastar meshes, this function will fail!

Delete Avastar Meshes

Remove all Meshes of the Avastar character. You will want this when you use the rig for non human characters where keeping the Avastar human meshes make no sense.

Load Appearance Sliders

When you load a blend file which contains an Avastar Character, then the Shape panel sometimes only displays the “Load Appearance sliders” Button. This happens when you just have started Blender.

Activating the button loads the appearance setting controls. We added this behavior for optimization purposes as it takes a few seconds to initialize the Avastar shape system.

 

By now the Avastar default Mesh character has been reshaped to precisely match your own mesh character. Note, that your imported character is rigged and weighted already. There is no need for any additional step. However you can still change the Avatar shape by using the shape sliders.
You find the Shape Sliders in the object properties section, right below the Load Shape button. We provide the exact same shape sections in Avastar as you can find in the SL Shape editor. The sliders are supposed to behave exactly in the same way.

Hint: The sliders are a bit slow sometimes. currently there is not much that we can do about that.

How to use the Collada Exporter - Read more...

The Collada exporter exports your Mesh character or mesh attachment to a file with the file ending .dae and possibly it also exports a set of images (image textures). You find the Mesh Exporter in the Blender Export menu.

The Exporter opens with a file selection window where you can set the file to where you want to export.

The Export option Panel

Hint: You usually can keep the default settings and just click on the “Collada(Avastar)(.dae)” button in the lower right corner of the Window (see zoom icon in this chapter title).

A File Selector will pop up. Here you can navigate to your export directory and then export your file as a Collada file (using the file extension “.dae”) There is also a set of export options available on the right side of the window (see image)

Tip: If you intend to use your exported mesh for Animesh then please note that Animesh currently does not support the Shape Sliders in world. Your mesh will always been displayed as when you enable the Neutral Shape preset in the Avastar Shape Editor panel.

The Export option Sub-panels

Textures export (advanced)

You can export images along with your models. In that case Avastar stores the images as files on your disk and adds a reference to the Collada file. The SL Importer knows how to read and import these images for static meshes.
Note: For rigged meshes the images are not recognized by the SL Importer. This is a viewer bug which has never been fixed.
  • Image Format: (default is png) is typically predefined in the Render settings. However we found it convenient to offer an immediate setting in the Exporter. By default the exporter applies the image type only to generated images.
  • Use ‘Image format’ for all images: If you set this option, then Blender will use the selected image format for all exported images. If you disable the option, then only the generated images are affected.
  • Use RGBA: Blender can export the Alpha channel for images. Normally you set this in the render settings where you can specify to use either RGB or RGBA for image exports. If the selected export format supports Alpha then enabling RGBA here will export images with Alpha channel even if the render settings are set to RGB and vice versa.

Hint: You may want to NOT use RGBA because of the Alpha glitch. However this is not a general advice. There are many situations where using Alpha images is even recommended (for example when you want to create an Alpha mask).

Hint: If the format of the exported image(es) does not support an Alpha channel then the “Use RGBA” option is simply ignored.

Advanced options

The Advanced Options are related to special scenarios. You should normally keep all options set as they are. This makes sure that your exports are well suited for SL. However in some situations you will have to get back here and set the options according to the descriptions below.

Warning: You must really know what you do when you set an advanced option. Handle with care!

Use Bind Pose: The Use Bind Pose option is largely documented in the Bind Pose Workflow
You normally set this option in the Avastar Shape Editor. We added it here only for convenience.

Following options are only available when the Use Bind Pose option is enabled:

  • with Reset Animation: Avastar generates a 0-priority single frame animation of the current Restpose. This animation can later be used in SL together with an animation reset script (see below)
  • with Reset Script: Avastar generates an LSL Script ready for usage in SL. In SL you copy this script together with the Reset Animation (see above) into your model’s inventory. You need this especially when you are not exporting in white stickman mode (see Avastar Shape Editor)
  • Animesh Restpose: when your model shall be used as an Animesh, then you need to enable this option here. Otherwise your imported meshes will not look the same as in Blender.

Animesh Restpose: You use this option when you want to export cor Animesh. Note this option only resets the Shape Editor to White Stickman for Export. You may actually want to work in White Stickman Shape all the time, so this option is here just for convenience.

 

Apply Armature Scale: If you have scaled your Armature in Object Mode for making a tiny or a giant you should not apply the scale to the armature because then the entire Avastar Animation system may no longer work. But the Object Scale must be applied when you export the mesh.
Otherwise the target online world does not recognize the scaling and the giant shrinks back (or the tiny grows back) to normal size. The apply Armature Scale option ensures that the Object scale is applied in the exported Armature.
Apply Rotation & Scale: If you have Scaled or rotated your Objects in Object Mode then this Scale&Rotation should be applied to all objects of an export to avoid unexpected scaling and rotation issues within the target system. However this is all so often simply forgotten and sometimes even unknown.
Hence we have added an automatic apply Rotation&Scale to the exporter. This setting does not affect the original objects.

Export SL Rotation: When you export an Avastar Rig then it must be rotated according to the SL Standards (so that the character looks into the positive X direction).

Hint: You want to enable this option when you export to Second Life or similar worlds.

Disabled: Do nothing
Enabled: Rotate the Rig by 90 degrees to make it compatible to the SL specifications

Triangulate: Export the meshes as triangles. Normally you want to do the triangulation on your own if at all. You also can just export without triangulation and let the SL Importer do the job. Or just use this option here.

This is an optional setting. We set it to True because it seems to be the safest option of all possible ones.

Weld Edge Normals: When two separate objects share a boundary line, then you typically see a boundary seam in the object texture. This happens because the vertex normals differ even if the adjacent objects share the same vertex locations.
The exporter recalculates the vertex Normals at the adjacent boundaries of the selected objects.
Weld to all visible: Sometimes you want to only export one part but still want the vertex Normals be fixed.
This option lets the exporter take all visible objects into account when calculating the vertex Normals at object boundaries.

Export Shape: The current Shape from the Shape editor is exported as an avatar shape file (with extention .xml) Some viewers (firestorm) can import this file as new Avatar Shape by some

This option is most important especially for Developerkit makers. If you distribute this shape along with the developerkit file, then Avastar can setup the Developerkit Manager with more precision.

Sanity Checks: Perform tests on the Mesh (tricount, texture face counts, etc…)

Hint: You want to enable this option in most cases.

 

Bone Filters

Define which subset of the Bones in the rig are exported along with the meshes.

Export with Joints: When you have edited the Armature to adjust the Rig to your special character (Alien, creature, pet…) then you normally want to keep your edited Armature when you export your Meshes.

Hint: You want this option disabled only when your rig is so complex that Avastar can not calculate the Neutral Rig for your situation. In that case please set the sliders to SL Neutral (Avastar Shape Editor, white stickman icon) and never touch the sliders again (actually the sliders will be locked when you select the neutral shape)

Disabled: Export the Rig visually as it is. Note: You must make sure that the Avastar Shape Editor is reset to the SL Neutral Shape (White Stickman Icon). Otherwise Avastar rejects the exports.

Enabled: Calculate the neutral skeleton from the current rig settings (temporary set Sliders to Neutral SL Settings) but apply the current Slider settings as bind pose. Pleased refer to the Bind Pose document for further explanations.

Export all Bones: Add all bones of the rig to the exported Model.

You want to enable this option only when you plan to export your model for import into another 3D Modelling tool.

Only Weighted Bones: Avastar can export all deform bones of the Rig. However in most cases it is enough to only export the deform Bones which are actually used (weighted to meshes)

Hint: You want to enable this option in most cases.

Disabled: Export all deform Bones unconditionally
Enabled: Export only those bones which are actually used (have weights for meshes)

Only Deform Bones: Avastar has many control bones (mainly for IK-Animation, targetless Animation and attachment points) Avastar can export all Bones of the rig, or only the Deform bones

Hint: You want to enable this option in most cases.

Disabled: Export all Bones in the Rig unconditionally
Enabled: Export only deform Bones

Allow Weighted Attachments: SL does not allow weighting of attachment points. Hence we suppress the export of weights for attachment points by default.

This option should indeed never be used for SL! Handle with Care. It is very likely that the SL importer rejects meshes with attachment point weighting at some time in the future.

Enforce Parent Hierarchy: Ensures that all parent bones of exported bones are also exported, even if they have no weights defined.

Details: When you enable the above bone filters then it can happen that not all bones of a Bone chain are exported. This becomes a problem when one or more of the not exported bones have Joint edits defined. Those definitions would then get lost during export.

Hint: You want to enable this option in most cases.

Disabled: Do nothing
Enabled: Take care that all parent bones of exported Bones are also exported.

Collada Options

The Collada options are mainly for exporting the models with the most possible extra information. This data can ater be used by other 3D programs or target engines for rebuilding as much of the original Avastar rig as possible. Those options are rarely used.

Export Bone Roll: Export Bone Roll using the Blender Collada Scheme.

Hint: This is only useful when you want to later import back the Dae file to Blender.

Disabled: Do nothing
Enabled: Export the Bone roll according to Blender’s Collada Scheme

Export Bone layers: Export Bone Layer Data using the Blender Collada Scheme.

Hint: This is only useful when you want to later import back the Dae file to Blender.

Disabled: Do nothing
Enabled: Export the Bone Layer data according to Blender’s Collada Scheme

Export with Blender Profile: Use Blender Collada scheme for exporting Blender specific Information

Hint: This is only useful when you want to later import back the Dae file to Blender.

Disabled: Do nothing
Enabled: Export Extended Options according to Blender’s Collada Scheme

Unsupported Options

Avastar also provides some advanced export options. However those options are not shown by default as they are only rarely used.

Note: If you really want to use these options, then you first need to enable them in the Avastar Addon Properties Panel.

You enable these options in the Avastar Add-on Panel (where you initially enabled the Add-on after you installed it):

Limit Weight Count: In SL the number of weights per vertex is strictly limited to 4. We believe this number is enough for all weighting tasks. In cases where you think this limit is too low, we always found the real problem was due to bad mesh topology and bad rigging.

Setting this number affects the maximum number of weights which are exported by Avastar. We strongly recommend to keep this number set to 4.

Troubleshooting an export- Read more...

Troubleshoot Collada Export Warnings/Errors

Warnings

When exporting meshes with the Avastar Collada exporter, our tool detects possible issues which may or may not become an issue when you later upload to the target system. In that case you get a popup window after export with a list of possible issues.

Errors

Sometimes Avastar detects serious issues which can not be exported in a good way. In this case You will get another similar popup that lists all issues.

If there is more detailed information available, then you find an additional (?) Icon on the left side of the message. Click on this icon to open a web page with more information.

Below you find a list of Exporter messages with brief explanations.

Messages from the Avastar Collada Exporter:

  • M001 : Limited weightcount to 4 for nnn verts in Mesh sss
    Your Mesh has vertices where the number of assigned Bone weightmaps exceeds the number of allowed weightmaps (4) SL supports up to 4 weightmaps per vertex. Avastar has fixed this for you by reducing the number of weights on affected vertices. Caution: This automatic fix may affect the visual shape in SL.
  • M002 : Found nnn zero weighted verts in sss
    Your mesh contains vertices which have weightmaps assigned, but all weights sum up to a value of 0. Caution: This may result in unexpected behavior and distortions when later uploaded to SL.
  • M003 : Bone sss is not defined in SL. nnn weights not exported
    Your mesh contains bones and related bone weightmaps which are not recognized by SL. The bones and weightmaps are ignored.
  • M004 : The Mesh sss uses nnn Bones while SL limit is nnn Bones per Mesh
    Your Mesh has vertices where the number of assigned Bone weightmaps exceeds the number of allowed weightmaps (4) SL supports up to 4 weightmaps per vertex.
  • M005 : High Tricount nnn in material face [sss] of mesh sss
    SL allows up to 21844 triangles per texture face. Your mesh contains texture faces with more triangles. the SL Importer will cut your mesh into pieces so that the maximum triangle count is obtained per texture face.
  • M006 : Image [sss] from material [sss]: not found on disk
    The image is not available at the specified location on disk. This may happen when you got the blend file from someone else but the images have not been loaded into the blend file.
  • M007 : Image copy failed
    The image could not be copied from the source to the destination. Typical issue: Missing write Permission or Disk full.
  • M008 : Armature [sss] not an Avastar Rig (can’t export mesh [sss])
    The Mesh uses an Armature that was not recognized as an Avastar Rig. Avastar can only export rigged mesh that is rigged to Avastar Rigs.
  • M009: Out of Date Reference for [sss]. (need rebind/repair)
    Avastar supports the Appearance slider system of Secondlife. For this purpose Avastar maintains extra data which needs to be updated when a mesh is edited in some way. But those updates can take time and can not be done silently in the background. The user must actively update the reference data instead. Avastar checks before exporting if that happened and rejects the export if necessary. You can update the reference data in the Skinning Panel
  • M010: No image assigned to mat:[sss] tex:[sss] A material with an image texture has currently no image assigned to it.
  • M011: nnn weightgroups assigned to non deforming bones in Mesh [sss] Blender’s Armature allows bones to be marked as deforming (contribute to skeletal animation of meshes) or non deforming (Only contribute to skeletal animation of Bones). Avastar issues a warning if it detects that non deforming bones are assigned to weights. This is not necessarily an error, but its at least a confusing situation.
  • M012: nnn unweighted vertices in Mesh [sss] Secondlife needs all vertices of a rigged mesh to be assigned to at least one single weight. This message indicates that Avastar has found one or more vertices which do not have any weight. This is an error, Avastar will reject the export.
  • M013: nnn verts have a weight sum of 0 in Mesh [sss] Blender allows weights of 0 in the weight maps. If all weights for a vertex are set to 0 then the vertex is treated as not weighted at all and thus not animated. This is an error, Avastar will rehjject the export.

More trouble makers

MAV_BLOCK Parsing error

If you create small objects with disconnected sub-meshes, then you often get errors labelled as MAV_BLOCK Error when you try to upload your mesh to Second Life.

The image aside gives a nice example of a single object that is made of many smaller disconnected submeshes. While there is nothing wrong with this mesh, the SL Importer often has trouble to import the mesh.

reference-058

The reason for this issue is hidden somewhere in the Second Life Upload process. We believe the reason for the issue is that the SL Importer deletes Submeshes when they become too small. Then suddenly a part of the Mesh gets removed and this can end in a situation where a complete texture face is no longer available in one of the LOD’s. Then the SL Importer runs into this issue.

A known Workaround

In all cases where small submeshes where involved, we found that adding your own (simple) physics mesh to your Object solves the problems:

  • Create a simple mesh like a cube or a tetrahedron for example. The size of the mesh does not matter.
  • Export this simple mesh as Collada file
  • Import your Mesh as usual.
  • But before uploading visit the physics tab of the SL importer
  • There add Physics mesh from file
  • select your simple object

Now the upload should work.

DAE Parsing Errors

Second Life users frequently report a Dae parsing error. We found a couple of situations where this error appears (see below). However, in general your first step is to look into the Second Life Viewer Logfile…

Find the Viewer Logfile

The logfile is named SecondLife.log (assuming you use the default SL Viewer). Different viewers might use different names.
Typical locations where the logfiles can be found:
Windows XP C:\Documents and Settings\%USERNAME%\Application Data\SecondLife\logs\
Windows 7 C:\Users\%USERNAME%\AppData\Roaming\SecondLife\logs\

Typical causes for this issue

Special characters in Object names

Most dangerous characters are: & < ! > # $ ‘ “

Resolution:

Remove special characters in Object names and then export again

Special characters in File names

Most dangerous characters are: & < ! > # $ ( * ) [ ] { } ‘ “

Resolution:

Remove special characters in file names (renaming the .dae file should be enough)

Extremely dense Meshes

Please check if your mesh contains areas with very small triangles (edge length smaller than about 1 millimeter)

Resolution:

Try to avoid high resolution meshes. You are doing better when you put high density into textures and normal maps (Normal maps are now supported by Second Life)

Orphaned edges and vertices

If your mesh contains edges which do not belong to any face or disconnected vertices.

Resolution:

Remove these edges and vertices.
Hint: in Edit mode Select -> Non Manifold to find candidates. You may want to disable the “boundary” option in the operator panel.

Duplicate Vertices

If your mesh contains duplicate vertices this can cause issues. However sometimes duplicate verts are on purpose (for example when you use the split edge modifier in Blender 2.73 or older) so you need to test if this issue is caused by split edge or by accidental duplicates.

Resolution:

Remove the duplicate vertices.
Hint: in Edit mode ‘W’ -> Remove Doubles to delete the duplicates.

 

Import your Character to SL

Once you have exported your Mesh character, you only need to import it to your target System (like SL or a compatible online world). Although this is easy in principle, there are a few pitfalls in your way. So let us take a deeper look into the Mesh Importer.

 

The Video explains:

  1. How to import a rigged Mesh to SL, OpenSim or similar online worlds.
  2. How to use an Alpha mask for hiding the default character
  3. How to use image textures to texturise your character.
  4. Potential problems with your meshes (visible seams, wrong shape, missing face animations)
This video has been made in SL. But it applies also OpenSim or any other OpenSim based world as well. Also the video does not depend on Blender, but it is a general purpose tutorial for the SL Importer. Below you find the import procedure explained in pictures.
Hint: Did you know that Linden Lab provides another world very similar to Second Life, where you can upload your meshes for free? The Beta Grid is a perfect way to test your mesh creations before you finally upload them to Second Life.

The Upload Panels in detail

Upload the model (import the Collada file to SL) - Read more...

You can start an upload directly from the main menu bar as shown in the image above.You also can start an upload from within the repository view.

The LOD Panel (The entry page) - Read more...

The model uploader starts in the LOD panel. Here you can define all your levels of detail or let them calculate automatically. We currently have no LOD files, so we keep this panel as it is.
Note: You always can get detailed help from the help button in the upper right corner. For now you can proceed by switching to the Upload options tab.

The Rigging Panel (Here you check if Skin Weights are included) - Read more...

Normally the uploader will only upload the mesh, but no animation data. If you want to also import the rig data (the mesh weights), then you have to include “skin weights”. Please keep the button “Include joint positions” unchecked unless you know exactly what you do. we will get to this advanced feature later.
Also note that you can checkmark the “skin weights” below the Preview window to see if your mesh is properly weighted. But checking the skin weights here has no influence on the upload! This is so common mistake! If you ever are “sure that your mesh is weighted” but remains stiff when worn, then there is a good chance that you forgot to enable “Include skin weights” on the left side!

Step 4: (Optional) Import your Shape back to SL

Sometimes you might have modified your Shape In Avastar. And maybe you want to get your modified Shape back into Second Life. While the default SL Viewer does not provide a Shape Importer, most other third party viewers offer such an option nowadays.

Exporting a Shape from Avastar

You can export your current shape from Avastar to File as follows:

  • Ensure Blender is in Object Mode
  • Select the Avastar Armature
  • in the Object Properties locate the Avatar Shape panel
  • There you find a Save Shape To option

Importing a Shape to Second Life (using Firestorm)

You can import your shape back to Second Life with the Firestorm viewer as follows:

  • Enter the Appearance Editor in your Firestorm Viewer
  • Down in the right lower corner of the editor you find an Import option
shape_importer

The Firestorm Viewer provides an Import Option right within the Appearance Editor.

Now we are done with our first Mesh creation. You can simply wear the mesh and see how it moves with the default animations…