
dgsin(1)                     Khoros                      dgsin(1)

PROGRAM
     dgsin - Creates a 1d sinusoidal data set.

SYNTAX
     dgsin

     -o             resulting image

     [-i]           input value file (xviff file)

     [-v]           number of data sets

     [-n]           number of points

     [-s]           sampling frequency

     [-m]           maximum signal level

     [-f]           signal frequency

     [-p]           phase

     [-b]           initial delay

     [-h]           radians per pixel (0) or hertz (1)

     [-d]           data processing direction (0 = down vectors,
                    1 = across bands)

     [-t]           lets user choose data type of image:
                     'float' (select data type),
                      or 'complex' (choose data type)
                       [default = float]

     [-V]           Gives the version for dgsin

     [-U]           Gives the usage for dgsin

     [-P]           Prompts for command line options

     [-A [file1]]   Creates the answer file called dgsin.ans or
                    file1

     [-a [file1]]   Uses dgsin.ans or file1 as the answer file

DESCRIPTION
     creates a one dimensional ensemble of signals (data sets).
     The image pixel values follow a sinusoidal waveform. The
     user can specify the frequency, phase, amplitude, sampling
     frequency, an initial delay, and signal dimensions.

     If a "value file" is specified, it will contain a kernel
     that describes the signal ensemble to be generated.  This is
     an viff format file.  The information for each data set will
     be contained in a single vector of float type information.
     The format of the information is as follows:

     [<sampling freq.><amplitude><frequency><phase><init. delay>]

     where each item enclosed in triangular brackets represents a
     single float.  The information set in square brackets is
     repeated as a group one per vector.  as many times as there
     are vectors (specified in the first float).

     For example if 2 vectors are specified, and the first vector
     has a sampling frequency of 10.0, an amplitude of 6.0, fre-
     quency of 2.0, phase of 0.0, initial delay of 0; the second
     vector is identical, except that the amplitude is 3.0 and
     the initial delay is 7, then the image data in the "value
     file" will look like this:

     band #1: 10.0 10.0
     band #2:  6.0  3.0
     band #3:  2.0  2.0
     band #4:  0.0  0.0
     band #5:  0.0  7.0

     The advantage of this "value file" is that it allows the
     creation of an ensemble of 1D signals that independant of
     each other.  Number of data sets, number of points per data
     set, data type, and process direction must be entered on the
     command line, or the defaults can be taken.  If more data
     sets are requested than are specified in the parameter file,
     then an error will occur.  If fewer data sets are requested
     than are specified, then the unused parameters will be
     ignored.

     A non zero initial delay causes the number of points indi-
     cated to be zeroed.  After the indicated delay, the
     sinusoidal signal is generated with a time shift equivalent
     to the delay specified (i.e. the t=0 line is shifted to the
     right based on the value of the delay).

     The resulting images may be of type FLOAT or COMPLEX.  A
     real image is generated using the formula:

     f = A*cos(2*pi*i*f/s + p);

     where A is magnitude, f is frequency, i is a point counter,
     p is the phase shift in radians, and s is the sampling fre-
     quency. A complex image is generated similarly:

     f = A*cos(2*pi*i*f/s + ps) +
             j*A*sin(2*pi*i*f/s + p);

     where j is sqrt(-1).

     Data can be processed with either band or vector orienta-
     tion.  The default data processing direction is in the vec-
     tor direction.  This means that data stored in multiband
     format will be processed as a set of data sequences, where
     each sequence corresponds to a pixel location, and the
     points of each sequence are defined by the bands correspond-
     ing to that pixel location.  The direction of processing can
     be changed so that each band is processed as a signal
     (instead of each vector being a signal) by setting the -d
     option to 1.

REQUIRED ARGUMENTS
     -o     type: outfile
            desc: resulting image

OPTIONAL ARGUMENTS
     -i     type: infile
            desc: input value file (xviff file)

     -v     type: integer
            desc: number of data sets
            default: 1
            bounds: value > 0

     -n     type: integer
            desc: number of points
            default: 256
            bounds: value > 0

     -s     type: float
            desc: sampling frequency
            default: 2
            bounds: value > 0.0

     -m     type: float
            desc: maximum signal level
            default: 1
            bounds: no range checking

     -f     type: float
            desc: signal frequency
            default: 1
            bounds: value > 0.0

     -p     type: float
            desc: phase
            default: 0
            bounds: no range checking

     -b     type: integer
            desc: initial delay
            default: 0
            bounds: value >= 0

     -h     type: boolean
            desc: radians per pixel (0) or hertz (1)
            default: true

     -d     type: boolean
            desc: data processing direction (0 = down vectors, 1
            = across bands)
            default: true

     -t     type: string
            desc: lets user choose data type of image
            allowed values:
             'float' (select data type),
              or 'complex' (choose data type)

EXAMPLES
     dgsin -o sin1.xv -v 2 -n 512 -s 10.0 -f 4.0 -m 4.0 -b 2 -d 1

     The above command line will cause a file sin1.xv to be
     created that has two sinusoids of length 512 with a sampling
     frequency of 10.0, a sinusoid frequency of 4.0, amplitude
     4.0 an initial delay of two points, stored in band format.

SEE ALSO
     intro(1), verror(3), vgparms(3), vutils(3), ldgsin(3)

RESTRICTIONS
     can only generate VFF_TYP_FLOAT and VFF_TYP_COMPLEX type
     images.

COPYRIGHT
     Copyright 1991, University of New Mexico.  All rights
     reserved.

Khoros                    Release: 1.0                          1

