FreeBSD Manual Pages
NEARBLACK(1) GDAL NEARBLACK(1) NAME nearblack - Convert nearly black/white borders to black. SYNOPSIS 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> DESCRIPTION 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 out- put format must use lossless compression if either alpha band or mask band is not set. TIP: Equivalent in new "gdal" command line interface: See gdal raster clean-collar. --help Show this help message and exit --help-general Gives a brief usage message for the generic GDAL commandline options and exit. -q, --quiet Suppress progress messages and other non-error output. -o <outfile> The name of the output file to be created. -of <format> Select the output format. If not specified, the format is guessed from the extension. 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 documenta- tion 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 multi- ple 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. De- faults to 15. -nb <non_black_pixels> number of consecutive non-black pixels that can be encountered be- fore 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 in- put file if it does not already have one and no output file is spec- ified. 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 cus- tom 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. <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. RETURN STATUS CODE The program returns status code 0 in case of success, and non-zero in case of error (non-blocking errors emitted as warnings are considered as a suc- cessful execution). C API This utility is also callable from C with GDALNearblack(). AUTHOR Frank Warmerdam <warmerdam@pobox.com> COPYRIGHT 1998-2026 Jun 05, 2026 NEARBLACK(1)
NAME | SYNOPSIS | DESCRIPTION | RETURN STATUS CODE | C API | AUTHOR | COPYRIGHT
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=nearblack&sektion=1&manpath=FreeBSD+Ports+15.1.quarterly>