Cleaning up your act - how a round trip through blender can improve your mesh

Those familiar with my blog may recall that our journey together through the art/accident of mesh making began with, and often returns to prim2mesh tools such as Mesh Studio (MS). During a period of particularly poor reliability from the Mesh Studio servers, in 2016, I made a blog post and video explaining how some of the optimisations achieved by Mesh Studio, could, with a little knowledge, be replicated in Blender.

That was a long time ago now, Blender has moved on and while MS remains perfectly adequate for many users, the loyal Mesh Studio user base has been challenged once again by instability and uncertainty. There is no suggestion that the product is anything other than the victim of circumstances ( and a pernicious bug) but it seems appropriate to update the "fallback plan" tutorial(s)

What are we going to learn today?

For this first "tutorial" we will look at the basics. After a quick reminder of what MS and similar tools do for us, we'll look at exporting to Blender, an initial cleanup, and then re-exporting.

What is a Prim2Mesh tool and why do I need it?

Let's have a quick recap on what it is that Mesh Studio and similar products do for us. Prim to mesh tools are typically used by builders/creators who wish to work inside Second Life, and/or who lack the skills required to create mesh in an external tool. They provide a convenient interim solution bridging the gap between the simple (but powerful) prim building in Second Life and the complex and frequently daunting Mesh creation tools such as Blender, Maya and 3DS Max. I will focus here on Mesh Studio but for the most part the same applies to similar products.

With Mesh Studio, the user is free to create their object using any prims that they like, this includes pretty-much any slices, twists and other tortures. Once the user has their model built (and ideally) textured, they simply drop in a script and use a menu-driven interface to analyse the prims and produce a mesh. The product is composed of two parts, an in-world scripted system that sends a detailed description of the linksets to an off-world server via a web  API. The Mesh itself is constructed on this external server and provided as a zip file containing the Collada (DAE) model ready to be uploaded into Second Life. Herein lies the Achilles heel of these solutions; any tool that depends on an external service is beholden to the operator of that service.

The menus and other scripts allow some pretty sophisticated constructions. In fact, the entire crystal palace exhibition glasshouse, a recreation of the original Hyde Park crystal palace from the late 19th Century, was created entirely using Mesh Studio by Vic Mornington, a long-term New Babbage resident and Mesh Studio connoisseur.

Full size : https://gyazo.com/fcfafb7cd350502aa75d009de632b913

The key features that Mesh to prim tools include are:-
1) some control over the mesh complexity (how many edges make up a curve or straight-edge
2) the elimination of unused mesh faces (transparent faces are not "meshed")
3) Simple mesh validation, checking that the number of materials used does not exceed the SL limit of 8
4) The merging of prims into one or more mesh units and elimination of some of the duplicate vertices.
5) The correct UV mapping to ensure that the resulting mesh can be textured the same way as the prim model.

The 2016 blog post linked above explains why this workflow is useful, it can be especially helpful when working on a project that needs to fit into a specific inworld scale and many creators use Secondlife tools to "prim-out" a rough model to use as a scale template.

So what do you do if the tools are not working?

You have your model, the deadline is approaching, you finish tweaking the textures and click on the menu....nothing...the server is down.

Blender and Firestorm to the rescue.

Blender is a free, open-source 3D creation tool. It stands squarely against many of the leading commercial packages that dominate the professional world and is increasingly making inroads into the commercial world of games and VFX. Blender has a reputation for being rather unfriendly to use,  personally, I think that this is overstated. All the big 3D desktop creation packages have complex user interfaces and no shortage of peculiarities, I tried learning any number of them in the past and found myself bemoaning the complexity and yearning for the solid ease of plugging prims together. The fact is that with power comes complexity. Someone used to Maya will swear it is the best, A 3DS Max aficionado will be equally convinced that their tool of choose is the best one. There is no single answer, pick one and stick with it. If you have no specific reason to pick one tool over another then Blender has two very significant points to consider. 1) It is free 2) It has a vast and ever growing ocean of tutorials and youtube channels. But don't choose blindly, if you have a friend or mentor who swears by another tool and you can afford that tool, then perhaps that is the better choice. The discussion that follows will not apply directly to those of you choosing a path other than Blender, but for the most part, the principles will remain the same.

What you should not listen to is all the moaning and whinging from people who used it in the past and failed.
1) They may not have failed because of Blender, in many cases it is simply the learning curve of moving away from the SL interface to something more complex.
2) They may not have tried a recent version of Blender (if they bemoan the mouse button selection, for example, nod politely and walk away - that has been configurable for many years and since last years revolutionary version 2.8 left-click select is the default).

Any tool is going to take practice and commitment. Pick one and commit. There are many excellent tutorials for Blender, prefer 2.8 ones over 2.7 at least until you know enough to work around the UI changes. Andrew Price's "Donut" tutorial series is as good a place as any to start. Look around SL for support groups for your chosen tool too.

And so onto the viewer... I will be using Firestorm because I am, of course, biased, but a number of other Third Party Viewers (TPVs) support the export of prims as Collada and the workflow should be very simple to translate to your chosen TPV if required. I will be using the Firestorm dialogues in my examples, but they will most likely have direct equivalents in other TPVs.

Please note: The Second Life viewer from Linden Lab does not have any export capability at present. Feel free to lobby your local Linden if this is important to you, Jiras are more effective than pitchforks.

SL-Blender roundtrip summary

The rest of this post is going to go into detail and the blogger platform is not ideal for formatting this so bear with me. I'll try to create a supporting video as I did before but I know many people prefer to read than watch, so I'm going to try to capture as much as I can in text as well.

It is probably worth re-stating our objective here. We are not looking to do anything advanced in terms of mesh creation, we are not going to bake textures, for example. Moreover, our objective is to retain (as far as possible) the UV layout (the texturing) that we established inworld. This simplified workflow is to enable people to export a prim model, "clean it up a little" and re-import it into Second Life/OpenSim with (hopefully) a lower Land Impact (LI), a workflow analogous to that of the Prim2Mesh tools.

Here is the high-level summary for the TL;DR crowd:-

I should note here that this is not the only workflow the steps can often be mixed up as best suits the purpose and things are often best taken iteratively. These techniques, however, should be sufficient to get you through most clean-up jobs.

Step by step overview

1) Grab Blender, I will be using 2.82. Download it here
2) Export the mesh from SL. I will be using Firestorm (of course), many other TPVs should work too.
3) Import the mesh into Blender.
4) Prepare the mesh for cleaning.
   a) Restore quads - establish some nice edge flow that will pay dividends later.
   b) Join the mesh - make sure our UVs are safe first though.
5) Cleaning.
   a) Remove doubles.
   b) Simplify the geometry -we'll look at a non-definitive selection of strategies.
6) Export again.

What won't we cover?

• We will not cover, creating LOD models in this article, though I may hint at options. I will look at this in a future blog.
• We will not examine UV editing, our objective is to leave those untouched
• We will not look at physics objects. I have older blogs for that and future ones planned.

