Kepler.gl is a powerful open source geospatial analysis tool for large-scale data sets.
feat: add Jenks natural breaks color scale (#3742)
Igor Dykhta3be42f855a19
diff --git a/docs/spatial-analysis-tutorial/basic-mapping.md b/docs/spatial-analysis-tutorial/basic-mapping.mdindex b62fdf388..39d712722 100644--- a/docs/spatial-analysis-tutorial/basic-mapping.md+++ b/docs/spatial-analysis-tutorial/basic-mapping.md@@ -73,6 +73,10 @@ Any time there are ties in the ranking of observations that align with the valueA natural (Jenks) breaks map uses a nonlinear algorithm to group observations such that the within-group homogeneity is maximized, following the pathbreaking work of Fisher ([1958](https://www.jstor.org/stable/2281952)) and Jenks ([1977](https://books.google.com/books/about/Optimal_Data_Classification_for_Chorople.html?id=HvAENQAACAAJ)). In essence, this is a clustering algorithm in one dimension to determine the break points that yield groups with the largest internal similarity.+:::tip+In Kepler.gl, natural breaks are the **Jenks Natural Breaks** color scale. You can select it from the Color Scale dropdown when coloring a numeric field.+:::+To create such a map with four categories, you can use the following prompt:```diff --git a/docs/user-guides/d-layer-attributes.md b/docs/user-guides/d-layer-attributes.mdindex 2ca15f5d5..7453c07a4 100644--- a/docs/user-guides/d-layer-attributes.md+++ b/docs/user-guides/d-layer-attributes.md@@ -12,7 +12,7 @@| Stroke width range | Set a lower and upper threshold for projected stroke width. | Arc, Line, Geojson || Grid size | Change the number of square kilometers covered by each grid square. | Grid || Color Palette | Choose from multiple, predefined or customized color palettes to apply to your layer. Predefined palettes are either Uber or ColorBrewer colors. | All layers |-| Color Scale | Choose either a quantile or quantized color scale. A quantile color scale is determined by rank, while a quantized color scale is determined by value. | All layers |+| Color Scale | Choose a quantile, quantized, Jenks natural breaks, or custom color scale. Quantile is determined by rank, quantized by equal value intervals, and Jenks by clustering similar values. | All layers || Height based on | Assign grid square height based on a field from your dataset. | Grid, Hexagon, S2 || Filter by count percentile | Increase or decrease the number of grid squares by choosing a range of percentiles to display. | Grid, Hexagon || Coverage | Change what portion of each grid cell is covered by a color square. | Grid, Hexagon |diff --git a/src/constants/src/default-settings.ts b/src/constants/src/default-settings.tsindex f05d3da57..ff4670d41 100644--- a/src/constants/src/default-settings.ts+++ b/src/constants/src/default-settings.ts@@ -451,6 +451,7 @@ export type SCALE_TYPES_DEF = {ordinal: 'ordinal';quantile: 'quantile';quantize: 'quantize';+ jenks: 'jenks';linear: 'linear';sqrt: 'sqrt';log: 'log';@@ -464,6 +465,7 @@ export const SCALE_TYPES: SCALE_TYPES_DEF = keyMirror({ordinal: null,quantile: null,quantize: null,+ jenks: null,linear: null,sqrt: null,log: null,@@ -477,6 +479,7 @@ export const SCALE_TYPE_NAMES: {[key in keyof SCALE_TYPES_DEF]: string} = {ordinal: 'Ordinal',quantile: 'Quantile',quantize: 'Quantize',+ jenks: 'Jenks Natural Breaks',linear: 'Linear',sqrt: 'Sqrt',log: 'Log',@@ -494,6 +497,7 @@ export const SCALE_FUNC = {[SCALE_TYPES.linear]: scaleLinear,[SCALE_TYPES.quantize]: scaleQuantize,[SCALE_TYPES.quantile]: scaleQuantile,+ [SCALE_TYPES.jenks]: scaleThreshold,[SCALE_TYPES.ordinal]: scaleOrdinal,[SCALE_TYPES.sqrt]: scaleSqrt,[SCALE_TYPES.log]: scaleLog,@@ -702,7 +706,12 @@ export const AGGREGATION_TYPE_OPTIONS: {id: string; label: string}[] = Object.en}));export const linearFieldScaleFunctions = {- [CHANNEL_SCALES.color]: [SCALE_TYPES.quantize, SCALE_TYPES.quantile, SCALE_TYPES.custom],+ [CHANNEL_SCALES.color]: [+ SCALE_TYPES.quantize,+ SCALE_TYPES.quantile,+ SCALE_TYPES.jenks,+ SCALE_TYPES.custom+ ],[CHANNEL_SCALES.radius]: [SCALE_TYPES.sqrt],[CHANNEL_SCALES.size]: [SCALE_TYPES.linear, SCALE_TYPES.sqrt, SCALE_TYPES.log],[CHANNEL_SCALES.angle]: [SCALE_TYPES.linear]@@ -711,6 +720,7 @@ export const linearFieldScaleFunctions = {const DEFAULT_AGGREGATION_COLOR_SCALES = [SCALE_TYPES.quantize,SCALE_TYPES.quantile,+ SCALE_TYPES.jenks,SCALE_TYPES.custom];diff --git a/src/deckgl-layers/src/layer-utils/aggregation-utils.ts b/src/deckgl-layers/src/layer-utils/aggregation-utils.tsindex 2211bb0ef..ce60b1792 100644--- a/src/deckgl-layers/src/layer-utils/aggregation-utils.ts+++ b/src/deckgl-layers/src/layer-utils/aggregation-utils.ts@@ -2,6 +2,38 @@// Copyright contributors to the kepler.gl projectimport type {AggregatedBin, ColorMap} from '@kepler.gl/types';+import {naturalBreaks} from '@kepler.gl/utils';++type JenksColorMapCache = {+ source: Float32Array;+ k: number;+ breaks: number[];+ colorMap: ColorMap;+};++function getJenksColorMap(values: number[], k: number): {breaks: number[]; colorMap: ColorMap} {+ const breaks = naturalBreaks(values, k);+ // classifyBinsByCustomBreaks only reads numeric thresholds from colorMap.+ const colorMap: ColorMap = [+ ...breaks.map(threshold => [threshold, '#000000'] as [number, string]),+ [null, '#000000']+ ];+ return {breaks, colorMap};+}++function resolveJenksColorMapCache(+ source: Float32Array,+ binCount: number,+ k: number,+ cached?: JenksColorMapCache | null+): JenksColorMapCache {+ if (cached && cached.source === source && cached.k === k) {+ return cached;+ }+ const values = Array.from(source.subarray(0, binCount)).filter(Number.isFinite) as number[];+ const {breaks, colorMap} = getJenksColorMap(values, k);+ return {source, k, breaks, colorMap};+}/*** Build a Record<index, AggregatedBin> from the raw Float32Array of per-bin@@ -121,10 +153,7 @@ export function enrichedAggregationUpdate(layer: any, ParentClass: any, channel:const binValues = result?.value as Float32Array | undefined;if (!binValues || aggregator.binCount <= 0) return;- layer.setState({- rawColorBinValues: Float32Array.from(binValues.subarray(0, aggregator.binCount))- });-+ const rawColorBinValues = Float32Array.from(binValues.subarray(0, aggregator.binCount));const domain = aggregator.getResultDomain(0);const aggregatedBins = buildAggregatedBinMap(binValues, aggregator.binCount, aggregator);@@ -133,18 +162,36 @@ export function enrichedAggregationUpdate(layer: any, ParentClass: any, channel:}let enrichedDomain = domain;+ let jenksColorMapCache: JenksColorMapCache | null = null;if (props.colorScaleType === 'quantile') {enrichedDomain = Array.from(binValues).slice(0, aggregator.binCount).filter(Number.isFinite).sort((a: number, b: number) => a - b);+ } else if (props.jenksScale) {+ const k = Array.isArray(props.colorRange) ? props.colorRange.length : 0;+ jenksColorMapCache = resolveJenksColorMapCache(rawColorBinValues, aggregator.binCount, k, null);+ classifyBinsByCustomBreaks(+ layer.state.colors,+ aggregator.binCount,+ jenksColorMapCache.colorMap,+ binValues+ );+ enrichedDomain = jenksColorMapCache.breaks;}++ layer.setState({+ rawColorBinValues,+ jenksColorMapCache+ });props.onSetColorDomain?.({domain: enrichedDomain, aggregatedBins});}/*** Shared renderLayers() wrapper that re-classifies bins when custom colorMap- * changes between renders without triggering a full re-aggregation.+ * or Jenks class count changes between renders without a full re-aggregation.+ * Jenks breaks are reused from `jenksColorMapCache` until the bin values or+ * palette size change.** @param layer The enhanced layer instance (`this`)* @param ParentClass The deck.gl parent class (HexagonLayer or GridLayer)@@ -152,9 +199,24 @@ export function enrichedAggregationUpdate(layer: any, ParentClass: any, channel:*/export function enrichedRenderLayers(layer: any, ParentClass: any): any {const props = layer.getCurrentLayer().props;- const {colors, rawColorBinValues, aggregator} = layer.state;- if (props.colorMap && colors && rawColorBinValues && aggregator?.binCount > 0) {- classifyBinsByCustomBreaks(colors, aggregator.binCount, props.colorMap, rawColorBinValues);+ const {colors, rawColorBinValues, aggregator, jenksColorMapCache} = layer.state;+ if (colors && rawColorBinValues && aggregator?.binCount > 0) {+ if (props.colorMap) {+ classifyBinsByCustomBreaks(colors, aggregator.binCount, props.colorMap, rawColorBinValues);+ } else if (props.jenksScale) {+ const k = Array.isArray(props.colorRange) ? props.colorRange.length : 0;+ const cache = resolveJenksColorMapCache(+ rawColorBinValues,+ aggregator.binCount,+ k,+ jenksColorMapCache+ );+ // Assign on state directly: setState during renderLayers would retrigger rendering.+ if (cache !== jenksColorMapCache) {+ layer.state.jenksColorMapCache = cache;+ }+ classifyBinsByCustomBreaks(colors, aggregator.binCount, cache.colorMap, rawColorBinValues);+ }}return (ParentClass.prototype as any).renderLayers.call(layer);}diff --git a/src/deckgl-layers/src/layer-utils/cpu-aggregator.ts b/src/deckgl-layers/src/layer-utils/cpu-aggregator.tsindex 89770b375..5713fd0a0 100644--- a/src/deckgl-layers/src/layer-utils/cpu-aggregator.ts+++ b/src/deckgl-layers/src/layer-utils/cpu-aggregator.ts@@ -4,8 +4,8 @@/* eslint-disable guard-for-in */import {console as Console} from 'global/window';-import {aggregate} from '@kepler.gl/utils';-import {AGGREGATION_TYPES, SCALE_FUNC} from '@kepler.gl/constants';+import {aggregate, naturalBreaks} from '@kepler.gl/utils';+import {AGGREGATION_TYPES, SCALE_FUNC, SCALE_TYPES} from '@kepler.gl/constants';import {RGBAColor} from '@kepler.gl/types';import type ClusterBuilder from './cluster-utils';@@ -303,6 +303,14 @@ export function getDimensionValueDomain(this: CPUAggregator, step, props, dimens);}+ if (props.colorScaleType === SCALE_TYPES.jenks) {+ const values = this.state.dimensions[key].sortedBins.aggregatedBins+ .map(bin => bin.value)+ .filter(Number.isFinite);+ const k = Array.isArray(props.colorRange) ? props.colorRange.length : 0;+ valueDomain = naturalBreaks(values, k);+ }+this._setDimensionState(key, {valueDomain});}@@ -411,7 +419,7 @@ function getSubLayerAccessor(const domain = scaleFunc.domain();const isValueInDomain =- scaleFunc.scaleType === 'custom'+ scaleFunc.scaleType === 'custom' || scaleFunc.scaleType === SCALE_TYPES.jenks? cv >= sortedBins.minValue && cv <= sortedBins.maxValue: cv >= domain[0] && cv <= domain[domain.length - 1];diff --git a/src/layers/src/aggregation-layer.ts b/src/layers/src/aggregation-layer.tsindex ad0db7345..e2b158896 100644--- a/src/layers/src/aggregation-layer.ts+++ b/src/layers/src/aggregation-layer.ts@@ -10,7 +10,7 @@ import Layer, {VisualChannelDescription,VisualChannels} from './base-layer';-import {hexToRgb, aggregate, DataContainerInterface} from '@kepler.gl/utils';+import {hexToRgb, aggregate, DataContainerInterface, naturalBreaks} from '@kepler.gl/utils';import {HIGHLIGH_COLOR_3D,CHANNEL_SCALES,@@ -19,7 +19,8 @@ import {AGGREGATION_TYPES,ALL_FIELD_TYPES,GEOJSON_FIELDS,- GEOARROW_METADATA_KEY+ GEOARROW_METADATA_KEY,+ SCALE_TYPES} from '@kepler.gl/constants';import {ColorRange, Field, LayerColumn, Merge} from '@kepler.gl/types';import {KeplerTable, Datasets} from '@kepler.gl/table';@@ -336,8 +337,9 @@ export default class AggregationLayer extends Layer {updateLayerVisualChannel({dataContainer}, channel) {this.validateVisualChannel(channel);- // When the color scale type changes, recompute colorDomain from stored aggregatedBins.- // quantile scale needs the full sorted array of bin values; other scales need [min, max].+ // When the color scale type or palette size changes, recompute colorDomain from+ // stored aggregatedBins. Quantile needs the full sorted array; Jenks needs k-1+ // thresholds from those bins; other scales need [min, max].// aggregatedBins is only populated from onSetColorDomain, so restrict to the color channel.const visualChannel = this.visualChannels[channel];if (channel === 'color' && visualChannel && this.config.aggregatedBins) {@@ -351,6 +353,13 @@ export default class AggregationLayer extends Layer {.filter(Number.isFinite).sort((a, b) => a - b);this.updateLayerConfig({[domainKey]: sorted});+ } else if (scaleType === SCALE_TYPES.jenks) {+ const values = bins.map(b => b.value).filter(Number.isFinite) as number[];+ const colorRange = visualChannel.range+ ? this.config.visConfig[visualChannel.range]+ : undefined;+ const k = Array.isArray(colorRange?.colors) ? colorRange.colors.length : 0;+ this.updateLayerConfig({[domainKey]: naturalBreaks(values, k)});} else {let min = Infinity;let max = -Infinity;@@ -673,6 +682,7 @@ export default class AggregationLayer extends Layer {colorAggregation: this.config.visConfig.colorAggregation,colorRange: visConfig.colorRange,colorMap: visConfig.colorRange.colorMap,+ colorScale: this.config.colorScale,filterRange: gpuFilter.filterRange,...gpuFilter.filterValueUpdateTriggers},@@ -687,18 +697,19 @@ export default class AggregationLayer extends Layer {// deck.gl's aggregation shader maps bin values to a color texture using a// simple linear interpolation: (value - domain[0]) / (domain[1] - domain[0]).// It only understands 'quantize', 'quantile', 'ordinal', and 'linear'.- // kepler.gl's 'custom' scale (d3.scaleThreshold with user-defined break- // points) cannot be represented in the shader directly. Instead, our- // ScaleEnhanced*Layer._onAggregationUpdate reclassifies each bin's raw- // value into a break index [0 … N-1]. We then tell deck.gl to use- // 'quantize' over [0, N-1] so each index maps to the correct color pixel.+ // kepler.gl's 'custom' and 'jenks' scales (d3.scaleThreshold) cannot be+ // represented in the shader directly. Instead, ScaleEnhanced*Layer+ // reclassifies each bin's raw value into a break index [0 … N-1]. We then+ // tell deck.gl to use 'quantize' over [0, N-1] so each index maps to the+ // correct color pixel.let colorScaleType = this.config.colorScale as string;let customColorDomain: [number, number] | undefined;- const isCustomScale = colorScaleType === 'custom';+ const isCustomScale = colorScaleType === SCALE_TYPES.custom;+ const isJenksScale = colorScaleType === SCALE_TYPES.jenks;const colorMap = isCustomScale ? visConfig.colorRange.colorMap : undefined;- if (isCustomScale && colorMap) {- colorScaleType = 'quantize';- customColorDomain = [0, colorMap.length - 1];+ if ((isCustomScale && colorMap) || isJenksScale) {+ colorScaleType = SCALE_TYPES.quantize;+ customColorDomain = [0, visConfig.colorRange.colors.length - 1];}return {@@ -709,6 +720,7 @@ export default class AggregationLayer extends Layer {colorRange: this.getColorRange(visConfig.colorRange),colorMap,colorScaleType,+ jenksScale: isJenksScale,...(customColorDomain ? {colorDomain: customColorDomain} : {}),upperPercentile: visConfig.percentile[1],lowerPercentile: visConfig.percentile[0],diff --git a/src/layers/src/base-layer.ts b/src/layers/src/base-layer.tsindex 5716ab2ee..46339b3ff 100644--- a/src/layers/src/base-layer.ts+++ b/src/layers/src/base-layer.ts@@ -1286,9 +1286,11 @@ class Layer implements KeplerLayer {return getScale;}- return SCALE_FUNC[fixed ? 'linear' : scale]()+ const scaleFunc = SCALE_FUNC[fixed ? 'linear' : scale]().domain(domain).range(fixed ? domain : range);+ (scaleFunc as {scaleType?: string}).scaleType = fixed ? 'linear' : scale;+ return scaleFunc;}/**@@ -1553,7 +1555,8 @@ class Layer implements KeplerLayer {return defaultDomain;}- return dataset.getColumnLayerDomain(field, scaleType) || defaultDomain;+ const range = this.config.visConfig[visualChannel.range];+ return dataset.getColumnLayerDomain(field, scaleType, range) || defaultDomain;}hasHoveredObject(objectInfo) {diff --git a/src/layers/src/vector-tile/vector-tile-layer.ts b/src/layers/src/vector-tile/vector-tile-layer.tsindex 1f560842a..521ef9a70 100644--- a/src/layers/src/vector-tile/vector-tile-layer.ts+++ b/src/layers/src/vector-tile/vector-tile-layer.ts@@ -413,6 +413,9 @@ export default class VectorTileLayer extends AbstractTileLayer<VectorTile, FeatugetScaleOptions(channelKey: string): string[] {let options = KeplerLayer.prototype.getScaleOptions.call(this, channelKey);+ // Jenks needs the full value distribution, which tilesets don't provide.+ options = options.filter(scale => scale !== SCALE_TYPES.jenks);+const channel = this.visualChannels.strokeColor;const field = this.config[channel.field];if (diff --git a/src/reducers/src/vis-state-updaters.ts b/src/reducers/src/vis-state-updaters.tsindex 7dedd2e31..6218eb86d 100644--- a/src/reducers/src/vis-state-updaters.ts+++ b/src/reducers/src/vis-state-updaters.ts@@ -1200,6 +1200,25 @@ export function layerVisConfigChangeUpdater(const newLayer = oldLayer.updateLayerConfig({visConfig: newVisConfig});+ // Jenks breaks depend on the number of colors. Recalculate the domain when+ // the color range of a Jenks channel changes.+ if (oldLayer.config.dataId) {+ const dataset = state.datasets[oldLayer.config.dataId];+ if (dataset) {+ Object.keys(newLayer.visualChannels).forEach(channelKey => {+ const channel = newLayer.visualChannels[channelKey];+ if (+ channel?.scale &&+ newLayer.config[channel.scale] === SCALE_TYPES.jenks &&+ channel.range &&+ Object.prototype.hasOwnProperty.call(action.newVisConfig, channel.range)+ ) {+ newLayer.updateLayerVisualChannel(dataset, channelKey);+ }+ });+ }+ }+let nextState = state;// Exclusive bitmap editing: when editBounds is turned on for one bitmap layer,diff --git a/src/table/src/kepler-table.ts b/src/table/src/kepler-table.tsindex 7216428b1..351b79aa1 100644--- a/src/table/src/kepler-table.ts+++ b/src/table/src/kepler-table.ts@@ -14,6 +14,7 @@ import {} from '@kepler.gl/constants';import {RGBColor,+ ColorRange,Field,FieldPair,FieldDomain,@@ -49,6 +50,7 @@ import {getLogDomain,getOrdinalDomain,getQuantileDomain,+ getJenksDomain,DataContainerInterface,FilterChanged} from '@kepler.gl/utils';@@ -795,7 +797,11 @@ class KeplerTable<F extends Field = Field> {/*** Get the domain of this column based on scale type*/- getColumnLayerDomain(field: F, scaleType: string): number[] | string[] | [number, number] | null {+ getColumnLayerDomain(+ field: F,+ scaleType: string,+ range?: ColorRange+ ): number[] | string[] | [number, number] | null {const {dataContainer, filteredIndexForDomain} = this;if (!SCALE_TYPES[scaleType]) {@@ -818,6 +824,15 @@ class KeplerTable<F extends Field = Field> {case SCALE_TYPES.quantile:return getQuantileDomain(filteredIndexForDomain, indexValueAccessor, sortFunction);+ case SCALE_TYPES.jenks:+ if (!range?.colors) {+ Console.error(+ 'the range is either missing or it does not have colors available for Jenks scale domain calculation'+ );+ return null;+ }+ return getJenksDomain(filteredIndexForDomain, indexValueAccessor, range.colors.length);+case SCALE_TYPES.log:return getLogDomain(filteredIndexForDomain, indexValueAccessor);diff --git a/src/utils/src/data-scale-utils.ts b/src/utils/src/data-scale-utils.tsindex 603824c5f..18953a106 100644--- a/src/utils/src/data-scale-utils.ts+++ b/src/utils/src/data-scale-utils.ts@@ -27,6 +27,7 @@ import {isRgbColor, rgbToHex, hexToRgb} from './color-utils';import {DataContainerInterface} from './data-container-interface';import {formatNumber, isNumber, reverseFormatNumber, unique} from './data-utils';import {getTimeWidgetHintFormatter} from './filter-utils';+import naturalBreaks from './jenks';import {isPlainObject} from './utils';export type ColorBreak = {@@ -63,6 +64,23 @@ export function getQuantileDomain(return values.filter(notNullorUndefined).sort(sortFunc);}+/**+ * Return Jenks natural-break thresholds for an array of data.+ * `k` is the number of color classes (range length).+ */+export function getJenksDomain(+ data: any[],+ valueAccessor: dataValueAccessor | undefined,+ k: number+): number[] {+ const values =+ typeof valueAccessor === 'function'+ ? data.map(valueAccessor).filter(isNumber)+ : data.filter(isNumber);++ return naturalBreaks(values, k);+}+/*** return ordinal domain for a data container*/@@ -237,7 +255,7 @@ export function getQuantLegends(scale: D3ScaleFunction, labelFormat: LabelFormatconst thresholdLabelFormat = (n, type) =>n && labelFormat ? labelFormat(n) : n ? formatNumber(n, type) : 'no value';const labels =- scale.scaleType === 'threshold'+ scale.scaleType === 'threshold' || scale.scaleType === SCALE_TYPES.jenks? getThresholdLabels(scale, thresholdLabelFormat): scale.scaleType === 'custom'? getThresholdLabels(scale, customScaleLabelFormat)@@ -307,6 +325,9 @@ export function getLegendOfScale({}const formatLabel = labelFormat || getQuantLabelFormat(scale.domain(), fieldType);+ if (scaleType === SCALE_TYPES.jenks) {+ scale.scaleType = SCALE_TYPES.jenks;+ }return getQuantLegends(scale, formatLabel);}diff --git a/src/utils/src/index.ts b/src/utils/src/index.tsindex 4477203be..132bd0822 100644--- a/src/utils/src/index.ts+++ b/src/utils/src/index.ts@@ -170,6 +170,7 @@ export {colorBreaksToColorMap,getLayerColorScale,getLegendOfScale,+ getJenksDomain,getLinearDomain,getLogDomain,getOrdinalDomain,@@ -215,6 +216,7 @@ export type {DatabaseAdapter, DatabaseConnection} from './application-config-typexport {isAppleDevice} from './browser-utils';export {default as quickInsertionSort} from './quick-insertion-sort';+export {default as naturalBreaks} from './jenks';export type {KeplerTableModel} from './types';diff --git a/src/utils/src/jenks.ts b/src/utils/src/jenks.tsnew file mode 100644index 000000000..2461e02cd--- /dev/null+++ b/src/utils/src/jenks.ts@@ -0,0 +1,163 @@+// SPDX-License-Identifier: MIT+// Copyright contributors to the kepler.gl project++import quickInsertionSort from './quick-insertion-sort';++type JenksLocalResult = {+ gvf: number;+ breakValues: number[];+};++/**+ * Permutation-based Jenks natural breaks.+ * Returns k-1 thresholds for a d3 threshold scale (or fewer when unique values < k).+ */+export default function naturalBreaks(data: number[], k: number): number[] {+ const dataSize = data.length;+ const sortedData = data.slice();++ quickInsertionSort(sortedData);++ // Unique values and the first index of each in the sorted array.+ const uniqueValPositions: number[] = [];+ for (let i = 0; i < dataSize; ++i) {+ if (i === 0 || sortedData[i] !== sortedData[i - 1]) {+ uniqueValPositions.push(i);+ }+ }+ const uniqueValuesSize = uniqueValPositions.length;++ // Rule of thumb: small data size -- more permutations; large -- fewer.+ let permutation = Math.floor(44000000 / Math.max(dataSize, 1));+ if (permutation < 10) permutation = 10;+ if (permutation > 1000) permutation = 1000;++ return run();++ function run(): number[] {+ if (k <= 1 || uniqueValuesSize <= 0) {+ return [];+ }++ if (k >= uniqueValuesSize) {+ // Each unique value is its own class. A threshold scale with k colors+ // needs exactly k-1 edges, so pad duplicate thresholds only up to that.+ let breaks = uniqueValPositions.map(i => sortedData[i]);+ if (uniqueValuesSize > 1) {+ breaks = breaks.slice(1);+ }+ const lastBreak = breaks[breaks.length - 1];+ for (let i = breaks.length; i < k - 1; ++i) {+ breaks.push(lastBreak);+ }+ return breaks;+ }++ const gssd = computeGSSD();+ return findBestBreaks(gssd, permutation);+ }++ function findBestBreaks(gssd: number, perm: number): number[] {+ let bestGvf = 0;+ let bestBreaks: number[] = [];++ for (let i = 0; i < perm; ++i) {+ const localResult = computeLocalSSD(i, gssd);+ if (localResult.gvf > bestGvf) {+ bestGvf = localResult.gvf;+ bestBreaks = localResult.breakValues;+ }+ }+ return bestBreaks;+ }++ function computeGSSD(): number {+ let sum = 0;+ for (let i = 0; i < dataSize; ++i) {+ sum += sortedData[i];+ }+ const mean = dataSize === 0 ? 0 : sum / dataSize;++ let gssd = 0;+ for (let i = 0; i < dataSize; ++i) {+ const diff = sortedData[i] - mean;+ gssd += diff * diff;+ }+ return gssd;+ }++ /**+ * A single iteration of Bob Jenkins' One-At-A-Time hashing algorithm.+ * Used as a deterministic seed for the PRNG.+ */+ function hash(x: number): number {+ x += (x << 10) >>> 0;+ if (x > 4294967295) x = x & 4294967295;+ x ^= x >> 6;+ x += (x << 3) >>> 0;+ if (x > 4294967295) x = x & 4294967295;+ x ^= x >> 11;+ x += (x << 15) >>> 0;+ if (x > 4294967295) x = x & 4294967295;+ return x;+ }++ /**+ * Seeded PRNG: https://gist.github.com/tommyettinger/46a874533244883189143505d203312c+ */+ function mulberry32(a: number): () => number {+ return () => {+ let t = (a += 0x6d2b79f5);+ t = Math.imul(t ^ (t >>> 15), t | 1);+ t ^= t + Math.imul(t ^ (t >>> 7), t | 61);+ return ((t ^ (t >>> 14)) >>> 0) / 4294967296;+ };+ }++ function pickRandomPositions(seed: number): number[] {+ const rng = mulberry32(seed);+ const randomPositions = new Set<number>();+ // Skip index 0: a break at the first element creates an empty first class.+ const candidatePositions = uniqueValPositions.slice(1);+ const poolSize = candidatePositions.length;+ const maxRandNumber = k - 1;+ while (randomPositions.size < maxRandNumber) {+ const i = Math.floor(rng() * poolSize);+ randomPositions.add(candidatePositions[i]);+ }+ const positions = Array.from(randomPositions);+ positions.sort((a, b) => a - b);+ return positions;+ }++ function localGvf(randomPositions: number[], gssd: number): number {+ let tssd = 0;++ for (let i = 0; i < k; ++i) {+ const s = i === 0 ? 0 : randomPositions[i - 1];+ const e = i === k - 1 ? dataSize : randomPositions[i];++ let localMean = 0;+ for (let j = s; j < e; ++j) {+ localMean += sortedData[j];+ }+ localMean = localMean / (e - s);++ let localSSD = 0;+ for (let j = s; j < e; ++j) {+ const diff = sortedData[j] - localMean;+ localSSD += diff * diff;+ }+ tssd += localSSD;+ }+ return gssd === 0 ? 1 : 1 - tssd / gssd;+ }++ function computeLocalSSD(idx: number, gssd: number): JenksLocalResult {+ const randomPositions = pickRandomPositions(hash(idx));+ return {+ gvf: localGvf(randomPositions, gssd),+ breakValues: randomPositions.map(i => sortedData[i])+ };+ }+}diff --git a/test/browser/components/side-panel/channel-by-value-selctor-test.js b/test/browser/components/side-panel/channel-by-value-selctor-test.jsindex ddc7d7fda..794d866d4 100644--- a/test/browser/components/side-panel/channel-by-value-selctor-test.js+++ b/test/browser/components/side-panel/channel-by-value-selctor-test.js@@ -215,12 +215,11 @@ test('Components -> ChannelByValueSelector -> ColorScaleSelector -> ColorBreakDi'Should not disabled color scale select');- // scale optons- t.equal(- wrapper.find(ColorScaleSelector).at(0).find('.list__item').length,- 4,- 'should render 4 scale options'- );+ // scale options: quantize, quantile, jenks, custom+ const scaleOptions = wrapper.find(ColorScaleSelector).at(0).find('.list__item');+ t.equal(scaleOptions.length, 5, 'should render 5 scale options');+ t.equal(scaleOptions.at(2).text(), 'Jenks Natural Breaks', '3rd scale option should be jenks');+ t.equal(scaleOptions.at(3).text(), 'Custom Breaks', '4th scale option should be custom');t.equal(wrapper.find(ColorBreaksPanel).length, 1, 'Should render 1 ColorBreaksPanel');t.equal(wrapper.find(ColorBreaksDisplay).length, 1, 'Should render 1 ColorBreaksDisplay');@@ -250,7 +249,7 @@ test('Components -> ChannelByValueSelector -> ColorScaleSelector -> ColorBreakDi}// select custom scale- wrapper.find(ColorScaleSelector).at(0).find('.list__item').at(2).simulate('click');+ wrapper.find(ColorScaleSelector).at(0).find('.list__item').at(3).simulate('click');t.ok(setColorUI.calledOnce, 'should call setColorUI');const expectedArgs = [@@ -525,7 +524,7 @@ test('Components -> ChannelByValueSelector -> ColorScaleSelector -> ColumnStatsC};const customTestCase = {- optionIndex: 2,+ optionIndex: 3,optionName: 'custom',// uses tick positions from the previous test case!expectedTickPositions: [0, 0, 1]diff --git a/test/browser/layer-tests/hexagon-layer-specs.js b/test/browser/layer-tests/hexagon-layer-specs.jsindex 775f2c838..b41d34447 100644--- a/test/browser/layer-tests/hexagon-layer-specs.js+++ b/test/browser/layer-tests/hexagon-layer-specs.js@@ -15,6 +15,7 @@ import {} from 'test/helpers/layer-utils';import {KeplerGlLayers} from '@kepler.gl/layers';+import {naturalBreaks} from '@kepler.gl/utils';const {HexagonLayer} = KeplerGlLayers;const columns = {@@ -693,3 +694,36 @@ test('#HexagonLayer -> renderHover', t => {testRenderLayerCases(t, HexagonLayer, TEST_CASES);t.end();});++test('#HexagonLayer -> updateLayerVisualChannel jenks', t => {+ const layer = new HexagonLayer({dataId: 'blue'});+ const binValues = [1, 1, 1, 50, 51, 52, 1000, 1001, 1002];+ const colors = ['#000000', '#888888', '#ffffff'];++ layer.updateLayerConfig({+ colorScale: 'jenks',+ aggregatedBins: Object.fromEntries(binValues.map((value, i) => [i, {i, value, counts: 1}])),+ visConfig: {+ ...layer.config.visConfig,+ colorRange: {+ ...layer.config.visConfig.colorRange,+ colors+ }+ }+ });++ layer.updateLayerVisualChannel({}, 'color');++ t.deepEqual(+ layer.config.colorDomain,+ naturalBreaks(binValues, colors.length),+ 'Jenks aggregation domain should recompute thresholds from bins when the palette changes'+ );+ t.notDeepEqual(+ layer.config.colorDomain,+ [1, 1002],+ 'Jenks aggregation domain should not fall back to [min, max]'+ );++ t.end();+});diff --git a/test/node/utils/aggregation-utils-test.js b/test/node/utils/aggregation-utils-test.jsnew file mode 100644index 000000000..14bca72a0--- /dev/null+++ b/test/node/utils/aggregation-utils-test.js@@ -0,0 +1,62 @@+// SPDX-License-Identifier: MIT+// Copyright contributors to the kepler.gl project++import test from 'tape';+import {enrichedRenderLayers} from '../../../src/deckgl-layers/src/layer-utils/aggregation-utils';++function ParentClass() {}+ParentClass.prototype.renderLayers = function renderLayers() {+ return 'layers';+};++function createJenksLayer(binValues, colorCount) {+ const rawColorBinValues = Float32Array.from(binValues);+ const props = {+ jenksScale: true,+ colorRange: Array.from({length: colorCount}, () => [0, 0, 0])+ };+ return {+ state: {+ colors: {},+ rawColorBinValues,+ aggregator: {binCount: rawColorBinValues.length}+ },+ getCurrentLayer: () => ({props})+ };+}++test('AggregationUtils -> enrichedRenderLayers caches Jenks breaks', t => {+ const binValues = [1, 1, 1, 50, 51, 52, 1000, 1001, 1002];+ const layer = createJenksLayer(binValues, 3);++ t.equal(enrichedRenderLayers(layer, ParentClass), 'layers', 'should call parent renderLayers');+ const firstCache = layer.state.jenksColorMapCache;+ t.ok(firstCache, 'should store a Jenks color map cache');+ t.equal(firstCache.k, 3, 'cache should record the palette size');+ t.equal(firstCache.source, layer.state.rawColorBinValues, 'cache should key off the bin array');+ t.ok(layer.state.colors.attribute, 'should classify bins on the first render');++ const classifiedAfterFirst = layer.state.colors.attribute.value;+ enrichedRenderLayers(layer, ParentClass);+ t.equal(+ layer.state.jenksColorMapCache,+ firstCache,+ 'should reuse the cached Jenks map when bins and k are unchanged'+ );+ t.notEqual(+ layer.state.colors.attribute.value,+ classifiedAfterFirst,+ 'should still reclassify bins on later renders'+ );++ layer.getCurrentLayer().props.colorRange = Array.from({length: 4}, () => [0, 0, 0]);+ enrichedRenderLayers(layer, ParentClass);+ t.notEqual(+ layer.state.jenksColorMapCache,+ firstCache,+ 'should recompute Jenks when the palette size changes'+ );+ t.equal(layer.state.jenksColorMapCache.k, 4, 'recomputed cache should use the new palette size');++ t.end();+});diff --git a/test/node/utils/data-scale-utils-test.js b/test/node/utils/data-scale-utils-test.jsindex c35c79765..51a312579 100644--- a/test/node/utils/data-scale-utils-test.js+++ b/test/node/utils/data-scale-utils-test.js@@ -10,6 +10,8 @@ import {getQuantileDomain,getLinearDomain,getLogDomain,+ getJenksDomain,+ naturalBreaks,createDataContainer,getThresholdsFromQuantiles,getDomainStepsbyZoom,@@ -19,7 +21,7 @@ import {getCategoricalColorMap} from '@kepler.gl/utils';import {StateWFilesFiltersLayerColor} from 'test/helpers/mock-state';-import {SCALE_FUNC} from '@kepler.gl/constants';+import {SCALE_FUNC, SCALE_TYPES} from '@kepler.gl/constants';function numberSort(a, b) {return a - b;@@ -122,6 +124,72 @@ test('DataScaleUtils -> getLogDomain', t => {t.end();});+test('DataScaleUtils -> naturalBreaks', t => {+ t.deepEqual(naturalBreaks([], 3), [], 'empty data should return no breaks');+ t.deepEqual(naturalBreaks([1, 2, 3], 1), [], 'k <= 1 should return no breaks');++ const clustered = [1, 1, 1, 1, 1, 1, 1, 1, 50, 51, 52, 50, 51, 1000, 1001, 1002];+ const breaks = naturalBreaks(clustered, 3);+ t.ok(breaks.length >= 2, 'should return thresholds for 3 classes');+ t.deepEqual(+ breaks,+ breaks.slice().sort((a, b) => a - b),+ 'breaks should be sorted'+ );+ t.ok(breaks[0] > 1 && breaks[0] < 1000, 'first break should split the low cluster');+ t.ok(+ breaks[breaks.length - 1] >= 50,+ 'last break should separate the high cluster from the rest'+ );+ t.deepEqual(+ naturalBreaks(clustered.slice(), 3),+ breaks,+ 'seeded permutation should be deterministic'+ );+ t.ok(+ breaks.every(b => b > clustered[0]),+ 'should not place a break at the first value'+ );++ const sequential = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];+ const sequentialBreaks = naturalBreaks(sequential, 3);+ t.equal(sequentialBreaks.length, 2, 'should return k-1 interior thresholds');+ t.ok(+ sequentialBreaks.every(b => b > 0),+ 'should not sample a break at index 0'+ );++ const padded = naturalBreaks([1, 2, 3], 5);+ t.equal(padded.length, 4, 'should pad to k-1 thresholds when k exceeds unique values');+ t.deepEqual(padded, [2, 3, 3, 3], 'padded thresholds should be the inner unique edges');++ t.end();+});++test('DataScaleUtils -> getJenksDomain', t => {+ const quanData = [1, 4, 2, 3, 1, undefined, null, 0];+ function valueAccessor(d) {+ return d.value;+ }+ const values = [{value: 1}, {value: 0}, {value: -3}, {value: 10}];++ const fromArray = getJenksDomain(quanData, undefined, 3);+ t.ok(Array.isArray(fromArray) && fromArray.length > 0, 'should compute jenks domain from array');+ t.deepEqual(+ fromArray,+ fromArray.filter(n => typeof n === 'number' && Number.isFinite(n)),+ 'jenks domain should contain only finite numbers'+ );++ const fromAccessor = getJenksDomain(values, valueAccessor, 2);+ t.ok(fromAccessor.length >= 1, 'should compute jenks domain with a value accessor');++ t.equal(SCALE_TYPES.jenks, 'jenks', 'jenks should be a registered scale type');+ t.ok(typeof SCALE_FUNC[SCALE_TYPES.jenks] === 'function', 'jenks should use a d3 scale factory');++ t.end();+});+test('DataScaleUtils -> getThresholdsFromQuantiles', t => {t.deepEqual(getThresholdsFromQuantiles([0, 1, 2, 3, 4, 5], 3),diff --git a/test/node/utils/index.js b/test/node/utils/index.jsindex 93afc3f60..ac57e683c 100644--- a/test/node/utils/index.js+++ b/test/node/utils/index.js@@ -16,6 +16,7 @@ import './mapbox-gl-style-editor-test';import './mapbox-utils-test';import './notifications-utils-test';import './aggregation-test';+import './aggregation-utils-test';import './color-util-test';import './util-test';import './export-utils-test';