Common Music Reference Manual

Top Objects Processes IO Scales Data Patterns Plotter Utilities Index

6 Plotter

Plotter is a graphical interface for graphing, editing and playing musical data. More than one plotter windows can be open at the same time and a single plotter window can contain more than one plot.

Figure 6-1: A Plotter window with two plots.

6.1 Plotter Features

Plotter is capable of displaying any data whose points are encoded as CLOS instances. Up to five slots in the data can participate in the display. Each slot is linked to the display by assigning it to one of the editor's five display dimensions: Horizontal, Vertical, Width, Height and Intensity (color). The display dimensions can be customized so that the appearance (axis, label format, zoom extent, ticks per label etc.) fit the type and magnitude of the associated slot values.

6.1.1 Plots

A plot is an object that associates a set of data points with a set of graphing parameters and axis specifications. The user has many controls over the appearance of each plot, including its graphing style, color, line size, and point shape. Plotter currently supports four different graphing styles: Line Envelope, Scatter Graph, Histogram and Piano Roll. The graphing style of a plot can be changed at any time. As mentioned in the previous section, a Plotter window can contain any number of plots. Each plot defines just a single layer in the plotter's display; layers can be made opaque, transparent or invisible.

6.1.2 Data Editing

A Plotter window is a full featured editor that supports mark, point and region selection, independent axis scrolling and zooming, graphical Move, Add/Delete, Copy/Paste, Merge/Replace, Quantize, Search and Undo/Redo. Editing operations can be performed with the mouse or by typing keyboard shortcuts. All the editing and display operations have a underlying function definition so a Plotter window can also be controlled programmatically from the Lisp Listener. In addition, mouse gestures may have hooks associated with them that call user specified code whenever the appropriate mouse event occurs.

6.1.3 Sound Output

Any plot that defines a Time axis on the Horizontal dimension and has an output method defined for its data set is capable of producing sound. Sound can be output to any file or port destination that Common Music supports. A plotter window can also serve as the destination for musical events that are generated from some external source, for example, from a group of musical processes running in the scheduler.

Figure 6-2

6.2 The Plotter Window

The plotter window consists of four components: the Menu View, the Focus View, the Axis and Plot view.

6.2.1 The Menu View

The menu view holds menus related to the plotter window and its contetx.

The File Menu:

Save

Saves plotter window and its contents to a file.

Save As

Saves plotter window and its contents to a file with a new name.

Load

Loads plotter window and its contents from file.

Rename

Renames plotter window.

Import

Imports coordinate list (x1 y1 ... xn yn) from clipboard.

Export

Exports plot or entire window to clipboard or window.

The Plot Menu:

New Plot

Create and add new plot to plotter window.

Delete Plot

Deletes focus plot from window.

Generate Plot

Generates points from an external source (process) and either adds it to the window as a new plot or to the currently selected region of the focus plot.

Rename Plot

Renames focus plot.

New Axis

Creates new axis for focus plot.

The Edit Menu:

Undo

Undoes the last command. Not yet available

Redo

Cancels an undo.

Delete

Deletes selected coordinates.

Cut

If the selection is contiguous along the X axis Cut removes selected coordinates or region and shifts everything above selection leftward.

Copy

Copies selection to the clipboard

Paste

Pastes contents of clipboard to the edit mark or region. Pasting to a region replaces the current region contents with the pasted material.

Merge

Like paste but merges new material into existing material.

Clear

Collapses the current selection.

Select

Selects a specified region.

Select All

Selects entire plot as a single region.

Select Points/Region

Converts the current selection to its opposite, i.e. a region is converted to a point selection and vice versa.

Find

Finds and selects points that match search criteria. Not yet available

Move

Move current selection to a new position.

Rescale

Rescales current selection to new size. Not yet available.

Quantize

Quantizes selection to grid size. Not yet available.

The View Menu:

Line Segment

Displays focus plot in point and line (envelope) style.