Step 1, download and install Blender.

Get the latest stable version from Blender.Org, at the time of writing this is version 2.82, though I am eagerly awaiting 2.83.

Step 2, grab your TPV of choice and export your prim model.

I am going to be using this old seahorse sub prim model, it comprises a number of useful features for our purposes, some transparent mesh, that we do not want to export, a few different textures and a couple of sculpted prims. It will pose a number of problems and has some rather awkward geometry to deal with.

Triaging the patient

Before we export it is worth taking some time to make sure things are as clean as possible.

I've deliberately picked a rather poor example, in the movie that accompanies this post you will get to see me trying to clean this up, applying the tricks I list here.

The model I am using is a steampunk seahorse submersible that I first built in around 2008. IT was never intended to be meshed, it has never been prepared for use with a prim2 mesh tool. For this exercise though we are simply going to export it clean it up. I

I have taken a few steps to clean up beforehand and I would strongly recommend the same to you. 

If there are prims that should "join" try to align them as close as you can. I will demonstrate how to fix cases where this has not happened, but as you will see it is easier if you do some work up front.

The model consists mostly of prims, the distinctive curved tail is a sculpty as is the exhaust array fin on the rear. The tail has some leftover vertices that we will also clean up in Blender. The top opens up using alpha-switching, which for a physical vehicle in 2008 was the only realistic means to get an opening submersible. With this test we are not going to open it up at all, so I have even set the interior to transparent where I can. this is no different to optimising your prim builds for Mesh Studio by removing the hidden faces.

We would quite like to export the textures, and we need the sculpts (the tail and brass fins on the back). Exporting the textures will be useful throughout the process, they will allow us to see when we take a wrong turn (the UV layouts get messed up); even if you are only using a "UV checkerboard" it will help you see when you need to take a step back and try a different option.)

Finally, before exporting I ensured that the rotation of the model was aligned to the axes.

Exporting

To export it we use the "save as..." menu, accessible by right-clicking on the object, if you have pie menus you will need to click more and more again to find the option. From "save as..." click "Collada".

You should be presented with a dialogue that looks a little like this.


In this case, we see that the object consists of 29 prims and that all of them are exportable. This is great news, in order to be exportable you have to be the creator of the prims and for sculpts you have to be the creator of the sculpt image that underlies the sculpty too. For the submersible, it is all mine.

The textures, however, we fail on 2 of them. They happen to be full perm, both taken from the Linden provided library I believe (the glass and the brass) but as I am not creator I cannot export them and those prim faces will be exported blank. If I wanted I could actually save these separately because the permissions allow it but they are not essential to our purpose here.

The options we pick are important.

• Save textures - We would like to save textures where we can, this will allow us to see the textures when we import it into Blender later.
• Consolidate textures - shown here "unchecked" but actually we want it checked. This will combine all the uses of the same texture into a single material in the export. Without this, every prim that has the rusty metal texture will get its own copy. This would be a real pain later.
• Skip transparent - very important here, we do not want all the extra mesh that results from the hidden faces, by enabling this option we can avoid that. 
• Apply texture params - this ensures that the texture repeats and rotations are preserved in the export, it ensures that the UV mapping is the same as you see inworld.

Finally, we can select our preferred format to save the texture images in, if you expect to work with the textures I would suggest sticking with Targa, it is a lossless format and while the source image has already undergone lossy compression, we do not need to add further artefacts at this stage.

Please note: that the export code pre-dates materials and as such all normal maps, spec maps and other materials settings are ignored completely.

Once we are happy we click "save as", give it a name, and save it to our local disk.

Something to remember, it is well worth taking a moment to ensure that your object is rotated to 0 degrees (or at least some whole number) I failed to remember that in my tests and I had to fiddle about cleaning that up in Blender.

And on to Blender....

Step 3 is to import it into Blender.

You will need only a few skills to follow this tutorial, but I am not going to try to include a beginners guide to Blender in this post. Please watch the first episode or so of the aforementioned Blender Guru Donut project. It will do a far better job of equipping you with basic Blender skills than I can.

With that out of the way, I'll assume that you can navigate in the 3d viewport, and find a few of the main menus, I will try my best not to assume much more than this.
Start with a new scene, delete the default cube if it is there.


Importing Collada is very easy, File->Import->Collada, locate the file on disk where you saved it. click "Import Collada" to import.

Your object(s) should appear in the viewport. Depending on how you have Blender setup following your "basic" tutorials you may well see your import mesh as entirely grey even if you exported the textures. To change this go to the top right of the 3d viewport and enable the rendered view. This will put you into the Eevee rendering engine and your textures should now be visible.



