| Environments | PYTHON :: EASI :: MODELER |
| Quick links | Description :: Parameters :: Parameter descriptions :: Details :: Example :: Algorithm :: Related |
| Back to top |
| Back to top |
scale(fili, filo, dbic, dboc, dbiw, dbow, inrange, trim, outrange, sfunct, datatype, ftype, foptions)
| Name | Type | Caption | Length | Value range |
|---|---|---|---|---|
| FILI * | str | Input file name | 1 - | |
| FILO | str | Output file name | 0 - | |
| DBIC * | List[int] | Unscaled raster layer or layers | 1 - | |
| DBOC | List[int] | Scaled raster layer or layers | 0 - | |
| DBIW | List[int] | Raster input window | 0 - 4 | Xoffset, Yoffset, Xsize, Ysize |
| DBOW | List[int] | Raster output window | 0 - 4 | Xoffset, Yoffset, Xsize, Ysize |
| INRANGE | List[float] | Input range (min,max) | 0 - | |
| TRIM | List[float] | Tail-trimming percentage (left, right) | 0 - 2 | 0 - 100 |
| OUTRANGE | List[float] | Output gray-level range (min,max) | 0 - 2 | |
| SFUNCT | str | Scaling function or quantization | 0 - 20 | LIN | SQR | ROOT | POW | LOG | NQ | EQ Default: LIN |
| DATATYPE | str | Output raster type | 0 - 3 | 8U | 16S | 16U | 32R Default: 8U |
| FTYPE | str | Output file type | 0 - 4 | |
| FOPTIONS | str | output file options | 0 - 64 |
| Back to top |
FILI
The name of the file from which to quantize or stretch image data.
FILO
The name of the file to which to write the processed image data.
If the output file you specify does not already exist, a new file is created, based on the values of the FTYPE and FOPTIONS parameters. An existing output file must be in a format that can be updated, and the file must already contain suitable channels to which to write the results written to the output channels defined by the DBOC parameter.
When your output file exists already, you need not specify a value for the FTYPE and FOPTIONS parameters.
The output file can be the same as the input file, provided that the input file meets the preceding criteria.
The output file will contain the same number of input channels as the input raster channel or channels. With new channels, however, the type is determined by the value of the DATATYPE parameter. The output file will have the same projection, geocoding, and file-level metadata as the input file.
DBIC
The input channel or channels to process.
DBOC
The channels to which to write the processed image data.
When your output file is a new file; that is, it does not exist already, you need not specify a value for this parameter; all channels in the new file will be of the bit depth specified by the value of the DATATYPE parameter.
The number of output channels you specify must be the same as the number of input channels.
If the output channel is the same as the input channel, the input channel data is overwritten.
This parameter is optional.
DBIW
The raster window (x-offset, y-offset, x-size, y-size) of data that is read from the input image. If no value is specified for this parameter, the entire channel is processed by default.
X-offset and y-offset define the upper-left starting pixel coordinates of the window. X-size is the number of pixels that define the window width. Y-size is the number of lines that define the window height.
This parameter is optional.
DBOW
The output raster window (x-offset, y-offset, x-size, y-size). If no value is specified for this parameter, the entire channel is used as output by default.
X-offset and y-offset define the upper-left starting pixel coordinates of the window. X-size is the number of pixels that define the window width. Y-size is the number of lines that define the window height.
The size of the output window must be the same as the input window.
This parameter is optional.
INRANGE
The value range of the input pixel.
If no value is specified for this parameter, SCALE calculates the range from the input raster data based on the tail-trimming levels (see the description of the TRIM parameter).
When the number of input channels is greater than one; and you specify your input range as one pair of values, this range (between the pair) is used for each input channel. When the number of input channels as multiple (must be 2 times of input channels) pairs of values, each range (between the pair) is used for each specific channel.
This parameter is optional.
TRIM
The amount of tail trimming to apply to the histogram of the input image before scaling.
The levels you specify define the input range for an image, must be in the range: 0 to 100, and the sum of the two values cannot be greater than 100.
If you specify a value for the INRANGE parameter, the specified input range is used and the TRIM parameter is ignored.
When no value is specified for the TRIM parameter, the minimum and maximum values of the image data for each input channel is used for the input range.
The TRIM parameter is useful only for scaling algorithms (LIN/SQR/ROOT/POW/LOG). The two quantization algorithms (EQ/NQ) squeeze tails automatically.
This parameter is optional.
OUTRANGE
The target pixel value range, after scaling.
The output range limit for 32R data is -100,000 to 100,000.
If no value is specified for this parameter, the output range defaults to the full range of the output-channel bit depth, except for 32R data which is set to the range limit.
When the number of output channels is greater than one, this range is used for each output channel.
This parameter is optional.
SFUNCT
The scaling function or quantization algorithm.
This parameter is optional.
DATATYPE
The data type of the output channel to create. When the output is written to existing channels, this parameter is ignored.
When the number of output channels is greater than one, the specified data type is used for each output channel.
This parameter is optional.
FTYPE
The format of the output file. The format must be a GDB-recognized type.
If you specify an existing file as your output file, you need not specify a value for this parameter; SCALE will update the file without changing its type.
The default value is PIX.
For a complete list of GDB-recognized file types, see GDB-supported file formats.
This parameter is optional.
FOPTIONS
The file-creation options to apply on creating the output file. These are specific to the format of the file; in each case, the default of no options is allowed. You can specify the compression schemes, file-format subtypes, and other information.
Different options are available for each type, as described for the FTYPE parameter.
For a complete list of GDB-recognized file types, see GDB-supported file formats.
This parameter is optional.
| Back to top |
SCALE maps the pixel values of the input raster to the pixel values of the output raster. Typically, you use SCALE to reduced the scale and quantize imagery in a high-resolution (32-bit or 16-bit) channel to a fewer number of pixel values to fit into a low-resolution (16-bit or 8-bit) channel. You can also use SCALE to visually enhance the input image by stretching or shifting the dynamic range.
The linear function equally scales data values from the input range to the output range. Other non-linear functions also perform compression and/or stretching.
The square function compresses the lower end of the spectrum and stretches the upper end. The effect is that the image gray levels are shifted towards the lower end and the image appears "darker" (as compared to the linearly scaled result).
On the contrary, the logarithmic and square root functions perform a greater amount of compression in the upper end (with the square root being "stronger" than logarithmic); hence, the image appears "brighter".
The general power function can be used to fine-tune the amount of compression and shifting in each direction, with a user-specified exponent value. If the exponent is greater than 1, the effect is shifting down; if the exponent is less than 1, the effect is shifting up.
By using the tail trimming levels (or by specifying an input range as a subrange within the image data range), you can exclude outlier values so as to increase the useful dynamic range in the output image.
The automatic normalized quantization algorithm transforms a typical input image (of a unimodal histogram) to a near-symmetric Gaussian-like distribution with the median input level transformed to the mid-point of the output range. The algorithm applies a smooth nonlinear function to gradually compress the extreme high or low portions of the input range. On the other hand, the middle portion of the data range is mapped with little distortion. This algorithm is recommended for image quantization to a lower number of pixel values. It is robust in handling 32-bit input images.
The equal-area quantization algorithm maps an image to the output range with an equalized output histogram (that is, each output level has approximately the same number of pixels).
Both quantization algorithms first attempt to estimate the histogram of the input image, then use it to build a mapping table. They do not require the input range (INRANGE) and trimming level (TRIM) parameters. The output of the two quantization algorithms can only be integer levels.
| Back to top |
In the following example, a 16-bit radar image (irvine.pix, channel 11) is mapped to a new 8U TIFF file using the automatic normalized quantization algorithm.
from pci.scale import scale fili = "irvine.pix" # input file filo = "irvine_radar_8U.tif" # create new output file dbic = [11] # 16-bit radar image dboc = [] # default dbiw = [] # default, process entire image dbow = [] # default, output entire image inrange = [] # default trim = [1] # trim 1% of low and high values outrange = [] # default sfunct = "NQ" # automatic normalized quantization datatype = "" # default to 8U ftype = "TIF" # output to a TIFF foptions = "" # output file options scale( fili, filo, dbic, dboc, dbiw, dbow, inrange, trim, outrange, sfunct, datatype, ftype, foptions )
| Back to top |
SCALE estimates the input image histogram by randomly sampling the image data and sorting the samples. This avoids binning (and, hence, prescaling) the data and, therefore, the resolution of the estimated histogram is not affected by extreme outlier values.
The quantization algorithms derive an inverse mapping table (from output levels to input intervals) based on the histogram. They then transform the pixels by looking up the table using a binary search.
In the automatic normalized quantization algorithm, the mapping function is in the form of:
sigmoid(x) = 1/(1 + exp(-x))
With properly scaled input and output variables based on the estimated histogram. The median level of the input image is always mapped to the middle of the output range.
In the tail-trimming scaling algorithms, the threshold gray levels at the specified tail percentage are determined from the estimated histogram.
To exclude a large area of background values from the estimated histogram, any multiple occurrences of the lowest and highest values among the samples are ignored.
Outliers
An important consideration in using SCALE is reducing the influence of outlier values on the scaling procedure. Outliers are the few pixels in an image with extremely high or low pixel values in comparison to the majority of pixels. For example, the radar image in channel 11 of irvine.pix has approximately 99 percent of pixel values in the range of 0 to 2,200. But some extreme pixel values are over 16,000.
If the image is linearly scaled to 8-bit, the useful data range will be squeezed to approximately 30 out of the 256 gray levels; a large portion of the dynamic range is occupied by the one percent outlier pixels. To efficiently use the output dynamic range, you can specify tail-trimming levels so that the highest or lowest portions of gray levels are excluded from being used in calculating the scaling function.
The automatic normalized quantization algorithm uses a smooth nonlinear function to map the input range of (-Infinity, Infinity) to a closed output range. The function automatically compresses extreme gray levels. Unlike tail-trimming approaches, using the smooth nonlinear function also has the advantage of not introducing high peaks at the two extreme bins of the output histogram.
The equal-area quantization procedure is also robust against outlier values.
After the scaling-and-quantization process, the ideal output histogram should fully occupy the dynamic range with no unnecessary empty or sparsely occupied slots in the middle. It is also advantageous that distortion to the image histogram is minimized.
NoData values
If the input data has the NO_DATA_VALUE metadata tag then any output pixel values scaled to the NO_DATA_VALUE are adjusted away from the NO_DATA_VALUE by 1 or -1. If the NO_DATA_VALUE is not present then all pixels are considered valid and no adjustments away from NoData are done.
© PCI Geomatics Enterprises, Inc.®, 2026. All rights reserved.