Plotter | SuperCollider 3.14.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;

.axisLabelX

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

.axisLabelY

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

.showUnits

.showUnits = bool

Get/set whether the corresponding ControlSpec: -units are displayed as labels. The state of -unitLocation determines whether the units are shown as axis labels or appended to the tick labels.

Arguments:

bool	A `Boolean`.

Discussion:

When enabling showUnits, axis or tick labels will only be updated to show the units when the axisLabelX/Y or grid labelAppendString properties are nil, empty, or were previously set to show the spec units — i.e. showUnits won't overwrite a label that has been explicitly set.

See Unit labels example below.

.unitLocation

.unitLocation = location

Get/set the label type on which the Spec ControlSpec: -units are shown.

See the Discussion in -showUnits about the interraction with pre-existing labels at the location, and Unit labels example below.

Arguments:

location

A Symbol, \axis or \ticks, to show the units as the axis label or appended to each of the tick labels, respectively.

.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.yellow, \plotColor, Color.magenta, \backgroundColor, Color.black, \gridColorX, Color.green, \gridColorY, Color.green, \labelX, "Frames", \labelFontColor, Color.magenta ); a.refresh; ); GUI.skins.at(\plot); // defaults

.plots

Returns:

An Array of Plots.

Grid properties

.setGridProperties(axis ... propertyPairs)

Set one or more properties of the DrawGridX or DrawGridY used by all Plots.

Arguments:

axis

A Symbol denoting the axis whose grid you're modifying: \x or \y.

... propertyPairs

Key value pairs, listed as successive arguments, of the properties to change and their new values. The property key is a Symbol.

Any of setters of DrawGridX or DrawGridY can be used. Here is a subset of useful properties:

`\labelAnchor`	A `Symbol` denoting the point on the label's bounding Rect that anchors to the point where the grid line meets the base of the axis. `\center, \top, \bottom, \left, \right, \topLeft, \topRight, \bottomLeft, \bottomRight, \leftTop, \rightTop, \leftBottom, \rightBottom`.
`\labelOffset`	A Point describing the offset of the `\labelAnchor` from the point where the grid line meets the base of the axis. The positive direction for the `x` and `y` dimensions is right and down, respectively.
`\labelAlign`	Alignment of the text within its bounding `Rect`: `\left`, `\center`, or `\right`.
`\constrainLabelExtents`	A `Boolean` specifying whether the tick labels at either end of the axis are constrained by, or can extend beyond, the grid bounds.
`\drawBaseLine`	A `Boolean` whether a line is drawn at the minimum extent of this axis.
`\drawBoundingLines`	A `Boolean` whether a line is drawn at both ends of the extent of this axis.
`\drawBoundingRect`	A `Boolean` whether a `Rect` is drawn around the bounds of the grid area.
`\labelAppendString`	A string to append to all of the axis's tick labels.
`\tickSpacing`	Set the minimum spacing between grid lines ("ticks") for each axis. See DrawGrid: -tickSpacing for details.
`\numTicks`	Set the approximate number of grid lines ("ticks") for each axis. See DrawGrid: -numTicks for details.
`\font`	A Font (including size) to be used for the tick labels.
`\fontColor`	The Color of the tick labels.
`\gridColor`	The Color of the axis grid lines.

The properties \drawBaseLine, \drawBoundingLines, or \drawBoundingRect are mutually exlusive — setting any of them to true will set the others two to false. In the context of Plotter, setting \drawBoundingRect on one axis to true has the same appearance of setting \drawBoundingLines on both axes to true.

Discussion:

This is a convenience method to set the grid properties for all Plots to the same values. An Example:( var plotter = [10, 34, 167].collect({ |freq| 101.collect{|i| sin((i/1000) * 2pi * freq)} }).plot; plotter.setGridProperties(\x, \labelAnchor, \topLeft, \labelAlign, \left, \labelOffset, 1 @ 5, \labelAppendString, " samp" ).setGridProperties(\y, \labelAnchor, \right, \labelAlign, \right, \labelOffset, -5 @ 0, \constrainLabelExtents, false ) )