As you can see from my images, there is an acne rash of little orange dots. These are the centres of the individual prims. We will normalise these, along with the scale and rotation. so that everything is starting from a nice origin. (If you forgot to align your model before saving it, now is the time you'll repay that debt).

Applying the loc/rot/scale is easy. Press 'a' to select all the objects, then ctrl-a to apply transforms. You will be presented with a menu, you can select "all transforms" or a subset if you prefer. There will be no noticeable change to the model except that any "origin acne" will be cleaned up as all the objects now have their centre at the global origin.

Joined up thinking

The viewer export has saved every prim as a separate object. Sometimes this is useful, but most of the time it is not what we want. At some point, we will need to join some or all of the prims together. In my example I am happy for this to be a single mesh, it will have fewer than 8 texture faces in total and thus it will be suitable to upload as a single item.

Linking meshes is simple enough. Ensure that you are in Object mode (you should be by default, press TAB if not). "Object Mode" will be shown on the top left. Working in Object Mode is a bit like working at prim level in SL. We can select the objects we want to link together (pressing A will select them all), selected objects will have an orange outline. 

Once you have them selected hit ctrl-J (join).

Oh dear.... that was not what we wanted at all. We selected all the objects but as soon as we joined them all the UVs went bad. You can see this in the video, the blurring of the textures is an indication that all the UV data was lost.

The problem here is that we have more than one UV map, in fact, the exporter gave every object a uniquely named UV map. This may be considered a bug in the exporter. I would certainly entertain making this option in a future Firestorm release. However, for now, it is how it is.

Ctrl-Z will safely undo the damage, Undo is you friend in Blender, there are 30 levels of undo by default I typically increase that to 100 in the preferences.

The next step is a bit of a pain, we need to go through each prim and rename the UV map to be the same as all the others, then when we join they will show as a single UV map..

The UVMap details are located in the mesh tab of the properties window on the right of the screen.
look for the green triangle with tiny circles at the points. Click in the box and rename the UVMaps from primN-map0 to something simple like combined-map or just map0

The important part is to ensure that all objects share the same map. Doing this for a large number of objects is a royal pain in the posterior, so I cheated...

(spoiler: I wrote some python to do this, but fear not, I will be releasing this as part of my free/open-source SL tools Addon SOON)

https://gyazo.com/b68fc5e0f349cde986f834105f1840df

I have now updated all my UVmaps to share a "unifiedmap".

Now I can safely ctrl-J and all the meshes are joined as one and all the UV information has been retained. This gives us the combined single object mesh we see below.

https://gyazo.com/28b43f7d638cae8ce9d874556f7446be

Let's get cleaning

Press TAB to enter Edit mode. 

Tip #1: Convert to quads

The first thing we can see is that the mesh is made up of triangles. This should not be surprising, but it is inconvenient for editing and it breaks any "edge flow" and loops that we have. It is an unwritten rule of Mesh creation to work in Quads as much as possible.

The following animation will show the benefits of having proper edge flow in the mesh by showing the selection of edge rings and loops before and after the removal of triangles. 

To remove the triangles we select all (A) and then press alt-J, this converts triangles to Quads where possible.

The quad conversion process can be complicated, it is not an exact process; the "tunable" setting on the quads converter can be used to control the angles that are used in the conversion. You can see how I use this to tweak the behaviour in the neck area.

It is not unusual for a few triangles to get left where you would have expected quads. We can clean these up using the "dissolve and join" trick we'll look at shortly

Our mesh is far cleaner to look at but we've not actually improved the geometry because we've left all the vertices in place.

Simplifying and refining

One of the tricks that Mesh Studio does for us is combining co-located vertices where possible. We can actually do a far better job in Blender as we have direct control. But for now, we'll just keep it simple. The objective here is not to rebuild/redesign this mesh, those skills we can work on later, we simply want to clean up this mesh and optimise, replicating where we can the functionality of our more familiar inworld tool.

Tip #2: Merging

What do we want to merge? where prims were aligned next to one another in SL we want them to be physically joined. to do this we want to merge the vertices that are on top of one another. In Blender, we can select the whole mesh or just the parts we want to work on and then use alt-m to find the merge menu, and pick "merge by distance" this is the new and more logical name for what was called "remove doubles" in earlier versions of blender. When we merge by distance we can control how close vertices need to be in order to be merged.

• Select some vertices
• Alt-M "by distance"
• Use the dialogue that appears to adjust the distance or press F9 to make it reappear.

The merge tool, as most are in Blender, is not fully applied until you commit the changes and move to another operation and thus it can be tweaked back and forth. Even after this, you have ctrl-z of course. I use undo a lot to test whether one operation works, then undo and try another.

Other merge options are equally useful. 

if you have two prims that you had wanted to join, but their vertices were not properly aligned then you can merge them manually. Select the vertex you wish to move and the one you wish to move it to, then Alt-M "merge at last", this merges all the selected vertices into the last vertex selected. Merge at first does the opposite, while "At center" while find the central point of the selected vertices and merge them there. Play with the various options to see which work best for you. 

Merge at cursor, is also powerful but is best used in conjunction with more advanced tricks that I will save for another post.

Getting more tricksy...

We've done the simple things, our precious UV layout is still in place, but look at the mesh, it is still more complex than it needs to be.

Second Life Prims have 4 vertices per straight edge, one at each end and two spaced along the edge. These do have an impact on surface lighting but are typically removed in mesh. This is most evident in the back of the "neck" of the seahorse


The edges (highlighted) are not needed and so we will remove them. There are (at least) two ways to do this, the first is the most simple but may also miss some opportunities that we, as humans, can spot.

Tip #3 : Limited dissolve

Limited dissolve is an awesome tool. It can help you in LOD production as well as the basic clean up. so what does it do? It traverses the mesh and examines the angles between edges if a given pair of edges have an intersection angle of less than the threshold then it will try to dissolve them. What we want to do here is the bare minimal dissolve, removing vertices that are on straight edges and add no real value to the mesh topolgy.

Select all of the parts that you want to clean. Probably this is everything, in which case, in edit mode, hit 'a' to select all. Next press 'x' to get the delete menu and select "limited dissolve". A small control panel should appear in the bottom left, inside this you can set the maximum angle beneath which you want to dissolve. Set this to 0.1. You should find that all extraneous geometry on flat faces has vanished. this may leave ngons (mesh "panels" with more than 4 sides) but don't worry this will be resolved later when we triangulate again. As we see in the video, that extra edges on the back of the neck are dissolved, but also the inner curves on the side of the neck, which when we triangulate later become a single triangle fan. In that case, I had 6 sides of a tube, there were 3 concentric rings of triangles as shown by the quads there beforehand. In total, 30 triangles. when we export this, it will be just the 6. That's not a bad result.

The following clip will show me performing this.

Tip #4 : Manual dissolving.

In edit mode: highlight the edges that you wish to remove.
note that now we have edge flow back we can use alt-shift-click to select the entire loop, be careful you have only selected what you need though.

Next press 'x' and from the menu that appears pick "dissolve edges"


Two points to note here. Firstly, dissolve only works when blender feels it is able to remove the edges and vertices without breaking the integrity of the model. If you cannot dissolve then there is probably a dependent vertex that is blocking you. Continue cleaning up and come back to this later it may have been freed up. Dealing with it otherwise is outside of the scope of this guide. Secondly, the quad conversion can go awry at times. We tried to minimise the problems using the sliders but often there are still places where the automation does something a little less than obvious. This is the time to fix those too.

I illustrate this in the following gif. This is a pretty extreme example, but one that can happen. The result here is nice clean quads.

Repeat this process across all the model until you feel you've removed all the unnecessary extras (this is why method 1 is preferred where possible - it saves a lot of time).

Patching and Repairing

We've gone a long way now to cleaning things up. I've used a particularly complicated model to test this with and for most simple items you may well be done at this point and can skip to the next step of re-exporting the DAE ready for Second Life. However, what if you have broken geometry that you'd like to clean up? Here's a few more tricks that might come in handy.

As always, this post is only scratching the surface of what you could do, and none of what I write here is necessarily the best way, it is certainly not the only way. With this in mind here are just a couple of final shortcuts and tricks that I use.

Tip #5 Hot key selection mode switching while editing.

In Blender, you can by default select one of vertices, edges or faces, in fact you can enable multiple at once but I find that confusing so I will not cover it here. As of Blender 2.8, you can quickly switch using the 1, 2 and 3 key on the top row (not the numpad as they control view).

Pressing 1 will let you select vertices, 2 for edges and 3 for faces.

Tip #6 : relinking vertices. 'f' for fill, is the best way to join

When you have two vertices and you wish to join them you can often highlight them both and press 'j' to join. but it does not always do what you want. You can quickly rebuild bad geometry by combining the dissolve edges, mode switching and filling tips.

Here you can see me cleaning up the results of a poor "limited dissolve" applied earlier using these few simple moves.

I iterate through the mesh, switching to vertex mode (1), selecting two vertices and joining them (f), then switching to edge mode (2), selecting the unwanted edge and dissolving it (x).

A few other tricks that are not essential but which I use a lot include:

Tip #7 Selecting things

I talk a lot about operations that act upon selections but how do we select?
In the gui there are many ways and I won't describe those in-depth, the icons and tools are mostly self-explanatory. box select, lasso select etc. I will instead focus on the keyboard short cuts and quick operations.

1. Select all (a) - pressing 'a' selects all vertices/edges/faces depending on your selection mode. In object mode it selects all objects (this includes lights and cameras so use the outlined window in the top right is you want to select some specific items) 
2. Deselect all (alt-a) - set the selection to nothing.
3. Select linked vertices. (ctrl-L) select only the vertices that are linked in the same contiguous mesh as the selected vertices. e.g. if you have two cubes and join them, they are one object but they are not connected in the mesh highlighting the corner of one cube and hitting ctrl-l will select all the verts in that cube and leave the rest unselected. 
4. Hide selection (h) - as the name suggests this makes the selected vertices and any edges connected to them vanish from view. Great for getting access to interiors.
5. unhide hidden (alt-h) - brings back everything you previously hid. 

Tip #8 Iterate and save often

In the next section, I'll explain how to save and to export (two subtly different things). Save often, use the versioning I describe and don't be afraid to try things out. you can often go over the process a few times to continually improve the results.

Exporting our work.

Finally, we are ready to export so that we can return or work to Second Life.

Make sure that you leave edit mode and return to object mode. Like many 3d tools the changes made in edit mode in Blender are not "finalised" until you leave edit mode. to switch back we need only press tab.

We will save our work as a blend file first, an optional step but worth doing in case we want to make further changes once we see what this looks like in-world.

To do this go to the file menu at the top, and click save as ... (shift-ctrl-s is the short cut). You will be asked for a filename. One of my favourite "lesser known" features is that if you pick a name that already exists in the file selector, the field at the bottom will go red to warn that you are going to overwrite, there are two symbols a '+' and a '-' at the far right of the field, these will automatically add and increment (or decrement) a number in the filename allowing you to keep "versions" of your progress. I tend to use this all the time and end up with tens or hundreds of iterations that I clear up once I am finished.

This image shows that I am trying to save my prim cleanup work in progress. You can also see that I have 22 versions of another model (my fully blender-native recreation of this model as it happens) in the same folder. If I click the '+' it will save as 'hippocampus prim cleanup WIP1.blend".


Pick a filename and save your blend file.

Now we will export the Collada (DAE) file.

First, we will highlight just the mesh objects we wish to export.
If you joined things into a single mesh then click the object you need. If you left it in multiple parts then shift-click to select all the ones that you want.

Next go to the file menu, export, Collada


You will now be shown a file dialogue. It will default to the name we chose when we saved the .blend file. There will be an "Export COLLADA" button highlighted.

DON'T PRESS IT YET!

This is one aspect of the new Blender I don't like very much as it makes life harder for new users.
The defaults for Collada export are rarely what we need. To change the settings we have to press the "cog" to expand the settings on the right-hand side.



In this settings box, we need to enable selection only. But there is a preset available, so let's use that. Click the "Operator presets" and select "SL + Open Sim static".

If we do not do this, Blender will export all the objects in the scene including the lights and cameras, sometimes this is fine, but as you get into more complex objects it is worth getting into the habit of explicitly exporting only the parts that you want.

We can now press the "Export COLLADA" button. If things work properly you will see a small message pop up on the screen saying "Exported N objects" depending on how many objects you had selected. It is always worth keeping an eye on that, if it is not what you expected then something went wrong, double-check that you had "selection only" selected and that you had remembered to come out of edit mode.

And that's it, you can now upload as normal.

A few last notes

Don't forget that you may well have joined your objects. If you had prepared the linkset as if you were using Mesh Studio then you will presumably have limited your "mesh faces" to 8, if not then be careful to check that you only had at most 8 materials in your mesh or you will get one of the mysterious "MAV errors" or a "model not a subset..." type error in Second Life.

Most of what I have taught in this blog should be "non-destructive" with regard to UV layout. However, an over-zealous use of the dissolve tools will leave areas in a mess and I have not tried to explain how to dig yourself out of that hole. Try to keep things in rendered mode, so you can see the textures and the effect your changes have on them. 

This concludes what I think you'll agree was a far longer delve into the cleanup process than the 2016 one. The steps I show are I think quite straightforward, and hopefully, with a little practice, you'll learn not to fear the tools. What I have explained here can be translated into other tools such as Maya or 3DS Max. My weapon of choice is Blender and for me, it is the right tool for pretty much everything I need to do. The thing I want to say though is that no matter what tool you use if you are starting from a background of Second Life prim editing, they are all going to be daunting, they are all going to be hard, and you will struggle, stumble and fall at times. Start simple and build up from there, when you fail, pick yourself up, and try again. You'll get there. 

Love 

Beq

x

When is a triangle not a triangle? (mesh streaming)

When is a triangle not a triangle?
(when it's compressed)

Welcome to this 6th in the series of blog posts examining the task of creating a Blender Addon to assist with our Second Life Mesh creation workflows.

In the last post, we discovered that all was not quite as it seems in the mesh streaming calculation. Our carefully recreated algorithm repeats all the steps that the published documentation discusses and yet the results did not match. We further learned that this was most likely down to the "estimation" process.

So what is the problem here?

The clue is in the name, "Mesh Streaming Cost" it is intended to "charge" based on the cost of streaming the model; so what does that mean? In real terms it means that they are not looking at the difficulty of rendering an object directly, they are looking at the amount of data that has to be sent across the network and processed by the client. When we export models for use in Second Life we typically use Collada format. Collada is a sprawling storage format that uses a textual XML representation of the data it is very poorly suited to streaming across the internet. This problem is addressed by the use of an internal format better suited to streaming and to the way that a virtual world like Second Life works.

What does the internal format look like?

We can take a look at another of the "hidden in plain sight" wiki pages for some guidance.

The Mesh Asset Format page is a little old, having last been updated in 2013 but it should not have fundamentally changed since then. Additions to SL such as normal and specular maps are not implemented as part of the mesh asset and thus have no effect. It may need a revision in parts once Bento is released.

The page (as with many of the wiki pages nowadays) has broken image links. There is a very useful diagram by Drongle McMahon that tells us a lot about the Mesh Asset Format in visual terms.

In my analysis of the mesh streaming format, it became clear that while Drongle's visualisation is extremely useful it lacks implementation specific details. In order to address this, I looked at both the client source code but also the generated SLM data file for a sample mesh and ended up writing a decoder based upon some of the older tools in the existing viewer source code.

{ 'instance': 
   [ # An array of mesh units
    { 'label': 'Child_0', # The name of the object
                  'material': 
       [  # An array of material definitions
        { 'binding': 'equatorialringside-material',
                     'diffuse': { 'color': [ 0.6399999856948853,
                                             0.6399999856948853,
                                             0.6399999856948853,
                                             1.0],
                                  'filename': '',
                                  'label': ''},
                     'fullbright': False
        }
       ]
       'mesh_id': 0, # A mesh ID, this is effectively the link_id of the resulting linkset
       'transform': [ 10.5, 0.0, 0.0, 0.0,
                      0.0, 10.455207824707031, 0.0, 0.0,
                      0.0, 0.0, 5.228701114654541, 0.0,
                      0.0, 0.0, 2.3643505573272705, 1.0]
    }
   ],
  'mesh': 
   [ # An array of mesh definitions (one per mesh_id)
    { # A definition block
     'high_lod': {'offset': 6071, 'size': 21301},
     'low_lod': {'offset': 2106, 'size': 1833},
     'lowest_lod': {'offset': 273, 'size': 1833},
     'material_list': 
         [ # array of materials used 
          'equatorialringside-material',
          'equatorialringsurface-material',
          'glassinner-material',
          'glassouter-material',
          'strutsinnersides-material',
          'strutsinnersurface-material',
          'strutsoutersides-material',
          'strutsoutersurface-material'
         ],
     'medium_lod': {'offset': 3939, 'size': 2132},
     'physics_convex': {'offset': 0, 'size': 273}
     <compressed data=""> 

     # LENGTH=SUM of all the size parameters in the LOD and Physics blocks
    }
   ],
  'name': 'Observatory Dome', # name of the given link set
  'version': 3  # translates to V0.003
}

All of this is an LLSD, a Linden Lab structure used throughout the SL protocol,  effectively an associative array or map of data items that is typically serialised as XML or binary. The header portion contains version information, and an asset name, it can also have the creators UUID and the upload date (if it came from the server) .

We also see two other top level markers, 'instance' and 'mesh', this is the stuff we really care about.

Instance

'Instance' is an array of mesh units that form part of the link set. Often when people work with mesh they use a single mesh unit but you can upload multipart constructs that appear inworld as a link set.
Each instance structure contains a set of further definitions.

Mesh

The final entry in the header is the mesh array. Like the instance array before it the mesh array has one entry for each mesh unit and as far as I am able to tell it must be in Mesh_id order.
The mesh structure in the array is another LLSD with the following fields:-

At the end of each Mesh is the compressed data that is represented by the bulk of Drongle's diagram and it is for this that we have been waiting for this is why our naive triangle counting solution is giving us the wrong answer.

Compressed mesh data

At the end of each Mesh block is an area of compressed data. Space for this is allocated by the SLM "mesh" entry whose length includes the compressed data even though it is not strictly part of the LLSD.

Once again we need to look at both Drongle's excellent roadmap and the viewer source code to work out precisely what is going on.

As you will recall the Mesh section defined a series of size and offset values, one pair per stored model. In my examples, the physics_convex is always the first model and thus has offset 0.

physics_convex

{ 'BoundingVerts': 'ÿÿÿ\x7f\x00\x00\x81Ú\x81Úa\x18þ\x7fæyþÿÿ\x7f\x00\x00\x
8}%\x81Úa\x18\x00\x00ÿ\x7fa\x18}%}%a\x18ÿ\x7fÿÿa\x181Ö\x16\x86\x97¸Ì)\x17\
                   '¯nÈ\x97¸\x00\x00ÿ\x7f\x00\x00\x9eO\x9aÇ\x94¸Äµ\x92í2\x
                   ':Jl\x12.\x0c'
                   '«·a\x133\x0c'
                   'SH\x9dì.\x0c'
                   'T\x85'
                   '\t}þÿªzò\x82þÿF\x85'
                   '\r'
                   '\x83þÿ¸zô|þÿ',
  'Max': [0.5, 0.5, 0.5],
  'Min': [-0.5, -0.5, -0.5]}

