@graphty/graph-io 0.3.48 → 0.3.49

package/src/formats/gexf/dialog-metrics.ts

@@ -0,0 +1,61 @@
+/**
+ * The advance widths of Java's logical font "Dialog" (DejaVu Sans on the Linux JRE the Gephi oracle runs on), which
+ * Gephi measures its node labels with, in thousandths of an em: what Font.getStringBounds gives for one character with
+ * fractional metrics on (Temurin JDK 17, Font("Dialog").deriveFont(1000f).getStringBounds). No kerning
+ * ("AV" is A + V). Its line box is 1.1640625 em tall (ascent plus descent, no leading).
+ */
+
+/** The widths of U+0020 .. U+007E. */
+const ASCII = [
+    318, 401, 460, 838, 636, 950, 780, 275, 390, 390, 500, 838, 318, 361, 318, 337, 636, 636, 636, 636, 636, 636, 636,
+    636, 636, 636, 337, 337, 838, 838, 838, 531, 1000, 684, 686, 698, 770, 632, 575, 775, 752, 295, 295, 656, 557, 863,
+    748, 787, 603, 787, 695, 635, 611, 732, 684, 989, 685, 611, 685, 390, 337, 390, 838, 500, 500, 613, 635, 550, 635,
+    615, 352, 635, 634, 278, 278, 579, 278, 974, 634, 612, 635, 635, 411, 521, 392, 634, 592, 818, 592, 592, 525, 636,
+    337, 636, 838,
+];
+
+/** The widths of U+00A0 .. U+024F (Latin-1 Supplement, Latin Extended-A and -B). */
+const LATIN = [
+    318, 401, 636, 636, 636, 636, 337, 500, 500, 1000, 471, 612, 838, 361, 1000, 500, 500, 838, 401, 401, 500, 636, 636,
+    318, 500, 401, 471, 612, 969, 969, 969, 531, 684, 684, 684, 684, 684, 684, 974, 698, 632, 632, 632, 632, 295, 295,
+    295, 295, 775, 748, 787, 787, 787, 787, 787, 838, 787, 732, 732, 732, 732, 611, 605, 630, 613, 613, 613, 613, 613,
+    613, 982, 550, 615, 615, 615, 615, 278, 278, 278, 278, 612, 634, 612, 612, 612, 612, 612, 838, 612, 634, 634, 634,
+    634, 592, 635, 592, 684, 613, 684, 613, 684, 613, 698, 550, 698, 550, 698, 550, 698, 550, 770, 635, 775, 635, 632,
+    615, 632, 615, 632, 615, 632, 615, 632, 615, 775, 635, 775, 635, 775, 635, 775, 635, 752, 634, 916, 695, 295, 278,
+    295, 278, 295, 278, 295, 278, 295, 278, 590, 556, 295, 278, 656, 579, 579, 557, 278, 557, 278, 557, 375, 557, 342,
+    562, 284, 748, 634, 748, 634, 748, 634, 813, 748, 634, 787, 612, 787, 612, 787, 612, 1070, 1023, 695, 411, 695, 411,
+    695, 411, 635, 521, 635, 521, 635, 521, 635, 521, 611, 392, 611, 392, 611, 392, 732, 634, 732, 634, 732, 634, 732,
+    634, 732, 634, 732, 634, 989, 818, 611, 592, 611, 685, 525, 685, 525, 685, 525, 352, 635, 735, 686, 635, 686, 635,
+    703, 698, 550, 775, 819, 686, 635, 612, 632, 787, 614, 575, 352, 775, 687, 984, 354, 295, 746, 579, 278, 592, 974,
+    748, 634, 787, 913, 612, 949, 759, 652, 635, 695, 635, 521, 632, 336, 392, 611, 392, 611, 858, 634, 764, 721, 744,
+    730, 685, 525, 666, 666, 578, 525, 636, 666, 578, 510, 635, 295, 492, 459, 295, 1422, 1299, 1154, 835, 787, 457,
+    931, 924, 797, 684, 613, 295, 278, 787, 612, 732, 634, 732, 634, 732, 634, 732, 634, 732, 634, 615, 684, 613, 684,
+    613, 974, 982, 775, 635, 775, 635, 656, 579, 787, 612, 787, 612, 666, 578, 278, 1422, 1299, 1154, 775, 635, 1113,
+    682, 748, 634, 684, 613, 974, 982, 787, 612, 684, 613, 684, 613, 632, 615, 632, 615, 295, 278, 295, 278, 787, 612,
+    787, 612, 695, 411, 695, 411, 732, 634, 732, 634, 635, 521, 611, 392, 627, 521, 752, 634, 735, 838, 698, 610, 685,
+    525, 684, 613, 632, 615, 787, 612, 787, 612, 787, 612, 787, 612, 611, 592, 475, 843, 477, 278, 998, 998, 684, 698,
+    550, 557, 611, 521, 525, 603, 479, 686, 732, 684, 632, 615, 295, 278, 781, 635, 695, 411, 611, 592,
+];
+
+/** How tall Dialog's line box is, in ems: what getStringBounds gives as a string's height. */
+export const DIALOG_LINE_HEIGHT = 1.1640625;
+
+/**
+ * How wide Dialog draws a text, in ems.
+ * @param text - the text
+ * @returns its advance width
+ */
+export function dialogWidth(text: string): number {
+    let sum = 0;
+    for (const ch of text) {
+        const c = ch.codePointAt(0) ?? 0;
+        // ponytail: a character outside the table (CJK and other scripts Java falls back to another font for) is
+        // counted a full em; a measured table per script when a sample needs it
+        if (c >= 32 && c < 127) {
+            sum += ASCII[c - 32];
+        } else {
+            sum += c >= 160 && c < 0x250 ? LATIN[c - 160] : 1000;
+        }
+    }
+    return sum / 1000;
+}

