babylonjs-serializers 9.18.1 → 9.19.0

package/babylonjs.serializers.module.d.ts

@@ -3972,228 +3972,269 @@ import { Matrix3d, ThreeMfModel, ThreeMfObject } from "babylonjs-serializers/3MF
 import { I3mfBaseMaterials, I3mfModel, I3mfObject, I3mfTriangle, I3mfVertex, ST_ResourceID, ST_ResourceIndex, ST_Unit, ST_ObjectType } from "babylonjs-serializers/3MF/core/model/3mf.interfaces";
 import { I3mfDocument, I3mfContentType, I3mfRelationship } from "babylonjs-serializers/3MF/core/model/3mf.opc.interfaces";
 import { I3mfRGBAColor, I3mfVertexData } from "babylonjs-serializers/3MF/core/model/3mf.types";
+/**
+ * Handler invoked for every vertex generated by a {@link ThreeMfMeshBuilder}, allowing it to be transformed before export.
+ */
 export type VertexHandler = (vertex: I3mfVertex) => I3mfVertex;
+/**
+ * Handler invoked for every triangle generated by a {@link ThreeMfMeshBuilder}, allowing it to be transformed before export.
+ */
 export type TriangleHandler = (triangle: I3mfTriangle) => I3mfTriangle;
-/** */
+/**
+ * Fluent builder for a 3MF object resource.
+ * An object is the base resource of a 3MF model and is either a mesh or a set of components.
+ */
 export class ThreeMfObjectBuilder {
     /**
-     *
+     * The 3MF object resource currently being built.
      */
     protected _object: ThreeMfObject;
     /**
-     *
-     * @param id
-     * @param type
+     * Creates a new object builder.
+     * @param id The unique resource id of the object within the model.
+     * @param type The 3MF object type (model, support, solidsupport, surface or other).
      */
     constructor(id: ST_ResourceID, type: ST_ObjectType);
     /**
-     *
-     * @param name
-     * @returns
+     * Sets the human readable name of the object.
+     * @param name The name to assign to the object.
+     * @returns This builder, to allow chaining.
      */
     withName(name: string): ThreeMfObjectBuilder;
     /**
-     *
-     * @param thumbnail
-     * @returns
+     * Sets the thumbnail of the object.
+     * @param thumbnail The package relative path of the thumbnail part.
+     * @returns This builder, to allow chaining.
      */
     withThumbnail(thumbnail: string): ThreeMfObjectBuilder;
     /**
-     *
-     * @param id
-     * @param index
-     * @returns
+     * Assigns the property resource used by the object.
+     * @param id The resource id of the property group (for example a base materials group).
+     * @param index The zero based index of the property within the group. Defaults to 0.
+     * @returns This builder, to allow chaining.
      */
     withProperty(id: ST_ResourceIndex, index?: number): ThreeMfObjectBuilder;
     /**
-     *
-     * @returns
+     * Returns the object that has been built.
+     * @returns The built 3MF object resource.
      */
     build(): I3mfObject;
     /**
-     *
-     * @param id
-     * @param type
+     * Discards the current object and starts building a new one.
+     * @param id The unique resource id of the new object.
+     * @param type The 3MF object type of the new object.
      */
     reset(id: ST_ResourceID, type: ST_ObjectType): void;
 }
 /**
- *
+ * Fluent builder for a 3MF object made of components.
+ * A components object references other objects instead of defining its own geometry.
  */
 export class ThreeMfComponentsBuilder extends ThreeMfObjectBuilder {
     /**
-     *
-     * @param id
-     * @param type
+     * Creates a new components object builder.
+     * @param id The unique resource id of the object within the model.
+     * @param type The 3MF object type. Defaults to `ST_ObjectType.model`.
      */
     constructor(id: ST_ResourceID, type?: ST_ObjectType);
     /**
-     *
-     * @param id
-     * @param t
-     * @returns
+     * Adds a component referencing another object resource.
+     * @param id The resource id of the referenced object.
+     * @param t The optional transform applied to the referenced object.
+     * @returns This builder, to allow chaining.
      */
     withComponent(id: ST_ResourceID, t?: Matrix3d): ThreeMfComponentsBuilder;
 }
 /**
- *
+ * Fluent builder for a 3MF object holding a mesh.
+ * Vertices and triangles are generated from Babylon vertex data and can be post processed through handlers.
  */
 export class ThreeMfMeshBuilder extends ThreeMfObjectBuilder {
     /**
-     *
+     * Optional handler invoked for every vertex before it is added to the mesh.
      */
     _vh?: VertexHandler;
     /**
-     *
+     * Optional handler invoked for every triangle before it is added to the mesh.
      */
     _th?: TriangleHandler;
     /**
-     *
-     * @param id
+     * Creates a new mesh object builder.
+     * @param id The unique resource id of the object within the model.
      */
     constructor(id: ST_ResourceID);
     /**
-     *
-     * @param vertex
-     * @param triangle
-     * @returns
+     * Registers the handlers used to post process the generated geometry.
+     * @param vertex The handler invoked for every generated vertex.
+     * @param triangle The optional handler invoked for every generated triangle.
+     * @returns This builder, to allow chaining.
      */
     withPostProcessHandlers(vertex: VertexHandler, triangle?: TriangleHandler): ThreeMfMeshBuilder;
     /**
-     *
-     * @param data
-     * @returns
+     * Builds the mesh content of the object from the provided vertex data.
+     * @param data The positions and indices used to generate the mesh.
+     * @returns This builder, to allow chaining.
      */
     withData(data: I3mfVertexData): ThreeMfMeshBuilder;
     /**
-     *
-     * @param id
-     * @param i
-     * @returns
+     * Assigns the material used by the mesh.
+     * @param id The resource id of the base materials group.
+     * @param i The zero based index of the material within the group.
+     * @returns This builder, to allow chaining.
      */
     withMaterial(id: ST_ResourceID, i: number): ThreeMfMeshBuilder;
     /**
-     *
-     * @param data
-     * @returns
+     * Converts vertex data into a 3MF mesh.
+     * @param data The positions and indices used to generate the mesh.
+     * @returns The generated 3MF mesh.
      */
     private _buildMesh;
+    /**
+     * Converts a flat position array into a 3MF vertex list, applying the vertex handler when one is registered.
+     * @param p The flat array of x, y and z positions.
+     * @returns The generated 3MF vertex list.
+     */
     private _buildVertices;
+    /**
+     * Converts a flat index array into a 3MF triangle list, applying the triangle handler when one is registered.
+     * @param indice The flat array of vertex indices, three per triangle.
+     * @returns The generated 3MF triangle list.
+     */
     private _buildTriangle;
 }
 /**
- *
+ * Fluent builder for a 3MF base materials resource.
+ * Colors are stored as sRGB hexadecimal strings as required by the 3MF specification.
  */
 export class ThreeMfMaterialBuilder {
     private _m;
+    /**
+     * Creates a new base materials builder.
+     * @param id The unique resource id of the base materials group within the model.
+     */
     constructor(id: ST_ResourceID);
     /**
-     *
-     * @param name
-     * @param color
-     * @returns
+     * Adds a named color to the group, or updates it when the name already exists.
+     * @param name The name of the material. The lookup is case insensitive.
+     * @param color The linear RGBA color, converted to an sRGB hexadecimal string.
+     * @returns This builder, to allow chaining.
      */
     withColor(name: string, color: I3mfRGBAColor): ThreeMfMaterialBuilder;
     /**
-     *
-     * @returns
+     * Returns the base materials group that has been built.
+     * @returns The built base materials resource.
      */
     build(): I3mfBaseMaterials;
+    /**
+     * Converts a linear color into the sRGB hexadecimal string used by 3MF.
+     * @param c The linear color to convert. The alpha channel is optional.
+     * @returns The color as `#RRGGBB`, or `#RRGGBBAA` when an alpha channel is provided.
+     */
     private _rgbaToHex;
 }
 /**
- *
+ * Fluent builder for a 3MF model, the root part of a 3MF document.
+ * It aggregates the resources (materials, meshes and components) and the build items that reference them.
  */
 export class ThreeMfModelBuilder {
     /**
-     *
+     * The lower cased set of the metadata names defined by the 3MF specification.
      */
     static KnownMetaSet: Set<string>;
     /**
-     *
+     * The 3MF model currently being built.
      */
     _model: ThreeMfModel;
     /**
-     *
+     * The object resources added to the model, indexed by resource id.
      */
     _objects: Map<string, I3mfObject>;
     /**
-     *
-     * @param name
-     * @param value
-     * @param preserve
-     * @param type
-     * @returns
+     * Adds a metadata entry to the model.
+     * @param name The metadata name. Names outside of the 3MF specification must be namespace qualified.
+     * @param value The metadata value.
+     * @param preserve Whether consumers must preserve this entry when editing the document.
+     * @param type The XML schema type of the value. Defaults to `xs:string`.
+     * @returns This builder, to allow chaining.
      */
     withMetaData(name: string, value: string, preserve?: boolean, type?: string): ThreeMfModelBuilder;
     /**
-     *
-     * @param material
-     * @returns
+     * Adds a base materials group to the model resources.
+     * @param material The base materials resource, or a builder that produces one.
+     * @returns This builder, to allow chaining.
      */
     withMaterial(material: I3mfBaseMaterials | ThreeMfMaterialBuilder): ThreeMfModelBuilder;
     /**
-     *
-     * @param object
-     * @returns
+     * Adds a mesh object to the model resources.
+     * @param object The object resource, or a builder that produces one.
+     * @returns This builder, to allow chaining.
      */
     withMesh(object: I3mfObject | ThreeMfMeshBuilder): ThreeMfModelBuilder;
     /**
-     *
-     * @param components
-     * @returns
+     * Adds a components object to the model resources.
+     * @param components The object resource, or a builder that produces one.
+     * @returns This builder, to allow chaining.
      */
     withComponents(components: I3mfObject | ThreeMfComponentsBuilder): ThreeMfModelBuilder;
     /**
-     *
-     * @param objectid
-     * @param transform
-     * @param partnumber
-     * @returns
+     * Adds a build item, which places an object resource in the build plate.
+     * @param objectid The resource id of the object to place.
+     * @param transform The optional transform applied to the object.
+     * @param partnumber The optional part number identifying the produced part.
+     * @returns This builder, to allow chaining.
      */
     withBuild(objectid: ST_ResourceID, transform?: Matrix3d, partnumber?: string): ThreeMfModelBuilder;
     /**
-     *
-     * @param unit
-     * @returns
+     * Sets the unit in which the model coordinates are expressed.
+     * @param unit The 3MF unit (micron, millimeter, centimeter, inch, foot or meter).
+     * @returns This builder, to allow chaining.
      */
     withUnit(unit: ST_Unit): ThreeMfModelBuilder;
     /**
-     *
-     * @returns
+     * Discards the current model and starts building a new one.
+     * @returns This builder, to allow chaining.
      */
     reset(): ThreeMfModelBuilder;
     /**
-     *
-     * @returns
+     * Validates and returns the model that has been built.
+     * @returns The built 3MF model.
+     * @throws When the model has no object resource or no build item.
      */
     build(): ThreeMfModel;
 }
 /**
- *
+ * Fluent builder for a 3MF document, the OPC package that wraps the model.
+ * It gathers the content types, the relationships and the model part.
  */
 export class ThreeMfDocumentBuilder {
     private _cts?;
     private _rs?;
     private _m?;
     /**
-     *
-     * @param type
-     * @returns
+     * Declares an OPC content type. Duplicate declarations are ignored.
+     * @param type The extension to content type mapping to declare.
+     * @returns This builder, to allow chaining.
      */
     withContentType(type: I3mfContentType): ThreeMfDocumentBuilder;
     /**
-     *
-     * @param rel
-     * @returns
+     * Adds an OPC relationship and ensures the relationships content type is declared.
+     * Relationships with an already registered id are ignored.
+     * @param rel The relationship to add.
+     * @returns This builder, to allow chaining.
      */
     withRelationship(rel: I3mfRelationship): ThreeMfDocumentBuilder;
     /**
-     *
-     * @param m
-     * @returns
+     * Sets the model part of the document and ensures the model content type is declared.
+     * @param m The model resource, or a builder that produces one.
+     * @returns This builder, to allow chaining.
      */
     withModel(m: I3mfModel | ThreeMfModelBuilder): ThreeMfDocumentBuilder;
+    /**
+     * Validates and returns the document that has been built.
+     * A default relationship pointing at the model part is generated when none was provided.
+     * @returns The built 3MF document.
+     * @throws When no model has been set.
+     */
     build(): I3mfDocument;
 }
 
