MadMapper OSC API

MadMapper from the Geneva based firm GarageCUBE is a great piece of software to create stunning visual mappings and even LED & light shows. Together with the Modul8 it is a powerful VJ tool for creating and presenting visuals.

From Modul8 we were used to have a full python environment to create new modules and extend the software with other great tools. Unfortunately MadMapper did not has this ability. It just provides a simple OSC interface which is great for mapping controllers to the surface, but not a real api.

Prototype

So a few days ago, Matthieu sent me a link to a preview version of MadMapper 2.1.1 which will have extended OSC support. The idea behind this is to provide a simple API over the OSC interface. I started to create a prototype of a remote surface controller, which would be able to read data from MadMapper and also send back. I’ve written it in processing and you can find the code at the end of the post.

Check out the video to get an idea how my prototype looks like:

Before I get into the API I give you a short introduction to OSC and how my prototype works. OSC is a simple UDP network protocol between a server and multiple clients. UDP gives us the ability to just send data and don’t care about, if the client is listening or not. Or how many client’s are listening to our message. The benefit of this is that it is really fast and simple. The drawback of this is that if you want to create a bidirectional channel between your software and MadMapper, we have to open a server and a client on each side.

And this is what I am doing in the processing example. osc is my server and madMapper is the client: //init osc
osc = new OscP5(this,9000);
madMapper = new NetAddress("127.0.0.1",8000) To get the OSC messages from MadMapper we have to declare a function called oscEvent. Here we can process the data we received. void oscEvent(OscMessage msg) {
} To send data to MadMapper we can just create a new message and send it. Messages could contain data but it could also just be empty. But a message does always contain an address to which it is related to: OscMessage msg = new OscMessage("/getValues?url=/surfaces/Quad 1/handles/.*&normalized=0");
osc.send(msg, madMapper); So the idea behind the API is to send a message that you want to have an information and get back an answer from MadMapper. This is like the same as in computer science the actor model.

Here is the code of my prototype in processing. The code is not very nice, but it is just to get an idea: Simple Quad Editor

Now what are we able to send and to get specifically with MadMapper?

The API

As I already mention, the API is still in just an early preview state. It could change till public release and maybe will be extended. But I just want you to get an overview how it works.

At the moment there are two addresses which will return data form MadMapper.

getAdresses

Get addresses is to receive the available nodes from MadMapper. /getAdresses?root=ROOT_URL&recursive=RECURSIVE Parameters – ROOT_URL (String): The node from where to search for other nodes. – RECURSIVE (Boolean): Defines if MadMapper should send only the direct children of ROOT_URL node, or if it should send back all controls below this node. Value: 0 or 1

Reply MadMapper replies with a message for each child of the requested node on the address of the node.

Example If we have one surface in MadMapper called “Quad 1” and we send a message with this address: /getAddresses?root=/surfaces&recursive=0 MadMapper sends back two messages without data on this addresses: /surfaces/selected
/surfaces/Quad 1

getValues

Get values is to receive the values of the nodes from MadMapper. /getValues?url=URL_PATTERN&normalized=NORMALIZED Parameters – URL_PATTERN (String): The url pattern of the Controls we are looking for, as a regular expression. A simple example is just the URL of a control “/surfaces/Quad 1/opacity”, but we might ask all controls of a surface using “/surfaces/Quad 1/.” – NORMALIZED (Boolean): Defines if you want to receive the normalised value (FLOAT 0.0-1.0) or the value as it is (FLOAT, INT, BOOL, STRING, RGBA). *Remark: RGBA and STRING values cannot be normalised, so MadMapper won’t send a reply for such addresses if normalised value is requested. Value: 0 or 1

Reply MadMapper replies with a message for each control that matches the URL_PATTERN, the address of the message is the address of a Control and the value of the message is the current value of this control.

Example If we have one surface in MadMapper called “Quad 1” and we send a message with this address: /getValues?url=/surfaces/Quad 1/handles/.*&normalized=1 MadMapper sends back two messages without data on this addresses: /surfaces/Quad 1/handles/0/x 0.5
/surfaces/Quad 1/handles/0/y 0.5
/surfaces/Quad 1/handles/1/x 0.5
/surfaces/Quad 1/handles/1/y 0.5
/surfaces/Quad 1/handles/2/x 0.5
/surfaces/Quad 1/handles/2/y 0.5
/surfaces/Quad 1/handles/3/x 0.5
/surfaces/Quad 1/handles/3/y 0.5

This was just a short introduction to the possibilities MadMapper will offer in the future. I hope a lot of great tools will be developed and you enjoyed reading my blog.

If you have any question about this, just write a comment!

Cheers Florian