package/src/formats/gexf/importer.ts

@@ -128,6 +128,13 @@ export interface GexfImportOptions extends CommonImportOptions {
      * @defaultValue true
      */
     viz?: boolean | undefined;
+    /**
+     * The Gephi Preview settings the file is drawn with, by Gephi's own property names and values as Gephi's
+     * Preview spells them (`{ "edge.curved": "false", "node.label.avoidOverlap": "false" }`): Gephi keeps them in its
+     * project, not in the GEXF, so a file's styles are Gephi's defaults unless they are given here. Read only when
+     * the file's styles are read; a property not given keeps Gephi's default.
+     */
+    gephiPreview?: Readonly<Record<string, string | number | boolean>> | undefined;
 }
 
 /**
@@ -641,6 +648,9 @@ class GexfReader implements XmlHandler {
     /** The text of graphty's `graphty.styles` block, read up to one character past the longest block read. */
     private styleBlock = "";
 
+    /** The `graphty.styles` block kept for the styles, or null. */
+    keptBlock: string | null = null;
+
     /** GEXF 1.0 only: nodes added for edges read before `<nodes>`, until their `<node>` declares them. */
     private readonly implicitNodes = new Map<number, NodeId>();
 
@@ -870,6 +880,7 @@ class GexfReader implements XmlHandler {
                 return;
             case Ctx.StyleBlock:
                 this.report.keepForStyles(this.styleBlock);
+                this.keptBlock = this.styleBlock;
                 this.styleBlock = "";
                 return;
             case Ctx.Graph:
@@ -2841,8 +2852,9 @@ class GexfReader implements XmlHandler {
 
     /**
      * `<viz:color r g b a hex>` as rgba in 0..1 (design section 5.5: role color, f32 x4). `hex` is read as
-     * `#rgb`, `#rgba`, `#rrggbb` or `#rrggbbaa`; a channel outside 0..255 or an alpha outside 0..1 is clamped and
-     * reported, as Gephi clamps it.
+     * Gephi reads it (Java's `Color.decode`: `canonVizColor`), and wins over `r` / `g` / `b` when both are written, as Gephi
+     * reads it (`gexf-specimen-node-fills-borders`, `color-hex-and-rgb`); a channel outside 0..255 or an alpha
+     * outside 0..1 is clamped and reported, as Gephi clamps it.
      * @param attrs - the element's attributes
      * @param name - the element name as written
      * @param where - the element's location
@@ -2851,12 +2863,12 @@ class GexfReader implements XmlHandler {
     private vizColor(attrs: ReadonlyMap<string, string>, name: string, where: IssueLocation): number[] {
         const hex = attrs.get("hex");
         let rgba: number[];
-        if (hex !== undefined && !attrs.has("r")) {
+        if (hex !== undefined) {
             const c = canonVizColor(hex);
             if (c === null) {
                 throw new GraphFormatError(
                     "E_COLUMN_TYPE",
-                    `viz hex="${hex}" is not a #RRGGBB, #RGB or #RRGGBBAA color`,
+                    `viz hex="${hex}" is not a color Gephi reads (a #-prefixed hexadecimal, 0x, octal or decimal integer)`,
                     { attribute: "hex" },
                 );
             }
@@ -3104,13 +3116,42 @@ function resolveGexfOptions(options: (GexfImportOptions & CommonImportOptions) |
     return viz;
 }
 
+/**
+ * The `gephiPreview` option, each value as text.
+ * @param options - the import options
+ * @returns the settings, or null when none are given
+ */
+function resolveGephiPreview(options: GexfImportOptions | undefined): Readonly<Record<string, string>> | null {
+    const preview = options?.gephiPreview;
+    if (preview === undefined) {
+        return null;
+    }
+    const bad = (found: unknown): never => {
+        throw new GraphFormatError("E_UNSUPPORTED", "option gephiPreview: not an object of Preview property values", {
+            option: "gephiPreview",
+            found,
+        });
+    };
+    if (typeof preview !== "object" || preview === null || Array.isArray(preview)) {
+        return bad(preview);
+    }
+    const out: Record<string, string> = {};
+    for (const [name, value] of Object.entries(preview)) {
+        if (typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") {
+            return bad(value);
+        }
+        out[name] = String(value);
+    }
+    return out;
+}
+
 /**
  * The GEXF importer.
  * @category Built-in formats
  */
 export const gexfImporter: GraphImporter<GexfImportOptions> = Object.freeze({
     format: GEXF_FORMAT,
-    options: Object.freeze(["viz"]),
+    options: Object.freeze(["viz", "gephiPreview"]),
     extensions: Object.freeze([".gexf"]),
     mimeTypes: Object.freeze(["application/gexf+xml", "application/xml", "text/xml"]),
     sniff: sniffGexf,
@@ -3156,6 +3197,10 @@ export const gexfImporter: GraphImporter<GexfImportOptions> = Object.freeze({
             throw err;
         }
         reader.finish();
+        const preview = resolveGephiPreview(options);
+        if (preview !== null) {
+            report.keepForStyles({ block: reader.keptBlock, gephiPreview: preview });
+        }
         // an abort raised during the last few elements (after the last periodic check) still rejects
         throwIfAborted(resolved.signal);
         return report.finish();

package/src/formats/gexf/preview.ts

@@ -0,0 +1,217 @@
+/**
+ * Gephi's Preview settings: what Gephi keeps in its project, not in a GEXF file, and how each one changes the
+ * drawing. Every rule here was measured on the Gephi Toolkit 0.11.3's SVG export of the GEXF specimen sheets
+ * (`graph-io/test/fidelity/specimens/gexf/pages.json`, one Preview setting per page).
+ */
+
+import type { StyleValue } from "../../styles/types.js";
+
+/**
+ * Gephi's Preview defaults as the Gephi Toolkit 0.11.3 spells them (a fresh PreviewModel), with node labels shown,
+ * as graph-io has always drawn a GEXF file.
+ */
+const GEPHI_PREVIEW: Readonly<Record<string, string>> = Object.freeze({
+    "edge.show": "true",
+    "edge.thickness": "1.0",
+    "edge.use-weight": "true",
+    "edge.rescale-weight": "false",
+    "edge.rescale-weight.min": "0.4",
+    "edge.rescale-weight.max": "8.0",
+    "edge.color": "mixed",
+    "edge.opacity": "100.0",
+    "edge.curved": "true",
+    "arrow.size": "3.0",
+    "node.border.fixed": "false",
+    "node.border.width": "1.0",
+    "node.border.color": "darker",
+    "node.opacity": "100.0",
+    "node.per.node.opacity": "false",
+    "node.label.show": "true",
+    "node.label.customFont": "false",
+    "node.label.font": "Dialog,plain,12",
+    "node.label.proportinalSize": "true",
+    "node.label.color": "#000000",
+    "node.label.shorten": "false",
+    "node.label.avoidOverlap": "true",
+    "node.label.overlapGridSize": "10",
+    "node.label.scale": "1.0",
+    "node.label.max-char": "30",
+    "node.label.outline.size": "0.0",
+    "node.label.outline.color": "#ffffff",
+    "node.label.outline.opacity": "80.0",
+    "node.label.box": "false",
+    "node.label.box.color": "parent",
+    "node.label.box.opacity": "100.0",
+    "edge.label.show": "false",
+    "edge.label.customFont": "false",
+    "edge.label.font": "Dialog,plain,10",
+    "edge.label.color": "original",
+    "edge.label.shorten": "false",
+    "edge.label.max-char": "30",
+    "edge.label.outline.size": "0.0",
+    "edge.label.outline.color": "#ffffff",
+    "edge.label.outline.opacity": "80.0",
+});
+
+/** A Java Font as Gephi's Preview writes it: `Family,style,size`. */
+export interface GephiFont {
+    readonly family: string;
+    readonly bold: boolean;
+    readonly italic: boolean;
+    readonly size: number;
+}
+
+/** The Preview settings a drawing was made with: Gephi's defaults under the ones given. */
+export class GephiPreview {
+    private readonly values: Readonly<Record<string, string>>;
+
+    /**
+     * The settings: Gephi's defaults under the ones given.
+     * @param given - the settings given, by Gephi's property names
+     */
+    constructor(given: Readonly<Record<string, string>> = {}) {
+        this.values = { ...GEPHI_PREVIEW, ...given };
+    }
+
+    /**
+     * A setting's text, trimmed and lower case.
+     * @param name - the property
+     * @returns the text
+     */
+    text(name: string): string {
+        return (this.values[name] ?? "").trim().toLowerCase();
+    }
+
+    /**
+     * A boolean setting.
+     * @param name - the property
+     * @returns its value
+     */
+    on(name: string): boolean {
+        return this.text(name) === "true";
+    }
+
+    /**
+     * A number setting; Gephi's default where the text is not a number.
+     * @param name - the property
+     * @returns its value
+     */
+    num(name: string): number {
+        const v = Number(this.text(name));
+        return Number.isFinite(v) ? v : Number(GEPHI_PREVIEW[name] ?? 0);
+    }
+
+    /**
+     * The font of node or edge labels: the given font when `<target>.label.customFont` is on, else Gephi's.
+     * @param target - "node" or "edge"
+     * @returns the font
+     */
+    font(target: "node" | "edge"): GephiFont {
+        const name = `${target}.label.font`;
+        const raw = this.on(`${target}.label.customFont`) ? (this.values[name] ?? "") : (GEPHI_PREVIEW[name] ?? "");
+        const [family = "Dialog", style = "plain", size = ""] = raw.split(",").map((s) => s.trim());
+        const s = style.toLowerCase();
+        const pt = Number(size);
+        const fallback = target === "node" ? 12 : 10;
+        return {
+            family,
+            bold: s.includes("bold"),
+            italic: s.includes("italic"),
+            size: Number.isFinite(pt) && pt > 0 ? pt : fallback,
+        };
+    }
+}
+
+/**
+ * A label as Gephi's shorten setting cuts it: only a label of at least max-char + 3 characters, to its first max-char
+ * characters and "..." (`gexf-specimen-labels-p7`, `-p8`).
+ * @param label - the label
+ * @param max - max-char
+ * @returns the label drawn
+ */
+function shortened(label: string, max: number): string {
+    return label.length >= max + 3 ? `${label.slice(0, max)}...` : label;
+}
+
+/**
+ * A color derived from another as Gephi's DependantColor modes derive it: `darker` halves each channel, `lighter`
+ * raises each by half (to 255 at most), `parent` (and `original`) is the color itself, `#rrggbb` is that color.
+ * @param mode - the mode, lower case
+ * @param parent - the color it derives from, r, g and b 0..255
+ * @returns the color as r, g and b, or null for a mode Gephi does not have
+ */
+export function dependantColor(mode: string, parent: readonly number[]): number[] | null {
+    switch (mode) {
+        case "darker":
+            return parent.slice(0, 3).map((v) => Math.floor(v / 2));
+        case "lighter":
+            return parent.slice(0, 3).map((v) => Math.min(255, Math.floor(v * 1.5)));
+        case "parent":
+        case "original":
+            return parent.slice(0, 3);
+        default: {
+            const m = /^#([0-9a-f]{6})$/.exec(mode);
+            if (m === null) {
+                return null;
+            }
+            const n = Number.parseInt(m[1], 16);
+            return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
+        }
+    }
+}
+
+/**
+ * The labels drawn: none when `<target>.label.show` is off, each cut when `<target>.label.shorten` is on, and, unless
+ * the file keeps its own values, with its line breaks left out, as Java's `drawString` draws a label on one line with
+ * nothing for a break ("line one\nline two" is drawn "line oneline two": Gephi Toolkit 0.11.3's preview and PNG
+ * export, `gexf-specimen-labels`).
+ * @param labels - each element's label, or undefined when none has one
+ * @param preview - the settings
+ * @param target - "node" or "edge"
+ * @param kept - whether the file keeps its own values (a `graphty.styles` block): its line breaks are drawn
+ * @returns the labels drawn, or undefined for none
+ */
+export function drawnLabels(
+    labels: readonly (StyleValue | null)[] | undefined,
+    preview: GephiPreview,
+    target: "node" | "edge",
+    kept = false,
+): (StyleValue | null)[] | undefined {
+    if (labels === undefined || !preview.on(`${target}.label.show`)) {
+        return undefined;
+    }
+    const max = preview.on(`${target}.label.shorten`) ? preview.num(`${target}.label.max-char`) : Infinity;
+    const drawn = (l: string): string => (kept ? l : l.replaceAll(/[\r\n]/g, ""));
+    return labels.map((l) => (typeof l === "string" ? drawn(shortened(l, max)) : l));
+}
+
+/**
+ * Each edge's weight as Gephi draws its thickness: with `edge.use-weight` off, `edge.thickness`; else the weight,
+ * rescaled linearly from the smallest and largest drawn weights to `edge.rescale-weight.min` .. `.max` when
+ * `edge.rescale-weight` is on, times `edge.thickness` (`gexf-specimen-edges-lines-p8` .. `-p11`).
+ * @param weights - each edge's weight
+ * @param drawn - whether each edge is drawn
+ * @param preview - the settings
+ * @returns each edge's thickness
+ */
+export function edgeThickness(weights: readonly number[], drawn: readonly boolean[], preview: GephiPreview): number[] {
+    const thickness = preview.num("edge.thickness");
+    if (!preview.on("edge.use-weight")) {
+        return weights.map(() => thickness);
+    }
+    if (!preview.on("edge.rescale-weight")) {
+        return weights.map((w) => w * thickness);
+    }
+    // loops, not Math.min(...): a spread of every edge overflows the call stack on a large graph
+    let lo = Infinity;
+    let hi = -Infinity;
+    weights.forEach((w, e) => {
+        if (drawn[e]) {
+            lo = Math.min(lo, w);
+            hi = Math.max(hi, w);
+        }
+    });
+    const min = preview.num("edge.rescale-weight.min");
+    const max = preview.num("edge.rescale-weight.max");
+    return weights.map((w) => (hi > lo ? min + ((w - lo) / (hi - lo)) * (max - min) : min) * thickness);
+}

package/src/formats/gexf/schema.ts

@@ -195,7 +195,8 @@ export const NODE_DECLS: Readonly<Record<keyof typeof NODE_COLUMNS, ColumnDecl>>
         mutable: true,
         nullable: true,
         origin: VIZ_ORIGIN,
-        extra: { units: "file" },
+        // Gephi puts a node with no viz:position at the origin (gexf-specimen-node-sizes-opacity: position-none)
+        extra: { units: "file", originUnplaced: true },
     },
     color: {
         name: NODE_COLUMNS.color,