@mark1russell7/highways 0.1.5 → 0.3.0

package/src/strategies/options.ts

@@ -0,0 +1,296 @@
+import type { Step, Strategy } from "./model.ts";
+
+/** The scale of a number option. A sweep on the scale `log` gives values with equal ratios, not with equal differences. */
+export type OptionScale = "linear" | "log";
+
+/** The fields of each option declaration. */
+interface OptionBase {
+  /** One short sentence that tells what the option sets. The site and the documents show it. */
+  readonly describe: string;
+}
+
+/**
+ * The declaration of a number option. The range from `min` to `max` is the range of a control and of a sweep.
+ * The strategy can take a value outside the range. `checkOptions` reports such a value, and `clampOptions` moves it into the range.
+ */
+export interface NumberOption extends OptionBase {
+  /** The type `integer` takes only whole numbers. */
+  readonly type: "number" | "integer";
+  readonly min: number;
+  readonly max: number;
+  /** The grain of a control and of a sweep. A value off the step is valid. Without it, the grain is free (or 1 for an integer). */
+  readonly step?: number;
+  /** The scale of a control and of a sweep. The default is `linear`. The scale `log` needs a `min` above 0. */
+  readonly scale?: OptionScale;
+  /** These values are valid outside the range. For example, `Infinity` sets no limit. */
+  readonly special?: readonly number[];
+  /** These values are the notable values of the option: the default and the values of the sweeps of the benchmark. */
+  readonly marks?: readonly number[];
+  /** The strategy uses this value when the caller and `defaults` give no value. */
+  readonly default?: number;
+}
+
+/** The declaration of a boolean option. */
+export interface BooleanOption extends OptionBase {
+  readonly type: "boolean";
+  /** The strategy uses this value when the caller and `defaults` give no value. */
+  readonly default?: boolean;
+}
+
+/** The declaration of an option with a fixed list of string values. */
+export interface EnumOption<V extends string = string> extends OptionBase {
+  readonly type: "enum";
+  /** The values of the option, in the order of a control. */
+  readonly values: readonly V[];
+  /** The strategy uses this value when the caller and `defaults` give no value. */
+  readonly default?: V;
+}
+
+/**
+ * The declaration of an option that a control or a sweep cannot set from a range.
+ * The type `function` is a rule, `strategy` is a strategy of the step `step`, `list` is an array and `object` is any other object.
+ */
+export interface ValueOption<V = unknown> extends OptionBase {
+  readonly type: "function" | "strategy" | "list" | "object";
+  /** The step of the strategy, for the type `strategy`. A control lists the strategies of this step of a registry. */
+  readonly step?: Step;
+  /** The strategy uses this value when the caller and `defaults` give no value. */
+  readonly default?: V;
+}
+
+/** The declaration of one option of any type. */
+export type AnyOption = NumberOption | BooleanOption | EnumOption | ValueOption;
+
+/** The declaration that fits the type of an option value: numbers, booleans, string unions or other values. */
+export type OptionDeclaration<V> = [V] extends [number] ? NumberOption : [V] extends [boolean] ? BooleanOption : [V] extends [string] ? EnumOption<V> : ValueOption<V>;
+
+/** The declarations of the options of a strategy. The schema has one declaration for each key of the options type, and no other key. */
+export type OptionSchema<O> = { readonly [K in keyof O]-?: OptionDeclaration<NonNullable<O[K]>> };
+
+/** One problem of an option value against its declaration. */
+export interface OptionIssue {
+  /** The key of the option. */
+  readonly key: string;
+  readonly value: unknown;
+  /** The kind of the problem: no declaration, the wrong type, out of the range, not a whole number or not one of the values. */
+  readonly problem: "unknown" | "type" | "range" | "integer" | "value";
+  /** One sentence that tells the problem. */
+  readonly message: string;
+}
+
+/** One setting of a sweep: a name for the rows of a table, and the options of the strategy. */
+export interface OptionSetting<O extends object> {
+  /** The key and the value of each option of the setting, for example `stretch 1.5`. */
+  readonly name: string;
+  readonly options: Partial<O>;
+}
+
+/** The options of `sweepValues`, `sweepOf` and `sweepGrid`. */
+export interface SweepOptions {
+  /**
+   * The number of values on the range of a number option. Without it, the sweep gives the `marks` of the declaration.
+   * A declaration without `marks` gets 5 values.
+   */
+  readonly count?: number;
+  /** With `true`, a sweep of a number option on the range also gives the `special` values. The default is `false`. */
+  readonly special?: boolean;
+}
+
+/** The number of values of a sweep on a range when the call and the declaration give no number. */
+const SWEEP_COUNT = 5;
+
+/** This function gives the declarations of a strategy as a record. A strategy without a schema gives an empty record. */
+function schemaOf(strategy: Strategy<Step, object>): Readonly<Record<string, AnyOption>> {
+  return (strategy.schema ?? {}) as Readonly<Record<string, AnyOption>>;
+}
+
+/** This function gives the declared options of a strategy, in the order of its schema, with the effective default of each one. */
+export function listOptions<S extends Step, O extends object>(
+  strategy: Strategy<S, O>,
+): { readonly key: keyof O & string; readonly declaration: AnyOption; readonly value: unknown }[] {
+  const defaults = optionDefaults(strategy) as Record<string, unknown>;
+  return Object.entries(schemaOf(strategy)).map(([key, declaration]) => ({ key: key as keyof O & string, declaration, value: defaults[key] }));
+}
+
+/**
+ * This function gives the effective default of each declared option: the value of `defaults`, else the `default` of the declaration.
+ * An option without either value stays out. The strategy gives the same output with this object as with no options.
+ */
+export function optionDefaults<S extends Step, O extends object>(strategy: Strategy<S, O>): Partial<O> {
+  const out: Record<string, unknown> = {};
+  const defaults = strategy.defaults as Readonly<Record<string, unknown>>;
+  for (const [key, declaration] of Object.entries(schemaOf(strategy))) {
+    if (key in defaults) out[key] = defaults[key];
+    else if (declaration.default !== undefined) out[key] = declaration.default;
+  }
+  for (const key of Object.keys(defaults)) if (!(key in out)) out[key] = defaults[key];
+  return out as Partial<O>;
+}
+
+/** This function gives `true` if the number is one of the special values of the declaration. */
+const isSpecial = (d: NumberOption, v: number): boolean => (d.special ?? []).some((s) => Object.is(s, v) || s === v);
+
+/** This function gives the problem of one value against its declaration, or `undefined` when the value fits. */
+function issueOf(key: string, value: unknown, d: AnyOption): OptionIssue | undefined {
+  const issue = (problem: OptionIssue["problem"], message: string): OptionIssue => ({ key, value, problem, message });
+  if (value === undefined) return undefined;
+  switch (d.type) {
+    case "number":
+    case "integer": {
+      if (typeof value !== "number" || Number.isNaN(value)) return issue("type", `The option "${key}" takes a number.`);
+      if (isSpecial(d, value)) return undefined;
+      if (value < d.min || value > d.max) return issue("range", `The option "${key}" is ${value}, out of the range ${d.min} to ${d.max}.`);
+      if (d.type === "integer" && !Number.isInteger(value)) return issue("integer", `The option "${key}" takes a whole number, not ${value}.`);
+      return undefined;
+    }
+    case "boolean":
+      return typeof value === "boolean" ? undefined : issue("type", `The option "${key}" takes true or false.`);
+    case "enum":
+      return d.values.includes(value as string) ? undefined : issue("value", `The option "${key}" takes ${d.values.join(", ")}, not ${String(value)}.`);
+    case "function":
+      return typeof value === "function" ? undefined : issue("type", `The option "${key}" takes a function.`);
+    case "list":
+      return Array.isArray(value) ? undefined : issue("type", `The option "${key}" takes a list.`);
+    default:
+      return typeof value === "object" && value !== null ? undefined : issue("type", `The option "${key}" takes an object.`);
+  }
+}
+
+/**
+ * This function examines option values against the schema of a strategy. It gives one issue for each key without a declaration.
+ * It also gives one issue for each value of the wrong type, out of the range, not whole or not one of the values.
+ * It changes no value.
+ * A strategy without a schema gives no issue.
+ */
+export function checkOptions<S extends Step, O extends object>(strategy: Strategy<S, O>, options: Partial<O>): OptionIssue[] {
+  if (strategy.schema === undefined) return [];
+  const schema = schemaOf(strategy);
+  const out: OptionIssue[] = [];
+  for (const [key, value] of Object.entries(options)) {
+    const d = schema[key];
+    const issue = d ? issueOf(key, value, d) : { key, value, problem: "unknown" as const, message: `The strategy "${strategy.name}" has no option "${key}".` };
+    if (issue) out.push(issue);
+  }
+  return out;
+}
+
+/**
+ * This function moves each number option into the range of its declaration, for a control. An integer option gets the nearest whole number.
+ * A special value stays. The function keeps each other value as it is. `checkOptions` reports the values that this function cannot correct.
+ */
+export function clampOptions<S extends Step, O extends object>(strategy: Strategy<S, O>, options: Partial<O>): Partial<O> {
+  const schema = schemaOf(strategy);
+  const out: Record<string, unknown> = { ...options };
+  for (const [key, value] of Object.entries(options)) {
+    const d = schema[key];
+    if (!d || (d.type !== "number" && d.type !== "integer") || typeof value !== "number" || Number.isNaN(value) || isSpecial(d, value)) continue;
+    const v = Math.min(d.max, Math.max(d.min, value));
+    out[key] = d.type === "integer" ? Math.min(d.max, Math.max(d.min, Math.round(v))) : v;
+  }
+  return out as Partial<O>;
+}
+
+/** This function gives `count` values from `min` to `max` on the scale, on the grain of the step, without repeats. */
+function rangeValues(d: NumberOption, count: number): number[] {
+  const n = Math.max(1, Math.floor(count));
+  const log = d.scale === "log" && d.min > 0;
+  const at = (t: number): number => (log ? d.min * (d.max / d.min) ** t : d.min + (d.max - d.min) * t);
+  const step = d.step ?? (d.type === "integer" ? 1 : undefined);
+  const snap = (v: number): number => {
+    const s = step === undefined ? v : d.min + Math.round((v - d.min) / step) * step;
+    const r = Number(s.toPrecision(12));
+    return Math.min(d.max, Math.max(d.min, d.type === "integer" ? Math.round(r) : r));
+  };
+  const out: number[] = [];
+  for (let i = 0; i < n; i++) {
+    const v = snap(at(n === 1 ? 0 : i / (n - 1)));
+    if (!out.includes(v)) out.push(v);
+  }
+  return out;
+}
+
+/**
+ * This function gives the values of a sweep of one option declaration.
+ * A number option gives its `marks`, or `count` values on its range and its scale. A boolean gives `false` and `true`. An enum gives its values.
+ * An option of another type has no sweep, so the function throws an error.
+ */
+export function sweepValues(declaration: AnyOption, options: SweepOptions = {}): unknown[] {
+  switch (declaration.type) {
+    case "number":
+    case "integer": {
+      if (options.count === undefined && declaration.marks !== undefined) return [...declaration.marks];
+      const values = rangeValues(declaration, options.count ?? SWEEP_COUNT);
+      return options.special ? [...values, ...(declaration.special ?? []).filter((s) => !values.includes(s))] : values;
+    }
+    case "boolean":
+      return [false, true];
+    case "enum":
+      return [...declaration.values];
+    default:
+      throw new Error(`An option of the type "${declaration.type}" has no sweep. A sweep takes a number, an integer, a boolean or an enum.`);
+  }
+}
+
+/** This function gives the declaration of one option of a strategy. When the strategy has no such declaration, the function throws an error. */
+function declarationOf(strategy: Strategy<Step, object>, key: string): AnyOption {
+  const d = schemaOf(strategy)[key];
+  if (!d) throw new Error(`The strategy "${strategy.name}" has no declaration of the option "${key}".`);
+  return d;
+}
+
+/**
+ * This function gives the settings of a sweep of one option of a strategy, from its declaration only.
+ * The name of each setting is the key and the value, for example `stretch 1.5`.
+ */
+export function sweepOf<S extends Step, O extends object>(strategy: Strategy<S, O>, key: keyof O & string, options: SweepOptions = {}): OptionSetting<O>[] {
+  return sweepValues(declarationOf(strategy, key), options).map((value) => ({ name: `${key} ${String(value)}`, options: { [key]: value } as Partial<O> }));
+}
+
+/**
+ * This function gives the settings of a grid of options: each combination of the values of the sweeps of the keys.
+ * The name of a setting joins the names of its values with commas, in the order of the keys.
+ */
+export function sweepGrid<S extends Step, O extends object>(strategy: Strategy<S, O>, keys: readonly (keyof O & string)[], options: SweepOptions = {}): OptionSetting<O>[] {
+  let out: OptionSetting<O>[] = [{ name: "", options: {} }];
+  for (const key of keys) {
+    const sweep = sweepOf(strategy, key, options);
+    out = out.flatMap((s) => sweep.map((t) => ({ name: s.name === "" ? t.name : `${s.name}, ${t.name}`, options: { ...s.options, ...t.options } })));
+  }
+  return keys.length === 0 ? [] : out;
+}
+
+/** This function gives the problems of one declaration: a bad range, a bad step, or marks and a default that do not fit. */
+function declarationIssues(key: string, d: AnyOption): string[] {
+  const out: string[] = [];
+  if (d.describe.trim().length === 0) out.push(`The option "${key}" has no description.`);
+  if (d.type === "number" || d.type === "integer") {
+    if (!Number.isFinite(d.min) || !Number.isFinite(d.max) || d.min > d.max) out.push(`The option "${key}" has the bad range ${d.min} to ${d.max}.`);
+    if (d.type === "integer" && (!Number.isInteger(d.min) || !Number.isInteger(d.max))) out.push(`The integer option "${key}" has a range that is not whole.`);
+    if (d.step !== undefined && !(d.step > 0)) out.push(`The option "${key}" has the step ${d.step}. A step is more than 0.`);
+    if (d.scale === "log" && !(d.min > 0)) out.push(`The option "${key}" has the scale log and the min ${d.min}. The scale log needs a min above 0.`);
+    for (const v of [...(d.marks ?? []), ...(d.default === undefined ? [] : [d.default])]) {
+      const issue = issueOf(key, v, d);
+      if (issue) out.push(issue.message);
+    }
+  } else if (d.type === "enum") {
+    if (d.values.length === 0) out.push(`The enum option "${key}" has no values.`);
+    if (d.default !== undefined && !d.values.includes(d.default)) out.push(`The default of the option "${key}" is not one of its values.`);
+  } else if (d.type === "boolean") {
+    if (d.default !== undefined && typeof d.default !== "boolean") out.push(`The default of the option "${key}" is not true or false.`);
+  }
+  return out;
+}
+
+/**
+ * This function examines the schema of a strategy. It gives one message for each option of `defaults` without a declaration.
+ * It also gives one message for each bad declaration, and for each value of `defaults` that does not fit its declaration.
+ * A good schema gives an empty list.
+ */
+export function checkSchema(strategy: Strategy<Step, object>): string[] {
+  const schema = schemaOf(strategy);
+  const out: string[] = [];
+  for (const key of Object.keys(strategy.defaults)) if (!(key in schema)) out.push(`The strategy "${strategy.name}" has the option "${key}" in its defaults, without a declaration.`);
+  for (const [key, d] of Object.entries(schema)) out.push(...declarationIssues(key, d).map((m) => `The strategy "${strategy.name}": ${m}`));
+  out.push(...checkOptions(strategy, strategy.defaults).filter((i) => i.problem !== "unknown").map((i) => `The strategy "${strategy.name}": ${i.message}`));
+  return out;
+}

