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.

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

Buoy power in the app is a calibrated energy-style score based on swell height and swell period from the buoy. It is designed to feel closer to the Surfline-style power values used elsewhere in the forecast, while still using a simple local formula.

The calculation starts with the idea that swell energy rises faster than height alone, so height is squared and then weighted by period:

buoy power = 1.23 × swell height² × swell period

In the formula above:

swell height is in feet
swell period is in seconds
the `1.23` factor is a calibration constant

This means buoy power 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.

Height matters most because it is squared. Period still matters a lot, but it grows linearly, which keeps the result from becoming as explosive as a more heavily weighted power formula.

Wave height uses a different idea. Instead of squaring height, it starts with the buoy swell height and applies a gentler period multiplier to estimate an offshore-to-surf face-height style number.

estimated wave face height = swell height × clamp((period / 8)^0.5, 0.9, 2.0)

This keeps wave-height growth more moderate than power and a bit more conservative overall. Longer period still increases the estimate, but not nearly as sharply as a squared-energy style score.

Pseudocode

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

buoyPower = 1.23 * swellHeightFeet * swellHeightFeet * swellPeriodSeconds

Wave Height Pseudocode

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

periodMultiplier = (swellPeriodSeconds / 8)^0.5
clampedMultiplier = clamp(periodMultiplier, 0.9, 2.0)
estimatedWaveFaceHeight = swellHeightFeet * clampedMultiplier

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	1.23 × 2.0² × 8	39.4	2.0 ft
2.5 ft @ 12s	1.23 × 2.5² × 12	92.3	3.1 ft
3.5 ft @ 8s	1.23 × 3.5² × 8	120.5	3.5 ft
4.0 ft @ 10s	1.23 × 4.0² × 10	196.8	4.5 ft
4.9 ft @ 14.8s	1.23 × 4.9² × 14.8	437.1	6.7 ft
5.4 ft @ 8s	1.23 × 5.4² × 8	286.9	5.4 ft
6.0 ft @ 12s	1.23 × 6.0² × 12	531.4	7.3 ft
6.5 ft @ 8s	1.23 × 6.5² × 8	415.7	6.5 ft
8.0 ft @ 18s	1.23 × 8.0² × 18	1417.0	12.0 ft
7.8 ft @ 9s	1.23 × 7.8² × 9	673.5	8.3 ft
10.0 ft @ 16s	1.23 × 10.0² × 16	1968.0	14.1 ft
12.0 ft @ 18s	1.23 × 12.0² × 18	3188.2	18.0 ft
18.0 ft @ 20s	1.23 × 18.0² × 20	7970.4	28.5 ft

This buoy power score is best used as a relative measure of swell energy. Higher numbers mean more potential surf energy at the buoy, 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 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.