GDAL-RASTER-NEIGHBORS(1)

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

okay so bestie, welcome to GDAL-RASTER-NEIGHBORS(1) — yes that's the whole manual name, and yes it's a mouthful, but we're gonna get through it together and you're gonna be so good at focal statistics by the end. buckle up. 💖

🦋 NAME 🦋

gdal-raster-neighbors — compute the value of each pixel from its neighbors (focal statistics). it's giving "every pixel is judged by the company it keeps". ✨

Added in version 3.12.

🌸 SYNOPSIS 🌸

Usage: gdal raster neighbors [OPTIONS] <INPUT> <OUTPUT>

Compute the value of each pixel from its neighbors (focal statistics)

Positional arguments:
  -i, --input <INPUT>                                      Input raster datasets [required] [not available in pipelines]
  -o, --output <OUTPUT>                                    Output raster dataset [required] [not available in pipelines]

Common Options:
  -h, --help                                               Display help message and exit
  --json-usage                                             Display usage as JSON document and exit
  --config <KEY>=<VALUE>                                   Configuration option [may be repeated]
  -q, --quiet                                              Quiet mode (no progress bar or warning message) [not available in pipelines]

Options:
  -f, --of, --format, --output-format <OUTPUT-FORMAT>      Output format ("GDALG" allowed) [not available in pipelines]
  --co, --creation-option <KEY>=<VALUE>                    Creation option [may be repeated] [not available in pipelines]
  --overwrite                                              Whether overwriting existing output dataset is allowed [not available in pipelines]
                                                           Mutually exclusive with --append
  --append                                                 Append as a subdataset to existing output [not available in pipelines]
                                                           Mutually exclusive with --overwrite
  -b, --band <BAND>                                        Input band (1-based index)
  --method <METHOD>                                        Method to combine weighed source pixels. METHOD=mean|sum|min|max|stddev|median|mode [may be repeated]
  --size <SIZE>                                            Neighborhood size
  --kernel <KERNEL>                                        Convolution kernel(s) to apply [1.. values] [required]
  --ot, --datatype, --output-data-type <OUTPUT-DATA-TYPE>  Output data type. OUTPUT-DATA-TYPE=UInt8|Int8|UInt16|Int16|UInt32|Int32|UInt64|Int64|CInt16|CInt32|Float16|Float32|Float64|CFloat32|CFloat64 (default: Float64)
  --nodata <NODATA>                                        Assign a specified nodata value to output bands ('none', numeric value, 'nan', 'inf', '-inf')

Advanced Options:
  --if, --input-format <INPUT-FORMAT>                      Input formats [may be repeated] [not available in pipelines]
  --oo, --open-option <KEY>=<VALUE>                        Open options [may be repeated] [not available in pipelines]

okay real talk, <INPUT> and <OUTPUT> are both required and neither one works inside pipelines. noted. 📝

💅 DESCRIPTION 💅

