Serialization format for transforms

[javagl]

This is not a real "feature request", but rather some brainstorming.

The scripting API is nice and powerful. The CLI is nice and powerful. But I could imagine a layer hidden between both of them - namely, that of a serialization format for transforms.

As an experiment, I created a stupidly-simple function that just takes JSON like this....

[
  {
    "name": "dedup"
  },
  {
    "name": "center",
    "options": {
      "pivot": "center"
    }
  },
  {
    "name": "dequantize"
  },
  {
    "name": "draco",
    "options": {
      "method": "edgebreaker"
    }
  }
]

and translates this into an array of Transform[] objects. This allows something like

const pipeline = JSON.parse(fs.readFileSync("pipeline.json").toString());
const transforms = createTransforms(pipeline);
await document.transform(...transforms);

In general, the possibility to read/write certain configurations of transform sequences could be pretty useful. (And more structured and versatile than a .BAT/.sh file that contains the proper CLI calls...)

I know how complicated this can become. I know many of the caveats of such an approach. If this was supposed to be done 'right', it would involve some work. (I defined a bunch of JSON schemas for dedup/center/... transforms, and these could be trivially translated into TypeScript structures, allowing to safely assemble them programmatically and so on - but doing that thoroughly is not something that can casually be jotted down on a boring afternoon). But I think that there might still be a few relatively low-hanging fruits with that approach.

[donmccurdy]

Hi @javagl! I've thought a little bit about the idea of a JSON representation of the public API and its documentation. For example it would be nice to be able to get help text and validation into the CLI without as much boilerplate as cli.ts currently includes. It's manageable, but wouldn't really scale well to having the API docs and the CLI and a user interface somewhere...

Maybe the closest thing in the project now, the documentation system encodes textureCompress as:

{
    "kind": "Function",
    "name": "textureCompress",
    "source": {
        "text": "packages/functions/src/texture-compress.ts",
        "url": "https://github.com/donmccurdy/glTF-Transform/tree/main/packages/functions/src/texture-compress.ts"
    },
    "tags": {
        "category": "Transforms"
    },
    "params": [
        {
            "name": "_options",
            "type": {
                "path": "/modules/functions/interfaces/TextureCompressOptions",
                "name": "TextureCompressOptions",
                "kind": "Interface"
            }
        }
    ],
    "returns": "Transform",
    "comment": "<p>Optimizes images, optionally resizing<...>"
}

... with a similar structure representing TextureCompressOptions. But that represents the just API, not the particular values and invocations associated with a specific pipeline, so I doubt that's much help to you.

[javagl]

Just to emphasize: There is no problem that needs to be solved right now. It's just a gut feeling that something like this could be cool and useful for certain tasks.
And in doubt, much of this could be developed on top of glTF-Transform, without affecting glTF-Transform itself.

But the point that you brought up is one where one could think about leveraging such an infrastructure inside of glTF-Transform. The idea (that is also ... 'drafted' but not really fully 'implemented' in other things that I've been working on) is roughly speaking: The CLI is parsing the command line arguments, and building a JSON structure. That JSON structure can (if desired) be trivially validated against the schema, using some generic JSON schema validator. Then, there only is a thin layer on top of the API, that translates this (validated) JSON into the proper API calls (and this can then be really be thin and generic).

Yeah. Sounds cool. But it's easier said than done, and raises questions like this:

scale well to having the API docs and the CLI and a user interface somewhere...

I don't know the processes/tools/libraries that are currently used for generating the CLI- and API documentation (although, from just looking at the result, it seems to be sophisticated and powerful). And whether or not it is possible (with which effort) to avoid duplication is indeed an open question.

I'd say that the TSDoc API docs have to exist anyhow, because they are independent of that serialization format after all.
The serialization format would be documented via the JSON schema, including description fields. One question would then be whether it's possible to use this for the CLI documentation - and ideally for both, the help output at the CLI itself, as well as the generated, browsable online documentation of the CLI.
But given that a JSON schema is ... standardized converging to a somewhat stable-ish draft version ..., and it is fully and trivially machine-processable, I think that it would not limit, but rather expand the options here.
(With the seemingly crazy (but at the same time 'obvious') goal of auto-generating a UI with checkboxes, dropdown-lists and sliders from that JSON schema - been there, done that...)

About the example for the textureCompress documentation input (I didn'd quickly find this - does this exist here in the repo?):

This looks like something that already could be stored as a JSON schema. And this includes things like a $ref to the corresponding schema for TextureCompressOptions that can then be resolved cleanly, e.g. for generating the docs, including all valid values and such. The definition of a pipeline (as a sequence of invocations) could then just be an array of objects conforming to that schema (just as I drafted in the first post).

Related to the question about duplication: Right now, the export interface TextureCompressOptions contains the API documentation. Does that 'documentation structure' that you referred to also contain this, as full text (maybe one comment for each parameter or so?).

(Remotely related: I once hacked wetzel to generate TypeScript from JSON schema, but that was only a one-shot thing, because I'm a lazy nerd. There likely are "proper" solutions for stuff like this, but probably not in a form that allows relying on something like that for an actual, evolving API...)