GeoTIFF to wavetable converter

This is a utility to convert GeoTIFF files to wavetable files (.wt) for use in synthesizers.

Despite the name, GeoTIFFs aren't the only way in: photos and scans (JPEG, PNG, WebP, and more) work too. Scan a poster, a wall, or a texture and play it. See Images and scans.

I've never worked with GeoTIFF and my wavetable experience is limited. Huge shout-out to both okwt and surge for their helpful implementations.

If you'd like to help or if you've noticed some issues, please see the CONTRIBUTING guide for information about how to go forward.

Usage

For these examples, we'll use the GeoTIFF of the lower Colorado River that ships in examples/. For more geospatial data, check out the sources below.

The tool automatically:

• Replaces nodata values (like -999999) with the mean elevation
• Resizes your terrain to valid dimensions (width: power of 2 between 2–4096, height: max 512)
• Normalizes elevation values to audio range (-32768 to 32767 for int16 format)

Basic conversion

Convert a GeoTIFF file to a wavetable:

geotiff-to-wavetable examples/USGS_OPR_AZ_2021LowerColoradoTB_C23_LCR_000002.tif

This creates examples/USGS_OPR_AZ_2021LowerColoradoTB_C23_LCR_000002.wt (in the same directory as your input file). The tool will automatically handle nodata values (like oceans or missing data) and resize your terrain to valid wavetable dimensions.

Options

Usage info:

geotiff-to-wavetable -h

Specify an output file:

geotiff-to-wavetable examples/USGS_OPR_AZ_2021LowerColoradoTB_C23_LCR_000002.tif -o output.wt

Select a specific band (if your GeoTIFF has multiple bands):

geotiff-to-wavetable examples/USGS_OPR_AZ_2021LowerColoradoTB_C23_LCR_000002.tif -b 2

Most elevation data only has one band, so you won't need this option. Use -i to see how many bands your file has.

Read columns instead of rows:

geotiff-to-wavetable examples/USGS_OPR_AZ_2021LowerColoradoTB_C23_LCR_000002.tif -c

By default, each row of the raster (top to bottom) becomes one wave frame. With -c/--columns, each column (left to right) does instead. It's the same data turned 90 degrees, and it makes a different instrument.

Set the wave size (samples per frame):

geotiff-to-wavetable examples/USGS_OPR_AZ_2021LowerColoradoTB_C23_LCR_000002.tif -w 256

-w/--wave-size takes a power of 2 from 2 to 4096. By default it's the raster's width rounded up to a power of 2, capped at 4096. The number of frames still follows the raster's height, capped at 512. How to choose:

• Sound: fewer samples per frame means less detail in each waveform, which sounds crunchier and more lo-fi. At 8 or 16 samples the terrain is reduced to a handful of steps, and it sounds like it. Large sizes keep the fine texture of the land (or the scan).
• File size: the file is 2 bytes × wave size × frame count, so it scales directly with -w. A full 4096 × 512 table is about 4 MB, and -w 256 on the same raster is about 256 KB.
• Synthesizer support: Surge reads anything from 2 to 4096. Some synthesizers resample every table to a fixed internal size (often 2048), so on those, very large sizes add file weight without adding detail.

View file information (bands and their colors, width, height):

geotiff-to-wavetable examples/USGS_OPR_AZ_2021LowerColoradoTB_C23_LCR_000002.tif -i

Visualize the data before converting:

View the default band:

geotiff-to-wavetable examples/USGS_OPR_AZ_2021LowerColoradoTB_C23_LCR_000002.tif -v

View a specific band:

geotiff-to-wavetable examples/USGS_OPR_AZ_2021LowerColoradoTB_C23_LCR_000002.tif -b 2 -v

This opens a plot showing your elevation data. It's a helpful first step to make sure Python can read your file and that it contains the terrain you expect. If it doesn't look right, make sure to check how many bands there are (-i) and then view the other bands.

