matterviz 0.4.0 → 0.4.2

package/dist/settings.d.ts

@@ -1,9 +1,10 @@
 import type { ColorScaleType, D3InterpolateName } from './colors';
 import type { HullFaceColorMode } from './convex-hull/types';
 import type { D3SymbolName } from './labels';
-import type { Vec3 } from './math';
+import type { Vec2, Vec3 } from './math';
 import type { BandwidthOption, Orientation, SankeyNodeAlign, SankeyOrientation, SunburstLabelRotation, SunburstLabelText, SunburstShape, SunburstValueMode, ViolinKind, ViolinSide, WhiskerMode } from './plot';
 import type { BondingStrategy } from './structure/bonding';
+import type { PolyhedraColorMode } from './structure/polyhedra';
 export interface SettingType<T = unknown> {
     value: T;
     description: string;
@@ -110,6 +111,15 @@ type ConvexHullWith3DType = ConvexHullCommonType & {
     hull_face_opacity: SettingType<number>;
     hull_face_color_mode: SettingType<HullFaceColorMode>;
 };
+type HierarchyChartSettingsSchema = {
+    value_mode: SettingType<SunburstValueMode>;
+    max_depth: SettingType<number>;
+    min_fraction: SettingType<number>;
+    show_labels: SettingType<boolean>;
+    label_text: SettingType<SunburstLabelText>;
+    zoom_on_click: SettingType<boolean>;
+    show_breadcrumbs: SettingType<boolean>;
+};
 export interface SettingsConfig {
     color_scheme: SettingType<string>;
     background_color: SettingType<string>;
@@ -130,6 +140,17 @@ export interface SettingsConfig {
         show_bonds: SettingType<ShowBonds>;
         bond_color: SettingType<string>;
         bonding_strategy: SettingType<BondingStrategy>;
+        show_polyhedra: SettingType<ShowBonds>;
+        polyhedra_opacity: SettingType<number>;
+        polyhedra_show_edges: SettingType<boolean>;
+        polyhedra_edge_color: SettingType<string>;
+        polyhedra_color_mode: SettingType<PolyhedraColorMode>;
+        polyhedra_color: SettingType<string>;
+        polyhedra_hide_center_atoms: SettingType<boolean>;
+        polyhedra_min_neighbors: SettingType<number>;
+        polyhedra_max_neighbors: SettingType<number>;
+        polyhedra_excluded_elements: SettingType<readonly string[]>;
+        polyhedra_included_elements: SettingType<readonly string[]>;
         atom_color_mode: SettingType<AtomColorMode>;
         atom_color_scale: SettingType<D3InterpolateName>;
         atom_color_scale_type: SettingType<ColorScaleType>;
@@ -179,7 +200,7 @@ export interface SettingsConfig {
     trajectory: {
         auto_play: SettingType<boolean>;
         fps: SettingType<number>;
-        fps_range: SettingType<[number, number]>;
+        fps_range: SettingType<Vec2>;
         display_mode: SettingType<`structure+scatter` | `structure` | `scatter` | `histogram` | `structure+histogram`>;
         show_controls: SettingType<boolean>;
         fullscreen_toggle: SettingType<boolean>;
@@ -277,18 +298,16 @@ export interface SettingsConfig {
         show_node_labels: SettingType<boolean>;
         iterations: SettingType<number>;
     };
-    sunburst: {
+    sunburst: HierarchyChartSettingsSchema & {
         shape: SettingType<SunburstShape>;
-        value_mode: SettingType<SunburstValueMode>;
-        max_depth: SettingType<number>;
         inner_radius: SettingType<number>;
         pad_angle: SettingType<number>;
-        min_fraction: SettingType<number>;
-        show_labels: SettingType<boolean>;
         label_rotation: SettingType<SunburstLabelRotation>;
-        label_text: SettingType<SunburstLabelText>;
-        zoom_on_click: SettingType<boolean>;
-        show_breadcrumbs: SettingType<boolean>;
+    };
+    treemap: HierarchyChartSettingsSchema & {
+        padding_inner: SettingType<number>;
+        padding_top: SettingType<number>;
+        padding_outer: SettingType<number>;
     };
     composition: {
         display_mode: SettingType<`pie` | `bubble` | `bar`>;
@@ -315,5 +334,8 @@ export type DefaultSettings = {
     } : never;
 };
 export declare const DEFAULTS: DefaultSettings;
-export declare const merge: (user?: Partial<DefaultSettings>) => DefaultSettings;
+export type PartialSettings = {
+    [Key in keyof DefaultSettings]?: DefaultSettings[Key] extends Record<string, unknown> ? Partial<DefaultSettings[Key]> : DefaultSettings[Key];
+};
+export declare const merge: (user?: PartialSettings) => DefaultSettings;
 export {};

package/dist/settings.js

@@ -3,6 +3,8 @@
 import { symbol_names } from './labels';
 import { merge_nested } from './utils';
 export const SHOW_BONDS_OPTIONS = [`never`, `always`, `crystals`, `molecules`];
+// Shared enum labels for never|always|crystals|molecules settings (bonds, polyhedra)
+const SHOW_BONDS_ENUM = Object.fromEntries(SHOW_BONDS_OPTIONS.map((key) => [key, key[0].toUpperCase() + key.slice(1)]));
 export const VECTOR_COLOR_MODES = [
     `auto`,
     `element`,
@@ -38,6 +40,49 @@ const DISPLAY_CONFIG = {
         description: `Show Y-axis zero reference line`,
     },
 };
+// Settings shared by the sunburst + treemap sections below so the two charts'
+// options can't drift; `node` names the chart's visual unit (arc/cell) and
+// `levels` its depth unit (rings/levels) in descriptions.
+const hierarchy_chart_settings = (node, levels, zoom_desc) => ({
+    value_mode: {
+        value: `leaf-sum`,
+        description: `How node values are interpreted (plotly branchvalues semantics): leaf-sum ignores parent values, total treats every value as authoritative, remainder adds a node's own value on top of its children`,
+        enum: { 'leaf-sum': `Leaf sum`, total: `Total`, remainder: `Remainder` },
+    },
+    max_depth: {
+        value: 0,
+        description: `Number of ${levels} shown below the current zoom root (0 = all)`,
+        minimum: 0,
+        maximum: 10,
+    },
+    min_fraction: {
+        value: 0,
+        description: `Group sibling ${node}s smaller than this fraction of the total into one 'Other' ${node === `arc` ? `slice` : `cell`} per parent (0 = off)`,
+        minimum: 0,
+        maximum: 0.2,
+    },
+    show_labels: {
+        value: true,
+        description: `Show labels on ${node}s large enough to fit them`,
+    },
+    label_text: {
+        value: `label`,
+        description: `What ${node} labels display (percent is of the root total, parent-percent of the parent node)`,
+        enum: {
+            label: `Label`,
+            value: `Value`,
+            percent: `Percent`,
+            'label+value': `Label + value`,
+            'label+percent': `Label + percent`,
+            'label+parent-percent': `Label + % of parent`,
+        },
+    },
+    zoom_on_click: { value: true, description: zoom_desc },
+    show_breadcrumbs: {
+        value: true,
+        description: `Show a clickable ${node === `arc` ? `trail` : `pathbar`} of ancestors when zoomed into a subtree`,
+    },
+});
 // Complete settings configuration with values, descriptions, and constraints
 export const SETTINGS_CONFIG = {
     // General display settings
@@ -122,7 +167,7 @@ export const SETTINGS_CONFIG = {
         show_bonds: {
             value: `always`,
             description: `When to display bonds between atoms`,
-            enum: Object.fromEntries(SHOW_BONDS_OPTIONS.map((key) => [key, key[0].toUpperCase() + key.slice(1)])),
+            enum: SHOW_BONDS_ENUM,
         },
         bond_color: {
             value: `#666666`,
@@ -136,6 +181,62 @@ export const SETTINGS_CONFIG = {
                 solid_angle: `Solid Angle`,
             },
         },
+        show_polyhedra: {
+            value: `crystals`,
+            description: `When to render coordination polyhedra around cation-like centers`,
+            enum: SHOW_BONDS_ENUM,
+        },
+        polyhedra_opacity: {
+            value: 0.2,
+            description: `Opacity of coordination polyhedra faces`,
+            minimum: 0,
+            maximum: 1,
+        },
+        polyhedra_show_edges: {
+            value: true,
+            description: `Draw outlines along coordination polyhedra edges`,
+        },
+        polyhedra_edge_color: {
+            value: `#222222`,
+            description: `Color of coordination polyhedra edge lines`,
+        },
+        polyhedra_color_mode: {
+            value: `vertex`,
+            description: `Color polyhedra by the atoms at their corners, the center atom, or a single custom color`,
+            enum: {
+                vertex: `Vertex Atoms`,
+                center: `Center Atom`,
+                uniform: `Custom Color`,
+            },
+        },
+        polyhedra_color: {
+            value: `#4a90d9`,
+            description: `Custom polyhedra color (used when color mode is Custom Color)`,
+        },
+        polyhedra_hide_center_atoms: {
+            value: false,
+            description: `Hide the central atom of each rendered polyhedron`,
+        },
+        polyhedra_min_neighbors: {
+            value: 4,
+            description: `Minimum number of bonded neighbors (coordination number) to form a polyhedron`,
+            minimum: 4, // hulls of <4 points are degenerate and render nothing
+            maximum: 12,
+        },
+        polyhedra_max_neighbors: {
+            value: 8,
+            description: `Maximum number of bonded neighbors for a polyhedron (skips e.g. CN-12 cuboctahedra around large A-site cations)`,
+            minimum: 4,
+            maximum: 16,
+        },
+        polyhedra_excluded_elements: {
+            value: [],
+            description: `Elements excluded from acting as polyhedra centers`,
+        },
+        polyhedra_included_elements: {
+            value: [],
+            description: `Elements always allowed as polyhedra centers (overrides automatic hiding of spectator cations like alkali metals and the max neighbors cap)`,
+        },
         atom_color_mode: {
             value: `element`,
             description: `Property to use for atom coloring`,
@@ -289,7 +390,7 @@ export const SETTINGS_CONFIG = {
             description: `Per-key configuration for site vector layers. Keys map to site property names (e.g. force, magmom, force_DFT). Auto-populated when a structure with vector data loads.`,
         },
         vector_scale: {
-            value: 1.0,
+            value: 0.75,
             description: `Scale factor for site vector arrows`,
             minimum: 0.1,
             maximum: 10.0,
@@ -311,8 +412,8 @@ export const SETTINGS_CONFIG = {
             description: `Show all arrows at the same length (direction only). Useful for spin/magmom visualization where orientation matters but magnitude does not.`,
         },
         vector_uniform_thickness: {
-            value: false,
-            description: `Use the same shaft and head size for all arrows regardless of length. When off (default), thickness scales with arrow length.`,
+            value: true,
+            description: `Use the same shaft and head size for all arrows regardless of length. Negative radii are scaled by characteristic atom spacing.`,
         },
         vector_origin_gap: {
             value: 0,
@@ -321,20 +422,20 @@ export const SETTINGS_CONFIG = {
             maximum: 0.5,
         },
         vector_shaft_radius: {
-            value: -0.03,
-            description: `Radius of vector shaft (negative = relative to length, positive = absolute)`,
+            value: -0.01,
+            description: `Radius of vector shaft (negative = relative to length or atom spacing with uniform thickness, positive = absolute)`,
             minimum: -0.1,
             maximum: 0.1,
         },
         vector_arrow_head_radius: {
-            value: -0.06,
-            description: `Radius of vector arrow head (negative = relative to length, positive = absolute)`,
+            value: -0.04,
+            description: `Radius of vector arrow head (negative = relative to length or atom spacing with uniform thickness, positive = absolute)`,
             minimum: -0.2,
             maximum: 0.2,
         },
         vector_arrow_head_length: {
-            value: -0.15,
-            description: `Length of vector arrow head (negative = relative to length, positive = absolute)`,
+            value: -0.1,
+            description: `Length of vector arrow head (negative = relative to length or atom spacing with uniform thickness, positive = absolute)`,
             minimum: -0.5,
             maximum: 0.5,
         },
@@ -693,7 +794,7 @@ export const SETTINGS_CONFIG = {
                 maximum: 5,
             },
             stroke_color: {
-                value: `#000000`,
+                value: `var(--text-color, black)`, // theme-responsive like axis/grid colors
                 description: `Box outline color`,
             },
             border_radius: {
@@ -711,7 +812,7 @@ export const SETTINGS_CONFIG = {
                 maximum: 5,
             },
             color: {
-                value: `#000000`,
+                value: `var(--text-color, black)`, // theme-responsive like axis/grid colors
                 description: `Whisker line color`,
             },
             cap_fraction: {
@@ -729,7 +830,7 @@ export const SETTINGS_CONFIG = {
                 maximum: 6,
             },
             color: {
-                value: `#000000`,
+                value: `var(--text-color, black)`, // theme-responsive like axis/grid colors
                 description: `Median line color`,
             },
         },
@@ -812,22 +913,12 @@ export const SETTINGS_CONFIG = {
     },
     // Sunburst chart specific
     sunburst: {
+        ...hierarchy_chart_settings(`arc`, `rings`, `Clicking a branch arc zooms into that subtree (center circle zooms out)`),
         shape: {
             value: `sunburst`,
             description: `Chart geometry: polar rings (sunburst) or stacked rows (icicle)`,
             enum: { sunburst: `Sunburst`, icicle: `Icicle` },
         },
-        value_mode: {
-            value: `leaf-sum`,
-            description: `How node values are interpreted (plotly branchvalues semantics): leaf-sum ignores parent values, total treats every value as authoritative, remainder adds a node's own value on top of its children`,
-            enum: { 'leaf-sum': `Leaf sum`, total: `Total`, remainder: `Remainder` },
-        },
-        max_depth: {
-            value: 0,
-            description: `Number of rings shown below the current zoom root (0 = all)`,
-            minimum: 0,
-            maximum: 10,
-        },
         inner_radius: {
             value: 0.25,
             description: `Center hole size as fraction of the outer radius`,
@@ -840,16 +931,6 @@ export const SETTINGS_CONFIG = {
             minimum: 0,
             maximum: 4,
         },
-        min_fraction: {
-            value: 0,
-            description: `Group sibling arcs smaller than this fraction of the total into one 'Other' slice per parent (0 = off)`,
-            minimum: 0,
-            maximum: 0.2,
-        },
-        show_labels: {
-            value: true,
-            description: `Show labels on arcs large enough to fit them`,
-        },
         label_rotation: {
             value: `auto`,
             description: `Arc label orientation (auto picks radial/tangential per arc)`,
@@ -860,24 +941,27 @@ export const SETTINGS_CONFIG = {
                 horizontal: `Horizontal`,
             },
         },
-        label_text: {
-            value: `label`,
-            description: `What arc labels display (percent is of the root total)`,
-            enum: {
-                label: `Label`,
-                value: `Value`,
-                percent: `Percent`,
-                'label+value': `Label + value`,
-                'label+percent': `Label + percent`,
-            },
+    },
+    // Treemap chart specific
+    treemap: {
+        ...hierarchy_chart_settings(`cell`, `levels`, `Clicking any cell zooms into it, plotly-style (the breadcrumb pathbar zooms out)`),
+        padding_inner: {
+            value: 0,
+            description: `Pixel gap between sibling cells (0 = cells share a single stroke divider; gaps > 0 show the parent's fill)`,
+            minimum: 0,
+            maximum: 10,
         },
-        zoom_on_click: {
-            value: true,
-            description: `Clicking a branch arc zooms into that subtree (center circle zooms out)`,
+        padding_top: {
+            value: 18,
+            description: `Pixel strip reserved at the top of branch cells for their label (0 = no headers)`,
+            minimum: 0,
+            maximum: 40,
         },
-        show_breadcrumbs: {
-            value: true,
-            description: `Show a clickable trail of ancestors when zoomed into a subtree`,
+        padding_outer: {
+            value: 3,
+            description: `Pixel inset of child cells within their parent's left/right/bottom edges, so parents visibly enclose their subtree (plotly marker.pad)`,
+            minimum: 0,
+            maximum: 10,
         },
     },
     // Composition specific
@@ -926,7 +1010,7 @@ export const SETTINGS_CONFIG = {
         display: DISPLAY_CONFIG,
         point: {
             size: {
-                value: 4,
+                value: 3,
                 description: `Point size for scatter plots`,
                 minimum: 1,
                 maximum: 20,
@@ -1390,5 +1474,6 @@ export const merge = (user) => ({
     box: merge_nested(DEFAULTS.box, user?.box),
     sankey: merge_nested(DEFAULTS.sankey, user?.sankey),
     sunburst: merge_nested(DEFAULTS.sunburst, user?.sunburst),
+    treemap: merge_nested(DEFAULTS.treemap, user?.treemap),
     convex_hull: merge_nested(DEFAULTS.convex_hull, user?.convex_hull),
 });