@xeokit/xeokit-sdk 2.2.5 → 2.3.0-beta-2

package/types/viewer/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./localization/LocaleService";
+export * from "./scene";
+export * from "./Plugin";
+export * from "./Viewer";
+export * from "./Configs";
+export * from "./metadata";

package/types/viewer/localization/LocaleService.d.ts

@@ -0,0 +1,183 @@
+export declare type LocaleServiceConfiguration = {
+  messages: any;
+  locale?: string;
+};
+
+/**
+ * Localization service for a {@link Viewer}.
+ */
+export declare class LocaleService {
+  /**
+   * @constructor
+   * @param {LocaleServiceConfiguration} cfg LocaleService configuration
+   */
+  constructor(cfg?: LocaleServiceConfiguration);
+
+  /**
+   * Replaces the current set of locale translations.
+   *
+   * * Fires an "updated" event when done.
+   * * Automatically refreshes any plugins that depend on the translations.
+   * * Does not change the current locale.
+   *
+   * ## Usage
+   *
+   * ````javascript
+   * viewer.localeService.setMessages({
+   *     messages: {
+   *         "en": { // English
+   *             "NavCube": {
+   *                 "front": "Front",
+   *                 "back": "Back",
+   *                 "top": "Top",
+   *                 "bottom": "Bottom",
+   *                 "left": "Left",
+   *                 "right": "Right"
+   *             }
+   *         },
+   *         "mi": { // Māori
+   *             "NavCube": {
+   *                 "front": "Mua",
+   *                 "back": "Tuarā",
+   *                 "top": "Runga",
+   *                 "bottom": "Raro",
+   *                 "left": "Mauī",
+   *                 "right": "Tika"
+   *             }
+   *         }
+   *    }
+   * });
+   * ````
+   *
+   * @param {*} messages The new translations.
+   */
+
+  set messages(arg: any);
+
+  /**
+   * Sets the current locale.
+   *
+   * * Fires an "updated" event when done.
+   * * The given locale does not need to be in the list of available locales returned by {@link LocaleService.locales}, since
+   * this method assumes that you may want to load the locales at a later point.
+   * * Automatically refreshes any plugins that depend on the translations.
+   * * We can then get translations for the locale, if translations have been loaded for it, via {@link LocaleService.translate} and {@link LocaleService.translatePlurals}.
+   *
+   * @param {String} locale The new current locale.
+   */
+  set locale(arg: string);
+
+  /**
+   * Gets the current locale.
+   *
+   * @returns {String} The current locale.
+   */
+  get locale(): string;
+
+  /**
+   * Loads a new set of locale translations, adding them to the existing translations.
+   *
+   * * Fires an "updated" event when done.
+   * * Automatically refreshes any plugins that depend on the translations.
+   * * Does not change the current locale.
+   *
+   * ## Usage
+   *
+   * ````javascript
+   * viewer.localeService.loadMessages({
+   *     "jp": { // Japanese
+   *         "NavCube": {
+   *             "front": "前部",
+   *             "back": "裏",
+   *             "top": "上",
+   *             "bottom": "底",
+   *             "left": "左",
+   *             "right": "右"
+   *         }
+   *     }
+   * });
+   * ````
+   *
+   * @param {*} messages The new translations.
+   */
+  loadMessages(messages?: any): void;
+
+  /**
+   * Clears all locale translations.
+   *
+   * * Fires an "updated" event when done.
+   * * Does not change the current locale.
+   * * Automatically refreshes any plugins that depend on the translations, which will cause those
+   * plugins to fall back on their internal hard-coded text values, since this method removes all
+   * our translations.
+   */
+  clearMessages(): void;
+
+  /**
+   * Gets the list of available locales.
+   *
+   * These are derived from the currently configured set of translations.
+   *
+   * @returns {String[]} The list of available locales.
+   */
+
+  get locales(): string[];
+  /**
+   * Translates the given string according to the current locale.
+   *
+   * Returns null if no translation can be found.
+   *
+   * @param {String} msg String to translate.
+   * @param {*} [args] Extra parameters.
+   * @returns {String|null} Translated string if found, else null.
+   */
+
+  translate(msg: string, args?: any): string | null;
+
+  /**
+   * Translates the given phrase according to the current locale.
+   *
+   * Returns null if no translation can be found.
+   *
+   * @param {String} msg Phrase to translate.
+   * @param {Number} count The plural number.
+   * @param {*} [args] Extra parameters.
+   * @returns {String|null} Translated string if found, else null.
+   */
+  translatePlurals(msg: string, count: number, args?: any): string | null;
+
+  /**
+   * Fires an event on this LocaleService.
+   *
+   * Notifies existing subscribers to the event, optionally retains the event to give to
+   * any subsequent notifications on the event as they are made.
+   *
+   * @param {String} event The event type name.
+   * @param {Object} value The event parameters.
+   * @param {Boolean} [forget=false] When true, does not retain for subsequent subscribers.
+   */
+  fire(event: string, value: any, forget?: boolean): void;
+
+  /**
+   * Subscribes to an event on this LocaleService.
+   *
+   * @param {String} event The event
+   * @param {Function} callback Callback fired on the event
+   * @return {String} Handle to the subscription, which may be used to unsubscribe with {@link .off}.
+   */
+  on(event: string, callback: Function): string;
+
+  /**
+   * Cancels an event subscription that was previously made with {@link LocaleService.on}.
+   *
+   * @param {String} subId Subscription ID
+   */
+  off(subId: string): void;
+
+  /**
+   * Fires when the messages or the locale are updated 
+   * @param event The loaded event
+   * @param callback Called fired on the event
+   */
+  on(event: "updated", callback: (e: LocaleService | string) => void): string
+}

