Technical Guide

Technical guide

This page will document how the app calculates wave data, filters surf spots, and combines buoy, wind, and tide information.

Sections will be added here over time as the forecast logic is documented.

Temporary Experiments

NOAA wave test page

Use the temporary NOAA test page to verify that the app can pull a live GFS Wave subset for a small box north of Hanalei Bay, including a far-range 16-day request.

Open NOAA test

Swell Timing

How swell travel time is estimated from a buoy

The app estimates swell timing by treating the swell as a moving line of energy in deep water. It uses the buoy location, the destination shoreline target, and the swell period reported by the buoy.

First, the swell period is converted into an approximate deep-water group speed:

group speed (knots) ≈ 1.515 × swell period (seconds)

Next, the app converts the swell “from” direction into a travel direction by adding 180 degrees. That travel vector is compared against the line from the buoy to the coastline target.

Instead of only using straight-line distance, the app projects the buoy-to-target vector onto the swell travel axis. That produces a signed distance:

signed distance = dot(target - buoy, unitVector(travelDirection))

Travel time is then estimated by dividing that signed distance by the swell group speed:

arrival hours = signed distance / group speed

A positive result means the swell line has not reached the target yet. A negative result means that the swell line has already passed the target. That is why an east or southeast swell can show as “past Hanalei Bay” when viewed from a northwest buoy.

Pseudocode

travelDirection = swellFromDirection + 180
groupSpeedKnots = 1.515 * swellPeriodSeconds
signedDistance = dot(targetVectorFromBuoy, unitVector(travelDirection))
arrivalHours = signedDistance / groupSpeedKnots

Swell speed by period

These are the approximate deep-water group speeds used by the app when estimating travel time from a buoy.

Swell period	Group speed	Approx mph
8s	12.1 kt	13.9 mph
10s	15.1 kt	17.4 mph
12s	18.2 kt	20.9 mph
14s	21.2 kt	24.4 mph
16s	24.2 kt	27.9 mph
18s	27.3 kt	31.4 mph

Back to buoy pages

Buoy Power

How buoy power and wave height are estimated

Forecast power in the app is a custom energy-style score based on swell height and swell period. It replaces Surfline's row power as the source of truth for filters and forecast displays.

The calculation starts with the idea that both height and period should matter a lot, especially for long-period reef swell, but neither should dominate too aggressively on its own:

swell power = swell height × swell period

In the formula above:

swell height is in feet
swell period is in seconds

This means the power score is not a direct physics unit like watts or kilowatts. It is a surf-forecast scoring metric that increases strongly with both size and period.

Forecast row power is then calculated from the matching swells for a spot: the biggest eligible swell power plus half of the second biggest eligible swell power.

Estimated surf height uses a different idea. Instead of reusing period directly, the app maps combined power to a simple linear display scale.

row power = biggest matching swell power + 0.5 × second biggest matching swell power

The power-to-height conversion is intentionally coarse. It is a surf-facing heuristic for filtering and display, not a spot-specific breaking-wave model.

Pseudocode

if swellHeightFeet == null or swellPeriodSeconds == null:
  return null

swellPower = swellHeightFeet * swellPeriodSeconds
rowPower = strongestMatchingSwellPower + 0.5 * secondStrongestMatchingSwellPower

Power To Height Bands

10 power => 1 ft
15 power => 1.5 ft
20 power => 2 ft
25 power => 2.5 ft
30 power => 3 ft
...
power / 10 => estimated surf height in feet

Estimated surf	Power band
1 ft	10-10
1.5 ft	15-15
2 ft	20-20
2.5 ft	25-25
3 ft	30-30
3.5 ft	35-35
4 ft	40-40
4.5 ft	45-45
5 ft	50-50
6 ft	60-60
7 ft	70-70
8 ft	80-80
9 ft	90-90
10 ft	100-100
12 ft	120-120
14 ft	140-140
16 ft	160-160
18 ft	180-180
20 ft	200-200
25 ft	250-250
30 ft	300-300
35 ft	350-350
40 ft	400-400

Example buoy power and wave-height values

These examples use the same formulas documented in this section so you can compare how power and estimated face height scale differently.

Buoy swell	Calculation	Power	Est. wave face height
2.0 ft @ 8s	2.0 × 8	16.0	1.6 ft
2.5 ft @ 12s	2.5 × 12	30.0	3.0 ft
3.5 ft @ 8s	3.5 × 8	28.0	2.8 ft
4.0 ft @ 10s	4.0 × 10	40.0	4.0 ft
4.9 ft @ 14.8s	4.9 × 14.8	72.5	7.3 ft
5.4 ft @ 8s	5.4 × 8	43.2	4.3 ft
6.0 ft @ 12s	6.0 × 12	72.0	7.2 ft
6.5 ft @ 8s	6.5 × 8	52.0	5.2 ft
8.0 ft @ 18s	8.0 × 18	144.0	14.4 ft
7.8 ft @ 9s	7.8 × 9	70.2	7.0 ft
10.0 ft @ 16s	10.0 × 16	160.0	16.0 ft
12.0 ft @ 18s	12.0 × 18	216.0	21.6 ft
18.0 ft @ 20s	18.0 × 20	360.0	36.0 ft

This power score is best used as a relative measure of swell energy. Higher numbers mean more potential surf energy offshore, but they do not directly guarantee a specific breaking wave height at the beach.

The estimated wave-height value is intended to be a more intuitive surf-facing number than power. It is still a coarse heuristic and should be treated as a generic offshore-to-surf estimate, not a spot-specific breaking-wave model.

Direction, refraction, island shadowing, and local bathymetry still determine how much of that energy actually turns into surf at a given spot and how big the final breaking waves appear.