Images and scans

Anything GDAL can read works as input: JPEG, PNG, WebP, BMP, GIF, and TIFF, georeferenced or not. A portable scanner and a city full of posters is a sample library.

geotiff-to-wavetable poster.jpg

How images are read:

• Brightness by default. Color images convert by their luma, the perceived brightness (Rec. 709: 0.2126 red + 0.7152 green + 0.0722 blue). Dark ink on light paper reads the way your eye sees it. Transparency (alpha) is ignored.
• One color channel with -b. On a color image, -b 1, -b 2, and -b 3 pick red, green, and blue alone. The same poster can sound quite different through each one. -i lists which band is which color.
• Indexed images (most GIFs and some PNGs) are converted through their color table, so they convert by their actual colors.
• Blank images are refused. A scan with no variation at all, such as a white wall, would make a silent wavetable, so the tool exits with an error instead.

Scanning tips:

• Resolution: the output is at most 4096 samples wide and 512 frames tall, so 300 dpi is plenty for anything poster-sized.
• Bit depth: photos are usually 8-bit, which gives 256 brightness levels. That sounds a little stepped and gritty, which may be exactly what you want. For smoother tables, have the scanner save 16-bit TIFF.
• Formats the tool can't read: iPhone HEIC photos and PDFs from scanner apps need converting first, e.g. magick scan.heic scan.png (ImageMagick).

Importing into Bitwig

Bitwig expects files to be in ~/Documents/Bitwig Studio/Library, so copy your file into that directory and then you can source it from Bitwig's wavetable.

To validate that the file is available in Bitwig, copy the file to the Bitwig Library:

cp /path/to/your/file.wt ~/Documents/Bitwig\ Studio/Library

Then, in Bitwig:

• Create a new Instrument and add Polymer to it.
• Change your Oscillator to "Wavetable" and click on the wavetable.
• This will bring up the Wavetables selector. On the left, click "My Library" and you should see your wavetable there.

You can also drag your wavetable file into the wavetable part of the oscillator.

Finding geospatial data

Here are some sources for dense GeoTIFF data:

1. USGS Elevation
   • Filter by: GeoTIFF, Elevation Products (DEM)
   • Choose interesting terrain: mountains, canyons, volcanoes
   • 1-arc-second resolution is good
2. OpenTopography
   • High-resolution LiDAR elevation data
   • Great for detailed terrain
   • Requires free account
3. SRTM (Shuttle Radar Topography Mission)
   • Global elevation data, 30m resolution
   • Has an easy browser
   • Download tiles covering interesting places
4. NASA ASTER GDEM
   • Global elevation
   • Higher resolution than SRTM

💡 Pro tips

• Avoid: Ocean/water data, cloud/atmospheric data, sparse measurements
• Look for: Elevation (DEM), bathymetry, land surface temperature
• Interesting terrain: Iceland volcanoes, Grand Canyon, Himalayas, Hawaiian islands

An example of getting a GeoTIFF from USGS

1. Go to their site
2. Zoom in on an area or search (upper right of the map). I have found that larger areas work better for finding results and then you can scroll through until you see something interesting.
3. On the left, you should be in the Datasets tab. Select "Elevation Source Data (3DEP) - Lidar, IfSAR". Within that, you can select File Formats "TIFF" (I want to add LiDAR support in a future update)
4. You might need to scroll up. Click the "🔍 Search Products" button. This will bring you to the Products tab.
5. You can now scroll through the available images. If nothing returns, try increasing your area. For example, I couldn't find anything for Kauai. I zoomed out and couldn't find anything for the Hawaiian Islands. So I zoomed out and got stuff for the Aleutian Islands (copyright is commercial for Alaska which is why we're using Arizona for our examples/).
6. Find something that looks interesting and click the "Download Link (TIF)" link (it might be "Download Link (ZIP)" and then you'll need to unzip and might have multiple TIFs to play around with).