GizStack
View .mdOpen in ChatGPTOpen in Claude

gizlang/catalog

CC0 asset catalogs and pinned asset files. A lock names each file an app uses as PATH SHA256 SIZE SOURCE, the line form of the test data lock, and keeps no bytes in git: fetch takes each file into the shared cache once from its SOURCE, checks its hash, and reads it offline after. A SOURCE is an https URL, or URL#MEMBER for one file of a zip archive.

gizlang
import * as Catalog from "gizlang/catalog";

Types

Pin

gizlang
type Pin = { path: string; sha256: string; size: i64; source: string; }

One locked file: where the app reads it, its sha256 in hex, its size, and where its bytes come from.

  • path: string
  • sha256: string
  • size: i64
  • source: string

Asset

gizlang
type Asset = { pins: Vec<Pin>; note: string; }

A catalog entry resolved to its files, and the line that credits it in the lock.

  • pins: Vec<gizlang_catalog.Pin>
  • note: string

Found

gizlang
type Found = { spec: string; name: string; kind: string; tags: Vec<string>; license: string; }

One asset a search found: the SPEC that resolve takes, its name, its kind ("model", "texture" or "hdri"), its words (tags and categories), and its license.

  • spec: string
  • name: string
  • kind: string
  • tags: Vec<string>
  • license: string

Functions

parseLock

gizlang
function parseLock(text: string): Vec<Pin> throws string

The pins of the lock TEXT: one PATH SHA256 SIZE SOURCE line each; # lines are notes.

Effects: fail, alloc.

lockText

gizlang
function lockText(notes: Vec<string>, pins: Vec<Pin>): string

The lock of PINS, sorted by path, under the credit lines NOTES.

Effects: fail, alloc.

cacheFolder

gizlang
function cacheFolder(): string

The folder of fetched objects, named by their sha256: $GIZLANG_CACHE/assets, else ~/.cache/gizlang/assets.

Effects: fail, io, alloc.

fetchPin

gizlang
function fetchPin(pin: Pin, folder: string = cacheFolder()): bytes throws string

PIN's bytes from the cache FOLDER, fetched from its source the first time; a hash or size that differs fails.

Effects: fail, read, write, console, io, alloc.

fetch

gizlang
function fetch(text: string, folder: string = cacheFolder()): Map<string, bytes> throws string

Every file of the lock TEXT, by its path.

Effects: fail, read, write, console, io, alloc.

pin

gizlang
function pin(path: string, source: string, folder: string = cacheFolder()): Pin throws string

A pin of the file at SOURCE, read once to hash it, kept at PATH.

Effects: fail, read, write, console, io, alloc.

polyhaven

gizlang
function polyhaven(id: string, resolution: string): Asset throws string

The Poly Haven asset ID (polyhaven.com, CC0) at RESOLUTION ("1k", "2k", ...), its files under ID/: a model's glTF with its buffer and textures, a texture's color, normal (OpenGL), ARM and displacement maps, or an HDRI's .hdr.

Effects: fail, read, write, console, io, alloc.

ambientcg

gizlang
function ambientcg(id: string, resolution: string): Asset throws string

The ambientCG material ID (ambientcg.com, CC0) at RESOLUTION ("1K-JPG", "2K-JPG", ...): its color, normal (OpenGL), roughness and ambient occlusion maps under ID/, each a member of the material's zip archive.

Effects: fail, read, write, console, io, alloc.

khronos

gizlang
function khronos(name: string): Asset throws string

The Khronos glTF sample model NAME (github.com/KhronosGroup/glTF-Sample-Assets) under NAME/: its .glb, else its .gltf with the buffers and images it names. Each model has its own license: the note quotes its README's.

Effects: fail, read, write, console, io, alloc.

resolve

gizlang
function resolve(spec: string, note: string = ""): Asset throws string

The asset that SPEC names, its files under its ID: polyhaven:ID[@RES], ambientcg:ID[@RES], khronos:NAME, or PATH=URL[#MEMBER] for any one file (a member of a zip archive with #), whose license the caller states in NOTE.

Effects: fail, read, write, console, io, alloc.

notes

gizlang
function notes(text: string): Vec<string>

The credit lines of the lock TEXT.

Effects: fail, alloc.

added

gizlang
function added(text: string, asset: Asset): string throws string

The lock TEXT with ASSET added: its files replace pins of the same path, and its note one of the same catalog spec (SOURCE:ID) or the same text, so the files of one archive share one credit.

Effects: fail, alloc.

polyhavenFound

gizlang
function polyhavenFound(index: Json, words: Vec<string>, kind: string): Vec<Found>

The assets of Poly Haven's index INDEX (GET /assets: each id to its name, type, tags and categories) that match WORDS, of KIND ("" for any), best first.

Effects: fail, alloc.

ambientcgFound

gizlang
function ambientcgFound(found: Json, words: Vec<string>): Vec<Found>

The materials of an ambientCG answer FOUND (GET /api/v2/full_json) that match WORDS, best first.

Effects: fail, alloc.

gizlang
function search(query: string, kind: string = "", most: i64 = 20): Vec<Found> throws string

The public assets that match QUERY (words), of KIND ("model", "texture", "hdri" or "" for any), at most MOST, best first: Poly Haven's models, textures and HDRIs and ambientCG's materials (both CC0), and Khronos's glTF samples by name (each its own license, which resolve's note quotes). Each SPEC goes to resolve, then to a lock (added).

Effects: fail, read, write, console, io, alloc.