MMMSEGUI

MMMSEGUI is a multi-segment graph editor written in JS/JSUI/MGraphics for Cycling 74’s Max platform.

Rationale

The main objectives for MMMSEGUI were:

• have the ability to output directly into a list message for use with the curve~ Max object
• make it very simple and fast to use while minimising modifier key requirement
• have the ability to add and delete nodes quickly and intuitively
• have the ability to easily alter curve shapes and move graph segments around
• have it easy to add to other projects and save the settings with your patchers
• have it be very customisable

In addition to this, recent updates include:

• automatic resizing of the graph when resizing the JSUI window
• commands to clear the graph and also to create a graph through a message list
• poll the graph to sample single values at a given point in the time (X) axis
• the ability to set the X, Y and control point of a single node via messages

For any previous users please read the following section regarding the November 2023 update.

Support My Work

If you like my work and use it or learn from it, please consider supporting me or just a donation to say thanks:

How Can I Get MMMSEGUI?

MMMSEGUI is freely available on my Github repository:

MMMSEGUI Repository

Important - Major Update and Refactoring November 2023

A soft apology to any existing users, especially if you’ve incorporated MMMSEGUI into any of your own projects and patchers. This update has MAJOR changes:

It was difficult to incorporate many of the changes without some collateral damage. I hope it’s not too painful for you and have faith that the ground-up refactoring has improved the overall structure so this situation won’t happen in future. Shouldn’t happen. Never say never in development!

18/11/2023 Update Overview

The entire documentation has been updated but here are the highlights:

• setting up and instantiating is now WAY simpler. Sensible default values are generated rather than making the user define them.
• changed mouse behaviour adding and removing nodes: now just double-click instead of SHIFT + click
• the curve shape of a segment can be reset (to linear) by holding SHIFT and double-clicking the segment
• MMMSEGUI will now resize itself if you resize the JSUI window
• the @parameter method of setting customisation has been removed in favour of dedicated messages
• there is now a much simpler fillcolor, strokeColor, and bgColor to set the graph colors along with a set of new messages for customising other features (see below)
• there is clear command to reset the graph (customisations are persistent)
• added a graph command to define a graph numerically for making templates and presets etc.
• similarly there is a graphfromcurve command that lets you define a graph numerically using MMMSEGUI output format (input format for Max [curve~])
• you can now move a graph segment in both the X and Y axis (hold SHIFT and drag the curve segment), previously you could only move a segment in the Y axis.
• two new commands to sample the graph Y value at a point in time, getvalue uses a normalised value as the X position where getvalueattime lets you specify a time in ms.
• some new commands to modify position and control point parameters for individual nodes

Updates

13/02/2024

Added “Phasor Mode” - a special mode with restrictions to use the the phasor~ object.

Content and Installation

• mmmsegui.js is the main JSUI file you need to use MMMSEGUI.
• mmmsegui.maxpat is the demo patcher to demonstrate all MMMSEGUI’s features - play around with stuff
• readme.md this file.
• mmmseg_audio_demo_1.maxpat demo of MMMSEGUI using a very basic step sequencer that drive a monophonic synth voice. Two step sequencers control pitch and LPF cutoff. Three MMMSEGUI envelopes control pitch, low-pass filter and overdrive modulation.
• mmmseg_audio_demo_2.maxpat a simple 4-step sequencer steps through four MMSEGUIs, each of which modulate the pitch of a [rect~] oscillator. You can change the metro tempo and also whether the MMSEGUIs loop (the curve~ objects are re-triggered when they reach their end point).

Adding MMMSEGUI To Your Patcher

Put the mmmsegui.js file in your Max search path(s) then add a JSUI object to your patcher specifying the MMMSEGUI filename:

1[JSUI @filename mmmsegui.js]

The default MMMSEGUI only contains two nodes, the end and start nodes. These cannot be deleted and only their Y position (and curve shape) can be changed. To add more nodes (or delete them) you need to use the mouse (and keyboard).

Adding, Deleting and Moving Nodes. And Curves.

Customisation Messages

Customisation is done via Max message objects. For data type see the Notes column. Some error/range checking/clamping is done but I’m sure you can break it if you try.

Color Messages

For the color messages that have the RGBA data type there are 4 values, so your message will look like: [fillcolor $1 $2 $3 $4] where $1 is the red value, $2 is the green value, $3 is the blue value and $4 is the alpha value. This is standard RGBA format in Max and is the output from [colorpicker @compatibility 0] or [swatch] etc.

Auto Output

