Refactor pipelines around glTF documents

docs/architecture/index.md

@@ -7,7 +7,7 @@ Nodes are referred to as **blocks** in code contexts and **nodes** in UI context
 Sink nodes, or terminal nodes, are **output blocks**.
 Edges are **connections**.
 End points of an edge are **connection points** in code contexts and **ports** in UI contexts.
-The payload carried along an edge is **runtime data**.
+The payload carried along an edge is **runtime data**: what a block processes.
 The type of payload accepted by an end points is defined by its **connection point type**.
 Edges can only be drawn between compatible **connection point types**.
 Inbound end points are block **inputs**.
@@ -17,26 +17,27 @@ Outbound end points are block **outputs**.
 
 Connection points types, in general, come in two forms.
 
-- File: for format- or byte-level operations. Examples: platform I/O
+- File: for format- or byte-level operations. Examples: platform I/O (future)
 - Content: for content-level operations. Examples: removing vertices, updating texture pixels
-- Module: for opt-in operations. Examples: encoders
 
 ## Content
 
-- `Babylon`
+- `Babylon` (future)
     - Runtime data: `Scene` (@babylonjs/core)
 - `glTF`
     - Runtime data: `Document` (@gltf-transform/core)
 
+Runtime data is passed by reference.
+
 ## File
 
-TBD
+(Future)
+
+# Resources
 
-## Module
+Resources are reusable values owned by a pipeline execution's resource scope, such as a shared `PlatformIO` instance. They are created on demand and shared by blocks within that execution. Blocks borrow resources; the scope retains them until execution completes or fails, then performs any required cleanup and releases its references.
 
-- `DracoEncoder`
-- `MeshoptEncoder`
-- `KTX2Encoder`
+Worker-backed encoding is future work.
 
 # Blocks
 
@@ -49,67 +50,53 @@ Blocks are broadly categorized as follows.
 Some other categories:
 
 - Files
-- Modules
 - Selectors
 - Transforms: N -> N
 - Transcoders: N -> U
 
 Blocks have input and output connection points. Some might also have additional, optional input connection points.
 
-> Before diving into the block registry, a note on the resources listed: blocks using a `Document` connection point type are assumed to be have a `Document` (@gltf-transform/core) resource. Only additional resources are named below.
+> **Uses** lists a block's implementation dependencies: libraries, functions, modules, and instances. These may include execution-scoped resources.
 
 ## Inputs
 
 - `FbxInputBlock`
     - Input: `string` which is a URL (HTTPS or data) that points to an FBX file.
     - Output: `Document`
-    - Resources: Babylon FBX loader
+    - Uses: Babylon FBX loader
     - Behavior: Uses the Babylon scene loader to load an FBX using NullEngine, exports it as a GLB, then reimports the bytes as a `Document`.
 - `GltfInputBlock`
-    - Input: `string` which is a URL (HTTPS or data) that points to a glTF or GLB.
+    - Input: `string` URI accepted by the current `PlatformIO` that points to a glTF or GLB.
     - Output: `Document`
-    - Behavior: Self-explanatory, I hope.
+    - Behavior: Reads glTF or GLB into a `Document`, using glTF Transform's default extension handling.
 - `ObjInputBlock`
     - Input: `string` which is a URL (HTTPS or data) that points to an OBJ file.
     - Output: `Document`
-    - Resources: Babylon OBJ loader
+    - Uses: Babylon OBJ loader
     - Behavior: Uses the Babylon scene loader to load an OBJ using NullEngine, exports it as a GLB, then reimports the bytes as a `Document`.
 - `StlInputBlock`
     - Input: `string` which is a URL (HTTPS or data) that points to an STL file.
     - Output: `Document`
-    - Resources: Babylon STL loader
+    - Uses: Babylon STL loader
     - Behavior: Uses the Babylon scene loader to load an STL using NullEngine, exports it as a GLB, then reimports the bytes as a `Document`.
