.help mkpattern Jan90 noao.artdata
.ih
NAME
mkpattern - Make/add patterns in images
.ih
USAGE
mkpattern input
.ih
PARAMETERS
.ls input
Images to create or modify.  Image sections are allowed to apply a pattern
to a portion of an image.
.le
.ls output = ""
Output images when modifying input images.  If no output images are
given then existing images in the input list are modified directly.
If an output image list is given then it must match in number the
input list.
.le
.ls pattern = "constant"
Pattern to be used.  The patterns are:
.ls constant
Constant value v1.
.le
.ls grid
A grid starting with the first pixel and going in steps of the
pattern size with value v2.  Pixels between the grid have value v1.
A minimum grid size of 2 is enforced.
.le
.ls checker
A checkerboard with squares of the pattern size alternating between values v1
and v2 starting with v1.
.le
.ls coordinates
Each pixel is numbered sequentially starting with 1 with the column
dimension varying fastest.
.le
.ls slope
A sloped plane starting with value v1 for the first pixel and value v2 for
the last pixel in one or two dimensions.
.le
.ls square
A checkerboard pattern in which the size of the squares begin with
the pattern size and grow as the square of the coordinate.
.le
.le
.ls option = "replace"
Editing option when modifying existing images.  Often this is used
in conjunction with image sections to modify a part of an image.
The options are:

.nf
 replace - Replace the image with the pattern.
     add - Add the pattern to the image.
multiply - Multiply the pattern with the image values.
.fi
.le
.ls v1 = 0., v2 = 1.
Pattern values used as described for each pattern.
.le
.ls size = 1
Pattern size used as described for each pattern.
.le

WHEN CREATING NEW IMAGES
.ls title = ""
Image title to be given to the images.  Maximum of 79 characters.
.le
.ls pixtype = "real"
Pixel datatype of new images; one of ushort, short, integer, real, double,
or complex.
.le
.ls ndim = 2
Number of dimensions between 0 and 7.
.le
.ls ncols = 512, nlines = 512
Number of columns (first dimension) and lines (second dimension).
.le
.ls n3 = 1, n4 = 1, n5 = 1, n6 = 1, n7 = 1
Number of pixels in 3rd-7th  dimensions
.le
.ls header = "artdata$stdheader.dat"
Image or header keyword data file.  If an image is given then the image header
is copied.  If a file is given then the FITS format cards are copied.
This only applies to new images.   The data file consists of lines
in FITS format with leading whitespace ignored.  A FITS card must begin
with an uppercase/numeric keyword.  Lines not beginning with a FITS
keyword such as comments or lower case are ignored.  The user keyword
output of \fBimheader\fR is an acceptable data file.  See \fBmkheader\fR
for further information.
.le
.ih
DESCRIPTION
This task creates or modifies images with a choice of patterns.  New images
are created with the specified dimensions, datatype, and pattern.
Existing images may have the pattern replace, add, or multiply the
pixel values.  Existing images may be modified in place or new images may be
created and image sections are allowed.

For new images a set of header keywords may be added by specifying an
image or data file with the \fIheader\fR parameter (see also \fBmkheader\fR).
If a data file is specified lines beginning with FITS keywords are
entered in the image header.  Leading whitespace is ignored and any
lines beginning with words having lowercase and nonvalid FITS keyword
characters are ignored.

This task is the simplest one for creating empty images to be used for
mosaicing with \fBimcopy\fR and making patterns for testing display and
image operators.  The replace option is generally used with image sections
to place constant values in regions.  The multiply option is useful
for making masks of the given pattern when the values are 0 and 1.

Though the patterns make sense extending to higher dimensions they
are only defined in two dimensions.  One dimensional images may be
thought of as the first line of the two dimensional pattern.  Images
with dimensions greater than 2 simply repeat the two dimensional
pattern into the higher dimensions.  The reason for stopping at
two dimensions is simplicity.

The patterns have the following precise definitions where P(i,j) is the
pixel value at column i and line j, v1 and v2 are the pattern
values, size is the pattern size, ncols and nlines are the number of
columns and lines in the image, int is the integer function, mod is the
modulus function, and sqrt is the square root function.

.nf
                k = int ((i-1)/size), l = int ((j-1)/size)
                ksr = int (sqrt (k)), lsr = int (sqrt (l))
                slope = (v2-v1) / ((ncols+nlines-2)/size)

    constant:   P(i,j) = v1

        grid:   P(i,j) = v2   when mod(i,size)=1 or mod(j,size)=1
                P(i,j) = v1   otherwise

 coordinates:   P(i,j) = i + j * ncols

     checker:   P(i,j) = v1   when mod(k,2)=0 and mod(l,2)=0
                P(i,j) = v2   when mod(k,2)=1 and mod(l,2)=0
                P(i,j) = v2   when mod(k,2)=0 and mod(l,2)=1
                P(i,j) = v1   when mod(k,2)=1 and mod(l,2)=1

       slope:   P(i,j) = v1 + slope * (k + l) 

      square:   P(i,j) = v1   when mod(ksr,2)=0 and mod(lsr,2)=0
                P(i,j) = v2   when mod(ksr,2)=1 and mod(lsr,2)=0
                P(i,j) = v2   when mod(ksr,2)=0 and mod(lsr,2)=1
                P(i,j) = v1   when mod(ksr,2)=1 and mod(lsr,2)=1
.fi

.ih
EXAMPLES
1. Create an empty (constant value of zero) three dimensional image.

.nf
	cl> mkpattern cube ndim=3 nc=100 nl=100 n3=100
.fi

2. Replace a square region of an image with the value -1000.

.nf
	cl> mkpat alpha[201:250,1:50] v1=-1000
.fi

3. Put a grid pattern on an image to create a new image.

.nf
	cl> mkpat dev$pix out=gridpix pat=grid op=mul v1=1 v2=0
.fi
.ih
REVISIONS
.ls MKPATTERN V2.11
Now allows ndim=0 to create dataless header.

Now allows type ushort pixel type.
.le
.ih
SEE ALSO
imcopy, imreplace
.endhelp