Auto Output is on by default (turn it off with [autooutput 0])which means anything you do that changes the nodes, curves or timescale will cause MMMSEGUI to output the current graph as a curve~ formatted list. If you set Auto Output to off, nothing will be output from MMMSEGUI until you send a bang message to its inlet. The only exception to this is the getvalue and getvalueattime commands (see Command Messages), for obvious reasons. Sending messages to MMMSEGUI that only change the graphical look of the graph will not cause output of node list.

Phasor Mode

“Phasor Mode” is a feature requested by a few members of the Max Discord channel for use with the phasor~ object. In Phasor Mode there are a few changes and restrictions to the way MMMSEGUI works:

Selecting Phasor Mode

The message setphasormode is used to turn Phasor Mode on/off. 0 turns it off (default) and 1 turns it on.

However you must also then use the clear message to reset the graph which means if you intend to use Phasor Mode on a MMMSEGUI object, select Phasor Mode first, then clear the graph before setting nodes etc.

Clearing the graph is necessary so that the graph starts with nodes that respect the restrictions of Phasor Mode. I thought about just adding some validation code so that you could switch between Phasor Mode on/off but that would also modify your graph. Clearing the graph is simpler and easier.

Command Messages

In addition to customisation there are some messages that control MMMSEGUI:

Set Value Commands

A new set of commands to enable you to set the position and curve shape of individual nodes in your graph. This has some interesting uses especially using an external signal to modulate node coordinates.

setxat n x, setyat n, y and setcat n c are used to set the X, Y and control point of node n

setnode n x y c allows you to set all the properties of a node in a single command.

Node number n needs to be a valid node in the current graph but MMMSEGUI will just reject the command silently if the node number is invalid.

The X position is constrained by the X position of the previous and next node in the graph.

You cannot change the X position of the first and last node. The first node is node 0.

Setting the curve point, c, affects the shape of the curve to the right of the specified node n.

Get Value Commands

Another two new commands, getvalue and getvalueattime allow you to sample the graph with a position/time input and get the normalised Y value at that point.

The value is output from [outlet 2], 0.0 to 1.0 with 0.0 being at the bottom and 1.0 at the top.

getvalue input is clamped to 0.0 - 1.0 whereas getvalueattime will post an error to the Max Console if the ms time is outside of the range of the current timeScale setting for the graph.

Graph Commands

There are two further new commands that let you send a list message to MMMSEGUI to define a graph numerically. This is handy if you want to make your own presets or templates for example. The two command messages are [graph] and [graphfromcurve]

When you send either the graph or graphfromcurve message, the graph will be immediately updated and the values mirrored at outlet 1.

graph

The first command, graph, lets you create a new graph with normalised values:

1[graph x1 y1 c1 x2 y2 c2 x3 y3 c3] etc.

• xn is the normalised position of the node along the X axis, 0.0 to 1.0, left-to-right
• yn is the normalised magnitude in the Y axis, 0.0 to 1.0, top-to-bottom
• cn is the normalised curve value, 0.0 to 1.0, 0.5 is the middle (linear curve)

This data form parallels the MMMSEGUI internal data form. It’s a more simple structure than graphfromcurve as it’s easier to visualise and because the X values are normalised you can define a graph independent of it’s timeScale setting.

graphfromcurve

You can also send MMMSEGUI a [graphfromcurve] message to define a graph numerically but this time the data format is exactly that of MMMSEGUI output (the same format as input message to Max’s [curve~] object).

1[graphfromcurve y1 d1 c1 y2 d2 c2 y3 d3 c3] etc.

The parameters are slightly different from the graph command in order to be compatible with [curve~]

• yn is the Y axis position of the node but is inverted, 1.0 is the top, 0.0 is the bottom
• dn is the delta time in ms from the previous node
• cn is the curve~ curve shape value, -0.999 to 0.999

The advantage of graphfromcurve over graph is that you can hook up the output of MMMSEGUI to the right-hand inlet of a message object and then use that output directly to form a graphfromcurve message.

The disadvantages of graphfromcurve compared to graph for manually typing in a graph definition are:

• it’s tricky to visualise and calculate the delta times
• MMMSEGUI has to calculate the timescale (X axis) from the delta times of the X position of the nodes and then it automatically sets the timeScale parameter from this

Saving

MMMSEGUI has an internal save structure that will save all of it’s parameters when you save your patcher and restore itself when you reload your patcher. On one hand this is convenient and simple but MMMSEGUI is always saving - any changes you make to MMMSEGUI while playing with your patcher will be saved when you save.