-- `DracoEncoderBlock`
-    - Input: none
-    - Output: `DracoEncoder`
-    - Resources: `DracoEncoder` (@babylonjs/core) (alternative: draco3d (`draco3dgltf`))
-    - Behavior: Loads and prepares the Draco encoder.
-- `MeshoptEncoderBlock`
-    - Input: none
-    - Output: `MeshoptEncoder`
-    - Resources: `MeshoptEncoder` (meshoptimizer)
-    - Behavior: Loads and prepares the Meshopt encoder.
-- `KTX2EncoderBlock`
-    - Input: none
-    - Output: `KTX2Encoder`
-    - Resources: `babylonpress-ktx2-encoder` (babylonpress-ktx2-encoder)
-    - Behavior: Loads and prepares the KTX2 encoder.
 
 # Transforms
 
-- `CompressTextureBlock`
-    - Inputs:
-        1. input: `Document`
-        2. encoder: `KTX2Encoder`
+- `EncodeKTX2Block`
+    - Input: `Document`
     - Output: `Document` (but in future should be type that locks images and/or textures)
-    - Resources: `babylonpress-ktx2-encoder` (babylonpress-ktx2-encoder)
-    - Behavior: Applies BasisU compression to all images in file.
-- `CompressGeometryBlock`
-    - Inputs:
-        1. input: `Document`
-        2. encoder: `DracoEncoder` | `MeshoptEncoder`
+    - Uses: `encodeToKTX2` (`babylonpress-ktx2-encoder`); `sharp` (Node.js only)
+    - Behavior: Compresses textures to KTX2 using encoder defaults, preserving color-space and normal-map semantics.
+- `EncodeDracoBlock`
+    - Input: `Document`
+    - Output: `Document` (but in future should be type that locks geometry)
+    - Uses: initialized `EncoderModule` (`draco3dgltf`)
+    - Behavior: Uses glTF Transform's Draco compression behavior with library-default tuning.
+- `EncodeMeshoptBlock`
+    - Input: `Document`
     - Output: `Document` (but in future should be type that locks geometry)
-    - Behavior: Applies supplied compression module to all geometry in file.
+    - Uses: `MeshoptEncoder` (`meshoptimizer`)
+    - Behavior: Uses glTF Transform's Meshopt compression behavior with library-default tuning.
 
 # Outputs
 

docs/usage.md

@@ -18,17 +18,17 @@ const result = await asset.executeAsync();
 
 # Example: Compressing GLB
 
-Same as before, but now add the `CompressTexturesBlock` transform and the `DracoEncoderBlock` input.
+Same as before, but now add KTX2 texture encoding and Draco geometry encoding.
 
 ```ts
 const source = new GltfInputBlock({ input: "https://assets.babylonjs.com/meshes/box.glb" });
-const compressTextures = new CompressTexturesBlock();
-const dracoEncoder = new DracoEncoderBlock();
+const encodeTextures = new EncodeKTX2Block();
+const encodeGeometry = new EncodeDracoBlock();
 const destination = new GltfOutputBlock();
 
-source.output.connectTo(compressTextures.input);
-compressTextures.output.connectTo(destination.input);
-dracoEncoder.output.connectTo(destination.geometryCompressionOptions);
+source.output.connectTo(encodeTextures.input);
+encodeTextures.output.connectTo(encodeGeometry.input);
+encodeGeometry.output.connectTo(destination.input);
 
 const asset = new NodeAsset({
     name: "gltf-roundtrip",

package.json

@@ -57,7 +57,13 @@
         "@babylonjs/core": "^9.21.2",
         "@babylonjs/loaders": "^9.21.2",
         "@babylonjs/serializers": "^9.21.2",
+        "@gltf-transform/core": "4.5.0",
+        "@gltf-transform/extensions": "4.5.0",
+        "@gltf-transform/functions": "4.5.0",
+        "@types/draco3dgltf": "1.4.3",
         "babylonpress-ktx2-encoder": "0.6.0",
+        "draco3dgltf": "1.5.7",
+        "meshoptimizer": "1.2.0",
         "sharp": "0.35.4"
     },
     "devDependencies": {