Wednesday, February 12, 2014

Copy Shape & Paste Shape scripts

Hello and welcome to the tutorial for the new "Copy Shape" and "Paste Shape" scripts provided with the update to the RealRestraint products.

Whenever a full update occurs in the RealRestraint brand, you are tempted to update of course, since you want to enjoy the latest bug fixes and features, but you also dread having to resize all your items again. Especially ropes, which are the hardest products to resize. And the more different your shape is from mine, the more difficult ! Some people need hours to resize their products, others give up after hours, but nobody wants to do it every time there is a new update, right ? I know, and I apologize for all the hours of frustration I must have given you. No really, I do !

This is where those two scripts are coming handy, and they are a project I should have worked on much sooner. Problem is, they were not at all easy to make and test and I had to really hone my skills on other projects first before considering this one.

So, what is it all about anyway ? Why two scripts and not an object ? Why can't an item be resized automatically to your shape ?

First of all, it is impossible to have an object to fit your shape automatically if it is made of prims or sculpts, and only a deformed mesh MIGHT fit you well enough (see the FittedMesh project from Linden Lab, which is coming to the grid soon at the time of this writing). And most of my products are either made of prims, sculpts, static mesh or a mix of those. A script cannot get any information about your shape except your overall size (shoes included), so it can't adapt to the thickness of your arms, or the size of your waist, or the length of your legs, and whatever part of your body. That's why you always have to do it manually.

But if you have already resized your items to your shape once, these two scripts will help you save time by copying the shape of the old item to the shape of the new one, as the name implies.

In short, here is how it works on an item :

- You rez both items on the ground, or you wear them both at the same time (provided your viewer is able to make you attach two objects on the same attachment point, but most viewers do nowadays).

- You put the "Copy Shape" script inside the old item, the one that is resized correctly but does not contain the latest scripts. That script will stop the other existing scripts so they won't get in the way.

- You put the "Paste Shape" script inside the new item, the one that is not resized correctly yet but has the up-to-date scripts in it. It will stop all those scripts as well during the time of the procedure.

- As soon as both scripts are set (the order does not matter), you will see the new item be moved, rotated and scaled to match the position of the old one, and all its prims will turn green. Or in some cases, almost all its prims.

