@azphalt/importer-cube 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Az
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+/** CLI for `@azphalt/importer-cube`: wrap a `.cube` LUT into a `.azp` package. */
+import { readFileSync, writeFileSync } from "node:fs";
+import { basename, extname } from "node:path";
+import { importCube } from "./index.js";
+const USAGE = "usage: azphalt-import-cube <input.cube> --id <reverse.dns.id> " +
+    "[-o out.azp] [--name N] [--version V] [--license SPDX] [--license-file PATH] [--author A]";
+function parse(argv) {
+    const a = {};
+    for (let i = 0; i < argv.length; i++) {
+        const t = argv[i];
+        switch (t) {
+            case "-o":
+            case "--out":
+                a.out = argv[++i];
+                break;
+            case "--id":
+                a.id = argv[++i];
+                break;
+            case "--name":
+                a.name = argv[++i];
+                break;
+            case "--version":
+                a.version = argv[++i];
+                break;
+            case "--license":
+                a.license = argv[++i];
+                break;
+            case "--license-file":
+                a.licenseFile = argv[++i];
+                break;
+            case "--author":
+                a.author = argv[++i];
+                break;
+            default:
+                if (!t.startsWith("-") && !a.input)
+                    a.input = t;
+                else
+                    fail(`unknown argument: ${t}`);
+        }
+    }
+    return a;
+}
+function fail(msg) {
+    console.error(`error: ${msg}`);
+    console.error(USAGE);
+    process.exit(2);
+}
+const args = parse(process.argv.slice(2));
+if (!args.input)
+    fail("an input .cube file is required");
+if (!args.id)
+    fail("--id <reverse-DNS id> is required (e.g. com.hereliesaz.teal-fade)");
+const cubeText = readFileSync(args.input, "utf8");
+let licenseText;
+if (args.licenseFile) {
+    licenseText = readFileSync(args.licenseFile, "utf8");
+}
+else {
+    const spdx = args.license ?? "MIT";
+    licenseText = `${spdx}\n\nProvide the full license text with --license-file.\n`;
+    console.error(`warning: no --license-file; writing a placeholder LICENSE (SPDX: ${spdx}).`);
+}
+const out = args.out ?? basename(args.input, extname(args.input)) + ".azp";
+const { azp, manifest } = importCube(cubeText, licenseText, {
+    id: args.id,
+    name: args.name,
+    version: args.version,
+    license: args.license,
+    author: args.author,
+});
+writeFileSync(out, azp);
+console.error(`wrote ${out}  (${manifest.id} v${manifest.version}, ${azp.length} bytes)`);

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `@azphalt/importer-cube` — normalize a `.cube` LUT into a `.azp` asset package.
+ * `.cube` is already the portable color-transform interchange, so normalization is
+ * 1:1: validate/parse for metadata, store the original bytes, and wrap them in a
+ * manifest. See RATIONALE § 1.3.
+ */
+import { type WriteResult } from "@azphalt/azp";
+import { type CubeLut } from "./parse-cube.js";
+export interface ImportOptions {
+    /** Reverse-DNS id, e.g. `"com.hereliesaz.teal-fade"`. Required. */
+    id: string;
+    /** Display name; defaults to the LUT's TITLE, then the asset stem. */
+    name?: string;
+    /** Semver; default `"1.0.0"`. */
+    version?: string;
+    /** SPDX id for the manifest; default `"MIT"`. */
+    license?: string;
+    author?: string;
+    /** Base name for the stored asset, e.g. `"teal-fade"` -> `assets/teal-fade.cube`. */
+    assetName?: string;
+}
+export interface ImportResult extends WriteResult {
+    /** The parsed LUT (metadata + table), for inspection. */
+    lut: CubeLut;
+}
+/** Parse `cubeText`, then package it as a `.azp` with `licenseText` as the LICENSE. */
+export declare function importCube(cubeText: string, licenseText: string, opts: ImportOptions): ImportResult;
+export { parseCube } from "./parse-cube.js";
+export type { CubeLut } from "./parse-cube.js";

package/dist/index.js

@@ -0,0 +1,51 @@
+/**
+ * `@azphalt/importer-cube` — normalize a `.cube` LUT into a `.azp` asset package.
+ * `.cube` is already the portable color-transform interchange, so normalization is
+ * 1:1: validate/parse for metadata, store the original bytes, and wrap them in a
+ * manifest. See RATIONALE § 1.3.
+ */
+import { writeAzp } from "@azphalt/azp";
+import { parseCube } from "./parse-cube.js";
+/** Manifest/format version this importer targets. */
+const FORMAT = "0.1";
+/** Parse `cubeText`, then package it as a `.azp` with `licenseText` as the LICENSE. */
+export function importCube(cubeText, licenseText, opts) {
+    const lut = parseCube(cubeText);
+    const stem = opts.assetName ?? slug(opts.name ?? lut.title ?? "lut");
+    const assetPath = `assets/${stem}.cube`;
+    const manifest = {
+        azphalt: FORMAT,
+        id: opts.id,
+        name: opts.name ?? lut.title ?? stem,
+        version: opts.version ?? "1.0.0",
+        kind: "asset",
+        license: opts.license ?? "MIT",
+        compat: ">=0.1",
+        author: opts.author,
+        assets: [
+            {
+                type: "lut",
+                path: assetPath,
+                params: {
+                    format: "cube",
+                    dimensions: lut.dimensions,
+                    size: lut.size,
+                    domainMin: lut.domainMin,
+                    domainMax: lut.domainMax,
+                    ...(lut.title ? { title: lut.title } : {}),
+                },
+            },
+        ],
+    };
+    const result = writeAzp({
+        manifest,
+        payload: { [assetPath]: new TextEncoder().encode(cubeText) },
+        license: licenseText,
+    });
+    return { ...result, lut };
+}
+/** Filesystem-safe stem: lowercase, runs of non-alphanumerics to single hyphens. */
+function slug(s) {
+    return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "lut";
+}
+export { parseCube } from "./parse-cube.js";

