@combeenation/3d-viewer 12.4.1 → 13.0.1

package/dist/lib-cjs/manager/parameter-manager.d.ts

@@ -0,0 +1,210 @@
+import { AbstractScene, Color3, Material, TransformNode, Vector3, Viewer } from '../index';
+/**
+ * Parameters with a built in observer implementation
+ */
+export declare const BuiltInParameter: {
+    Visible: string;
+    Material: string;
+    Position: string;
+    Rotation: string;
+    Scaling: string;
+    Color: string;
+    Roughness: string;
+    Metallic: string;
+    Paintable: string;
+};
+export declare type ParameterName = string;
+export declare type ParameterValue = string | number | boolean;
+export declare type TagParameterSubject = {
+    tagName: string;
+    nodeName?: never;
+    materialName?: never;
+};
+export declare type NodeParameterSubject = {
+    tagName?: never;
+    nodeName: string;
+    materialName?: never;
+};
+export declare type MaterialParameterSubject = {
+    tagName?: never;
+    nodeName?: never;
+    materialName: string;
+};
+/**
+ * Defines which objects are affected by the parameter.\
+ * This can be single nodes and materials or tags, which can be used to apply a parameter to a group of nodes or
+ * materials.
+ */
+export declare type ParameterSubject = TagParameterSubject | NodeParameterSubject | MaterialParameterSubject;
+/**
+ * Bulk of targeted parameter values, mainly used as input for {@link ParameterManager.setParameterValues} function.\
+ * E.g.
+ * ```
+ * [
+ *  { nodeName: 'someMesh', parameterName: BuiltInParameter.Visible, value: false },
+ *  { materialName: 'someMaterial', parameterName: BuiltInParameter.Color, value: '#DD0060' }
+ * ]
+ * ```
+ * Each parameter value entry has to set exactly one of the subject keys (`nodeName`, `materialName` or `tagName`)
+ */
+export declare type ParameterValues = (ParameterSubject & {
+    parameterName: ParameterName;
+    value: ParameterValue;
+})[];
+/**
+ * Definition of callback function for parameter change
+ */
+export declare type ParameterObserver = (payload: ParameterObserverPayload) => Promise<void>;
+/**
+ * Payload of parameter observer.\
+ * Contains current data of parameter entry, which can be usefull for implementing the dedicated observer
+ */
+export declare type ParameterObserverPayload = {
+    subject: ParameterSubject;
+    nodes: TransformNode[];
+    materials: Material[];
+    newValue: ParameterValue;
+    oldValue: ParameterValue | undefined;
+};
+declare type ParameterEntry = {
+    subject: ParameterSubject;
+    parameterName: ParameterName;
+    value: ParameterValue;
+    oldValue: ParameterValue | undefined;
+};
+export declare class ParameterManager {
+    protected viewer: Viewer;
+    /**
+     * Parses and converts input to a boolean value, valid values are:
+     * - true / false
+     * - 1 / 0
+     */
+    static parseBoolean(value: ParameterValue): boolean;
+    /**
+     * Parses and converts input to a number value
+     */
+    static parseNumber(value: ParameterValue): number;
+    /**
+     * Parses and converts input to a string value
+     */
+    static parseString(value: ParameterValue): string;
+    /**
+     * Parses a string of format "(x,y,z)"" to a "Vector3".
+     */
+    static parseVector(value: ParameterValue): Vector3;
+    /**
+     * Parses a string of format `'(x,y,z)'` with angular degrees to a `Vector3` with rotation information in radians.
+     */
+    static parseRotation(value: ParameterValue): Vector3;
+    /**
+     * Parses a string of format `'#rrggbb'` or `'(r,g,b)'` to a `Color3`.
+     */
+    static parseColor(value: ParameterValue): Color3;
+    protected _parameterEntries: ParameterEntry[];
+    protected _parameterObserver: {
+        [parameterName: ParameterName]: ParameterObserver;
+    };
+    constructor(viewer: Viewer);
+    /**
+     * Set parameter value for a certain node and calls the corresponding observer if the value has changed
+     *
+     * @returns "true" if parameter value has changed
+     */
+    setNodeParameterValue(nodeName: string, parameterName: ParameterName, value: ParameterValue): Promise<boolean>;
+    /**
+     * Set parameter value for a certain material and calls the corresponding observer if the value has changed
+     *
+     * @returns "true" if parameter value has changed
+     */
+    setMaterialParameterValue(materialName: string, parameterName: ParameterName, value: ParameterValue): Promise<boolean>;
+    /**
+     * Set parameter value for a certain tag and calls the corresponding observer if the value has changed.\
+     * Setting a parameter value on a tag can affect multiple nodes and tags, depending which of these objects contains
+     * the desired tag.
+     *
+     * @returns "true" if parameter value has changed
+     */
+    setTagParameterValue(tagName: string, parameterName: ParameterName, value: ParameterValue): Promise<boolean>;
+    /**
+     * Set multiple parameter values simultaniously.\
+     * Tag parameters are applied before node and material parameters, node and materials are more specific and should
+     * have priority.
+     *
+     * @returns Array of parameters, which have changed values
+     */
+    setParameterValues(values: ParameterValues): Promise<ParameterValues>;
+    /**
+     * @returns desired parameter value or "undefined" if parameter entry is not available.
+     */
+    getParameterValue(subject: ParameterSubject, parameterName: ParameterName): ParameterValue | undefined;
+    /**
+     * Define observer callback for certain parameter.\
+     * There can only be one observer for a certain parameter name.\
+     * Parameter observers can not be overwritten once they are defined, this also includes system observers for
+     * {@link BuiltInParameter}.
+     */
+    setParameterObserver(parameterName: ParameterName, observer: ParameterObserver): void;
+    /**
+     * Print all parameter entries in table format into the console
+     */
+    printAllParameters(): void;
+    /**
+     * Applies all existing parameter entries to a certain "model", as defined in the {@link ModelManager}.\
+     * This can be usefull when updating the model before showing it in the scene.
+     *
+     * @internal
+     */
+    applyAllParameterValuesToModel(model: AbstractScene): Promise<void>;
+    /**
+     * Applies all parameter values which are targeting a material.\
+     * This can be usefull when updating a material definition before creating it.
+     *
+     * @internal
+     */
+    applyParameterValuesToMaterial(material: Material): Promise<void>;
+    /**
+     * @returns Desired parameter value of a certain node.
+     * Tags are considered as well but have lower priority than node parameters, as these are more specific.
+     *
+     * @internal
+     */
+    getParameterValueOfNode(node: TransformNode, parameterName: string): ParameterValue | undefined;
+    /**
+     * @returns Desired parameter value of a certain material.
+     * Tags are considered as well but have lower priority than material parameters, as these are more specific.
+     * Unused ATM, but added for consistency as counter part for {@link getParameterValueOfNode}
+     *
+     * @internal
+     */
+    getParameterValueOfMaterial(material: Material, parameterName: string): ParameterValue | undefined;
+    /**
+     * Parameter observer implementation of default parameters
+     */
+    protected _addBuiltInParameterObservers(): void;
+    /**
+     * Change parameter value in array of existing parameter entries or create a new entry
+     *
+     * @returns "true" if parameter has changed or wasn't available before
+     */
+    protected _addParameterValue(subject: ParameterSubject, parameterName: ParameterName, value: ParameterValue): boolean;
+    /**
+     * Call parameter observer of desired parameter which usually apply the new values to the scene.
+     *
+     * @param assetContainer Asset container in which to look for the paramter entries subjects (e.g. the nodes and
+     *                       materials to which the parameter values should be applied to).\
+     *                       Defaults to `viewer.scene`.
+     */
+    protected _applyParameterValues(parameterEntries: ParameterEntry[], assetContainer?: AbstractScene): Promise<void>;
+    /**
+     * Call parameter observer of desired parameter
+     *
+     * @param assetContainer Optionally add an "asset container", which actually represents a model in the
+     * {@link ModelManager}. Viewer scene is used if left empty.
+     */
+    protected _applyParameterValue(subject: ParameterSubject, parameterName: ParameterName, assetContainer?: AbstractScene): Promise<void>;
+    protected _getAffectedMaterials(subject: ParameterSubject, assetContainer?: AbstractScene): Material[];
+    protected _getAffectedNodes(subject: ParameterSubject, assetContainer?: AbstractScene): TransformNode[];
+    protected _getEntry(subject: ParameterSubject, parameterName: ParameterName): ParameterEntry | undefined;
+    protected _getEntriesOfSubject(subject: ParameterSubject): ParameterEntry[];
+}
+export {};