
dinsert(1)                   Khoros                    dinsert(1)

PROGRAM
     dinsert - Inserts 1-D format file into another 1-D file.

SYNTAX
     dinsert

     -i1            input image

     -i2            input image

     -o             resulting output image

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

     [-e]           Append i2 to the end of i1
                                        -OR-

     [-x]           Starting point where i2 is inserted into i1
                                        -OR-

     [-i3]          File which contains insert point for each
                    vector

     [-V]           Gives the version for dinsert

     [-U]           Gives the usage for dinsert

     [-P]           Prompts for command line options

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

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

DESCRIPTION
     dinsert inserts 1-dimensional vector(s) from the input data
     file (i2) into the vector(s) in file i1.  The position(s)
     where the vector(s) are inserted are determined by the -x,
     -i3, or -e option (mutually exclusive) specified by the
     user.

     Input and output files
                    The two input files must be of the same data
                    type and have the same number of vectors. The
                    input files must be of dimension = 0, have
                    implicit location types, and be of data
                    storage type VFF_TYP_FLOAT or
                    VFF_TYP_COMPLEX.  The map types of the 2
                    input files are not checked, and, if dif-
                    ferent, the output file assumes the map type
                    of file i1.  The output file will contain the
                    same number of vectors as are in the input
                    files, and the data storage type will be the
                    same as that of the input files.  The vector
                    dimension of the output file will be the sum
                    of the dimensions of the two input files.

     Point of Insertion
                    Three mutually exclusive options are avail-
                    able for specifying the position where file
                    i2 is to be inserted into i1: -x (int), -i3
                    (file), and -e (logical).

                    Specify Beginning Point (-x)
                    The starting point (-x) option specifies a
                    constant offset into the i1 data set(s) where
                    the first point of the i2 data set(s) is to
                    be inserted. The default value is 0 (the
                    first point of the i1 data).

                    Insert File (-i3)
                    The -i3 option allows the user to specify a
                    file which contains the starting point of
                    each vector independently.  This file must be
                    of type int and have the same number of
                    points as there are vectors in the input
                    files.

                    Append to End of Input Sequence (-e)
                    The default option is the -e (append to end
                    of sequence) option.  When this option is
                    selected, dinsert appends the signal(s) con-
                    tained in file i2 to the end of the signal(s)
                    in i1.  The insert 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 The direc-
                    tion of processing can be changed so that
                    each vector is processed as a signal (instead
                    of each band being a signal), by setting the
                    -d option to 0.  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.

REQUIRED ARGUMENTS
     -i1    type: infile
            desc: input image

     -i2    type: infile
            desc: input image

     -o     type: outfile
            desc: resulting output image

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

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

     -e     desc: Append i2 to the end of i1
            default: true

     -x     desc: Starting point where i2 is inserted into i1
            default: 0
            bounds: value >= 0

     -i3    desc: File which contains insert point for each vec-
            tor

            ********

EXAMPLES
     dinsert -i1 in_file_1 -i2 in_file_2 -o out_file -x 18

     Will return out_file which containing in_file_2 inserted at
     position 18 in in_file_1.

     dinsert -i1 in_file_1 -i2 in_file_2 -i3 start_vals -o
     out_file -d 0

     The input files both have 3 vectors, therefore the
     start_vals file must have 3 values.  If start_vals contains
     [4 2 6], out_file will contain the following data:  Vector
     1, will be vector 1 from in_file_1 with vector 1 from
     in_file_2 inserted at point 4.  Vector 2 will be vector2
     from in_file_1 with vector 2 from in_file_2 inserted at
     point 2, and vector 3 will be vector3 from in_file_1 with
     vector 3 from in_file_2 inserted at point 6.

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

RESTRICTIONS
     Dinsert works only on VFF_TYP_COMPLEX and VFF_TYP_FLOAT.

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

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

Khoros                    Release: 1.0                          1

