Support divergent color ramps #912

nakul-py · 2025-08-29T14:37:31Z

Description

Currently, Color Ramp Type only supports Divergent colors such as balance, delta , curl, diff and tarn so other colormaps are still show type unknown. Enable users to set a minimum and maximum value for the colormap.

Screencast.From.2025-09-02.17-35-03.mp4

Checklist

PR has a descriptive title and content.
PR description contains references to any issues the PR resolves, e.g. Resolves #XXX.
PR has one of the labels: documentation, bug, enhancement, feature, maintenance
Checks are passing.
Failing lint checks can be resolved with:
- pre-commit run --all-files
- jlpm run lint

📚 Documentation preview: https://jupytergis--912.org.readthedocs.build/en/912/
💡 JupyterLite preview: https://jupytergis--912.org.readthedocs.build/en/912/lite

github-actions · 2025-08-29T14:37:40Z

👈 Launch a Binder on branch nakul-py/jupytergis/divergent

github-actions · 2025-08-29T14:49:11Z

Integration tests report: appsharing.space

nakul-py

cmocean's "balance" is cool :)

nakul-py · 2025-09-02T12:18:58Z

packages/base/src/dialogs/symbology/colorRampUtils.ts

+> = {
+  balance: {
+    name: 'balance',
+    type: 'Divergent',
+    colors: [],
+    criticalValue: 0,
+  },
+  delta: {
+    name: 'delta',
+    type: 'Divergent',
+    colors: [],
+    criticalValue: 0,
+  },
+  curl: {
+    name: 'curl',
+    type: 'Divergent',
+    colors: [],
+    criticalValue: 0,
+  },
+  diff: {
+    name: 'diff',
+    type: 'Divergent',
+    colors: [],
+    criticalValue: 0,
+  },
+  tarn: {
+    name: 'tarn',
+    type: 'Divergent',
+    colors: [],
+    criticalValue: 0,
+  },


@mfisher87 I think balance and the other four are also divergent?

That is true!

mfisher87

Hey Nakul! This looks really good so far! I have some thoughts on the implementation details, most importantly around saving the min & max into the project file as symbologyState.min, symbologyState.max and updating singleband pseudocolor (for raster data) to share the same behavior. We can definitely share a common component!

mfisher87 · 2025-09-03T15:13:58Z

packages/base/src/dialogs/symbology/colorRampUtils.ts

+    if (COLOR_RAMP_DEFINITIONS[name]) {
+      COLOR_RAMP_DEFINITIONS[name].colors = colorRamp;
+    }
+


Suggested change

if (COLOR_RAMP_DEFINITIONS[name]) {

COLOR_RAMP_DEFINITIONS[name].colors = colorRamp;

}

Instead of having a new data structure for color ramp information, what do you think about using getColorMapList to generate all the information needed in its return value? And updating the COLOR_MAP_NAMES data structure to include all the information aside from the colors (I think COLOR_RAMP_DEFINITIONS is a great name for that data structure, so let's combine them under that name?). E.g.:

// `Object.keys()` always returns `string[]`, but sometimes we need a narrower type, ideally without assertion or repetition. // This should live in `tools.ts` with the similar `objectEntries` function. const objectKeys = Object.keys as <T extends Record<string, any>>(obj: T) => Array<keyof T>; // This should probably live in types.ts? type ColorRampType = "sequential" | "divergent"; interface BaseColorMapDefinition { type: ColorRampType; } interface SequentialColorRampDefinition extends BaseColorMapDefinition { type: "sequential"; } interface DivergentColorRampDefinition extends BaseColorMapDefinition { type: "divergent"; /** * Where in the colorramp the divergence occurs * @example 0.5 */ criticalValue: number; } type ColorRampDefinition = SequentialColorRampDefinition | DivergentColorRampDefinition const COLOR_RAMP_DEFINITIONS = { viridis: {type: "sequential"}, // ... balance: {type: "divergent", criticalValue: 0.5}, // 0.5 indicates that the colormap's critical value is in the exact middle // ... } as const satisfies {[key: string]: ColorRampDefinition}; const COLOR_RAMP_NAMES = objectKeys(COLOR_RAMP_DEFINITIONS); type ColorRampName = typeof COLOR_RAMP_NAMES[number]; export interface IColorMap { name: ColorRampName; colors: string[]; definition: ColorRampDefinition; } // example return value of `getColorMapList` const colorMaps: Array<IColorMap> = [ {name: "viridis", colors: [/* ... */], definition: {type: "sequential"}}, {name: "balance", colors: [/* ... */], definition: {type: "divergent", criticalValue: 0.5}} ];

mfisher87 · 2025-09-03T15:14:48Z

packages/base/src/dialogs/symbology/components/color_ramp/ColorRamp.tsx

+import {
+  COLOR_RAMP_DEFINITIONS,
+  ColorRampName,
+} from '../../../symbology/colorRampUtils';


Suggested change

} from '../../../symbology/colorRampUtils';

} from '@src/dialogs/symbology/colorRampUtils';