package/types/viewer/metadata/IFCObjectDefaults.d.ts

@@ -0,0 +1,9 @@
+
+export declare type IFCObjectDefaults = {
+  [key: string]: {
+    colorize?: number[];
+    pickable?: boolean;
+    visible?: boolean;
+    opacity?: number
+  }
+};

package/types/viewer/metadata/MetaModel.d.ts

@@ -0,0 +1,65 @@
+import { MetaScene } from "./MetaScene";
+import { PropertySet } from "./PropertySet";
+import { MetaObject } from "./MetaObject";
+
+/**
+ * Metadata corresponding to an {@link Entity} that represents a model.
+ */
+export declare class MetaModel {
+  /**
+   * Globally-unique ID.
+   *
+   * MetaModels are registered by ID in {@link MetaScene.metaModels}.
+   *
+   * When this MetaModel corresponds to an {@link Entity} then this ID will match the {@link Entity.id}.
+   *
+   */
+  id: string | number;
+
+  /**
+   * The project ID
+   */
+  projectId: string | number;
+
+  /**
+   * The revision ID, if available.
+   */
+  revisionId?: string | number;
+
+  /**
+   * The model author, if available.
+   */
+  author?: string;
+
+  /**
+   * The date the model was created, if available.
+   */
+  createdAt?: string;
+
+  /**
+   * The application that created the model, if available.
+   */
+  creatingApplication?: string;
+
+  /**
+   * The model schema version, if available.
+   */
+  schema?: string;
+
+  /**
+   * Metadata on the {@link Scene}.
+   */
+  metaScene?: MetaScene;
+
+  /**
+   * The {@link PropertySet}s in this MetaModel.
+   */
+  propertySets: {
+    String: PropertySet;
+  };
+
+  /**
+   * The root {@link MetaObject} in this MetaModel's composition structure hierarchy.
+   */
+  rootMetaObject: MetaObject;
+}

package/types/viewer/metadata/MetaObject.d.ts

