.\"                                      Hey, EMACS: -*- nroff -*-
.\" Copyright 1995 Peter Neelin, McConnell Brain Imaging Centre,
.\" Montreal Neurological Institute, McGill University.
.\" Permission to use, copy, modify, and distribute this
.\" software and its documentation for any purpose and without
.\" fee is hereby granted, provided that the above copyright
.\" notice appear in all copies.  The author and McGill University
.\" make no representations about the suitability of this
.\" software for any purpose.  It is provided "as is" without
.\" express or implied warranty.
.\"
.\" $Header: /private-cvsroot/minc/progs/mincmath/mincmath.man1,v 6.3 2004-05-20 21:52:08 bert Exp $
.\"
.TH MINCMATH 1 "$Date: 2004-05-20 21:52:08 $" "" "MINC User's Guide"

.SH NAME
mincmath - perform simple math operations on minc files

.SH SYNOPSIS
.B mincmath
[<options>] <in1>.mnc [<in2>.mnc...] <out>.mnc

.SH DESCRIPTION
\fIMincmath\fR will perform simple, voxel-by-voxel math operations, 
on one or more minc files of the same shape and having the same 
coordinate sampling, producing a single output file. Operations can be
unary (operate on one file), binary (two input files) or cumulative 
(operate on two or more input files). Cumulative operations can also 
be performed across a specified dimension of the input files.

.SH OPTIONS
Note that options can be specified in abbreviated form (as long as
they are unique) and can be given anywhere on the command line.

.SH General options
.TP
\fB\-2\fR
Create a MINC 2.0 format output file.
.TP
\fB\-clobber\fR
Overwrite an existing file.
.TP
\fB\-noclobber\fR
Don't overwrite an existing file (default).
.TP
\fB\-no_clobber\fR
Synonym for \fB\-noclobber\fR.
.TP
\fB\-verbose\fR
Print out progress information for each chunk of data copied (default).
.TP
\fB\-quiet\fR
Do not print out progress information.
.TP
\fB\-debug\fR
Print out debugging information.
.TP
\fB\-filelist\fR\ \fIfilename\fR
Specify a file containing a list of input file names. If "-" is given, then
file names are read from the standard input. If this option is given, then 
there should be no input file names specified on the command line. Empty
lines in the input file are ignored.
.TP
\fB\-copy_header\fR
Copy all of the header information from the first input file (default for 
one input file).
.TP
\fB\-nocopy_header\fR
Do not copy all of the header from the first input file; copy only
coordinate information (default for more than one input file).
.TP
\fB\-filetype\fR
Create an output file with the same type as the first input file
(default).
.TP
\fB\-byte\fR
Store output voxels in 8-bit integer format.
.TP
\fB\-short\fR
Store output voxels in 16-bit integer format.
.TP
\fB-int\fR
Store output voxels in 32-bit integer format.
.TP
\fB-long\fR
Superseded by \fB\-int\fR.
.TP
\fB-float\fR
Store output voxels in 32-bit floating point format.
.TP
\fB-double\fR
Store output voxels in 64-bit floating point format.
.TP
\fB\-signed\fR
Use signed, two's complement integer format. Applies only
if the output voxel type is specified to be an integer type
(one of \fB\-byte\fR, \fB\-short\fR, \fB\-int\fR or \fB-long\fR).
.TP
\fB\-unsigned\fR
Use unsigned integer format. Applies only
if the output voxel type is specified to be an integer type
(one of \fB\-byte\fR, \fB\-short\fR, \fB\-int\fR or \fB-long\fR).
.TP
\fB\-range\fR \fImin max\fR
Restrict the valid range of integer data.  Applies only if one
of the \fB-byte\fR, \fB-short\fR, \fB-int\fR or \fB\-long\fR options is
specified.
.TP
\fB\-max_buffer_size_in_kb\fR \fIsize\fR
Specify the maximum size of the internal buffers (in kbytes). Default
is 4096 (4MB).
.TP
\fB\-dimension\fR\ \fIdimname\fR
Specify a dimension along which we wish to perform a cumulative
operation.
.TP
\fB\-check_dimensions\fR
Check that all input files have matching sampling in world 
dimensions (default).
.TP
\fB\-nocheck_dimensions\fR
Ignore any differences in world dimensions sampling for input files .
.TP
\fB\-propagate_nan\fR
Invalid data (Not-A-Number or NaN) at a voxel in any of the input
files will produce invalid data in the output file at that voxel
(default).
.TP
\fB\-ignore_nan\fR
For cumulative operations, invalid data (NaN) in an input file is
ignored, ie. treated as though it is not present.
.TP
\fB\-nan\fR
When an illegal operation is attempted at a voxel (such as divide by
zero), invalid data (NaN) is stored in the output file (default). Having 
no valid input data for a cumulative operation is also considered an 
illegal operation when \fB\-ignore_nan\fR is used.
.TP
\fB\-zero\fR
When an illegal operation is attempted at a voxel (such as divide by
zero), value zero is stored in the output file.
.TP
\fB\-illegal_value\fR\ \fIvalue\fR
When an illegal operation is attempted at a voxel (such as divide by
zero), the specified value is stored in the output file.

