Leptonica 1.68
C Image Processing Library

Image up and downscaling, by linear interpolation, area mapping, and sampling; scaling from binary to gray; mipmap scaling; upscaling with thresholding; downscaling with min, max and rank value. More...
Go to the source code of this file.
Image up and downscaling, by linear interpolation, area mapping, and sampling; scaling from binary to gray; mipmap scaling; upscaling with thresholding; downscaling with min, max and rank value.
Toplevel scaling PIX *pixScale() *** PIX *pixScaleToSize() *** PIX *pixScaleGeneral() *** Linearly interpreted (usually up) scaling PIX *pixScaleLI() *** PIX *pixScaleColorLI() PIX *pixScaleColor2xLI() *** PIX *pixScaleColor4xLI() *** PIX *pixScaleGrayLI() PIX *pixScaleGray2xLI() PIX *pixScaleGray4xLI() Scaling by closest pixel sampling PIX *pixScaleBySampling() PIX *pixScaleByIntSubsampling() Fast integer factor subsampling RGB to gray and to binary PIX *pixScaleRGBToGrayFast() PIX *pixScaleRGBToBinaryFast() PIX *pixScaleGrayToBinaryFast() Downscaling with (antialias) smoothing PIX *pixScaleSmooth() *** PIX *pixScaleRGBToGray2() [special 2x reduction to gray] Downscaling with (antialias) area mapping PIX *pixScaleAreaMap() *** PIX *pixScaleAreaMap2() Binary scaling by closest pixel sampling PIX *pixScaleBinary() Scaletogray (1 bpp > 8 bpp; arbitrary downscaling) PIX *pixScaleToGray() PIX *pixScaleToGrayFast() Scaletogray (1 bpp > 8 bpp; integer downscaling) PIX *pixScaleToGray2() PIX *pixScaleToGray3() PIX *pixScaleToGray4() PIX *pixScaleToGray6() PIX *pixScaleToGray8() PIX *pixScaleToGray16() Scaletogray by mipmap(1 bpp > 8 bpp, arbitrary reduction) PIX *pixScaleToGrayMipmap() Grayscale scaling using mipmap PIX *pixScaleMipmap() Replicated (integer) expansion (all depths) PIX *pixExpandReplicate() Upscale 2x followed by binarization PIX *pixScaleGray2xLIThresh() PIX *pixScaleGray2xLIDither() Upscale 4x followed by binarization PIX *pixScaleGray4xLIThresh() PIX *pixScaleGray4xLIDither() Grayscale downscaling using min and max PIX *pixScaleGrayMinMax() PIX *pixScaleGrayMinMax2() Grayscale downscaling using rank value PIX *pixScaleGrayRankCascade() PIX *pixScaleGrayRank2() RGB scaling including alpha (blend) component and gamma transform PIX *pixScaleWithAlpha() *** PIX *pixScaleGammaXform() *** Note: these functions make an implicit assumption about RGB component ordering.
Definition in file scale.c.
Input: pixs (1, 2, 4, 8, 16 and 32 bpp) scalex, scaley Return: pixd, or null on error
This function scales 32 bpp RGB; 2, 4 or 8 bpp palette color; 2, 4, 8 or 16 bpp gray; and binary images.
When the input has palette color, the colormap is removed and the result is either 8 bpp gray or 32 bpp RGB, depending on whether the colormap has color entries. Images with 2, 4 or 16 bpp are converted to 8 bpp.
Because pixScale() is meant to be a very simple interface to a number of scaling functions, including the use of unsharp masking, the type of scaling and the sharpening parameters are chosen by default. Grayscale and color images are scaled using one of four methods, depending on the scale factors: (1) antialiased subsampling (lowpass filtering followed by subsampling, implemented here by area mapping), for scale factors less than 0.2 (2) antialiased subsampling with sharpening, for scale factors between 0.2 and 0.7 (3) linear interpolation with sharpening, for scale factors between 0.7 and 1.4 (4) linear interpolation without sharpening, for scale factors >= 1.4.
One could use subsampling for scale factors very close to 1.0, because it preserves sharp edges. Linear interpolation blurs edges because the dest pixels will typically straddle two src edge pixels. Subsmpling removes entire columns and rows, so the edge is not blurred. However, there are two reasons for not doing this. First, it moves edges, so that a straight line at a large angle to both horizontal and vertical will have noticable kinks where horizontal and vertical rasters are removed. Second, although it is very fast, you get good results on sharp edges by applying a sharpening filter.
For images with sharp edges, sharpening substantially improves the image quality for scale factors between about 0.2 and about 2.0. However, the generic sharpening operation is about 3 times slower than linear interpolation, so there is a speedvsquality tradeoff. (Note: the cases where the sharpening halfwidth is 1 or 2 have special implementations and are about twice as fast as the general case). When the scale factor is larger than 1.4, the cost, which is proportional to image area, is very large for the incremental quality improvement, so we cut off the use of sharpening at 1.4. For scale factors greater than 1.4, these highlevel scaling functions only do linear interpolation.
Because sharpening is computationally expensive, we provide the option of not doing it. To avoid sharpening, call pixScaleGeneral() with = 0.0. pixScale() uses a small amount of of sharpening because it strengthens edge pixels that are weak due to antialiasing. The sharpening factors are: * for scaling factors < 0.7: sharpfract = 0.2 sharpwidth = 1 * for scaling factors >= 0.7: sharpfract = 0.4 sharpwidth = 2
The constraints that tie sharpening to the scale factor in pixScaleGeneral() can be circumvented by calling with = 0.0. This can be followed by the sharpening of choice; e.g., pixUnsharpMasking().
Binary images are scaled by sampling the closest pixel, without any lowpass filtering (averaging of neighboring pixels). This will introduce aliasing for reductions, which can be prevented by using pixScaleToGray() instead.
*** Warning: implicit assumption about RGB component order for LI color scaling
Definition at line 181 of file scale.c.
References L_MAX, and pixScaleGeneral().
Referenced by AddScaledImages(), convertTiffMultipageToPS(), GenerateSetOfMargePix(), main(), pixacompDisplayTiledAndScaled(), pixaDisplayTiledAndScaled(), pixaDisplayTiledInRows(), pixAffineSequential(), pixConvertColorToSubpixelRGB(), pixConvertGrayToSubpixelRGB(), pixConvertToPdfDataSegmented(), pixDisplayWithTitle(), pixDisplayWriteFormat(), pixGetBackgroundGrayMapMorph(), pixGetBackgroundRGBMapMorph(), pixGetRankValueMaskedRGB(), pixHtmlViewer(), pixSaveTiledOutline(), pixScaleAreaMap(), pixScaleColorLI(), pixScaleGrayLI(), pixScaleLI(), pixScaleSmooth(), pixScaleToSize(), pixScaleWithAlpha(), pixWriteSegmentedPageToPS(), saConvertFilesToPdfData(), and TestImage().
Input: pixs (1, 2, 4, 8, 16 and 32 bpp) wd (target width; use 0 if using height as target) hd (target height; use 0 if using width as target) Return: pixd, or null on error
Notes: (1) The guarantees that the output scaled image has the dimension(s) you specify.
Definition at line 215 of file scale.c.
References ERROR_PTR, NULL, pixGetDimensions(), pixScale(), and PROCNAME.
Referenced by main(), and pixSaveTiledWithText().
PIX* pixScaleGeneral  (  PIX *  pixs, 
l_float32  scalex,  
l_float32  scaley,  
l_float32  sharpfract,  
l_int32  sharpwidth  
) 
Input: pixs (1, 2, 4, 8, 16 and 32 bpp) scalex, scaley sharpfract (use 0.0 to skip sharpening) sharpwidth (halfwidth of lowpass filter; typ. 1 or 2) Return: pixd, or null on error
Notes: (1) See pixScale() for usage. (2) This interface may change in the future, as other special cases are added. (3) The actual sharpening factors used depend on the maximum of the two scale factors (maxscale): maxscale <= 0.2: no sharpening 0.2 < maxscale < 1.4: uses the input parameters maxscale >= 1.4: no sharpening (4) To avoid sharpening for grayscale and color images with scaling factors between 0.2 and 1.4, call this function with == 0.0. (5) To use arbitrary sharpening in conjunction with scaling, call this function with = 0.0, and follow this with a call to pixUnsharpMasking() with your chosen parameters.
Definition at line 273 of file scale.c.
References ERROR_PTR, L_MAX, NULL, pixClone(), pixConvertTo8Or32(), pixCopy(), pixDestroy(), pixGetDepth(), pixScaleAreaMap(), pixScaleBinary(), pixScaleColorLI(), pixScaleGrayLI(), pixUnsharpMasking(), and PROCNAME.
Referenced by pixScale(), and pixScaleWithAlpha().
Input: pixs (2, 4, 8 or 32 bpp; with or without colormap) scalex, scaley (must both be >= 0.7) Return: pixd, or null on error
Notes: (1) This function should only be used when the scale factors are greater than or equal to 0.7, and typically greater than 1. If either scale factor is smaller than 0.7, we issue a warning and invoke pixScale(). (2) This works on 2, 4, 8, 16 and 32 bpp images, as well as on 2, 4 and 8 bpp images that have a colormap. If there is a colormap, it is removed to either gray or RGB, depending on the colormap. (3) The does a linear interpolation on the src image. (4) It dispatches to much faster implementations for the special cases of 2x and 4x expansion.
*** Warning: implicit assumption about RGB component ordering ***
Definition at line 353 of file scale.c.
References ERROR_PTR, L_MAX, L_WARNING, NULL, pixConvertTo8Or32(), pixDestroy(), pixGetDepth(), pixScale(), pixScaleColorLI(), pixScaleGrayLI(), and PROCNAME.
Referenced by main().
Input: pixs (32 bpp, representing rgb) scalex, scaley Return: pixd, or null on error
Notes: (1) If this is used for scale factors less than 0.7, it will suffer from antialiasing. A warning is issued. Particularly for document images with sharp edges, use pixScaleSmooth() or pixScaleAreaMap() instead. (2) For the general case, it's about 4x faster to manipulate the color pixels directly, rather than to make images out of each of the 3 components, scale each component using the pixScaleGrayLI(), and combine the results back into an rgb image. (3) The speed on intel hardware for the general case (not 2x) is about 10 * 10^6 destpixels/sec/GHz. (The special 2x case runs at about 80 * 10^6 destpixels/sec/GHz.)
Definition at line 411 of file scale.c.
References ERROR_PTR, L_MAX, L_WARNING, NULL, pixCopy(), pixCopyResolution(), pixCreate(), pixGetData(), pixGetDepth(), pixGetDimensions(), pixGetWpl(), pixScale(), pixScaleColor2xLI(), pixScaleColor4xLI(), pixScaleResolution(), PROCNAME, and scaleColorLILow().
Referenced by main(), pixScaleGeneral(), and pixScaleLI().
Input: pixs (32 bpp, representing rgb) Return: pixd, or null on error
Notes: (1) This is a special case of linear interpolated scaling, for 2x upscaling. It is about 8x faster than using the generic pixScaleColorLI(), and about 4x faster than using the special 2x scale function pixScaleGray2xLI() on each of the three components separately. (2) The speed on intel hardware is about 80 * 10^6 destpixels/sec/GHz (!!)
*** Warning: implicit assumption about RGB component ordering ***
Definition at line 473 of file scale.c.
References ERROR_PTR, NULL, pixCopyResolution(), pixCreate(), pixGetData(), pixGetDepth(), pixGetDimensions(), pixGetWpl(), pixScaleResolution(), PROCNAME, and scaleColor2xLILow().
Referenced by pixScaleColorLI().
Input: pixs (32 bpp, representing rgb) Return: pixd, or null on error
Notes: (1) This is a special case of color linear interpolated scaling, for 4x upscaling. It is about 3x faster than using the generic pixScaleColorLI(). (2) The speed on intel hardware is about 30 * 10^6 destpixels/sec/GHz (3) This scales each component separately, using pixScaleGray4xLI(). It would be about 4x faster to inline the color code properly, in analogy to scaleColor4xLILow(), and I leave this as an exercise for someone who really needs it.
Definition at line 516 of file scale.c.
References COLOR_BLUE, COLOR_GREEN, COLOR_RED, ERROR_PTR, NULL, pixCreateRGBImage(), pixDestroy(), pixGetDepth(), pixGetRGBComponent(), pixScaleGray4xLI(), and PROCNAME.
Referenced by pixScaleColorLI().
Input: pixs (8 bpp grayscale) scalex scaley Return: pixd, or null on error
This function is appropriate for upscaling (magnification: scale factors > 1), and for a small amount of downscaling (reduction: scale factors > 0.5). For scale factors less than 0.5, the best result is obtained by area mapping, but this is very expensive. So for such large reductions, it is more appropriate to do low pass filtering followed by subsampling, a combination which is effectively a cheap form of area mapping.
Some details follow.
For each pixel in the dest, this does a linear interpolation of 4 neighboring pixels in the src. Specifically, consider the UL corner of src and dest pixels. The UL corner of the dest falls within a src pixel, whose four corners are the UL corners of 4 adjacent src pixels. The value of the dest is taken by linear interpolation using the values of the four src pixels and the distance of the UL corner of the dest from each corner.
If the image is expanded so that the dest pixel is smaller than the src pixel, such interpolation is a reasonable approach. This interpolation is also good for a small image reduction factor that is not more than a 2x reduction.
Note that the linear interpolation algorithm for scaling is identical in form to the areamapping algorithm for grayscale rotation. The latter corresponds to a translation of each pixel without scaling.
This function is NOT optimal if the scaling involves a large reduction. If the image is significantly reduced, so that the dest pixel is much larger than the src pixels, this interpolation, which is over src pixels only near the UL corner of the dest pixel, is not going to give a good areamapping average. Because area mapping for image scaling is considerably more computationally intensive than linear interpolation, we choose not to use it. For large image reduction, linear interpolation over adjacent src pixels degenerates asymptotically to subsampling. But subsampling without a lowpass prefilter causes aliasing by the nyquist theorem. To avoid aliasing, a lowpass filter (e.g., an averaging filter) of size roughly equal to the dest pixel (i.e., the reduction factor) should be applied to the src before subsampling.
As an alternative to lowpass filtering and subsampling for large reduction factors, linear interpolation can also be done between the (widely separated) src pixels in which the corners of the dest pixel lie. This also is not optimal, as it samples src pixels only near the corners of the dest pixel, and it is not implemented.
Summary: (1) If this is used for scale factors less than 0.7, it will suffer from antialiasing. A warning is issued. Particularly for document images with sharp edges, use pixScaleSmooth() or pixScaleAreaMap() instead. (2) The speed on intel hardware for the general case (not 2x) is about 13 * 10^6 destpixels/sec/GHz. (The special 2x case runs at about 100 * 10^6 destpixels/sec/GHz.)
Definition at line 623 of file scale.c.
References ERROR_PTR, L_MAX, L_WARNING, NULL, pixCopy(), pixCopyResolution(), pixCreate(), pixGetColormap(), pixGetData(), pixGetDepth(), pixGetDimensions(), pixGetWpl(), pixScale(), pixScaleGray2xLI(), pixScaleGray4xLI(), pixScaleResolution(), PROCNAME, and scaleGrayLILow().
Referenced by main(), pixScaleGeneral(), pixScaleLI(), pixScaleToGray(), pixScaleToGrayFast(), pixScaleToGrayMipmap(), and pixWriteSegmentedPageToPS().
Input: pixs (8 bpp grayscale) Return: pixd, or null on error
Notes: (1) This is a special case of gray linear interpolated scaling, for 2x upscaling. It is about 6x faster than using the generic pixScaleGrayLI(). (2) The speed on intel hardware is about 100 * 10^6 destpixels/sec/GHz
Definition at line 683 of file scale.c.
References ERROR_PTR, L_WARNING, NULL, pixCopyResolution(), pixCreate(), pixGetColormap(), pixGetData(), pixGetDepth(), pixGetDimensions(), pixGetWpl(), pixScaleResolution(), PROCNAME, and scaleGray2xLILow().
Referenced by pixScaleGrayLI().
Input: pixs (8 bpp grayscale) Return: pixd, or null on error
Notes: (1) This is a special case of gray linear interpolated scaling, for 4x upscaling. It is about 12x faster than using the generic pixScaleGrayLI(). (2) The speed on intel hardware is about 160 * 10^6 destpixels/sec/GHz (!!)
Definition at line 724 of file scale.c.
References ERROR_PTR, L_WARNING, NULL, pixCopyResolution(), pixCreate(), pixGetColormap(), pixGetData(), pixGetDepth(), pixGetDimensions(), pixGetWpl(), pixScaleResolution(), PROCNAME, and scaleGray4xLILow().
Referenced by pixScaleColor4xLI(), and pixScaleGrayLI().
Input: pixs (1, 2, 4, 8, 16, 32 bpp) scalex, scaley Return: pixd, or null on error
Notes: (1) This function samples from the source without filtering. As a result, aliasing will occur for subsampling ( and/or < 1.0). (2) If == 1.0 and == 1.0, returns a copy.
Definition at line 769 of file scale.c.
References ERROR_PTR, NULL, pixCopy(), pixCopyColormap(), pixCopyResolution(), pixCreate(), pixGetData(), pixGetDepth(), pixGetDimensions(), pixGetWpl(), pixScaleBinary(), pixScaleResolution(), PROCNAME, and scaleBySamplingLow().
Referenced by main(), pixConvertTo1BySampling(), pixConvertTo32BySampling(), pixConvertTo8BySampling(), pixDisplayHitMissSel(), pixDisplayMatchedPattern(), pixFastTophat(), pixGetBackgroundGrayMap(), pixGetBackgroundGrayMapMorph(), pixGetBackgroundRGBMap(), pixMakeHistoHS(), pixMakeHistoHV(), pixMakeHistoSV(), pixOctreeColorQuantGeneral(), pixScaleByIntSubsampling(), selaAddCrossJunctions(), and selaAddTJunctions().
Input: pixs (1, 2, 4, 8, 16, 32 bpp) factor (integer subsampling) Return: pixd, or null on error
Notes: (1) Simple interface to pixScaleBySampling(), for isotropic integer reduction. (2) If == 1, returns a copy.
Definition at line 816 of file scale.c.
References ERROR_PTR, L_ERROR, NULL, pixCopy(), pixScaleBySampling(), and PROCNAME.
Referenced by pixGetRankColorArray().
Input: pixs (32 bpp rgb) factor (integer reduction factor >= 1) color (one of COLOR_RED, COLOR_GREEN, COLOR_BLUE) Return: pixd (8 bpp), or null on error
Notes: (1) This does simultaneous subsampling by an integer factor and extraction of the color from the RGB pix. (2) It is designed for maximum speed, and is used for quickly generating a downsized grayscale image from a higher resolution RGB image. This would typically be used for image analysis. (3) The standard color byte order (RGBA) is assumed.
Definition at line 856 of file scale.c.
References COLOR_BLUE, COLOR_GREEN, COLOR_RED, ERROR_PTR, L_BLUE_SHIFT, L_GREEN_SHIFT, L_RED_SHIFT, NULL, pixCopyResolution(), pixCreate(), pixGetData(), pixGetDepth(), pixGetDimensions(), pixGetWpl(), pixScaleResolution(), PROCNAME, and SET_DATA_BYTE.
Referenced by main(), pixGetBackgroundRGBMapMorph(), and pixGetRankValueMaskedRGB().
Input: pixs (32 bpp RGB) factor (integer reduction factor >= 1) thresh (binarization threshold) Return: pixd (1 bpp), or null on error
Notes: (1) This does simultaneous subsampling by an integer factor and conversion from RGB to gray to binary. (2) It is designed for maximum speed, and is used for quickly generating a downsized binary image from a higher resolution RGB image. This would typically be used for image analysis. (3) It uses the green channel to represent the RGB pixel intensity.
Definition at line 928 of file scale.c.
References ERROR_PTR, L_GREEN_SHIFT, NULL, pixCopyResolution(), pixCreate(), pixGetData(), pixGetDepth(), pixGetDimensions(), pixGetWpl(), pixScaleResolution(), PROCNAME, and SET_DATA_BIT.
Input: pixs (8 bpp grayscale) factor (integer reduction factor >= 1) thresh (binarization threshold) Return: pixd (1 bpp), or null on error
Notes: (1) This does simultaneous subsampling by an integer factor and thresholding from gray to binary. (2) It is designed for maximum speed, and is used for quickly generating a downsized binary image from a higher resolution gray image. This would typically be used for image analysis.
Definition at line 991 of file scale.c.
References ERROR_PTR, GET_DATA_BYTE, NULL, pixCopyResolution(), pixCreate(), pixGetData(), pixGetDepth(), pixGetDimensions(), pixGetWpl(), pixScaleResolution(), PROCNAME, and SET_DATA_BIT.
Input: pixs (2, 4, 8 or 32 bpp; and 2, 4, 8 bpp with colormap) scalex, scaley (must both be < 0.7) Return: pixd, or null on error
Notes: (1) This function should only be used when the scale factors are less than or equal to 0.7 (i.e., more than about 1.42x reduction). If either scale factor is larger than 0.7, we issue a warning and invoke pixScale(). (2) This works only on 2, 4, 8 and 32 bpp images, and if there is a colormap, it is removed by converting to RGB. In other cases, we issue a warning and invoke pixScale(). (3) It does simple (flat filter) convolution, with a filter size commensurate with the amount of reduction, to avoid antialiasing. (4) It does simple subsampling after smoothing, which is appropriate for this range of scaling. Linear interpolation gives essentially the same result with more computation for these scale factors, so we don't use it. (5) The result is the same as doing a full block convolution followed by subsampling, but this is faster because the results of the block convolution are only computed at the subsampling locations. In fact, the computation time is approximately independent of the scale factor, because the convolution kernel is adjusted so that each source pixel is summed approximately once.
*** Warning: implicit assumption about RGB component ordering ***
Definition at line 1072 of file scale.c.
References ERROR_PTR, FALSE, L_MAX, L_MIN, L_WARNING, NULL, pixClone(), pixConvertTo8(), pixCopyResolution(), pixCreate(), pixDestroy(), pixGetColormap(), pixGetData(), pixGetDepth(), pixGetDimensions(), pixGetWpl(), pixRemoveColormap(), pixScale(), pixScaleResolution(), PROCNAME, REMOVE_CMAP_BASED_ON_SRC, scaleSmoothLow(), and size.
Referenced by main(), pixBackgroundNormFlex(), pixScaleToGray(), pixScaleToGrayFast(), and pixScaleToGrayMipmap().
Input: pixs (32 bpp rgb) rwt, gwt, bwt (must sum to 1.0) Return: pixd, (8 bpp, 2x reduced), or null on error
Definition at line 1154 of file scale.c.
References ERROR_PTR, NULL, pixCopyResolution(), pixCreate(), pixGetData(), pixGetDepth(), pixGetHeight(), pixGetWidth(), pixGetWpl(), pixScaleResolution(), PROCNAME, and scaleRGBToGray2Low().
Input: pixs (2, 4, 8 or 32 bpp; and 2, 4, 8 bpp with colormap) scalex, scaley (must both be <= 0.7) Return: pixd, or null on error
Notes: (1) This function should only be used when the scale factors are less than or equal to 0.7 (i.e., more than about 1.42x reduction). If either scale factor is larger than 0.7, we issue a warning and invoke pixScale(). (2) This works only on 2, 4, 8 and 32 bpp images. If there is a colormap, it is removed by converting to RGB. In other cases, we issue a warning and invoke pixScale(). (3) It does a relatively expensive area mapping computation, to avoid antialiasing. It is about 2x slower than pixScaleSmooth(), but the results are much better on fine text. (4) This is typically about 20% faster for the special cases of 2x, 4x, 8x and 16x reduction. (5) Surprisingly, there is no speedup (and a slight quality impairment) if you do as many successive 2x reductions as possible, ending with a reduction with a scale factor larger than 0.5.
*** Warning: implicit assumption about RGB component ordering ***
Definition at line 1218 of file scale.c.
References ERROR_PTR, FALSE, L_MAX, L_WARNING, NULL, pixClone(), pixConvertTo8(), pixCopyResolution(), pixCreate(), pixDestroy(), pixGetColormap(), pixGetData(), pixGetDepth(), pixGetDimensions(), pixGetWpl(), pixRemoveColormap(), pixScale(), pixScaleAreaMap2(), pixScaleResolution(), PROCNAME, REMOVE_CMAP_BASED_ON_SRC, scaleColorAreaMapLow(), and scaleGrayAreaMapLow().
Referenced by main(), pixColorsForQuantization(), pixScaleGeneral(), and pixWriteSegmentedPageToPS().
Input: pixs (2, 4, 8 or 32 bpp; and 2, 4, 8 bpp with colormap) Return: pixd, or null on error
Notes: (1) This function does an area mapping (average) for 2x reduction. (2) This works only on 2, 4, 8 and 32 bpp images. If there is a colormap, it is removed by converting to RGB. (3) Speed on 3 GHz processor: Color: 160 Mpix/sec Gray: 700 Mpix/sec This contrasts with the speed of the general pixScaleAreaMap(): Color: 35 Mpix/sec Gray: 50 Mpix/sec (4) From (3), we see that this special function is about 4.5x faster for color and 14x faster for grayscale (5) Consequently, pixScaleAreaMap2() is incorporated into the general area map scaling function, for the special cases of 2x, 4x, 8x and 16x reduction.
Definition at line 1333 of file scale.c.
References ERROR_PTR, FALSE, L_WARNING, NULL, pixClone(), pixConvertTo8(), pixCopyResolution(), pixCreate(), pixDestroy(), pixGetColormap(), pixGetData(), pixGetDepth(), pixGetHeight(), pixGetWidth(), pixGetWpl(), pixRemoveColormap(), pixScaleResolution(), PROCNAME, REMOVE_CMAP_BASED_ON_SRC, and scaleAreaMapLow2().
Referenced by pixColorsForQuantization(), and pixScaleAreaMap().
Input: pixs (1 bpp) scalex, scaley Return: pixd, or null on error
Notes: (1) This function samples from the source without filtering. As a result, aliasing will occur for subsampling (scalex and scaley < 1.0).
Definition at line 1392 of file scale.c.
References ERROR_PTR, NULL, pixCopy(), pixCopyColormap(), pixCopyResolution(), pixCreate(), pixGetData(), pixGetDepth(), pixGetDimensions(), pixGetWpl(), pixScaleResolution(), PROCNAME, and scaleBinaryLow().
Referenced by main(), pixScaleBySampling(), pixScaleGeneral(), pixScaleToGray(), and pixScaleToGrayFast().
Input: pixs (1 bpp) scalefactor (reduction, < 1.0) Return: pixd (8 bpp), scaled down by scalefactor in each direction, or NULL on error.
Notes:
For faster scaling in the range of scalefactors from 0.0625 to 0.5, with very little difference in quality, use pixScaleToGrayFast().
Binary images have sharp edges, so they intrinsically have very high frequency content. To avoid aliasing, they must be lowpass filtered, which tends to blur the edges. How can we keep relatively crisp edges without aliasing? The trick is to do binary upscaling followed by a powerof2 scaleToGray. For large reductions, where you don't end up with much detail, some corners can be cut.
The intent here is to get high quality reduced grayscale images with relatively little computation. We do binary prescaling followed by scaleToGrayN() for best results, esp. to avoid excess blur when the scale factor is near an inverse power of 2. Where a lowpass filter is required, we use simple convolution kernels: either the hat filter for linear interpolation or a flat filter for larger downscaling. Other choices, such as a perfect bandpass filter with infinite extent (the sinc) or various approximations to it (e.g., lanczos), are unnecessarily expensive.
The choices made are as follows: (1) Do binary upscaling before scaleToGrayN() for scalefactors > 1/8 (2) Do binary downscaling before scaleToGray8() for scalefactors between 1/16 and 1/8. (3) Use scaleToGray16() before grayscale downscaling for scalefactors less than 1/16 Another reasonable choice would be to start binary downscaling for scalefactors below 1/4, rather than below 1/8 as we do here.
The general scaling rules, not all of which are used here, go as follows: (1) For grayscale upscaling, use pixScaleGrayLI(). However, note that edges will be visibly blurred for scalefactors near (but above) 1.0. Replication will avoid edge blur, and should be considered for factors very near 1.0. (2) For grayscale downscaling with a scale factor larger than about 0.7, use pixScaleGrayLI(). For scalefactors near (but below) 1.0, you tread between Scylla and Charybdis. pixScaleGrayLI() again gives edge blurring, but pixScaleBySampling() gives visible aliasing. (3) For grayscale downscaling with a scale factor smaller than about 0.7, use pixScaleSmooth() (4) For binary input images, do as much scale to gray as possible using the special integer functions (2, 3, 4, 8 and 16). (5) It is better to upscale in binary, followed by scaleToGrayN() than to do scaleToGrayN() followed by an upscale using either LI or oversampling. (6) It may be better to downscale in binary, followed by scaleToGrayN() than to first use scaleToGrayN() followed by downscaling. For downscaling between 8x and 16x, this is a reasonable option. (7) For reductions greater than 16x, it's reasonable to use scaleToGray16() followed by further grayscale downscaling.
Definition at line 1495 of file scale.c.
References ERROR_PTR, L_MIN, NULL, pixDestroy(), pixGetDepth(), pixGetDimensions(), pixScaleBinary(), pixScaleGrayLI(), pixScaleSmooth(), pixScaleToGray16(), pixScaleToGray2(), pixScaleToGray3(), pixScaleToGray4(), pixScaleToGray6(), pixScaleToGray8(), and PROCNAME.
Referenced by main(), pixacompDisplayTiledAndScaled(), pixaDisplayTiledAndScaled(), pixConvertToPdfDataSegmented(), pixDisplayMatchedPattern(), pixDisplayWriteFormat(), and pixSaveTiledOutline().
Input: pixs (1 bpp) scalefactor (reduction, < 1.0) Return: pixd (8 bpp), scaled down by scalefactor in each direction, or NULL on error.
Notes: (1) See notes in pixScaleToGray() for the basic approach. (2) This function is considerably less expensive than pixScaleToGray() for scalefactor in the range (0.0625 ... 0.5), and the quality is nearly as good. (3) Unlike pixScaleToGray(), which does binary upscaling before downscaling for scale factors >= 0.0625, pixScaleToGrayFast() first downscales in binary for all scale factors < 0.5, and then does a 2x scaletogray as the final step. For scale factors < 0.0625, both do a 16x scaletogray, followed by further grayscale reduction.
Definition at line 1609 of file scale.c.
References ERROR_PTR, L_MIN, NULL, pixDestroy(), pixGetDepth(), pixGetDimensions(), pixScaleBinary(), pixScaleGrayLI(), pixScaleSmooth(), pixScaleToGray16(), pixScaleToGray2(), pixScaleToGray3(), pixScaleToGray4(), pixScaleToGray6(), pixScaleToGray8(), and PROCNAME.
Input: pixs (1 bpp) Return: pixd (8 bpp), scaled down by 2x in each direction, or null on error.
Definition at line 1679 of file scale.c.
References ERROR_PTR, FREE, makeSumTabSG2(), makeValTabSG2(), NULL, pixCopyResolution(), pixCreate(), pixGetData(), pixGetDepth(), pixGetDimensions(), pixGetWpl(), pixScaleResolution(), PROCNAME, and scaleToGray2Low().
Referenced by DoPageSegmentation(), main(), pixDisplayWithTitle(), pixScaleToGray(), pixScaleToGrayFast(), pixScaleToGrayMipmap(), and RotateTest().
Input: pixs (1 bpp) Return: pixd (8 bpp), scaled down by 3x in each direction, or null on error.
Notes: (1) Speed is about 100 x 10^6 srcpixels/sec/GHz. Another way to express this is it processes 1 src pixel in about 10 cycles. (2) The width of pixd is truncated is truncated to a factor of 8.
Definition at line 1737 of file scale.c.
References ERROR_PTR, FREE, makeSumTabSG3(), makeValTabSG3(), NULL, pixCopyResolution(), pixCreate(), pixGetData(), pixGetDepth(), pixGetDimensions(), pixGetWpl(), pixScaleResolution(), PROCNAME, and scaleToGray3Low().
Referenced by main(), pixDisplayWithTitle(), pixScaleToGray(), and pixScaleToGrayFast().
Input: pixs (1 bpp) Return: pixd (8 bpp), scaled down by 4x in each direction, or null on error.
Notes: (1) The width of pixd is truncated is truncated to a factor of 2.
Definition at line 1792 of file scale.c.
References ERROR_PTR, FREE, makeSumTabSG4(), makeValTabSG4(), NULL, pixCopyResolution(), pixCreate(), pixGetData(), pixGetDepth(), pixGetDimensions(), pixGetWpl(), pixScaleResolution(), PROCNAME, and scaleToGray4Low().
Referenced by main(), pixDisplayWithTitle(), pixScaleToGray(), pixScaleToGrayFast(), and pixScaleToGrayMipmap().
Input: pixs (1 bpp) Return: pixd (8 bpp), scaled down by 6x in each direction, or null on error.
Notes: (1) The width of pixd is truncated is truncated to a factor of 8.
Definition at line 1848 of file scale.c.
References ERROR_PTR, FREE, makePixelSumTab8(), makeValTabSG6(), NULL, pixCopyResolution(), pixCreate(), pixGetData(), pixGetDepth(), pixGetDimensions(), pixGetWpl(), pixScaleResolution(), PROCNAME, and scaleToGray6Low().
Referenced by main(), pixScaleToGray(), and pixScaleToGrayFast().
Input: pixs (1 bpp) Return: pixd (8 bpp), scaled down by 8x in each direction, or null on error
Definition at line 1899 of file scale.c.
References ERROR_PTR, FREE, makePixelSumTab8(), makeValTabSG8(), NULL, pixCopyResolution(), pixCreate(), pixGetData(), pixGetDepth(), pixGetDimensions(), pixGetWpl(), pixScaleResolution(), PROCNAME, and scaleToGray8Low().
Referenced by main(), pixDisplayWithTitle(), pixScaleToGray(), pixScaleToGrayFast(), and pixScaleToGrayMipmap().
Input: pixs (1 bpp) Return: pixd (8 bpp), scaled down by 16x in each direction, or null on error.
Definition at line 1951 of file scale.c.
References ERROR_PTR, FREE, makePixelSumTab8(), NULL, pixCopyResolution(), pixCreate(), pixGetData(), pixGetDepth(), pixGetDimensions(), pixGetWpl(), pixScaleResolution(), PROCNAME, and scaleToGray16Low().
Referenced by main(), pixScaleToGray(), pixScaleToGrayFast(), and pixScaleToGrayMipmap().
Input: pixs (1 bpp) scalefactor (reduction, < 1.0) Return: pixd (8 bpp), scaled down by scalefactor in each direction, or NULL on error.
Notes:
This function is here mainly for pedagogical reasons. Mipmapping is widely used in graphics for texture mapping, because the texture changes smoothly with scale. This is accomplished by constructing a multiresolution pyramid and, for each pixel, doing a linear interpolation between corresponding pixels in the two planes of the pyramid that bracket the desired resolution. The computation is very efficient, and is implemented in hardware in highend graphics cards.
We can use mipmapping for scaletogray by using two scaletogray reduced images (we don't need the entire pyramid) selected from the set {2x, 4x, ... 16x}, and interpolating. However, we get severe aliasing, probably because we are subsampling from the higher resolution image. The method is very fast, but the result is very poor. In fact, the results don't look any better than either subsampling off the higherres grayscale image or oversampling on the lowerres image. Consequently, this method should NOT be used for generating reduced images, scaletogray or otherwise.
Definition at line 2024 of file scale.c.
References ERROR_PTR, L_MIN, NULL, pixConvert1To8(), pixDestroy(), pixGetDepth(), pixGetDimensions(), pixScaleGrayLI(), pixScaleMipmap(), pixScaleSmooth(), pixScaleToGray16(), pixScaleToGray2(), pixScaleToGray4(), pixScaleToGray8(), and PROCNAME.
Referenced by main().
Input: pixs1 (high res 8 bpp) pixs2 (low res  2x reduced  8 bpp) scale (reduction with respect to high res image, > 0.5) Return: 8 bpp pix, scaled down by reduction in each direction, or NULL on error.
Notes: (1) See notes in pixScaleToGrayMipmap(). (2) This function suffers from aliasing effects that are easily seen in document images.
Definition at line 2115 of file scale.c.
References ERROR_PTR, L_WARNING, NULL, pixCopyResolution(), pixCreate(), pixGetColormap(), pixGetData(), pixGetDimensions(), pixGetHeight(), pixGetWidth(), pixGetWpl(), pixScaleResolution(), PROCNAME, and scaleMipmapLow().
Referenced by pixScaleToGrayMipmap().
Input: pixs (1, 2, 4, 8, 16, 32 bpp) factor (integer scale factor for replicative expansion) Return: pixd (scaled up), or null on error.
Definition at line 2173 of file scale.c.
References ERROR_PTR, GET_DATA_BYTE, GET_DATA_DIBIT, GET_DATA_QBIT, GET_DATA_TWO_BYTES, NULL, pixCopy(), pixCopyColormap(), pixCopyResolution(), pixCreate(), pixExpandBinaryReplicate(), pixGetData(), pixGetDimensions(), pixGetWpl(), pixScaleResolution(), PROCNAME, SET_DATA_BYTE, SET_DATA_DIBIT, SET_DATA_QBIT, and SET_DATA_TWO_BYTES.
Referenced by displayHSVColorRange(), fpixaDisplayQuadtree(), jbGetComponents(), main(), pixGenHalftoneMask(), pixGetRegionsBinary(), pixMorphCompSequence(), pixMorphCompSequenceDwa(), pixMorphSequence(), and pixMorphSequenceDwa().
Input: pixs (8 bpp) thresh (between 0 and 256) Return: pixd (1 bpp), or null on error
Notes: (1) This does 2x upscale on pixs, using linear interpolation, followed by thresholding to binary. (2) Buffers are used to avoid making a large grayscale image.
Definition at line 2307 of file scale.c.
References CALLOC, ERROR_PTR, FREE, L_WARNING, NULL, pixCopyResolution(), pixCreate(), pixGetColormap(), pixGetData(), pixGetDepth(), pixGetDimensions(), pixGetWpl(), pixScaleResolution(), PROCNAME, scaleGray2xLILineLow(), and thresholdToBinaryLineLow().
Referenced by convertFilesTo1bpp(), main(), and pixConvertToPdfDataSegmented().
Input: pixs (8 bpp) Return: pixd (1 bpp), or null on error
Notes: (1) This does 2x upscale on pixs, using linear interpolation, followed by FloydSteinberg dithering to binary. (2) Buffers are used to avoid making a large grayscale image.
Definition at line 2384 of file scale.c.
References CALLOC, DEFAULT_CLIP_LOWER_1, DEFAULT_CLIP_UPPER_1, ditherToBinaryLineLow(), ERROR_PTR, FREE, L_WARNING, NULL, pixCopyResolution(), pixCreate(), pixGetColormap(), pixGetData(), pixGetDepth(), pixGetDimensions(), pixGetWpl(), pixScaleResolution(), PROCNAME, and scaleGray2xLILineLow().
Referenced by main().
Input: pixs (8 bpp) thresh (between 0 and 256) Return: pixd (1 bpp), or null on error
Notes: (1) This does 4x upscale on pixs, using linear interpolation, followed by thresholding to binary. (2) Buffers are used to avoid making a large grayscale image. (3) If a full 4x expanded grayscale image can be kept in memory, this function is only about 10% faster than separately doing a linear interpolation to a large grayscale image, followed by thresholding to binary.
Definition at line 2496 of file scale.c.
References CALLOC, ERROR_PTR, FREE, L_WARNING, NULL, pixCopyResolution(), pixCreate(), pixGetColormap(), pixGetData(), pixGetDepth(), pixGetDimensions(), pixGetWpl(), pixScaleResolution(), PROCNAME, scaleGray4xLILineLow(), and thresholdToBinaryLineLow().
Referenced by convertFilesTo1bpp(), and main().
Input: pixs (8 bpp) Return: pixd (1 bpp), or null on error
Notes: (1) This does 4x upscale on pixs, using linear interpolation, followed by FloydSteinberg dithering to binary. (2) Buffers are used to avoid making a large grayscale image.
Definition at line 2582 of file scale.c.
References CALLOC, DEFAULT_CLIP_LOWER_1, DEFAULT_CLIP_UPPER_1, ditherToBinaryLineLow(), ERROR_PTR, FREE, L_WARNING, NULL, pixCopyResolution(), pixCreate(), pixGetColormap(), pixGetData(), pixGetDepth(), pixGetDimensions(), pixGetWpl(), pixScaleResolution(), PROCNAME, and scaleGray4xLILineLow().
Referenced by main().
Input: pixs (8 bpp) xfact (x downscaling factor; integer) yfact (y downscaling factor; integer) type (L_CHOOSE_MIN, L_CHOOSE_MAX, L_CHOOSE_MAX_MIN_DIFF) Return: pixd (8 bpp)
Notes: (1) The downscaled pixels in pixd are the min, max or (max  min) of the corresponding set of xfact * yfact pixels in pixs. (2) Using L_CHOOSE_MIN is equivalent to a grayscale erosion, using a brick Sel of size (xfact * yfact), followed by subsampling within each (xfact * yfact) cell. Using L_CHOOSE_MAX is equivalent to the corresponding dilation. (3) Using L_CHOOSE_MAX_MIN_DIFF finds the difference between max and min values in each cell. (4) For the special case of downscaling by 2x in both directions, pixScaleGrayMinMax2() is about 2x more efficient.
Definition at line 2706 of file scale.c.
References ERROR_PTR, GET_DATA_BYTE, L_CHOOSE_MAX, L_CHOOSE_MAX_MIN_DIFF, L_CHOOSE_MIN, NULL, pixCreate(), pixGetData(), pixGetDimensions(), pixGetWpl(), pixScaleGrayMinMax2(), PROCNAME, and SET_DATA_BYTE.
Referenced by pixFastTophat(), and pixMinMaxTiles().
Input: pixs (8 bpp) type (L_CHOOSE_MIN, L_CHOOSE_MAX, L_CHOOSE_MAX_MIN_DIFF) Return: pixd (8 bpp downscaled by 2x)
Notes: (1) Special version for 2x reduction. The downscaled pixels in pixd are the min, max or (max  min) of the corresponding set of 4 pixels in pixs. (2) The max and min operations are a special case (for levels 1 and 4) of grayscale analog to the binary rank scaling operation pixReduceRankBinary2(). Note, however, that because of the photometric definition that higher gray values are lighter, the erosionlike L_CHOOSE_MIN will darken the resulting image, corresponding to a threshold level 1 in the binary case. Likewise, L_CHOOSE_MAX will lighten the pixd, corresponding to a threshold level of 4. (3) To choose any of the four rank levels in a 2x grayscale reduction, use pixScaleGrayRank2(). (4) This runs at about 70 MPix/sec/GHz of source data for erosion and dilation.
Definition at line 2811 of file scale.c.
References ERROR_PTR, GET_DATA_BYTE, L_CHOOSE_MAX, L_CHOOSE_MAX_MIN_DIFF, L_CHOOSE_MIN, NULL, pixCreate(), pixGetData(), pixGetDimensions(), pixGetWpl(), PROCNAME, and SET_DATA_BYTE.
Referenced by pixScaleGrayMinMax(), and pixScaleGrayRank2().
PIX* pixScaleGrayRankCascade  (  PIX *  pixs, 
l_int32  level1,  
l_int32  level2,  
l_int32  level3,  
l_int32  level4  
) 
Input: pixs (8 bpp) level1, ... level4 (rank thresholds, in set {0, 1, 2, 3, 4}) Return: pixd (8 bpp, downscaled by up to 16x)
Notes: (1) This performs up to four cascaded 2x rank reductions. (2) Use level = 0 to truncate the cascade.
Definition at line 2891 of file scale.c.
References ERROR_PTR, L_WARNING, NULL, pixCopy(), pixDestroy(), pixGetDepth(), pixScaleGrayRank2(), and PROCNAME.
Referenced by main().
Input: pixs (8 bpp) rank (1 (darkest), 2, 3, 4 (lightest)) Return: pixd (8 bpp, downscaled by 2x)
Notes: (1) Rank 2x reduction. If rank == 1(4), the downscaled pixels in pixd are the min(max) of the corresponding set of 4 pixels in pixs. Values 2 and 3 are intermediate. (2) This is the grayscale analog to the binary rank scaling operation pixReduceRankBinary2(). Here, because of the photometric definition that higher gray values are lighter, rank 1 gives the darkest pixel, whereas rank 4 gives the lightest pixel. This is opposite to the binary rank operation. (3) For rank = 1 and 4, this calls pixScaleGrayMinMax2(), which runs at about 70 MPix/sec/GHz of source data. For rank 2 and 3, this runs 3x slower, at about 25 MPix/sec/GHz.
Definition at line 2954 of file scale.c.
References ERROR_PTR, GET_DATA_BYTE, L_CHOOSE_MAX, L_CHOOSE_MIN, L_MAX, L_MIN, NULL, pixCreate(), pixGetData(), pixGetDimensions(), pixGetWpl(), pixScaleGrayMinMax2(), PROCNAME, and SET_DATA_BYTE.
Referenced by main(), and pixScaleGrayRankCascade().
PIX* pixScaleWithAlpha  (  PIX *  pixs, 
l_float32  scalex,  
l_float32  scaley,  
PIX *  pixg,  
l_float32  fract  
) 
Input: pixs (32 bpp rgb) scalex, scaley pixg (<optional> 8 bpp, can be null) fract (between 0.0 and 1.0, with 0.0 fully transparent and 1.0 fully opaque) Return: pixd, or null on error
Notes: (1) The alpha channel is transformed separately from pixs, and aligns with it, being fully transparent outside the boundary of the transformed pixs. For pixels that are fully transparent, a blending function like pixBlendWithGrayMask() will give zero weight to corresponding pixels in pixs. (2) Scaling is done with area mapping or linear interpolation, depending on the scale factors. Default sharpening is done. (3) If pixg is NULL, it is generated as an alpha layer that is partially opaque, using . Otherwise, it is cropped to pixs if required, and is ignored. The alpha channel in pixs is never used. (4) Colormaps are removed. (5) The default setting for the border values in the alpha channel is 0 (transparent) for the outermost ring of pixels and (0.5 * fract * 255) for the second ring. When blended over a second image, this (a) shrinks the visible image to make a clean overlap edge with an image below, and (b) softens the edges by weakening the aliasing there. Use l_setAlphaMaskBorder() to change these values.
*** Warning: implicit assumption about RGB component ordering ***
Definition at line 3065 of file scale.c.
References AlphaMaskBorderVals, ERROR_PTR, L_ALPHA_CHANNEL, L_WARNING, NULL, pixCreate(), pixDestroy(), pixGetColormap(), pixGetDepth(), pixGetDimensions(), pixResizeToMatch(), pixScale(), pixScaleGeneral(), pixSetAll(), pixSetAllArbitrary(), pixSetBorderRingVal(), pixSetRGBComponent(), and PROCNAME.
Referenced by main(), and pixScaleGammaXform().
PIX* pixScaleGammaXform  (  PIX *  pixs, 
l_float32  gamma,  
l_float32  scalex,  
l_float32  scaley,  
l_float32  fract  
) 
Input: pixs (32 bpp rgb) gamma (gamma correction; must be > 0.0) scalex, scaley fract (between 0.0 and 1.0, with 1.0 fully transparent) Return: pixd, or null on error
Notes: (1) This wraps a gamma/inversegamma photometric transform around pixScaleWithAlpha(). (2) For usage, see notes in pixScaleWithAlpha() and pixGammaTRCWithAlpha(). (3) The basic idea of a gamma/inversegamma transform is to remove gamma correction before scaling and restore it afterward. The effects can be subtle, but important for some applications. For example, using gamma > 1.0 will cause the dark areas to become somewhat lighter and slightly reduce aliasing effects when blending using the alpha channel.
Definition at line 3140 of file scale.c.
References ERROR_PTR, L_WARNING, NULL, pixDestroy(), pixGammaTRCWithAlpha(), pixGetDepth(), pixScaleWithAlpha(), and PROCNAME.
Referenced by main().