NAME

       nearblack - Convert nearly black/white borders to black.

SYNOPSIS

          nearblack [--help] [--help-general]
                    [-of <format>] [-white | [-color <c1>,<c2>,<c3>...<cn>]...]
                    [-near <dist>] [-nb <non_black_pixels>]
                    [-setalpha] [-setmask] [-alg twopasses|floodfill]
                    [-o <outfile>] [-q] [-co <NAME>=<VALUE>]... <infile>

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 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.

       -o <outfile>
              The name of the output file to be created.

       -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
              New 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.

C API

       This utility is also callable from C with GDALNearblack().

       New in version 2.1.

AUTHOR

       Frank Warmerdam <warmerdam@pobox.com>

COPYRIGHT

       1998-2025

                                                  Apr 01, 2025                                      NEARBLACK(1)