@@ -7711,228 +7752,269 @@ declare namespace BABYLON {
     }
 
 
+    /**
+     * Handler invoked for every vertex generated by a {@link ThreeMfMeshBuilder}, allowing it to be transformed before export.
+     */
     export type VertexHandler = (vertex: I3mfVertex) => I3mfVertex;
+    /**
+     * Handler invoked for every triangle generated by a {@link ThreeMfMeshBuilder}, allowing it to be transformed before export.
+     */
     export type TriangleHandler = (triangle: I3mfTriangle) => I3mfTriangle;
-    /** */
+    /**
+     * Fluent builder for a 3MF object resource.
+     * An object is the base resource of a 3MF model and is either a mesh or a set of components.
+     */
     export class ThreeMfObjectBuilder {
         /**
-         *
+         * The 3MF object resource currently being built.
          */
         protected _object: ThreeMfObject;
         /**
-         *
-         * @param id
-         * @param type
+         * Creates a new object builder.
+         * @param id The unique resource id of the object within the model.
+         * @param type The 3MF object type (model, support, solidsupport, surface or other).
          */
         constructor(id: ST_ResourceID, type: ST_ObjectType);
         /**
-         *
-         * @param name
-         * @returns
+         * Sets the human readable name of the object.
+         * @param name The name to assign to the object.
+         * @returns This builder, to allow chaining.
          */
         withName(name: string): ThreeMfObjectBuilder;
         /**
-         *
-         * @param thumbnail
-         * @returns
+         * Sets the thumbnail of the object.
+         * @param thumbnail The package relative path of the thumbnail part.
+         * @returns This builder, to allow chaining.
          */
         withThumbnail(thumbnail: string): ThreeMfObjectBuilder;
         /**
-         *
-         * @param id
-         * @param index
-         * @returns
+         * Assigns the property resource used by the object.
+         * @param id The resource id of the property group (for example a base materials group).
+         * @param index The zero based index of the property within the group. Defaults to 0.
+         * @returns This builder, to allow chaining.
          */
         withProperty(id: ST_ResourceIndex, index?: number): ThreeMfObjectBuilder;
         /**
-         *
-         * @returns
+         * Returns the object that has been built.
+         * @returns The built 3MF object resource.
          */
         build(): I3mfObject;
         /**
-         *
-         * @param id
-         * @param type
+         * Discards the current object and starts building a new one.
+         * @param id The unique resource id of the new object.
+         * @param type The 3MF object type of the new object.
          */
         reset(id: ST_ResourceID, type: ST_ObjectType): void;
     }
     /**
-     *
+     * Fluent builder for a 3MF object made of components.
+     * A components object references other objects instead of defining its own geometry.
      */
     export class ThreeMfComponentsBuilder extends ThreeMfObjectBuilder {
         /**
-         *
-         * @param id
-         * @param type
+         * Creates a new components object builder.
+         * @param id The unique resource id of the object within the model.
+         * @param type The 3MF object type. Defaults to `ST_ObjectType.model`.
          */
         constructor(id: ST_ResourceID, type?: ST_ObjectType);
         /**
-         *
-         * @param id
-         * @param t
-         * @returns
+         * Adds a component referencing another object resource.
+         * @param id The resource id of the referenced object.
+         * @param t The optional transform applied to the referenced object.
+         * @returns This builder, to allow chaining.
          */
         withComponent(id: ST_ResourceID, t?: Matrix3d): ThreeMfComponentsBuilder;
     }
     /**
-     *
+     * Fluent builder for a 3MF object holding a mesh.
+     * Vertices and triangles are generated from Babylon vertex data and can be post processed through handlers.
      */
     export class ThreeMfMeshBuilder extends ThreeMfObjectBuilder {
         /**
-         *
+         * Optional handler invoked for every vertex before it is added to the mesh.
          */
         _vh?: VertexHandler;
         /**
-         *
+         * Optional handler invoked for every triangle before it is added to the mesh.
          */
         _th?: TriangleHandler;
         /**
-         *
-         * @param id
+         * Creates a new mesh object builder.
+         * @param id The unique resource id of the object within the model.
          */
         constructor(id: ST_ResourceID);
         /**
-         *
-         * @param vertex
-         * @param triangle
-         * @returns
+         * Registers the handlers used to post process the generated geometry.
+         * @param vertex The handler invoked for every generated vertex.
+         * @param triangle The optional handler invoked for every generated triangle.
+         * @returns This builder, to allow chaining.
          */
         withPostProcessHandlers(vertex: VertexHandler, triangle?: TriangleHandler): ThreeMfMeshBuilder;
         /**
-         *
-         * @param data
-         * @returns
+         * Builds the mesh content of the object from the provided vertex data.
+         * @param data The positions and indices used to generate the mesh.
+         * @returns This builder, to allow chaining.
          */
         withData(data: I3mfVertexData): ThreeMfMeshBuilder;
         /**
-         *
-         * @param id
-         * @param i
-         * @returns
+         * Assigns the material used by the mesh.
+         * @param id The resource id of the base materials group.
+         * @param i The zero based index of the material within the group.
+         * @returns This builder, to allow chaining.
          */
         withMaterial(id: ST_ResourceID, i: number): ThreeMfMeshBuilder;
         /**
-         *
-         * @param data
-         * @returns
+         * Converts vertex data into a 3MF mesh.
+         * @param data The positions and indices used to generate the mesh.
+         * @returns The generated 3MF mesh.
          */
         private _buildMesh;
+        /**
+         * Converts a flat position array into a 3MF vertex list, applying the vertex handler when one is registered.
+         * @param p The flat array of x, y and z positions.
+         * @returns The generated 3MF vertex list.
+         */
         private _buildVertices;
+        /**
+         * Converts a flat index array into a 3MF triangle list, applying the triangle handler when one is registered.
+         * @param indice The flat array of vertex indices, three per triangle.
+         * @returns The generated 3MF triangle list.
+         */
         private _buildTriangle;
     }
     /**
-     *
+     * Fluent builder for a 3MF base materials resource.
+     * Colors are stored as sRGB hexadecimal strings as required by the 3MF specification.
      */
     export class ThreeMfMaterialBuilder {
         private _m;
+        /**
+         * Creates a new base materials builder.
+         * @param id The unique resource id of the base materials group within the model.
+         */
         constructor(id: ST_ResourceID);
         /**
-         *
-         * @param name
-         * @param color
-         * @returns
+         * Adds a named color to the group, or updates it when the name already exists.
+         * @param name The name of the material. The lookup is case insensitive.
+         * @param color The linear RGBA color, converted to an sRGB hexadecimal string.
+         * @returns This builder, to allow chaining.
          */
         withColor(name: string, color: I3mfRGBAColor): ThreeMfMaterialBuilder;
         /**
-         *
-         * @returns
+         * Returns the base materials group that has been built.
+         * @returns The built base materials resource.
          */
         build(): I3mfBaseMaterials;
+        /**
+         * Converts a linear color into the sRGB hexadecimal string used by 3MF.
+         * @param c The linear color to convert. The alpha channel is optional.
+         * @returns The color as `#RRGGBB`, or `#RRGGBBAA` when an alpha channel is provided.
+         */
         private _rgbaToHex;
     }
     /**
-     *
+     * Fluent builder for a 3MF model, the root part of a 3MF document.
+     * It aggregates the resources (materials, meshes and components) and the build items that reference them.
      */
     export class ThreeMfModelBuilder {
         /**
-         *
+         * The lower cased set of the metadata names defined by the 3MF specification.
          */
         static KnownMetaSet: Set<string>;
         /**
-         *
+         * The 3MF model currently being built.
          */
         _model: ThreeMfModel;
         /**
-         *
+         * The object resources added to the model, indexed by resource id.
          */
         _objects: Map<string, I3mfObject>;
         /**
-         *
-         * @param name
-         * @param value
-         * @param preserve
-         * @param type
-         * @returns
+         * Adds a metadata entry to the model.
+         * @param name The metadata name. Names outside of the 3MF specification must be namespace qualified.
+         * @param value The metadata value.
+         * @param preserve Whether consumers must preserve this entry when editing the document.
+         * @param type The XML schema type of the value. Defaults to `xs:string`.
+         * @returns This builder, to allow chaining.
          */
         withMetaData(name: string, value: string, preserve?: boolean, type?: string): ThreeMfModelBuilder;
         /**
-         *
-         * @param material
-         * @returns
+         * Adds a base materials group to the model resources.
+         * @param material The base materials resource, or a builder that produces one.
+         * @returns This builder, to allow chaining.
          */
         withMaterial(material: I3mfBaseMaterials | ThreeMfMaterialBuilder): ThreeMfModelBuilder;
         /**
-         *
-         * @param object
-         * @returns
+         * Adds a mesh object to the model resources.
+         * @param object The object resource, or a builder that produces one.
+         * @returns This builder, to allow chaining.
          */
         withMesh(object: I3mfObject | ThreeMfMeshBuilder): ThreeMfModelBuilder;
         /**
-         *
-         * @param components
-         * @returns
+         * Adds a components object to the model resources.
+         * @param components The object resource, or a builder that produces one.
+         * @returns This builder, to allow chaining.
          */
         withComponents(components: I3mfObject | ThreeMfComponentsBuilder): ThreeMfModelBuilder;
         /**
-         *
-         * @param objectid
-         * @param transform
-         * @param partnumber
-         * @returns
+         * Adds a build item, which places an object resource in the build plate.
+         * @param objectid The resource id of the object to place.
+         * @param transform The optional transform applied to the object.
+         * @param partnumber The optional part number identifying the produced part.
+         * @returns This builder, to allow chaining.
          */
         withBuild(objectid: ST_ResourceID, transform?: Matrix3d, partnumber?: string): ThreeMfModelBuilder;
         /**
-         *
-         * @param unit
-         * @returns
+         * Sets the unit in which the model coordinates are expressed.
+         * @param unit The 3MF unit (micron, millimeter, centimeter, inch, foot or meter).
+         * @returns This builder, to allow chaining.
          */
         withUnit(unit: ST_Unit): ThreeMfModelBuilder;
         /**
-         *
-         * @returns
+         * Discards the current model and starts building a new one.
+         * @returns This builder, to allow chaining.
          */
         reset(): ThreeMfModelBuilder;
         /**
-         *
-         * @returns
+         * Validates and returns the model that has been built.
+         * @returns The built 3MF model.
+         * @throws When the model has no object resource or no build item.
          */
         build(): ThreeMfModel;
     }
     /**
-     *
+     * Fluent builder for a 3MF document, the OPC package that wraps the model.
+     * It gathers the content types, the relationships and the model part.
      */
     export class ThreeMfDocumentBuilder {
         private _cts?;
         private _rs?;
         private _m?;
         /**
-         *
-         * @param type
-         * @returns
+         * Declares an OPC content type. Duplicate declarations are ignored.
+         * @param type The extension to content type mapping to declare.
+         * @returns This builder, to allow chaining.
          */
         withContentType(type: I3mfContentType): ThreeMfDocumentBuilder;
         /**
-         *
-         * @param rel
-         * @returns
+         * Adds an OPC relationship and ensures the relationships content type is declared.
+         * Relationships with an already registered id are ignored.
+         * @param rel The relationship to add.
+         * @returns This builder, to allow chaining.
          */
         withRelationship(rel: I3mfRelationship): ThreeMfDocumentBuilder;
         /**
-         *
-         * @param m
-         * @returns
+         * Sets the model part of the document and ensures the model content type is declared.
+         * @param m The model resource, or a builder that produces one.
+         * @returns This builder, to allow chaining.
          */
         withModel(m: I3mfModel | ThreeMfModelBuilder): ThreeMfDocumentBuilder;
+        /**
+         * Validates and returns the document that has been built.
+         * A default relationship pointing at the model part is generated when none was provided.
+         * @returns The built 3MF document.
+         * @throws When no model has been set.
+         */
         build(): I3mfDocument;
     }