Plotter | SuperCollider 3.13.0-dev Help

Description

Plot data of up to three dimensions on a Window or UserView.

Keyboard shortcuts

When the plotter window has focus, the following keyboard shortcuts can be used to change the display:

+ / -	vertical zoom
=	compare plot channels
n	toggle normalize display (0..1) / (-1..1), or fit range
s	toggle superposition (see: superpose)
m	switch plot mode (see: Plotter: -plotMode)
e	toggle editing (see: Plotter: -editMode)
g	toggle horizontal (domain) grid
G	toggle vertical (codomain) grid
p	print curve
ctrl-+ / -	zoom font
alt-click	post value

Method extensions

Plotter extends other classes with methods. To see what classes implements plot, see Methods: plot

plot(args)

// plot array [1, 6, 2, -5, 2].plot; (0..100).normalize(0, 8pi).sin.plot; // nested arrays { (0..100).normalize(0, 15.0.rand).sin }.dup(3).plot; { { (0..17).normalize(0, 15.0.rand).sin }.dup(4) }.dup(3).plot; // UGen functions { SinOsc.ar([700, 357]) * SinOsc.ar([400, 476]) * 0.2 }.plot; // Buffer { var b = Buffer.read(s, Platform.resourceDir +/+ "sounds/SinedPink.aiff"); s.sync; b.plot }.fork(AppClock); // Env Env.perc(0.4, 0.6).plot;

plotGraph(n,from,to,...)

{ |x| sin(x) }.plotGraph(300, 0, 2*pi); { |x| sin(1/x) * x }.plotGraph(from: 0.0001, to: 0.2);

Class Methods

Plotter.new(name, bounds, parent)

Arguments:

name	Plot window title.
bounds	The window bounds (a Rect).
parent	Either a Window / View may be passed in - then the plot is embedded. Otherwise a new Window is created.

Discussion:

Inherited class methods

Instance Methods

Embedding in another view

.makeWindow(argParent, argBounds)

Open given plotter in a new window or within a given composite view.

See the Embedding in another View or GUI example.

Arguments:

argParent	Either a Window or View may be passed in - then the plot is embedded. Otherwise a new Window is created.
argBounds	The window bounds (a Rect).

Plot properties

.plotMode

.plotMode = modes

Get/Set the style of data display. This can be an array of different modes for multi-channel data. Available modes:

`\linear`	connecting data points with linear interpolation
`\points`	draw data points only
`\plines`	combination of lines and points
`\levels`	horizontal lines
`\steps`	connecting data points with step interpolation
`\bars`	bar graph with filled bars

Arguments:

modes

A Symbol or an Array of Symbols.

If modes.size < numChannels, the plots will wrap around the array of modes.

Returns:

An Array of Symbols, unless there is only one mode specified or if all modes of a multi-channel plot are the same, in which case a single Symbol is returned.

Discussion:

.plotColor

.plotColor = colors

Set or get the colors of your data plot.

Arguments:

colors

This can be an Array of Colors for multichannel data, or a single Color to map to all channels.

If colors.size < numChannels, the plots will wrap around the array of colors.

Returns:

An Array of Colors, unless there is only one color specified or if all colors of a multi-channel plot are the same, in which case a Color is returned.

.superpose

.superpose = flag

If true, plotter displays channels overlaid on a single plot. (keyboard shortcut: s)a = { (0..30).scramble }.dup(2).plot; a.superpose = true; a.refresh;

.labelX

.labelX = labels

Get/set the label for the x-axes. Can be a String or an Array of Strings, or nil to remove the label. See Axis labels example below.

.labelY

.labelY = labels

Get/set the label for the y-axes. Can be a String or an Array of Strings, or nil to remove the label. See Axis labels example below.

.setProperties( ... pairs)

Set properties of all plot views. Defaults are taken from GUI.skins.at(\plot);

WARNING: It's preferrable to use Plotter's instance methods when possible to set Plot properties to ensure proper behavior when using -superpose.

Arguments:

... pairs

A list of symbol,value pairs. Supported properties:

font
fontColor
gridColorX
gridColorY
plotColor (an Array)
backgroundColor
gridLinePattern
gridLineSmoothing ( Boolean )
labelX
labelY
gridOnX ( Boolean )
gridOnY ( Boolean )