package/dist/parse-cube.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Parser for the Adobe/IRIDAS `.cube` LUT format (1D or 3D). Faithful enough to
+ * validate a file and extract the metadata a manifest needs; the importer stores the
+ * original bytes, so parsing is validation + description, not re-serialization.
+ */
+export interface CubeLut {
+    title?: string;
+    dimensions: 1 | 3;
+    /** Entries per dimension. */
+    size: number;
+    domainMin: [number, number, number];
+    domainMax: [number, number, number];
+    /** Table of `[r, g, b]` float triplets; length is `size` (1D) or `size**3` (3D). */
+    entries: [number, number, number][];
+}
+/** Parse `.cube` text into a {@link CubeLut}, throwing on anything malformed. */
+export declare function parseCube(text: string): CubeLut;

package/dist/parse-cube.js

@@ -0,0 +1,71 @@
+/**
+ * Parser for the Adobe/IRIDAS `.cube` LUT format (1D or 3D). Faithful enough to
+ * validate a file and extract the metadata a manifest needs; the importer stores the
+ * original bytes, so parsing is validation + description, not re-serialization.
+ */
+/** Parse `.cube` text into a {@link CubeLut}, throwing on anything malformed. */
+export function parseCube(text) {
+    let title;
+    let dimensions;
+    let size;
+    let domainMin = [0, 0, 0];
+    let domainMax = [1, 1, 1];
+    const entries = [];
+    const lines = text.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i].trim();
+        if (line === "" || line.startsWith("#"))
+            continue;
+        const upper = line.toUpperCase();
+        const parts = line.split(/\s+/);
+        if (upper.startsWith("TITLE")) {
+            const quoted = line.match(/"([^"]*)"/);
+            title = quoted ? quoted[1] : line.slice(5).trim();
+            continue;
+        }
+        if (upper.startsWith("LUT_1D_SIZE")) {
+            dimensions = 1;
+            size = parseInt(parts[1], 10);
+            continue;
+        }
+        if (upper.startsWith("LUT_3D_SIZE")) {
+            dimensions = 3;
+            size = parseInt(parts[1], 10);
+            continue;
+        }
+        if (upper.startsWith("DOMAIN_MIN")) {
+            domainMin = [num(parts[1]), num(parts[2]), num(parts[3])];
+            continue;
+        }
+        if (upper.startsWith("DOMAIN_MAX")) {
+            domainMax = [num(parts[1]), num(parts[2]), num(parts[3])];
+            continue;
+        }
+        if (upper.startsWith("LUT_1D_INPUT_RANGE") || upper.startsWith("LUT_3D_INPUT_RANGE")) {
+            const lo = num(parts[1]);
+            const hi = num(parts[2]);
+            domainMin = [lo, lo, lo];
+            domainMax = [hi, hi, hi];
+            continue;
+        }
+        // Otherwise: a data row of three floats.
+        if (parts.length < 3) {
+            throw new Error(`cube: malformed data on line ${i + 1}: "${lines[i]}"`);
+        }
+        entries.push([num(parts[0]), num(parts[1]), num(parts[2])]);
+    }
+    if (dimensions === undefined || size === undefined || !Number.isFinite(size) || size < 2) {
+        throw new Error("cube: missing or invalid LUT_1D_SIZE / LUT_3D_SIZE");
+    }
+    const expected = dimensions === 1 ? size : size * size * size;
+    if (entries.length !== expected) {
+        throw new Error(`cube: expected ${expected} entries for a ${dimensions}D LUT of size ${size}, got ${entries.length}`);
+    }
+    return { title, dimensions, size, domainMin, domainMax, entries };
+}
+function num(s) {
+    const n = Number(s);
+    if (!Number.isFinite(n))
+        throw new Error(`cube: expected a number, got "${s}"`);
+    return n;
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@azphalt/importer-cube",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Import .cube LUTs into .azp asset packages.",
+  "license": "MIT",
+  "author": "Az (https://hereliesaz.com)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "azphalt-import-cube": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@azphalt/azp": "0.1.0",
+    "@azphalt/sdk": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "vitest": "^3.2.6",
+    "@types/node": "^22.0.0"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "clean": "rm -rf dist"
+  }
+}

package/readme.md

@@ -0,0 +1,20 @@
+# @azphalt/importer-cube
+
+Normalize a `.cube` LUT (Adobe/IRIDAS, 1D or 3D) into a `.azp` asset package. `.cube` is already the portable color-transform interchange, so the import is 1:1: the LUT is validated and its metadata captured, the original bytes are stored verbatim, and a manifest wraps them.
+
+## CLI
+
+~~~sh
+pnpm --filter @azphalt/importer-cube build
+azphalt-import-cube teal-fade.cube --id com.hereliesaz.teal-fade -o teal-fade.azp
+# real packaging supplies the LUT's own license text:
+azphalt-import-cube teal-fade.cube --id com.hereliesaz.teal-fade --license-file LICENSE.txt
+~~~
+
+## Library
+
+~~~ts
+import { importCube, parseCube } from "@azphalt/importer-cube";
+
+const { azp, manifest, lut } = importCube(cubeText, licenseText, { id: "com.hereliesaz.teal-fade" });
+~~~