
dshift(1)                    Khoros                     dshift(1)

PROGRAM
     dshift - Shifts or rotates 1-D signal(s)

SYNTAX
     dshift

     -i             input data file

     -o             resulting output file

     [-j]           Real Padding Value

     [-k]           Imaginary Padding Value

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

     [-w]           Shift or Rotate (wrap). Rotate: w=1, Shift:
                    w=0 (default=0):
                    0 (shift signal (w=0)),
                    or 1 (rotate signal (w=1))
                       [default = 0]

     [-x]           Positive or Negative Shifting value
                                        -OR-

     [-i2]          Input Shifting Value File

     [-V]           Gives the version for dshift

     [-U]           Gives the usage for dshift

     [-P]           Prompts for command line options

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

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

DESCRIPTION
     dshift shifts or rotates the 1-dimensional signals in the
     input data file by the specified value(s).  If the wrap
     option (-w) is specified, the signal will be rotated.
     Shifting values can be positive or negative.  Positive shift
     values will cause rotation or shifting to occur from left to
     right.  Negative shift values will cause rotation or shift-
     ing to occur from right to left.  The -w option (wrap)
     defaults to 0 -- no rotation. (0=shift, 1=rotate).

     Dshift will shift the 1-dimensional signals in the input
     data file by the value specified by the -x option, or by the
     shifting values given in the shift value input file (-i2).
     If a shift value file is specified, it must contains the
     same number of points as there are vectors in the input
     file. There is a one to one correspondence between shift
     values and vectors, and each vector will be offset by it's
     correspoinding shift value.

     Dshift does not work on explicit location data and will
     return an error when such a file is encountered.  No output
     file will be created.  Dshift works only on VFF_TYP_FLOAT or
     VFF_TYP_COMPLEX input data files, and the value file must be
     type VFF_TYP_4_BYTE.

     Input/Output Files
                    The input file must be of type VFF_TYP_FLOAT
                    or VFF_TYP_COMPLEX. The output file returned
                    will be the same size and type as the input
                    file.

     Real & Imaginary Shift Padding Values
                    The real (-j) and imaginary (-k) padding
                    value options allow the user to specify a
                    constant float value for padding the posi-
                    tions from which the signal has been shifted
                    away.  The default padding values are 0.0.
                    If the imaginary padding value is selected
                    and the input data is not complex, a warning
                    statement will be printed, and the -k option
                    ignored.
                    Note: If the -w option is specified (-w = 1 =
                    wrap), rotation occurs, so the -i and -j
                    options are ignored.

     Specification of Shifting Value(s)
                    Dshift will shift the 1-dimensional signals
                    in the input data file by the value specified
                    by the -x option, or by the shifting values
                    given in the shift value input file (-i2).
                    These two options are mutually exclusive.

                    Shifting values can be positive or negative.
                    Positive shift values will cause rotation or
                    shifting to occur from left to right.  Nega-
                    tive shift values will cause rotation or
                    shifting to occur from right to left.

                    The constant shift value (-x) option is the
                    default option (default value = 0).  When -x
                    is used, all vectors in the data file are
                    shifted or rotated by the same value.

                    If a shift value file (-i2) is specified,
                    each vector in the input file will be shifted
                    independently by the values defined in the
                    file.  The shift value file must contains the
                    same number of points as there are vectors in
                    the input file. There is a one to one
                    correspondence between shift values and vec-
                    tors, and each vector will be offset by it's
                    correspoinding shift value. The shift value
                    file must be of type VFF_TYP_4_BYTE.

     Process direction
                    Data can be processed with either band or
                    vector orientation (-d option). The default
                    data processing direction is in the band
                    direction (d = 1). This means that each band
                    is processed as a signal (instead of each
                    vector being a signal).  The direction of
                    processing can be changed so that processing
                    occurs down vectors by setting the -d option
                    to 0.  In other words, data stored in multi-
                    band 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 corresponding to that pixel location.

REQUIRED ARGUMENTS
     -i     type: infile
            desc: input data file

     -o     type: outfile
            desc: resulting output file

OPTIONAL ARGUMENTS
     -j     type: float
            desc: Real Padding Value
            default: 0
            bounds: no range checking

     -k     type: float
            desc: Imaginary Padding Value
            default: 0
            bounds: no range checking

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

     -w     type: integer
            desc: Shift or Rotate (wrap). Rotate: w=1, Shift: w=0
            (default=0)
            allowed values:
            0 (shift signal (w=0)),
            or 1 (rotate signal (w=1))

     ***   These arguments are MUTUALLY EXCLUSIVE   ***
      If desired, you may provide ONE AND ONLY ONE of:

     -x     desc: Positive or Negative Shifting value
            default: 0
            bounds: no range checking

     -i2    desc: Input Shifting Value File

            ********

EXAMPLES
     dshift -i input_file -o shifted_file -x 3 -j 1.0

     Will return a file containing the input signal(s) shifted to
     the right by 3 points.  The far right 3 points of the input
     signal(s) are truncated and the 3 leftmost points in the
     output file are set to the constant value of 1.0

     dshift -i input_file -o rotated_file -w 1 -x -6

     Will return a file containing the input signal(s) rotated to
     the left by 6 points.  The 6 points that were rotated left
     are wrapped onto the right end of the signal

     dshift -i input_file -i2 shift_vals -o out_file -w 1

     The input file has 3 vectors, therefore the i2 file must
     have 3 values.  If i2 contains [4 2 6], the vectors 1, 2 and
     3 in out_file will be rotated by 4, 2, and 6 points respec-
     tively.

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

RESTRICTIONS
     Dshift works only on VFF_TYP_COMPLEX and VFF_TYP_FLOAT.

     Dshift does not work on explicit location data and will
     return an error when such a data file is encountered.

     The shift value file must be of type VFF_TYP_4_BYTE.

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

Khoros                    Release: 1.0                          1

