Getting from "radiance in nW/cm²/sr" to "Bortle 4" is two conversions and one classic mistake. This post is the mistake.

Step 1: radiance → SQM

VIIRS radiance spans an absurd dynamic range. A genuinely dark rural pixel might read around 0.1–0.3; a suburban street sits in the single digits to low teens; the core of a big city can be 100 or more. You cannot map that linearly onto anything a human reads.

So the map uses a deliberately simplified logarithmic fit — roughly:

sqm ≈ 22.0 - 2.0 * log10(radiance + 1)
sqm = clamp(sqm, 16.0, 22.0)

The +1 keeps the log defined at zero radiance. The clamp reflects reality: you don't get darker than ~22 mag/arcsec² at a truly pristine site, and city cores flatten out around 16–17 for viewing purposes.

This is not a radiative-transfer model. The real reference for ground-level sky brightness — Falchi & Cinzano's World Atlas — runs the satellite data through atmospheric scattering physics. This is curve-fitting tuned to roughly agree with ground measurements. It's good enough to answer "is it darker an hour north of here"; it is not good enough to cite in a paper. I'll come back to why that distinction matters.

Step 2: SQM → Bortle class

The Bortle scale is 9 buckets. Each class boundary corresponds to an SQM threshold — Class 1 is roughly 21.9+, the Class 4/5 boundary sits around 20.5, Class 8 is down near 18, and so on. So step 2 is just: find which bucket the SQM value falls into.

For the location-detail panel that's the whole story. The trouble started when I tried to render the same idea as a map layer.

The binning mistake

One of the color styles on the map is meant to look like contour bands — clean, discrete zones with hard edges, not a smooth gradient. To get that, before handing the image to the visualizer I discretize it into 9 steps.

My first version discretized with a uniform step:

step = (max - min) / 9
band = image.subtract(min).divide(step).floor().clamp(0, 8)

With min = 0 and max = 150 (chosen to cover the brightest city cores), that puts the first band's ceiling at 16.7.

Zoom the map out to continent scale and almost everything goes black.

Here's why. The radiance→SQM relationship is logarithmic specifically because radiance is log-distributed. Most inhabited-but-not-blazing places — small towns, exurbs, anywhere with streetlights but no skyline — sit in the single digits to low teens of radiance. Under a uniform split with a ceiling of 16.7, all of that collapses into band 0, the darkest, rendered black. Only genuine city cores clear the first threshold. The result looks like a black planet with a few glowing dots, which is not what the data actually says.

Uniform binning of a log-distributed quantity throws away all the resolution exactly where most of your users live.

The fix: bin on real Bortle thresholds

Instead of slicing the value range evenly, I went back to the SQM thresholds the Bortle scale already defines, and converted each one back into a radiance breakpoint with the inverse of step 1:

BORTLE_RADIANCE_BREAKPOINTS = BORTLE_SQM_THRESHOLDS.map(sqmToRadiance)

These breakpoints are naturally dense at the dark end — the radiance gap between Bortle 1 and Bortle 4 is only a few units — and wide at the bright end, where an extra 50 nW barely changes what you can see. That matches how the underlying signal is distributed.

Then classify each pixel by counting how many breakpoints it clears:

band = breakpoints
  .map(b => image.gte(b))   // one boolean layer per breakpoint
  .reduce(ee.Reducer.sum()) // 0..8 = the class index

Summing a stack of gte booleans to get a bucket index is a standard trick in Earth Engine — no loops, no server-side iteration. Now a small town with radiance around 8 lands in a middle band with a visible color instead of being quantized to black, and the continent-scale view actually shows the gradient that's in the data.

One more detail: discretize after a light smoothing pass (focal_mean over a few pixels), not before. Pixel-level noise, quantized directly, produces confetti — each noisy pixel snaps to a different band. Smooth the continuous signal first, then bin.

The lesson, and why the methodology page exists

The generalizable takeaway: before you bucket a continuous physical quantity, check whether the underlying distribution is linear. If it's log-distributed — radiance, sound intensity, a lot of natural signals — uniform bins will crush detail at one end. Bin on domain-meaningful breakpoints instead.

The specific takeaway is that every number this map shows you is the output of a chain of approximations: a simplified radiance→SQM fit, a threshold table for Bortle, a binning choice for the map layer, an annual composite that's over a year old. None of it is a measurement.

Rather than bury that, I wrote up every step of that conversion on a separate methodology page — what the satellite input is, that the brightness model is a simplified log formula rather than an atmospheric one, and that the Bortle class is derived from a modeled value, not observed in the field. If you're going to show people an estimate they'll make decisions on, the honest move is to show your work.