GDAL-RASTER-RGB-TO-PALETTE(1)

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

✨ GDAL-RASTER-RGB-TO-PALETTE ✨

okay bestie come CLOSE, because this one is genuinely so fun 💅 it's gdal-raster-rgb-to-palette, from the GDAL manual pages, and it does exactly what it says on the tin: takes your full-color RGB image and turns it into a cute little pseudo-color / paletted image, like a pixel-art glow-up. 🌈

🆕 added in version 3.12 — she's new-ish, she's fresh, she's got range.

📜 SYNOPSIS

Usage: gdal raster rgb-to-palette [OPTIONS] <INPUT> <OUTPUT>

Convert a RGB image into a pseudo-color / paletted image.

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
  --color-count <COLOR-COUNT>                          Select the number of colors in the generated color table (default: 256)
  --color-map <COLOR-MAP>                              Color map filename
  --output-nodata <OUTPUT-NODATA>                      Output nodata value
  --no-dither                                          Disable Floyd-Steinberg dithering
  --bit-depth <BIT-DEPTH>                              Bit depth of color palette component (8 bit causes longer computation time). BIT-DEPTH=5|8 (default: 5)

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]

💖 DESCRIPTION

so basically, gdal raster rgb-to-palette is out here computing an optimal pseudo-color table for your RGB image 🎨 and the way it does it?? median cut algorithm, running on a downsampled RGB histogram. iconic. that is, unless you hand it a color table yourself with --color-map, in which case she just uses yours, no notes. 🫶

then — and this is the part that eats — it converts the image into a pseudo-colored image using that color table.

and it's not even doing the basic thing, because this conversion by default uses Floyd-Steinberg dithering (that's error diffusion, bestie, not a vibe) to max out the output image's visual quality. ✨🍓

also: this subcommand is available as a potential step of gdal raster pipeline too, so you can slot it into your whole little assembly line. 🧚

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

okay so this program supports serializing the command line as a JSON file using the GDALG output format. that 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 an on-the-fly / streamed way. main character energy, honestly. 👑

⚠️ NOTE: however, bestie... this algorithm is not natively streaming compatible. consequently a temporary dataset will be generated, which may cause significant processing time at opening. so like, she's streamed adjacent. 😭 not her fault, just how it is.

🎀 PROGRAM-SPECIFIC OPTIONS

  • --color-count <COLOR-COUNT> — pick how many colors go in the generated color table. defaults to 256. and it must be between 2 and 256, no exceptions, periodt. 💅
  • --color-map <FILENAME> — instead of computing a color table, just yoink it from <FILENAME>. super useful if you want a consistent color table for multiple files (matching sets, we love to see it). the <FILENAME> has to be either a raster file in a GDAL supported format that has a palette, or a color file in a supported format (.txt, QGIS .qml, QGIS .qlr). 🎨
  • --output-nodata <VALUE> — 🆕 added in version 3.13. this specifies the output nodata value, which gets used for input pixels that are at the source nodata value, or that are transparent because of a mask band — like an alpha band. the destination nodata value must be between 0 and 255. and here's the little autopilot: if there's a source nodata value, or a dataset-wide mask band attached to the source bands, and you did not specify --output-nodata, it defaults to 0. 🙈
  • --no-dither — 🆕 added in version 3.13. this disables Floyd-Steinberg dithering (error diffusion). lowkey useful when you want to improve the compression rate by avoiding the "noise" that error diffusion adds. sometimes less shimmer = more slay. 🔥
  • --bit-depth 5|8 — 🆕 added in version 3.13. this is the bit depth of each of the output color table's R, G, B components. the default value is 5, which means each component is limited to 32 = 2 ^ 5 values. setting bit depth to 8 increases the fidelity of the output color table — at the expense of longer computation time. beauty is pain, bestie. 💀

⭐ STANDARD OPTIONS

  • --co, --creation-option <NAME>=<VALUE> — lots of formats have one or more optional creation options you can use to control particulars about the file being created. for instance, the GeoTIFF driver supports creation options to control compression, and whether the file should be tiled. 🖼️

may be repeated.

the creation options available vary by format driver, and 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 info on driver creation options. see Raster drivers format specific documentation for legal creation options for each format.

  • -f, --of, --format, --output-format <OUTPUT-FORMAT> — which output raster format to use. allowed values may be given by gdal --formats | grep raster | grep rw | sort 🔍
  • --overwrite — allow the program to overwrite an existing target file or dataset. otherwise, by default, gdal errors out if the target file or dataset already exists. so be nice and ask first. 🫶

💀 RETURN STATUS CODE

the program returns status code 0 in case of success, and non-zero in case of error. and just to be clear: non-blocking errors that get emitted as warnings are considered a successful execution. so a lil warning doesn't mean she failed, okay?? she's fine. she's thriving. 💜

🌸 EXAMPLES

Example 1

convert a TIFF file into a paletted PNG image 🎀

$ gdal raster rgb-to-palette input.tif output.png

👑 AUTHOR

Even Rouault <even.rouault@spatialys.com>

1998-2026

and that's the whole page bestie, no cap — written by Even Rouault, copyright 1998-2026, from the GDAL manual, version stamped Aug 18, 2026. go forth and palette-ify something gorgeous. 🦋✨💅

📦 where this page comes from