Inlets and Outlets

inlet 1 handles all the command and parameter messages

outlet 1 outputs a list of nodes and delta times from the current graph shape

outlet 2 is used to retrieve a single Y value at a point in time

See Command Messages for details on the various commands.

Using the Output from MMMSEGUI

As already mentioned, the output is deliberately formatted as a list that will be immediately accepted by a [curve~] object.

The output format is a trio of parameters per curve:

1[magnitude deltaTime curveFactor]

• magnitude is the Y axis value

• deltaTime is the time in milliseconds from when the [curve~] previous node (or when the curve~ was triggered) and is calculated from the timescale setting

• curveFactor is the control-point value that describes the curve shape. The value range is -0.999 to 0.999 - for some reason if you go to -1.0 or 1.0 things start to go a bit weird with the [curve~] object. That’s a Max issue, not MMMSEGUI!

Each trio of parameters makes a stage of a multi-stage curve in a [curve~] object.

Using the Output From the [curve~] Object

The output from a connected [curve~] object will be a float value in the range 0.0 to 1.0 so you will need a [scale~] object or other ways to transform this normalised value into something useful. I’ll leave that for you to work out.

I may look at other output features such as exponential scaling for future updates.

Rolling Your Own Output

If you want to create your own output format, look towards the bottom of the mmmsegui.js file for the function called this.outputList. This is the internal function that is called by MMMSEGUI whenever it needs to output the node values.

 1this.outputList = function() {
 2  var out = [];
 3  // Add first node to output list using a time delta of zero
 4  out.push(1-this.nodeList[0].y, 0.0, 0.0);
 5  for (n = 1; n <= this.nodeCount-1; n++) {
 6    // Add next node Y value
 7    out.push(1-this.nodeList[n].y);
 8    // Add node delta time
 9    out.push((this.nodeList[n].x - this.nodeList[n-1].x) * this.timeScale)
10    // Add node curve factor
11    out.push((this.nodeList[n-1].cp * 1.998) - 0.999);
12  }
13  // Send output list to first outlet
14  this.outputFlag = false;
15return out;
16}

Here I’m creating an empty array, out and then iterating through the nodes pushing the Y value, then the calculated delta time and then the curve factor. The variable this.outputFlag is used to only trigger output when there has been a change in the graph that requires outputting. The final line returns the output array for sending to the JSUI outlet.

@parameter Style Customisation

I made the decision to remove this in the November 2023 update. Several reasons, the main one being that you can’t tweak the parameters as jsarguments without causing MMMSEGUI to recompile which was deeply annoying. Poor design decision on my part: I hold my hands up.

However, if the removal of these is the worse news ever for you, here’s how you can implement them yourself.

The basic code for interpreting the @parameters follow this form. Put this in the mmmsegui.js code just after the instantiation line:

 1jsarguments.filter(function(arg) {
 2  if (arg[0] == "@") {
 3    var val = jsarguments[jsarguments.indexOf(arg)+1]
 4    switch (arg) {
 5      case "@nodesize":
 6        mmmsegui.setNodeSize(val)
 7        break;
 8      case "@timescale":
 9        mmmsegui.setTimeScale(val)
10        break;
11      default:
12        break;
13    }
14  }
15});

So you can add as many or as few as you like by adding more case clauses to the JS switch statement. You can see there are two MMMSEGUI function calls, mmmsegui.setNodeSize(val) and mmmsegui.setTimeScale(val). These function names are the internal functions that handle those parameters. val is the value you place after each of the @parameters

As an example, let’s say you wanted to add a parameter called @padding to set the padding inside the JSUI window. Add another switch clause before where the default one is in the code:

1case "@padding":
2	mmmsegui.setPadding(val)
3	break;

The @parameter names don’t have to match the function names, you can call them whatever you like.

The list of functions you can use is here (though could be subject to change but I’ll endeavour to update this section if any future updates affect them). I won’t describe them as their function should be fairly obvious from their name.

The obvious omissions here are the functions to set fill, stroke and background colors. This is a bit more fiddly to implement as @paramters because you need four float values (RGBA) and the example code above will only copy with one parameter. If you need that and want help with it just get in touch.

Node and Line setNodeSize(), setLineWidth(), setPadding()

Input and Output setTimeScale(), setAutoOutput(),setMouseSpeed()

Mouse-over Highlighting setNodeHighlighting(), setCurveHighlighting()

Node Visibility setAutoHideNodes(),setNodesVisible()