@@ -0,0 +1,74 @@
+import { MetaModel } from "./MetaModel";
+import { PropertySet } from "./PropertySet";
+
+/**
+ * Metadata corresponding to an {@link Entity} that represents an object.
+ */
+export declare class MetaObject {
+  /**
+   * Model metadata.
+   */
+  metaModel: MetaModel;
+
+  /**
+   * Globally-unique ID.
+   */
+  id: string;
+
+  /**
+   * ID of the corresponding object within the originating system, if any.
+   */
+  originalSystemId: string;
+
+  /**
+   * Human-readable name.
+   */
+  name: string;
+
+  /**
+   * Type - often an IFC product type.
+   */
+  type: string;
+
+  /**
+   * Optional {@link PropertySet}s used by this MetaObject.
+   */
+  propertySets: PropertySet[];
+
+  /**
+   * The parent MetaObject within the structure hierarchy.
+   */
+  parent?: MetaObject;
+
+  /**
+   * Child ObjectMeta instances within the structure hierarchy.
+   */
+  children: MetaObject[];
+
+  /**
+   * External application-specific metadata
+   */
+  external?: any;
+
+  /**
+   * Gets the {@link MetaObject.id}s of the {@link MetaObject}s within the subtree.
+   *
+   * @returns {String[]} Array of {@link MetaObject.id}s.
+   */
+  getObjectIDsInSubtree(): string[];
+
+  /**
+   * Iterates over the {@link MetaObject}s within the subtree.
+   *
+   * @param {Function} callback Callback fired at each {@link MetaObject}.
+   */
+  withMetaObjectsInSubtree(callback: (metaobect: MetaObject)=> void): void;
+
+  /**
+   * Gets the {@link MetaObject.id}s of the {@link MetaObject}s within the subtree that have the given {@link MetaObject.type}s.
+   *
+   * @param {String[]} types {@link MetaObject.type} values.
+   * @returns {String[]} Array of {@link MetaObject.id}s.
+   */
+  getObjectIDsInSubtreeByType(types: string[]): string[];
+}

package/types/viewer/metadata/MetaScene.d.ts

@@ -0,0 +1,135 @@
+import { Viewer } from "../Viewer";
+import { Scene } from "../scene/scene/Scene";
+import { MetaModel } from "./MetaModel";
+import { PropertySet } from "./PropertySet";
+import { MetaObject } from "./MetaObject";
+
+/**
+ * Metadata corresponding to a {@link Scene}.
+ */
+export declare class MetaScene {
+  /**
+     * The {@link Viewer}.
+     * @property viewer
+     * @type {Viewer}
+     */
+  viewer: Viewer;
+
+  /**
+     * The {@link Scene}.
+     * @property scene
+     * @type {Scene}
+     */
+  scene: Scene;
+
+  /**
+     * The {@link MetaModel}s belonging to this MetaScene, each mapped to its {@link MetaModel.modelId}.
+     *
+     * @type {{String:MetaModel}}
+     */
+  metaModels: {[key: string]: MetaModel};
+
+  /**
+     * The {@link PropertySet}s belonging to this MetaScene, each mapped to its {@link PropertySet.id}.
+     *
+     * @type {{String:PropertySet}}
+     */
+  propertySets: {[key: string]: PropertySet};
+
+  /**
+     * The {@link MetaObject}s belonging to this MetaScene, each mapped to its {@link MetaObject.id}.
+     *
+     * @type {{String:MetaObject}}
+     */
+  metaObjects: {[key: string]: MetaObject};
+
+  /**
+     * The {@link MetaObject}s belonging to this MetaScene, each mapped to its {@link MetaObject.type}.
+     *
+     * @type {{String:MetaObject}}
+     */
+  metaObjectsByType: {[key: string]: MetaObject};
+
+  /**
+     * Subscribes to an event fired at this Viewer.
+     *
+     * @param {String} event The event
+     * @param {Function} callback Callback fired on the event
+     */
+  on(event: string, callback: ()=> void): void;
+
+  /**
+     * Fires an event at this Viewer.
+     *
+     * @param {String} event Event name
+     * @param {Object} value Event parameters
+     */
+  fire(event: string, value: any): void;
+
+  /**
+     * Unsubscribes from an event fired at this Viewer.
+     * @param event
+     */
+  off(event: any): void;
+
+  /**
+     * Creates a {@link MetaModel} in this MetaScene.
+     *
+     * The MetaModel will contain a hierarchy of {@link MetaObject}s, created from the
+     * meta objects in ````metaModelData````.
+     *
+     * The meta object hierarchy in ````metaModelData```` is expected to be non-cyclic, with a single root. If the meta
+     * objects are cyclic, then this method will log an error and attempt to recover by creating a dummy root MetaObject
+     * of type "Model" and connecting all other MetaObjects as its direct children. If the meta objects contain multiple
+     * roots, then this method similarly attempts to recover by creating a dummy root MetaObject of type "Model" and
+     * connecting all the root MetaObjects as its children.
+     *
+     * @param {String} modelId ID for the new {@link MetaModel}, which will have {@link MetaModel.id} set to this value.
+     * @param {Object} metaModelData Data for the {@link MetaModel}.
+     * @param {Object} [options] Options for creating the {@link MetaModel}.
+     * @param {String[]} [options.includeTypes] When provided, only create {@link MetaObject}s with types in this list.
+     * @param {String[]} [options.excludeTypes] When provided, never create {@link MetaObject}s with types in this list.
+     * @param {Boolean} [options.globalizeObjectIds=false] Whether to globalize each {@link MetaObject.id}. Set this ````true```` when you need to load multiple instances of the same meta model, to avoid ID clashes between the meta objects in the different instances.
+     * @returns {MetaModel} The new MetaModel.
+     */
+  createMetaModel(modelId: string, metaModelData: any, options?: {
+    includeTypes?: string[];
+    excludeTypes?: string[];
+    globalizeObjectIds?: boolean;
+  }): MetaModel;
+
+  /**
+     * Removes a {@link MetaModel} from this MetaScene.
+     *
+     * Fires a "metaModelDestroyed" event with the value of the {@link MetaModel.id}.
+     *
+     * @param {String} id ID of the target {@link MetaModel}.
+     */
+  destroyMetaModel(id: string): void;
+
+  /**
+     * Gets the {@link MetaObject.id}s of the {@link MetaObject}s that have the given {@link MetaObject.type}.
+     *
+     * @param {String} type The type.
+     * @returns {String[]} Array of {@link MetaObject.id}s.
+     */
+  getObjectIDsByType(type: string): string[];
+
+  /**
+     * Gets the {@link MetaObject.id}s of the {@link MetaObject}s within the given subtree.
+     *
+     * @param {String} id  ID of the root {@link MetaObject} of the given subtree.
+     * @param {String[]} [includeTypes] Optional list of types to include.
+     * @param {String[]} [excludeTypes] Optional list of types to exclude.
+     * @returns {String[]} Array of {@link MetaObject.id}s.
+     */
+  getObjectIDsInSubtree(id: string, includeTypes?: string[], excludeTypes?: string[]): string[];
+
+  /**
+     * Iterates over the {@link MetaObject}s within the subtree.
+     *
+     * @param {String} id ID of root {@link MetaObject}.
+     * @param {Function} callback Callback fired at each {@link MetaObject}.
+     */
+  withMetaObjectsInSubtree(id: string, callback: ()=> void): void;
+}