Discussion:

Example:( a = { (0..30).scramble }.dup(2).plot; a.setProperties( \fontColor, Color.red, \plotColor, Color.blue, \backgroundColor, Color.black, \gridColorX, Color.white, \labelX, "Humidity" ); a.refresh; ); GUI.skins.at(\plot); // defaults

.plots

Returns:

An Array of Plots.

Data display properties

.specs

.specs = argSpecs

Set or get the spec for the y-axis (codomain).a = { (40..3000).scramble }.dup(2).plot; a.specs = \freq.asSpec; a.refresh;

See also the Explicit domain and axis specs example below.

NOTE: The y-axis label will update with the units assigned to your spec, if it has not been previously set.

.domainSpecs

.domainSpecs = argSpecs

Set or get the spec for the x-axis (domain).a = { (40..300).scramble }.dup(2).plot; a.domainSpecs = \freq.asSpec; a.refresh;

See also the Explicit domain and axis specs example below.

NOTE: The x-axis label will update with the units assigned to your spec, if it has not been previously set.

Discussion:

The default domainSpec when setting your Plotter -value is a linear spec in the range [0, value.size-1]. Unless you set -domain, your values are displayed as evenly sampled between the minval and maxval of the domainSpecs.

If a new -value is set, you will need to update your domainSpecs.

.domain

.domain = domainArray

Set or get the x-axis positions of your data points. The size of the domainArray must equal the size of your value array, i.e. a domain value specified for each data point.( var data, domain, plot; domain = 25.collect({rrand(0, 50)}).sort; data = domain.linlin(0, 50, 0, 1); plot = data.plot.plotMode_(\points); plot.domainSpecs_([0, 50].asSpec); plot.domain_(domain); )

See also the Explicit domain and axis specs example below.

Discussion:

Domain values are mapped into the range of the -domainSpecs, so need not be evenly distributed. If -domain is set to nil, your values are displayed as evenly sampled between the minval and maxval of the -domainSpecs.

Currently, for multichannel data plots, it's assumed that all channels of data share a single -domain. I.e. domainArray must be an Array of rank 1.

If a new -value is set, you will need to update your -domain.

.resolution

.resolution = value

Set the minimum number of pixels between data points (default: 1)// Changing plot resolution (x-axis) p = 5000.collect({ |i| sinPi(i * 0.0025) }).plot; p.resolution_(5).refresh; // 5px p.resolution_(10).refresh; p.resolution_(50).refresh; // undersampled p.resolution_(1).refresh; // default

Plot data

.value

.value = arrays

Return or set the data values. Data may be numerical arrays of up to 3 dimensions.a = [1, 4, 2, 7, 4].dup(2).plot; a.value;

.setValue(arrays, findSpecs: true, refresh: true, separately: true, minval, maxval, defaultRange)

Set the data values, with additional arguments determining how the plot is updated.

Arguments:

arrays	Arrays of data to plot. Data may be numerical arrays of up to 3 dimensions.
findSpecs	A `Boolean`. If `true` (default), bounds of the plot(s) are determined automatically. If `false`, previous bounds will persist.
refresh	A `Boolean`. If `true` (default), refresh the view immediately.
separately	A `Boolean`. If `true` (default), min and max of each set of data will be calculated and displayed separately for each plot. If `false`, each plot's range on the y-axis will be the same.
minval	(Optional) The minimum value displayed on the y-axis.
maxval	(Optional) The maximum value displayed on the y-axis.
defaultRange	(Optional) A default range for the y-axis in the case that the max and min values of the data are identical.

.findSpecs

.findSpecs = value

If true, specs are derived from new data (using min and max values) automatically. Default: true.

.data

Reference to the current internal data (with shape up to depth of 3).

Edit mode

.editMode

.editMode = value

If the edit mode is set to true, the data may be edited via cursor.a = (0..20).plot; a.editMode = true; // now edit the data by clicking into the plot.. a.value; // the updated values

.editFunc

.editFunc = value

Supply a function which is evaluated when editing data. The function is called with the arguments: plotter, plotIndex, index, val, x, y.

Discussion:

Example:( a = { (0..10).scramble.normalize }.dup(2).plot; a.editMode = true; a.editFunc = { |...args| args.postln }; ); // using plotter as a control interface ( a = (0..10).scramble.normalize(300, 400).plot; a.specs = \freq; a.plotMode = \points; a.editMode = true; x = { SinOsc.ar(\freq.kr(a.value)).mean * 0.1 }.play; a.editFunc = { |plotter, plotIndex, i, val| x.setn(\freq, a.value) }; a.parent.onClose = { x.release }; ); ( a = { (0..10).scramble.normalize(300, 400) }.dup.plot; a.specs = \freq; a.plotMode = \bars; a.editMode = true; x = { var phase = SinOsc.ar(\rate.kr(a.value[1])); SinOsc.ar(\freq.kr(a.value[0]), phase).mean * 0.1 }.play; a.editFunc = { |plotter, plotIndex, i, val| x.setn(\freq, a.value[0]); x.setn(\rate, a.value[1]); }; a.parent.onClose = { x.release }; );

.cursorPos

Returns:

The last cursorPos (a Point).

Inherited instance methods

Undocumented instance methods

.bounds

.bounds = value

.calcDomainSpecs

.calcSpecs(separately: true, minval, maxval, defaultRange)

.draw

.drawBounds

.drawFunc

.drawFunc = value

.editData(x, y)

.editPlotIndex

.editPos

.getDataPoint(x, y)

.interactionView

.makePlots

.maxval = val

.minval = val

.name

.name = value

.normalized

.normalized = value

.numChannels

.numFrames

.parent

.parent = value

.postCurrentValue(x, y)

.print

.refresh

.updatePlotBounds

.updatePlotSpecs

.updatePlots

Examples

(
a = Plotter("the plot", Rect(600, 30, 600, 400));
a.value = (0..100).normalize(0, 8pi).sin;
)

a.value = { |i| (0..90) % (i + 12) + ( (0..90) % (i + 2 * 1) ) }.dup(3);
a.value = (0..12).squared;
a.plotMode = \points; a.refresh;
a.plotMode = \levels; a.refresh;
a.plotMode = \plines; a.refresh;

a.domainSpecs = [[0, 115, \lin, 1]]; a.refresh;

a.parent.close; // close window
a.makeWindow;    // open it again

a.value = { (0..70).scramble }.dup(3);
a.plotMode = \linear; a.refresh;
a.value = { |i| (0..2000).normalize(0, 4pi + i).sin } ! 4; // lots of values, test efficiency
a.value = { |i| (0..10000).normalize(0, 8pi + i).sin } ! 3; // lots of values, test efficiency
a.value = { (0..140).scramble } ! 7;

a.value = { |i| (0..90).normalize(0, 8pi + (i*2pi)).sin } ! 2 * [400, 560] + 700;
a.value = { |i| (_ + 2.0.rand).dup(100).normalize(0, 8pi + i).sin } ! 2 * 400 + 700;

// Multi channel expansion of single values
a.value = { |i| (_ + 2.0.rand).dup(100).normalize(0, 8pi + i).sin *.t [1, 2, 3] } ! 2 * 400 + 700;
a.value = { |i| (0..10) **.t [1, 1.2, 1.3, 1.5] * (3.5 ** i) }.dup(3);

a.parent.bounds = Rect(400, 100, 500, 700);
a.parent.bounds = Rect(600, 30, 500, 300);

a.superpose = true;
a.value = { |i| (0..20) * (3.5 ** i) }.dup(5);
a.superpose = false;

Object .plot methods

Explicit domain and axis specs

// data
a = (50..90).midicps.scramble.plot;
// specs (y-axis)
a.specs = ControlSpec(100, 2000, units: "Hz"); a.refresh;

a.value = 50.collect{ exprand(1e4, 1e7) };
a.specs = [1e4, 1e7, \exp].asSpec; a.refresh;

// domainSpecs (x-axis)
// If domain is unassigned, values are
// distributed evenly within the spec range
a.domainSpecs = [-10, 70].asSpec; a.refresh;