gdal raster neighbors takes a kernel (that's a convolution matrix, bestie) plus a method, and uses them to compute the target pixel value from the neighborhood of the source pixel. it's a glow-up for your raster, pixel by pixel. 🔥

here's the edge situation, and it's lowkey important: at the top edge, the values of the first row get replicated to virtually extend the source window by a number of rows equal to the radius of the kernel. same energy at the bottom, left and right edges. and the docs are very upfront about this — this strategy may potentially lead to unexpected results depending on the applied kernel. so like. be aware. 🙈

now, per target cell: if the corresponding source value (the one sitting at the center of the kernel) is nodata, then the resulting pixel is nodata. periodt. for the other source values in the neighborhood defined by the kernel, source nodata values are just ignored. they're not the main character. 💀

this algorithm can be part of a gdal pipeline or gdal raster pipeline. slay.

[image] Raster dataset before (left) and after (right) summation with a 3x3 equal-weight kernel. NoData values are considered zero for the purpose of the summation. Edge cells are replicated where the kernel window extends beyond the edge of the dataset.

✨ GDALG OUTPUT (ON-THE-FLY / STREAMED DATASET) ✨

this program supports serializing the command line as a JSON file using the GDALG output format. the resulting file can then be opened as a raster dataset using the GDALG: GDAL Streamed Algorithm driver, and it'll apply the specified pipeline in a on-the-fly / streamed way. no cap, it just does it. 🦋

🎀 PROGRAM-SPECIFIC OPTIONS 🎀

  • --band <BAND> — source band number, and indexing starts at one (one-based, bestie, not zero). if you don't specify it, all input bands are used. 🌈
  • --kernel — the convolution kernel to apply to source pixels in a neighborhood of each pixel. two ways to give it to me:
    • either the name of a well-known kernel, among edge1, edge2, sharpen, gaussian, or unsharp-masking — those correspond to those kernels (convolution matrix) — plus these extras:
      • equal, which corresponds to a kernel with all coefficients at one (kernel size can be any odd number between 3 and 99):
\begin{align}
\begin{bmatrix} 1 & 1 & 1\\ 1 & 1 & 1 \\ 1 & 1 & 1 \end{bmatrix} \end{align}

for method mean, this corresponds to a box blur filter. iconic. ✨

  • u, corresponding to an horizontal derivative with coefficients:
\begin{align}
\begin{bmatrix} 0 & 0 & 0\\ -0.5 & 0 & 0.5 \\ 0 & 0 & 0 \end{bmatrix} \end{align}
  • v, corresponding to a vertical derivative with coefficients:
\begin{align}
\begin{bmatrix} 0 & -0.5 & 0\\ 0 & 0 & 0 \\ 0 & 0.5 & 0 \end{bmatrix} \end{align}

heads up tho: edge1, edge2, sharpen, u and v are only supported for a kernel size equal to 3.

gaussian is supported for a kernel size equal to 3 or 5.

unsharp-masking is supported for a kernel size equal to 5.

  • or the values of the coefficients of the kernel as a square matrix of width and height N, where N is an odd number, given as:
[[val00, val01, ..., val0N],[val10, val11, ..., val1N],...,[valN0, valN1, ..., valNN]]

if --method is set to mean, this has the effect of adding the sum of the (contributing, i.e. non nodata) weighted source pixels and dividing it by the sum of the coefficients in the kernel. math girlie behavior. 🧮

if --kernel is specified several times, there will be one output band for each combination of kernel and input band. yes, really. 🔥

  • --method sum|mean|min|max|stddev|median|mode — the function to apply to the weighted source pixels in the neighborhood defined by the kernel. it defaults to mean, except when --kernel is set to u, v, edge1, edge2, or a user defined kernel whose sum of coefficients is zero — in that case sum is used. plot twist. 💫
    • sum: computes the sum of the value of contributing source pixels multiplied by the corresponding weight of the kernel. this corresponds to a kernel with un-normalized sum of coefficients.
    • mean: computes the average of the value of contributing source pixels multiplied by the corresponding weight of the kernel. this has the effect of normalizing kernel coefficients so their sum is one.
    • min: computes the minimum of the value of contributing source pixels multiplied by the corresponding weight of the kernel.
    • max: computes the maximum of the value of contributing source pixels multiplied by the corresponding weight of the kernel.
    • stddev: computes the standard deviation of the value of contributing source pixels multiplied by the corresponding weight of the kernel.
    • median: computes the median of the value of contributing source pixels multiplied by the corresponding weight of the kernel.
    • mode (majority): computes the most frequent of the value of contributing source pixels multiplied by the corresponding weight of the kernel. majority rules, as always. 👑
  • --nodata — sets the NoData value for the output dataset. you can set it to none to leave the NoData value undefined. and if you don't pass --nodata at all, gdal raster neighbors will use a NoData value from the first source dataset to have one. so generous of it. 🫶
  • --size <SIZE> — size of the kernel. odd number between 3 and 99.
NOTE: computation time is proportional to the square of the kernel size. so like, a 99 kernel is not a casual decision. it's a lifestyle. 💀

for kernels edge1, edge2, sharpen, u, v, gaussian, equal, it defaults to 3.

for kernel unsharp-masking, it defaults to 5.

for kernels specified through their coefficient values, it is deduced from the shape of the matrix. it just knows. ✨

okay that's the first part bestie, we're not done yet — keep reading, there's more coming 💖

✨ STANDARD OPTIONS ✨

bestie these are the options every gdal raster subcommand gets, so they're not even neighbors-specific, they're just... the house rules 💅

  • --append — adds your input raster as a brand new subdataset inside an output file that already exists. Only works with drivers that actually support adding subdatasets, like GTiff — GeoTIFF File Format, and GPKG — GeoPackage raster. Bonus: if the output dataset doesn't exist yet, this just... makes it. no cap 🫶
  • --co, --creation-option <NAME>=<VALUE> — lots of formats have optional creation options that let you control the little particulars of the file being created. for example, the GeoTIFF driver has creation options to control compression, and whether the file should be tiled 👑

May be repeated. (say it with me: repeatable ✨)

Which creation options exist varies by format driver, and ngl some simple formats have no creation options at all. you can list the options a format supports with the --formats command line option, but the documentation for the format is the definitive source of information on driver creation options. see Raster drivers format specific documentation for the legal creation options for each format.

  • --if, --input-format <format> — the format/driver name you want the program to attempt to open the input file(s) with. usually you don't need to specify this at all, but it's here for when automatic driver detection fails to pick the right driver and you just want to skip it. this option can be repeated several times to specify several candidate drivers. note that it does not force those drivers to open the dataset — in particular, some drivers have requirements on file extensions. 💀

May be repeated.

  • --oo, --open-option <NAME>=<VALUE> — dataset open option (format specific). yes it's giving very mysterious, that's the point 🎀

May be repeated.

  • -f, --of, --format, --output-format <OUTPUT-FORMAT> — which output raster format to use. if you need the allowed values, they may be given by:
gdal --formats | grep raster | grep rw | sort
  • --ot, --datatype, --output-data-type <OUTPUT-DATA-TYPE> — the output data type, picked from: Byte, Int8, UInt16, Int16, UInt32, Int32, UInt64, Int64, CInt16, CInt32, Float32, Float64, CFloat32, CFloat64. pick your fighter 🌈
  • --overwrite — lets the program overwrite an existing target file or dataset. otherwise, by default, gdal errors out if the target file or dataset already exists. so like, it's giving permission slip energy 🙈

💖 RETURN STATUS CODE 💖

the program returns status code 0 if everything slayed, and non-zero if something went wrong. and yes, non-blocking errors that get emitted as warnings still count as a successful execution — so a lil warning does not tank your exit code, periodt ✨

🦋 EXAMPLES 🦋

Example 1: Compute the horizontal and vertical derivative of a single-band raster

gdal raster neighbors --kernel u --kernel v in.tif uv.tif

Example 2: Compute the average value around each pixel in a 3x3 neighborhood

gdal raster neighbors --kernel equal --method mean in.tif mean.tif

Example 3: Compute the maximum value around each pixel in a 5x5 neighborhood

gdal raster neighbors --kernel equal --size 5 --method max in.tif max.tif

Example 4: Compute a sharpen filter of a single-band raster, by manually specifying the kernel coefficients

gdal raster neighbors "--kernel=[[0,-1,0],[-1,5,-1],[0,-1,0]]" in.tif sharpen.tif

like... look at that last one writing out the whole kernel matrix by hand. main character energy fr fr 👑

🌸 AUTHOR 🌸

Even Rouault <even.rouault@spatialys.com>

1998-2026

okay bestie that's the whole page, no crumbs left 🍓 this was GDAL-RASTER-NEIGHBORS(1), source version GDAL, dated Aug 18, 2026 — go forth and filter your pixels, you absolute icon 💅✨

📦 where this page comes from