nucleation 0.10.22 → 0.10.24

package/renderer/Palette.d.mts

@@ -0,0 +1,157 @@
+// generated by diplomat-tool
+import type { NucleationError } from "./NucleationError.mjs"
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+
+
+/**
+ * A set of colored blocks that color/gradient brushes snap their computed
+ * colors to (nearest neighbor in Oklab space). Wraps an Arc'd
+ * {@link crate::building::BlockPalette}; sharing one palette across many
+ * brushes is cheap.
+ */
+export class Palette {
+    /** @internal */
+    get ffiValue(): pointer;
+    /** @internal */
+    constructor();
+
+
+    /**
+     * Opaque building blocks and full glass blocks, for material-aware imports.
+     */
+    static materials(): Palette;
+
+    /**
+     * Keep only opaque blocks (`false`) or full glass blocks (`true`).
+     * Includes/excludes remain respected. Returns an empty palette when
+     * no suitable block exists; check `len()` before matching colours.
+     */
+    forMaterial(translucent: boolean): Palette;
+
+    /**
+     * Every block blockpedia knows a color for (the default palette
+     * brushes use when none is set).
+     */
+    static all(): Palette;
+
+    /**
+     * Only solid blocks: no transparency, gravity, tile entities, or
+     * support requirements.
+     */
+    static solid(): Palette;
+
+    /**
+     * Conservative structural set (full building blocks).
+     */
+    static structural(): Palette;
+
+    /**
+     * Decorative set: allows stairs/slabs but no tile entities.
+     */
+    static decorative(): Palette;
+
+    /**
+     * The 16 concrete colors (excludes concrete powder).
+     */
+    static concrete(): Palette;
+
+    /**
+     * The 16 wool colors.
+     */
+    static wool(): Palette;
+
+    /**
+     * Terracotta colors (excludes glazed variants).
+     */
+    static terracotta(): Palette;
+
+    /**
+     * Genuinely gray blocks: opaque full cubes whose measured color
+     * is near-neutral (low Oklab chroma) — judged from color data,
+     * not names.
+     */
+    static grayscale(): Palette;
+
+    /**
+     * The planks family — a natural light→dark wood ramp.
+     */
+    static wood(): Palette;
+
+    /**
+     * A copy of this palette with ordered dithering enabled: brushes
+     * snapping through it alternate between the two nearest blocks per
+     * voxel (4x4 Bayer threshold, deterministic in position), which
+     * reads as intermediate shades at a distance — the classic map-art
+     * trick. Ramp and list queries are unaffected.
+     */
+    dithered(): Palette;
+
+    /**
+     * A copy of this palette ordered by perceptual lightness (Oklab L,
+     * dark → light). Combined with `block_ids_json`, gives a
+     * ready-to-index ramp: `ids[i]` for intensity `i / (len - 1)`.
+     */
+    sortedByLightness(): Palette;
+
+    /**
+     * JSON array of exactly `steps` DISTINCT block ids forming the
+     * smoothest ramp this palette can make from (`r1`,`g1`,`b1`) to
+     * (`r2`,`g2`,`b2`): targets are evenly spaced along the Oklab line
+     * and blocks are chosen by a minimum-cost monotonic matching, so
+     * off-hue blocks are penalized and no block repeats. Errors with
+     * `InvalidArgument` when the palette has fewer than `steps` blocks,
+     * `steps` is 0, or start equals end.
+     */
+    rampIdsJson(r1: number, g1: number, b1: number, r2: number, g2: number, b2: number, steps: number): string;
+
+    /**
+     * JSON array of exactly `steps` block ids sampling the color
+     * gradient from (`r1`,`g1`,`b1`) to (`r2`,`g2`,`b2`) in Oklab
+     * space, each step snapped to this palette's closest block. Built
+     * for value→block lookups (heatmaps, fractals): index the returned
+     * list by `intensity * (steps - 1)`. Entries may repeat on coarse
+     * palettes; errors with `NotFound` on an empty palette.
+     */
+    gradientIdsJson(r1: number, g1: number, b1: number, r2: number, g2: number, b2: number, steps: number): string;
+
+    /**
+     * JSON array of exactly `steps` block ids sampling an Oklab gradient
+     * whose endpoints are the measured texture colors of `start_block`
+     * and `end_block`. Errors with `NotFound` when either id is unknown
+     * or has no measured color, or when this palette is empty.
+     */
+    gradientIdsBetweenBlocksJson(startBlock: string, endBlock: string, steps: number): string;
+
+    /**
+     * Custom palette from a JSON array of block ids, e.g.
+     * `["minecraft:stone", "minecraft:oak_planks"]`. Ids blockpedia has
+     * no color for are silently skipped — check `len` afterwards.
+     */
+    static fromBlockIds(idsJson: string): Palette;
+
+    /**
+     * Number of blocks in the palette.
+     */
+    len(): number;
+
+    /**
+     * The palette's block ids as a JSON array string.
+     */
+    blockIdsJson(): string;
+
+    /**
+     * Position-aware dithered snap: the block for the given RGB at
+     * voxel (x, y, z), alternating between the two nearest palette
+     * blocks per position (4x4 Bayer) — the per-pixel entry point for
+     * pixel art and image mapping. Deterministic. Errors with
+     * `NotFound` on an empty palette.
+     */
+    closestBlockDithered(r: number, g: number, b: number, x: number, y: number, z: number): string;
+
+    /**
+     * The palette block whose color is closest (Oklab distance) to the
+     * given RGB. Errors with `NotFound` on an empty palette.
+     */
+    closestBlock(r: number, g: number, b: number): string;
+}

