# @isis/3d-asset-library Searchable 3D asset marketplace infrastructure for Isis. ## Purpose `@isis/3d-asset-library` is the Phase 71 asset-library domain package. The scaffold is intentionally split into five future-facing modules so the remaining `71.6.x` tasks can land without reorganizing the library: - `core`: metadata, ingestion, thumbnails, search, taxonomy, and filters - `variation`: controlled remix, palette remapping, scale normalization, and kit generation - `style`: project style profiles, constrained generation, and style scoring - `provenance`: generation traceability, licensing, compliance, and embedded export metadata - `community`: upload validation, ratings, collections, download conversion, and usage analytics ## Implemented Surface `71.6.1.1` establishes the Nx project scaffold, package exports, TypeScript and Vitest configuration, typed marketplace manifest, and module blueprints that track all remaining `71.6.x` deferred tasks. This gives the next tasks a stable home for: - asset metadata and technical extraction contracts - ingestion and preview-generation orchestration - keyword, semantic, and similarity search surfaces - licensing and provenance-aware catalog governance - community publishing, collection, and analytics workflows `71.6.1.2` now implements the canonical 3D asset metadata schema in `src/core/metadata-schema.ts`. The core schema covers: - normalized `name`, `description`, and deduplicated `tags` - marketplace-ready `category`, `polyCount`, `textureResolution`, and `format` - explicit license descriptors with commercial-use and attribution flags - structured generation parameters for provider, model, prompt, seed, quality, target polycount, and requested output format - source-model linkage for remixed or derived assets - filter-ready facet extraction for category, format, license, provider, model, polycount bucket, texture bucket, and tags `71.6.1.3` now implements the ingestion pipeline in `src/core/ingestion-pipeline.ts`. The default pipeline provides: - source upload persistence through an in-memory artifact-store contract - automatic 3D metadata extraction for GLB, glTF, OBJ, FBX, USD, PLY, and STL through existing `@isis/3d-generation` parsers plus lightweight header inspection where appropriate - normalized metadata assembly that reuses the canonical schema from `71.6.1.2` - six-view thumbnail generation during ingest, with Blender-backed PNG renders for `front`, `right`, `back`, `left`, `top`, and `bottom` plus a deterministic SVG fallback when Blender is unavailable - search-document creation plus in-memory indexing so every ingest emits a searchable record immediately `71.6.1.4` now adds `src/core/thumbnail-renderer.ts`, which provides: - a dedicated Blender-backed asset thumbnail renderer for the canonical six-view set used elsewhere in Isis (`front`, `right`, `back`, `left`, `top`, `bottom`) - reusable render-script generation and Blender-availability helpers so server environments can promote draft thumbnails into real PNG renders - ingestion integration that prefers true rendered thumbnails but still keeps the pipeline portable in environments where Blender is not installed `71.6.1.5` now adds `src/core/turntable-preview.ts`, which provides: - Blender-driven frame rendering for animated asset turntables using the same asset import and lighting conventions as the six-view thumbnail renderer - FFmpeg-based GIF, MP4, and WebM assembly so asset previews can ship as either lightweight animation or video, with GIF as the default catalog format - ingestion integration that stores a `preview-animation` artifact per asset when the renderer succeeds, while cleanly degrading to `null` in environments without Blender or FFmpeg `71.6.1.6` now upgrades the in-memory asset search index with real full-text search over `name`, `description`, and `tags`. The search layer now provides: - weighted inverted indexes over `title`, `description`, `tags`, and the aggregate `searchText` field emitted by ingestion - BM25-style ranking with optional fuzzy term matching for typo tolerance - query-time highlights so consumers can explain why an asset matched `71.6.1.7` now adds CLIP-style semantic search in `src/core/semantic-search.ts` and wires it into the default in-memory asset index. The semantic layer now provides: - a CLIP-shaped embedding-provider contract with `embedText` and `embedImage` hooks so production deployments can swap in a real aligned model - a deterministic local provider for development and tests that keeps the package runnable without external inference infrastructure - ingestion-time semantic indexing over each asset's canonical metadata text and generated thumbnail set - semantic retrieval by text description or reference image, with late fusion of text and image branches plus per-hit signal breakdowns for debugging ranking `71.6.1.8` now formalizes the category taxonomy in `src/core/metadata-schema.ts` instead of treating categories as a flat enum only. The taxonomy layer now provides: - stable group-level paths such as `world-building/furniture` and `props-and-gear/weapons` for marketplace browsing and future filters - alias, keyword, and suggested-tag metadata for every primary asset category - lookup and resolution helpers that normalize common category synonyms into the canonical marketplace categories - taxonomy-driven category inference during ingestion so automatic classification now reuses the same registry that powers category browsing and faceting `71.6.1.9` now adds `src/core/filters.ts` and wires filter-aware discovery into `src/core/ingestion-pipeline.ts`. The filter layer now provides: - typed filter contracts plus a reusable builder/engine for range-based and exact-match catalog constraints - catalog browse filters for poly count, texture resolution, format, license, style, category, provider, and generation model - style inference during metadata faceting so assets can be filtered by marketplace-relevant looks such as `low-poly`, `game-ready`, `photorealistic`, `archviz`, and `cartoon` - facet aggregation that keeps counts useful during drill-down by excluding the currently requested facet from its own aggregation scope - integration across filter-only browse, full-text search, and semantic search so all three retrieval paths honor the same filter contract `71.6.1.10` now extends the semantic index with asset-to-asset nearest-neighbor retrieval so the catalog can answer "show me assets like this one" directly from an existing library item. The similar-search layer now provides: - multimodal nearest-neighbor ranking seeded from the source asset's own text and thumbnail embeddings, with image similarity weighted above caption similarity by default - a dedicated `findSimilarAssets()` API on the in-memory catalog index that resolves an asset by id and returns related catalog entries with optional per-branch similarity signals - filter and facet support on similar-asset results so "assets like this, but only game-ready/commercial/4k" uses the same contract as browse and search - deterministic tests that verify sword-to-sword retrieval outranks unrelated furniture assets and that filter-aware facet counts remain stable `71.6.2.1` now adds `src/variation/asset-variation-generation.ts`, which provides: - deterministic variation planning for any catalog asset, producing `N` controllable variants from a single library source with stable seeds and repeatable trait coverage - explicit variance controls across geometry, materials, condition, color, detail, and scale, plus lock flags for category/style/scale/license-sensitive constraints - fully runnable text-to-3D requests for every planned variant and optional image-conditioned requests when source reference images are available - catalog-ready draft metadata per variant, including inherited license data, derived-from-asset source linkage, expected poly and texture budgets, and remix-aware generation parameters - guardrails and warnings for restrictive source licenses, unsupported output formats, missing stored prompts, and overly image-heavy conditioning plans `71.6.2.2` now adds `src/variation/asset-style-transfer.ts`, which provides: - asset-to-asset material transfer planning that preserves the target asset's geometry while applying the donor asset's material language and inferred style - strategy selection between direct PBR transfer, preview-image-driven style transfer, and target-material extraction when the geometry asset does not advertise transferable maps - channel-aware transfer plans for `albedo`, `normal`, `roughness`, `metallic`, and `metallicRoughness`, with profile-specific strengths and UV/detail preservation settings - catalog-ready transfer drafts that merge geometry-source and style-source license constraints, preserve geometry provenance, and attach donor-style lineage in structured generation metadata - deterministic tests covering direct map transfer, preview-image fallback, extraction planning, merged-license restrictions, and invalid donor inputs `71.6.2.3` now adds `src/variation/asset-palette-remapping.ts`, which provides: - material-safe palette remap planning that retargets asset color schemes while keeping roughness, metallic, normal, and UV detail constraints explicit in the execution plan - strategy selection between direct texture remapping, mask-assisted remapping, and extraction-first remapping when the catalog asset does not advertise an editable albedo map - source-palette inference from prompts or catalog metadata, target-palette presets plus custom hex support, luminance-preserving role mapping, and family-aware guardrails for metal, wood, stone, fabric, glass, and other material classes - catalog-ready palette-remap drafts with derived-from-asset provenance, structured palette lineage in generation metadata, and deterministic warnings for restrictive licenses, low texture budgets, and artist-review edge cases - deterministic tests covering protected PBR remaps, extraction planning, preset suggestion, palette expansion, and invalid custom color rejection `71.6.2.4` now adds `src/variation/asset-scale-normalization.ts`, which provides: - real-world scale normalization planning that resolves asset size from measured scan data, catalog dimension metadata, or raw mesh bounds before applying a uniform normalization transform - archetype-aware target profiles for common assets such as characters, chairs, tables, barrels, mugs, candles, swords, doors, columns, vehicles, and trees, with category-level fallbacks when no specific archetype matches - scene-ready normalization transforms that preserve proportions, carry unit scale into metric scene space, plan up-axis conversion, and emit usage-aware DCC and engine notes for consistent composition - catalog-ready scale-normalization drafts with structured measurement lineage, target profile metadata, and warnings for category-only priors, unitless mesh bounds, extreme scale factors, and restrictive licenses - deterministic tests covering scan-measured normalization, unitless mesh-bounds normalization, metric mesh-bounds normalization, and missing-measurement rejection `71.6.2.5` now adds `src/variation/asset-kit-generation.ts`, which provides: - deterministic themed kit planning from a single brief, resolving either an explicit item list, a theme preset, or a hybrid of both for matching asset sets - shared kit-style profiles that keep material language, palette, wear level, scale class, atlas strategy, and lighting reference coherent across every planned asset in the set - per-item kit asset plans with role-aware quantities, target dimensions, production-ready text-to-3D requests, and catalog drafts that preserve marketplace metadata expectations - pack-level coverage summaries and marketplace-facing draft metadata so a kit can be reviewed as a cohesive bundle instead of disconnected assets - deterministic tests covering medieval tavern explicit kits, preset fallback, deterministic repeatability, and empty-brief rejection `71.6.3.1` now adds `src/style/project-style-profile.ts`, which provides: - deterministic project style-profile planning from a brief, generating a reusable project-wide visual identity contract instead of one-off prompt text - preset-backed and inference-backed style baselines covering grounded PBR, stylized adventure, low-poly, anime, cinematic hard-surface, and archviz project directions - normalized color palettes, material-property bands, per-category poly-budget rules, and texture-style directives that later generation and scoring tasks can reuse directly - category-aware asset directives plus prompt guidance so downstream 3D asset generation can preserve palette, material hierarchy, silhouette language, and atlas/budget constraints consistently - deterministic tests covering cinematic hard-surface profiles, inferred low-poly mobile profiles, stylized palette/material overrides, and empty brief rejection `71.6.3.2` now adds `src/style/style-constrained-generation.ts`, which provides: - style-constrained 3D generation planning from an existing project style profile, turning profile rules into runnable text-to-3D or image-conditioned requests - explicit style-lock execution payloads with `style_profile_id`, `use_style_lock`, lock strength, palette locks, style anchors, and continuity dimensions suitable for downstream workflow orchestration - category-aware budget, material, silhouette, and texture enforcement that reuses the project profile's asset directives while falling back safely when a request goes outside the original profile scope - catalog-ready draft metadata for new generated assets, including the new `style-constrained-generation` mode in the canonical metadata schema plus structured custom parameters for style locks and directive lineage - deterministic tests covering text-conditioned plans, image-conditioned plans, metadata-schema compatibility, fallback directive warnings, textureless STL output handling, and invalid request rejection `71.6.3.3` now adds `src/style/style-post-processing.ts`, which provides: - project-style-aware post-processing planning for existing generated assets, wrapping palette realignment, profile-driven material retargeting, and optional donor-assisted style transfer behind a single workflow contract - automatic strategy selection between palette-only realignment, profile-material retargeting, and reference-assisted hybrid adaptation based on the project texture style, the asset's texture budget, and whether a donor style asset is available - continuity-ready execution payloads with `continuity_style_*` overrides, palette locks, style anchors, processing-format decisions, and nested execution requests for palette-remap and style-transfer substeps - catalog-ready draft metadata for the derived asset, including the new `style-post-process-transfer` generation mode plus preserved source-asset lineage and project-style custom parameters - deterministic tests covering profile-driven retargeting, donor-assisted hybrid plans, fallback directives for out-of-scope categories, and metadata-schema compatibility for the new workflow mode `71.6.3.4` now adds `src/style/style-consistency-scoring.ts`, which provides: - profile-aware style consistency scoring that measures category fit, inferred style language, palette alignment, material response, poly-budget adherence, texture treatment, and shape-language fit for any catalog asset - support for high-confidence measured observations such as dominant colors, material-property coverage, texture-treatment analysis, and shape cues, while still degrading gracefully to lower-confidence intent metadata when those signals are not yet available - review-ready outputs with weighted per-dimension breakdowns, locked-dimension divergence detection, approval/manual-review/reject decisions, and prioritized remediation recommendations that point toward palette remap, material retargeting, style-locked regeneration, or richer observation capture - deterministic tests covering strong profile matches, clear aesthetic mismatches, and metadata-only/manual-review fallback scoring `71.6.3.5` now adds `src/style/reference-sheet-extraction.ts`, which provides: - reference-sheet analysis planning for concept art, style guides, moodboards, material boards, color scripts, and turnaround sheets so style profiles can be derived from actual art direction artifacts instead of hand-written briefs - deterministic extraction of style, palette, material, category, platform, shape-language, and texture-treatment cues from sheet metadata, OCR text, annotations, swatches, and supplied material observations - a synthesized project brief that feeds directly into `planThreeDAssetProjectStyleProfile`, keeping automatic reference-driven extraction on the same canonical style-profile contract as manually authored project briefs - workflow-ready multimodal analysis requests that specify BLIP-2 captioning, CLIP semantic alignment, and Segment Anything segmentation so production deployments can deepen analysis when raw image payloads are available - deterministic tests covering cinematic hard-surface sheet extraction, stylized-adventure extraction from moodboards and color scripts, and request validation for empty sheet sets `71.6.4.1` now adds `src/provenance/generation-provenance-tracking.ts`, which provides: - deterministic provenance records for 3D assets, including exact generation parameters, source-model linkage, prompt fingerprints, and stable record hashes suitable for storage or compliance review - lineage merging across upstream provenance records so derived assets preserve root asset ancestry, inherited pipeline steps, and derivation depth instead of resetting history on every remix - structured post-processing capture from both explicit API inputs and embedded generation metadata, covering DCC tools, model versions, parameters, notes, and source asset references for replayability - reproducibility scoring with `replay-ready`, `partial`, and `opaque` status outputs plus warnings for missing prompt, seed, workflow, or post-process detail - audit context capture for `projectId`, `actorId`, and `sessionId` so catalog governance can trace who generated or modified an asset inside a larger Isis workflow `71.6.4.2` now adds `src/provenance/license-assignment.ts`, which provides: - canonical license assignment for 3D assets across `cc0`, `cc-by`, `commercial`, `non-commercial`, and `project-restricted`, with conservative fallback into `custom` or `unknown` when the evidence is not strong enough - inference from source references and terms URLs using the same license vocabulary already present elsewhere in the repo, so imported assets can enter the catalog with normalized policy instead of raw free-form strings - restrictive lineage merging for derived assets, preserving upstream attribution and non-commercial constraints rather than letting downstream remixes silently broaden rights - distribution-intent evaluation for `internal`, `public-catalog`, `commercial-marketplace`, and `client-delivery`, including automatic blocking when the requested release channel conflicts with the resolved policy - provenance-aware review gating so `partial` and `opaque` generation history can stop risky public or commercial license assignment before later C2PA and export steps build on bad metadata `71.6.4.3` now adds `src/provenance/asset-usage-tracking.ts`, which provides: - an in-memory usage ledger that answers which projects, collections, scenes, render flows, and delivery bundles currently reference a given 3D asset - deterministic usage identifiers keyed by asset, project, and usage reference so repeated registrations upsert cleanly instead of creating compliance-noise duplicates - license-aware compliance evaluation for every usage registration, including public publishing and marketplace-release gating plus attribution enforcement when a resolved license requires visible credit - asset-level and project-level compliance summaries that expose active versus released usage counts, blocked relationships, and attribution-sensitive dependencies for downstream catalog governance - release tracking that preserves first-use history while allowing individual usages to be retired cleanly from scenes, packages, or client-delivery flows `71.6.4.4` now adds `src/provenance/c2pa-metadata-embedding.ts`, which provides: - sign-ready C2PA manifest drafts for 3D assets, with explicit `claim_generator` metadata, signer envelopes, assertion hashing, and `c2pa.claim.v2` claim assembly aligned to the official Content Credentials guidance - mandatory `c2pa.actions` assertion generation that starts with `c2pa.created` for de novo AI assets or `c2pa.opened` for derived assets, while attaching the trained-algorithmic `digitalSourceType` expected for generative provenance labeling - ingredient assertion support for upstream assets so remixed or style-adapted library assets preserve parent relationships instead of flattening lineage - Oshun-specific custom assertions for asset metadata, exact generation provenance, and license state so later validators and export routines can embed richer 3D-specific evidence than the base C2PA envelope carries alone - format-aware embedding instructions for glTF extras, USD custom layer data, and sidecar manifests, with hard-binding and signing intentionally deferred to the final export stage where the serialized asset bytes actually exist `71.6.4.5` now adds `src/provenance/embedded-provenance-export.ts`, which provides: - actual container mutation for provenance-aware asset exports instead of planner-only instructions, covering GLB JSON-chunk rewriting and USDA/USD `customLayerData` injection - GLB embedding under `asset.extras.oshun.c2pa`, preserving any existing extras while adding manifest ids, claim summaries, provenance record hashes, and an export-generator trail on the glTF `asset.generator` field - USD ASCII embedding that merges or creates `customLayerData` entries for the C2PA manifest id, claim packet, and provenance record summary without discarding pre-existing layer metadata - sidecar `*.c2pa.json` manifest emission alongside the embedded export so signing, audit, and downstream verification workflows still have the full manifest draft available outside the container - deterministic tests covering GLB chunk rewriting, USDA metadata preservation, and rejection of unsupported binary-USD payloads that cannot safely carry the inline metadata block yet `71.6.5.1` now adds `src/community/asset-upload-validation.ts`, which provides: - a community-facing upload pipeline that wraps the existing ingestion stack with file-size, geometry, and external-reference validation before any asset is accepted into the marketplace - automatic rejection of oversized payloads, malformed meshes, empty geometry, triangle-budget violations, and missing referenced files such as OBJ/MTL texture maps or external glTF buffers/images - format-aware validation for OBJ, glTF/GLB, and USD ASCII uploads, including deeper glTF mesh/material checks through the existing `@isis/3d-generation` processing validators - a structured validation report surface that returns normalized issue codes, detected format, technical profile, referenced files, and missing companions so moderation or creator tooling can explain exactly why an upload was blocked - deterministic tests covering successful OBJ ingestion, missing texture rejection, source-size rejection, and empty-geometry rejection `71.6.5.2` now adds `src/community/asset-rating-reviews.ts`, which provides: - a marketplace-ready in-memory rating and review service with deterministic per-reviewer upserts so each creator or buyer keeps one canonical review per asset instead of inflating counts with duplicates - structured moderation states for published, pending, hidden, and rejected reviews, including automatic heuristics for suspicious contact-info or spam-like content and explicit manual moderator overrides - review-quality signals beyond star ratings alone, including helpful/unhelpful voting, verified-usage flags, report reasons, pros/cons aggregation, and sentiment tracking - per-asset summary generation with average rating, Bayesian weighted rating, recommendation ratio, moderation counts, helpfulness totals, and top pros/cons so discovery and analytics layers can rank assets without recalculating review math ad hoc - deterministic tests covering rating aggregation, reviewer upserts, moderation routing, manual publication, and automatic hiding after repeated reports `71.6.5.3` now adds `src/community/asset-collections.ts`, which provides: - an in-memory collection manager for curated sets, scene bundles, style packs, starter packs, and showcase groupings with owner metadata, visibility, publish state, tags, and cover-art selection - asset-level bundle entries with explicit collection roles, pinned/manual ordering, notes, and automatic cover selection that prefers hero assets and stronger community signals when a curator does not pin a cover explicitly - generated bundle manifests that aggregate asset ids, categories, formats, license kinds, poly counts, contributor credits, attribution lines, and a deterministic `*.bundle.json` package name for downstream sharing surfaces - public-publish distribution checks that reuse the library's license assignment/policy logic so non-redistributable assets block public bundles while attribution-friendly assets surface concrete credit lines and actions - deterministic tests covering bundle creation, duplicate prevention, reorder and removal flows, redistribution blocking, and successful public publication for open attribution-compatible collections `71.6.5.4` now adds `src/community/asset-download-api.ts`, which provides: - a server-side download orchestration layer that registers canonical asset artifacts, resolves the best source variant, and serves direct downloads when the requested format already exists - on-demand format conversion through an injected converter contract so a single registered GLB can satisfy requests for FBX, USDZ, or other delivery formats without hard-coding a specific conversion backend into the asset library - conversion-result caching back into the asset's available artifact set, with explicit cache-status reporting for direct, fresh-conversion, and cached-conversion responses - structured download records, per-asset download summaries, and response metadata such as content disposition, package kind, and format/count breakdowns so later analytics can rank assets by real download behavior - deterministic tests covering direct downloads, fresh and cached conversions, preferred-source selection, and summary/record queries for analytics surfaces `71.6.5.5` now adds `src/community/asset-usage-analytics.ts`, which provides: - a usage analytics aggregator that combines registered asset metadata, raw download records, and review summaries into per-asset metrics rather than relying on precomputed leaderboard rows - asset-level metrics for total and recency-window downloads, unique recent downloaders, converted-download counts, rating depth, recommendation ratio, and a transparent trending score that favors recent velocity over stale historical volume - generated overall leaderboards for most-downloaded, trending, and top-rated assets, plus mirrored category-specific rankings for merchandising and discovery surfaces - deterministic analytics workflows that keep zeroed metrics stable for newly registered assets with no usage yet, which is important for dashboard and API consumers that expect complete inventories instead of sparse results - deterministic tests covering overall ranking behavior, trending sensitivity to fresh activity, category reporting, and converted-download metric inclusion ## Verification - `NX_DAEMON=false pnpm nx test @isis/3d-asset-library` - `NX_DAEMON=false pnpm nx lint @isis/3d-asset-library` - `NX_DAEMON=false pnpm nx build @isis/3d-asset-library` - `pnpm tsc -p libs/isis/3d-asset-library/tsconfig.json --noEmit`