HALFTONE(1)

NAME

halftone - convert a black and white image to a halftoned black and white image

On this page

SYNOPSIS
DESCRIPTION
OPTIONS
EXAMPLES
SEE ALSO
AUTHOR
COPYRIGHT
BUG REPORTS

SYNOPSIS

halftone [-R] [-S] [-a] [-s _squaresize_] [-w _width_] [-n _height_] [-B _contrast_] [-I _levels_] [-M _method_] [-T _x1 y1 x2 y2 ..._] [-D _debug_level_] [_file.bw_]

halftone reads a black and white image in bw(5) format from the named file (or from standard input if no file is given) and writes a halftoned bw(5) image to standard output. Halftoning reduces the number of distinct intensity levels (256 by default down to 2, that is black and white) while using dithering to preserve as much apparent shading and detail as possible. Several dithering algorithms are available via the -M option, ranging from Floyd-Steinberg error diffusion to ordered halftone screens.

The output is itself a bw(5) file whose pixels take a limited set of values; each output level is scaled to the range 0 to 255 (as 255 / (levels - 1) * value) so the result displays correctly with tools such as bw-pix(1). The dithering algorithms are drawn largely from Digital Halftoning by Robert Ulichney.

OPTIONS

-s squaresize

Set both the width and height of the input image to squaresize pixels.

-w width

Set the width of the input image in pixels. The default is 512.

-n height

Set the height of the input image in scanlines. The default is 512.

-a

Automatically determine the input image dimensions from the file name or file size. Automatic sizing cannot be used with pipes or standard input.

-B contrast

Floating-point beta coefficient applied by a Laplacian edge sharpening filter before dithering. The default is 0.0, which disables sharpening.

-I levels

Number of output intensity levels. The default is 2 (1-bit black/white) and the maximum is 256.

-M method

Select the halftoning method:

0: Floyd-Steinberg error diffusion (default)
1: 45-degree classical clustered-dot halftone screen
2: simple thresholding dither
3: 0-degree dispersed-dot halftone screen

A value outside the range 0-3 is reported and reset to the default (0).

-R

Add random noise to the dither threshold. This can break up repeating screen patterns and improve the appearance of the output.

-S

Use a serpentine scan path, reversing direction on every other row instead of always scanning left to right. This option only has an effect with Floyd-Steinberg error diffusion (-M 0); it is ignored for the other methods.

-T x1 y1 x2 y2 …

Define a tone-scale mapping from a list of integer coordinate pairs (each in the range 0 to 255). A cubic spline is fit through the points to map input intensities to output intensities. The default mapping is the straight line equivalent to -T 0 0 255 255.

-D debug_level

Set the debug level. A value of 9 emits all debugging messages.

-h, -?

Print a usage message and exit.

EXAMPLES

Example 1. Render a model and halftone the result for a 1-bit display

rt -s 512 -o image.pix model.g component.r
pix-bw image.pix > image.bw
halftone -M 0 -S image.bw > image.ht.bw

Ray traces a region to a 512x512 color image, converts it to bw(5) grayscale, then applies Floyd-Steinberg error diffusion with a serpentine scan to produce a dithered black-and-white image suitable for a 1-bit device.

Example 2. Coarse newsprint-style halftone with four gray levels

halftone -w 1024 -n 768 -M 1 -I 4 photo.bw > photo.ht.bw

Treats the input as a 1024x768 image and applies the 45-degree classical clustered-dot screen quantized to four intensity levels, mimicking a coarse printed halftone.