CAP
Home ›
Software ›
Manual Pages ›
CAP
Section: User Commands (1)
Updated:
Index
Return to Main Contents
NAME
cap - interactive data capture program
SYNOPSIS
cap
[
-n
] [
-f
runfile
] [
-p
parmfile
]
DESCRIPTION
Cap
captures a
run
of data from the
A/D converter.
A run consists of a set of
triggered channels,
and a set of
untriggered channels.
The triggered channels are stored in a
frame file,
and the untriggered channels are stored in individual
waveform files.
Each channel can be sampled at any rate that is an integer
fraction of the specified sampling rate.
You have the option to
perform a disk capture
or a queued capture.
A disk capture allows a higher transfer rate,
but requires more processing time.
The queued capture allows you to stop the data capture
before the run length has expired, by typing a
Q,
or by limiting the number of sweeps.
The queued capture also allows you
to pause the capture of triggered channels, by hitting SPACE,
or by setting the number of sweeps to capture before an automatic pause.
Cap
allows you to set all required parameters,
and then invokes
qcap
or
dcap
to perform the data capture.
(See
dsepr(1)
for more details about the data capture,
and about the files produced.)
Cap
maintains, in your current directory, the file
default.cap,
which keeps track of all the parameters used for the previous
data capture.
These parameters are used as the defaults for the current capture.
If this file does not exist in your current directory, it will be created.
Also, if there is no
default.cap
in your current directory,
cap
will attempt to load the
cap
parameter file
/usr/neuro/lib/parmgrps/default.cap.
If
cap
is invoked with either the
-n
option, the
-f
option, or the
-p
option, it will not go into its parameter setting mode,
but will invoke
qcap
or
dcap
right away.
The
-n
option will cause all current parameter values to be used for
the capture.
The
-f
option allows you to specify an alternate output file name,
runfile;
all other current parameter values are taken as-is.
The
-p
option allows you to specify a parameter set,
parmfile,
to be loaded;
all parameter values other than the output file name are taken from
this file.
The
parmfile
name can be a simple parameter set name, to be taken from your
current parameter group, or a name of the form
groupname/setname
to load a set from any parameter group.
When
cap
is invoked without any of the above options,
it displays all current parameter values.
A line at the top of the display shows the free disk space remaining
on the current volume.
The right side-bar shows a list of alternate parameter sets which can
be loaded, or a list of parameter groups;
see
PARAMETER SETS
below for details about how to use these.
A parameter is set by pressing the
key corresponding to it, then entering the new parameter value.
See
PARAMETERS
below.
Once you have finished setting the parameters, and wish to proceed to
the data capture, press either
C
or
Q.
The entered parameters are then saved in the file
default.cap,
for the next time you run
cap.
Cap
then invokes
qcap
or
dcap
to perform the capture.
(See
dsepr(1).)
In either case, you will be prompted to hit RETURN
once you are ready to start capturing data.
The capture program will copy the calibration information
into the run header
of the frame file it will create.
If the capture is successful, you will be asked for a
run description.
You can enter one line of text to describe the run of data which
was just captured.
Hit RETURN when done.
Cap
will then attempt to "increment" the file name stored in
default.cap.
The last part of the file name will then be the run number.
If you leave from the parameter setting mode by pressing either
ESCAPE or end-of-file, the parameters will not be saved in
default.cap,
and the capture will not be performed.
Similarly, if you leave from the parameter setting mode by
interrupting
it, usually by typing
Control-C,
the parameters will not be saved, and the capture will not be performed.
PARAMETERS
When
cap
is in the parameter setting mode, you can set any capture
parameter by pressing the
key corresponding to it, then entering the new parameter value.
Any leading or trailing spaces will be stripped away from the
line you enter.
You can also use the arrow keys to move the highlight from one
parameter to another, and use the
RETURN
key to select the highlighted parameter.
On an X Window terminal,
you can also select a parameter by using the mouse to point and click on
any parameter you want, and then type in the new value.
A further mouse click, when cap is waiting for you to enter a value for a
parameter, will be taken as a RETURN key press.
Note that not all parameters on the screen have a particular key associated
with them.
The central part of the screen is the channel table, which features rows
for channels 0 through 15, and for each of these rows there are colums for
the channel name, WF (i.e. waveform) number, divisor, effective rate in Hz,
Tr (trace) number, divisor and rate, and a "checkbox" column, marked with an
X
for the channel that's selected as trigger.
It's best to point and click these entries, on an X Window terminal, but
they can be accessed by the arrow keys as well.
Here is a description of each column of the channel table.
Ch Name
This column shows the number and name of each channel.
You can highlight the number you want, and press RETURN, or click on the
name or number, and you will be prompted for the name of the channel.
This name will be updated right away in your
default.cal
file.
If you have an A/D converter with more than 16 channels, the channel table
can be scrolled:
A + or - sign will appear to the left of this column,
at the top and/or bottom row,
showing that the table can be scrolled by clicking on that sign.
You can also use the up and down arrow keys from within the top or bottom
row of this table to scroll it.
Note that because these channel names are stored in the
default.cal
file, and not
default.cap,
they are also
not
saved in or loaded from stored parameter sets.
WF or Tr
These columns show the waveform number and/or trace number associated with
a particular channel.
When blank, that particular channel will not be captured as a waveform or
trace.
You can set either one, or both if you want the same signal captured twice
as a continuous waveform and as triggered sweeps.
When selecting an empty slot for WF or Tr, you are prompted with the next
available waveform or trace number, but if the slot wasn't empty, the current
number is shown.
Either way, you can hit SPACE to clear the number, if you decide you don't
want this waveform or trace, or you can change the number if you want to
assign the channel to a different wf/trace number in the captured run.
Changing the number will cause any other affected waveform or trace numbers
to be automatically reassigned so there are no gaps or duplicates.
When using the mouse, because a click is taken as a press of the RETURN key
when cap is waiting for a value to be entered, you can quickly add channels
to be captured by double-clicking empty slots in these columns.
Similarly, you can remove any channel by pointing to the WF or Tr number
and using click-SPACE-click, as the SPACE bar clears the value.
Div
These columns show the sampling rate divisor for the corresponding waveform
or trace.
Changing these causes the corresponding effective capture rate in the next
column to be automatically updated.
A divisor of
0
is accepted, but is not recommended, as it will cause the channel to be
captured, increasing overhead, even though none of the data will be kept.
The preferred method of removing a waveform or trace is to blank out the
WF or Tr number as explained above.
Hz
These columns show the effective sampling rate for the corresponding waveform
or trace.
Changing these causes the corresponding rate divisor in the previous
column to be automatically updated.
Note that the effective sampling rate for any channel must divide into the
current Sampling Rate
(R),
described below, as the sampling rate divisor must be a whole number.
If you pick a value that is inappropriate, cap will automatically adjust it
to the closest valid value.
Trig
Clicking or selecting any row in this column will assign this channel as the
trigger channel.
This will only take effect if you've actually selected some channels as
traces by setting the Tr number column.
An
X
will mark the current selection.
The rest of the parameters are those that can be accessed by a single
keystroke, as well as a mouse click.
Below is a description of all of these parameters,
and the keys used to select them.
F File
This selection allows you to select the
output file name.
This name refers to a group of related files.
Each file name generated by the program consists of the specified file name,
followed by a dot and a three character suffix
which indicates the type of the file.
It is recommended that you stick to alphanumeric characters and hyphens in
the file name, as spaces and other punctuation have been known to cause
problems later on.
L Run Length
This selection allows you to select the
run length,
which may be specified as either a number of samples at the sampling frequency,
or as a time value,
as for the pre/post trigger delay and the window duration below.
R Sampling Rate (Hz)
This selection allows you to select the
sampling frequency
(in Hz).
The frequency used may not be exactly what you specify,
since frequencies are generated by dividing a fundamental clock frequency.
K (Q)ueued/(D)isk
This selection allows you to select the
type of data capture:
either a
queued capture
or a
disk capture.
Enter a
Q
for a queued capture, or a
D
for a disk capture.
X Queue Buffer Length
This selection allows you to
change the capture buffer length used by
qcap.
It may be specified as either a number of samples at the sampling frequency,
or as a time value, as for the delay and the window duration below.
Usually, the default value (2 seconds) is acceptable,
but it may be necessary to reduce this if
qcap
fails to lock its pages in physical memory.
This parameter can also be specified as a specific size in bytes,
by entering a real number followed by a
b
(for bytes),
kb
(for kilobytes),
or
mb
(for megabytes).
W Window Dur.
This selection allows you to select the
window duration.
It may be specified as either a number of samples at the sampling frequency,
or as a time value, as for the pre/post trigger delay below.
The window duration, which must be positive,
indicates how long to sample the
triggered channels for each trigger pulse.
P Pre/Post Trigger
This selection allows you to select the
pre- or post-trigger
delay to start of window.
It may be specified either as a number of samples at the sampling frequency,
by entering an integer; or as a time value,
by entering a real number followed by an
s
(for seconds), an
m
(for milliseconds),
or a
u
(for microseconds).
The delay indicates how long to wait,
after the detection of a trigger pulse,
before sampling the triggered channels.
If a negative delay is specified,
it indicates the amount of pre-trigger sampling desired;
the window will start before the trigger by that amount.
N Sweeps
This selection allows you to select the maximum number of sweeps
(or frames) which will be captured from the triggered channels.
Capture will end after this number of sweeps has been triggered,
even if the run length has not yet expired.
Note that if you select the disk capture,
the capture is performed for the entire run
length, before even looking for sweeps.
Limiting the number of sweeps for a disk capture will affect the
way the run file is processed, but will not limit the size of the
raw direct-to-disk capture
file, nor limit the time taken to capture it.
H Trig. Thresh.
This selection allows you to select the
trigger pulse threshold.
This value, specified in A/D units,
determines the change in amplitude required on the trigger pulse channel,
in two sampling periods,
to trigger a frame; i.e. to start sampling the triggered channels.
The value must be large enough to avoid triggering on noise,
and small enough so no trigger pulses are missed.
(An A/D unit is roughly equal to 2.5 mV, for a 10 volt input range.)
B # of Bins
This selection allows you to select the number of bins to be used
for real-time averaging.
This parameter is used by
cavg(1)
for this purpose.
It also applies to
cap,
for the purpose of enabling or disabling automatic frame tagging.
When this parameter is
0,
automatic tagging is disabled, whether or not the hardware
generates the proper trigger signal for tagging.
When this parameter is non-zero (e.g.
1),
automatic tagging is enabled.
Use this feature only if your hardware is set up for this.
(See
TAGGING
in
dsepr(1)
for details.)
A Sweeps to Pause
This selection allows you to select the number of sweeps
(or frames) which will be captured before automatically pausing
the capture of data from the triggered channels.
This works for the
queued
capture only.
Triggered capture will pause after this number of sweeps have been triggered.
You can then enter a description, and resume triggered capture,
just like when the pause facility is invoked directly, by
pressing the space bar during a queued capture (see
dsepr(1)).
If you set this parameter to
0,
then the automatic pausing will not take place.
M Trigger Mode
This selection allows you to select the
trigger mode
to be used for scanning the trigger
signal for trigger pulses, and deciding what action to take if
the trigger rate is too fast for the current window.
The mode can be one of
C,
R
or
I,
(upper- or lower-case),
corresponding to "check" mode, "retrigger" mode, and "ignore" mode.
In check mode, the program checks whether the trigger rate is too
fast, and warns you if it is.
In retrigger mode, an early trigger will end the current sweep,
and begin a new frame.
The ignore mode will not check the trigger signal while a sweep
is in progress; it is a bit faster, and uses a bit less memory
than the check mode.
Y Stim. Trig. Chan. and Thresh.
On systems configured for queued, networked capture and stimulator control,
this parameter selection appears.
It allows you to select the channel number and signal threshold for the
channel to be monitored for stimulator triggering.
When the signal on the specified channel crosses the given threshold,
qcap
will turn on the digital output that controls the stimulator, and turn it off
again when the signal drops below that level.
Specify the channel number first, followed by the threshold, separated by
punctuation (e.g., a comma, slash or "at" sign).
The threshold is specified in A/D levels, or can be followed by "uV", "mV"
or "V" if specified in microvolts, millivolts or volts.
You can optionally include a hysteresis level after the threshold, again
spearated by a punctuation character, and again optionally followed by a
voltage specifier.
The hysteresis is specified relative to the threshold level: if you specify
a negative hysteresis, the signal must drop by that amount below the threshold
before the digital output is turned off; if positive, the triggering is based
on a negative crossing of the threshold, and the digital output is turned off
again after the signal rises above the threshold plus the hysteresis.
Finally, you can optionally include one or two delays after the hysteresis,
again separated by a punctuation character, and optionally followed by a time
specifier of "us", "ms" or "s".
Without the time specifier, the delays are in sampling periods at the selected
Sampling Rate.
The first delay is the time from the detection of the threshold crossing
(plus a few milliseconds of jitter elimination) to the beginning of the output
trigger pulse.
If a second delay is given, it will be a post-trigger delay before scanning
resumes for the next threshold crossing.
Z Scan Freq.
This selection allows you to
change the
conversion frequency
or channel scanning frequency
- the rate (in Hz) at which channels are scanned in one sampling cycle.
This should be set high enough to support the Sampling Rate you choose
multiplied by the total number of channels you are capturing (including
the trigger signal and any repeated channels).
However, you should beware of setting it too high, especially if you have
equipment connected to your A/D converter that does not have a very low
input impedance.
Setting it too high can result in sequential-channel crosstalk, because
a higher impedance signal source needs more time to pull the A/D input to
it's level after the multiplexer switches to that source.
A lower scanning frequency, or a low impedance buffer amplifier between the
A/D card and your equipment, can minimize this problem.
O Channel Sampling Order/Origin
This selection allows you to select the
channel sampling order on systems that support random channel
addressing, or the first channel to be sampled on systems that don't.
Normally, you do not set this parameter directly, as it is automatically
altered by changes you make to the channel table.
For A/D hardware that allows random channel addressing,
this parameter is a
random channel list,
which specifies the order in which the channels will be sampled.
Enter a list of channel numbers, in the order you want,
separated by spaces.
For A/D hardware that cannot handle random channel access,
such as the EF12M on old Masscomp systems, enter a single channel number;
the channels will be sampled sequentially, beginning with this
channel.
For example, if you enter 13, and are capturing a total of five
channels, the channels sampled will be 13, 14, 15, 0 and 1, in that order.
Currently supported QNX or Linux-based data capture systems all have
A/D hardware that support random channel lists.
T # of Triggered Channels
This selection allows you to select the
number of
triggered channels
to be extracted.
If you aren't using triggered channels, enter a
0.
If you are using triggered channels, the first channel
in the input sequence is used as the trigger, followed by the
specified number of triggered channels, followed by the untriggered
channels (if any).
Normally, you do not set this parameter directly, as it is automatically
altered by changes you make to the channel table.
D Divisors
This selection allows you to select the
list of
triggered channel divisors.
Enter a divisor (a positive integer or a
0)
for each triggered channel, separated by spaces.
These numbers are used to divide the sampling frequency, allowing each
channel to be sampled at a different frequency.
A divisor of
0
means "don't save points from this channel".
If you enter more divisors than there are triggered channels, the
extra divisors are ignored.
If there are too few divisors,
0
is assumed for the missing ones.
Normally, you do not set this parameter directly, as it is automatically
altered by changes you make to the channel table.
U # of Untriggered Channels
This selection allows you to select the
number of
untriggered channels
to be extracted.
If you aren't using untriggered channels, enter a
0.
Normally, you do not set this parameter directly, as it is automatically
altered by changes you make to the channel table.
I Divisors
This selection allows you to select the
list of
untriggered channel divisors.
Enter a divisor (a positive integer or a
0)
for each untriggered channel, separated by spaces.
These numbers are used to divide the sampling frequency, allowing each
channel to be sampled at a different frequency.
A divisor of
0
means "don't save points from this channel".
If you enter more divisors than there are untriggered channels, the
extra divisors are ignored.
If there are too few divisors,
0
is assumed for the missing ones.
Normally, you do not set this parameter directly, as it is automatically
altered by changes you make to the channel table.
J CALIBRATE
This selection doesn't change any capture parameters, but it launches
the
calibrate(1)
program, to make changes to the calibration file beyond simple name changes
in the channel table.
PARAMETER SETS
When
cap
is in the parameter setting mode, you can
change all of the parameters
(except the output file name),
by loading in a
parameter set.
Cap
can have up to twelve
groups
of up to twelve parameter sets each.
The same keys are used to select a group of parameter sets and to
select a parameter set within a group.
On an X Window terminal,
the right side-bar shows either a list of parameter sets which can
be loaded from a group, or a list of groups.
Use the keys
F1
through
F12
to select a set or group,
or use the mouse to point and click.
If
cap
is run from a plain ASCII terminal,
the keys
1
through
9,
0,
-
and
=
are used instead of
F1
through
F12.
Also, on a terminal with less than 34 lines, not all parameters will fit on
the screen at once, but cap will display them page by page, and automatically
switch pages on the display when you move to an off-screen parameter.
The parameters are laid out such that the page division is at a good place
on a standard 24 line display.
When no group has been selected,
cap
lists the groups available, and the "Group Name" field is blank.
Select a group by hitting the key corresponding to it, or by using
the pointing device.
You will be prompted for the group name.
Group names should be limited to 14 characters, and you should avoid
characters that have special meanings to the system, such as
spaces and slashes.
If no group name exists for the selected slot, enter one and the
group will be created.
If a group name has already been assigned to the slot you
selected, you can just hit
RETURN
to select that group.
If you enter a different name, for a named slot, the group name
is changed without affecting the contents of the group.
Finally, you can enter a space to clear the group name:
the group will be erased, provided it is an empty group.
The selection "V VIEW GROUPS" will de-select the current
group, and return you to the list of the available groups, allowing you
to choose another group.
When a group has been selected,
cap
lists the contents of that group (the parameter sets in the group),
and the "Group Name" field indicates the name of the selected group.
Select a parameter set by hitting the key corresponding to it, or by using
the pointing device.
You can only select a slot that has a name assigned to it.
The parameter set of that name will be loaded.
N.B.:
while most parameters in a saved parameter set are loaded in this way,
there are two parameters that are not:
the
File
name and the
Group Dir.
name, which retain the value you set for them, and do not change their
value to what was stored in the parameter set.
Also, because the channel names are set in the local directory's
default.cal
file,
they are not part of the parameters saved and loaded from parameter sets,
and so these do not change when loading a parameter set.
The selection "S SAVE PARAMETER SET" allows you to save
your current parameter values as a set in the current group.
(You must be in a group to save a parameter set.)
After selecting the "SAVE" operation, you are asked to select the
parameter set (i.e. the slot into which the parameters are to be
saved).
Select a slot by hitting the key corresponding to it, or by using
the pointing device.
You will be prompted for the parameter set name.
If no set name exists for the selected slot, enter one and the
set will be created.
If a set name has already been assigned to the slot you
selected, you can just hit
RETURN
to update that set with the current parameter values.
If you enter a different name, for a named slot, the existing set
is removed, and the new set is created with the name you chose.
Finally, you can enter a space to clear the parameter set name:
the parameter set will be removed, and the slot freed up.
Parameter set names should be limited to 10 characters, and you
should avoid characters that have special meanings to the system,
such as spaces and slashes.
The selection "E LOAD EXTERNAL SET" allows you to load
a parameter file located elsewhere on the system, rather than in
one of the available groups.
After selecting the "LOAD" operation, you are asked for the
parameter file name.
Enter the name of the file you want to load, complete with the
.cap
suffix if it has one.
This can be a
default.cap
file that you copied or renamed previously, or one of the
parameter sets from the old version of
cap.
There is no selection for
deleting a parameter set
or parameter group.
Instead, removing a set is done by saving the parameter set via the
S
selection, selecting the slot or key associated with the set you
wish to clear, then clearing the parameter set name by entering a space.
Removing an empty parameter group, after all sets have been removed from
it, is done by using the
selection to view the groups, selecting the slot or key for the empty group,
and clearing the group name by entering a space.
The selection "G Group Dir." allows you to use a
completely different collection of groups of parameter sets.
The directory you specify must exist, but any group indexes or
group directories can be created under it as required by
cap.
This allows you to work with your own private collection of
parameter groups, instead of the system-wide collection that is
used by default.
NOTES
Before
cap
calls
qcap
or
dcap,
if a run already exists with the same name as the selected output
file name, it will be removed, along with any
analysis(1)
parameter files of the same name.
The
DACPAD
environment variable indicates the device name for the A/D converter.
For systems configured to use a networked capture server, such as any
NI USB or PCI based systems, as well as any 64-bit Linux system, the
DACPAD
variable will instead indicate the URL used to contact the server.
If the data capture server is configured to support stimulator control via
a digital output, a parameter in the URL specifies the output, and the presence
of that parameter enables the "Y Stim. Trig. Chan. and Thresh." parameter on
the parameter setting screen.
On an X Window terminal,
cap
temporarily clears the
KEYMAP
environment variable, to disable any keyboard mapping you may
have enabled, such as the ISO Latin 1 character set.
It does this so that the function keys, which are mapped internally to
upper-half 8-bit characters, have their usual assignments.
The side effect is that if you selected an alternate keyboard
mapping, it will not work while in
cap,
or in any program called from
cap.
If the
CALFIXUP
environment variable is set to the file name of an executable program,
this program will be called right after a successful capture, with
the name of the captured file as its command line argument.
This is to facilitate the automatic calibration correction system
used at the Panum Institute, where the program indicated by this
variable reads the settings of knobs on the amplifiers and adjusts
the calibration accordingly.
X WINDOW SUPPORT
When
cap
is run from an
xterm
(or
kterm)
window on an X Window terminal,
a new window will be shown for the parameter setting.
Like the other X Window programs in this package,
cap
will recognise the usual X command line options,
such as
-display,
-geometry,
-font,
etc.
The environment variables for setting these options will also work.
(This is provided that the
DISPLAY
environment variable is set, and
TERM
is set to xterm or kterm.)
See
analysis(1)
for details on X options and environment variables.
However,
cap
shouldn't be run in the background, since the program returns to the
xterm
window once parameter setting is complete.
FILES
default.cap default capture parameters
/usr/neuro/lib/parmgrps/*.ini configuration files
/usr/neuro/lib/parmgrps/editprms.grp group list
/usr/neuro/lib/parmgrps/*/editprms.grp parameter set lists
/usr/neuro/lib/parmgrps/*/*.cap parameter sets
default.cal calibration information
/usr/neuro/lib/default.cal system calibration file
*.raw produced by disk capture
*.frm the frame file
*.w[0-9][0-9] untriggered waveforms
*.txt run description text line
*.frd frame description file
*.p?? parameter files
SEE ALSO
dsepr(1), cavg(1), calibrate(1), lsrun(1), frmsel(1), analysis(1)
Index
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- PARAMETERS
-
- Ch Name
-
- WF or Tr
-
- Div
-
- Hz
-
- Trig
-
- F File
-
- L Run Length
-
- R Sampling Rate (Hz)
-
- K (Q)ueued/(D)isk
-
- X Queue Buffer Length
-
- W Window Dur.
-
- P Pre/Post Trigger
-
- N Sweeps
-
- H Trig. Thresh.
-
- B # of Bins
-
- A Sweeps to Pause
-
- M Trigger Mode
-
- Y Stim. Trig. Chan. and Thresh.
-
- Z Scan Freq.
-
- O Channel Sampling Order/Origin
-
- T # of Triggered Channels
-
- D Divisors
-
- U # of Untriggered Channels
-
- I Divisors
-
- J CALIBRATE
-
- PARAMETER SETS
-
- NOTES
-
- X WINDOW SUPPORT
-
- FILES
-
- SEE ALSO
-
This document was created by
man2html,
using the manual pages.
Time: 17:58:02 GMT, February 20, 2019
Copyright © G. R. Detillieux,
Spinal Cord Research Centre,
The University of Manitoba.