Here we see that the compressed data is really just another LLSD map. In this case, we have three keys, Max, Min and BoundingVerts.

Max and Min are important, we will see them time and again and in most cases, they will always be 0.5 an -0.5 respectively. These define the domain of the normalised coordinate space of the mesh. I'll explain what that means in a moment.

BoundingVerts is binary data. We will need to find another way to show this and then to start to unpick it.

['physics_convex']['BoundingVerts'] as hex
dumping 18 bytes:
00000000: FF FF 00 00 00 00 00 00  00 00 FF FF 00 00 FF FF  ................
00000010: 00 00                                             ..

This is the definition of the convex hull vertices, but it has been encoded. Each vertex is made of three coordinates. The coordinates have been scaled to a 1x1 cube and encoded as an unsigned short integer. Weirdly the code to do this is littered throughout the viewer source, where a simple inline function would be far more maintainable. But we're not here to clean the viewer code.
In llmodel.cpp we find the following example

 //convert to 16-bit normalized across domain
 U16 val = (U16) (((src[k]-min.mV[k])/range.mV[k])*65535);

In python, we can recreate this as follows.

def ushort_to_float_domain(input_ushort, float_lower, float_upper):
    range = float_upper - float_lower
    value = input_ushort / float(65535) # give us a floating point fraction 
    value *= range # target range * the fraction gives us the magnitude of the new value in the domain
    value += float_lower # then we add the lower range to offset it from 0 base
    return float(value)