// Setting the domain, run the full block:
(
var ys, xs; // ys: data, xs: domain positions
var rs = 0, plt2;

// xs are the sample points over a 2pi range

// sample locations, normalized
xs = 50.collect({rrand(0.05, 1)}).normalizeSum;
xs.do{ |me, i| xs[i] = me + rs; rs = rs + me; };

// force beginning/end to land on 0/2pi
xs[0] = 0;
xs[xs.size-1] = 1;

// scale these points to a 2pi range
xs = xs * 2pi;

// ys are the values of the sinusoid at the sampled points
ys = sin(xs);

// the uneven sampling is apparent when
// displayed as uniformly sampled
ys.plot("original data plot, uniform domain", [100, 100, 385, 285].asRect);

// generate a second plot whose domainSpec is specified:
// we see a smooth sinusoid cycle beginning
// at 0 and ending at 2pi
plt2 = ys.plot("resampled domain", [100+400, 100, 385, 285].asRect);

// domain values place plotted points where they
// actually sampled the sinusoid, thus visually
// reconstructing it.
plt2.domain = xs;

// these values are placed within the domainSpec
// so we can pad the plot on either side.
plt2.domainSpecs_(([-0.5pi, 2.5pi]).asSpec);
)

// Non-linear scaling of axes.
// plot 1000 values, linearly distributed on X and Y
p = (1, 2 .. 1000).plot.domainSpecs_([1, 1000, \lin].asSpec).refresh;
// scale y axis exponentially
p.specs_([[1, 1000, \exp].asSpec]).refresh;
// then scale x axis exponentially
p.domainSpecs_([1, 1000, \exp].asSpec).refresh;

Axis labels

Embedding in another View or GUI

Changing global defaults

The default styles are kept (and may be overridden) in GUI.skins.at(\plot). See also GUI help.// specify plot layout ( GUI.skins.plot.gridLinePattern = FloatArray[1, 0]; GUI.skins.plot.fontColor = Color(0.5, 1, 0); GUI.skins.plot.gridColorX = Color.yellow(0.5); GUI.skins.plot.gridColorY = Color.yellow(0.5); GUI.skins.plot.background = Color.black; GUI.skins.plot.plotColor = Color.red; GUI.skins.plot.labelX = "X"; GUI.skins.plot.labelY = "Y"; ) ( x = { |i| (0..60).scramble * (3.5 ** i) }.dup(3); x.plot("ARRAY:PLOT", Rect(200, 300, 600, 500)); ) GUI.skins.plot.put(\plotColor, { Color.rand(0.0, 0.8) } ! 8); [(0..100), (20..120), (40..140)].squared.flop.bubble.plot; // reset the defaults: Plot.initClass;

helpfile source: https://github.com/supercollider/supercollider/tree/develop/HelpSourceClasses/Plotter.schelp
link::Classes/Plotter::

Plotter : Object

plot(args)

plotGraph(n,from,to,...)

Plotter.new(name, bounds, parent)

Arguments:

Discussion:

.makeWindow(argParent, argBounds)

Arguments:

.plotMode

.plotMode = modes

Arguments:

Returns:

Discussion:

.plotColor

.plotColor = colors

Arguments:

Returns:

.superpose

.superpose = flag

.labelX

.labelX = labels

.labelY

.labelY = labels

.setProperties( ... pairs)

Arguments:

Discussion:

.plots

Returns:

.specs

.specs = argSpecs

.domainSpecs

.domainSpecs = argSpecs

Discussion:

.domain

.domain = domainArray

Discussion:

.resolution

.resolution = value

.value

.value = arrays

.setValue(arrays, findSpecs: true, refresh: true, separately: true, minval, maxval, defaultRange)

Arguments:

.findSpecs

.findSpecs = value

.data

.editMode

.editMode = value

.editFunc

.editFunc = value

Discussion:

.cursorPos

Returns:

.bounds

.bounds = value

.calcDomainSpecs

.calcSpecs(separately: true, minval, maxval, defaultRange)

.draw

.drawBounds

.drawFunc

.drawFunc = value

.editData(x, y)

.editPlotIndex

.editPos

.getDataPoint(x, y)

.interactionView

.makePlots

.maxval = val

.minval = val

.name

.name = value

.normalized

.normalized = value

.numChannels

.numFrames

.parent

.parent = value

.postCurrentValue(x, y)

.print

.refresh

.updatePlotBounds