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.

Hardware samplers (M8, MPC, OP-1, etc.)

Hardware samplers like the Dirtywave M8, Akai MPC, Teenage Engineering OP-1, and Polyend Tracker can't read .wt files, but they all play WAVs. Ask for one with -f wav:

geotiff-to-wavetable examples/USGS_OPR_AZ_2021LowerColoradoTB_C23_LCR_000002.tif -f wav

Use -f wt,wav to get both from one run.

The WAV is mono, 16-bit, 44.1 kHz, with every wave frame laid end to end. It holds sample-for-sample the same data as the .wt. A wavetable synthesizer lets you choose which frame to play; a sampler plays straight through the WAV, so you hear the terrain (or the poster) evolving over time. Loop it and it keeps cycling.

• Dirtywave M8: load it into a Sampler instrument and set PLAY to FWDLOOP, or to REPITCH/BPM to lock it to the song.
• Other samplers: use a forward-looping playback mode. The file has no loop points in it; the sampler's own loop settings handle that.

Pitch and length: at 44.1 kHz, each frame of N samples repeats 44100 ÷ N times a second, which sets the pitch you hear: 2048 samples gives about 21.5 Hz (a low rumble), 256 about 172 Hz, 128 about 345 Hz. So -w doubles as a tuning control. The file lasts N × frames ÷ 44100 seconds: about 48 seconds at 4096 × 512, 3 seconds at 256 × 512. A sampler treats the whole file as one chromatic sample, so playing it higher speeds up the scan as well as raising the pitch.

Finding geospatial data

Where to get elevation data, in the order to try them:

1. Start here: SRTM 30m tile browser. It's the fastest route to anywhere on Earth: click a 1° tile on a world map and download it. It covers nearly all land between 60° N and 56° S at 30 m resolution, including places the USGS downloader comes up empty for (Kauai and the rest of Hawaii download cleanly here). You need a free NASA Earthdata login to download. SRTM tiles are int16 with a -32768 nodata value, which the tool handles.
2. Backup: NASA ASTER GDEM. Also global and also 30 m, with wider coverage toward the poles (83° N to 83° S). Worth trying when SRTM has gaps, such as far-northern terrain or steep mountains.
3. Deepest catalog: OpenTopography. High-resolution LiDAR, bathymetry, and more, for when 30 m isn't detailed enough. Requires a free account.
4. United States, no account: USGS National Map downloader. Filter by elevation products (DEM) in GeoTIFF format. 1-arc-second data is a good size. See the walkthrough below.

💡 Pro tips

• Avoid: ocean/water data, cloud/atmospheric data, sparse measurements
• Look for: elevation (DEM), bathymetry, land surface temperature
• Interesting terrain: Iceland's volcanoes, the Grand Canyon, the Himalayas, the Hawaiian islands (via SRTM)

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).