Plotter | SuperCollider 3.12.2 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 Buffer.read(s, Platform.resourceDir +/+ "sounds/SinedPink.aiff").plot; // 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

Accessing Instance Variables

.makeWindow(argParent, argBounds)

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

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).

.plotMode

.plotMode = modes

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

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 Symbol is returned.

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

Discussion:

.setProperties( ... pairs)

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

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.skin.at(\plot); // defaults

.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 value

.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

.findSpecs

.findSpecs = value

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

.superpose

.superpose = flag

If set to true, plotter displays channels on top of each other (keyboard shortcut: s)a = { (0..30).scramble }.dup(2).plot; a.superpose = true; a.refresh;

.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.

.data

Reference to the current internal data.

.cursorPos

Returns:

the last cursorPos (a Point).

.plots

Returns:

the single subplots (a Plot).

.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;

.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;

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.

For examples, see -domain and examples.

.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.

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.

Example:( 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); )

A more elaborate example can be found in the examples.

.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.

.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 }; );

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)

.gui

.interactionView

.makePlots

.maxval = val

.minval = val

.name

.name = value

.normalized

.normalized = value

.numChannels

.numFrames

.parent

.parent = value

.pointIsInWhichPlot(point)

.postCurrentValue(x, y)

.prReshape(item)

.print

.refresh

.updatePlotBounds

.updatePlotSpecs

.updatePlots

Examples

// embedding in another GUI
(
w = Window("plot panel", Rect(20, 30, 520, 450));
Slider.new(w, Rect(10, 10, 490, 20)).resize_(2).action_ { |v|
    a.value = (0..(v.value.linexp(0, 1, 5, 8000)).asInteger).scramble;
    w.refresh;
};
z = CompositeView(w, Rect(10, 35, 490, 400)).background_(Color.rand(0.7)).resize_(5);
a = Plotter("plot", parent: z).value_([0, 1, 2, 3, 4].scramble * 100);
w.front;
)

(
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;

// specs

a.value = (50..90).midicps.scramble;
a.specs = \freq; a.refresh;
a.value = (1..60).scramble.neg;
a.specs = \db; a.refresh;

a.value = { |i| { exprand(1e3, (10 ** (i + 8))) }.dup(90) }.dup(3);
a.value = { { exprand(1e3, 1e9) }.dup(90) }.dup(3);
a.specs = [[1e3, 1e10, \exp], [1e3, 1e20, \exp], [1e3, 1e30, \exp]]; a.refresh;
a.domainSpecs = [[0, 5], [-8, 100], [-1, 1]]; a.refresh;

// Array:plot
(
a = (4 ** (-5..0)).postln.plot;
a.specs = \delay; a.refresh;
a.domainSpecs = [0, 10, \lin, 0, 0, " Kg"].asSpec; a.refresh;
);

a.domainSpecs = [0.1, 10, \exponential, 0, 0, " Kg"].asSpec; a.refresh;
a.domainSpecs = [-10, 10, \lin, 0, 0, " Kg"].asSpec; a.refresh;

a = [(0..100) * 9, (200..1300) * 2, (200..1000)/ 5].plot;
a.superpose = true;

a = [[0, 1.2, 1.5], [0, 1.3, 1.5, 1.6], [0, 1.5, 1.8, 2, 6]].midiratio.plot;
a.plotMode = \levels; a.refresh;
a.superpose = false;

// Function:plot
a = { SinOsc.ar([700, 357]) * SinOsc.ar([400, 476]) * 0.2 }.plot;
a = { SinOsc.ar([700, 357] *0.02) * SinOsc.ar([400, 476]) * 0.3 }.plot(0.2, minval: -1);
a = { SinOsc.ar(440) }.plot(1);

// Env:plot
Env.perc(0.4, 0.6).plot;
Env.new({ 1.0.rand2 }! 8, { 1.0.rand } ! 7, \sin).plot;

// Buffer:plot
b = Buffer.read(s, Platform.resourceDir +/+ "sounds/SinedPink.aiff");
        // Platform.resourceDir +/+ "sounds/SinedPink.aiff" contains SinOsc on left, PinkNoise on right
b.plot;
b.free;

// 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;

Changing global defaults

The default styles are kept (and may be overridden) in GUI.skin.at(\plot). See also GUI help.// specify plot layout ( GUI.skin.plot.gridLinePattern = FloatArray[1, 0]; GUI.skin.plot.fontColor = Color(0.5, 1, 0); GUI.skin.plot.gridColorX = Color.yellow(0.5); GUI.skin.plot.gridColorY = Color.yellow(0.5); GUI.skin.plot.background = Color.black; GUI.skin.plot.plotColor = (10..0).normalize(0.1, 1).collect { |i| Color.rand(i) }; GUI.skin.plot.labelX = "X"; GUI.skin.plot.labelY = "Y"; ); ( x = { |i| (0..60).scramble.clump(8) * (3.5 ** i) }.dup(3); x.plot("ARRAY:PLOT", Rect(200, 300, 600, 500)); ) GUI.skin.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: /usr/local/share/SuperCollider/HelpSource/Classes/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:

.setProperties( ... pairs)

Arguments:

Discussion:

.editMode

.editMode = value

.resolution

.resolution = value

.findSpecs

.findSpecs = value

.superpose

.superpose = flag

.value

.value = arrays

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

Arguments:

.data

.cursorPos

Returns:

.plots

Returns:

.specs

.specs = argSpecs

.domainSpecs

.domainSpecs = argSpecs

Discussion:

.domain

.domain = domainArray

Discussion:

.plotColor

.plotColor = colors

Arguments:

Returns:

.editFunc

.editFunc = value

Discussion:

.bounds

.bounds = value

.calcDomainSpecs

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

.draw

.drawBounds

.drawFunc

.drawFunc = value

.editData(x, y)

.editPlotIndex

.editPos

.getDataPoint(x, y)

.gui

.interactionView

.makePlots

.maxval = val

.minval = val

.name

.name = value

.normalized

.normalized = value

.numChannels

.numFrames

.parent

.parent = value

.pointIsInWhichPlot(point)

.postCurrentValue(x, y)

.prReshape(item)

.print

.refresh

.updatePlotBounds

.updatePlotSpecs