Scatter Plot

Displays focus plot as points without lines.

Piano Roll

Displays focus plot as rectangular points without lines.

Histogram

Displays focus plot in a bar format, with points and vertical lines.

Zoom In

Zooms both X and Y dimensions simultaneously.

Zoom Out

Zooms both X and Y dimensions simultaneously.

Fit Window

Zooms X and Y dimensions such that entire plot fits in current window.

Show Grid

Displays background grid.

Show Back Plots

Make all plots visible in window with focus plot on top.

Show Mouse Guide

Draws mouse guide on mouse down.

The Sound Menu:

New Output

Open new output destination for sound.

Set Output

Set sound file or port destination. Sound cannot be produced without specifying an output destination.

Output

Writes current plot to output destination.

Output Selection

Writes selected points to output destination.

Mix

Opens Mix worksheet with sound plots available for mixing.

Hush

Stops current sound playback.

Mute Selection

Marks selected points as unavailable for sound output.

Unmute Selection

Marks selected points as available for sound output.

Record

Record events via MIDI input. Not yet available.

The Options Menu:

Region Sweeping

If enabled a region sweep with the mouse creates a region selection otherwise it creates a point selection.

Back Plots Sensitive

If enabled then background plots can be selected by clicking on their points.

Lines Sensitive

If enabled then clicking on a line will select its end points.

The Help Menu:

HTML Help

Opens HTML help browser.

6.2.2 The Focus View

The Focus View is located directly under the Menu View. It displays information about the current focus plot. A plotter window can display more than one plot at a time but only the forward-most plot, called the focus plot, is available for editing.

The first line in the focus view contains five pop-up menus. THe second line contains a row of labels. Each label is associated with the menu directly above it.

Point Class

Holds the list of available classes for creating new points in the Plot View. New points cannot be created if a class is not visible in the label beneath the menu. To add a new point of the specified point class click the mouse button with the Command key depressed, 1er. COMMAND-<click<.

Horizontal

Contains a list of slots available for placing on the horizontal (X) dimension. Only slots belonging to the current Point Class are selectable in the menu. A slot for the Horizontal dimension must be visible in the associated label or points will not be visible in the plot view. Slot values along the Horizontal axis must be in monotonically increasing order.

Vertical

Contains a list of slots available for placing on the vertical (Y) dimension. Only slots belonging to the current Point Class are selectable in the menu. A slot for the Vertical dimension must be visible in the associated label or points will not be visible in the plot view.

Width

Contains a list of slots available for placing on the Width (W) dimension. Width can be a constant plotting value or a slot in the data set. Only slots belonging to the current Point Class are selectable in the menu.

Height

Contains a list of slots available for placing on the Height (H) dimension. Height can be a constant plotting value or a slot in the data set. Only slots belonging to the current Point Class are selectable in the menu.

Color

Contains a list of slots available for placing on the Color (C) dimension. Color can be a constant plotting value or a slot in the data set. Only slots belonging to the current Point Class are selectable in the menu.

6.2.3 The Axis View

The Axis view displays the axis lines and labels along the x and y dimensions. Clicking anywhere in axis tick area will set an edit mark at that position on the axis. Mouse-<sweep> in the axis tick area to establish a region selection in the plot data.

Each dimension has three control icons in the lower right corner of the view. The first icon (a tiny axis) opens an Axis Dialog for customizing various axis display parameters. The second icon (a tiny square ) "zooms out" along that axis. The third icon (a slightly larger square) "zooms in" along that axis.

6.2.4 The Plot View

The plot view contains the point display of the focus plot. Other plots may be visible in the background if the Background Plots Option is on.

6.2.4.1 Selecting Points

Mouse-<click> or Shift-Mouse-<click> on top of a point to select it. If the Lines Sensitive option is on then Mouse-<click> on a line will select the end points of the line. If the Region Sweeping option is off then Mouse-<sweep> will select all the points under the region.