There is an implication to this of course. It means that regardless of how you model things your vertices will be constrained to a 64k grid in each dimension. In practice, you are unlikely to have any issues because of it. And so applying this knowledge we can now examine the vertex data.

expanding using LittleEndian

0: (65535,0,0)->(0.500000,-0.500000,-0.500000)
1: (0,0,65535)->(-0.500000,-0.500000,0.500000)
2: (0,65535,0)->(-0.500000,0.500000,-0.500000)
Max coord: 65535 Min coord: 0

It is my belief that these are little-endian encoded. The code seems to support this but we may find that we have to switch that later.

We can apply this knowledge to all sets of vertices.

Onwards into the Mesh

Looking into the compressed data we find that the LOD models now follow. They follow in the order that you'd expect, lowest to high.

Each LOD model represents the actual vertex data of the mesh. Mesh data is stored as a mesh per material, thus we find the compressed data section per LOD is comprised of an array /list of structures or what Drongle refers to as a submesh in his illustration, one element of the array for each material face. Each material face is the comprised of a structure of the following:

Field	Description
Normal	A list of vector normal that corresponds to the vertices
Position	The vector cords of the vertices
PositionDomain	The min and max values for the expanded coord data (as per the preceding physics section)
TexCoord0	The UVW mapping data. At present, I have not investigated the encoding of this, but it would appear to be the case that these are encoded identically to the Vertex data but with only the X and Y components.
TexCoord0Domain	The min/max domain values associated with the UVW data
TriangleList	The mesh, a list of indices into the other data fields (the Position, TexCoord and Normal) that form the triangles of the mesh itself. Each triangle in the lost is represented by three indices, which refer uniquely to an entry in the other tables.Individual indices may of cours be shared by more than one triangle.

I think this is more than enough for one post. We've covered a lot of ground.
I am now able to successfully decode an SLM asset in Python and so next we can see how this helps us calculate the LI.

love Beq
x

The truth about mesh streaming

