BWMOD(1)

NAME

bwmod - arithmetically modify pixel values in black and white bw file

On this page

SYNOPSIS
DESCRIPTION
OPTIONS
EXAMPLES
SEE ALSO
AUTHOR
COPYRIGHT
BUG REPORTS

SYNOPSIS

bwmod [-c] [-a val] [-s val] [-m val] [-d val] [-A] [-e val] [-r val] [-S val] [-M val] [-O val] [-X val] [-R] [-t] [file.bw] > file2.bw

bwmod performs a series of arithmetic operations on each 8-bit pixel of its input/output stream. The input and output are in the bw(5) file format. Pixel values initially range from 0 to 255 and are internally operated on as floating-point numbers (unless the -c option is specified) so that dynamic range, truncation, and sign are preserved. Upon output, values are converted back to 8-bit unsigned integers. Values less than 0 are clipped to 0, and values greater than 255 are clipped to 255. If any pixels are clipped, the total number of low and high clips is reported to standard error upon completion.

Any number of operations can be specified on the command line, and they are applied sequentially in the order given. All operation arguments can be floating-point values.

Note that this command can also be applied to color pix(5) files, but no distinction will be made between color planes (the same operation will be uniformly applied to all channels).

OPTIONS

-c: Store intermediate results as signed characters. Command-line arguments remain in floating-point format. This is useful when one wishes to take advantage of the wrap-around characteristics of binary mathematics.
-a val: Add val.
-s val: Subtract val.
-m val: Multiply by val.
-d val: Divide by val.
-A: Take the absolute value.
-e val: Exponentiate (raise to the power of val).
-r val: Take the val-th root.
-S val: Shift by val bits. If val is positive, this performs a left-shift using the C << operator; if val is negative, this performs a right-shift using the C >> operator by -val bits. This is a bitwise operation. Before it is applied, both the pixel value and val are truncated to integers. Unless -c is in effect, the resulting new value will be placed back into a floating-point representation.
-M val: Perform a bitwise AND operation with val (automatically truncates to integer before operation).
-O val: Perform a bitwise inclusive OR operation with val (automatically truncates to integer before operation).
-X val: Perform a bitwise exclusive OR (XOR) operation with val (automatically truncates to integer before operation).
-R: Round to the nearest integer.
-t: Truncate to integer. (Note: Truncation is automatically applied for the bitwise options -S, -M, -O, and -X).

EXAMPLES

Example 1. Produce the negative of an image

bwmod -m-1 -a255 < file.bw > file2.bw

This will produce the negative of a file by first multiplying by minus one, and then adding 255 to shift the pixels back into the 0 to 255 range. (i.e., replacing each pixel value by 255 minus that value.)

Example 2. Apply a gamma factor to a file

bwmod -d255 -r2.2 -m255 < file.bw > file2.bw

This first normalizes the pixel values (putting them into the 0 to 1 range), then takes the 2.2 root of each value, and finally scales the pixel values back to the 0 to 255 range. (Note: Applying gammas this way is not recommended for performance reasons, as it results in a function call per pixel.)

Example 3. Expand the range of intensities while preserving the mean

Suppose you ran bwstat on a file and found min=80, max=210, and mean=100. If you wish to expand the range of intensities while still preserving the mean, this can be done by:

bwmod -s100 -m1.409 -a100 < file.bw > file2.bw

The multiplier 1.409 results from (255.0 - 100.0) / (210.0 - 100.0), which boosts the maximum value (210) to full scale (255) after subtracting the mean (100). Subtracting and adding 100 makes the multiply occur "about that point"; i.e., values less than 100 get smaller, and those above get higher.

A file.bw for this example can be created with these three command lines:

gencolor -r 11 80 >file.bw
gencolor -r 262131 100 >>file.bw
gencolor -r 2 210 >>file.bw