@graphty/graph-io 0.3.43 → 0.3.44

package/src/formats/xgmml/styles.ts

@@ -0,0 +1,400 @@
+/**
+ * The styles of XGMML files and Cytoscape 2.x session networks: Cytoscape writes every element's RESOLVED visual
+ * properties into its `<graphics>` (XML attributes in the old spelling, nested `<att>` elements named for the visual
+ * property, and the locked ones under `lockedVisualProperties`), and no style. The reader turns those values into
+ * the neutral vocabulary; the planner explains them. The writer does the reverse from what graphty draws.
+ */
+
+import type { GraphSnapshot } from "@graphty/graph-format";
+
+import { STYLE_ISSUE } from "../../styles/codes.js";
+import {
+    type CytoscapeDialect,
+    cytoscapeElementProperties,
+    cytoscapeWritableProperties,
+} from "../../styles/cytoscape/emit.js";
+import { normalizeVisualProperties } from "../../styles/cytoscape/lexicon.js";
+import { emptyCytoscapeStyle } from "../../styles/cytoscape/mappings.js";
+import { cytoscapeBackground, type CytoscapeBypass, resolveCytoscapeBypasses } from "../../styles/cytoscape/resolve.js";
+import { blockStyles, parseStyleBlock, STYLE_BLOCK_NAME } from "../../styles/io/block.js";
+import type { ExporterStyleInput } from "../../styles/io/writer.js";
+import { StyleNotes } from "../../styles/notes.js";
+import { styleFingerprint } from "../../styles/plan/features.js";
+import { plainCell, resolveStyles } from "../../styles/plan/resolve.js";
+import type {
+    EdgeStyleProperty,
+    GraphStyle,
+    ImporterStyles,
+    NodeStyleProperty,
+    ReaderOutput,
+    StyleColumn,
+    StyleProperty,
+    StyleReadContext,
+    StyleTarget,
+    StyleTool,
+    StyleValue,
+    StyleWriteCapabilities,
+} from "../../styles/types.js";
+import type { LossNote } from "../../types.js";
+import { lossOf } from "../cx/styles.js";
+import { GRAPHICS_COLUMN, XGMML_ORIGIN_NAMESPACE } from "./constants.js";
+
+type Table = GraphSnapshot["nodes"];
+
+/**
+ * The name of a table's graphics column: the json column the XGMML reader keeps `<graphics>` in.
+ * @param table - the node, edge or graph table
+ * @returns the column's name, or null
+ */
+function graphicsColumnOf(table: Table): string | null {
+    for (const col of table) {
+        const { origin } = col.meta;
+        if (col.dtype === "json" && origin?.type === "graphics" && origin.namespace === XGMML_ORIGIN_NAMESPACE) {
+            return col.meta.name;
+        }
+    }
+    return table.get(GRAPHICS_COLUMN)?.dtype === "json" ? GRAPHICS_COLUMN : null;
+}
+
+/**
+ * Each element's visual properties from its graphics: the graphics values normalized to visual property names, the
+ * locked ones (`lockedVisualProperties`, a session view's bypasses) on top.
+ * @param table - the node or edge table
+ * @param target - nodes or edges
+ * @param n - the element count
+ * @param notes - where too-deep nesting is noted
+ * @returns per element, its visual properties (null without graphics)
+ */
+export function graphicsBypasses(table: Table, target: StyleTarget, n: number, notes: StyleNotes): CytoscapeBypass[] {
+    const out = new Array<CytoscapeBypass>(n).fill(null);
+    const name = graphicsColumnOf(table);
+    if (name === null) {
+        return out;
+    }
+    for (let i = 0; i < n; i++) {
+        const g = plainCell(table.value(name, i));
+        if (g === null || typeof g !== "object" || Array.isArray(g)) {
+            continue;
+        }
+        const map = normalizeVisualProperties(target, g, notes);
+        const locked = Object.hasOwn(g, "lockedVisualProperties")
+            ? (g as Record<string, unknown>).lockedVisualProperties
+            : undefined;
+        if (locked !== null && typeof locked === "object") {
+            for (const [k, v] of normalizeVisualProperties(target, locked, notes)) {
+                map.set(k, v);
+            }
+        }
+        out[i] = map.size > 0 ? map : null;
+    }
+    return out;
+}
+
+/** What the XGMML style reader is told by its caller. */
+interface XgmmlStyleSettings {
+    /** Whose defaults fill what the file leaves unset. */
+    readonly tool: StyleTool;
+    /** A bool column marking hidden elements (a Cytoscape 2.x session's hidden state), or null. */
+    readonly hiddenColumn?: string | null;
+}
+
+/**
+ * The styles of a graph whose elements carry Cytoscape's resolved visual properties in their graphics.
+ * @param snapshot - the graph
+ * @param context - the budget and cancel signal
+ * @param settings - the tool and the hidden-state column
+ * @returns the styles (canonical values, no declared rules)
+ */
+export function readXgmmlStyles(
+    snapshot: GraphSnapshot,
+    context: StyleReadContext,
+    settings: XgmmlStyleSettings,
+): ImporterStyles {
+    const notes = new StyleNotes();
+    const out: Record<StyleTarget, ReaderOutput> = { node: { values: {} }, edge: { values: {} } };
+    for (const target of ["node", "edge"] as const) {
+        context.signal?.throwIfAborted();
+        const table = target === "node" ? snapshot.nodes : snapshot.edges;
+        const n = target === "node" ? snapshot.nodeCount : snapshot.edgeCount;
+        const maps = graphicsBypasses(table, target, n, notes);
+        const values = maps.some((m) => m !== null)
+            ? resolveCytoscapeBypasses(target, maps, { notes, budget: context.budget })
+            : {};
+        hiddenToVisible(table, settings.hiddenColumn ?? null, n, values);
+        exactFromBlock(snapshot, target, values);
+        out[target] = { values: nonEmpty(values) };
+    }
+    return {
+        canonical: true,
+        dialect: "cytoscape",
+        tool: settings.tool,
+        units: "px",
+        node: out.node,
+        edge: out.edge,
+        graph: graphStyleOf(snapshot, notes),
+        notes: notes.list(),
+    };
+}
+
+/**
+ * The styles of an XGMML file: its elements' resolved values, with Cytoscape desktop's default style beneath.
+ * @param snapshot - the graph
+ * @param context - the budget and cancel signal
+ * @returns the styles
+ */
+export function readXgmmlFileStyles(snapshot: GraphSnapshot, context: StyleReadContext): ImporterStyles {
+    return readXgmmlStyles(snapshot, context, { tool: "cytoscape" });
+}
+
+/**
+ * For a file graphty wrote: where an element's value is what the writer's nearest Cytoscape value of the
+ * `graphty.styles` block's value reads back as (a font family list written as its first family, a shape Cytoscape
+ * does not have), the block's exact value is the truth, so a re-import gives the same rules. A value that differs
+ * from what graphty wrote (another program edited it) stays the truth.
+ * @param snapshot - the graph
+ * @param target - nodes or edges
+ * @param values - the values per property, changed in place
+ * @param dialect - the Cytoscape dialect the file's values are written in
+ */
+export function exactFromBlock(
+    snapshot: GraphSnapshot,
+    target: StyleTarget,
+    values: Partial<Record<string, StyleColumn>>,
+    dialect: CytoscapeDialect = "desktop",
+): void {
+    const text = snapshot.graph.has(STYLE_BLOCK_NAME) ? plainCell(snapshot.graph.value(STYLE_BLOCK_NAME, 0)) : null;
+    if (typeof text !== "string") {
+        return;
+    }
+    const parsed = parseStyleBlock(text, styleFingerprint(snapshot));
+    const ex = parsed.ok ? blockStyles(parsed.block, snapshot, "xgmml") : null;
+    if (ex === null) {
+        return;
+    }
+    const n = target === "node" ? snapshot.nodeCount : snapshot.edgeCount;
+    const want = new Map<string, readonly (StyleValue | null)[]>();
+    const exact = (property: string): readonly (StyleValue | null)[] => {
+        let held = want.get(property);
+        if (held === undefined) {
+            held = resolveStyles(ex, target, property as StyleProperty, snapshot);
+            want.set(property, held);
+        }
+        return held;
+    };
+    // What each element's exact values are written as, read back the way the file is read.
+    const written = Array.from({ length: n }, (_v, i) =>
+        cytoscapeElementProperties(
+            target,
+            (property) => exact(property)[i] ?? null,
+            dialect,
+            () => undefined,
+        ),
+    );
+    const readBack = resolveCytoscapeBypasses(target, written, { notes: new StyleNotes() });
+    for (const [property, native] of Object.entries(values)) {
+        const back = readBack[property];
+        if (native !== undefined && back !== undefined) {
+            values[property] = withBlockValues(native, back, exact(property));
+        }
+    }
+}
+
+/**
+ * A property's values with the block's exact value wherever the file's value is what the writer wrote for it.
+ * @param native - the file's values
+ * @param back - what the writer wrote for the block's values, read back
+ * @param w - the block's values
+ * @returns the values, the file's own array when none changes
+ */
+function withBlockValues(
+    native: StyleColumn,
+    back: readonly (StyleValue | null)[],
+    w: readonly (StyleValue | null)[],
+): StyleColumn {
+    let changed: (StyleValue | null)[] | null = null;
+    for (let i = 0; i < native.length; i++) {
+        if (w[i] !== null && native[i] !== w[i] && native[i] === back[i]) {
+            changed ??= [...native];
+            changed[i] = w[i];
+        }
+    }
+    return changed ?? native;
+}
+
+/**
+ * Marks the elements a hidden-state column holds true as not visible.
+ * @param table - the node or edge table
+ * @param column - the bool column, or null
+ * @param n - the element count
+ * @param values - the values per property, changed in place
+ */
+export function hiddenToVisible(
+    table: Table,
+    column: string | null,
+    n: number,
+    values: Partial<Record<string, StyleColumn>>,
+): void {
+    if (column === null || !table.has(column)) {
+        return;
+    }
+    let visible: (StyleValue | null)[] | null = null;
+    for (let i = 0; i < n; i++) {
+        if (plainCell(table.value(column, i)) === true) {
+            visible ??= values.visible === undefined ? new Array<StyleValue | null>(n).fill(null) : [...values.visible];
+            visible[i] = false;
+        }
+    }
+    if (visible !== null) {
+        values.visible = visible;
+    }
+}
+
+/**
+ * The properties with at least one value.
+ * @param values - per property, each element's value
+ * @returns the same without all-null properties
+ */
+export function nonEmpty(values: Partial<Record<string, StyleColumn>>): Partial<Record<StyleProperty, StyleColumn>> {
+    const out: Partial<Record<string, StyleColumn>> = {};
+    for (const [p, col] of Object.entries(values)) {
+        if (col?.some((v) => v !== null) === true) {
+            out[p] = col;
+        }
+    }
+    return out;
+}
+
+/**
+ * The graph's background from its own graphics (`NETWORK_BACKGROUND_PAINT`).
+ * @param snapshot - the graph
+ * @param notes - where a bad value is noted
+ * @returns the graph style
+ */
+function graphStyleOf(snapshot: GraphSnapshot, notes: StyleNotes): GraphStyle {
+    const name = graphicsColumnOf(snapshot.graph);
+    const g = name === null ? null : plainCell(snapshot.graph.value(name, 0));
+    if (g === null || typeof g !== "object") {
+        return {};
+    }
+    const style = emptyCytoscapeStyle();
+    for (const [k, v] of normalizeVisualProperties("node", g, notes)) {
+        if (k.startsWith("NETWORK_")) {
+            style.network.defaults.set(k, v);
+        }
+    }
+    const background = cytoscapeBackground(style, notes);
+    return background === null ? {} : { background };
+}
+
+// ------------------------------------------------------------------ writing
+
+/**
+ * What the XGMML writer holds natively: every visual property Cytoscape keeps per element, and the graph's
+ * background. The block and the tagged values go into graph and element `<att>`s.
+ */
+export const XGMML_STYLE_CAPABILITIES: StyleWriteCapabilities = Object.freeze({
+    node: Object.freeze(cytoscapeWritableProperties("node", "desktop") as NodeStyleProperty[]),
+    edge: Object.freeze(cytoscapeWritableProperties("edge", "desktop") as EdgeStyleProperty[]),
+    graph: Object.freeze(["background"] as const),
+    block: "attributes",
+});
+
+/** The visual properties Cytoscape also writes as `<graphics>` XML attributes, in its old spelling. */
+const XML_ATTRIBUTES: Readonly<Record<StyleTarget, readonly (readonly [vp: string, attribute: string])[]>> = {
+    node: [
+        ["NODE_SHAPE", "type"],
+        ["NODE_HEIGHT", "h"],
+        ["NODE_WIDTH", "w"],
+        ["NODE_FILL_COLOR", "fill"],
+        ["NODE_BORDER_WIDTH", "width"],
+        ["NODE_BORDER_PAINT", "outline"],
+    ],
+    edge: [
+        ["EDGE_WIDTH", "width"],
+        ["EDGE_STROKE_UNSELECTED_PAINT", "fill"],
+    ],
+};
+
+/**
+ * One element's graphics record for a file written with styles: what graphty draws as Cytoscape visual properties,
+ * the six classic ones also as XML attributes (the importer reads both alike), over the kept graphics' visual
+ * properties no neutral property carries (custom graphics, label widths) and edge bends.
+ * @param target - nodes or edges
+ * @param styles - the exporter's style input
+ * @param i - the element index
+ * @param kept - the element's kept graphics record, or null
+ * @returns the record, or null when there is nothing to write
+ */
+export function styledGraphics(
+    target: StyleTarget,
+    styles: ExporterStyleInput,
+    i: number,
+    kept: Record<string, unknown> | null,
+): Record<string, unknown> | null {
+    const vps = cytoscapeElementProperties(
+        target,
+        (p) => styles.picture(target, p as StyleProperty)[i] ?? null,
+        "desktop",
+        () => undefined,
+    );
+    const out: Record<string, unknown> = {};
+    for (const [vp, attribute] of XML_ATTRIBUTES[target]) {
+        if (vps.has(vp)) {
+            out[attribute] = String(vps.get(vp));
+        }
+    }
+    for (const [k, v] of Object.entries(kept ?? {})) {
+        // a kept visual property the picture does not write, or the edge's bends; old-spelling and nested keys
+        // would be read before the picture's values and contradict them
+        if (k === "Line" || (/^[A-Z][A-Z_0-9]+$/.test(k) && !vps.has(k))) {
+            out[k] = v;
+        }
+    }
+    for (const [vp, v] of vps) {
+        out[vp] = String(v);
+    }
+    return Object.keys(out).length === 0 ? null : out;
+}
+
+/**
+ * What writing every element's graphics with styles loses: each value written as the nearest one Cytoscape allows,
+ * counted per element.
+ * @param styles - the exporter's style input
+ * @param snapshot - the graph
+ * @returns the loss notes
+ */
+export function styledGraphicsNotes(styles: ExporterStyleInput, snapshot: GraphSnapshot): LossNote[] {
+    const notes = new StyleNotes();
+    for (const target of ["node", "edge"] as const) {
+        const n = target === "node" ? snapshot.nodeCount : snapshot.edgeCount;
+        for (let i = 0; i < n; i++) {
+            cytoscapeElementProperties(
+                target,
+                (p) => styles.picture(target, p as StyleProperty)[i] ?? null,
+                "desktop",
+                (p) => {
+                    notes.add(STYLE_ISSUE.APPROXIMATED, target, p, { element: i });
+                },
+            );
+        }
+    }
+    return notes.list().map(lossOf);
+}
+
+/**
+ * The graph's graphics record for a file written with styles: the kept record with the background replaced.
+ * @param styles - the exporter's style input
+ * @param kept - the kept graph graphics, or null
+ * @returns the record, or null
+ */
+export function styledGraphGraphics(
+    styles: ExporterStyleInput,
+    kept: Record<string, unknown> | null,
+): Record<string, unknown> | null {
+    const { background } = styles.rules.styles.graph;
+    const out: Record<string, unknown> = { ...kept };
+    if (background !== undefined) {
+        out.NETWORK_BACKGROUND_PAINT = background.toUpperCase();
+    }
+    return Object.keys(out).length === 0 ? null : out;
+}