The truth about mesh streaming

Ever wondered why a mesh with the same number of triangles could give different LI? Or how the impact of each LOD model is assessed? Stick with me today and hopefully, I'll show you.

Today's post is the fifth in the series of meanderings through Blender Addons. Yesterday, we left things in an OK state. My AddOn is reflecting the correct triangle counts for the models (and correctly associating the models with the LOD they represent).

Today we will look at the Mesh Streaming Cost algorithm and have a go at converting that to python.
This is an unashamedly technical blog. I will try to explain some aspects as I go through but the nature of the topic demands some technical detail, quite a lot of it.

I am going to work from the latest Firestorm Viewer source, and a couple of somewhat outdated wiki resources. The wiki resources themselves should be good enough, but the problem with them is that you can never be sure if things have been tweaked since. Ultimately though we have a real world comparison, our estimates should match (or be close to) the Viewer upload, we will test this at the very end.

A good place to start is the Mesh Streaming Cost wiki page as with many wiki documents it is out of date and not entirely correct. However, we can use it as a starting place. The concept section explains the thought behind this. The equation part is where we will start.

1. Compute the distance at which each LOD is displayed
2. Compute the area in which each LOD is relevant
3. Adjust for missiing LODs
4. Scale relative weights of each LOD based on what percentage of the region each LOD covers.
5. Compute cost based on relevant range and bytes in LOD

It goes on to tell us what the LOD transition distances are, details we covered in the post yesterday.

Using these we can write another helper function

def getLODRadii(object):
    max_distance = 512.0
    radius = get_radius_of_object(object)
    dlowest = min(radius / 0.03, max_distance)
    dlow = min(radius / 0.06, max_distance)
    dmid = min(radius / 0.24, max_distance)
    return (radius, dmid, dlow, dlowest)

This function takes an object and using our previously written radius function and applying the knowledge above, returns a list of values. The radius itself, the High to Mid transition distance, The Mid to low transition and finally the Low to Lowest.

We use a constant max distance of 512 as it matches that used in the code example and the current live code. Quite why it should be 512 (2 regions) is unclear to me.

So now we should be able to add a new column to our display and show the LOD change radii

Step 2 is to compute the area for each LOD. Now that we have the Radius that is a simple task.

def area_of_circle(r):
    return math.pi * r * r

The function above returns the area for a given radius.

The next step is "Adjusting for missing LODs", we'll take this into account when we display things. But in terms of the algorithm, if a given LOD is missing then the next highest available LOD is used.

We can now progress to the "Computing Cost" section. This section gives use the following formula.

    Streaming Cost =
        (   (lowest_area / total_area) * bytes_in_lowest
          + (low_area    / total_area) * bytes_in_low
          + (mid_area    / total_area) * bytes_in_mid
          + (high_area   / total_area) * bytes_in_high   ) * cost_scalar

The first part is a ratio, a weighting applied to the LOD based upon the visibility radii.
The second part is more confusing on its own, "bytes_in_LOD" where did that come from?

The answer lies in the note just below the pseudo code.

In the details of the implementation, the cost_scalar is based on a target triangle budget, and efforts are made to convert bytes_in_foo to an estimated triangle count.

So what does that mean exactly? The answer lies in the C++ code below it and, in particular:

F32 bytes_per_triangle = (F32) gSavedSettings.getU32("MeshBytesPerTriangle");

This is a setting stored in the viewer that approximates how many bytes are in a triangle for the purpose of converting "bytes" to triangles. Looking at the current live viewers, we find that the setting has a value of 16.

This value is then used to convert a bytes_LOD value to a triangles_LOD value.

    F32 triangles_high   = llmax((F32) bytes_high-METADATA_DISCOUNT, MINIMUM_SIZE
                            /bytes_per_triangle;

This deducts a METADATA_DISCOUNT constant to remove the "overhead" in each mesh LOD to leave only the real triangle data. The remaining bytes are divided by our bytes_per_triangle to get the number of triangles. This raises the question of whether 16 is the right "estimate" Indeed, why is it an estimate at all? In Blender we won't be estimating, we know how many triangles we have. However, it will turn out that the page is missing one vital piece of information that explains all of this...However, we will come back to this once we have worked out the rest.

Looking in more detail at the implementation we find that lowest area and the related "areas" are not quite what they seem.
In the C++ implementation, we observe that high_area is indeed the area of the circle defined by the roll off point from High to Medium LOD,

F32 high_area   = llmin(F_PI*dmid*dmid, max_area);

but we discover that mid_area is the area of the medium range only, excluding the high_area. The area of the Ring in which the Medium LOD is visible.The same applies to the others.

Putting this all together in python we get the following:-

def getWeights(object):
    (radius, LODSwitchMed, LODSwitchLow, LODSwitchLowest) = getLODRadii(object)

    MaxArea = bpy.context.scene.sl_lod.MaxArea
    MinArea = bpy.context.scene.sl_lod.MinArea

    highArea = clamp(area_of_circle(LODSwitchMed), MinArea, MaxArea)
    midArea = clamp(area_of_circle(LODSwitchLow), MinArea, MaxArea)
    lowArea = clamp(area_of_circle(LODSwitchLowest), MinArea, MaxArea)
    lowestArea = MaxArea

    lowestArea -= lowArea
    lowArea -= midArea
    midArea -= highArea

    highArea = clamp(highArea, MinArea, MaxArea)
    midArea = clamp(midArea, MinArea, MaxArea)
    lowArea = clamp(lowArea, MinArea, MaxArea)
    lowestArea = clamp(lowestArea, MinArea, MaxArea)

    totalArea = highArea + midArea + lowArea + lowestArea

    highAreaRatio = highArea / totalArea
    midAreaRatio = midArea / totalArea
    lowAreaRatio = lowArea / totalArea
    lowestAreaRatio = lowestArea / totalArea
    return (highAreaRatio, midAreaRatio, lowAreaRatio, lowestAreaRatio)

This should give us the weighting of each LOD in the current models at the current scale. So let's add this to our display.

Here we can see that our Medium and Low LODs are carrying a lot of the LI impact and thus if we want to manage the LI we need to pay a lot of attention to these. The more observant will note that the Lowest is effectively 0, and yet we are telling it to use the LOD from the LOW, this makes no sense at first glance, it should be very expensive. The explanation is in the radius column. Lowest does not become active until 261m, which is outside of the 256m maximum  (see maxArea in the code above), this means that the Lowest is clamped to a radius of 256, which matches the radius of the Low and thus results in 0 weight.

With all this in place, we are finally able to have a first run at calculating the streaming cost.
Once again we refer to the C++ implementation for guidance.

    F32 weighted_avg = triangles_high*high_area +
                       triangles_mid*mid_area +
                       triangles_low*low_area +
                       triangles_lowest*lowest_area;
 
    return weighted_avg/gSavedSettings.getU32("MeshTriangleBudget")*15000.f;

 In our python translation this becomes:

        weightedAverage =   hi_tris*highAreaRatio + mid_tris*midAreaRatio + low_tris*lowAreaRatio + lowest_tris*lowestAreaRatio
        streamingCost = weightedAverage/context.scene.sl_lod.MeshTriangleBudget*15000

I am not a fan of the magic numbers used here (MeshTriangleBudget is in fact another viewer setting and has a value of 250000, the 15000 however is a simple hard coded constant so we have little choice but to replicate it.

For our final reveal for tonight then let's see how out LI calculation has performed.

Oh dear...
Well, I guess it had all been too easy so far.
The Firestorm upload has calculated that this object will have a streaming impact of 8LI
Our determination has calculated 13LI. That is a considerable difference, what could possibly have gone wrong?

The answer was hinted at previously; it is to do with the estimate, the bytes_LOD values and what they actually are. The problem lies in the fact that your mesh is not sent back and forth unaltered from the DaE file that you upload. In fact, it is uploaded in an internal format that compresses each LOD model. The bytes_LOD values represent the compressed size of the actual mesh that will be streamed, the estimated bytes_per_triangle of 16 is, it would seem greatly underestimating the compression level.
In my next blog, I will examine the internal format in more detail. We'll explain why the estimated bytes per triangle is wrong, and we will start to work out how we can make this work.

Until then, thank you for reading this blog. Please share or +1 if you have found it useful, or if you think that your friends might.

Love
Beq
x

Mesh accounting mayhem

Mesh accounting - Download/streaming costs

This post is the 4th in this series of posts about Blender Addons for SecondLife creation, and we (finally) get to sink our pythonic fangs into something concrete.

Previously...

Post 1 - We started to put a simple addon together to generate five copies of a selected Mesh and rename them according to their intended use.
Post 2 - We took it a step further by allowing the user to select which LOD to use as the source and which targets to produce.
Post 3 - We wrapped up the process, connecting the execute method of the operator to the new structures maintained from the UI.

So what next?

Tonight we are going to try (or at least start) to replicate the streaming cost calculation of SL in Blender.

A quick recap

For those who have not looked lately and are perhaps a little rusty on Mesh accounting here is the summary.
Firstly, I will use the term Mesh primitive to denote a single mesh object that cannot be decomposed (unlinked) in-world. It is possible to link Mesh Primitives together and to upload a multi-part mesh exported as multiple objects from a tool such as Blender.

The LI (Land Impact) of a Mesh primitive is defined as being the greater of three individual weights.
1) The streaming or download cost
2) The Physics cost
3) The server/script cost