- Normally, for 99% of the people, the procedure should be over and you should see the new object turn completely green because all its prims would match the prims composing the old one. But if you have tweaked some prims individually on the old object (builders and perfectionists tend to do that, and I wouldn't blame them !), then those prims would stick out because their shapes and positions would not match those of their counterparts in the new object. So what to do ? Well those prims are marked in red in the old object, and not tinted in the new object, while all the other prims are invisible in the old object, and transparent green in the new one. So the unruly prims are easy to spot.

- In the case of prims sticking out in red and white, all you need to do is to click on one of them, then on its counterpart in the other object (the order doesn't matter), and the new one will match the old one and turn green (while the old prim turns invisible). Repeat these steps for all the remaining prims until your whole object is green.

- If you make a mistake, you can either press "Undo" to undo the last step (you can undo several steps, back to the beginning) or "Undo all" to go back to the original state when both objects were merely positioned together.

- Once done, press "DONE" and both scripts will be deleted from the objects, and the objects will be made operational again.

Now, you might be asking yourself an important question :

Why can't the scripts resize all the prims one by one instead of asking you to point the rogue prims by hand ?

Short answer : Because the scripts have no way to tell which prim is the counterpart of which prim in the other object if those prims are not already positioned identically.

Long answer : This is because technically, each prim is a number in the script's standpoint, and it is hard to decide the order of the prims when you modifiy an object physically. There is no guarantee that I won't unlink an item, add or modify a prim then re-link it and that the order will stay the same. In fact, it most certainly won't. So you can have two seemingly identical objects with prims ordered differently, and the scripts would screw up if they relied on the number of each prim to match the positions. You'd end up with a mess if they did.

Worse, a lot of my scripts rely on the name and description of each prim in order to decide what to do with it (usually to change its visibility but also its texture, its color...). Once again there is no guarantee that all the prims will keep their names and descriptions through an update. In fact, most updates require me to modify such information, this is the point of an update. So the script cannot rely on the names of the prims either.

Each prim has its own unique identifier ("UUID" for short, for "Universal Unique IDentifier"), and it changes every time it rezzes. That UUID is a set of 32 hexadecimal characters and is random. So two identical objects will have two completely different UUIDs, and all the prims composing those objects will also have different UUIDs. And there is no way (by design) to predict what those UUIDs will be set to.

Prims have shapes, too. Some are cubes, some spheres, some are torii, some are sculpts, some are mesh... But there is no guarantee that each shape is unique. And even if it were, a script cannot find the exact shape of a complex prim such as a sculpt or a mesh. It is simply not given that information, because it is supposed to be secret.

Finally, each prim has a texture, tint and glossiness, but there is no guarantee that they will stay the same between two versions. There is no guarantee they will stay the same through the use of the product anyway, since most of them provide you ways to change the textures and tints.

So, to recap : the scripts can't rely on the order of the prims, on their names, on their descriptions or on their UUIDs. Neither can they rely on their colors, textures, glossiness, topology etc. They can't rely on anything except their positioning. But in the case of prims that have been resized individually, there is no possible match anymore. That's why they need you to indicate which prim is the counterpart of which prim in the other object.


Now that you have the theory covered, let's show you a practical use on the Light Harness of the Siren Ropes. That item is particularly tricky to resize manually, I'm told.

First, I rez the old harness on the ground. This harness is resized correctly but does not contain the latest scripts, and that's why I need to update.

Next, I rez the new harness that I got from the new box, next to it. As you can see, that new harness is bigger (let's say I'm small so I had to shrink the old harness), and some prims are badly out of shape (bear with me, this is for the sake of the demonstration). I have made these prims bright on the picture so you can see them well. There are 3 of them and you can see how much work would be required to match them with their old counterparts manually.

I have the two scripts in my inventory, one is called "Copy Shape" and the other "Paste Shape". I drag and drop the former into the old object to the left, and the latter into the new object to the right. Once done...

As you can see, both harnesses are now matching almost exactly. But the 3 prims that were out of shape are still out of shape, and their counterparts are red. This is because the scripts could not match them and this is what I'm going to do now, by clicking on each prim then its counterpart, and watching them be positioned correctly as I go along :

I've been deliberately slow on this video, to take the time to show you, but you can click much faster than this.

Now, you can see that the harnesses are now identical, there is no prim sticking out, everything is just as it was before !

The scripts are able to go back and undo some steps you took. They can even go back to the beginning. I click on "Undo all" and I'm back to step one.

Now, suppose I make a mistake (I make mistakes all the time) and match two prims that shouldn't be matched. As you've read above, the scripts match those two and turns the new one green because it has no way to know those two mesh prims have different shapes. Sure, they look different to you, but to the scripts they are just a bunch of numbers and the information does not go down to the vertex level. So the scripts happily match those two prims and I'm left with a mess. This is where the "Undo" and "Undo all" buttons come in handy :

Once I'm satisfied with the result (the new object is fully green and the old one is fully invisible), I can click on "DONE".

Doing this removes both "Copy Shape" from the old object and "Paste Shape" from the new one, restores the original scripts, the color and the transparency.

And now I have two identical objects !

As you can see, it makes it much easier, therefore much less daunting, to update your products.

Have fun !


PS : I must add a little disclaimer here. Although those scripts are made for RealRestraint products, they can actually work on any object that is modifiable, regardless of who created it in the first place. You do this at your own risk, though, I can't take responsibility to any damage done to your object since I can't predict how it would react when receiving these scripts. Copy Shape and Paste Shape merely turn the other scripts on and off, they don't delete any item but themselves. However, they do rely on a special message to the main script in order to update the transparency once done, and other objects would not react to this message, so it is very possible that the object will stay fully opaque after the scripts are removed.

The scripts are Copy and Transfer, but I do not grant the right to use them commercially. You can use them on your own objects for your personal use, but please don't include them in your own brand if you own one. And if you really want to distribute them in your own brand as a way to update or otherwise, please have the courtesy to ask me first. Thank you.