To set the properties of grids on each Plot separately, iterate over the plots:( var plotter, labelAnchors; plotter = [10, 34, 167].collect({ |freq| 101.collect{|i| sin((i/1000) * 2pi * freq)} }).plot; labelAnchors = [\topLeft, \top, \bottomLeft]; plotter.plots.do{ |plot, i| plot.drawGrid.x .labelAnchor_(labelAnchors[i]) .constrainLabelExtents_(true); }; plotter.updatePlotBounds; )

.getGridProperty(axis, property)

Get the value of a grid property. See -setGridProperties for a list of available properties.

Arguments:

axis	A `Symbol` denoting the axis whose grid you're modifying: `\x` or `\y`.
property	The property name as a `Symbol`.

Discussion:

As a convenience method, getGridProperty assumes that properties across all Plots are the same (as would be the case if set by -setGridProperties) so returns a single value. Alternatively, properties from individual plot grids can be collected by iterating over the plots:( // inspect the \labelAnchor of each DrawGridX var plotter = [10, 34, 167].collect({ |freq| 101.collect{|i| sin((i/1000) * 2pi * freq)} }).plot; plotter.plots.collect({ |plot| plot.drawGrid.x.labelAnchor }).postln; )

.drawGridBoundingRect = bool

Set whether a Rect is drawn around the boundary of the grid. Setting to false disables any bounding grid lines (including "base" lines).

Arguments:

bool	A `Boolean`.

Discussion:

In some cases, the GridLines of the grid will not fall on the minimum or maximum of it's spec's range. Using -drawGridBaseLines or -drawGridBoundingRect will give the appearance of grid lines at the lower end ("base") of the grid, or at both ends of the grid, respectively.

.drawGridBaseLines = bool

Set whether a line is drawn at the lower extent of the grid axes. Setting to false disables any bounding grid lines (including a bounding Rect). See also the Discussion in -drawGridBoundingRect.

Arguments:

bool	A `Boolean`.

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;

See also the Explicit domain and axis specs example below.

.domainSpecs

.domainSpecs = argSpecs

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

See also the Explicit domain and axis specs example below.

Discussion:

When setting your Plotter -value, the default domainSpecs is a linear spec in the range [0, value.size-1] (i.e. the indices of the values). Therefore, your values are displayed as evenly sampled between the minval and maxval, unless you have explicitly set the -domain values.

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

.domain

.domain = domainArray

Set/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) }.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; a.updatePlotBounds; // 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

Unit labels

The units of the grid specs are shown as labels, either axis labels or appended to tick labels. Unit labels won't overwrite preexisting labels, and can be disabled altogether.( // units displayed in the axis labels by default p = (4 ** (-1.5, -1.25 .. 0)).plot; p.specs = \delay.asSpec.minval_(0.1); p.domainSpecs = [0, 10, \lin, 0, 0, "xUnits"].asSpec; p.setGridProperties(\y, \constrainLabelExtents, false); p.setGridProperties(\x, \constrainLabelExtents, true); ) p.showUnits = false; // hide units p.unitLocation = \ticks; // move units to tick labels p.showUnits = true; // show units p.axisLabelX = "X LABEL"; // set an axis label p.unitLocation = \axis; // move units to axes // ... x-axis label isn't overwritten p.axisLabelX = nil // remove x-axis label p.unitLocation = \axis; // set units to axes again // ... units now appear on the x-axis // customize the Y labels p.setGridProperties(\y, \labelAppendString, " y"); // move units to tick labels p.unitLocation = \ticks; // ... y-axis tick labels aren't overwritten // now remove y-tick label string p.setGridProperties(\y, \labelAppendString, nil); // set units to tick labels again p.unitLocation = \ticks; // ... units now appear on the y-tick 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: /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:

.plotColor

.plotColor = colors

Arguments:

Returns:

.superpose

.superpose = flag

.axisLabelX

.axisLabelX = labels

.axisLabelY

.axisLabelY = labels

.showUnits

.showUnits = bool

Arguments:

Discussion:

.unitLocation

.unitLocation = location

Arguments:

.setProperties( ... pairs)

Arguments:

Discussion:

.plots

Returns:

.setGridProperties(axis ... propertyPairs)

Arguments:

Discussion:

.getGridProperty(axis, property)

Arguments:

Discussion:

.drawGridBoundingRect = bool

Arguments:

Discussion:

.drawGridBaseLines = bool

Arguments:

.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