Mathematically speaking if D is Download, P is physics and S is streaming then

LI = round(max(D,P,S)) 

Of these S is simplest and generally speaking least significant. It represented the server side load, things like script usage and essential resources on the server. At the time of upload, this is 0.5 for any given Mesh primitive; this means that the very lowest LI that a Mesh primitive can have is 0.5, and this rounds up to 1 in-world. Because the rounding is calculated for the entire link set,  two Mesh primitives of 0.5 each, can be linked to one another and still be 1LI (in fact three can because 1.5LI gets rounded down!).
Physics cost we will leave to another post,  much misunderstood and often misrepresented, it is an area for future discussion.
And so that leaves Streaming cost,
If you read my PrimPerfect (also here) articles on Mesh building in the past, you will know that the streaming cost is driven by the number of triangles in each LOD and the scale of the object.
LOD, or Level Of Detail, is the term used to describe the use of multiple different models to deal with close up viewing and far away viewing. The idea being that someone looking in your direction from half a region away does not want to download the enormous mesh definition of your beautifully detailed silver cutlery. Instead, objects decay with distance from the viewer. A small item such as a knife or fork will decay to nothing quite quickly, while a larger object such as a building can reasonably be expected to be seen from across the sim. Even with a large building,  the detailing of the windows, that lovely carving on the stone lintel on the front door, and so forth, are not going to be discernable so why pay the cost for them when a simpler model could be used instead? Taking both of these ideas together it is hopefully clear why scale and complexity are both significant factors in the LI calculation.

The highest LOD model is only visible from relatively close up. The Medium LOD from further away, then the low and the lowest. Because the lowest LOD can be seen from anywhere and everywhere the cost of every triangle in it is very high. If you want a highly detailed crystal vase that will be "seen" from the other side of the sim, then you can do so, but you will pay an extremely high price for it.

The way that most of us see the streaming cost is through the upload dialogue. Each LOD model can be loaded or generated from the next higher level. One rule is that each lower LOD level must have the same or fewer triangles than the level above it.

When I am working in Blender, I export my Mesh files, drop into the upload dialogue and see what it would cost me in LI. I then go back and tweak things, etc, etc. Far from the ideal workflow.

One of my primary goals in starting this process was to be able to replicate that stage in Blender itself. It can't be that hard now, can it?

..Sadly, nothing is ever quite as easy as it seems, as we will find out.

To get us started, we need to get a few helper functions in place to get the Blender equivalent functions.

We will need to know the dimensions of the object and the triangle count of each LOD Model.
This is why we wanted a simple way to link models that are related so that we can now do calculations across the set.

def get_radius_of_object(object):
    bb = object.bound_box
    return (Vector(bb[6]) - Vector(bb[0])).length / 2.0

The function above is simple enough, I do not like the magic numbers (0 and 6) and if there is a more semantic way to describe them I would love to hear of it, but they represent two extreme corners of the bounding box and the vector between them is therefore 2* the radius of a sphere that would encompass the object.

def GetTrianglesSingleObject(object):
    mesh = object.data
    tri_count = 0
    for poly in mesh.polygons:
        tris_from_poly = len(poly.vertices) - 2
        if tris_from_poly > 0:
            tri_count += tris_from_poly
    return tri_count

The function here can (as the name suggests) be used to count the triangles in any object,
At first thought, you might think that, with triangles being the base of much modelling, there would be a simple method call that returned the number of triangles, alas no. In Blender, we have triangles, and quads and ngons, A mesh is not normally reduced to triangles until the late stages of modelling (if at all) to maintain edge flow and improve the editing experience. Digital Tutor have an excellent article on why Quads are preferred.

The definitive way to do this is to convert a copy of the mesh into triangles using Blenders triangulate function, but we want this to work in realtime, and the overhead of doing this would be phenomenal. The method I settled on was a mathematical one. The Mesh data structure in Blender maintains a list of polygons. Each Polygon, in turn, has a list of vertices. We can, therefore, iterate over the polygon list and count the number of vertices in each poly. For each polygon, we need to determine the number of triangles it will decompose in to. A three-sided is a single triangle, of course, A four-sided polygon, a quad, decomposes, ideally, into two triangles, a five-sided poly gives us a minimum of three. The pattern is clear. For a polygon with N sides, the optimal number of triangles is N-2. What is less clear to me is whether there are cases that I am ignoring here. There are many types of mesh some more complex than others. If there are cases where certain types of geometry produce no conformant polygons, then this function will not get the correct answer. For now, however, we will be content with it and see how it compares to the Second Life uploader's count.

