
`youtube:mVnml1j_XlM`

Text components and screen text are well known features of Lens Studio. The text texture, however, is lesser known but is a super powerful feature. With the text texture, you can add dynamic text directly to the surface of a 3D object and this tutorial will show you how. You can see an example of this by [clicking here](https://www.snapchat.com/unlock/?type=SNAPCODE&uuid=7a5cfc849edd49e3ba43d099b44746dc&metadata=01) or by scanning the snapcode below.

![Snapcode for lens with 3D text](/images/tutorials/snapchat-advanced/text-texture/snapcode.png)

## Prepare your 3D object

The text texture in Lens Studio is treated as an image texture, and in order to place it onto a 3D object, we need to make sure the UV map is setup for that. I personally use Blender, but feel free to use whatever software you wish.

- Select the faces on your object where you would like the text texture to be placed
- Give these faces a new material
- Create a second UV map for your object
- With just these faces selected, UV unwrap your object onto the new UV map
- Scale the faces in the UV map as desired
- Export your object and import into Lens Studio

![Setting up the second UV map to receive the text texture](/images/tutorials/snapchat-advanced/text-texture/uv-setup.jpg)

## Apply the text texture to your object

Heading into Lens Studio, create a Text Texture if you haven't already (in the Resources Panel) and give it some sample text. You also need to make sure your text material is setup. It can be as simple as an Unlit material, or it can be a custom material made with the Material Editor. Assign the material texture to the text texture and then select your model, find the material to be replaced, and replace it with your new material.

![Simple graph material for the text texture](/images/tutorials/snapchat-advanced/text-texture/simple-material-setup.jpg)

At this point you should see something changed on your 3D model, but we aren't quite finished yet. Currently the text texture material is using the original UV map of the object and so it won't look right. We need to switch that to the second UV map we created. If you are using the material editor you'll need to swap out the "Surface UV Coord 0" for "Surface UV Coord 1," and if you are using a non-graph material you'll need to set the texture UV to "Mesh UV 1." Now you'll be able to see your text, but there'll be empty space around the words. Let's fix that. With the 3D object selected, add another material slot and select the regular material for the object. Then click on the three small dots to the left of the material name and drag it above the text material. Provided your text is a different color than the background behind it, you should now see your text.

![Adding both materials to the 3D object](/images/tutorials/snapchat-advanced/text-texture/material-ordering.jpg)

The last issue you might notice is the text and the base material are clashing with each other and flickering over the top of each other. To solve that issue, select your text material and disable "Depth Test" in the Inspector Panel. Now you are good to go!

![Disabling Depth Test for the material](/images/tutorials/snapchat-advanced/text-texture/depth-test.jpg)

## Text texture caveats

There are a few things to keep in mind with the text texture. First, the "Outline" and "Drop Shadow" features of the text do not work. Second, the text is stretched to fit the bounds of the UV map you defined in your 3D software. This is usually only noticeable for really short or really long strings of text. You can compensate for this by scaling the UV and then clamping it to get rid of the tiling, but this will cause banding with some letters (especially common with the letter "y" in my testing). Depending on your font, this approach may or may not work. If it does work for you, you can write a script to adjust the X and/or Y UV scaling based on the length of the text. For a slightly more in depth view of the material setup for that, watch the video version of this tutorial on YouTube.

## Making it dynamic

If we wanted some set text on the model, it would be immensely easier to set it up with the original texture for the material. The real power of the text texture is our ability to modify it via a script. This is super simple, just import the text texture as a texture asset and set the right property. With normal text components and screen text you directly set the "text" property, but with the text texture you do it through "control.text" instead. The below code snippet sets the text texture to the user's Display Name.

```javascript
// @input Asset.Texture mainText

global.userContextSystem.requestDisplayName(function (displayName) {
  script.mainText.control.text = displayName.toUpperCase();

  // Uncomment the below line when creating the preview
  // so it doesn't get flagged for having the word "Snap"
  // in it. Then comment this line again when you submit.
  // script.mainText.control.text = "YOUR NAME HERE";
});
```

## Further reading

- [Material Editor](https://lensstudio.snapchat.com/templates/world/material-editor/)
- [Materials](https://lensstudio.snapchat.com/guides/3d/materials/)
- [User Context System](https://lensstudio.snapchat.com/api/classes/UserContextSystem/)


Text components and screen text are well known features of Lens Studio. The text texture, however, is lesser known but is a super powerful feature. With the text texture, you can add dynamic text directly to the surface of a 3D object.

Add dynamic text directly to 3D objects in Lens Studio


`youtube:6eIlx8EAxwY`

Chain, or swing, physics can breathe a lot of life into your creations. With the proper setup, chain physics automatically adds swinging motion to elements of your lens. This can remove rigidity from objects in your scene and give everything a more organic feel. In this Lens Studio tutorial we will go over everything you need to know to add chain physics to your own lenses. You can see an example of this by [clicking here](https://www.snapchat.com/unlock/?type=SNAPCODE&uuid=87fb00b83f5c4d85a691ee5a2bbe4e79&metadata=01) or by scanning the snapcode below.

![Snapcode for lens with 3D text](/images/tutorials/snapchat-advanced/chain-physics/snapcode.png)

## What are chain physics?

Chain physics (also sometimes referred to as swing physics) is the type of motion that comes from swinging something (like a chain). The reason a hair flip works is because when you stop swinging your head, your hair keeps going and will (ideally) get out of your face. Other examples are earrings swaying from your ears or flowers swaying on your head. Chain physics is a great way to add some organic motion to your lenses.

## Get the scripts

Luckily for us we don't need to write any code ourselves. The Lens Studio team has done all the hard work and they even [provide a template](https://lensstudio.snapchat.com/templates/face/chain-physics/) directly within Lens Studio. We could always open up the template and work from there, but maybe you have an existing project and want to add chain physics to that. Not to worry, it is a straightforward task to get what we need out of the template.

Open up Lens Studio and open up the Chain Physics template. If you are on the home screen you can select "Templates" over on the left-hand side and search for it. If you already have a project open you can go to `File -> New Project from Template -> All -> Chain Physics`. A sample project with some earrings and a flower on the user's forehead will open up. You can of course add your own resources to this template and go from there, but let's go over how to export the chain physics scripts in case you need to add this ability to an existing project.

The chain physics are controlled by three different scripts.

- JSMathLibrary
- ChainController
- PositionBasedDynamicsHelper

![Script setup in the Lens Studio Chain Physics template](/images/tutorials/snapchat-advanced/chain-physics/template-scripts.jpg)

You can find all three scripts in the "Scripts" folder in the Resources Panel. If we take a look at the Objects Panel, we'll see a "Helper Scripts" object that contains the JSMathLibrary and PositionBasedDynamicsHelper. We don't need to mess with those scripts at all, we just need to make sure they are present in our scene. If you select one of the groupings of objects (Leaf Earring Chain L, for example), you'll see in the Inspector Panel that this is where we place the ChainController script and configure the chain physics. Don't remove any of the joints, but feel free to play around with some of the other settings to see how things work. Once you are ready, right-click each script in the Resources Panel and choose the Export option. You can import these scripts into any project, so save them somewhere useful where you will remember where they are.

## Prepare your 3D model

For the chain physics scripts to work, we need a rigged 3D model. Now this is a Lens Studio tutorial, not a 3D software tutorial, so if you unfamiliar with rigging 3D objects, you will have to look that up on your own. That being said, I'll still be going over everything at a high level (my 3D software of choice is Blender, but feel free to use whatever you wish).

The length of the chain (number of joints) can be as short or long as you wish. For this example I am going to be applying the chain physics to a simple worm model I made (marvel at my skill). For my particular model, I have four bones directed upwards and nine bones directed downwards. The bottom bones will be trailing below where I eventually put the user's face and the top bones will be controlling the motion above the face. When parenting my model to the rig I just used an automatic weight calculation (the weight is how much each portion of the model will be controlled by each bone). You don't need all the bones in your rig to be connected in a line. Each portion that you want to wiggle can have its own set of bones. For my worm model the top and bottom portions are going to be controlled separately, they just so happen to still be connected. Once your model is rigged and ready to go, export it and then import it into Lens Studio.

![Rig and bone setup for chain physics inside of Blender](/images/tutorials/snapchat-advanced/chain-physics/bone-setup.jpg)

## Adding the scripts

So I have my 3D model attached to a head binding, and now I want to add some motion. Make sure you've already imported the three chain physics scripts that you exported from the template, add a Scene Object in the Objects Panel, drag it to the top if the object hierarchy, and then add the JSMathLibrary and PositionBasedDynamicsHelper scripts to it. You can also rename it (this is the equivalent of the Helper Scripts object from the template). Now add the ChainController script to your scene. I placed mine on the worm model I imported. We are almost ready to add the joints, but if you look in the Logger you'll see there is an error. Go to the JSMathLibrary script component (what you added to the Objects Panel, not the actual script file in the Resources Panel), check the "Settings" box, and then select "vec3" and "quat." That should prevent the error from popping back up again.

![Setting up the scripts for chain physics](/images/tutorials/snapchat-advanced/chain-physics/helper-script-setup.jpg)

## Add the physics

I'm going to start with the four top bones. If I go back to the ChainController script component that I added to my 3D model, there is an input called "Joints, values" with an "+ Add Value" button. I'm going to click that button, click inside the "Value 0" box that appears, and then select all the bones I want to participate in my first chain. You can hold down shift/ctrl to select multiple values, but the last value selected will end up first in the chain, so delete that input and then re-add it to the end of the list. Now that I've selected some joints, the top part of my worm is now hanging down inside the rest of the body. What I need to do now is adjust the Force input on the script. Right now for the "Y" value it is set to -1, so let's change that to 0.1 to give it a slight, upward lift. Now I can see the first chain bouncing around! Once I've adjusted the parameters to my liking, I do the same for the bottom chain. Here's an overview of the different parameters and what they do.

### Stiffness

The stiffness parameter behaves much as you would expect it to. A low stiffness allows the joints to move around more freely, while a high stiffness restricts their motion a bit more.

### Type

Here you can choose between `Rigid` and `Elastic`. If you select rigid, the spacing between the joints will remain constant, although with a low stiffness value you will still get some stretching. If you select elastic, the spacing between joints is more free to move and stretch.

### Iterations

According to the official Lens Studio documentation for the template, the iterations parameter will control how quickly the joints return to their resting state. In practice I don't see huge differences when this parameter is changed unless I have elastic selected for the motion type. A higher iteration counts means more calculations need to be run, so I typically just keep this value at one.

### Time Speed

This parameter is one of the more important ones. A low value means the joints will be moving around more before they come to rest, while a high value will move the joints to their resting state much faster. It is almost like controlling the stiffness; a high value will keep things more aligned while a low value will do the opposite.

### Force

Force is another important parameter. If there is no force applied, then the joints will continue to swing around for a long, long time. Too high of a force can stretch things out, so depending on how you want your motion to look, a value of 0.1 (or -0.1 depending on the direction you want things to go) will usually be a good starting point.

### Is Relative

This parameter will let you align the physics with another object. Let's use my worm as an example. If I have my Y-force set to 0.1, the head of the worm will always end up straight up and down after it stops moving. If I check the "Is Relative" box and then select my head binding, it will point up relative to my head. Unchecked the worm's head will point up to the top of the phone screen, and if I tilt my head, it will still point up to the top of the phone screen. If this option is checked then the worm's head will always point the direction my head is facing, even if I tilt my head. Play around with it a bit to get a feel for how this works.

### Add Rotation

When this option is not enabled, the motion from the chain physics tends to be side-to-side and up-and-down. If you enable this option, then you will start to get some outward-and-back motion as well. I like to have this option enabled with 3D objects.

## Add the face

If you were simply adding chain physics to some sort of element in the scene, you would probably be good to go at this point. However, since I want to turn the user into this worm, I still have a few steps left. I'm going to start by adding the user's eyes and mouth to the worm. This is easy enough with a few Face Insets. Just add a mouth, left eye, right eye, then position them, and voila!

## Add the background

For my background, I am going to do the following:

- Create a new Render Target and name it "Background"
- Add a Screen Image (which will also create an Orthographic Camera)
- Change the render target on the Orthographic Camera to the new Background render target
- Set the Texture on the Screen Image to my image of choice and set the Stretch Mode to "Fill" (so it looks good on Snap Camera too)
- In the Scene Config drag the Orthographic Camera and Background render target above the original camera and Render Target (make sure the background is rendered first)
- Select the original camera, change the "Clear Color Option" to Texture, and then for the Input select the Background render target

## Further reading

- [Chain Physics Template](https://lensstudio.snapchat.com/templates/face/chain-physics/)
- [Face Inset](https://lensstudio.snapchat.com/guides/face/face-effects/face-inset/)
- [Cameras and Render Targets](https://lensstudio.snapchat.com/guides/general/camera/)
- [3D Object Import](https://lensstudio.snapchat.com/guides/3d/3d-object-import/)


Chain, or swing, physics can breathe a lot of life into your creations. With the proper setup, chain physics automatically adds swinging motion to elements of your lens. This can remove rigidity from objects in your scene and give everything a more organic feel.

Make things flop around with chain/swing physics in Lens Studio


`youtube:qEK1Ksz0-PE`

## The scenario

Let's say you are making a lens where you want to apply a post effect to the user but not to the background. For example, maybe you want the user to be in black and white but keep the background in color. This is pretty straightforward to do using a segmentation texture as a mask.

But now let's say you have some 3D accessory you want to add to the user such as glasses or a hat that extend past the outline of the person. Lens Studio doesn't create masks for 3D objects, so how do you selectively apply your post effect to both the person and the object? The solution is to create our own mask for the 3D object.

![An example 3D object which extends past the outline of the user](/images/tutorials/snapchat-advanced/selective-post-effect/scenario.jpg)

## The approach

So how do we create a mask for our 3D object? At a high level, we are going to basically make a green screen for our 3D object, use that to create a mask, and then layer everything together. It is not horribly complicated, but there are lots of little details we need to keep track of. Let's get started!

## Create the green screen

To create a mask for our 3D object, we are going to create a green screen. The exact color we use doesn't matter, so if you have a green object you can use a different color. Start by creating a new Render Target and name it "Chroma Key" or something to your liking. Now create a new camera and also name it accordingly. Set the render target of the camera to the chroma key render target and set the camera to a new layer. Next go to your Scene Config and set the Live Target to the chroma key render target.

![Setting up the chroma key camera](/images/tutorials/snapchat-advanced/selective-post-effect/chroma-cam-setup.jpg)

Next we are going to add our 3D model to the chroma key cam. For this tutorial I am going to use the "Birthday Hat" in the Asset Library, but you can use whichever model you wish. After importing your model, be sure to place it under the chroma key camera and change the layer of all your objects to be that same layer. Since this is a hat I also added a head binding.

![Adding your 3D model to the scene and placing it under the correct camera and on the correct layer](/images/tutorials/snapchat-advanced/selective-post-effect/adding-3d-model.jpg)

Now that we have our object in the scene, select the chroma key camera, change the Clear Color Option to "Color," and choose a color that is not present in your object. I chose RGB values of 0, 255, and 0 for a pure green. It's not required, but I also changed the alpha value to 255 to make sure the little color picker icon shows the color I picked in the Inspector Panel. At this point you should see your object against a solid background.

## Creating the mask

Now that we have our object against a plain background, let's turn that into a mask. Create a new render target for the mask, create a new orthographic camera with its own layer, then set it to the mask render target. Next update the Live Target in the Scene Config to the mask render target.

To create the mask for our 3D object, we are going to just check what the color is. If it is green (or whichever color you chose) we'll set the color to black, otherwise it will be white. Let's get started by creating a "Graph Empty" material and naming it "object mask" or something. I like to have a preview of what I'm doing, so before I edit the material I am going to create a new screen image in the mask cam (set it to the correct layer), set it to "stretch," then set the image material to my object mask material. At this point the preview panel should go all white, so let's open up the graph editor and get started on our material.

The first thing we need to add is a "Texture 2D Parameter" node. Connect that to the Color input on the Shader node and select the chroma key render target as the input texture. The preview panel should now show you your object against the solid color background.

![Setting up our object masking material](/images/tutorials/snapchat-advanced/selective-post-effect/starting-the-material.jpg)

Now we are going to check what the color is in our image. Add an "Is Equal" node and an "If/Else" node. Connect the texture node to the top input of the Is Equal, the output of the Is Equal to the Condition input of the If/Else, then the output of the If/Else to the Shader. The preview panel will probably go all black, but that's okay, we can fix that.

On the Is Equal node select the same color that you used for your chroma key on the "B" input. Then select the If/Else node, change the channels to "rgb," and change the color on the "else" portion to white. Now you have a mask for your object!

![Our finished object mask material](/images/tutorials/snapchat-advanced/selective-post-effect/creating-the-object-mask.jpg)

We have our object mask, now we just need to combine it with our person segmentation. Add a new screen image to the mask camera and set the texture to the Portrait Background segmentation texture (or segmentation texture of your choosing). You might need to invert the mask so that the background is black and the user is in white. But now we have a problem, we lost our object mask! No worries, select the screen image with the user segmentation and change the Blend Mode to "Add." Now you have a mask with both the person and your 3D object!

## Adding the post effect

Now change your Live Target back to the original Render Target. You should now just see a plain camera view. Select the original camera (the one with the blue dot), and for the layers go ahead and add the chroma key layer; make sure you keep the Default layer enabled. You should now see the hat on top of your user! This is a little tricky, so let's go over it real quick. An object can be present on just one layer. However, a camera can render objects from multiple layers. We have our 3D object on the chroma key layer to setup our mask, but now with the original camera we can include that object without including the solid background. Pretty neat.

Now we can add a post effect. For the sake of the tutorial I am going to add the "Rainbow" color correction so that there is a clear distinction between what does and does not have the post effect applied. But wait, we can see our post effect applied but the hat still looks normal! What is going on? Right now in my scene the chroma cam with my hat comes after the original camera. So the original camera is applying the post effect, and then the hat is being added. All I need to do is drag my chroma cam to above the original camera so that the hat can be rendered to the screen before the post effect is applied.

## Use the mask

We could at this point use our mask render target as the camera mask on the original camera. That works for creating this effect, but if you want to also apply a post effect to the background then it gets a little tricky. Let's go over another way to use our mask.

Create a new render target named "comp" for composite or something similar and set that as the Live and Capture targets in your Scene Config. If you add a new Screen Image to your scene, it should also create a new Orthographic Camera. Select your camera and make sure its render target is set to comp. I named my screen image "background" and then I duplicated it and named the copy "foreground." For the background I set the texture to the Device Camera Texture, but if you are wanting to have a separate post effect on the background you can setup a new camera/render target/layer and use that resulting output for the texture here.

For the foreground image we are going to create a new "Uber Unlit" material, set the base texture to the original Render Target, set the Opacity Texture to the mask render target, then set the blend mode to "Normal." Our effect is now finished!

## Further reading

- [Camera, Render Targets, & Layers](https://lensstudio.snapchat.com/guides/general/camera/)
- [3D Object Import](https://lensstudio.snapchat.com/guides/3d/3d-object-import/)


Learn how to add a post effect to a user and a 3D object together without affecting the background! This Lens Studio tutorial will teach you everything you need to know to create some pretty awesome effects.

Selectively apply post effects to a 3D object


`youtube:3ewwVAExoO0`

Sometimes you need to know what color something is, whether it is the user's skin tone or some area of the screen. The Procedural Texture Provider in Lens Studio gives us access to pixel-by-pixel color information. You can see an example of this by [clicking here](https://www.snapchat.com/unlock/?type=SNAPCODE&uuid=6eadcd01503341e88c7e710eea02095c&metadata=01) or by scanning the snapcode below.

![Snapcode for lens that samples colors with the Procedural Texture Provider](/images/tutorials/snapchat-advanced/color-sample/snapcode.png)

## The procedural texture provider

Lens Studio has this really nifty feature called the Procedural Texture (let's call it "PT" from here on out). The PT is super cool because you can actually read and write pixel specific information. I don't think the PTs are efficient enough to be doing crazy effects with them (I may be wrong, I haven't tried it), but we can use PT to sample colors in specific regions. This means we can create color palettes from images or sample skin tones.

To sample skin tones, we are first going to create a script using a PT to visualize where we are sampling colors from and then create a second script to actually do the sampling. Please note that we are going to be spending quite a bit of time writing JavaScript in this tutorial.

## Visualizing the sampling

Let's start by setting up our sampling visualization. Add a Screen Image to your scene and set the texture as a Face Crop Texture. Select the Face Crop Texture and change the Scale to something like 0.5 x 0.5 so we have a nice, zoomed-in look. None of this is required for the final lens, we are just going to use this to figure out our sampling areas.

Now create a new script and name it "mapper" then add it to your scene. Change the dropdown that says "Initialized" to "Frame Updated" so that the script runs on each frame. Then, copy and paste the following code and save your script. Let's go over what everything is doing.

```javascript
// -----JS CODE-----
// @input Asset.Texture tex
// @input Component.Image image
// @input int sampleSize
// @input float x {"widget":"slider", "min":0, "max":1, "step":0.01}
// @input float y {"widget":"slider", "min":0, "max":1, "step":0.01}

var channels = 4;

function fillBlack(size) {
  var data = new Uint8Array(size * size * channels);
  for (var i = 0; i < data.length; i += 4) {
    data[i] = 0;
    data[i + 1] = 0;
    data[i + 2] = 0;
    data[i + 3] = 255;
  }
  return data;
}

function percentToPixel(p, l) {
  return Math.floor(p * l);
}

var procTex = ProceduralTextureProvider.createFromTexture(script.tex);

var x = percentToPixel(script.x, script.tex.getWidth());
var y = percentToPixel(script.y, script.tex.getHeight());

var data = fillBlack(script.sampleSize);

procTex.control.setPixels(x, y, script.sampleSize, script.sampleSize, data);
script.image.mainPass.baseTex = procTex;
```

We start off by exposing a few parameters to select as script inputs. The texture asset will be the texture we are sampling pixels from and the image component will be where we are displaying our texture. The sample size input will be the width and height (in pixels) of our sampling area and the x and y inputs are the sampling coordinates (in percent) of where to sample. Select the face crop texture for the "tex" input, the screen image for the "image" input, then set the sample size to something like 10. You should now see a black box in the lower left-hand corner of the face crop image.

![Running our procedural texture mapping script](/images/tutorials/snapchat-advanced/color-sample/mapper-script.jpg)

So how does this all work? Let's skip over the functions for now (we'll come back to them) and start at the line that starts with "var procTex." Here we use the `ProceduralTextureProvider` to create a new PT from our input texture.

Next up we are taking our x & y inputs and passing them into the `percentToPixel` function. Our input x and y are on a 0-1 scale, but the PT needs an actual pixel value. This function just multiplies our input percentage by the width or height of the PT.

Next up we are using the function `fillBlack` to set our data variable. Let's take a look at this function. We start off by creating a Uint8Array. A Uint8Array is a list of 8-bit unsigned integers. That's computer talk for a list of numbers that can go from 0-255 which is the same range as RGB pixel values (this is to save on the amount of memory needed to store the data). The size of this array is our sample size squared multiplied by the number of channels (4 in this case for RGBA). Let's take a quick breather to make sure we understand what is going on. Images are basically three dimensional sets of data. There is a width and height (two dimensions), but then at each pixel we have values for the red, green, blue, and alpha channels (the third dimension). The procedural texture provider only works in one dimension though, so this Uint8Array is what we need to use. We multiply the width times the height times the channels to get the total size of the array. In our case the width equals the height because we chose to sample a square area of pixels.

Next we are looping through our Uint8Array, but you'll notice we are skipping ahead 4 places at a time. That is because every four positions represents a single pixel. We set the red, green, and blue channels to 0 (to create the color black) and set the alpha channel to 255 (so the pixel is visible). Then we return the data array. All this function does is create a list of data points which are understood by the procedural texture provider to be a black square.

Now if we jump back to the rest of our code, we can see that we take our black pixel data and pass it to the `setPixels` function on our PT. We specify the x & y positions, how far to go in each direction, and the data we want to be used. In other words, we are taking our square of black pixels and sticking them in our texture. The last step is to set our procedural texture to the base texture of the image so that we can see it. If you play around with the X & Y sliders on the script, you'll see the square move around. If you set the values too high, the black square will disappear because it is trying to write pixel values that are outside the bounds of the image.

## Doing the sampling

The code we just wrote shows us how to select a position on a texture, but it doesn't actually sample the colors. Let's now create a new script to do the sampling. Once you've created your script, add it to the scene and set it to "Frame Updated" just like the mapping script.

For our script inputs, we need to input a texture to sample from, and let's add an image component too so that we can visualize the output of our sampling (you can always remove this part in your final lens). Now, we could specify some inputs for the x and y sampling locations along with the sample size (like we did with the mapping one), but I'm instead going to accept an array of values so that we can sample from many locations. You don't need to do it this way, but in this example I want to sample the face color so I'm going to sample from several different parts of the face.

```javascript
// -----JS CODE-----
// @input Asset.Texture tex
// @input Component.Image image

// @input int[] sampleSize
// @input float[] x
// @input float[] y
```

Go ahead and select the face crop texture for the tex input, create a new screen image and use that for the image input (also create an Unlit material and set the screen image's material to that), then for now leave the sample size, x, and y inputs blank.

Next I'm going to copy a little bit of the mapping script - the channels assignment, the percentToPixel function, and the creation of the procedural texture. Then I'm going to create a new `doSampling` function and add a check to make sure we have x, y, and size values before sampling our texture.

```javascript
var channels = 4;

function percentToPixel(p, l) {
  return Math.floor(p * l);
}

var procTex = ProceduralTextureProvider.createFromTexture(script.tex);

function doSampling() {}

if (
  script.sampleSize.length > 0 &&
  script.sampleSize.length === script.x.length &&
  script.sampleSize.length === script.y.length
) {
  doSampling();
} else {
  print(
    "Make sure you have at least one sampling area set and that you have specified sample size, x, and y"
  );
}
```

For our `doSampling` function, we want to loop through each sampling area, extract the pixel values, then average them together to get our sampled color. It's nothing groundbreaking, so let's get straight to the code.

```javascript
function doSampling() {
  var r = 0;
  var g = 0;
  var b = 0;
  var n = 0;
  for (var i = 0; i < script.sampleSize.length; i++) {
    var x = percentToPixel(script.x[i], script.tex.getWidth());
    var y = percentToPixel(script.y[i], script.tex.getHeight());
    var data = new Uint8Array(
      script.sampleSize[i] * script.sampleSize[i] * channels
    );
    procTex.control.getPixels(
      x,
      y,
      script.sampleSize[i],
      script.sampleSize[i],
      data
    );
    for (var j = 0; j < data.length; j += 4) {
      r += data[j];
      g += data[j + 1];
      b += data[j + 2];
      n += 1;
    }
  }
  var color = new vec4(r / n / 255, g / n / 255, b / n / 255, 1);
  script.image.mainPass.baseColor = color;
}
```

The key difference here is that instead of setting the pixels to a color, we are instead getting the pixels. The rest is just looping through everything and calculating an average color. Then at the end we set the color of our image to the sampled color.

Now, you'll notice that our screen image is still showing as plain white, and that is because we need to choose some sampling areas. Use the mapper script to find some areas of the face you want to sample, then on the sampling script add an entry each to the x, y, and size inputs. It is very important to note that you need to have the same number of entries for the Sample Size, X, and Y inputs. The first entries in each list go together, the second entries, etc. You can use the mapping script to choose a few different areas of the face to sample and then average all of those together by creating those multiple entries on the sampler script. Be sure to select a few different regions of the face, and keep in mind some users will be wearing glasses or have facial hair. Also be mindful of areas in light and shadow - if you don't have a good variety of sampling locations, you can skew too light or too dark. Of course we aren't going for an exact skin tone, but something pretty close.

![Sampling the user's skin tone](/images/tutorials/snapchat-advanced/color-sample/sampling.jpg)

Setting the color of a screen image is pretty boring, but you can add a MaterialMeshVisual component input to the script and set the base color of virtually anything you want! You can customize the script to accept material inputs instead too. Here is our final script with a material mesh visual input.

```javascript
// -----JS CODE-----
// @input Asset.Texture tex
// @input Component.Image image
// @input Component.MaterialMeshVisual recipient

// @input int[] sampleSize
// @input float[] x
// @input float[] y

var channels = 4;

function percentToPixel(p, l) {
  return Math.floor(p * l);
}

var procTex = ProceduralTextureProvider.createFromTexture(script.tex);

function doSampling() {
  var r = 0;
  var g = 0;
  var b = 0;
  var n = 0;
  for (var i = 0; i < script.sampleSize.length; i++) {
    var x = percentToPixel(script.x[i], script.tex.getWidth());
    var y = percentToPixel(script.y[i], script.tex.getHeight());
    var data = new Uint8Array(
      script.sampleSize[i] * script.sampleSize[i] * channels
    );
    procTex.control.getPixels(
      x,
      y,
      script.sampleSize[i],
      script.sampleSize[i],
      data
    );
    for (var j = 0; j < data.length; j += 4) {
      r += data[j];
      g += data[j + 1];
      b += data[j + 2];
      n += 1;
    }
  }
  var color = new vec4(r / n / 255, g / n / 255, b / n / 255, 1);
  script.image.mainPass.baseColor = color;
  script.recipient.mainPass.baseColor = color;
}

if (
  script.sampleSize.length > 0 &&
  script.sampleSize.length === script.x.length &&
  script.sampleSize.length === script.y.length
) {
  doSampling();
} else {
  print(
    "Make sure you have at least one sampling area set and that you have specified sample size, x, and y"
  );
}
```

## Further reading

- [Procedural Texture Provider API](https://lensstudio.snapchat.com/api/classes/ProceduralTextureProvider/)


Sometimes you need to know what color something is, whether it is the user's skin tone or some area of the screen. The Procedural Texture Provider in Lens Studio gives us access to pixel-by-pixel color information.

Sample colors with a Procedural Texture

Sample colors and skin tone with a Procedural Texture


`youtube:69XAmkXiL6U`

The more the merrier. More is always better. These wise words of wisdom have been handed down for generations, and now you can bring them to pass inside Snapchat. Here in this tutorial you will learn how to exactly recreate my viral cloning lens. Just make sure you change it up a bit so we don't get caught ;) The key to this effect is the new full-body segmentation which was recently introduced in Lens Studio 3.4 along with a little scripting. You can see an example of this by [clicking here](https://www.snapchat.com/unlock/?type=SNAPCODE&uuid=6eadcd01503341e88c7e710eea02095c&metadata=01) or by scanning the snapcode below.

![Snapcode for lens with 3D text](/images/tutorials/snapchat-advanced/clone/snapcode.png)

## Overview

The concept of our clone lens is pretty simple - we want to be able to display the same person multiple times. We'll use segmentation to cutout the person, the copyFrame function to freeze their state at various times, and we'll have a simple UI at the beginning of the lens to let the user pick the number of clones they want to create.

## The base UI

Let's start with the UI. Create a new [render target](https://lensstudio.snapchat.com/guides/general/camera/) and name it UI. In the scene config, set the Live Target to the UI render target. We want to let the user choose their number of clones, but it doesn't need to be displayed in the final Snap. Using a separate render target for the Live Target accomplishes this.

Now add some Screen Text. This will also create an orthographic camera. Select the camera and set its render target to the UI target, set it to a new layer (I named mine UI), set the Clear Color Option to Texture, then choose the original Render Target for the Input. Now select your screen text and place it on the UI layer. Now if you toggle between the Live Camera and Capture Mode in the preview panel, you should see the screen text disappear for Capture Mode.

Now let's add our options. Select the [Full Frame Region 0](https://lensstudio.snapchat.com/guides/2d/screen-transform/screen-region-device-simulation/) and set the Screen Region to "Safe Render" in the inspector panel; we want to ensure our options are not covered by the Snapchat UI. Head back to the screen text and rename it to "instructions" or something similar. Put in your text and then style and position it.

On to the choices! Rather than create a new Screen Text object, I'm just going to copy the instructions so that I don't have to change the layers or anything. Ultimately I want to have five choices, the numbers 1-5, but for now just make a single copy. Move it down and change the text to read "1". Before we create the rest of the choices, we are going to take a pause and create a couple scripts first. Trust me, it will make our lives a little easier in a bit.

## The base scripts

Our clone effect will need two scripts - one main script to create the clones and a helper script on our choices to trigger the effect. Let's start out by scaffolding out the main script.

Create a new script in the resources panel and then add it to the scene at the top of the object hierarchy. We are going to keep things simple to start and add only the following code to this script:

```javascript
// -----JS CODE-----

function startCloning(num) {
  print(num);
}

script.api.triggerClones = startCloning;
```

The `startCloning` function will be what kicks off the process of creating our clones. The `script.api.triggerClones` portion can be thought of as Lens Studio's equivalent to `module.exports`. What this line does is it allows us import our script inside another script and call the `startCloning` function. Let's create our helper script for the option choices to see this in action.

Create a second script for our helper script and add the following code:

```javascript
// -----JS CODE-----
// @input Component.ScriptComponent controller
// @input int numberOfClones

script.createEvent("TapEvent").bind(function () {
  script.controller.api.triggerClones(script.numberOfClones);
});
```

Here we import a script component and the number of clones we want. Then when there is a tap event, we call the `triggerClones` function of the imported script. In our case this will call the `startCloning` function with the number of clones we want. Scripting wise this is all we'll need for the helper script, so now add it to the screen text representing the first choice. For the number of clones I am going with "1" and for the controller input I am selecting my main script. If you now click in the preview window, you'll see the value you specified for the "Number Of Clones" input printed out in the logger panel. We've added quite a bit so far, but we still aren't quite ready for the cloning portion. But almost.

![Setting up the helper script on the choices](/images/tutorials/snapchat-advanced/clone/helper-script-setup.jpg)

One issue you may have noticed is that our main script is printing out the number of clones regardless of where we tap on the screen. We want to make sure our function is only triggered when an answer choice is tapped. Add a Touch Component to the first answer choice, select the Orthographic Camera for the Camera input, and then set the Min Touch Size to something like 0.2. If that value is too small, the taps won't register. If it is too large, then tapping elsewhere on the screen can still trigger it. A value of 0.2 works well for me. Now if you click on the first choice, the number of clones should be printed in the logger. If you tap elsewhere, nothing will be printed out.

Now that we have our script and touch components added to our first choice, go ahead and duplicate it a few times. With each copy, you just need to change the text that is displayed along with the "Number Of Clones" input on the helper script.

![Finished UI setup for the options for the number of clones to create](/images/tutorials/snapchat-advanced/clone/ui-setup.jpg)

## A place for the clones

Now that we have our base UI and scripts created, it's almost time for the actual clones! We'll use our script to create the clones, but before we can do that we need a place to display the clones. Deselect everything in the objects panel (you can click in a blank space in the objects panel to do so) and add a new Screen Image. This should add a new orthographic camera as well. Alternatively you can add a new camera/screen image manually. I'm going to rename this camera to "Clone Cam" to help stay organized. I'll also drag it above the other orthographic camera (the one for the UI) and then make sure it is rendered before the UI render target in the scene config by dragging it up by the original camera. This helps me keep track of everything a little better.

![Creating and ordering the multiple cameras](/images/tutorials/snapchat-advanced/clone/camera-ordering.jpg)

Make sure the Full Frame Region is set to "Full Frame," set your image stretch mode to "Stretch," and then rename the screen image to "1" or something. This will be where our first clone goes. Go ahead and copy that screen image so that you have enough for all the potential clones (in this case, we want five total). Then copy it once more and rename this one to "Overlay." The preview panel should now be covered by the placeholder images, but we'll take care of that soon.

To overlay each clone over the previous clone, we need to be able to add an opacity texture to our screen images. Lens Studio 3.4 now includes [full body segmentation](https://lensstudio.snapchat.com/guides/general/segmentation/) which is just what we need to do this, but we can't apply opacity textures to the default image materials. Not to worry, that is easily solved with the Unlit material. In the resources panel, add a Segmentation Texture -> Body and then create some Unlit materials, one for each of the screen images we just added (so six total and I'm naming the materials the same as the images). For each unlit material, change the Blend Mode to "Normal" and enable the Opacity Texture option, but skip enabling the opacity texture on the first material because we want to freeze the background with our first clone. Now that you have the materials made, apply the corresponding material to each screen image. For images 1-5, don't worry about selecting base and opacity textures. On the overlay image, go ahead and select the Device Camera Texture for the base texture and the body segmentation for the opacity texture. We will use our script to set the textures for the remaining materials.

## Create the clones

Finally! Let's get cloning!

Head back to the main script (not the helper script we added to the UI choices) and add a few inputs at the beginning of the script. We need the texture to clone from, the segmentation mask, and then the images and materials we just created.

```javascript
// @input Asset.Texture cameraTex
// @input Asset.Texture maskTex
// @input Asset.Material[] cloneMats
// @input Component.Image[] cloneImgs
```

Save your script then find it in the objects panel. Go ahead and select the inputs.

![Setting the inputs for our cloning script](/images/tutorials/snapchat-advanced/clone/script-inputs.jpg)

First we will use a loop to make sure all the screen images for the clones are disabled. We can manually disable them in the objects panel, but doing it in the script ensures they always start disabled (in case we forget to disable them manually). Next we are going to create a function we can call to create the clones. We are going to pass in which number clone we are on, [freeze the camera texture](https://lensstudio.snapchat.com/api/classes/Texture/) and the segmentation texture, and apply those to the corresponding material and activate the screen image. Our script should now look like the following:

```javascript
// -----JS CODE-----
// @input Asset.Texture cameraTex
// @input Asset.Texture maskTex
// @input Asset.Material[] cloneMats
// @input Component.Image[] cloneImgs

for (var i = 0; i < script.cloneImgs.length; i++) {
  script.cloneImgs[i].enabled = false;
}

function createClone(index) {
  print("Making clone " + index);
  script.cloneMats[index].mainPass.baseTex = script.cameraTex.copyFrame();
  script.cloneMats[index].mainPass.opacityTex = script.maskTex.copyFrame();
  script.cloneImgs[index].enabled = true;
}

function startCloning(num) {
  print(num);
}

script.api.triggerClones = startCloning;
```

Time to trigger the cloning! We want to create the clones at periodic intervals, so we are going to use a [`DelayedCallbackEvent`](https://lensstudio.snapchat.com/api/classes/DelayedCallbackEvent/) to trigger the cloning. We'll also need a few extra variables to keep track of a few things.

- `delayTime` will be the time in seconds between clones
- `currentIndex` will be how we keep track of which clone we are creating
- `cloneCount` will start at 0 but be set to however many clones the user chooses

Inside our delayed callback event, we'll create the clone, increment the current index, and then if we have not yet reached our desired clone count, we'll trigger the delayed callback event again. And in our `startCloning` function we'll be sure to set our clone count to the number we receive there from the UI helper script. Let's take a look at our code now:

```javascript
// -----JS CODE-----
// @input Asset.Texture cameraTex
// @input Asset.Texture maskTex
// @input Asset.Material[] cloneMats
// @input Component.Image[] cloneImgs

var delayTime = 3;
var currentIndex = 0;
var cloneCount = 0;

for (var i = 0; i < script.cloneImgs.length; i++) {
  script.cloneImgs[i].enabled = false;
}

function createClone(index) {
  print("Making clone " + index);
  script.cloneMats[index].mainPass.baseTex = script.cameraTex.copyFrame();
  script.cloneMats[index].mainPass.opacityTex = script.maskTex.copyFrame();
  script.cloneImgs[index].enabled = true;
}

var delayedEvent = script.createEvent("DelayedCallbackEvent");
delayedEvent.bind(function () {
  createClone(currentIndex);

  currentIndex += 1;
  if (currentIndex < cloneCount) {
    delayedEvent.reset(delayTime);
  }
});

function startCloning(num) {
  print(num);
  cloneCount = num;
  delayedEvent.reset(delayTime);
}

script.api.triggerClones = startCloning;
```

When you select an option in the UI, you should see the cloning progress printed out in the logger. Keep in mind that JavaScript uses 0-based indexing so our first clone will actually be clone 0. Switch the preview panel over to your webcam and give the lens a try! You should be seeing your clones created, but let's polish the UI a little and add in the countdown.

## Finishing the UI

We are going to start by adding in some screen text for the countdown. Select the UI orthographic camera and add a new Screen Text. This should create a new Full Frame region as well (it will be important in just a bit that we have a new full frame region). Rename the text to countdown, format it how you wish, move it to the UI layer, and leave the text value blank - we'll set the value with our script. Our text is already in the middle of the screen, but I set the full frame region to Safe Render just to be safe. Before heading back to our script, rename the full frame region with the instructions and the choices to something like "choices."

Jump back into the main script and add a couple more inputs - a `Component.Text` input for the countdown text and a `SceneObject` input for the "choices" full frame region. Save the script and select the appropriate objects for the new inputs.

Our first scripting change is simple. When we start cloning, we want to hide our initial list of options. Inside the `startCloning` function, just add `script.choices.enabled = false`, swapping out whichever name you used for that input. Once the number of clones is selected, the options will be hidden so the user can focus on the actual cloning process.

Our next change is a little larger, but nothing too crazy. We want to add in a new variable `hasStarted` to keep track of if we should start the countdown; it should be initialized to `false`. Next we'll create an `UpdateEvent` and use the remaining time on the delayed callback event to calculate how much time is left and display that to the user. Our script should now look like this:

```javascript
// -----JS CODE-----
// @input Asset.Texture cameraTex
// @input Asset.Texture maskTex
// @input Asset.Material[] cloneMats
// @input Component.Image[] cloneImgs
// @input Component.Text countdownText
// @input SceneObject choices

var delayTime = 3;
var currentIndex = 0;
var cloneCount = 0;
var hasStarted = false;

for (var i = 0; i < script.cloneImgs.length; i++) {
  script.cloneImgs[i].enabled = false;
}

function createClone(index) {
  print("Making clone " + index);
  script.cloneMats[index].mainPass.baseTex = script.cameraTex.copyFrame();
  script.cloneMats[index].mainPass.opacityTex = script.maskTex.copyFrame();
  script.cloneImgs[index].enabled = true;
}

var delayedEvent = script.createEvent("DelayedCallbackEvent");
delayedEvent.bind(function () {
  createClone(currentIndex);

  currentIndex += 1;
  if (currentIndex < cloneCount) {
    delayedEvent.reset(delayTime);
  }
});

function startCloning(num) {
  print(num);
  hasStarted = true;
  script.choices.enabled = false;
  cloneCount = num;
  delayedEvent.reset(delayTime);
}

script.createEvent("UpdateEvent").bind(function () {
  if (hasStarted && currentIndex < cloneCount) {
    var timeRemaining = Math.floor(delayedEvent.getTimeLeft());
    var displayTime = delayTime - timeRemaining;
    script.countdownText.text = displayTime.toString();
  } else {
    script.countdownText.text = "";
  }
});

script.api.triggerClones = startCloning;
```

You would expect the `getTimeLeft` function to give us exactly what we need, but we actually have to subtract that value from whatever delay time we are using. Anyway, give your lens a try! You should now have a fully functioning clone lens! If you are happy with how everything looks, push the lens to your device to test it out (hint hint).

## Time to fix a bug

If you pushed your lens to your device (which you always do before submitting, right?), you may have noticed that it crashes when creating the clones. The UI works and the countdown works, but once you get to the first clone it crashes. This sort of problem is super frustrating to troubleshoot because everything was working fine inside Lens Studio and Snapchat doesn't tell us what went wrong.

So how do we troubleshoot this? Well we know when the issue is occurring. We know that the issue is either occurring with our `createClone` function or when we reset the delayed callback event. The first countdown works, but then either creating the clone or triggering the second one does not.

Let's start by taking a look at our `createClone` function. The first thing we are going to try is commenting out the line where we set the baseTex. Make the change, save the script, and push to your device. Didn't work? Comment out the next line where we set the opacityTex, save, and push to device. Hooray! Our lens doesn't crash anymore! But why? Unfortunately, I don't have an exact answer. I did ask around a bit and [Ben Knutson](https://kargraphics.com/) shared that for whatever reason, the `copyFrame` function does not work with segmentation textures. But that is kind of a problem for us. How do we solve it?

Fortunately the answer is simple. We are going to pipe the Body Segmentation texture to a separate render target.

- Create a new Render Target, name it "Mask" or something
- Create a new camera, name it "Mask Cam" or something
- Create a new layer and set the camera to just that layer
- Set the camera type to orthographic
- Set the camera's render target to the mask render target
- Go to the Scene Config and drag the mask render target to the top of the list so it is rendered first
- Add a screen image to the mask camera and make sure it is on the same layer as the camera
- Change the stretch mode of the image to "Stretch" (I don't like to take any chances) and choose the Body Segmentation texture for the image texture
- Select the clone controller script and select the mask render target for the mask texture input
- Make sure any changes you made to the control script while troubleshooting are reverted (uncomment anything you commented out).

That's a long list, but all we are doing is setting up a new camera/render target pair on a new layer, outputting our segmentation texture to that, and then using that render target as our mask texture. Once that is done, your lens is now complete and will work on your device. Give it a try!

## Further reading

- [Cameras and Render Targets](https://lensstudio.snapchat.com/guides/general/camera/)
- [Frame Regions](https://lensstudio.snapchat.com/guides/2d/screen-transform/screen-region-device-simulation/)
- [copyFrame](https://lensstudio.snapchat.com/api/classes/Texture/)
- [Segmentation](https://lensstudio.snapchat.com/guides/general/segmentation/)
- [Delayed Callback Event](https://lensstudio.snapchat.com/api/classes/DelayedCallbackEvent/)
- [Lens Studio Forum](https://support.lensstudio.snapchat.com/hc/en-us/community/topics)


The more the merrier. More is always better. These wise words of wisdom have been handed down for generations, and now you can bring them to pass inside Snapchat. Here you will learn how to exactly recreate my viral cloning lens. Just make sure you change it up a bit so we do not get caught ;)

Advanced Lens Studio

Add dynamic text directly to 3D objects in Lens Studio

Make things flop around with chain/swing physics in Lens Studio

Selectively apply post effects to a 3D object

Sample colors and skin tone with a Procedural Texture

Recreate the Clone Photos filter from TikTok using Lens Studio