package/src/strategies/schemas.ts

@@ -0,0 +1,221 @@
+import type { CutOptions } from "../groups/cut/index.ts";
+import type { KdOptions } from "../groups/kd/index.ts";
+import type { KeyOptions } from "../groups/keys/index.ts";
+import type { CornersOptions } from "../routers/corners.ts";
+import type { SectionsOptions } from "../routers/sections.ts";
+import type { SharedOptions } from "../routers/shared.ts";
+import type { TrunksOptions } from "../routers/trunks.ts";
+import type { SectionOptions } from "../sections.ts";
+import type { RunOrder } from "../segments.ts";
+import type { ClothoidStrategyOptions, HighwayStrategyOptions, LevelRoomPreset, RadiusOptions, RoomPreset, RouterPreset, SmoothStrategyOptions, TensionOptions } from "./builtins.ts";
+import type { EnumOption, OptionSchema } from "./options.ts";
+
+// The declarations of the options of the built-in strategies. Each `default` is the value that the function uses without the option.
+// The test of the defaults runs each strategy with `optionDefaults` and with no option, and compares the output.
+
+/** The options of the way finder (`WayOptions`), for each router that goes around the nodes. */
+const WAY_SCHEMA: OptionSchema<RouterPreset<CornersOptions>> = {
+  margin: { type: "number", min: 1, max: 20, step: 1, default: 5, describe: "The distance from a box to the corners of the graph." },
+  k: { type: "integer", min: 2, max: 16, step: 1, default: 8, describe: "The number of visible neighbours of each corner." },
+  smooth: { type: "boolean", default: false, describe: "With `true`, a way in clear view uses the inflection rule, and the other ways get round corners." },
+};
+
+/** The declaration of the lane order of the shared ways of the routers `trunks` and `shared`. */
+const LANE_ORDER: EnumOption<RunOrder> = {
+  type: "enum",
+  values: ["bundle", "run"],
+  default: "bundle",
+  describe: "With `bundle`, two edges keep one lane order on each shared way of their common stretch. With `run`, each shared way gets its order alone.",
+};
+
+/** The declaration of the lane order of the runs of the router `sections`. The default keeps the lane order of version 0.2.0. */
+const RUN_LANE_ORDER: EnumOption<RunOrder> = { ...LANE_ORDER, default: "run" };
+
+/** The declarations of the options of the routers `corners` and `corners-smooth`. */
+export const CORNERS_SCHEMA: OptionSchema<RouterPreset<CornersOptions>> = WAY_SCHEMA;
+
+/** The declarations of the options of the router `trunks`. */
+export const TRUNKS_SCHEMA: OptionSchema<RouterPreset<TrunksOptions>> = {
+  ...WAY_SCHEMA,
+  rule: { type: "function", describe: "The grouping rule. The edges from one plug with one key share a trunk." },
+  split: { type: "number", min: 0.1, max: 0.9, step: 0.05, default: 0.5, describe: "The split point is at this share of the way to the center of the targets." },
+  minSize: { type: "integer", min: 1, max: 8, step: 1, default: 2, describe: "A group with fewer edges stays unbundled." },
+  laneOrder: LANE_ORDER,
+  leave: {
+    type: "enum",
+    values: ["part", "split"],
+    default: "part",
+    describe: "With `part`, a lane leaves the trunk where its way parts from the other ways. With `split`, each lane leaves at the split point.",
+  },
+};
+
+/** The declarations of the options of the routers `shared` and `shared-all`. */
+export const SHARED_SCHEMA: OptionSchema<RouterPreset<SharedOptions>> = {
+  ...WAY_SCHEMA,
+  rule: { type: "function", describe: "The edges with one key share their ways. Without a rule, all edges share." },
+  discount: {
+    type: "number",
+    min: 0.05,
+    max: 1,
+    step: 0.05,
+    default: 0.5,
+    describe: "The cost of a link that an edge with the same key uses already, as a share of its length.",
+  },
+  laneOrder: LANE_ORDER,
+};
+
+/** The declarations of the limits of the tree of sections (`SectionOptions`). */
+export const SECTION_SCHEMA: OptionSchema<Required<SectionOptions>> = {
+  cap: { type: "integer", min: 1, max: 32, step: 1, scale: "log", marks: [4, 6, 8, 12, 16], default: 8, describe: "The section limit. A section with more nodes splits in four." },
+  maxDepth: { type: "integer", min: 1, max: 32, step: 1, default: 16, describe: "The depth limit of the tree." },
+  collapse: { type: "integer", min: 1, max: 64, step: 1, default: 32, describe: "A cell shrinks to one quarter at most this many times without a split." },
+};
+
+/** The declarations of the options of the routers `sections` and `sections-tree`. */
+export const SECTIONS_SCHEMA: OptionSchema<RouterPreset<SectionsOptions>> = {
+  ...WAY_SCHEMA,
+  ...SECTION_SCHEMA,
+  hubs: {
+    type: "integer",
+    min: 0,
+    max: 8,
+    step: 1,
+    special: [Infinity],
+    default: Infinity,
+    describe: "The number of hubs on each side of the lowest common section that a way passes. `Infinity` passes each hub.",
+  },
+  stretch: {
+    type: "number",
+    min: 1,
+    max: 4,
+    step: 0.25,
+    special: [Infinity],
+    marks: [1.25, 1.5, 2, 3, Infinity],
+    default: 2,
+    describe: "The hub limit. A way through the hubs is at most this many times the straight line. `Infinity` keeps each such way.",
+  },
+  stretchPad: { type: "number", min: 0, max: 16, step: 1, default: 4, describe: "A way through the hubs can be this many margins longer than the hub limit." },
+  hubSlack: {
+    type: "number",
+    min: 0,
+    max: 320,
+    step: 10,
+    special: [Infinity],
+    marks: [0, 40, 80, 160, Infinity],
+    default: 80,
+    describe: "A way skips a hub that is this many units farther from the target than the way was before.",
+  },
+  tightMargin: { type: "number", min: 0, max: 5, step: 0.5, default: 1, describe: "The margin of the second corner graph of the level links." },
+  plugInset: { type: "number", min: 0, max: 12, step: 1, default: 6, describe: "A plug of a level link stays this far from the corners of its side." },
+  throughCost: {
+    type: "number",
+    min: 0,
+    max: 16,
+    step: 1,
+    marks: [0, 2, 4, 8, 16],
+    default: 8,
+    describe: "The cost of a level link through a far box, in mean box sizes. The value 0 gives the links of version 0.1.5.",
+  },
+  group: { type: "strategy", step: "group", describe: "The grouping rule: a strategy of the step `group`. Without it, the router uses the quadtree." },
+  groupOptions: { type: "object", describe: "The options of the strategy `group`." },
+  levels: { type: "list", describe: "The depths of the tree that get a level with groups. Without it, each depth gets a level." },
+  laneOrder: RUN_LANE_ORDER,
+};
+
+/** The declarations of the option of the curves `rounded` and `arc`. */
+export const RADIUS_SCHEMA: OptionSchema<RadiusOptions> = {
+  radius: { type: "number", min: 0, max: 48, step: 1, describe: "The radius of the corners." },
+};
+
+/** The declarations of the options of the curve `highway`. */
+export const HIGHWAY_SCHEMA: OptionSchema<HighwayStrategyOptions> = {
+  ...RADIUS_SCHEMA,
+  minRadius: { type: "number", min: 0, max: 24, step: 1, describe: "The smallest radius of a lane at a bend of a bundle." },
+  jog: {
+    type: "enum",
+    values: ["biarc", "cubic", "quintic"],
+    default: "biarc",
+    describe: "The shape of the S curve where a lane changes its offset. A `quintic` S curve has no jump of the curvature.",
+  },
+  jogPieces: { type: "integer", min: 1, max: 8, step: 1, default: 4, describe: "The number of cubic pieces of a `quintic` S curve." },
+};
+
+/** The declarations of the options of the curve `smooth`. */
+export const SMOOTH_SCHEMA: OptionSchema<SmoothStrategyOptions> = {
+  ...RADIUS_SCHEMA,
+  smoothing: { type: "number", min: 0, max: 1, step: 0.05, describe: "The share of the turn of a corner in its two spirals. The value 0 gives the curve `arc`." },
+};
+
+/** The declarations of the options of the curve `clothoid`. */
+export const CLOTHOID_SCHEMA: OptionSchema<ClothoidStrategyOptions> = {
+  ...RADIUS_SCHEMA,
+  spiral: { type: "number", min: 0, max: 1, step: 0.05, describe: "The share of the turn of a corner in its two clothoids. The value 0 gives the curve `arc`." },
+  tolerance: { type: "number", min: 0.05, max: 1, step: 0.05, describe: "The largest distance from the cubic pieces to the true clothoid." },
+};
+
+/** The declarations of the option of the curve `spline`. */
+export const TENSION_SCHEMA: OptionSchema<TensionOptions> = {
+  tension: { type: "number", min: 0, max: 1, step: 0.05, describe: "The tension of the spline, from 0 (the spline) to 1 (the polyline)." },
+};
+
+/** The declarations of the options of the room strategies: the options of `roomDemand`, without the method. */
+export const ROOM_SCHEMA: OptionSchema<RoomPreset> = {
+  gutter: { type: "number", min: 0, max: 32, step: 1, marks: [4, 8, 12, 16], default: 8, describe: "The smallest width of each gap." },
+  spacing: { type: "number", min: 1, max: 12, step: 1, marks: [2, 4, 6, 8], default: 4, describe: "The width of one lane: the distance between two lines that run side by side." },
+  maxGrowth: {
+    type: "number",
+    min: 0,
+    max: 1,
+    step: 0.01,
+    special: [Infinity],
+    marks: [0, 0.06, 0.09, 0.12, 0.15, 0.18, 0.21, 0.25, 0.3, 0.35, 0.5, Infinity],
+    default: Infinity,
+    describe: "The largest growth of the board on each axis, as a share of its size. `Infinity` sets no limit.",
+  },
+  router: { type: "object", describe: "The router of the method `routes`. Without it, the links go as the links of a zoom level." },
+  lanes: { type: "enum", values: ["link", "count"], default: "link", describe: "With `count`, a link takes one lane for each of its edges. With `link`, a link takes one lane." },
+  snap: { type: "number", min: 0, max: 4, step: 0.25, default: 0.5, describe: "Two box edges nearer than this distance make one boundary of the sweep." },
+  passes: { type: "integer", min: 1, max: 4, step: 1, marks: [1, 2], default: 1, describe: "The number of passes of the demand. Each pass after the first finds the lanes on the open board." },
+  bends: {
+    type: "object",
+    describe: "The room for the bends of the bundles: a router that bundles, and the lane options of `highwayCurves`. Without it, the bends get no room.",
+  },
+};
+
+/** The declarations of the options of the room strategy `levels`. They are the options of the room, the levels with room and the limits of the quadtree. */
+export const LEVEL_ROOM_SCHEMA: OptionSchema<LevelRoomPreset> = {
+  ...ROOM_SCHEMA,
+  depths: { type: "list", describe: "The depths of the tree that get room. Without it, each depth with groups gets room." },
+  nodes: { type: "boolean", default: false, describe: "With `true`, the last level, with each node alone, also gets room." },
+  board: { type: "enum", values: ["shared", "each"], default: "shared", describe: "With `shared`, each level uses the board of the nearest level. With `each`, each level has its own board." },
+  ...SECTION_SCHEMA,
+};
+
+/** The declarations of the options of the grouping rule `keys`. */
+export const KEY_SCHEMA: OptionSchema<KeyOptions> = {
+  key: { type: "function", describe: "This function gives the key of the group of each node." },
+  split: { type: "object", describe: "With these limits of the quadtree, a large group splits into cells. Without them, each group is one leaf." },
+};
+
+/** The declarations of the limits of the tree of the grouping rules `kd` and `cut`. */
+const SPLIT_TREE_SCHEMA: OptionSchema<Required<Pick<KdOptions, "cap" | "maxDepth" | "fanout">>> = {
+  cap: { ...SECTION_SCHEMA.cap, describe: "The section limit. A section with more nodes splits." },
+  maxDepth: SECTION_SCHEMA.maxDepth,
+  fanout: { type: "integer", min: 2, max: 4, step: 2, default: 4, describe: "The number of children of a section. With 4, a section splits two times on one level." },
+};
+
+/** The declarations of the options of the grouping rule `kd`. */
+export const KD_SCHEMA: OptionSchema<KdOptions> = {
+  ...SPLIT_TREE_SCHEMA,
+  line: { type: "enum", values: ["median", "middle", "slide"], default: "slide", describe: "The place of the line in the cell: the median node, the middle, or the middle that slides to the nearest node." },
+  axis: { type: "enum", values: ["longer", "alternate"], default: "longer", describe: "The axis of each split: across the longer side of the cell, or x and y in turn." },
+};
+
+/** The declarations of the options of the grouping rule `cut`. */
+export const CUT_SCHEMA: OptionSchema<CutOptions> = {
+  ...SPLIT_TREE_SCHEMA,
+  balance: { type: "number", min: 0.05, max: 0.5, step: 0.05, marks: [0.1, 0.25, 0.4], default: 0.25, describe: "The smallest share of the nodes in each part of a split." },
+  objective: { type: "enum", values: ["ratio", "normalized", "sparsest"], default: "ratio", describe: "The cost of a line: the ratio cut, the normalized cut or the sparsest cut." },
+  pull: { type: "number", min: 0, max: 4, step: 0.25, marks: [0, 0.5, 1, 2, 4], default: 0.5, describe: "The cost of a line grows with its distance from the middle of the cell, by this factor." },
+  guard: { type: "boolean", default: true, describe: "With `true`, each section also tests the quadtree split, and keeps the split that cuts fewer edges." },
+};