HelpSource/Classes/Plotter.schelp

   1 class:: Plotter
   2 summary:: Plot numerical data on a window or view
   3 categories:: GUI>Accessories
   4 related:: Reference/plot
   5
   6 description::
   7 Plot data of up to three dimensions on a link::Classes/Window:: or link::Classes/UserView::.
   8
   9 subsection:: Keyboard shortcuts
  10
  11 When the plotter window has focus, the following keyboard shortcuts can be used to change the display:
  12 table::
  13 ## + / - || vertical zoom
  14 ## = || compare plot channels
  15 ## n || toggle normalize display (0..1) / (-1..1), or fit range
  16 ## s || toggle superposition (see: superpose)
  17 ## m || switch plot mode (see: link::Classes/Plotter#plotMode::)
  18 ## e || toggle editing (see: link::Classes/Plotter#editMode::)
  19 ## g || toggle horizontal (domain) grid
  20 ## G || toggle vertical (codomain) grid
  21 ## ctrl-+ / - || zoom font
  22 ## alt-click || post value
  23 ::
  24
  25 subsection:: Method extensions
  26 Plotter extends other classes with methods. To see what classes implements plot, see link::Overviews/Methods#plot::
  27
  28 method:: plot (args)
  29
  30 code::
  31 // plot array
  32 [1, 6, 2, -5, 2].plot;
  33 (0..100).normalize(0, 8pi).sin.plot;
  34
  35 // nested arrays
  36 { (0..100).normalize(0, 15.0.rand).sin }.dup(3).plot;
  37 { { (0..17).normalize(0, 15.0.rand).sin }.dup(4) }.dup(3).plot;
  38
  39 // UGen functions
  40 { SinOsc.ar([700, 357]) * SinOsc.ar([400, 476]) * 0.2 }.plot;
  41
  42 // Buffer
  43 Buffer.read(s, Platform.resourceDir +/+ "sounds/SinedPink.aiff").plot;
  44
  45 // Env
  46 Env.perc(0.4, 0.6).plot;
  47 ::
  48
  49 method:: plotGraph (n,from,to,...)
  50
  51 code::
  52 { |x| sin(x) }.plotGraph(300,0,2*pi);
  53 { |x| sin(1/x)*x }.plotGraph(from:0.0001,to:0.2);
  54 ::
  55
  56 section:: Changing global defaults
  57
  58 The default styles are kept (and may be overridden) in code::GUI.skin.at(\plot)::. See also link::Classes/GUI:: help.
  59
  60 code::
  61 // specify plot layout
  62 (
  63 GUI.skin.plot.gridLinePattern = FloatArray[1, 0];
  64 GUI.skin.plot.fontColor = Color(0.5, 1, 0);
  65 GUI.skin.plot.gridColorX = Color.yellow(0.5);
  66 GUI.skin.plot.gridColorY = Color.yellow(0.5);
  67 GUI.skin.plot.background = Color.black;
  68 GUI.skin.plot.plotColor = (10..0).normalize(0.1, 1).collect { |i| Color.rand(i) };
  69 GUI.skin.plot.labelX = "X";
  70 GUI.skin.plot.labelY = "Y";
  71 );
  72
  73 (
  74 x = { |i| (0..60).scramble.clump(8) * (3.5 ** i) }.dup(3);
  75 x.plot("ARRAY:PLOT", Rect(200, 300, 600, 500));
  76 )
  77
  78 GUI.skin.plot.put(\plotColor, { Color.rand(0.0, 0.8) } ! 8);
  79 [(0..100), (20..120), (40..140)].squared.flop.bubble.plot;
  80
  81 // reset the defaults:
  82 Plot.initClass;
  83 ::
  84
  85 classmethods::
  86
  87 method:: new
  88 argument:: name
  89 Plot window title.
  90 argument:: bounds
  91 The window bounds (a link::Classes/Rect::).
  92 argument:: parent
  93 Either a link::Classes/Window:: / link::Classes/View:: may be passed in - then the plot is embedded. Otherwise a new link::Classes/Window:: is created.
  94 discussion::
  95 code::
  96 (
  97 a = Plotter("the plot", Rect(600, 30, 800, 250));
  98 a.value = (0..1000).normalize(0, 14pi).curdle(0.01).scramble.flat.sin;
  99 )
 100 ::
 101
 102 instancemethods::
 103
 104 subsection:: Accessing Instance Variables
 105
 106 method:: makeWindow
 107 Open given plotter in a new window or within a given composite view.
 108 argument:: argParent
 109 Either a link::Classes/Window:: or link::Classes/View:: may be passed in - then the plot is embedded. Otherwise a new link::Classes/Window:: is created.
 110 argument:: argBounds
 111 The window bounds (a link::Classes/Rect::).
 112
 113 method:: plotMode
 114 Set the style of data display.
 115 argument:: symbol
 116 Available modes:
 117 table::
 118 ## code::\linear:: || connecting data points with linear interpolation
 119 ## code::\points:: || draw data points only
 120 ## code::\plines:: || combination of lines and points
 121 ## code::\levels:: || horizontal lines
 122 ## code::\steps:: || connecting data points with step interpolation
 123 ::
 124 discussion::
 125 code::
 126 a = (0..20).scramble.plot;
 127 a.plotMode = \points; a.refresh;
 128 a.plotMode = \plines; a.refresh;
 129 a.plotMode = \levels; a.refresh;
 130 a.plotMode = \steps; a.refresh;
 131 a.plotMode = \linear; a.refresh;
 132 ::
 133
 134 method:: setProperties
 135 Set properties of all plot views. Defaults are taken from code::GUI.skin.at(\plot);::
 136 argument:: ... pairs
 137 A list of symbol,value pairs. Supported properties:
 138 list::
 139 ## font
 140 ## fontColor
 141 ## gridColorX
 142 ## gridColorY
 143 ## plotColor (an link::Classes/Array::)
 144 ## backgroundColor
 145 ## gridLinePattern
 146 ## gridLineSmoothing ( link::Classes/Boolean:: )
 147 ## labelX
 148 ## labelY
 149 ## gridOnX ( link::Classes/Boolean:: )
 150 ## gridOnY ( link::Classes/Boolean:: )
 151 ::
 152 discussion::
 153 Example:
 154 code::
 155 (
 156 a = { (0..30).scramble }.dup(2).plot;
 157 a.setProperties(
 158         \fontColor, Color.red,
 159         \plotColor, Color.blue,
 160         \backgroundColor, Color.black,
 161         \gridColorX, Color.white,
 162         \labelX, "Humidity"
 163 );
 164 a.refresh;
 165 );
 166
 167 GUI.skin.at(\plot); // defaults
 168 ::
 169
 170 method:: editMode
 171 If the edit mode is set to true, the data may be edited via cursor.
 172 code::
 173 a = (0..20).plot;
 174 a.editMode = true; // now edit the data by clicking into the plot..
 175 a.value; // the value
 176 ::
 177
 178 method:: resolution
 179 Set the number of data points displayed maximally per pixel (default: 1)
 180 code::
 181 a = (0..200).scramble.plot;
 182 a.resolution = 8; a.refresh; // resizing the window shows interpolation
 183 a.resolution = 1; a.refresh;
 184 ::
 185
 186 method:: findSpecs
 187 If true (default: code::true::), specs are derived from new data (using min and max values) automatically.
 188
 189 method::superpose
 190 If set to true, plotter displays channels on top of each other (keyboard shortcut: s)
 191 code::
 192 a = { (0..30).scramble }.dup(2).plot;
 193 a.superpose = true; a.refresh;
 194 ::
 195
 196 method:: value
 197 Return or set the data values. Data may be numerical arrays of up to 3 dimensions.
 198 code::
 199 a = [1, 4, 2, 7, 4].dup(2).plot;
 200 a.value;
 201 ::
 202
 203 method:: data
 204 Reference to the current internal data.
 205
 206 method:: cursorPos
 207 Returns:: the last cursorPos (a link::Classes/Point::).
 208
 209 method:: plots
 210 Returns:: the single subplots (a link::Classes/Plot::).
 211
 212
 213 method:: specs
 214 Set or get the spec for the y-axis (codomain).
 215 code::
 216 a = { (40..3000).scramble }.dup(2).plot;
 217 a.specs = \freq.asSpec; a.refresh;
 218 ::
 219
 220 method:: domainSpecs
 221 Set or get the spec for the x-axis (domain).
 222 code::
 223 a = { (40..300).scramble }.dup(2).plot;
 224 a.domainSpecs = \freq.asSpec; a.refresh;
 225 ::
 226
 227 method:: editFunc
 228 Supply a function which is evaluated when editing data. The function is called with the arguments: code::plotter::, code::plotIndex::, code::index::, code::val::, code::x::, code::y::.
 229 discussion::
 230 Example:
 231 code::
 232 (
 233 a = { (0..10).scramble.normalize }.dup(2).plot;
 234 a.editMode = true;
 235 a.editFunc = { |...args| args.postln };
 236 );
 237
 238 // using plotter as a control interface
 239 (
 240 a = (0..10).scramble.normalize(300, 400).plot;
 241 a.specs = \freq; a.plotMode = \points;
 242 a.editMode = true;
 243 x = { SinOsc.ar(\freq.kr(a.value)).mean * 0.1 }.play;
 244 a.editFunc = { |plotter, plotIndex, i, val|
 245         x.setn(\freq, a.value)
 246 };
 247 a.parent.onClose = { x.release };
 248 );
 249
 250 (
 251 a = { (0..10).scramble.normalize(300, 400) }.dup.plot;
 252 a.specs = \freq; a.plotMode = \levels;
 253 a.editMode = true;
 254 x = {
 255         var phase = SinOsc.ar(\rate.kr(a.value[1]));
 256         SinOsc.ar(\freq.kr(a.value[0]), phase).mean * 0.1
 257 }.play;
 258 a.editFunc = { |plotter, plotIndex, i, val|
 259         x.setn(\freq, a.value[0]);
 260         x.setn(\rate, a.value[1]);
 261 };
 262 a.parent.onClose = { x.release };
 263 );
 264 ::
 265
 266 examples::
 267
 268 code::
 269 // embedding in another GUI
 270 (
 271 w = Window("plot panel", Rect(20, 30, 520, 250));
 272 Slider.new(w, Rect(10, 10, 490, 20)).resize_(2).action_ { |v|
 273         a.value = (0..(v.value * 80).asInteger).scramble;
 274         w.refresh;
 275 };
 276 z = CompositeView(w, Rect(10, 35, 490, 200)).background_(Color.rand(0.7)).resize_(5);
 277 a = Plotter("plot", parent: z).value_([0, 1, 2, 3, 4].scramble * 100);
 278 w.front;
 279 )
 280
 281
 282 (
 283 a = Plotter("the plot", Rect(600, 30, 600, 400));
 284 a.value = (0..100).normalize(0, 8pi).sin;
 285 )
 286
 287 a.value = { |i| (0..90) % (i + 12) + ( (0..90) % (i + 2 * 1) ) }.dup(3);
 288 a.value = (0..12).squared;
 289 a.plotMode = \points; a.refresh;
 290 a.plotMode = \levels; a.refresh;
 291 a.plotMode = \plines; a.refresh;
 292
 293 a.domainSpecs = [[0, 115, \lin, 1]]; a.refresh;
 294
 295 a.parent.close; // close window
 296 a.makeWindow;   // open it again
 297
 298 a.value = { (0..70).scramble }.dup(3);
 299 a.plotMode = \linear; a.refresh;
 300 a.value = { |i| (0..2000).normalize(0, 4pi + i).sin } ! 4; // lots of values, test efficiency
 301 a.value = { |i| (0..10000).normalize(0, 8pi + i).sin } ! 3; // lots of values, test efficiency
 302 a.value = { (0..140).scramble } ! 7;
 303
 304 a.value = { |i| (0..90).normalize(0, 8pi + (i*2pi)).sin } ! 2 * [400, 560] + 700;
 305 a.value = { |i| (_ + 2.0.rand).dup(100).normalize(0, 8pi + i).sin } ! 2 * 400 + 700;
 306
 307
 308 // multi channel expansion of single values
 309 a.value = { |i| (_ + 2.0.rand).dup(100).normalize(0, 8pi + i).sin *.t [1, 2, 3] } ! 2 * 400 + 700;
 310 a.value = { |i| (0..10) **.t [1, 1.2, 1.3, 1.5] * (3.5 ** i) }.dup(3);
 311
 312 a.parent.bounds = Rect(400, 100, 500, 700);
 313 a.parent.bounds = Rect(600, 30, 500, 300);
 314
 315 a.superpose = true;
 316 a.value = { |i| (0..20) * (3.5 ** i) }.dup(5);
 317 a.superpose = false;
 318
 319 // specs
 320
 321 a.value = (50..90).midicps.scramble;
 322 a.specs = \freq; a.refresh;
 323 a.value = (1..60).scramble.neg;
 324 a.specs = \db; a.refresh;
 325
 326 a.value = { |i| { exprand(1e3, (10 ** (i + 8))) }.dup(90) }.dup(3);
 327 a.value = { { exprand(1e3, 1e9) }.dup(90) }.dup(3);
 328 a.specs = [[1e3, 1e10, \exp], [1e3, 1e20, \exp], [1e3, 1e30, \exp]]; a.refresh;
 329 a.domainSpecs = [[0, 5], [-8, 100], [-1, 1]]; a.refresh;
 330
 331
 332 // Array:plot
 333 (
 334 a = (4 ** (-5..0)).postln.plot;
 335 a.specs = \delay; a.refresh;
 336 a.domainSpecs = [0, 10, \lin, 0, 0, " Kg"].asSpec; a.refresh;
 337 );
 338
 339 a.domainSpecs = [0.1, 10, \exponential, 0, 0, " Kg"].asSpec; a.refresh;
 340 a.domainSpecs = [-10, 10, \lin, 0, 0, " Kg"].asSpec; a.refresh;
 341
 342
 343 a = [(0..100) * 9, (200..1300) * 2, (200..1000)/ 5].plot;
 344 a.superpose = true;
 345
 346 a = [[0, 1.2, 1.5], [0, 1.3, 1.5, 1.6], [0, 1.5, 1.8, 2, 6]].midiratio.plot;
 347 a.plotMode = \levels; a.refresh;
 348 a.superpose = false;
 349
 350
 351 // Function:plot
 352 a = { SinOsc.ar([700, 357]) * SinOsc.ar([400, 476]) * 0.2 }.plot;
 353 a = { SinOsc.ar([700, 357] *0.02) * SinOsc.ar([400, 476]) * 0.3 }.plot(0.2, minval: -1);
 354 a = { SinOsc.ar(440) }.plot(1);
 355
 356
 357 // Env:plot
 358 Env.perc(0.4, 0.6).plot;
 359 Env.new({ 1.0.rand2 }! 8, { 1.0.rand } ! 7, \sin).plot;
 360
 361 // Buffer:plot
 362 b = Buffer.read(s, Platform.resourceDir +/+ "sounds/SinedPink.aiff");
 363                 // Platform.resourceDir +/+ "sounds/SinedPink.aiff" contains SinOsc on left, PinkNoise on right
 364 b.plot;
 365 b.free;
 366 ::
 367