6.2.4.2 Adding Points

To add points to a plot first select the appropriate point class from the Point Class menu and then Command-Mouse-<click> on the appropriate position in the view to add a new point.

6.2.4.3 Editing Points

Mouse-<double-click> on one or more points to edit the selected material in an editor. If more than one point is edited a * will be visible as the last character the editor's title.

6.2.4.4 Region vs Point Selection

If the Region Sweeping option is on, Mouse-<sweep> establishes a region selection. All editing operations in the Edit Menu can operate on either region selections or point selections. The essential difference between a region selection and a point selection is that Copy, Cut,Paste, etc. respect a region selection's geometric area as well as the points contained by the region. So, for example, if a region established along the x axis is Cut then the region's geometric area in the plot is deleted and all points after the cut are moved leftward by the amount of x space claimed by the cut. In contrast, Cut on a point selection simply deletes the selected points from the plot without affecting any other point positions in the plot.

6.2.4.5 Axis Points and Regions

Clicking in the tick area of the axis view will establish an edit point. Pasting material to an edit point will move all material past the edit point rightwards by the amount of x space the pasted material claims. Pasting to a region along the X axis will replace the contents of the region with the pasted material and then either left-shift or right-shift later material depending on the size of the pasted material relative to the replaced region.

6.3 Plotter Programming Interface

6.3.1 Plotter Windows

The following classes and functions relate to plotter windows. Functions that operate on plotter windows all accept an optional plotter argument, the plotter window to operate on. The value of plotter can be a plotter window, a plotter window title (string) or a subview of a plotter window. If plotter is not specified it defaults to the most recently active plotter window.

plotter [Class]

plotter is a subclass of window. A plotter window can be created using new, make-instance or the plotter function.

plotter supports the following initializations:

window-title string

Sets the title of the window to string

window-position point

The MCL point position for the plotter window to be placed on the screen.

window-size point

The width and height of the plotter window encoded as an MCL point.

window-show {t | nil}

If true the plotter window is made visible. otherwise the window is returned without appearing on the screen. The default is to show the window if it is created using plotter and to not show the window automatically if it is created using new or make-instance.

undo-length integer

The length of the undo command stack, defaults to 8.

file pathname

The name of the file to save the window in. If no file is specified the user will be prompted when the window is first saved.

output io

The sound output destination (file or port).

plotter &rest args [Function]

Creates a new plotter window. args can be plotter initializations and plot objects.

plotter-window &optional plotter [Function]

Returns the plotter window referenced by plotter.

plotter-close &optional plotter [Function]

Closes plotter and removes it from *plotter-windows*.

plotter-rename name &optional plotter [Function]

Renames plotter to the string name and displays it as the window title.

plotter-save &optional plotter [Function]

Saves plotter to a file. The user will be prompted for a file name if no file is currently associated with the window.

plotter-save-as &optional file plotter [Function]

Saves plotter to file.

plotter-export &key :export :to :format :x-values :y-values :w-values :h-values :c-values :plotter [Function]

Exports current plotter window.

plotter-menu-view &optional plotter [Function]

Returns the menu view associated with plotter.

plotter-plot-view &optional plotter [Function]

Returns the plot view associated with plotter.

plotter-axis-view &optional plotter [Function]

Returns the axis view associated with plotter.

plotter-focus-view &optional plotter [Function]

Returns the focus view associated with plotter.

6.3.2 `plot`, `axis` and `point`

Associates a list of data points with five axis descriptions. plot, axis and point objects can be created using the new macro or the make-instance function. The points in a plot can be any list of CLOS instances. Point instances are linked to the display by assigning appropriate slots to the display dimensions Horizontal (X), Vertical (Y), Width (Z), Height (H) and Color (C).

For sake of convenience plotter provides the point and pointer classes as convenient point representations, and the function points can be used to parse numerical data in a variety of formats into a point list suitable for displaying in a plot.

