GDAL Export Format

The GDAL exporter creates text files compatible with GDAL’s gdaldem color-relief command.

Format Details

Property	Value
Identifier	gdal
Extension	.txt
Use case	GDAL raster coloring

Output Format

The output is a text file with one color entry per line. By default, the output includes a nodata (nv) line but no comments:

nv 0 0 0 0
0.0 68 1 84 255
1.0 68 2 85 255
2.0 68 3 87 255
...
255.0 253 231 37 255

When using verbose mode (-v), comments are included:

# GDAL Color Relief File generated by Palettize
# Colormap name: viridis
# Domain: [0, 255], Scaler: linear
# Interpolation Space for Colormap: oklch
nv 0 0 0 0
0.0 68 1 84 255
...

Each line has the format: value R G B A

CLI Usage

# Basic export (includes nv line by default)
palettize create viridis --format gdal --output viridis.txt --domain 0,255

# With verbose comments
palettize create viridis -f gdal -o viridis.txt --domain 0,255 -v

# Custom number of colors
palettize create viridis -f gdal -o viridis.txt --domain 0,255 --steps 256

# Without nodata line
palettize create viridis -f gdal -o viridis.txt --domain 0,255 -O nodata=false

# Custom nodata value
palettize create viridis -f gdal -o viridis.txt --domain 0,255 \
  -O nodata_value=-9999 -O "nodata_color=0,0,0,0"

Python Usage

from palettize import create_colormap, get_scaler_by_name, get_exporter

cmap = create_colormap(preset="viridis")
scaler = get_scaler_by_name("linear", domain_min=0, domain_max=255)
exporter = get_exporter("gdal")

output = exporter.export(
    colormap=cmap,
    scaler=scaler,
    domain_min=0,
    domain_max=255,
    options={"num_colors": 256}
)

# Save to file
with open("viridis.txt", "w") as f:
    f.write(output)

Options

Option	Type	Default	Description
num_colors	int	256	Number of color steps to generate
nodata	bool	true	Include nv 0 0 0 0 line by default
nodata_value	float | str	"nv"	NoData value. Use "nv" for GDAL keyword or a numeric value
nodata_color	tuple[int,int,int,int]	(0,0,0,0)	RGBA color for NoData
verbose	bool	false	Include comment header lines (set automatically by -v flag)

Using with GDAL

Once exported, use with gdaldem:

# Generate color-relief image
gdaldem color-relief input.tif viridis.txt output_colored.tif

# With other options
gdaldem color-relief input.tif viridis.txt output.tif \
  -of GTiff -co COMPRESS=LZW

NoData Handling

By default, the GDAL exporter includes an nv 0 0 0 0 line for transparent nodata handling. GDAL’s nv keyword applies to any nodata value defined in the raster.

# Default behavior includes nv line
palettize create viridis -f gdal -o viridis.txt --domain 0,255

# Disable nodata line
palettize create viridis -f gdal -o viridis.txt --domain 0,255 -O nodata=false

# Specify a numeric NoData value instead of nv
palettize create viridis -f gdal -o viridis.txt --domain 0,255 \
  -O nodata_value=-9999 -O "nodata_color=0,0,0,0"

The NoData line appears before the color entries:

nv 0 0 0 0
0.0 68 1 84 255
...