package/renderer/Palette.d.ts

@@ -0,0 +1,157 @@
+// generated by diplomat-tool
+import type { NucleationError } from "./NucleationError.mjs"
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+
+
+/**
+ * A set of colored blocks that color/gradient brushes snap their computed
+ * colors to (nearest neighbor in Oklab space). Wraps an Arc'd
+ * {@link crate::building::BlockPalette}; sharing one palette across many
+ * brushes is cheap.
+ */
+export class Palette {
+    /** @internal */
+    get ffiValue(): pointer;
+    /** @internal */
+    constructor();
+
+
+    /**
+     * Opaque building blocks and full glass blocks, for material-aware imports.
+     */
+    static materials(): Palette;
+
+    /**
+     * Keep only opaque blocks (`false`) or full glass blocks (`true`).
+     * Includes/excludes remain respected. Returns an empty palette when
+     * no suitable block exists; check `len()` before matching colours.
+     */
+    forMaterial(translucent: boolean): Palette;
+
+    /**
+     * Every block blockpedia knows a color for (the default palette
+     * brushes use when none is set).
+     */
+    static all(): Palette;
+
+    /**
+     * Only solid blocks: no transparency, gravity, tile entities, or
+     * support requirements.
+     */
+    static solid(): Palette;
+
+    /**
+     * Conservative structural set (full building blocks).
+     */
+    static structural(): Palette;
+
+    /**
+     * Decorative set: allows stairs/slabs but no tile entities.
+     */
+    static decorative(): Palette;
+
+    /**
+     * The 16 concrete colors (excludes concrete powder).
+     */
+    static concrete(): Palette;
+
+    /**
+     * The 16 wool colors.
+     */
+    static wool(): Palette;
+
+    /**
+     * Terracotta colors (excludes glazed variants).
+     */
+    static terracotta(): Palette;
+
+    /**
+     * Genuinely gray blocks: opaque full cubes whose measured color
+     * is near-neutral (low Oklab chroma) — judged from color data,
+     * not names.
+     */
+    static grayscale(): Palette;
+
+    /**
+     * The planks family — a natural light→dark wood ramp.
+     */
+    static wood(): Palette;
+
+    /**
+     * A copy of this palette with ordered dithering enabled: brushes
+     * snapping through it alternate between the two nearest blocks per
+     * voxel (4x4 Bayer threshold, deterministic in position), which
+     * reads as intermediate shades at a distance — the classic map-art
+     * trick. Ramp and list queries are unaffected.
+     */
+    dithered(): Palette;
+
+    /**
+     * A copy of this palette ordered by perceptual lightness (Oklab L,
+     * dark → light). Combined with `block_ids_json`, gives a
+     * ready-to-index ramp: `ids[i]` for intensity `i / (len - 1)`.
+     */
+    sortedByLightness(): Palette;
+
+    /**
+     * JSON array of exactly `steps` DISTINCT block ids forming the
+     * smoothest ramp this palette can make from (`r1`,`g1`,`b1`) to
+     * (`r2`,`g2`,`b2`): targets are evenly spaced along the Oklab line
+     * and blocks are chosen by a minimum-cost monotonic matching, so
+     * off-hue blocks are penalized and no block repeats. Errors with
+     * `InvalidArgument` when the palette has fewer than `steps` blocks,
+     * `steps` is 0, or start equals end.
+     */
+    rampIdsJson(r1: number, g1: number, b1: number, r2: number, g2: number, b2: number, steps: number): string;
+
+    /**
+     * JSON array of exactly `steps` block ids sampling the color
+     * gradient from (`r1`,`g1`,`b1`) to (`r2`,`g2`,`b2`) in Oklab
+     * space, each step snapped to this palette's closest block. Built
+     * for value→block lookups (heatmaps, fractals): index the returned
+     * list by `intensity * (steps - 1)`. Entries may repeat on coarse
+     * palettes; errors with `NotFound` on an empty palette.
+     */
+    gradientIdsJson(r1: number, g1: number, b1: number, r2: number, g2: number, b2: number, steps: number): string;
+
+    /**
+     * JSON array of exactly `steps` block ids sampling an Oklab gradient
+     * whose endpoints are the measured texture colors of `start_block`
+     * and `end_block`. Errors with `NotFound` when either id is unknown
+     * or has no measured color, or when this palette is empty.
+     */
+    gradientIdsBetweenBlocksJson(startBlock: string, endBlock: string, steps: number): string;
+
+    /**
+     * Custom palette from a JSON array of block ids, e.g.
+     * `["minecraft:stone", "minecraft:oak_planks"]`. Ids blockpedia has
+     * no color for are silently skipped — check `len` afterwards.
+     */
+    static fromBlockIds(idsJson: string): Palette;
+
+    /**
+     * Number of blocks in the palette.
+     */
+    len(): number;
+
+    /**
+     * The palette's block ids as a JSON array string.
+     */
+    blockIdsJson(): string;
+
+    /**
+     * Position-aware dithered snap: the block for the given RGB at
+     * voxel (x, y, z), alternating between the two nearest palette
+     * blocks per position (4x4 Bayer) — the per-pixel entry point for
+     * pixel art and image mapping. Deterministic. Errors with
+     * `NotFound` on an empty palette.
+     */
+    closestBlockDithered(r: number, g: number, b: number, x: number, y: number, z: number): string;
+
+    /**
+     * The palette block whose color is closest (Oklab distance) to the
+     * given RGB. Errors with `NotFound` on an empty palette.
+     */
+    closestBlock(r: number, g: number, b: number): string;
+}