package/types/viewer/metadata/Property.d.ts

@@ -0,0 +1,29 @@
+/**
+ * A property within a {@link PropertySet}.
+ */
+export declare class Property {
+  /**
+   * The name of this property.
+   */
+  name: string;
+
+  /**
+   * The type of this property.
+   */
+  type: number | string;
+
+  /**
+   * The value of this property.
+   */
+  value: any;
+
+  /**
+   * The type of this property's value.
+   */
+  valueType: number | string;
+
+  /**
+   * Informative text to explain the property.
+   */
+  description: string;
+}

package/types/viewer/metadata/PropertySet.d.ts

@@ -0,0 +1,31 @@
+import { Property } from "./Property";
+
+/**
+ * A set of properties associated with one or more {@link MetaObject}s.
+ */
+export declare class PropertySet {
+  /**
+   * Globally-unique ID for this PropertySet.
+   */
+  id: string;
+
+  /**
+   * ID of the corresponding object within the originating system, if any.
+   */
+  originalSystemId: string;
+
+  /**
+   * Human-readable name of this PropertySet.
+   */
+  name: string;
+
+  /**
+   * Type of this PropertySet.
+   */
+  type: string;
+
+  /**
+   * Properties within this PropertySet.
+   */
+  properties: Property[];
+}

package/types/viewer/metadata/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./MetaModel";
+export * from "./MetaObject";
+export * from "./MetaScene";
+export * from "./Property";
+export * from "./PropertySet";
+export * from "./IFCObjectDefaults";