nearblack - Convert nearly black/white borders to black.
Usage: nearblack [--help] [--long-usage] [--help-general]
[-of <output_format>] [--quiet] [-co <NAME>=<VALUE>]...
[-o <output_file>]
[[-white]|[-color <c1,c2,c3...cn>]...]
[-nb <non_black_pixels>] [-near <dist>] [-setalpha] [-setmask]
[-alg floodfill|twopasses]
<input_file>
This utility will scan an image and try to set all pixels that are
nearly or exactly black, white or one or more custom colors around the
collar to black or white. This is often used to "fix up" lossy
compressed air photos so that color pixels can be treated as transparent
when mosaicing. The output format must use lossless compression if either
alpha band or mask band is not set.
- --help
- Show this help message and exit
- --help-general
- Gives a brief usage message for the generic GDAL commandline options and
exit.
- -of <format>
- Select the output format. Starting with GDAL 2.3, if not specified, the
format is guessed from the extension (previously was ERDAS Imagine .img).
Use the short format name (GTiff for GeoTIFF for example).
- -co
<NAME>=<VALUE>
- Passes a creation option to the output format driver. Multiple -co
options may be listed. See Raster drivers format specific
documentation for legal creation options for each format.
Only valid when creating a new file
- -white
- Search for nearly white (255) pixels instead of nearly black pixels.
- -color
<c1>,<c2>,<c3>...<cn>
- Search for pixels near the specified color. May be specified multiple
times. When -color is specified, the pixels that are considered as the
collar are set to 0.
- -near
<dist>
- Select how far from black, white or custom colors the pixel values can be
and still considered near black, white or custom color. Defaults to
15.
- -nb
<non_black_pixels>
- number of consecutive non-black pixels that can be encountered before the
giving up search inwards. Defaults to 2.
- -setalpha
- Adds an alpha band if the output file is specified and the input file has
3 bands, or sets the alpha band of the output file if it is specified and
the input file has 4 bands, or sets the alpha band of the input file if it
has 4 bands and no output file is specified. The alpha band is set to 0 in
the image collar and to 255 elsewhere.
- -setmask
- Adds a mask band to the output file, or adds a mask band to the input file
if it does not already have one and no output file is specified. The mask
band is set to 0 in the image collar and to 255 elsewhere.
- -alg
twopasses|floodfill
- Added in version 3.8.
Selects the algorithm to apply.
twopasses uses a top-to-bottom pass followed by a
bottom-to-top pass. This is the only algorithm implemented before GDAL
3.8. It may miss with concave areas. The algorithm processes the image
one scanline at a time. A scan "in" is done from either end
setting pixels to black or white until at least
"non_black_pixels" pixels that are more than "dist"
gray levels away from black, white or custom colors have been
encountered at which point the scan stops. The nearly black, white or
custom color pixels are set to black or white. The algorithm also scans
from top to bottom and from bottom to top to identify indentations in
the top or bottom.
floodfill (added in GDAL 3.8) uses the Flood
Fill algorithm and will work with concave areas. It requires
creating a temporary dataset and is slower than twopasses. When a
non-zero value for -nb is used, twopasses is actually
called as an initial step of floodfill.
- -q
- Suppress progress monitor and other non-error output.
- <infile>
- The input file. Any GDAL supported format, any number of bands, normally
8bit Byte bands.
The processing is all done in 8bit (Bytes).
If the output file is omitted, the processed results will be
written back to the input file - which must support update.
This utility is also callable from C with
GDALNearblack().
Added in version 2.1.
Frank Warmerdam <warmerdam@pobox.com>