.TH SNDPATH 1carl CARL
.SH NAME
sndpath \- create/edit a sound trajectory
.SH SYNOPSIS
.B sndpath 
[
.B -b
] [ plotfile ]
flags: 
.TP
.B -b
don't print box around edge of screen.
.br
.B Plotfiles
are created with the 
.B P
command, and have .p as a suffix.  Leave off the suffix when
naming a plotfile.
.SH DESCRIPTION
.B sndpath 
is an interactive program to produce and edit two dimensional sound 
trajectories or
paths.  It works on ordinary CRT terminals by using the curses(3)
screen control package.  The user is presented with a rectangle the size
of the screen with a '+' sign in the middle indicating the center of the
sound space.  Four numbers surround the '+' representing the four speakers
typically used to reproduce such sound paths.  The user marks the locations
the sound is to pass through in the order they occur.  
On command,
.B sndpath 
draws a smooth curve (a cubic spline function) through the points the user
has specified,
creating the trajectory.  The user then writes out the spline function to
a file.  The file can be in a variety of formats, suitable for digestion
by various programs that can control sound distribution in space, such as
.I cmusic(1carl).
Commands exist in
.B sndpath 
to modify, append and delete points on the path. 
The area
covered by the screen display can be scaled to represent 
a range from a few meters to many kilometers.
.SH File Formats
There are three file formats 
.B sndpath
can create files of:
1) binary floating point functions,
2) text functions, and
3) screen plots.
.IP 1)
Binary floating point function files are written with the 
.I w
command (see below).  
.B sndpath
prompts for a filename, then writes two files: filename.x and filename.y
(the .x and .y are added automatically, you just supply the filename part).
These two files contain the x and y coordinate values, respectively,
of the path, in binary floating point format (called floatsams).  In this
format, the two files can be read into 
.I cmusic
via the
.I genraw(1carl)
function handling program for 
.I cmusic.
.IP 2)
Text function file format, which is written with the
.I W
command,
contains [x,y] coordinate pairs for each point on
the path arranged as one coordinate pair per line.  
The file is in text format.  This format is useful for two particular
applications.  First, the path can be passed to 
.I graph(1)
and
.I plot(1)
for rendering on a high resolution printer.  Also, this is suitable
for another function handling program 
called
.I quad(1carl), 
which implements Chowning-style spacial manipulation.
Text function files have a .t appended to the name automatically.
.IP 3)
Lastly, the 
.B sndpath
representation of the screen image can be saved in a plot file.
These are written with the
.I P
command.
Plot files contain summaries of the state of the display.  A 
.B sndpath
plot can be saved this way such that it can be retrieved by
.B sndpath
for further editing.  
There are two ways of retrieving a plot file for editing.
First is to name it (without the .p suffix) when starting 
.B sndpath.
Inside 
.B sndpath,
the
.I r
command reads a plot file previously created with a
.I P
command.  (Again, leave off the .p).  The
.I a
command appends the named plot file to the current contents of the screen.
.SH Commands
.RS 0.5i
.nf
q	quit sndpath,
?	print a help message,
u i o j l m , .	move cursor one position,
U I O J  K L M < >	slam cursor to window edge, K to center,
x [spacebar]	put/remove a node where cursor is,
y p	yank a node, place a node,
[RETURN]	draw spline curve through nodes,
e E	erase spline curve, erase whole screen,
f b	move forward/back to next/previous node,
n	interpolate new point between this and next node,
w       write xy binary floating point function files
W	write text function file
P       write sndpath plot file
r a	read in plot file, append plot file to screen,
t	set time of a node,
:	enter extend mode, 

Extend mode commands:
z		set set zoom size (2.0),
c		set x,y coordinates of center of terrain displayed (0 0)
d		set distance between speakers in meters (5),
P		print nodes,
o		add offset to path (type two blank-separated numbers)
s		scale path (type two blank-separated numbers)
r		rotate path (type degrees of rotation)
i		toggle spline interpolation mode (reset),
n		set number of total spline points plotted (128 average),
t		set time in seconds to scale duration of entire function,
k		set spline constant (0),
p		toggle spline periodic mode (reset),
T		toggle spline time mode (set)
.RE
.SH FILES
There are three kinds of files generated by 
.B sndpath.
.TP
Plot files
These are small text files which contain the state of a plot in ASCII format.
They have a .p filename suffix appended automatically.
Ingredients of the state which are saved include:
.RS .5i
.IP *
interspeaker distance,
.IP *
zoom scaling,
.IP *
number of spline points,
.IP *
x, y, and time position for each X point,
.IP *
spline mode,
.IP *
spline time mode,
.IP *
spline constant.
.RE
.TP
Text x,y files
These are ASCII files of x,y number pairs representing the spline-fitted
curve, suitable for input to, e.g., 
.I graph(1).
No suffix is appended.
.TP
Floatsam files
Two files are written, file.x and file.y which contain x against time and
y against time respectively of the spline-fitted curve, suitable for input
to e.g., 
.I cmusic(1carl).
.SH AUTHOR
Gareth Loy
.SH SEE ALSO
cmusic(1carl), quad(1carl), graph(1), plot(1),
``Sndpath, a Program to Create/Edit Sound Trajectories'', in
/mnt/tutorials/sndpath.dgl locally at CARL.
.SH BUGS
While this paradigm works well for most trajectories, there are pitfalls.
In particular, the spline function places goodness of fit over
everything, including length of the function, so the function length can be
off by as many as 10 points.  
.PP
Spline functions also have other
pathological reactions to certain trajectory specifications.  In
particular, the number of spline
points for a trajectory
is not automatically adjusted to the path.  
For instance, if
1000 spline points are specified for a path of 0 - 100 seconds,
and if two path points are separated by less than .10 of a second,
no spline points will be interpolated between them, and
a perceptable discontinuity can occur.  The solution is to specify
more spline points to be interpolated, or to readjust the trajectory.
