BYTSCL

The BYTSCL function scales all values of Array that lie in the range (Min≤x≤Max) into the range (0 ≤x≤Top). Additionally, the result is returned as type BYTE.

For floating-point input, each value is scaled using the formula (Top + 0.9999) * (x - Min)/(Max - Min).
For integer input, each value is scaled using the formula (Top + 1) * (x ‑ Min ‑ 1)/(Max - Min).
(See Note on Integer Computation.)

Examples

BYTSCL is often used to scale images into the appropriate range for 8-bit displays. In the following example, we create a 200x200 image, and then rescale the image pixels from 0 through 255.

image = DIST(200)
scaled_image = BYTSCL(image)

; Display the original and filtered images together
WINDOW, 0, XSIZE=400, YSIZE=200, $

TITLE="BYTSCL: Before and After"
TV, image, 0
TV, scaled_image, 1

Syntax

Result = BYTSCL( Array [, MAX=value] [, MIN=value] [, /NAN] [, TOP=value] )

Return Value

The returned result has the same structure as the original parameter and is of byte type.

Arguments

Array

The array to be scaled and converted to bytes.

Keywords

MAX

Set this keyword to the maximum value of Array to be considered. If MAX is not provided, Array is searched for its maximum value. All values greater or equal to MAX are set equal to TOP in the result.

Note: The data type of the value specified for MAX should match the data type of the input array. Since MAX is converted to the data type of the input array, specifying mismatched data types may produce undesired results.

MIN

Set this keyword to the minimum value of Array to be considered. If MIN is not provided, Array is searched for its minimum value. All values less than or equal to MIN are set equal to 0 in the result.

Note: The data type of the value specified for MIN should match the data type of the input array. Since MIN is converted to the data type of the input array, specifying mismatched data types may produce undesired results.

NAN

Set this keyword to cause the routine to check for occurrences of the IEEE floating-point values NaN or Infinity in the input data. Elements with the value NaN or Infinity are treated as missing data.

TOP

Set this keyword to the maximum value of the scaled result. If TOP is not specified, 255 is used. Note that the minimum value of the scaled result is always 0.

Thread Pool Keywords

This routine is written to make use of IDL’s thread pool, which can increase execution speed on systems with multiple CPUs. The values stored in the !CPU system variable control whether IDL uses the thread pool for a given computation. In addition, you can use the thread pool keywords TPOOL_MAX_ELTS, TPOOL_MIN_ELTS, and TPOOL_NOTHREAD to override the defaults established by !CPU for a single invocation of this routine. See Thread Pool Keywords for details.

Note on Integer Computation

When scaling integer values, the scaling algorithm is optimized for speed when the range of values (Max - Min) is less than 2²². In this case, the actual formula used is:

Scale = (2²² * (Top + 1))/(Max - Min)

Result = ((x - Min) * Scale - 1) * 2^-22

where all computations are done using integer arithmetic.

Version History

Original

Introduced