.SH Options for specifying constants
.TP
\fB\-constant\fR\ \fIvalue\fR
Specify a single constant.
.TP
\fB\-const\fR\ \fIvalue\fR
Synonym for \fB\-constant\fR.
.TP
\fB\-const2\fR\ \fIvalue1 value2\fR
Specify two constants.

.SH Operations
.TP
\fB\-add\fR
Cumulatively add two or more volumes, or add a volume and a constant.
.TP
\fB\-sub\fR
Subtract two volumes or a volume minus a constant.
.TP
\fB\-mult\fR
Cumulatively multiply two or more volumes, or multiply a volume and a constant.
.TP
\fB\-div\fR
Divide two volumes or a volume divided by a constant.
.TP
\fB\-invert\fR
Calculate 1/x at each voxel, where x is the input voxel value. If a 
constant c is specified (with -constant), then calculate c/x at each voxel.
.TP
\fB\-sqrt\fR
Calculate the square root of a volume.
.TP
\fB\-square\fR
Calculate the square of a volume.
.TP
\fB\-abs\fR
Calculate the absolute value of a volume.
.TP
\fB\-maximum\fR
Calculate the maximum of a series of volumes.
.TP
\fB\-minimum\fR
Calculate the minimum of a series of volumes.
.TP
\fB\-exp\fR
Calculate \fIc2*exp(c1*x)\fR at each voxel of a volume, where \fIx\fR
is the voxel value and \fIc1\fR and \fIc2\fR are constants specified
by \fB\-constant c1\fR or \fB\-const2 c1 c2\fR. The default value for
these constants is 1.0.
.TP
\fB\-log\fR
Calculate \fIlog(x/c2)/c1\fR for each voxel of a volume, where \fIx\fR is the
voxel value and \fIc1\fR and \fIc2\fR are constants specified by 
\fB\-constant c1\fR or \fB\-const2 c1 c2\fR. The default value for these
constants is 1.0.
.TP
\fB\-scale\fR
Scale a volume either by multiplying by a single constant (use
-constant) or by multiplying by the first constant and adding the
second (use -const2).
.TP
\fB\-clamp\fR
Clamp a volume to lie between two values specified with \fB-const2\fR.
.TP
\fB\-segment\fR
Segment (binarize) a volume so that values within the range specified
by \fB\-const2\fR give value 1 and those outside it give value 0.
.TP
\fB\-nsegment\fR
Opposite of \fB\-segment\fR: values within the range specified by 
\fB\-const2\fR give value 0 and those outside it give value 1. 
.TP
\fB\-percentdiff\fR
Calculate the percent difference between two volumes (normalized to
the first volume). If the first volume is less than a threshold (or
zero), then the value specified by \fB\-nan\fR or \fB\-zero\fR is 
used. The threshold is specified using \fB\-constant\fR, with a 
default of zero.
.TP
\fB\-pd\fR
Synonym for \fB\-percentdiff\fR.
.TP
\fB\-eq\fR
Test for equality of two volumes or a volume and a constant.
Values are rounded to the nearest integer before performing the
test. Output 1 for true and 0 for false at each voxel.
.TP
\fB\-ne\fR
Test for inequality of two volumes or a volume and a constant. 
Values are rounded to the nearest integer before performing the test.
Output 1 for true and 0 for false at each voxel.
.TP
\fB\-gt\fR
Test for volume 1 > volume 2 or a volume > a constant. Output 1 for
true and 0 for false at each voxel. 
.TP
\fB\-ge\fR
Test for volume 1 >= volume 2 or a volume >= a constant. Output 1 for
true and 0 for false at each voxel. 
.TP
\fB\-lt\fR
Test for volume 1 < volume 2 or a volume < a constant. Output 1 for
true and 0 for false at each voxel. 
.TP
\fB\-le\fR
Test for volume 1 <= volume 2 or a volume <= a constant. Output 1 for
true and 0 for false at each voxel.
.TP
\fB\-and\fR
Test for volume 1 && volume 2 or a volume && a constant. Values are
rounded to the nearest integer before performing the test. Output 1
for true and 0 for false at each voxel. 
.TP
\fB\-or\fR
Test for volume 1 || volume 2 or a volume || a constant. Values are
rounded to the nearest integer before performing the test. Output 1
for true and 0 for false at each voxel. 
.TP
\fB\-not\fR
Perform logical negation on a volume: convert non-zero to zero and
zero to one. Values are rounded to the nearest integer before the
negation.
.TP
\fB\-isnan\fR
Test a volume for invalid values (NaN). Output 1 for invalid values
and 0 for valid values.
.TP
\fB\-nisnan\fR
Opposite of -isnan. Output 0 for invalid values and 1 for valid values.
.TP
\fB\-count_valid\fR
Count the number of valid voxels across a series of volumes. If none of the
volumes has valid data, then zero is written out (ie. \fB\-zero\fR and 
\fB\-ignore_nan\fR are always assumed, unlike other cumulative operations).

.SH Generic options for all commands:
.TP
\fB\-help\fR
Print summary of command-line options and exit.
.TP
\fB\-version\fR
Print the program's version number and exit.

.SH AUTHOR
Peter Neelin

.SH COPYRIGHTS
Copyright \(co 1995 by Peter Neelin
 
.SH "SEE ALSO"
.LP
.BR minccalc (1)