Envelope Editor
by Fernando Lípez Lezcano
CCRMA, Stanford Center for Computer Research in Music and Acoustics

This program allows you to graphically edit envelopes or more general x-y functions. The original purpose of the program was to edit envelopes in text oriented computer music languages like the MusicKit score language, CLM, cmusic, csound, cmix, etc. The problem of interfacing between text and graphics was solved using the pasteboard of the NeXT computer. When copy is selected in the graphical envelope view, a text representation of the envelope is placed in the pasteboard. When paste is selected, the program parses the text found in the pasteboard and draws the envelope.

Editing envelopes:

The graphic window can contain any number of stacked envelope views. To add a new envelope view to the window click the Add button. An envelope is selected and made current by clicking in its view (the selected or current envelope is shown in black).  The Delete button erases the current envelope and removes its view from the window. Just in case, the Undo retrieves the last envelope deleted. A new envelope has only two points with x-y coordinates 0,0 and 1,0.

To move a point:		click on the point and drag
To add a point:		shift-click on the desired location
To erase a point:		shift-click on an existing breakpoint
To make a point the sticky point:	alternate-click on the point

The current point is shown in black and can also be edited by typing numbers in the appropriate fields. The field point changes the currently selected point. The fields x and y change the coordinates of the point. The field yr shows and can alter the real value (I hope!) the envelope reaches at the breakpoint. This value depends on the smoothing parameter (changing yr changes y at constant smoothing, provided that y does not exceed the maximum displayable value). The smoothing can be changed by typing in the field smooth or with the slider next to it (using the slider limits the value to a maximum of 10). The sticky point is shown graphically by a black vertical line and can also be toggled in the current point with the button called stick point.

Here is a complex envelope you can play with that includes smoothing, sticky point and everything. Just select it, copy the text to the pasteboard and paste it to the graphic view:

[(0.000,0.000)(0.097,1.000)(0.150,0.086)(0.170,0.968,7.143)(0.306,-0.061,4.175)(0.330,0.950,3.857)(0.478,0.039,3.540)(0.865,0.115,4.651)(1.185,0.964,0.030)|(1.476,0.032)(1.581,0.384)(1.701,0.294)(2.522,0.642,5.603)(3.000,0.000)]

Drawing limits:
The four limit fields (xmin, xmax, ymin, ymax) let you select the drawing limits for the envelope view.  There are two buttons (last minute addition!) that might help you when building envelopes for different parameters of the same note. The recalc button recalculates the maximum and minimum values for both axis, so as to fit the whole envelope within the boundaries of the window. The link all x's button forces all envelopes to use the x limits of the currently selected envelope. In this way you can more easily see temporal relationships between different envelopes. 

Snap grid:
The snap fields let you select the rounding value of x and y coordinates.  If the x coordinates of two points are less than two snap values apart, snapping turns off. Keep in mind that the program always prints output to the pasteboard to only three decimal places.

Input and Output Formats:
The program automatically parses and can write envelopes with the following formats:

"[(x,y{,s}){|}, ...]"		standard MusicKit format
"(x y ...)"			Lisp list (for CLM and similar languages)
"((x y) ...)"		Lisp list of lists 
"(x,y, ...)"			comma separated list
"x y  ..."			blank separated pairs
"x,y, ..."			comma separated pairs
"x0 y0 z0,x1 y1 z1, ..."	comma separated triads
"x0,y0,z0 x1,y1,z1  ..."	space separated triads
	x=x coordinate of point
	y=y coordinate of point
	s=optional smoothing in MusicKit envelopes
	| (vertical bar)=optional sticky point position in MusicKit envelopes

The output format pop up list lets you select the output format that the program will use when copying an envelope to the pasteboard. The selection is global for all envelopes displayed.
The show smooth button allows you to turn off the drawing of exponential envelope segments. This option is automatically turned off if you paste an envelope in any non-MusicKit format. 

Note: The two "triad" formats are a partial support for cmusic envelopes. The third component is the curvature of the segment and though it is not displayed (yet!) it can be edited numerically in the field smooth. Please note that the separation character between components of a triad and between triads has to be different (so that the software can automatically parse the text representation of the envelope). See also the Defaults Database section for more information useful for cmusic users.

Defaults Database:
The program recognizes three options in the NeXT Defaults Database:

"EnvelopeEd defaultSmoothing 1.0"	
Floating point value that sets the default for the smooth parameter of new points. Default value is 1.0.
	
"EnvelopeEd showSmoothing YES/NO"
Default value of "show smooth" switch. If set to YES (the default) a new envelope shows the MusicKit smoothing. 

"EnvelopeEd drawSegments YES/NO"
Controls segment drawing. If set to YES (the default) both points and segments are drawn. Otherwise only points are drawn (with no connecting segments). 

These options can be examined or changed in a Terminal by using dwrite, dread and dremove (do a "man dwrite" for more information), or you can use the DefaultMgr program by Drew Davidson that is available on the archives. 

Many thanks to:
* Julius O. Smith and David Jaffe for insights into how the MusicKit envelopes work.
* James Pritchett for his edsnd program.
* Ali Ozer and Jayson Adams for the lines example and easy to use UserPaths.

Comments, bug reports or fixes and added features are welcome to the address below:
	Fernando Lípez Lezcano
	nando@CCRMA.stanford.edu

Version 1.04b
- Added libraries so that it can be compiled fat
Version 1.04
- Changed over to NeXTStep 3.x
Version 1.03
- Now parses exponential format numbers.
- Slightly enlarged point cell for functions with more than 999 breakpoints.
Version 1.02:
- Fixed nasty bug in memory allocation routines that was crashing the program with large envelopes.
- Three new options for output format.
- Three options that can be set from the NeXT Defaults Database.
- New menu option to toggle drawing of line segments.