NEARBLACK(1)

📦
version 3.13.3 · 11 versions
, in alpine 3.24, arch rolling, ubuntu stonking

💅 nearblack — bestie edition

okay so this is nearblack, manual page 1, from the GDAL fam. it lives in section 1, it's a command-line tool, and honestly? it's giving glow-up-for-your-air-photos energy. let's GO 🫶

✨ NAME ✨

nearblack — take all those crusty nearly-black / nearly-white borders and turn them into actually black (or white, we're flexible 💅).

🌸 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 💖

so the vibe is: this utility scans an image and tries to set every pixel that's nearly or exactly black, white, or one or more custom colors around the collar to black or white. no cap. the classic use case is "fixing up" lossy-compressed air photos so those color pixels can be treated as transparent when you're mosaicing. iconic behavior tbh.

🚨 real talk: the output format must use lossless compression if either the alpha band or the mask band is not set. that's not optional, bestie.
💡 TIP: there's an equivalent in the new gdal command line interface — go look at gdal raster clean-collar.

okay now the options, one by one, no skipping, we're thorough here 💅

  • --help — prints this help message and dips out.
  • --help-general — gives you a quick lil usage rundown of the generic GDAL commandline options, then exits.
  • -q, --quiet — mutes progress messages and any other non-error chatter. silent mode, main character mystery energy 🤫
  • -o <outfile> — the name of the output file that's gonna get created.
  • -of <format> — picks the output format. if you don't say anything, it gets guessed from the file extension. use the short format name — like GTiff for GeoTIFF, iykyk.
  • -co <NAME>=<VALUE> — passes a creation option through to the output format driver. you can stack multiple -co options. check the Raster drivers' format-specific docs for what creation options each format actually allows.
    • heads up: this is only valid when creating a new file.
  • -white — hunts for nearly-white (255) pixels instead of nearly-black ones. plot twist ✨
  • -color <c1>,<c2>,<c3>...<cn> — hunts for pixels near the color you specify. you can throw this flag multiple times. and listen: when -color is specified, the pixels considered as the collar get set to 0. 📌
  • -near <dist> — controls how far away from black, white, or your custom colors a pixel's values can be and still count as "near" black/white/custom. defaults to 15.
  • -nb <non_black_pixels> — how many consecutive non-black pixels you can hit before it gives up searching 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 that's 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 was specified. that alpha band goes to 0 in the image collar and 255 everywhere else. 🎀
  • -setmask — adds a mask band to the output file; or adds a mask band to the input file if it doesn't already have one and no output file is specified. mask band = 0 in the image collar, 255 elsewhere. same deal, different band 💜
  • -alg twopasses|floodfill — added in version 3.8.
    • picks which algorithm gets applied.
    • twopasses does a top-to-bottom pass, then a bottom-to-top pass. this was 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" happens 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/custom pixels get set to black or white. it also scans top-to-bottom and bottom-to-top to spot indentations in the top or bottom.
    • floodfill (added in GDAL 3.8) uses the Flood Fill algorithm and will work with concave areas. it needs to create a temporary dataset though, so it's slower than twopasses. note: when a non-zero value for -nb is used, twopasses actually gets called as an initial step of floodfill.
  • <infile> — the input file. any GDAL supported format, any number of bands, normally 8bit Byte bands.

and just so we're clear: the processing is all done in 8bit (Bytes). that's the whole point.

oh and — if the output file is omitted, the processed results get written back to the input file, which means that file must support update. be normal about that, okay? 🙈

🔥 RETURN STATUS CODE 🔥

the program returns status code 0 on success, and non-zero on error. and note: non-blocking errors emitted as warnings are considered a successful execution, so don't panic 💀

🧚 C API 🧚

you can also call this utility straight from C with GDALNearblack(). cute, right?

👑 AUTHOR 👑

Frank Warmerdam <warmerdam@pobox.com>

1998-2026

and that's the whole page, bestie 🦋 — this was GDAL's nearblack(1), dated Aug 18, 2026. go fix up those collars. slay. periodt. 💅✨

📦 where this page comes from