Kantan Mapper - an approach on simple mapping in TD


If you are running TouchDesigner099 please check mottoKantan for a complete 099 rebuild with improved ui and workflow.

The Kantan Mapper Wiki Page can be found here:

after painstakingly building masks in Photoshop for a recent Installation here is the foundation for a simple mapping kit which should allow you to mask and map many surfaces and shapes.

The Idea is to draw directly on the projection and follows well known techniques and workflows just implementing them in a TouchDesigner077 environment.

Here are a couple first steps with it:

Note: This is made with and for TouchDesigner077 build 16240. Please make sure your installation is up to date.
I had trouble running this on an ATI Card. Picking Masks was only possible through selecting them in the Mask List.

After loading the tox file, open the Controlpanel of “kantanmapper”
Enter a resolution and select which monitor you want to output to.
Click the Enable button for the Output.
Now click on the Mask List Button to open up the main controls for your masks.

In the Mask List click the “Add Rectangle” button. A rectangle should now appear on your output.
In your output select the newly created rectangle which should reveal a green outline and 4 corner-points. By selecting and dragging the corner-points you can adjust the shape of the rectangle and by dragging anywhere inside the rectangle you move the whole mask.

You can also select one or more corner-points and move them together or use your arrow keys to move them more precise.

Once done with setting up the mask, drag a TOP from your network onto the mask to give it a texture. If you don’t see the texture but the mask is colored in a bright color, make sure you enable the Texture Button in the main Controlpanel.

By double-clicking onto the mask in your output, another Controlpanel comes up which lets you edit the texture itself. Hit ‘t’ to bring up a translate handle, ‘s’ to bring up a scale handle, ‘r’ to rotate and ‘p’ to see the cornerpin handles.

The same thing can be done with Freeform Masks. To create a Freeform, click “Add Freeform” in the Mask List and click in the output window to add points. When you are done adding points, right-click and you are exiting the Freeform mode. Everything else works the same except you have an extra option to add more inline points to the mask. You find the option for that in the Mask Lister on the bottom when a Freeform Mask is selected. Points in Freeform Masks can also be deleted by selecting them and hitting the ‘del’ key.

Please let me know of any trouble or ideas. This is really a prototype and your input will be very valuable to make it better.

kantanmapper.tox (1.46 MB)

a small fix where when entering the resolution it would only change the width of the projection.

Wow. This is a really slick UI! Thanks! One comment, I think it’s strange to have to enter in network mode to add images. Would be easier if there was a panel which pulled all the tops from the network and allowed you to assign textures while in perform mode.

wow markus!!!

This is incredibly awesome in so many ways…!!!
I’m so gonna find time to break it apart, tinker and probably add stuff to it…
gotta love this tox!!


Here’s a video of a first test with the kantan mapper tox. It took about two hours to do the masks. It would be cool to be able to save while adding masks. Also it would be handy to have the number of the mask displayed so it’s easier to keep track of which component belongs to which mask.


Hearing that it takes 2 hours I’m thinking it would also probably be usefull to copy and paste masks?


Some updates to KantanMapper that introduce some improvements and fixes:

  • All controls have been merged into one main UI.
  • Apart from the output window, there is now also an Edit Window which comes in handy when points are not on the screen or can’t be located.
  • When a mask is selected in the edit or output window, use the TAB key to cycle through the points.
  • There is an animated indicator when a point of a mask is being selected.
  • The resolution cannot be changed once a mask is created.
  • You can specify your own Sample Image to map onto or to aid with visibility when mapping.
  • The Mask List is ordered by Layer Position of the masks
  • Use Ctrl+c and Ctrl+v to copy and paste masks in the edit or output window.



I’m new to TD. This component seems great.
How to send my output (clips, movies, renders) to the container / mapper?

Thanks for help


you can just drag a TOP node onto a mask on the edit or output screen. Does that help?


Here is an update to the Kantan Mapper which adds support for Bezier Curves. Works the same way as the other object types yet creates nice round shapes with control handles. These are currently still locked, the next update should have the function to unlock them or lock them at different angles.

Another addition is the possibility to display the names of the objects on the edit and output screen. Just click the “Show Names” Button in the controlpanel.

As usual, feedback is greatly appreciated

Hey Markus,

Having a lot of fun playing around with this and really liking the new beziers.

We’ve been testing it out a bit and theres two main bits of feedback:

One is that it’d be cool if you could just export mattes or a full matte of all of the shapes added together, it’s one of the first modifications I made so you can project directly onto the whole object with no warping from textures, it’s easy enough to do with constants however…just be cool if you could toggle it in the UI.

The second was that the warping is fitting horizontally. It’s easy to go in and skew the image so it fits the perspective of the mapping but this is more for when people are viewing from one particular point (in our case through a shop window) …I’m going to experiment with this later tonight to make sure it’s definitely not possible, we’ve already just put in a corner pin fix so you can adjust the angles manually but it’d probably be easy enough to guesstimate from point differences.


I’ll add a save button for each object and all objects to the ui for the next update, this is indeed very much needed…

For your second point, when adding a rectangle it maps the texture automatically, for freeform and bezier it fits it horizontally, yet by double-clicking on the object you can translate, rotate, scale and pin the texture - is there something missing which you would like to see or did I misunderstand you?

Thanks for testing!

I tried dragging ramp node on the top node and rectangular mask I created, but nothing showed up. What am I doing wrong? Should I use different node?



are you dragging the TOP onto the shape in the output or edit window? Also do you have the “Texture” button in the main control panel enabled? If it’s not showing up, can you post the tox and I can have a look?

There now is also a wiki page with some instructions on howto use the mapper: derivative.ca/wiki/index.php … tan_Mapper


Been playing with it again today…didn’t realise you could double click, thats very very cool.

We’ve been projecting onto a box with a framework around the edges and have had to use more than one shape to create the framework, I guess a way of subtracting one shape from another’d be a cool suggestion too. (All these suggestions)

Either way…absolutely great fun playing around today, I’ll be posting up a full piece we’re doing with Kantan in 2 weeks time.


Hey Richard,

do you mean subtracting as in image compositing operation or as in geometric boolean operations?


I don’t get one thing. Can you please help me.
If I’m running Kantan Mapper in performance mode, how do I access any node in the network?
You said that I have to drag TOP node to mask in editor, but the editor is only visible when I execute it (that is in performance mode). As I can see, in performance mode there is no nodes visible, only the patch running.

Interface is super cool and simple, but that part with assigning textures/videos is giving me a lot of trouble.


When you are in performance mode you can simply hit the ESC key to get into the editor.

currently you have to be in the edit mode to drag TOP nodes as textures onto the shapes. As also James noted a browser would be nice which enables you staying in perform mode, I will add this in at a later point…



I’ve been wondering if its possible to mask output of a node / video without perspective transformation?

What I’d like to do is to create 4 masks for one video output, and split video to those masks (not to duplicate it and transform in perspective)