plot [Class]

plot is a subclass of seq. Subobject in a plot are treated as graphing points by plotter windows.

plot supports the following initializations:

name string

An optional name for the plot.

points list

The list of CLOS instances to be displayed in the plot. points can also be specified as data.

data-class class

The name of the class for new points. Defaults to the class of the first point in points.

x-axis axis

The axis object to serve as the Horizontal axis description. Defaults to an axis whose characteristics are determined from the data points or data class. x-axis can also be specified as horizontal-axis.

x-slot symbol

The slot in points to become the Horizontal variable. Defaults to a slot determined from the data points or data class. x-slot can also be specified as horizontal-slot.

y-axis axis

The axis object to serve as the Vertical axis description. Defaults to an axis whose characteristics are determined from the data points or data class. y-axis can also be specified as vertical-axis.

y-slot symbol

The slot in points to become the Vertical variable. Defaults to a slot determined from the data points or data class. y-slot can also be specified as vertical-slot.

z-axis axis

The axis object to serve as the Width axis description. Defaults to the X axis. z-axis can also be specified as width-axis.

z-slot symbol

The slot in points to become the Width variable. Defaults to a slot determined from the data points or data class or nil. z-slot can also be specified as width-slot.

s-axis axis

The axis object to serve as the Height axis description. Defaults to the Y axis. s-axis can also be specified as height-axis.

s-slot symbol

The slot in points to become the Height variable. Defaults to a slot determined from the data points or data class or nil. s-slot can also be specified as height-slot.

c-axis axis

The axis object to serve as the Color axis description. Defaults to an axis whose characteristics are determined from the data points or data class. c-axis can also be specified as color-axis.
c-slot symbol

The slot in points to become the Color variable. Defaults to a slot determined from the data points or data class or nil. c-slot can also be specified as color-slot.

color integer

The color of the plot expressed as an MCL color integer. Defaults to a color selected from the list *named-colors*.

graph-style style

Specifies display style for the plot. style can be one of the four keyword graphing styles: :line,:scatter, :piano-roll and :histogram. Defaults to a style determined from the data points or data class.

point-size point

Specifies a default width and height size for points encoded as a point object. Defaults to a point size determined from the data points or data class.

axis [Class]

The axis class links values in point data with display coordinates.

axis provides the following initializations:

type type

The type of values the axis will display. Influences the choice of default initialization values for the axis. There are currently five axis types: :axis, :time, :keynum, :hertz, and :symbolic. The default value is :axis.

label-type type

The format for printing labels along the axis. There are currently seven label types: :float, :integer, :hexidecimal, :keynum, :hertz, :note and :none. The default label type depends on the type value specified to the axis.

from number

The minimum axis label value. The default minimum value depends on the type value specified to the axis. from can also be specified as minimum.

to number

The maximum axis label value. The default maximum value depends on the type value specified to the axis. to can also be specified as maximum.

by number

The increment between labels displayed on the axis. The default increment value depends on the type value specified to the axis. by can also be specified as increment.

ticks integer

The number of graduals drawn per label. The default increment value depends on the type value specified to the axis.

zoom number

Specifies the zoom amount of the axis. Defaults to 100%.

point [Class]

The point class can be used to represent coordinate data.

point provides the following initializations:

x number

The x coordinate value of the point.

y number

The y coordinate value of the point.

points &rest args &key :y-values :x-values :type :y-min :y-max :x-min :x-max :x-slot :y-slot [Function]

Returns a list of point objects created from args. points supports a variety of different calling formats:

Example 6-1

;; Creating points from a series of x and y values:
(points 0 0 25 1 75 1 100 0)

