From 6505e941ae8aba6bb280ef594b705b5860fdd180 Mon Sep 17 00:00:00 2001 From: ArkXiong Date: Thu, 19 Nov 2026 14:58:12 +0800 Subject: [PATCH] feat(relief): add the relief command, a photo to a bas-relief model and depth map `meshy relief create|get|list|wait|stream|delete` calls /openapi/v1/relief (20 credits, paid plan). Create takes every documented parameter: --variant, --depth-only, --size-mm, --carving-mode, --carving-depth-mm, --remove-base, --removal-threshold, --base-thickness-mm, --bend-mode, --bend-axis, --bend-angle, --mesh-resolution, --target-formats and --color-mapping. Ranges, the base-thickness rule and settings the API would not use are checked before the request, for --data too. The 16-bit depth map is an asset of its own (`depth_map`, depth_map.png): -o saves it with the models, a depth-only task saves it alone, and it is never converted to another image format. --model-format naming a format the task does not have now lists the formats it has. --- README.md | 2 +- docs/decisions.md | 43 +++ docs/scripting.md | 4 +- docs/usage.md | 59 +++- package.json | 2 +- skills/meshy-cli/SKILL.md | 36 ++- src/client/resource-registry.ts | 8 +- src/client/types.ts | 2 + src/cmd/download.ts | 4 +- src/cmd/relief.ts | 268 +++++++++++++++++ src/cmd/resources.ts | 1 + src/internal/artifacts.ts | 18 +- src/internal/download.ts | 3 +- src/internal/errors.ts | 3 +- src/internal/task-view.ts | 3 + src/internal/views.ts | 1 + src/root.ts | 2 + tests/relief.test.ts | 497 ++++++++++++++++++++++++++++++++ 18 files changed, 938 insertions(+), 18 deletions(-) create mode 100644 src/cmd/relief.ts create mode 100644 tests/relief.test.ts diff --git a/README.md b/README.md index 0334241..c67e0a5 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ The command line for the [Meshy AI API](https://docs.meshy.ai/): text-to-3D, image-to-3D, text-to-motion, remesh, convert, resize, UV unwrap, rigging, animation, retexture, 2D images, printability, auto split, multi-color print, -Creative Lab products, usage records, plus +photo to bas-relief and depth map, Creative Lab products, usage records, plus the local helpers a 3D-printing or agent workflow needs. Built for people and AI agents: a terminal gets a readable view, a pipe or an agent gets JSON. diff --git a/docs/decisions.md b/docs/decisions.md index 04d2863..a225bdd 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -1743,3 +1743,46 @@ behind it, and what a reviewer should check. IDs are stable; append, do not renu before; refreshing during a wait is separate work. - Reviewer check: a change to the window must keep a fresh token outside it, or every command refreshes again. + +## D-096 Relief: one v1 resource, a depth map asset, and the API's rules checked before the request + +- `relief` is a task resource on `/openapi/v1/relief` with the full verb set + and task type `relief`. Its `image_url` takes the photo formats the API + accepts (JPG/JPEG, PNG, WebP), the same list as the Creative Lab photos + (`PHOTO_FORMATS`). The 20 MB, 32 × 32 px and aspect-ratio limits are left to + the API, which answers 400 without charging. +- Flags follow D-076: the API booleans are `--remove-base ` and + `--color-mapping `. `should_generate_model: false` is `--depth-only`, + a presence flag: `--should-generate-model false` would read backwards for + the one value anyone sends, and `--data` still reaches the field. Nothing is + pinned; a flag left out is left out of the request, so the API's defaults + (low, 60 mm, GLB + STL) apply. +- Every documented range is checked on the merged payload, `--data` included. + `--mesh-resolution` is parsed as a number and must be an integer, so 1500.5 + is refused rather than truncated. `target_formats` must be a non-empty list + of the documented lowercase values without repeats. `base_thickness_mm` is + 0.1-10, or left out or 0 with `remove_base: true`. +- Refused as D-076 refuses settings the API would not use: `removal_threshold` + without `remove_base: true`, `bend_axis` / `bend_angle` without a convex or + concave bend, and every model setting with `--depth-only` (the variant + stays: it shapes the depth map). `carving_depth_mm: 0` with + `remove_base: true` is a request the API documents and runs (an empty + model, still billed), so it is sent with an `empty_model` warning rather + than refused. +- `--color-mapping true` with only STL / 3MF formats is sent as asked, with a + `color_not_in_formats` warning: those formats carry no color, but the API + still returns the texture. +- The TaskView gains `depth_map_url` (null for other resources), so a v1 + envelope saved without `--include-raw` still names the depth map. The asset + is `depth_map` (kind `depth_map`, file `depth_map.png`); `-o` saves it with + the models, and a depth-only task saves it alone. It is never transcoded: + sharp would flatten its 16 bits to 8, so a request for `.jpg` keeps the PNG + under its own extension (`extension_corrected`). +- `--model-format` naming a format the task lacks now lists the formats it has + (or says it has no model file). The 402 hint names both causes the API gives + it, no credits or a plan without the endpoint. +- A relief task cannot be the input of another endpoint (403); the help, the + usage guide and the skill say so. Its own `relief delete` is the documented + delete; the shared `meshy delete` was not checked against relief tasks. +- Reviewer check: a new rule must come from the API reference, and must hold + for the same field in `--data`. diff --git a/docs/scripting.md b/docs/scripting.md index 7022845..efeac1c 100644 --- a/docs/scripting.md +++ b/docs/scripting.md @@ -97,8 +97,8 @@ one JSON document (`ndjson` streams emit one line per event plus a final in every output format, and in `ndjson` the final `outcome` line carries the download manifest. - `-o` on `get`/`wait`/`stream`/`make` saves the primary files of a SUCCEEDED - task: the model formats it produced, the primary thumbnail, images and - reports, and the rig or animation result in GLB. `result.downloads.files` is a + task: the model formats it produced, the primary thumbnail, the relief depth + map, images and reports, and the rig or animation result in GLB. `result.downloads.files` is a per-file manifest (stable `key` as `meshy download --asset` takes it, real `path`, bytes, sha256, status). `result.downloads.skipped` lists `{key, reason}` for what stayed on the server: `embedded_textures`, diff --git a/docs/usage.md b/docs/usage.md index d81d87e..7b844bf 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -217,6 +217,11 @@ meshy animate create --rig-task-id --motion-task-id meshy auto-split create --input-task-id --mode by_parts --prompt "head, torso, legs" --connectors true meshy usage tasks --start-time 2026-08-01T00:00:00Z --endpoints image-to-3d --page-size 100 +# photo → bas-relief model + 16-bit depth map (3D print, laser engraving, CNC); 20 credits, paid plan +meshy relief create --image-url ./photo.jpg -o out/relief/ # GLB, STL, depth map, preview +meshy relief create --image-url ./photo.jpg --variant high --size-mm 120 --target-formats 3mf +meshy relief create --image-url ./photo.jpg --depth-only -o heightmap.png # the depth map alone + # Enterprise showcases (billed per request) meshy showcases list --search car --page-size 3 --model-format glb @@ -295,6 +300,7 @@ local commands with their kind. | `analyze-printability` | `/print/analyze` | [docs](https://docs.meshy.ai/en/api/analyze-printability) | | `repair-printability` | `/print/repair` | [docs](https://docs.meshy.ai/en/api/repair-printability) | | `auto-split` | `/print/split` | [docs](https://docs.meshy.ai/en/api/auto-split) | +| `relief` | `/relief` | [docs](https://docs.meshy.ai/en/api/relief) | | `creative-lab prototype\|build` | `/openapi/creative-lab//v1/` | [figure](https://docs.meshy.ai/en/api/creative-lab-figure) · [vinyl-figure](https://docs.meshy.ai/en/api/creative-lab-vinyl-figure) · [brick-figure](https://docs.meshy.ai/en/api/creative-lab-brick-figure) · [lamp](https://docs.meshy.ai/en/api/creative-lab-lamp) · [keychain](https://docs.meshy.ai/en/api/creative-lab-keychain) · [fridge-magnet](https://docs.meshy.ai/en/api/creative-lab-fridge-magnet) · [keycap](https://docs.meshy.ai/en/api/creative-lab-keycap) · [fidget-pixel](https://docs.meshy.ai/en/api/creative-lab-fidget-pixel) | | `creative-lab fidget-collapsible` | `/openapi/creative-lab/fidget-collapsible/v1` | [docs](https://docs.meshy.ai/en/api/creative-lab-fidget-collapsible) | | `animation-catalog list` | `GET /animations/library` (free) | [docs](https://docs.meshy.ai/en/api/animation#list-animations) | @@ -369,6 +375,55 @@ in the web app are rejected by the server (404). a printable STL (plus a preview GLB when available), with the same get/list/wait/stream/delete verbs. +### Relief + +`relief` turns one photo into a bas-relief model and a 16-bit grayscale depth +map, for 3D printing, laser engraving and CNC carving. A task costs 20 credits, +depth map only included, and needs a paid plan (`402` on the free plan). The +photo is a JPG, PNG or WebP of at most 20 MB and at least 32 × 32 px; a local +file is sent inline. + +```bash +meshy relief create --image-url ./photo.jpg -o out/relief/ +meshy relief create --image-url ./photo.jpg --variant high --carving-depth-mm 10 \ + --bend-mode convex --bend-angle 90 --color-mapping true --target-formats glb,obj,stl -o out/plaque/ +meshy relief create --image-url ./logo.png --remove-base true --removal-threshold 0.05 --target-formats stl +meshy relief create --image-url ./photo.jpg --depth-only -o heightmap.png +``` + +- `--variant low` (the default) carves shallow, for laser engraving, CNC and + thin plaques; `high` carves deeper, for printed pieces. The variant shapes the + depth map and sets the default `--carving-depth-mm` (3 or 6). +- `--depth-only` returns only the depth map: no model, no preview image, the + same price. The model settings do not apply to it, so the CLI refuses them. +- `--size-mm` (20-250, default 60) is the photo's longer side on the model. + `--carving-mode engrave` cuts the subject in instead of raising it. + `--remove-base true` cuts the background away and builds no plate; with it, + `--base-thickness-mm` is left out or 0 and `--removal-threshold` (0.01-1) + sets what counts as background. `--bend-mode convex|concave` with + `--bend-axis` and `--bend-angle` curves the relief. +- `--target-formats` (default `glb,stl`) lists the only formats generated: + `glb`, `obj` (with its MTL), `fbx`, `stl`, `usdz`, `3mf`. STL and 3MF keep the + real size in millimetres. `--color-mapping true` colors GLB, OBJ, FBX and + USDZ with the photo and returns the texture; STL and 3MF stay white. +- Files are large: at the default `--mesh-resolution 1024` a GLB is about + 40-50 MB and an STL 80-105 MB; at 2048 about 150 MB and 300 MB, and a bend + makes them larger still. List only the formats you need. + +Every documented range and rule is checked before the request, also for the +same fields in `--data`. A parameter the API would ignore in the combination +asked for (a threshold without `--remove-base true`, a bend angle with no bend) +is refused rather than sent, and so is `--carving-depth-mm 0` with +`--remove-base true`, which builds an empty model that is still billed. + +`-o ` saves every model format, the depth map (`depth_map.png`), the +preview and, when an OBJ or FBX needs it, the texture; `meshy download +--asset depth_map` fetches the depth map alone. The depth map is never +converted to another image format: that would drop its 16-bit levels. + +A relief task cannot be the input of another command (`remesh`, `convert`, +`resize`, `auto-split` …): the API answers 403. + ## Saving artifacts with `-o` and `meshy download` (selective) When `-o` is set on a `create`/`wait`/`get`/`stream` or on `make`, the CLI @@ -383,8 +438,8 @@ The primary files are: - every model format the task produced. That is GLB unless `--target-formats` asked for more. -- the primary thumbnail, the generated images, motion clips, `processed_*` - outputs and reports (`printability.json`). +- the primary thumbnail, the relief depth map, the generated images, motion + clips, `processed_*` outputs and reports (`printability.json`). - the rig or animation result in GLB (`rigged_character.glb`, `animation_glb.glb`). Left on the server by default, and listed under `result.downloads.skipped` diff --git a/package.json b/package.json index cf747d0..6564318 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "meshy-cli", "version": "0.8.7", - "description": "Official command-line interface for the Meshy AI API — text-to-3D, image-to-3D, text-to-motion, remesh, UV unwrap, rigging, animate, retexture, 2D images, printability, auto split, multi-color print, Creative Lab, balance and usage — plus selective downloads, project folders, face checks, OBJ print preparation and slicer launch.", + "description": "Official command-line interface for the Meshy AI API — text-to-3D, image-to-3D, text-to-motion, remesh, UV unwrap, rigging, animate, retexture, 2D images, printability, auto split, multi-color print, relief, Creative Lab, balance and usage — plus selective downloads, project folders, face checks, OBJ print preparation and slicer launch.", "license": "MIT", "type": "module", "packageManager": "pnpm@11.24.0", diff --git a/skills/meshy-cli/SKILL.md b/skills/meshy-cli/SKILL.md index 61039fa..9a50859 100644 --- a/skills/meshy-cli/SKILL.md +++ b/skills/meshy-cli/SKILL.md @@ -1,6 +1,6 @@ --- name: meshy-cli -description: "Generate 3D models, motion clips, 2D images and Creative Lab print products with the Meshy API through the meshy-cli command — text-to-3D, image-to-3D, text-to-motion, remesh, UV unwrap, rigging, animation, retexture, printability, auto split into printable parts, per-task credit usage, selective downloads, face checks, OBJ print preparation and slicer launch. Use for any Meshy asset or 3D-printing request." +description: "Generate 3D models, motion clips, 2D images, bas-reliefs and Creative Lab print products with the Meshy API through the meshy-cli command — text-to-3D, image-to-3D, text-to-motion, remesh, UV unwrap, rigging, animation, retexture, printability, auto split into printable parts, photo to relief model and depth map (3D print, laser engraving, CNC), per-task credit usage, selective downloads, face checks, OBJ print preparation and slicer launch. Use for any Meshy asset or 3D-printing request." license: MIT compatibility: Requires meshy-cli on PATH (Node 22.12+, no Python) and a stored credential, MESHY_API_KEY or --api-key-file for API commands; network access to api.meshy.ai. Local helpers work offline. metadata: @@ -118,6 +118,40 @@ output `lamp_stl`/`base_stl` or `bundle_zip`; keychain/fridge-magnet `obj` and keycap `obj_zip` are ZIP bundles saved as `.zip`; fidget-pixel builds a 3MF. Never call `showcases` in a health check. +## Relief (photo → bas-relief model and depth map) + +```bash +meshy relief create --image-url ./photo.jpg -o out/relief/ # GLB + STL + depth_map.png + preview +meshy relief create --image-url ./photo.jpg --variant high --size-mm 120 --target-formats 3mf -o out/plaque/ +meshy relief create --image-url ./photo.jpg --depth-only -o heightmap.png # the 16-bit depth map alone +``` + +Use `relief` when the user wants a photo turned into a relief, plaque, medallion +or engraving, or a height map for laser or CNC software; the Creative Lab +keychain and fridge magnet are styled products with a prototype stage, not this. +Every task costs 20 credits, a depth-map-only task too, and needs a paid plan +(exit 9 on the free plan or without credits: relay it, do not retry). + +- `--variant low` (default) is shallow, for laser engraving, CNC and thin + plaques; `high` is deeper, for 3D-printed pieces. +- `--depth-only` returns only `depth_map_url` (a 16-bit grayscale PNG, relative + heights): no model, no preview. Use it when the user asked for a height or + depth map only. Model settings are refused with it. +- `--target-formats` (default `glb,stl`) is the only set generated: `glb`, `obj` + (+ MTL), `fbx`, `stl`, `usdz`, `3mf`. STL and 3MF are in real millimetres, for + printing. `--color-mapping true` colors GLB/OBJ/FBX/USDZ only; STL and 3MF stay + white. Ask only for the formats the user needs: an STL is 80-105 MB at the + default `--mesh-resolution 1024` and about 300 MB at 2048 (more with a bend). +- `--remove-base true` cuts the background away (then `--base-thickness-mm` is + left out or 0); `--bend-mode convex|concave` curves it. Ranges and the + combinations the API would ignore are refused before the request (exit 2). +- `-o ` saves the models, `depth_map.png` and the preview; + `meshy download --task-json --asset depth_map --output ` + fetches the depth map alone. It is never converted to another image format. +- **A relief task cannot feed another command** (`remesh`, `convert`, `resize`, + `auto-split`, `multi-color-print` …: 403). Pick the formats, size and depth at + create time; to change them, create a new relief. + ## Downloads, printing (local, no key) ```bash diff --git a/src/client/resource-registry.ts b/src/client/resource-registry.ts index 0c98b81..ede4e91 100644 --- a/src/client/resource-registry.ts +++ b/src/client/resource-registry.ts @@ -120,7 +120,8 @@ export const CREATIVE_LAB_PRODUCTS: readonly CreativeLabProduct[] = [ "fidget-pixel", ]; export const CREATIVE_LAB_STAGES: readonly CreativeLabStage[] = ["prototype", "build"]; -const CREATIVE_LAB_IMAGE_FORMATS = ["jpg", "jpeg", "png", "webp"] as const; +/** The photo inputs of Creative Lab and Relief: JPG/JPEG, PNG or WebP. */ +const PHOTO_FORMATS = ["jpg", "jpeg", "png", "webp"] as const; function creativeLab(product: CreativeLabProduct, stage: CreativeLabStage, summary: string): TaskResourceDescriptor { const relativePath = `/${product}/v1/${stage}`; @@ -131,7 +132,7 @@ function creativeLab(product: CreativeLabProduct, stage: CreativeLabStage, summa relativePath, endpoint: `/openapi/creative-lab${relativePath}`, supports: ALL_VERBS, - mediaFields: stage === "prototype" ? [image("image_url", false, CREATIVE_LAB_IMAGE_FORMATS)] : [], + mediaFields: stage === "prototype" ? [image("image_url", false, PHOTO_FORMATS)] : [], taskTypes: [`creative-lab-${product}-${stage}`], billing: { create: "may-charge" }, automaticRetry: false, @@ -150,7 +151,7 @@ function creativeLabSingle(product: CreativeLabSingleProduct, summary: string): relativePath, endpoint: `/openapi/creative-lab${relativePath}`, supports: ALL_VERBS, - mediaFields: [image("image_url", false, CREATIVE_LAB_IMAGE_FORMATS)], + mediaFields: [image("image_url", false, PHOTO_FORMATS)], taskTypes: [`creative-lab-${product}`], billing: { create: "may-charge" }, automaticRetry: false, @@ -189,6 +190,7 @@ export const TASK_RESOURCES: readonly TaskResourceDescriptor[] = [ v1("repair-printability", "/print/repair", { mediaFields: [inlineModel("model_url")], taskTypes: ["print-repair"], summary: "fix non-watertight / non-manifold geometry" }), v1("auto-split", "/print/split", { taskTypes: ["print-split"], summary: "split a model into printable parts (auto / by named parts / by colour; optional connectors)" }), v1("uv-unwrap", "/uv-unwrap", { mediaFields: [model("model_url", ["glb"])], taskTypes: ["uv-unwrap"], summary: "generate fresh UVs for a GLB (≤40k faces) — a UV white model for external texturing" }), + v1("relief", "/relief", { mediaFields: [image("image_url", false, PHOTO_FORMATS)], taskTypes: ["relief"], summary: "photo → bas-relief model + 16-bit depth map (3D print, laser engraving, CNC)" }), creativeLab("figure", "prototype", "Creative Lab figure: photo → styled concept image"), creativeLab("figure", "build", "Creative Lab figure: prototype → textured GLB/OBJ/MTL"), creativeLab("lamp", "prototype", "Creative Lab lamp: photo → concept image + lampshade GLB"), diff --git a/src/client/types.ts b/src/client/types.ts index 7034700..2f12b4d 100644 --- a/src/client/types.ts +++ b/src/client/types.ts @@ -92,6 +92,8 @@ export const TaskSchema = z thumbnail_url: z.string().nullable().optional(), thumbnail_urls: z.record(z.string(), z.string().nullable()).nullable().optional(), alpha_thumbnail_url: z.string().nullable().optional(), + /** Relief: the 16-bit grayscale depth map the model is built from ("" until it exists). */ + depth_map_url: z.string().nullable().optional(), image_urls: z.array(z.string()).nullable().optional(), diff --git a/src/cmd/download.ts b/src/cmd/download.ts index 58f38d6..d130597 100644 --- a/src/cmd/download.ts +++ b/src/cmd/download.ts @@ -30,7 +30,7 @@ import { buildLocalRuntime, buildRuntime } from "../internal/runtime.js"; import { extractTaskObject } from "../internal/task-view.js"; const TASK_JSON_MAX_BYTES = 16 * 1024 * 1024; -const KINDS: readonly AssetKind[] = ["model", "image", "texture", "thumbnail", "rig", "animation", "motion", "report"]; +const KINDS: readonly AssetKind[] = ["model", "image", "texture", "thumbnail", "depth_map", "rig", "animation", "motion", "report"]; interface DownloadOpts { taskJson?: string; @@ -92,7 +92,7 @@ export const downloadCommand = new Command("download") .option("--url ", "download exactly one asset URL (no task context)") .option("--resource ", "with --task-id: fetch the task from the API first (one GET)") .option("--task-id ", "with --resource: the task to fetch") - .option("--asset ", "stable asset key to download (repeatable), e.g. model.glb, thumbnail.primary, result.basic_animations.walking_glb_url", collect) + .option("--asset ", "stable asset key to download (repeatable), e.g. model.glb, thumbnail.primary, depth_map, result.basic_animations.walking_glb_url", collect) .option("--model-format ", "select the model of this format (glb, obj, fbx, usdz, stl, 3mf, …)") .addOption(new Option("--kind ", "select every asset of one kind").choices([...KINDS])) .option("--all", "select every asset") diff --git a/src/cmd/relief.ts b/src/cmd/relief.ts new file mode 100644 index 0000000..37fded5 --- /dev/null +++ b/src/cmd/relief.ts @@ -0,0 +1,268 @@ +/** + * relief — https://docs.meshy.ai/en/api/relief + * + * Turns one photo into a bas-relief model and a 16-bit grayscale depth map, + * for 3D printing, laser engraving and CNC carving. `--depth-only` asks for + * the depth map alone: no model and no preview image, billed like a full task. + * + * Every range and rule the API documents is checked on the merged payload + * (--data and flags alike) before the request: the numeric ranges, an integer + * mesh resolution, the base-thickness rule with remove_base, target formats + * from the documented set without repeats. Parameters the API documents as + * unused in a combination are refused rather than sent (D-076): + * removal_threshold without remove_base, the bend axis and angle without a + * bend, and the model settings of a depth-only task. A zero carving depth + * with remove_base is sent with a warning: the API builds an empty model and + * still bills it. + * + * Nothing is pinned: a flag left out is left out of the request, so the API's + * own defaults apply (low variant, 60 mm, GLB + STL). + * + * A relief task cannot be the input of another endpoint (remesh, convert, + * resize, auto-split …); the API answers 403. + */ + +import { Option } from "commander"; +import { UsageError, type Warning } from "../internal/errors.js"; +import { parseBool, parseCsv, parseNumber } from "../internal/flags.js"; +import { warning } from "../internal/result.js"; +import { buildResourceCommand, type ResourceCommandSpec } from "../internal/task-command.js"; + +export const RELIEF_VARIANTS = ["low", "high"] as const; +export const RELIEF_CARVING_MODES = ["emboss", "engrave"] as const; +export const RELIEF_BEND_MODES = ["off", "convex", "concave"] as const; +export const RELIEF_BEND_AXES = ["xz", "yz"] as const; +export const RELIEF_TARGET_FORMATS = ["glb", "obj", "fbx", "stl", "usdz", "3mf"] as const; +/** Formats that carry the photo's color with color_mapping; STL and 3MF stay white. */ +const COLOR_FORMATS = new Set(["glb", "obj", "fbx", "usdz"]); + +/** Inclusive numeric ranges from the API reference. */ +const RANGES = { + size_mm: [20, 250], + carving_depth_mm: [0, 60], + removal_threshold: [0.01, 1], + base_thickness_mm: [0.1, 10], + bend_angle: [0, 360], + mesh_resolution: [512, 2048], +} as const satisfies Record; + +/** Settings that shape the model; a depth-only task has no model to shape. */ +const MODEL_SETTINGS = [ + "size_mm", + "carving_mode", + "carving_depth_mm", + "remove_base", + "removal_threshold", + "base_thickness_mm", + "bend_mode", + "bend_axis", + "bend_angle", + "mesh_resolution", + "target_formats", + "color_mapping", +] as const; + +const flagOf = (key: string): string => `--${key.replace(/_/g, "-")}`; +const present = (payload: Record, key: string): boolean => payload[key] !== undefined && payload[key] !== null; + +function checkEnum(payload: Record, key: string, values: readonly string[]): void { + const v = payload[key]; + if (v === undefined || v === null) return; + if (typeof v !== "string" || !values.includes(v)) { + throw new UsageError(`${flagOf(key)} must be one of ${values.join(" | ")} (got ${JSON.stringify(v)})`); + } +} + +function checkBool(payload: Record, key: string, flag = flagOf(key)): void { + if (present(payload, key) && typeof payload[key] !== "boolean") { + throw new UsageError(`${flag} must be true or false (got ${JSON.stringify(payload[key])})`); + } +} + +function checkRange(payload: Record, key: keyof typeof RANGES, opts: { integer?: boolean } = {}): void { + if (!present(payload, key)) return; + const [min, max] = RANGES[key]; + const v = payload[key]; + if (typeof v !== "number" || !Number.isFinite(v) || v < min || v > max || (opts.integer && !Number.isInteger(v))) { + throw new UsageError(`${flagOf(key)} must be ${opts.integer ? "an integer" : "a number"} from ${min} to ${max} (got ${JSON.stringify(v)})`); + } +} + +function checkTargetFormats(payload: Record): void { + if (!present(payload, "target_formats")) return; + const formats = payload.target_formats; + if (!Array.isArray(formats) || formats.length === 0) { + throw new UsageError(`--target-formats must list at least one of ${RELIEF_TARGET_FORMATS.join(", ")}`); + } + const seen = new Set(); + for (const f of formats) { + if (typeof f !== "string" || !(RELIEF_TARGET_FORMATS as readonly string[]).includes(f)) { + throw new UsageError(`--target-formats: unknown format ${JSON.stringify(f)}; choose from ${RELIEF_TARGET_FORMATS.join(", ")} (OBJ comes with its MTL)`); + } + if (seen.has(f)) throw new UsageError(`--target-formats lists '${f}' twice`); + seen.add(f); + } +} + +export function validateReliefPayload(payload: Record): void { + if (typeof payload.image_url !== "string" || !payload.image_url) { + throw new UsageError("provide --image-url (a photo as an http(s) URL, data: URI or local jpg/jpeg/png/webp file)"); + } + // The API reads "" as "not sent", like an omitted variant. + if (payload.variant !== "") checkEnum(payload, "variant", RELIEF_VARIANTS); + checkBool(payload, "should_generate_model", "should_generate_model (--depth-only)"); + checkEnum(payload, "carving_mode", RELIEF_CARVING_MODES); + checkEnum(payload, "bend_mode", RELIEF_BEND_MODES); + checkEnum(payload, "bend_axis", RELIEF_BEND_AXES); + checkBool(payload, "remove_base"); + checkBool(payload, "color_mapping"); + checkRange(payload, "size_mm"); + checkRange(payload, "carving_depth_mm"); + checkRange(payload, "removal_threshold"); + checkRange(payload, "bend_angle"); + checkRange(payload, "mesh_resolution", { integer: true }); + checkTargetFormats(payload); + + if (payload.should_generate_model === false) { + const set = MODEL_SETTINGS.filter((k) => present(payload, k)); + if (set.length > 0) { + throw new UsageError( + `--depth-only returns the depth map alone, so ${set.map(flagOf).join(", ")} ${set.length === 1 ? "does" : "do"} not apply; drop ${set.length === 1 ? "it" : "them"} or leave out --depth-only`, + ); + } + return; + } + + const removeBase = payload.remove_base === true; + if (present(payload, "base_thickness_mm")) { + const t = payload.base_thickness_mm; + if (removeBase) { + if (t !== 0) { + throw new UsageError(`--remove-base true builds no base plate: leave out --base-thickness-mm or pass 0 (got ${JSON.stringify(t)})`); + } + } else { + checkRange(payload, "base_thickness_mm"); + } + } + if (present(payload, "removal_threshold") && !removeBase) { + throw new UsageError("--removal-threshold applies with --remove-base true only"); + } + const bent = payload.bend_mode === "convex" || payload.bend_mode === "concave"; + const bendShape = (["bend_axis", "bend_angle"] as const).filter((k) => present(payload, k)); + if (bendShape.length > 0 && !bent) { + throw new UsageError(`${bendShape.map(flagOf).join(" and ")} ${bendShape.length === 1 ? "applies" : "apply"} with --bend-mode convex or concave only`); + } +} + +/** + * Requests the API runs but that likely miss what was meant: color mapping on + * formats that cannot show it (the texture still comes back, the models stay + * white), and a zero carving depth with the base removed (an empty model, + * still billed). + */ +export function reliefWarnings(payload: Record): Warning[] { + const warnings: Warning[] = []; + const formats = payload.target_formats; + if (payload.color_mapping === true && Array.isArray(formats) && !formats.some((f) => typeof f === "string" && COLOR_FORMATS.has(f))) { + warnings.push( + warning( + "color_not_in_formats", + `--color-mapping true: ${formats.join(", ")} carr${formats.length === 1 ? "ies" : "y"} no color, so the model stays white; the texture is returned in texture_urls (add glb, obj, fbx or usdz for a colored model)`, + ), + ); + } + if (payload.should_generate_model !== false && payload.remove_base === true && payload.carving_depth_mm === 0) { + warnings.push( + warning( + "empty_model", + "--carving-depth-mm 0 with --remove-base true builds a model with no geometry, and the task is still billed", + ), + ); + } + return warnings; +} + +export const reliefSpec: ResourceCommandSpec = { + name: "relief", + description: + "Turn one photo into a bas-relief model and a 16-bit grayscale depth map, for 3D printing, laser engraving " + + "and CNC carving (--depth-only: the depth map alone). Needs a paid plan. A relief task cannot be the input " + + "of another command (remesh, convert, resize, auto-split …)", + create: { + description: "Create a relief task from a photo", + configure(cmd) { + return cmd + .option("--image-url ", "photo: http(s) URL, data: URI or local jpg/jpeg/png/webp path, at most 20 MB and at least 32x32 px (required)") + .addOption( + new Option( + "--variant ", + "low (default; shallow carving for laser engraving, CNC and thin plaques) | high (deeper carving for 3D-printed pieces)", + ).choices([...RELIEF_VARIANTS]), + ) + .option( + "--depth-only", + "return only the 16-bit depth map: no model, no preview image (sends should_generate_model false; billed like a full task)", + ) + .option("--size-mm ", "length of the photo's longer side on the model, measured flat before any bend: 20-250 (default: 60)", parseNumber) + .addOption( + new Option("--carving-mode ", "emboss (default; nearer parts stand out) | engrave (depth inverted, nearer parts cut in)").choices([ + ...RELIEF_CARVING_MODES, + ]), + ) + .option("--carving-depth-mm ", "how deep the relief is carved: 0-60 (default: 6 on high, 3 on low)", parseNumber) + .option("--remove-base ", "cut the background away and build no base plate (default: false)", parseBool) + .option("--removal-threshold ", "with --remove-base true: depth below which the background is cut away, 0.01-1 on the depth map's 0-1 scale (default: 0.01)", parseNumber) + .option("--base-thickness-mm ", "base plate thickness: 0.1-10 (default: 1); with --remove-base true leave it out or pass 0", parseNumber) + .addOption( + new Option("--bend-mode ", "off (default; flat) | convex (the front bulges outward) | concave (the front curves inward)").choices([ + ...RELIEF_BEND_MODES, + ]), + ) + .addOption( + new Option("--bend-axis ", "with --bend-mode convex|concave: xz (default; curls the left and right edges) | yz (the top and bottom edges)").choices([ + ...RELIEF_BEND_AXES, + ]), + ) + .option("--bend-angle ", "with --bend-mode convex|concave: the arc the bend spans, 0-360 degrees (default: 60; below 1 stays flat)", parseNumber) + .option( + "--mesh-resolution ", + "mesh points along the photo's longer side, an integer 512-2048 (default: 1024). Higher keeps finer detail and makes much larger files: " + + "about 40-50 MB GLB and 80-105 MB STL at 1024, about 150 MB and 300 MB at 2048, more with a bend", + parseNumber, + ) + .option( + "--target-formats ", + "glb,obj,fbx,stl,usdz,3mf (default: glb,stl); only the listed formats are generated. OBJ comes with its MTL; STL and 3MF keep the real size in millimetres", + parseCsv, + ) + .option( + "--color-mapping ", + "color the model with the photo (default: false): GLB, OBJ, FBX and USDZ carry the color, STL and 3MF stay white; the texture comes back in texture_urls", + parseBool, + ); + }, + toPayload(opts) { + return { + image_url: opts.imageUrl, + variant: opts.variant, + should_generate_model: opts.depthOnly === true ? false : undefined, + size_mm: opts.sizeMm, + carving_mode: opts.carvingMode, + carving_depth_mm: opts.carvingDepthMm, + remove_base: opts.removeBase, + removal_threshold: opts.removalThreshold, + base_thickness_mm: opts.baseThicknessMm, + bend_mode: opts.bendMode, + bend_axis: opts.bendAxis, + bend_angle: opts.bendAngle, + mesh_resolution: opts.meshResolution, + target_formats: opts.targetFormats, + color_mapping: opts.colorMapping, + }; + }, + validatePayload: (payload) => validateReliefPayload(payload), + warnPayload: reliefWarnings, + }, +}; + +export const reliefCommand = buildResourceCommand(reliefSpec); diff --git a/src/cmd/resources.ts b/src/cmd/resources.ts index 4174b29..a330fca 100644 --- a/src/cmd/resources.ts +++ b/src/cmd/resources.ts @@ -52,6 +52,7 @@ export const RESOURCES: ResourceEntry[] = [ { name: "doctor", summary: "local environment diagnosis (no network by default)" }, { name: "view", summary: "show a local .glb/.gltf in an interactive 3D viewer in the browser (local only)" }, { name: "auto-split", summary: "split a model into printable parts (auto / by named parts / by colour; optional connectors)" }, + { name: "relief", summary: "photo → bas-relief model + 16-bit depth map (3D print, laser engraving, CNC)" }, { name: "usage", summary: "usage tasks: finished API tasks with the credits each consumed (Studio/Enterprise)" }, ]; diff --git a/src/internal/artifacts.ts b/src/internal/artifacts.ts index 368a291..e4fa4d5 100644 --- a/src/internal/artifacts.ts +++ b/src/internal/artifacts.ts @@ -12,16 +12,18 @@ * - keychain / fridge-magnet build: `model_urls.obj` is a ZIP bundle * (model.obj + model.mtl + texture.png), delivered as `.zip`, unextracted; * - keycap build: `model_urls.obj_zip` is the same kind of bundle; + * - relief: `depth_map_url` is a 16-bit grayscale PNG, an asset of its own + * (`depth_map`) and the only one of a depth-only task; * - motion clips carry their format in `result.motion_format`. */ import type { TaskResourceDescriptor } from "../client/resource-registry.js"; import { safeExtension, safeSegment } from "./paths.js"; -export type AssetKind = "model" | "image" | "texture" | "thumbnail" | "rig" | "animation" | "motion" | "report"; +export type AssetKind = "model" | "image" | "texture" | "thumbnail" | "depth_map" | "rig" | "animation" | "motion" | "report"; export interface Asset { - /** Stable selector, e.g. `model.glb`, `thumbnail.primary`, `result.basic_animations.walking_glb_url`. */ + /** Stable selector, e.g. `model.glb`, `thumbnail.primary`, `depth_map`, `result.basic_animations.walking_glb_url`. */ key: string; kind: AssetKind; url: string | null; @@ -115,6 +117,11 @@ export function enumerateAssets(task: Record, descriptor?: Task } } + // Relief: the height map the model is built from — the whole output of a depth-only task. + if (isUrl(task["depth_map_url"])) { + assets.push({ key: "depth_map", kind: "depth_map", url: task["depth_map_url"], format: "png", containerFormat: null, modelFormat: null, sourcePath: "depth_map_url", filename: "depth_map.png", dependencies: [] }); + } + if (isUrl(task["thumbnail_url"])) { assets.push({ key: "thumbnail.primary", kind: "thumbnail", url: task["thumbnail_url"], format: "png", containerFormat: null, modelFormat: null, sourcePath: "thumbnail_url", filename: "thumbnail.png", dependencies: [] }); } @@ -269,7 +276,10 @@ export function selectAssets(enumeration: AssetEnumeration, sel: Selection, opts } else if (sel.modelFormat) { const fmt = sel.modelFormat.toLowerCase(); selected = assets.filter((a) => a.kind === "model" && (a.key === `model.${fmt}` || a.modelFormat === fmt || a.format === fmt)); - if (selected.length === 0) throw new SelectionError(`no model asset in format '${sel.modelFormat}'`, assets); + if (selected.length === 0) { + const has = [...new Set(assets.filter((a) => a.kind === "model").map((a) => a.modelFormat ?? a.format ?? a.key.replace(/^model\./, "")))]; + throw new SelectionError(`no model asset in format '${sel.modelFormat}' (${has.length > 0 ? `the task has ${has.join(", ")}` : "the task has no model file"})`, assets); + } } else if (sel.kind) { selected = assets.filter((a) => a.kind === sel.kind); if (selected.length === 0) throw new SelectionError(`no asset of kind '${sel.kind}'`, assets); @@ -317,7 +327,7 @@ const RESULT_PAIR = /^result\.(rigged_character|animation)_(glb|fbx)_url$/; /** * The default `-o` set: every model format the task produced, the primary - * thumbnail, images, motion, post-process outputs and reports, the rig / + * thumbnail, the relief depth map, images, motion, post-process outputs and reports, the rig / * animation result in GLB. Left on the server: the rig's bundled * walking/running clips, the FBX copy of a result that also came as GLB, * texture maps a delivered model already embeds, the pre-remesh GLB and the diff --git a/src/internal/download.ts b/src/internal/download.ts index f22c15a..baa33f8 100644 --- a/src/internal/download.ts +++ b/src/internal/download.ts @@ -511,7 +511,8 @@ async function placeFetched( } else if (!requestedExt && actualExt) { finalPath = `${planned}.${actualExt}`; } else if (requestedExt && actualExt && requestedExt !== actualExt && !extEquivalent(requestedExt, actualExt)) { - if (CONVERTIBLE_IMAGE_EXTS.has(actualExt) && CONVERTIBLE_IMAGE_EXTS.has(requestedExt)) { + // A depth map is never transcoded: its 16-bit levels would be flattened to 8 bits, so it keeps its own extension. + if (asset.kind !== "depth_map" && CONVERTIBLE_IMAGE_EXTS.has(actualExt) && CONVERTIBLE_IMAGE_EXTS.has(requestedExt)) { const converted = `${tmp}.conv`; await convertImage(readFileSync(tmp), requestedExt, converted); removeQuietly(tmp); diff --git a/src/internal/errors.ts b/src/internal/errors.ts index 6e9878b..47630ff 100644 --- a/src/internal/errors.ts +++ b/src/internal/errors.ts @@ -201,7 +201,8 @@ function hintForApiError(err: MeshyApiError): { hint?: string; docs?: string } { return { hint: SESSION_REVOKED_HINT, docs: DOCS_AUTH }; case "credit": return { - hint: "Out of credits. Confirm with: meshy balance — then top up at https://www.meshy.ai/pricing", + // 402 also answers a create on the free plan; the error message says which. + hint: "Out of credits, or this request needs a paid plan (the message says which). Confirm with: meshy balance — then top up or upgrade at https://www.meshy.ai/pricing", }; case "rate_limit": return { hint: "Rate limited. Pause before retrying, or lower request concurrency." }; diff --git a/src/internal/task-view.ts b/src/internal/task-view.ts index b8d1304..d07d400 100644 --- a/src/internal/task-view.ts +++ b/src/internal/task-view.ts @@ -30,6 +30,8 @@ export interface TaskView { thumbnail_url: string | null; thumbnail_urls: Record | null; alpha_thumbnail_url: string | null; + /** Relief: the 16-bit grayscale depth map (a depth-only task's whole output). */ + depth_map_url: string | null; result: Record | null; printability: Record | null; task_error: { message: string | null; [k: string]: unknown } | null; @@ -96,6 +98,7 @@ export function toTaskView(raw: unknown, opts: TaskViewOptions = {}): TaskView { thumbnail_url: str(r["thumbnail_url"]), thumbnail_urls: strRecord(r["thumbnail_urls"]), alpha_thumbnail_url: str(r["alpha_thumbnail_url"]), + depth_map_url: str(r["depth_map_url"]), result: r["result"] && typeof r["result"] === "object" && !Array.isArray(r["result"]) ? (r["result"] as Record) : null, printability: r["printability"] && typeof r["printability"] === "object" ? (r["printability"] as Record) : null, task_error: diff --git a/src/internal/views.ts b/src/internal/views.ts index 801d359..634efc1 100644 --- a/src/internal/views.ts +++ b/src/internal/views.ts @@ -156,6 +156,7 @@ function assetSummary(task: TaskView): string { const parts: string[] = []; const models = Object.entries(task.model_urls).filter(([, u]) => u).map(([k]) => k); if (models.length) parts.push(models.join(", ")); + if (task.depth_map_url) parts.push("depth map"); const sets = task.texture_urls.filter((s) => Object.values(s).some(Boolean)); if (sets.length === 1) parts.push(`textures: ${Object.keys(sets[0]!).filter((k) => sets[0]![k]).join(", ")}`); else if (sets.length > 1) parts.push(`${sets.length} texture sets`); diff --git a/src/root.ts b/src/root.ts index b8aed50..e770c1b 100644 --- a/src/root.ts +++ b/src/root.ts @@ -37,6 +37,7 @@ import { meshCommand } from "./cmd/mesh.js"; import { multiColorPrintCommand } from "./cmd/multi-color-print.js"; import { multiImageTo3dCommand } from "./cmd/multi-image-to-3d.js"; import { operationsCommand } from "./cmd/operations.js"; +import { reliefCommand } from "./cmd/relief.js"; import { remeshCommand } from "./cmd/remesh.js"; import { repairPrintabilityCommand } from "./cmd/repair-printability.js"; import { resizeCommand } from "./cmd/resize.js"; @@ -201,6 +202,7 @@ export function buildRootCommand(): Command { slicerCommand, doctorCommand, autoSplitCommand, + reliefCommand, usageCommand, viewCommand, ]) { diff --git a/tests/relief.test.ts b/tests/relief.test.ts new file mode 100644 index 0000000..67ec928 --- /dev/null +++ b/tests/relief.test.ts @@ -0,0 +1,497 @@ +/** + * Relief: photo → bas-relief model + 16-bit depth map on /openapi/v1/relief. + * Registry entry, flag → payload mapping and local validation (nothing sent + * when a rule is broken), the task verbs' routes, and what `-o` and + * `meshy download` save for a relief task — models (OBJ with its MTL), the + * color texture, the depth map, and the depth map alone for a depth-only task. + */ + +import test from "node:test"; +import assert from "node:assert/strict"; +import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; +import sharp from "sharp"; +import { requireTaskResource, resourceIndex } from "../src/client/resource-registry.js"; +import { enumerateAssets, selectDefaultAssets } from "../src/internal/artifacts.js"; +import { UsageError } from "../src/internal/errors.js"; +import { okEnvelope } from "../src/internal/result.js"; +import { toTaskView } from "../src/internal/task-view.js"; +import { renderView } from "../src/internal/views.js"; +import { plain } from "../src/internal/color.js"; +import { reliefWarnings, validateReliefPayload } from "../src/cmd/relief.js"; +import { jsonReply, parseSingleJson, runCli, startMockApi, tmpDir, type MockApi } from "./helpers/cli.js"; + +const IMAGE = "https://photos.example.com/cat.png"; + +function glb(payload = "relief"): Buffer { + const head = Buffer.alloc(12); + head.write("glTF", 0, "ascii"); + head.writeUInt32LE(2, 4); + head.writeUInt32LE(12 + payload.length, 8); + return Buffer.concat([head, Buffer.from(payload)]); +} + +async function png(): Promise { + return sharp({ create: { width: 32, height: 32, channels: 3, background: { r: 10, g: 20, b: 30 } } }).png().toBuffer(); +} + +/** A 16-bit grayscale PNG, the depth map's real shape. */ +async function depthPng(): Promise { + return sharp({ create: { width: 4, height: 4, channels: 3, background: { r: 128, g: 128, b: 128 } } }).toColourspace("grey16").png().toBuffer(); +} + +/** The colored relief task of the API reference, with OBJ + MTL and 3MF added, its URLs on `host`. */ +function coloredTask(host: string): Record { + const out = (name: string) => `${host}/assets/relief-1/output/${name}?Expires=1&Signature=secret`; + return { + id: "relief-1", + type: "relief", + model_urls: { glb: out("model.glb"), stl: out("model.stl"), obj: out("model.obj"), mtl: out("model.mtl"), "3mf": out("model.3mf") }, + texture_urls: [{ base_color: out("texture_0.png") }], + depth_map_url: out("depth.png"), + thumbnail_url: out("preview.png"), + progress: 100, + status: "SUCCEEDED", + created_at: 1_699_999_999_000, + started_at: 1_700_000_000_000, + finished_at: 1_700_000_060_000, + expires_at: 1_700_259_260_000, + task_error: null, + consumed_credits: 20, + }; +} + +/** A depth-map-only task: no models, an empty thumbnail. */ +function depthOnlyTask(host: string): Record { + return { + id: "depth-1", + type: "relief", + model_urls: {}, + depth_map_url: `${host}/assets/depth-1/output/depth.png?Expires=1&Signature=secret`, + thumbnail_url: "", + progress: 100, + status: "SUCCEEDED", + created_at: 1_699_999_999_000, + started_at: 1_700_000_000_000, + finished_at: 1_700_000_030_000, + expires_at: 1_700_259_230_000, + task_error: null, + consumed_credits: 20, + }; +} + +interface Bodies { + glb: Buffer; + png: Buffer; + depth: Buffer; +} + +async function bodies(): Promise { + return { glb: glb(), png: await png(), depth: await depthPng() }; +} + +/** One loopback origin for the API and the asset host, as the tests elsewhere do. */ +async function reliefApi(b: Bodies): Promise { + const api: MockApi = await startMockApi((req, res) => { + const asset = /^\/assets\/[a-z0-9-]+\/output\/(.+)$/.exec(req.path)?.[1]; + if (asset) { + const files: Record = { + "model.glb": ["model/gltf-binary", b.glb], + "model.stl": ["model/stl", Buffer.from("solid relief\nendsolid relief\n")], + "model.3mf": ["model/3mf", Buffer.from("3mf-bytes")], + "model.obj": ["model/obj", "mtllib model.mtl\nusemtl relief\nv 0 0 0\nv 1 0 0\nv 0 1 0\nf 1 2 3\n"], + "model.mtl": ["text/plain", "newmtl relief\nmap_Kd texture_0.png\n"], + "texture_0.png": ["image/png", b.png], + "preview.png": ["image/png", b.png], + "depth.png": ["image/png", b.depth], + }; + const f = files[asset]; + if (!f) return jsonReply(res, 404, { message: "no such asset" }); + res.writeHead(200, { "content-type": f[0] }); + return void res.end(f[1]); + } + if (req.path === "/photos/cat.png") { + res.writeHead(200, { "content-type": "image/png" }); + return void res.end(req.method === "HEAD" ? undefined : b.png); + } + if (req.method === "POST" && req.path === "/openapi/v1/relief") return jsonReply(res, 202, { result: "relief-1" }); + if (req.method === "DELETE" && req.path === "/openapi/v1/relief/relief-1") return jsonReply(res, 200, {}); + if (req.method === "GET" && req.path === "/openapi/v1/relief") return jsonReply(res, 200, [coloredTask(api.url), depthOnlyTask(api.url)]); + if (req.method === "GET" && req.path === "/openapi/v1/relief/relief-1") return jsonReply(res, 200, coloredTask(api.url)); + if (req.method === "GET" && req.path === "/openapi/v1/relief/depth-1") return jsonReply(res, 200, depthOnlyTask(api.url)); + if (req.method === "GET" && req.path === "/openapi/v1/relief/depth-1/stream") { + res.writeHead(200, { "content-type": "text/event-stream" }); + res.write(`event: message\ndata: ${JSON.stringify({ id: "depth-1", progress: 0, status: "PENDING" })}\n\n`); + return void res.end(`event: message\ndata: ${JSON.stringify(depthOnlyTask(api.url))}\n\n`); + } + return jsonReply(res, 404, { message: "not found" }); + }); + return api; +} + +const posts = (api: MockApi) => api.requests.filter((q) => q.method === "POST"); + +// --------------------------------------------------------------------------- +// Registry +// --------------------------------------------------------------------------- + +test("relief is a v1 task resource on /relief: photo input as JPG/PNG/WebP, task type relief, may charge, every verb", () => { + const d = requireTaskResource("relief"); + assert.deepEqual([...d.commandPath], ["relief"]); + assert.equal(d.base, "v1"); + assert.equal(d.relativePath, "/relief"); + assert.equal(d.endpoint, "/openapi/v1/relief"); + assert.deepEqual([...d.taskTypes], ["relief"]); + assert.equal(d.billing.create, "may-charge"); + assert.equal(d.automaticRetry, false); + assert.deepEqual(d.supports, { create: true, get: true, list: true, delete: true, stream: true }); + assert.deepEqual(d.mediaFields, [{ path: "image_url", kind: "image", many: false, formats: ["jpg", "jpeg", "png", "webp"] }]); + const entry = resourceIndex().find((e) => e.name === "relief"); + assert.deepEqual(entry && { kind: entry.kind, command: entry.command, endpoint: entry.endpoint, verbs: entry.verbs }, { + kind: "task", + command: "meshy relief", + endpoint: "/openapi/v1/relief", + verbs: ["create", "get", "list", "wait", "stream", "delete"], + }); +}); + +test("meshy resources lists relief (local, no key)", async () => { + const r = await runCli(["resources", "--format", "json"]); + assert.equal(r.code, 0, r.stderr); + const items = (parseSingleJson(r.stdout) as { result: { items: Array<{ name: string; kind: string; endpoint: string | null }> } }).result.items; + const relief = items.find((i) => i.name === "relief"); + assert.deepEqual(relief && { kind: relief.kind, endpoint: relief.endpoint }, { kind: "task", endpoint: "/openapi/v1/relief" }); +}); + +// --------------------------------------------------------------------------- +// create: flags → payload +// --------------------------------------------------------------------------- + +test("relief create: flags reach POST /openapi/v1/relief; omitted flags stay out; a local photo goes inline", async () => { + const api = await reliefApi(await bodies()); + try { + const dir = tmpDir(); + const IMAGE = `${api.url}/photos/cat.png`; + const photo = join(dir, "cat.png"); + writeFileSync(photo, await png()); + + // Only the photo: the API's own defaults apply, nothing is pinned. + const minimal = await runCli(["relief", "create", "--image-url", photo, "--async", "--format", "json"], { env: api.env(), cwd: dir }); + assert.equal(minimal.code, 0, minimal.stderr); + assert.equal(posts(api)[0]!.path, "/openapi/v1/relief"); + const first = posts(api)[0]!.json as Record; + assert.deepEqual(Object.keys(first), ["image_url"]); + assert.match(String(first.image_url), /^data:image\/png;base64,/); + const env = parseSingleJson(minimal.stdout) as { command: string; result: { task_id: string; submission: { task_id: string } } }; + assert.equal(env.command, "relief.create"); + assert.equal(env.result.submission.task_id, "relief-1"); + + // The API reference's advanced request. + const advanced = await runCli([ + "relief", "create", "--image-url", IMAGE, "--variant", "high", "--size-mm", "120", "--carving-depth-mm", "10", + "--base-thickness-mm", "3", "--bend-mode", "convex", "--bend-angle", "90", "--color-mapping", "true", + "--target-formats", "glb,obj,stl", "--async", "--format", "json", + ], { env: api.env(), cwd: dir }); + assert.equal(advanced.code, 0, advanced.stderr); + assert.deepEqual(posts(api)[1]!.json, { + image_url: IMAGE, variant: "high", size_mm: 120, carving_depth_mm: 10, base_thickness_mm: 3, + bend_mode: "convex", bend_angle: 90, color_mapping: true, target_formats: ["glb", "obj", "stl"], + }); + + // Depth map only: should_generate_model false, and the variant still shapes the depth map. + const depth = await runCli(["relief", "create", "--image-url", IMAGE, "--depth-only", "--variant", "high", "--async", "--format", "json"], { env: api.env(), cwd: dir }); + assert.equal(depth.code, 0, depth.stderr); + assert.deepEqual(posts(api)[2]!.json, { image_url: IMAGE, variant: "high", should_generate_model: false }); + + // No base plate, engraved, bent along the other axis, every other format; explicit false survives. + const cut = await runCli([ + "relief", "create", "--image-url", IMAGE, "--remove-base", "true", "--removal-threshold", "0.2", "--base-thickness-mm", "0", + "--carving-mode", "engrave", "--bend-mode", "concave", "--bend-axis", "yz", "--mesh-resolution", "2048", + "--target-formats", "usdz,fbx,3mf", "--color-mapping", "false", "--async", "--format", "json", + ], { env: api.env(), cwd: dir }); + assert.equal(cut.code, 0, cut.stderr); + assert.deepEqual(posts(api)[3]!.json, { + image_url: IMAGE, remove_base: true, removal_threshold: 0.2, base_thickness_mm: 0, carving_mode: "engrave", + bend_mode: "concave", bend_axis: "yz", mesh_resolution: 2048, target_formats: ["usdz", "fbx", "3mf"], color_mapping: false, + }); + + // --data merges under the flags (flags win) and is validated like them. + const data = await runCli(["relief", "create", "--data", JSON.stringify({ image_url: IMAGE, size_mm: 80, mesh_resolution: 512 }), "--size-mm", "100", "--async", "--format", "json"], { env: api.env(), cwd: dir }); + assert.equal(data.code, 0, data.stderr); + assert.deepEqual(posts(api)[4]!.json, { image_url: IMAGE, size_mm: 100, mesh_resolution: 512 }); + + // Color for formats that cannot show it is sent as asked, with a warning. + const white = await runCli(["relief", "create", "--image-url", IMAGE, "--color-mapping", "true", "--target-formats", "stl", "--async", "--format", "json"], { env: api.env(), cwd: dir }); + assert.equal(white.code, 0, white.stderr); + assert.deepEqual(posts(api)[5]!.json, { image_url: IMAGE, color_mapping: true, target_formats: ["stl"] }); + assert.deepEqual((parseSingleJson(white.stdout) as { warnings: Array<{ code: string }> }).warnings.map((w) => w.code), ["color_not_in_formats"]); + } finally { + await api.close(); + } +}); + +test("relief create: a broken rule is refused before any request — by flag or by --data", async () => { + const api = await reliefApi(await bodies()); + try { + const dir = tmpDir(); + const gif = join(dir, "cat.gif"); + writeFileSync(gif, await sharp({ create: { width: 32, height: 32, channels: 3, background: { r: 1, g: 2, b: 3 } } }).gif().toBuffer()); + // The full rule set is covered in-process below; these prove the rules run before anything is sent. + const cases: Array<[string[], RegExp]> = [ + [[], /provide --image-url/], + [["--image-url", gif], /jpg\/jpeg\/png\/webp only/], + [["--image-url", IMAGE, "--mesh-resolution", "1500.5"], /--mesh-resolution must be an integer from 512 to 2048/], + [["--image-url", IMAGE, "--target-formats", "glb,glb"], /lists 'glb' twice/], + [["--image-url", IMAGE, "--remove-base", "true", "--base-thickness-mm", "2"], /leave out --base-thickness-mm or pass 0/], + [["--image-url", IMAGE, "--depth-only", "--target-formats", "stl"], /--depth-only returns the depth map alone, so --target-formats does not apply/], + [["--image-url", IMAGE, "--data", '{"should_generate_model":false,"size_mm":80}'], /--size-mm does not apply/], + ]; + for (const [args, message] of cases) { + const r = await runCli(["relief", "create", ...args, "--async", "--format", "json"], { env: api.env(), cwd: dir }); + assert.equal(r.code, 2, `${args.join(" ")}: ${r.stdout}`); + assert.match((parseSingleJson(r.stdout) as { error: { message: string } }).error.message, message, args.join(" ")); + } + assert.equal(api.requests.length, 0, "nothing reaches the API"); + } finally { + await api.close(); + } +}); + +test("validateReliefPayload: ranges, the base-thickness rule, and settings the API would not use", () => { + const ok = (extra: Record) => assert.doesNotThrow(() => validateReliefPayload({ image_url: IMAGE, ...extra }), JSON.stringify(extra)); + const refused = (extra: Record, message: RegExp) => + assert.throws(() => validateReliefPayload({ image_url: IMAGE, ...extra }), (err: unknown) => err instanceof UsageError && message.test(err.message), JSON.stringify(extra)); + + // Range edges are inclusive. + ok({ size_mm: 20, carving_depth_mm: 0, bend_mode: "convex", bend_angle: 0, mesh_resolution: 512, base_thickness_mm: 0.1 }); + ok({ size_mm: 250, carving_depth_mm: 60, bend_mode: "concave", bend_angle: 360, mesh_resolution: 2048, base_thickness_mm: 10 }); + ok({ remove_base: true, removal_threshold: 0.01 }); + ok({ remove_base: true, removal_threshold: 1, base_thickness_mm: 0 }); + ok({ variant: "" }); // the API reads "" as not sent + ok({ should_generate_model: false, variant: "low" }); + ok({ should_generate_model: true, size_mm: 60 }); + ok({ bend_mode: "off" }); + ok({ remove_base: true, carving_depth_mm: 0 }); // documented: an empty model, still billed (a warning, not a refusal) + for (const [extra, message] of [ + [{ size_mm: 250.5 }, /--size-mm must be a number from 20 to 250/], + [{ size_mm: "60" }, /--size-mm must be a number/], + [{ carving_depth_mm: -1 }, /--carving-depth-mm must be a number from 0 to 60/], + [{ remove_base: true, removal_threshold: 0 }, /--removal-threshold must be a number from 0.01 to 1/], + [{ bend_mode: "convex", bend_angle: 361 }, /--bend-angle must be a number from 0 to 360/], + [{ mesh_resolution: 4096 }, /--mesh-resolution must be an integer from 512 to 2048/], + [{ mesh_resolution: 1024.5 }, /an integer/], + [{ base_thickness_mm: 0 }, /--base-thickness-mm must be a number from 0.1 to 10/], + [{ base_thickness_mm: 11 }, /--base-thickness-mm must be a number from 0.1 to 10/], + [{ remove_base: true, base_thickness_mm: 1 }, /--remove-base true builds no base plate/], + [{ removal_threshold: 0.5 }, /--removal-threshold applies with --remove-base true only/], + [{ remove_base: false, removal_threshold: 0.5 }, /--removal-threshold applies with --remove-base true only/], + [{ bend_angle: 90 }, /--bend-angle applies with --bend-mode convex or concave only/], + [{ bend_mode: "off", bend_axis: "yz", bend_angle: 90 }, /--bend-axis and --bend-angle apply with --bend-mode/], + [{ target_formats: [] }, /--target-formats must list at least one/], + [{ target_formats: "glb" }, /--target-formats must list at least one/], + [{ target_formats: ["GLB"] }, /unknown format "GLB"/], + [{ target_formats: ["obj", "mtl"] }, /unknown format "mtl".*OBJ comes with its MTL/], + [{ target_formats: ["stl", "3mf", "stl"] }, /lists 'stl' twice/], + [{ variant: "medium" }, /--variant must be one of low \| high/], + [{ carving_mode: "deboss" }, /--carving-mode must be one of emboss \| engrave/], + [{ bend_mode: "twist" }, /--bend-mode must be one of off \| convex \| concave/], + [{ bend_mode: "convex", bend_axis: "xy" }, /--bend-axis must be one of xz \| yz/], + [{ remove_base: "true" }, /--remove-base must be true or false/], + [{ color_mapping: 1 }, /--color-mapping must be true or false/], + [{ should_generate_model: "false" }, /should_generate_model \(--depth-only\) must be true or false/], + [{ should_generate_model: false, color_mapping: true, mesh_resolution: 1024 }, /--mesh-resolution, --color-mapping do not apply/], + [{ should_generate_model: false, remove_base: false }, /--remove-base does not apply/], + ] as Array<[Record, RegExp]>) { + refused(extra, message); + } + assert.throws(() => validateReliefPayload({}), /provide --image-url/); + assert.throws(() => validateReliefPayload({ image_url: "" }), /provide --image-url/); +}); + +test("relief create warns when the request likely misses what was meant", () => { + assert.deepEqual(reliefWarnings({ remove_base: true, carving_depth_mm: 0 }).map((w) => w.code), ["empty_model"]); + assert.deepEqual(reliefWarnings({ remove_base: false, carving_depth_mm: 0 }), [], "the base plate is still a model"); + assert.deepEqual(reliefWarnings({ color_mapping: true, target_formats: ["stl", "3mf"] }).map((w) => w.code), ["color_not_in_formats"]); + assert.match(reliefWarnings({ color_mapping: true, target_formats: ["stl"] })[0]!.message, /stl carries no color/); + assert.deepEqual(reliefWarnings({ color_mapping: true, target_formats: ["stl", "glb"] }), []); + assert.deepEqual(reliefWarnings({ color_mapping: true }), [], "the default formats include GLB"); + assert.deepEqual(reliefWarnings({ color_mapping: false, target_formats: ["stl"] }), []); +}); + +// --------------------------------------------------------------------------- +// get / list / delete / stream +// --------------------------------------------------------------------------- + +test("relief get/list/delete use /openapi/v1/relief; the task view carries the depth map, MTL and 3MF", async () => { + const api = await reliefApi(await bodies()); + try { + const get = await runCli(["relief", "get", "relief-1", "--format", "json"], { env: api.env() }); + assert.equal(get.code, 0, get.stderr); + const task = (parseSingleJson(get.stdout) as { result: { task: Record } }).result.task; + assert.equal(task["resource"], "relief"); + assert.equal(task["type"], "relief"); + assert.equal(task["consumed_credits"], 20); + assert.match(String(task["depth_map_url"]), /\/depth\.png\?/); + assert.deepEqual(Object.keys(task["model_urls"] as object).sort(), ["3mf", "glb", "mtl", "obj", "stl"]); + assert.deepEqual(Object.keys((task["texture_urls"] as object[])[0]!), ["base_color"]); + + const depth = await runCli(["relief", "get", "depth-1", "--format", "json"], { env: api.env() }); + const depthTask = (parseSingleJson(depth.stdout) as { result: { task: Record } }).result.task; + assert.deepEqual(depthTask["model_urls"], {}); + assert.equal(depthTask["thumbnail_url"], ""); + assert.match(String(depthTask["depth_map_url"]), /depth-1\/output\/depth\.png/); + + const list = await runCli(["relief", "list", "--page-size", "2", "--format", "json"], { env: api.env() }); + assert.equal(list.code, 0, list.stderr); + assert.equal((parseSingleJson(list.stdout) as { result: { count: number } }).result.count, 2); + + const del = await runCli(["relief", "delete", "relief-1", "--format", "json"], { env: api.env() }); + assert.equal(del.code, 0, del.stderr); + assert.equal((parseSingleJson(del.stdout) as { result: { deleted: boolean } }).result.deleted, true); + + assert.deepEqual(api.requests.map((q) => `${q.method} ${q.path}`), [ + "GET /openapi/v1/relief/relief-1", + "GET /openapi/v1/relief/depth-1", + "GET /openapi/v1/relief", + "DELETE /openapi/v1/relief/relief-1", + ]); + assert.match(api.requests[2]!.url, /page_size=2/); + } finally { + await api.close(); + } +}); + +// --------------------------------------------------------------------------- +// -o and meshy download +// --------------------------------------------------------------------------- + +test("relief -o: models (OBJ with its MTL), the texture, the depth map and the preview; a depth-only task saves the depth map alone", async () => { + const b = await bodies(); + const api = await reliefApi(b); + try { + const dir = tmpDir(); + const out = join(dir, "relief"); + const r = await runCli(["relief", "get", "relief-1", "-o", out, "--format", "json"], { env: api.env(), cwd: dir }); + assert.equal(r.code, 0, r.stderr); + const env = parseSingleJson(r.stdout) as { result: { downloads: { state: string; files: Array<{ key: string; status: string }>; skipped: unknown[] } } }; + assert.equal(env.result.downloads.state, "completed"); + assert.deepEqual(env.result.downloads.files.map((f) => f.key), [ + "model.glb", "model.stl", "model.obj", "model.mtl", "model.3mf", "depth_map", "thumbnail.primary", "texture.0.base_color", + ]); + assert.ok(env.result.downloads.files.every((f) => f.status === "written")); + assert.deepEqual(env.result.downloads.skipped, [], "an OBJ does not embed its texture, so the texture is saved"); + assert.deepEqual(readdirSync(out).sort(), [ + "depth_map.png", "meta.json", "model.3mf", "model.glb", "model.mtl", "model.obj", "model.stl", "texture_0_base_color.png", "thumbnail.png", + ]); + assert.ok(readFileSync(join(out, "depth_map.png")).equals(b.depth), "the 16-bit depth map is saved byte for byte"); + assert.match(readFileSync(join(out, "model.mtl"), "utf8"), /map_Kd texture_0_base_color\.png/, "the MTL points at the saved texture"); + + // Depth map only, followed over SSE: one file plus the sidecar. + const depthOut = join(dir, "depth"); + const s = await runCli(["relief", "stream", "depth-1", "-o", depthOut, "--format", "json"], { env: api.env(), cwd: dir }); + assert.equal(s.code, 0, s.stderr); + const sEnv = parseSingleJson(s.stdout) as { result: { task: { status: string }; downloads: { files: Array<{ key: string }> } } }; + assert.equal(sEnv.result.task.status, "SUCCEEDED"); + assert.deepEqual(sEnv.result.downloads.files.map((f) => f.key), ["depth_map"]); + assert.deepEqual(readdirSync(depthOut).sort(), ["depth_map.png", "meta.json"]); + + // A file path picks the file of that format; a model the depth-only task does not have is refused, naming what it has. + const stl = join(dir, "plaque.stl"); + const one = await runCli(["relief", "get", "relief-1", "-o", stl, "--format", "json"], { env: api.env(), cwd: dir }); + assert.equal(one.code, 0, one.stderr); + assert.equal(readFileSync(stl, "utf8"), "solid relief\nendsolid relief\n"); + const none = await runCli(["relief", "get", "depth-1", "-o", join(dir, "plaque.glb"), "--format", "json"], { env: api.env(), cwd: dir }); + // The task is fine and nothing was saved; the class is the existing one for an -o path that cannot be written (local_io, 11). + assert.equal(none.code, 11, none.stdout); + assert.match((parseSingleJson(none.stdout) as { error: { message: string } }).error.message, /does not name exactly one file of task depth-1 \(it has depth_map\.png\)/); + assert.ok(!existsSync(join(dir, "plaque.glb"))); + } finally { + await api.close(); + } +}); + +test("meshy download on a relief task: --asset depth_map, --kind depth_map, OBJ with MTL and texture; a missing format names the ones the task has", async () => { + const b = await bodies(); + const api = await reliefApi(b); + try { + const dir = tmpDir(); + const taskJson = join(dir, "relief.json"); + writeFileSync(taskJson, JSON.stringify(coloredTask(api.url))); + const depthJson = join(dir, "depth.json"); + writeFileSync(depthJson, JSON.stringify(depthOnlyTask(api.url))); + const run = (args: string[]) => runCli(["download", ...args, "--format", "json"], { env: api.env({ MESHY_API_KEY: undefined }), cwd: dir }); + + const list = await run(["--task-json", taskJson, "--list"]); + assert.equal(list.code, 0, list.stderr); + const listed = parseSingleJson(list.stdout) as { result: { source: { resource: string }; assets: Array<{ key: string; kind: string; filename: string }> } }; + assert.equal(listed.result.source.resource, "relief", "the task type maps a saved task to its resource"); + const depthMap = listed.result.assets.find((a) => a.key === "depth_map"); + assert.deepEqual(depthMap && [depthMap.kind, depthMap.filename], ["depth_map", "depth_map.png"]); + + const byKey = await run(["--task-json", taskJson, "--asset", "depth_map", "--output", join(dir, "heightmap.png")]); + assert.equal(byKey.code, 0, byKey.stderr); + assert.ok(readFileSync(join(dir, "heightmap.png")).equals(b.depth)); + + const byKind = await run(["--task-json", depthJson, "--kind", "depth_map", "--output-dir", join(dir, "by-kind")]); + assert.equal(byKind.code, 0, byKind.stderr); + assert.deepEqual(readdirSync(join(dir, "by-kind")), ["depth_map.png"]); + + // A depth map is never transcoded to 8 bits: asked for .jpg, it is kept as PNG under its own extension. + const jpg = await run(["--task-json", depthJson, "--asset", "depth_map", "--output", join(dir, "depth.jpg")]); + assert.equal(jpg.code, 0, jpg.stderr); + assert.ok(readFileSync(join(dir, "depth.png")).equals(b.depth)); + assert.ok(!existsSync(join(dir, "depth.jpg"))); + assert.ok((parseSingleJson(jpg.stdout) as { warnings: Array<{ code: string }> }).warnings.some((w) => w.code === "extension_corrected")); + + const obj = await run(["--task-json", taskJson, "--model-format", "obj", "--output-dir", join(dir, "obj")]); + assert.equal(obj.code, 0, obj.stderr); + assert.deepEqual(readdirSync(join(dir, "obj")).sort(), ["model.mtl", "model.obj", "texture_0_base_color.png"]); + + const fbx = await run(["--task-json", taskJson, "--model-format", "fbx", "--output-dir", join(dir, "fbx")]); + assert.equal(fbx.code, 2, fbx.stdout); + assert.match((parseSingleJson(fbx.stdout) as { error: { message: string } }).error.message, /no model asset in format 'fbx' \(the task has glb, stl, obj, mtl, 3mf\)/); + const depthGlb = await run(["--task-json", depthJson, "--model-format", "glb", "--output-dir", join(dir, "glb")]); + assert.equal(depthGlb.code, 2, depthGlb.stdout); + assert.match((parseSingleJson(depthGlb.stdout) as { error: { message: string } }).error.message, /the task has no model file/); + } finally { + await api.close(); + } +}); + +test("relief assets: stable keys and file names; -o keeps the depth map, and leaves a texture GLB/STL already carry", () => { + const host = "https://assets.example.com"; + const relief = requireTaskResource("relief"); + const e = enumerateAssets(coloredTask(host), relief); + assert.deepEqual(e.assets.map((a) => [a.key, a.kind, a.format, a.filename]), [ + ["model.glb", "model", "glb", "model.glb"], + ["model.stl", "model", "stl", "model.stl"], + ["model.obj", "model", "obj", "model.obj"], + ["model.mtl", "model", "mtl", "model.mtl"], + ["model.3mf", "model", "3mf", "model.3mf"], + ["depth_map", "depth_map", "png", "depth_map.png"], + ["thumbnail.primary", "thumbnail", "png", "thumbnail.png"], + ["texture.0.base_color", "texture", "png", "texture_0_base_color.png"], + ]); + assert.deepEqual(e.assets.find((a) => a.key === "model.obj")!.dependencies, ["model.mtl", "texture.0.base_color"]); + assert.deepEqual(e.unknown_urls, []); + + const depthOnly = enumerateAssets(depthOnlyTask(host), relief); + assert.deepEqual(depthOnly.assets.map((a) => a.key), ["depth_map"], "an empty thumbnail_url is no asset"); + + const glbStl = { ...coloredTask(host), model_urls: { glb: `${host}/m.glb`, stl: `${host}/m.stl` } }; + const sel = selectDefaultAssets(enumerateAssets(glbStl, relief).assets); + assert.deepEqual(sel.selected.map((a) => a.key), ["model.glb", "model.stl", "depth_map", "thumbnail.primary"]); + assert.deepEqual(sel.skipped.map((s) => [s.asset.key, s.reason]), [["texture.0.base_color", "embedded_textures"]]); +}); + +test("pretty view of a relief task names the depth map", () => { + const card = (raw: Record) => + renderView("relief.get", okEnvelope("relief.get", { + task: toTaskView(raw, { descriptor: requireTaskResource("relief") }), + submission: { state: "accepted", operation_id: null }, + downloads: { state: "not_requested", files: [], metadata_path: null }, + saved_json: null, + }), plain); + assert.match(card(coloredTask("https://assets.example.com")), /^Assets {3}glb, stl, obj, mtl, 3mf · depth map · textures: base_color · thumbnail$/m); + assert.match(card(depthOnlyTask("https://assets.example.com")), /^Assets {3}depth map$/m); +});