Armed with these helper functions, and the work we did previously, we can now add the counts that we need to a new Blender UI panel as follows.

So let's see if this compares well with the Second Life Mesh uploader.

Spot on. So far so good. Enough for one night, tomorrow we'll take a deeper dive into the streaming cost calculation.

Beq
x

Snake charming in Blender part 3 -

This blog post is the third in the series of posts on my Blender AddOn adventures.

Previously:-
Post 1 - We started to put a simple addon together to generate five copies of a selected Mesh and rename them according to their intended use.
Post 2 - We took it a step further by allowing the user to select which LOD to use as the source and which targets to produce.

At the end of the last post we had the user interface elements working but they had not be wired up to the addon itself.

The code for this blog has taken a while for me to get to the point where I am properly happy with it as it required a bit more background reading to make the work covered in the last blog initialise itself correctly. This blog post, however, should be quite short and then we will move on to something more interesting.

In the first, naive, version we had a simple function that created 5 duplicate copies of a base object. There are lots of different workflows that can be followed and, for me at least, it varies a little depending on what I am building, where I am starting from etc.  I work on a Mesh I often end up working in two directions. I upload a template made using Mesh Studio in SL, this gives me a proforma with the right scale and a little confidence that it will fit where it needs to. That template can often evolve into the medium LOD, then get duplicated, adding detail and refinement to use as the high LOD model and then removing things from another copy to form the low LOD.

It was also a good chance to refactor the repetitive code from the first version.

The execute method of the operator is now far more generic. I have created support functions for stripping the LOD extension from an object name. This means that I can quickly get from any LOD model to any other by removing the extension and adding another, the upshot of this is that you do not need to be looking at the HIGH LOD model in order to generate another clone from it.

def execute(self, context):
# For every selected object
        for object in context.selected_objects:        
            basename = self.getSLBaseName(object.name)  
# strip the _LOD if any to find the "root" name
            source = self.findOrCreateSourceModel(basename, context)
# locate the source LOD Model if it exists, if not create it using the selected mesh
            if(source is not None):
                for i in context.scene.sl_lod.LOD_model_target:
                    # For every target LOD clone the src and relocate it to the correct layer
                    targetModel=self.createNewLODModel(source, self.getLODAsString(i))
                    self.moveToLayers(targetModel, {int(i)})                    
        return {"FINISHED"}

That's all for this blog, it was wrapping up a few loose ends, though the brevity of the blog does not reflect the pain of learning how to get properties to register properly in Blender.

Meshing about in Blender with Python

Part 2 of my adventures in Blender add-on land

A short one tonight as I've been busy with RL annoyances.

In the last post on my Blender Journey when I stopped I had built my first ever Blender add-on, taught it to iterate through a list of selected items and for each one create duplicates that we can then mangle into lower LOD models.

At the moment the results of running it are as follows:-

In this example the High LOD model is shown first (it is two separate objects), the "Make LOD models from selection" button has been clicked, and the associated operator (blender term for function) has been executed. The result as shown is that the first five layers are populated. Layer zero (top left) has the original model, which we are treating as the High LOD. Next to this are layers one and two which contain lower detail models for Medium and Low. In this example, I had already made the models and by naming them appropriately, I allowed the script to find them and move them to the correct layer and not have it generate ones I did not need. Layer three contains a copy of the original renamed to Original_LOWEST and finally layer four includes another copy Original_PHYS. 

This immediately raises a few points. If I have a model for LOW then perhaps I should derive LOWEST and PHYS from that one. Perhaps I do not want a physics model at all.

Also, while my workflow would normally be to start with the High and work down there is often a good case for starting with the Medium and establishing the basic shape before adding smaller details to the High model. So maybe I should allow this too.

The image below is a quick mockup (from Gliffy) of how it could look

Each LOD/model has a row with a set of radio buttons to determine which LOD the selected object(s) should be treated as, and a set of tick boxes for the ones we want to be generated/found and moved. In this example the selected objects would be renamed with an _MED suffix. A copy would be made and any suffix removed, another copy with the _LOW suffix would be made. 

Having thought about the inheriting of LOD models I think it makes the most sense to do this automatically, so I will update the code to derive LOW from MED, LOWEST from LOW. This automatically means that models will inherit from pre-existing LOD models.

Updating the panel

It looks as if my visualisation was somewhat fanciful as Blender does not easily support radio buttons as a set (know better? Please tell me). It does, however, have an enumeration property type and this gives us a similar functionality.

Adding a properties class is a bit fiddly, or at least it seemed so. The result is quite simple, but the journey to getting there took me on more messy routes.
Here, however, is the final UI, which allows me to specify the source model and the targets to create from it.

import bpy

class LODModelProperties(bpy.types.PropertyGroup):
# This is how you make a static enum prop for the scene
    enum_items = (('0','High',''),('1','Medium',''), ('2','Low',''), ('3','Lowest',''), ('4','Physics',''))
    LOD_model_source = bpy.props.EnumProperty(items = enum_items)
    LOD_model_target = bpy.props.EnumProperty(
            name = "LOD Models required",
            description = "LOD Models to be generated",
            items = enum_items,
            options = {"ENUM_FLAG"}
        )    
        
bpy.utils.register_class(LODModelProperties)    

bpy.types.Scene.sl_lod = bpy.props.PointerProperty(type=LODModelProperties)

class CreateLODModelsPanel(bpy.types.Panel):
    bl_idname = "create_lod_models_panel"
    bl_label = "Create Lod Models Panel"
    bl_space_type = "VIEW_3D"
    bl_region_type = "TOOLS"
    bl_category = "SecondLife"
   
    def draw(self, context):
        layout = self.layout
        layout.operator("my_operator.make_lodmodels_from_selection")
        layout.label("Use selected model as...")
        layout.prop(bpy.context.scene.sl_lod, 'LOD_model_source', expand=True)
        layout.label("Create LOD (shift click multi)")
        layout.prop(bpy.context.scene.sl_lod, 'LOD_model_target', expand=True)

Right now, however, there is no linkage between them. In an ideal world, the target models would automatically exclude the source LOD selected.

We can achieve this using the get/set methods. It took me quite a while to figure this out.
It appears that the property itself is read only. You cannot apply a remove('1') to the set that represents that LODS to generate for example.
The solution is to maintain a parallel data value as a map entry on the property class.

def getter(self):
    return self['value']
    
def setter(self, value):
    if (value & self['src_value']):
        value ^= self['src_value']
    self['value'] = value
    

def source_getter(self):
    return self['src_value']
    
def source_setter(self, value):
    self['src_value'] = value
    if (value & self['src_value']):
        self['value'] ^= value

Now when we select a value in the source radio control, it is automatically removed from the target set if it is set, likewise trying to set it in the target will fail if it corresponds to the source.

That's it for tonight.
Next step is to use out new properties to control the generation because at the moment it still generates all 5 models.