;; Creating points from a list of x and y values:
(points '(0 0 25 1 75 1 100 0))

;; Creating points from separate x and y value lists
(points :y-values '(0 1 1 0) :x-values '(0 25 75 100))

;; Creating points from a y values list. x values set to positions in y list.
(points :y-values '(0 1 1 0))

;; Creating points from a y values list, :x-min and :x-max values.
(points :y-values '(0 1 1 0) :x-min 10 :x-max 20)

;; Creating points of :type with x and y values assigned to slots:
(points :type 'midi :x-slot 'time :y-slot 'keynum '(0 60 10 20 11 127))

6.3.3 Plots and Plotter Windows

plotter-plots &optional plotter [Function]

Returns a list of all plots in plotter.

plotter-focus-plot &optional plotter [Function]

Returns the focus plot of plotter.

plotter-add-plot plot &optional plotter [Function]

Adds plot to plotter and makes it the new focus plot.

plotter-delete-plot plot &optional plotter [Function]

Deletes plot from plotter.

plotter-set-focus-plot plot &optional plotter [Function]

Makes plot the new focus plot in plotter.

plotter-sound-plots &optional plotter [Function]

Returns the list of sound producing plots in plotter.

6.3.4 Editing Functions

All editing functions operate on the current selection in the focus plot of a plotter window. The plotter window defaults to the most recently active plotter window.

plotter-selection &optional plotter [Function]

Returns the current selection of plotter.

plotter-select-region &key :left :right :top :bottom :plotter [Function]

Creates a region selection out of the rectangle specified in :left, :right, :top and :bottom. These values are in axis coordinates.

plotter-double-click &optional plotter [Function]

Performs the double click action on the current mouse position in plotter.

plotter-delete-selection &optional plotter [Function]

Deletes the current selection of plotter to the clipboard. Delete removes points without shifting remaining points.

plotter-cut-selection &optional plotter [Function]

Cuts the current selection of plotter to the clipboard and moves points to the right of the cut to the start of the cut.

plotter-copy-selection &optional plotter [Function]

Copies the current selection of plotter to the clipboard.

plotter-clear-selection &optional plotter [Function]

Clears the current selection of plotter.

plotter-paste-to-selection &optional plotter [Function]

Pastes the contents of the clipboard to the current selection of plotter. Points to the right of the paste are right-shifted past the end of the paste.

plotter-merge-to-selection &optional plotter [Function]

Merges the contents of the clipboard into the current selection of plotter. Points to the right of the paste are right-shifted past the end of the merge.

plotter-select-all &optional plotter [Function]

Selects the entire focus plot in plotter.

plotter-convert-selection &optional plotter [Function]

Converts the current selection of plotter from a region selection to a point selection and vice versa.

plotter-move-selection &optional to plotter [Function]

Moves current selection of plotter to new selection to.

6.3.5 Sound Output Functions

plotter-write &optional plotter [Function]

Writes focus plot to the open sound output destination.

plotter-write-selection &optional plotter [Function]

Writes current selection of plotter the open sound output destination.

6.4 Plotter Examples

Example 6-2: Plotting sin.

Example 6-3: Plotting an FM spectrum.

(load "cm:contrib;fm.lisp")
(plotter (new plot data (points (fm-spectrum 220 pi 10 :amps t))
              graph-style ':histogram
              x-axis (new axis minimum 0 maximum 10000)
              y-axis (new axis minimum -.4 maximum .4))
         :window-title "FM c=220 mrat=pi, index=10")

Example 6-4: Midi plots in beta and band-pass distribution.

(plotter (new plot 
              data (loop for x = 0 then (+ x (ran ))
                         while (< x 59)
                         collect (new midi time x 
                                      keynum (ran :from 24 :below 96 
                                                  :type ':beta :a .2 ':b .2)
                                      duration (ran :from .5 :below 2))))
         (new plot 
              data (loop for x = 0 then (+ x (ran ))
                         while (< x 59)
                         collect (new midi time x 
                                      keynum (ran :from 24 :below 96 
                                                  :type 'band-pass)
                                      duration (ran :from .5 :below 2)))))