package/src/index.ts

@@ -139,6 +139,8 @@ export {
 export {
     DOT_ISSUE,
     DOT_LOSS,
+    DOT_STYLE_BLOCK_ATTRIBUTE,
+    DOT_STYLE_CAPABILITIES,
     dotExporter,
     type DotExportOptions,
     dotImporter,
@@ -148,15 +150,19 @@ export {
     GEXF_1_2_CAPABILITIES,
     GEXF_ISSUE,
     GEXF_LOSS,
+    GEXF_STYLE_CAPABILITIES,
     gexfExporter,
     type GexfExportOptions,
     gexfImporter,
     type GexfImportOptions,
     type GexfVersion,
+    GRAPHTY_XML_NAMESPACE,
 } from "./formats/gexf/index.js";
 export {
     GML_ISSUE,
     GML_LOSS,
+    GML_STYLE_BLOCK_KEY,
+    GML_STYLE_CAPABILITIES,
     gmlExporter,
     type GmlExportOptions,
     gmlImporter,
@@ -165,6 +171,7 @@ export {
 export {
     GRAPHML_ISSUE,
     GRAPHML_LOSS,
+    GRAPHML_STYLE_CAPABILITIES,
     graphmlExporter,
     type GraphmlExportOptions,
     graphmlImporter,
@@ -212,6 +219,8 @@ export {
 export {
     PAJEK_ISSUE,
     PAJEK_LOSS,
+    PAJEK_STYLE_CAPABILITIES,
+    PAJEK_STYLE_COMMENT,
     pajekExporter,
     type PajekExportOptions,
     pajekImporter,
@@ -304,6 +313,7 @@ export {
     ImportReportBuilder,
     isAbortError,
     type IssueLocation,
+    keptForStyles,
     type MutableCounts,
     PARSE_ERROR_CODE,
 } from "./common/report.js";
@@ -333,10 +343,16 @@ export {
 } from "./common/writer.js";
 export {
     hasIllegalXmlChar,
+    MAX_XML_DEPTH,
     tokenizeXml,
     type XmlHandler,
     xmlIllegalTextNotes,
+    XmlNestingError,
     type XmlRepairs,
     XmlSyntaxError,
     XmlTokenizer,
 } from "./common/xml.js";
+
+// ============================================================ styles through the importer and exporter contracts
+export type { StyleImportOptions } from "./styles/io/generic.js";
+export type { ExporterStyleInput, ExporterStyleOptions } from "./styles/io/writer.js";

package/src/positions/codes.ts

@@ -0,0 +1,32 @@
+/**
+ * The note codes of `extractPositions()`. Singular `W_POSITION_*` codes are about some nodes,
+ * plural `W_POSITIONS_*` codes about the file as a whole. Keys drop the `W_` and `POSITION_` /
+ * `POSITIONS_` prefixes.
+ */
+
+/**
+ * Every code a `PositionNote` carries.
+ * @category Positions
+ */
+export const POSITION_ISSUE = Object.freeze({
+    /** Every placed node sits on one point; the coordinates are dropped and `usable` is false. */
+    STACKED: "W_POSITION_STACKED",
+    /** Some nodes have no position. */
+    PARTIAL: "W_POSITION_PARTIAL",
+    /** Some coordinates are not finite numbers; those nodes count as unplaced. */
+    NON_FINITE: "W_POSITION_NON_FINITE",
+    /** The file mixes 2- and 3-coordinate positions. */
+    DIMS_MIXED: "W_POSITION_DIMS_MIXED",
+    /** A top-left coordinate has no width or height, so it was not moved to the center. */
+    ANCHOR_NO_SIZE: "W_POSITION_ANCHOR_NO_SIZE",
+    /** The file holds more than one view (layout); only the first is used. */
+    OTHER_VIEWS: "W_POSITION_OTHER_VIEWS",
+    /** The file has position-like columns this format does not read (plain `x` / `y`). */
+    NOT_READ: "W_POSITIONS_NOT_READ",
+} as const);
+
+/**
+ * A code of `POSITION_ISSUE`.
+ * @category Positions
+ */
+export type PositionNoteCode = (typeof POSITION_ISSUE)[keyof typeof POSITION_ISSUE];

package/src/positions/convert.ts

@@ -0,0 +1,123 @@
+/**
+ * The coordinate conversions between a file's spelling and the neutral convention (center, y up):
+ * the y flip, the top-left anchor shift, and `toFilePositions()`, the inverse a writer uses. Format
+ * modules import from here, so they never pull in the reader.
+ */
+
+import type { PositionColumnExtra } from "./types.js";
+
+/**
+ * A y that grows downward as one that grows upward, and back: a negation that never yields -0.
+ * @param y - the coordinate
+ * @returns the flipped coordinate
+ * @category Positions
+ */
+export function flipY(y: number): number {
+    return y === 0 ? 0 : -y;
+}
+
+/**
+ * One coordinate from a file's spelling into the neutral convention, in place.
+ * @param p - x, y, z as the file wrote them; becomes the node's center, y up
+ * @param extra - how the file spells it
+ * @param size - the node's width and height, for a top-left anchor; null when unknown
+ * @param realZ - whether the file has a z that differs between nodes
+ */
+export function toNeutral(
+    p: [number, number, number],
+    extra: PositionColumnExtra,
+    size: readonly [number, number] | null,
+    realZ: boolean,
+): void {
+    if (extra.anchor === "top-left" && size !== null) {
+        p[0] += size[0] / 2;
+        p[1] += extra.yAxis === "down" ? size[1] / 2 : -size[1] / 2;
+    }
+    p[2] = realZ ? p[2] - (extra.zOrigin ?? 0) : 0;
+    if (extra.yAxis === "down") {
+        // with a real z this turns the drawing 180 degrees about x, so a 3D shape is never mirrored
+        p[1] = flipY(p[1]);
+        p[2] = flipY(p[2]);
+    }
+}
+
+/**
+ * Neutral coordinates (center, y up, as `extractPositions()` returns them) back into a column
+ * spelled as `extra` declares, for a writer: the y flip, Pajek's z origin and yEd's top-left corner
+ * are undone. Rows that are NaN stay NaN.
+ * @param coords - x, y, z per node
+ * @param extra - the spelling of the column to write
+ * @param sizes - each node's width and height, needed for a top-left anchor
+ * @param sizes.width - widths by node index
+ * @param sizes.height - heights by node index
+ * @returns a new array, x, y, z per node in the file's spelling
+ * @category Positions
+ */
+export function toFilePositions(
+    coords: Float64Array,
+    extra: PositionColumnExtra,
+    sizes?: { width: Float64Array; height: Float64Array },
+): Float64Array {
+    const out = new Float64Array(coords.length);
+    const down = extra.yAxis === "down";
+    for (let i = 0; i < coords.length; i += 3) {
+        let y = coords[i + 1];
+        let z = coords[i + 2];
+        if (down) {
+            y = flipY(y);
+            z = flipY(z);
+        }
+        out[i] = coords[i];
+        out[i + 1] = y;
+        out[i + 2] = z === 0 && extra.sourceDims !== 3 ? 0 : z + (extra.zOrigin ?? 0);
+        const row = i / 3;
+        if (extra.anchor === "top-left" && sizes !== undefined) {
+            out[i] -= sizes.width[row] / 2;
+            out[i + 1] -= down ? sizes.height[row] / 2 : -sizes.height[row] / 2;
+        }
+    }
+    return out;
+}
+
+/**
+ * The median of some numbers.
+ * @param values - the numbers, reordered in place
+ * @returns the median, or null for none
+ * @category Positions
+ */
+export function median(values: number[]): number | null {
+    if (values.length === 0) {
+        return null;
+    }
+    values.sort((a, b) => a - b);
+    const mid = values.length >> 1;
+    return values.length % 2 === 1 ? values[mid] : (values[mid - 1] + values[mid]) / 2;
+}
+
+/**
+ * How each built-in writer that writes the position column as it stands spells a coordinate:
+ * GML (y down, as yEd draws it) and Pajek (y down, z centered on 0.5). Every other built-in writer
+ * either converts the neutral form itself (JSON, XGMML, CX, CX2, Cytoscape sessions, yEd graphics
+ * in a styled GraphML) or writes a y-up format (GEXF, DOT).
+ */
+const WRITTEN_SPELLING: Readonly<Record<string, PositionColumnExtra>> = {
+    gml: { yAxis: "down" },
+    pajek: { yAxis: "down", zOrigin: 0.5 },
+};
+
+/**
+ * Neutral coordinates (center, y up) as a built-in format's writer expects its position column, so
+ * a graph whose positions are in the neutral form is written the way up its program draws it.
+ * @example
+ * ```ts
+ * const column = writtenPositions("gml", coords); // y flipped for GML
+ * ```
+ * @param format - the format being written
+ * @param coords - x, y, z per node; NaN for a node with no position
+ * @returns the coordinates to write (the same array when the format needs no conversion)
+ * @category Positions
+ */
+export function writtenPositions(format: string, coords: Float64Array): Float64Array {
+    const spelling = WRITTEN_SPELLING[format];
+    return spelling === undefined ? coords : toFilePositions(coords, spelling);
+}