Plotter |
![[cmlogo-small.gif]](gif/cmlogo-small.gif) |
Heinrich Taube
Asst. Prof. Composition/Theory
University of Illinois
Urbana-Champaign, IL 61820
taube@uiuc.edu
|
(plotter
(new plot
points (points :y-values (histo (ran :type :gauss) 1000 -4 4 50)
:x-min -4 :x-max 4)
graph-style ':histogram)
(new plot
points (points :y-values
(loop repeat 50 collect (ran :type :gauss)))
graph-style ':scatter)
:window-title "Gaussian Values and Distribution")
|
- Introduction
- The Plotter Window
- Plotter API
- Examples
- Index
Plotter
Plotter is a graphical interface for graphing, editing and playing back 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.
Plotter is capable of displaying any plot whose data set (points) are encoded as CLOS instances. Up to five slots in the data set 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.
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.
Editing
A Plotter window is a full featured editor that supports mark, point and region selection, independent 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.
Sound
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.
The plotter window consists of four components: the Menu View, the Focus View, the Axis and Plot view.
The Menu View
The menu view at the top of the plotter window organizes all interactions with the window into six main categories.
- File Menu
- The File menu contains commands related to the entire window or to
creating new plots.
- New Plot
- Creates a new plot and adds it to the window.
- Generate Plot
- Generates new data from an external source (process) and adds
it as a new plot or at the currently selected region of the focus plot.
- Open Plotter
- Opens a Plotter window saved in a file.
- Save Plotter
- Saves the window and its plots to a file.
- Save As
- Saves the window and its plots to a new filename.
- Rename Plotter
- Renames the window title.
- Import
- Imports plots from the clipboard or scorefile. Not yet available
- Export
- Exports the window, plot or selected points to the clipboard or text window.
- Edit Menu
- The Edit menu contains commands related to points and region selections./dd>
- 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 All
- Selects entire plot as a single region.
- Select Coordinates/Region
- Converts the current selection to its opposite, i.e. a region is
converted to a coordinate selection and vice versa.
- Search
- Finds and selects points that match search criteria. Not yet available
- Search Again
- Searches again. Not yet available.
- Move
- Move selection to a new position.
- Rescale
- Rescales current selection to new size. Not yet available.
- Quantize
- Quantizes selection to grid size. Not yet available.
- View Menu
- The View Menu allows various display and formatting options to be set.
- 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.
- Sound Menu
- Contains commands related to creating sound from plots.
- Set Output
- Set sound file or port destination. Sound cannot be produced without specifying an output destination.
- Write
- Writes current plot to output destination.
- Write 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.
- Options Menu
- The Options menu contains various editing and selection preferences.
- Region Sweeping
- If active a region sweep with the mouse creates a region
selection otherwise it creates a point selection.
- Back Plots Sensitive
- If active then background plots can be selected by clicking on
their points.
- Lines Sensitive
- If active then clicking on a line will select its end points.
- Help Menu
- The Help Menu holds help commands.
- HTML Help
- Opens HTML help browser.
The Focus View
The Focus View is located 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 in the display is available for editing. This plot
is called the focus plot.
The pop-up menu titled Plots in the upper left corner of the Focus View contains
a listing of all the plots currently loaded into the window. Selecting a new plot
from this menu brings it to the front of the display and makes it the new focus plot.
The typein buffer directly to the right the Plots menu displays the name of
the focus plot and allows it to be edited. If you provide a new name you must press Return before the new name will take effect.
The two lines directly below the name buffer contain six pop-up menus and six associated labels. The labels display items selected from the pop-up menu directly above it. The
menus all relate to points in the plot's data set:
- 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.
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.
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.
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.
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.
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.
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.
Axis Points and Axis 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.
Windows and Views
plotter is a subclass of window. A plotter window can be created using new, make-instance or the plotter function.
The plotter class provides the following initializations:
-
window-title string
-
Sets the title of the window to string. The default title
includes a number indicating how many plotter windows are currently open.
- 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. If plotter
is not specified it defaults to the active plotter window. Otherwise,
plotter should be a window, title or view.
| plotter-close (&optional plotter) |
[Function]
|
Closes plotter and removes it from *plotter-windows*.
If plotter
is not specified it defaults to the active plotter window. Otherwise
plotter should be a plotter window, title or view.
| plotter-rename (name &optional plotter) |
[Function]
|
Renames plotter to the string name and displays
it as the window title.
If plotter
is not specified it defaults to the active plotter window. Otherwise
plotter should be a plotter window, title or view.
| 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.
If plotter
is not specified it defaults to the active plotter window. Otherwise
plotter should be a plotter window, title or view.
| plotter-save-as (&optional file plotter) |
[Function]
|
Saves plotter to file.
If plotter
is not specified it defaults to the active plotter window. Otherwise
plotter should be a plotter window, title or view.
| plotter-export (&key :export :to :format :x-values
:y-values :w-values :h-values :c-values :plotter) |
[Function]
|
blah blah blah
| plotter-menu-view (&optional plotter) |
[Function]
|
Returns the menu view associated with plotter.
If plotter
is not specified it defaults to the active plotter window. Otherwise
plotter should be a plotter window, title or view.
| plotter-plot-view (&optional plotter) |
[Function]
|
Returns the plot view associated with plotter.
If plotter
is not specified it defaults to the active plotter window. Otherwise
plotter should be a plotter window, title or view.
| plotter-axis-view (&optional plotter) |
[Function]
|
Returns the axis view associated with plotter.
If plotter
is not specified it defaults to the active plotter window. Otherwise
plotter should be a plotter window, title or view.
| plotter-focus-view (&optional plotter) |
[Function]
|
Returns the focus view associated with plotter.
If plotter
is not specified it defaults to the active plotter window. Otherwise
plotter should be a plotter window, title or view.
Plot, Axis and Points
A plot associates a list of data points with
five axis descriptions. Plots, axes and points are all CLOS objects
and 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 is a subclass of seq. plot provides the following initializations.
Values for all initializations except points will be determined automatically
if they are not supplied by the user.
- name string
- An optional name for the plot.
- points list
- The list of CLOS instances to be displayed in the plot.
The points initialization 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.
The axis class provides the following initializations.
Axis initializations will be determined automatically from the data
if they are not supplied by the user.
- type type
- Indicates the type of values the axis will display which 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, :hexadecimal, :keynum, :hertz, :note and :none.
The default label type depends on the type value specified to the axis.
- from value
- 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 value
- 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 value
- Specifies 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
- specifies the number of graduals drawn per label.
The default increment value depends on the type value specified to the axis.
- zoom
- Specifies the zoom amount of the axis. Defaults to 100%.
The point class can be used to represent basic 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.
The pointer class can be used to encode arbitrary data as
points in a plot. For example, by assigning processes or seqs to pointers they
can be time-lined in a plot and referenced by more than one point.
The pointer class provides the following initializations:
dl>
x number
The x coordinate value of the point.
y number
The y coordinate value of the point.
thing thing
The datum associated with the pointer, i.e. the thing the pointer "points" to.
| points(&rest args) |
[Function]
|
Returns a list of point objects created from args.
points supports a variety of different argument formats:
Creating points from a series of x and y values:
(points 0 0 25 1 75 1 100 0)
Creating points from single list of x and y values:
(points '(0 0 25 1 75 1 100 0))
Creating points from a y values list and an x values list:
(points :y-values '(0 1 1 0) :x-values '(0 25 75 100))
Creating points from just a y values list. x point values automatically
become integers 0 < length of y values.
(points :y-values '(0 1 1 0))
Creating points from a y values list, an x minimum value and an X maximum value.
:x-min defaults to 0, :x-max defaults to the length of y values - 1.
X point values are distributed evenly between :x-min and :x-max.
(points :y-values '(0 1 1 0) :x-min 10 :x-max 20)
Creating points of a different type with x and y values assigned to appropriate slots:
(points :type 'midi :x-slot 'time :y-slot 'keynum '(0 60 10 20 11 127))
Plots and Plotter Windows
| plotter-plots (&optional plotter) |
[Function]
|
Blah blah blah.
| plotter-focus-plot (&optional plotter) |
[Function]
|
Blah blah blah.
| plotter-add-plot (&optional plotter) |
[Function]
|
Blah blah blah.
| plotter-delete-plot (&optional plotter) |
[Function]
|
Blah blah blah.
| plotter-set-focus-plot (&optional plotter) |
[Function]
|
Blah blah blah.
| plotter-sound-plots (&optional plotter) |
[Function]
|
Blah blah blah.
Editing Functions
All editing functions operate on the "current selection" in the
focus plot.
| plotter-selection (&optional plotter) |
[Function]
|
Blah blah blah.
| plotter-select-region (&key :left :right :top :bottom :plotter) |
[Function]
|
Blah blah blah.
| plotter-double-click (&optional plotter) |
[Function]
|
Blah blah blah.
| plotter-delete-selection (&optional plotter) |
[Function]
|
Blah blah blah.
| plotter-cut-selection (&optional plotter) |
[Function]
|
Blah blah blah.
| plotter-copy-selection (&optional plotter) |
[Function]
|
Blah blah blah.
| plotter-clear-selection (&optional plotter) |
[Function]
|
Blah blah blah.
| plotter-paste-to-selection (&optional plotter) |
[Function]
|
Blah blah blah.
| plotter-merge-to-selection (&optional plotter) |
[Function]
|
Blah blah blah.
| plotter-select-all (&optional plotter) |
[Function]
|
Blah blah blah.
| plotter-convert-selection (&optional plotter) |
[Function]
|
Blah blah blah.
| plotter-move-selection (&optional to plotter) |
[Function]
|
Blah blah blah.
Sound Output Functions
| plotter-write (&optional plotter) |
[Function]
|
Blah blah blah.
| plotter-write-selectoin (&optional plotter) |
[Function]
|
Blah blah blah.
Sin
(plotter (new plot
points (loop with f = 2.5
for x from 0 to 1 by .01
collect (new point x x y (sin (* x f 2 pi)))))
:window-title "A Little Sin")
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")
Midit 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)))))
Last
Modified: 26-Feb-2001
