# Topo Lines

Aperveil / Light, shaped for the web.

A procedural topographic contour background for React. Tune terrain ridges, contour intervals and local pointer relief, then export the WGSL.

[Aperveil integration guide](https://www.aperveil.com/docs)

## What it does

Topo Lines builds warped, ridged terrain and draws minor contours with stronger index lines. Hypsometric color and relief lighting add depth to the contour field.

## Choose it for

Create an outdoor product introduction with cartographic character. Use the contours as a visual motif while keeping real locations and specifications in HTML.

## Limits

The contours do not represent geographic elevations or GIS data. They are generated for visual design, without map coordinates or elevation uploads.

## Current look

Default. Color Looks change colors only; motion, geometry and typography remain unchanged.

[Open editor](https://www.aperveil.com/shaders/topo-lines/edit?look=default)

## Install

Download the Export Kit from the editor. No shader-specific npm package or CLI is published yet.

```sh
npm install ./vendor/aperveil-runtime-0.1.0.tgz ./vendor/aperveil-react-0.1.0.tgz
```

Every control in the editor is a typed prop. Leave a prop out to keep the value you exported; change one and the running shader updates without restarting. Give the surface a size and pass fallback for browsers without WebGPU.

```tsx
"use client";

import TopoLines from "./TopoLines";

export default function Hero() {
  return (
    <TopoLines
      className="hero-shader"
      scale={2.4} background="#090e12ff"
      fallback={<div className="hero-shader-fallback" />}
    />
  );
}

// .hero-shader { width: 100%; height: 560px; }
```

Component props: `background`, `lowColor`, `highColor`, `lineColor`, `indexColor`, `scale`, `warpStrength`, `ridgeSharpness`, `levels`, `lineWidth`, `majorEvery`, `hypsometric`, `relief`, `flowSpeed`, `hill`, `hillReach`, `opacity`, `className`, `style`, `paused`, `fallback`, `onReady`, `onError`.

Raw WGSL is included for a custom WebGPU host; it is not CSS. Keep semantic headings and links in HTML.

## Controls

- Paper (`background`, color): Colour of the paper, shown where the elevation tint is off.
- Low ground (`lowColor`, color): Tint of the lowest ground.
- High ground (`highColor`, color): Tint of the highest ground.
- Minor contours (`lineColor`, color): Colour of the regular contour lines.
- Index contours (`indexColor`, color): Colour of the heavier index contours.
- Terrain scale (`scale`, slider): Density of the terrain; higher values give smaller, more numerous hills.
- Domain warp (`warpStrength`, slider): How much the terrain twists and folds.
- Ridge sharpness (`ridgeSharpness`, slider): How sharp the ridges are; higher values give crisper, rockier crests.
- Contour count (`levels`, slider): Number of contour levels between the lowest and highest ground.
- Line weight (`lineWidth`, slider): Thickness of the contour lines.
- Index interval (`majorEvery`, slider): How many contours between each heavier index line.
- Elevation tint (`hypsometric`, slider): How strongly the land is tinted by height; 0 leaves plain paper.
- Slope relief (`relief`, slider): Shading of the slopes, as if lit from one side.
- Geologic drift (`flowSpeed`, slider): How fast the terrain slowly shifts; 0 holds it still.
- Pointer elevation (`hill`, slider): Height of the hill the pointer raises in the land.
- Pointer reach (`hillReach`, slider): Width of the hill the pointer raises.
- Opacity (`opacity`, slider): Opacity of the complete effect, including its background.

## Compatibility

WebGPU rendering requires a supported browser and secure context. The landing shows a real poster for the selected Look when live rendering is unavailable. The standard exported component does not bundle a poster fallback. Supply your own fallback in the host layout. Text exports also retain readable HTML typography.

## Performance

6.2 ms legacy timing (method not recorded; not a pure GPU measurement). 1440x900 @ dpr 2; Metal driver on macOS Version 26.6.2 (Build 25G83); measured 2026-09-03. This is a recorded headless sample, not a browser FPS or mobile-performance guarantee.

## Questions

### Can I import a real terrain map?

No. The current terrain is procedural. Terrain scale, Ridge sharpness, Contour count and Index interval shape an invented landscape rather than loading geographic data.

### How can I make the contour pattern less dense?

Reduce Contour count to draw fewer contour intervals, then balance Line weight and Index interval. Terrain scale changes the size of the landforms rather than importing or scaling a real map.

### What should I not use Topo Lines for?

The contours do not represent geographic elevations or GIS data. They are generated for visual design, without map coordinates or elevation uploads.

### What happens without WebGPU?

This landing shows a still poster of your selected Color Look. The raw WGSL needs a WebGPU host. Landing posters are not bundled in the Export Kit: add your own fallback around the exported component.

### Can I use this shader commercially?

Part of the Free collection for Aperveil 1.0. Public live preview and Color Looks are open. Free Export Kits do not require an account. Purchasing is not available yet. Follow the license notices supplied with the source you download. The planned Free collection permits personal and commercial interface projects. An alpha access grant is not a purchase or a replacement for those license terms.

## License

Part of the Free collection for Aperveil 1.0. Public live preview and Color Looks are open. Free Export Kits do not require an account. Purchasing is not available yet. Follow the license notices supplied with the source you download. The planned Free collection permits personal and commercial interface projects. An alpha access grant is not a purchase or a replacement for those license terms.

## Related shaders

- [Line Waves](https://www.aperveil.com/shaders/line-waves)
- [Iso Grid](https://www.aperveil.com/shaders/iso-grid)
- [Grain Gradient](https://www.aperveil.com/shaders/grain-gradient)