Long chains of ../ can be hard to read :)

mfisher87 · 2025-09-03T15:16:59Z

packages/base/src/dialogs/symbology/components/color_ramp/ColorRamp.tsx

  ) => void;
  showModeRow: boolean;
  showRampSelector: boolean;
+  layerType?: 'graduated' | 'categorized';


mfisher87 · 2025-09-03T15:28:40Z

packages/base/src/dialogs/symbology/components/color_ramp/ColorRamp.tsx

  };

+  const rampDef = COLOR_RAMP_DEFINITIONS[selectedRamp as ColorRampName];
+  const rampType = rampDef?.type || 'Unknown';


This shows "unknown" most of the time, but the suggestion above to COLOR_RAMP_DEFINITIONS should fix that. I suggest including the color ramp type in the dropdown instead of outside the dropdown. E.g. in the dropdown it would say "Viridis (sequential)".

mfisher87 · 2025-09-03T15:33:34Z

packages/base/src/dialogs/symbology/components/color_ramp/ColorRamp.tsx

+
+          <div className="jp-gis-symbology-row">
+            <label htmlFor="critical-value">Critical Value:</label>
+            <input


Critical value shouldn't be an input -- instead it should be calculated as the colorRampDefinition.criticalValue (0.5 with the divergent colormaps we're using) point between min and max so the user knows where the divergence point will lie. Changing this value manually should have no effect on the classification (and currently doesn't).

mfisher87 · 2025-09-03T15:36:37Z

packages/base/src/dialogs/symbology/components/color_ramp/ColorRamp.tsx

@@ -76,6 +106,64 @@ const ColorRamp: React.FC<IColorRampProps> = ({
          setSelectedMode={setSelectedMode}
        />
      )}
+      {/* 🔹 Divergent colormap controls */}
+      {layerType === 'graduated' && rampType === 'Divergent' && (


Let's support setting the minimum and maximum in the same way for singleband pseudocolor, too, and regardless of whether the color ramp type is divergent or sequential. We only need to display the critical value for divergent color ramps, though.

Right now singleband psuedocolor already has a setting for min and max, and the choice saves the values into the project file under the sources key (sources[id][parameters][url][0][min|max]. But this is really a symbology setting, not an attribute of the source data. We should be saving that information at layers[id][parameters][symbologyState][min|max] for all render types that support a color ramp except heatmap, i.e. graduated, categorized, singleband. We'll also need to update the geotiff add layer dialog to save this information in the correct place!

We should extract the min/max/critical value fields (though critical value should not be editable) into a separate component so we can share it between the graduated and singleband components! The props for that extracted component can be min, setMin, max, setMax, and colorRampDefinition... I don't think we need any others but I could be missing something ;)

mfisher87 · 2025-09-03T15:48:04Z

packages/base/src/dialogs/symbology/vector_layer/types/Categorized.tsx

When classifying in the radius tab, the min and max fields are shown, but the classify button ignores their values. We should be able to specify the classification range there as well.

For Graduated?

Yeah, graduated render type in the radius tab!

mfisher87 · 2025-09-03T15:49:26Z

packages/base/src/dialogs/symbology/symbologyUtils.ts

@@ -104,7 +105,35 @@ export namespace Utils {
    selectedRamp: string,
    nClasses: number,
    reverse = false,
+    layerType: 'categorized' | 'graduated' = 'graduated',


Suggested change

layerType: 'categorized' | 'graduated' = 'graduated',

renderType: 'categorized' | 'graduated' = 'graduated',

mfisher87 · 2025-09-03T15:57:55Z

packages/base/src/dialogs/symbology/components/color_ramp/ColorRamp.tsx

 }) => {
  const [selectedRamp, setSelectedRamp] = useState('');
  const [selectedMode, setSelectedMode] = useState('');
  const [numberOfShades, setNumberOfShades] = useState('');
+  const [criticalValue, setCriticalValue] = useState<number | undefined>(0);
+  const [minValue, setMinValue] = useState<number | undefined>(-5);


Let's not set an arbitrary default. We should either leave it blank or use the min/max from the actual data.

I think we have two options:

Leave them blank and offer a button ("Set to data min & max"? "Fill from data"? "Detect range"? "Use actual range"?) which populates the values from the actual data. This will mean the dialog will load faster and the user will control when the data is read.

Pre-populate them with the values from the actual data. This will mean the dialog loads more slowly.

The "classify" button should be greyed out unless min & max are populated. Then the classify button will always use the min & max and won't have to calculate them.

What do you think?

mfisher87 · 2025-09-03T16:07:55Z

packages/base/src/panelview/components/legendItem.tsx

+          {/* Labels below bar */}
+          <div
+            style={{ fontSize: '0.75em', color: '#555', fontWeight: 'bold' }}
+          >
+            {minValue !== undefined && <div>Min: {minValue.toFixed(2)}</div>}
+            {maxValue !== undefined && <div>Max: {maxValue.toFixed(2)}</div>}
+            {isDivergent && criticalValue !== undefined && (
+              <div style={{ color: '#555', fontWeight: 'bold' }}>
+                Critical: {criticalValue.toFixed(2)}
+              </div>
+            )}


The bar communicates all this information already, I don't think we need the additional labels :)

Suggested change

{/* Labels below bar */}

<div

style={{ fontSize: '0.75em', color: '#555', fontWeight: 'bold' }}

>

{minValue !== undefined && <div>Min: {minValue.toFixed(2)}</div>}

{maxValue !== undefined && <div>Max: {maxValue.toFixed(2)}</div>}

{isDivergent && criticalValue !== undefined && (

<div style={{ color: '#555', fontWeight: 'bold' }}>

Critical: {criticalValue.toFixed(2)}

</div>

)}

Supporting divergent colomaps

78e9966

nakul-py added 2 commits August 29, 2025 20:48

critical value only for divergent

63bcb15

Divergent with min-max

e9ecb40

nakul-py changed the title ~~Wip: Supporting divergent colomaps with critical value~~ Supporting divergent colomaps with critical value Sep 2, 2025

nakul-py marked this pull request as ready for review September 2, 2025 12:16

nakul-py commented Sep 2, 2025

View reviewed changes

mfisher87 added the enhancement New feature or request label Sep 3, 2025

mfisher87 requested changes Sep 3, 2025

View reviewed changes

mfisher87 changed the title ~~Supporting divergent colomaps with critical value~~ Support divergent color ramps Sep 3, 2025

mfisher87 reviewed Sep 3, 2025

View reviewed changes

mfisher87 requested a review from arjxn-py September 3, 2025 16:13

	if (COLOR_RAMP_DEFINITIONS[name]) {
	COLOR_RAMP_DEFINITIONS[name].colors = colorRamp;
	}

	} from '../../../symbology/colorRampUtils';
	} from '@src/dialogs/symbology/colorRampUtils';

	layerType?: 'graduated' \| 'categorized';
	renderType?: 'graduated' \| 'categorized';

	layerType: 'categorized' \| 'graduated' = 'graduated',
	renderType: 'categorized' \| 'graduated' = 'graduated',

Support divergent color ramps #912

Are you sure you want to change the base?

Support divergent color ramps #912

Uh oh!

Conversation

nakul-py commented Aug 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Uh oh!

github-actions bot commented Aug 29, 2025

Uh oh!

github-actions bot commented Aug 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nakul-py left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mfisher87 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mfisher87 Sep 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mfisher87 Sep 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mfisher87 Sep 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

nakul-py commented Aug 29, 2025 •

edited

Loading

github-actions bot commented Aug 29, 2025 •

edited

Loading

nakul-py left a comment •

edited

Loading

mfisher87 left a comment •

edited

Loading

mfisher87 Sep 3, 2025 •

edited

Loading

mfisher87 Sep 3, 2025 •

edited

Loading

mfisher87 Sep 3, 2025 •

edited

Loading