Using the Slice Selector to crop the input of a player – HeavyM

In another tutorial, you've learned how to display a media in a Player and how to clip it to Faces. While masking is a useful tool if you need fancy shapes, in that case the Player still fits the full size media inside its rectangular area. There are cases where you might want to crop the input before it is sent to the Player. That's when the Slice Selector module comes in handy.

In this article, we'll describe the behavior of the Slice Selector and then illustrate its application in a cake mapping use case.

How does it work?

Where to find it

A slice is a property of a player, not sources or medias. It is independent from the linked content.

You can open the Slice Selector of a player by selecting it and clicking on "Enter slice selector" under the "Crop" section of its Properties.

Note: there can be one slice per player.

Overview of the Slice Selector window

There can be one slice per player. A slice is a non-destructive way to crop content, it can be edited indefinitely.

Here's an overview of the selector window:

In the center of the Slice Selector, you get a still frame of the content displayed inside the player and the name and resolution of the media that is playing are indicated above. If nothing is attached to the player the moment you open the Slice Selector, you'll see the 1920x1080 default checkerboard card seen in the previous screenshot and you can still create a slice.
On this frame, you'll find the crop zone, the rectangular area defined by the four yellow handles. It represents the slice and its resolution (in pixels) and coordinates (in pixels too, relative to the top left corners of the frame and the zone).
You can navigate the creation area with common HeavyM controls: zoom in/out with the buttons on the bottom right corner or with your mousewheel ; move around by pressing your mousewheel or with [Space] + drag.

Creating a slice

To create a slice, simply:

Set its size by dragging the yellow handles to define the limits of the crop zone or use the input fields below the frame to enter precise values, either in percentage or pixels (more on that in the next section).
Set its position by dragging the crop zone, or using the arrow keys on your keyboard.
Click on "Create".

That's it! If you need to edit the slice, simply enter the slice selector of the player, make your changes and click on "Create" to apply them.

Behavior with Medias

A slice is not directly linked to a Source, so it's not relative to any Media. Actually, any type of Media can be cropped, even with different sizes. The slice just creates a texture with the same proportions relative to the resolution of the current media.

As seen in the overview, the size of the slice is given in percent and pixels. You'll notice that the values in percent never change, no matter which media is currently playing. That's because it doesn't depend on the resolution of the current media (contrary to the pixel size, that is just given has an indication and is converted from the percentage value). Same with the coordinates, they're proportional. Here's an example:

You create a slice that takes 50% of the width and 50% of the height and place it on the top right corner : no matter which type of media is playing or its resolution, this player will always display the top right quarter of the texture. For instance if it's a 1920x1080 video, the slice will cover 960x540px and be placed at X=960 ; Y=0. For a 500x500 shader, those values will represent 250x250px and X=250 ; Y=250.

Behavior with Maps

As mentioned before, a slice is considered a geometric property of a player. Hence, it is linked to the shape and will be the same throughout all sequences using the same Map.

Cake mapping example

Here's an example of how the Slice Selector can make your life easier. Let's map a single video loop on a dummy cake for a wedding.

We've added a photo of the cake from the point of view of the projector in the background (View → Image Settings...) to help us draw.
We create and adjust one player on each part of the cake where we want to see the loop.
Our video is 1920x1080. We've created an image template of the same size to help us define each of the 8 slices.
Let's attach it to a first player. We see that, as expected, the image fills the shape.
We can create the slice in its Slice Selector by adjusting the crop zone to the corresponding color block in the template. Here, we know that it's going to be 860x270 so we can directly use the pixel input fields.

Here's the result after hitting "Create":
After repeating steps 4 and 5 for each player, we get this:
Now that each slice is properly adjusted, we can just change the content and link our video.

That's it! The same single video is attached to all the players, so playback is perfectly synchronized between all slices.