# State

The state contains Models, Objects and Annotations logic. It can be accessed with $viewer.state.

interface State {
  hub: EventHandler<StateEvents>;

  /**** Models ****/
  readonly models: Model[];
  readonly modelsMap: Map<number, Model>;
  loadModels(ids: number[]): Promise<Model[]>;
  unloadModels(ids: number[]);
  getStoreyFromAbsoluteElevation(model: Model, elevation: number): Storey;

  /**** Objects ****/
  readonly objects: StateObject[];
  readonly objectsIds: number[];
  readonly objectsUuids: string[];
  readonly objectsMap: Map<number, StateObject>;
  readonly uuidsMap: { get(uuid: string): StateObject[]; };
  getObject(id: number): StateObject;
  getObjectsByUuids(uuids: string[]): StateObject[];
  getObjectsOfType(type: string): StateObject[];
  getObjectsWithTheSameTypeAs(ids: number[]): StateObject[];
  getTypesOf(ids: number[]): string[];

  readonly visibleObjects: StateObject[];
  readonly visibleObjectsIds: number[];
  readonly visibleObjectsUuids: string[];
  showObjects(ids: number[], options?: any): void;
  showObjectsByUuids(uuids: string[], options?: any): void;

  readonly unvisibleObjects: StateObject[];
  readonly unvisibleObjectsIds: number[];
  readonly unvisibleObjectsUuids: string[];
  hideObjects(ids: number[], options?: any): void;
  hideObjectsByUuids(uuids: string[], options?: any): void;

  readonly pickableObjects: StateObject[];
  readonly pickableObjectsIds: number[];
  readonly pickableObjectsUuids: string[];
  setObjectsPickable(ids: number[], options?: any): void;
  setObjectsPickableByUuids(uuids: string[], options?: any): void;

  readonly unpickableObjects: StateObject[];
  readonly unpickableObjectsIds: number[];
  readonly unpickableObjectsUuids: string[];
  setObjectsUnpickable(ids: number[], options?: any): void;
  setObjectsUnpickableByUuids(uuids: string[], options?: any): void;

  readonly selectedObjects: StateObject[];
  readonly selectedObjectsIds: number[];
  readonly selectedObjectsUuids: string[];
  selectObjects(ids: number[], options?: any): void;
  selectObjectsByUuids(uuids: string[], options?: any): void;

  readonly deselectedObjects: StateObject[];
  readonly deselectedObjectsIds: number[];
  readonly deselectedObjectsUuids: string[];
  deselectObjects(ids: number[], options?: any): void;
  deselectObjectsByUuids(uuids: string[], options?: any): void;

  readonly highlightedObjects: StateObject[];
  readonly highlightedObjectsIds: number[];
  readonly highlightedObjectsUuids: string[];
  highlightObjects(ids: number[], options?: any): void;
  highlightObjectsByUuids(uuids: string[], options?: any): void;

  readonly unhighlightedObjects: StateObject[];
  readonly unhighlightedObjectsIds: number[];
  readonly unhighlightedObjectsUuids: string[];
  unhighlightObjects(ids: number[], options?: any): void;
  unhighlightObjectsByUuids(uuids: string[], options?: any): void;

  readonly xrayedObjects: StateObject[];
  readonly xrayedObjectsIds: number[];
  readonly xrayedObjectsUuids: string[];
  xrayObjects(ids: number[], options?: any): void;
  xrayObjectsByUuids(uuids: string[], options?: any): void;

  readonly unxrayedObjects: StateObject[];
  readonly unxrayedObjectsIds: number[];
  readonly unxrayedObjectsUuids: string[];
  unxrayObjects(ids: number[], options?: any): void;
  unxrayObjectsByUuids(uuids: string[], options?: any): void;

  readonly colorizedObjects: StateObject[];
  readonly colorizedObjectsIds: number[];
  readonly colorizedObjectsUuids: string[];
  colorizeObjects(ids: number[], color?: string, options?: any): void;
  colorizeObjectsByUuids(uuids: string[], color?: string, options?: any): void;

  /**** Annotations ****/
  readonly annotations: Annotation[];
  addAnnotation(annotation: Annotation, options?: any): Annotation;
  removeAnnotation(annotation: Annotation, options?: any): boolean;
  clearAnnotations(): void;
}

# Models

A state Model is a model object from API (opens new window) extended with some additional fields.

interface Model extends ApiModel {
  structure: Object;
  uuids: Map<string, StateObject>;
  objects: StateObject[];
  storeys: Storey[];
}

The structure object is obtained by fetching and parsing the file pointed by the model structure_file property.

The uuids map can be used to retrieve model objects directly (using their uuids).

The objects array is the list of model objects.

The storeys array is the list of model storeys. Storey objects have the following interface:

interface Storey {
  uuid: string;
  name: string;
  model: Model;        // model that contain the storey
  plans: Plan[];       // list of storey plans
  object: StateObject; // storey object (from IFC)
  uuids: Set<string>;  // UUIDs of all storey descendents

  elevation: number;         // vertical position (z) of the storey in model coordinates
  topElevation: number;      // elevation of the next storey (in model coordinates)
  absoluteElevation: number; // vertical position of the storey (z) in world coordinates
  absoluteTopElevation: number; // elevation of the next storey (in world coordinates)

  key: string; // storey unique key
}

interface Plan {
  plan: ApiModel; /* see: https://api.bimdata.io/doc#/model/getModel */
  translation_x: number;
  translation_y: number;
  rotate_z: number;
  scale: number;
  opacity: number;

  key: string; // plan unique key
}

# Objects

interface StateObject {
  // Properties
  id: number;
  uuid: string;
  name: string;
  longname: string;
  type: string;
  object_type: string;
  model: Model;
  parent: StateObject;
  children: StateObject[];

  // State
  visible: boolean;
  pickable: boolean;
  selected: boolean;
  highlighted: boolean;
  xrayed: boolean;
  color: string;

  // Advanced getters
  readonly descendants: StateObject[];
  readonly ancestors: StateObject[];
  readonly site: StateObject;
  readonly building: StateObject;
  readonly storey: StateObject;
  readonly layout: StateObject;
  readonly space: StateObject;
  getFirstAncestorWithType: (type: string) => StateObject;
}

# Objects maps

Name	Description
`objectsMap: Map<string, StateObject>`	A Map of all objects keyed by id.
`uuidsMap: Map<string, StateObject[]>`	A Map of all objects keyed by uuids.

Note: As object uuids may not be unique, uuidsMap.get() always returns an array of objects.

# Objects getters

The state provide getters that allows to quickly access a set of objects with specific properties.

Name	Description
properties
`visibleObjects`	List of visible objects.
`unvisibleObjects`	List of objects that are not visible.
`pickableObjects`	List of pickable objects.
`unpickableObjects`	List of objects that are not pickable.
`selectedObjects`	List of selected objects.
`deselectedObjects`	List of objects that are not selected.
`highlightedObjects`	List of highlighted objects.
`unhighlightedObjects`	List of objects that are not highlighted.
`xrayedObjects`	List of xrayed objects.
`unxrayedObjects`	List of objects that are not xrayed.
`colorizedObjects`	List of colorized objects.
methods
`getObject(id: number)`	Returns the object with the specified id.
`getObjectsByUuids(uuids: string[])`	Returns objects with corresponding uuids.
`getObjectsOfType(type: string)`	Returns objects with corresponding type.
`getObjectsWithTheSameTypeAs(ids: number[] \| Set<number>)`	Returns all objects with the same type as objects ids.
`getTypesOf(ids: number[] \| Set<number>)`	Returns all the types of the corresponding objects.

Note: for convenience, all getter properties have also ids and uuids equivalent:

$viewer.state.selectedObjects;      // list of selected objects
$viewer.state.selectedObjectsIds;   // list of selected objects ids
$viewer.state.selectedObjectsUuids; // list of selected objects uuids

# Objects setters

Setters allows to update the objects state.

Name	Description
`showObjects(ids: number[], options?: any)`	Show objects.
`hideObjects(ids: number[], options?: any)`	Hide objects.
`setObjectsPickable(ids: number[], options?: any)`	Set objects as pickable.
`setObjectsUnpickable(ids: number[], options?: any)`	Set objects as unpickable.
`selectObjects(ids: number[], options?: any)`	Select objects.
`deselectObjects(ids: number[], options?: any)`	Deselect objects.
`highlightObjects(ids: number[], options?: any)`	Highlight objects.
`unhighlightObjects(ids: number[], options?: any)`	Unhighlight objects.
`xrayObjects(ids: number[], options?: any)`	Xray objects.
`unxrayObjects(ids: number[], options?: any)`	Unxray objects.
`colorizeObjects(ids: number[], color?: string, options?: any)`	Set objects color (ex: "#FFFFFF").

Note: as for getters, setters have uuids equivalent as well:

$viewer.state.selectObjects(ids);          // selects objects by ids
$viewer.state.selectObjectsByUuids(uuids); // selects objects by uuids

Moreover, every setter has an optional options argument that can be used to pass additional data to the triggered event payload. This provide more flexibility and allows to handle some complex use cases.

An example usage is to ensure that a plugin will not "auto-trigger" itself by emitting an "objects-selected" event while still being able to react to other plugins "objects-selected" events:

this.$viewer.state.hub.on("objects-selected", ({ objects, options }) => {
  if (options.emitter === this) return;
  /* Do something if the event comes from another plugin. */
});

// Pass an `emitter` option to ensure the plugin will not trigger itself
this.$viewer.state.selectObjects(ids, { emitter: this });

# Annotations

See the dedicated reference page to learn more about Annotation API.

# Events

Name	Payload	Description
Models events
`models-loaded`	`{ models: Model[] }`	One or more models have been loaded in the state
`models-unloaded`	`{ models: Model[] }`	One or more models have been unloaded from the state
`plan-created`	`{ plan: Plan }`	A storey plan has been created
`plan-updated`	`{ plan: Plan }`	A storey plan has been updated
`plan-deleted`	`{ plan: Plan }`	A storey plan has been deleted
Objects events
`objects-added`	`{ objects: StateObject[] }`	Some objects have been added to the state
`objects-removed`	`{ objects: StateObject[] }`	Some objects have been removed from the state
`objects-shown`	`{ objects: StateObject[], options?: any }`	Some objects have been made visible
`objects-hidden`	`{ objects: StateObject[], options?: any }`	Some objects have been hidden
`objects-pickable`	`{ objects: StateObject[], options?: any }`	Some objects have been made pickable
`objects-unpickable`	`{ objects: StateObject[], options?: any }`	Some objects have been made unpickable
`objects-selected`	`{ objects: StateObject[], options?: any }`	Some objects have been selected
`objects-deselected`	`{ objects: StateObject[], options?: any }`	Some objects have been deselected
`objects-highlighted`	`{ objects: StateObject[], options?: any }`	Some objects have been highlighted
`objects-unhighlighted`	`{ objects: StateObject[], options?: any }`	Some objects have been unhighlighted
`objects-xrayed`	`{ objects: StateObject[], options?: any }`	Some objects have been xrayed
`objects-unxrayed`	`{ objects: StateObject[], options?: any }`	Some objects have been unxrayed
`objects-colorized`	`{ objects: StateObject[], color: string, options?: any }`	Some objects have been colorized
Annotations events
`annotation-added`	`{ annotation: Annotation, options?: any }`	An annotation has been added
`annotation-updated`	`{ annotation: Annotation, options?: any }`	An annotation has been updated/moved
`annotation-removed`	`{ annotation: Annotation, options?: any }`	An annotation has been removed

TIP

For more information about the state hub interface, see the hub reference.

Examples:

state.hub.on("models-loaded", ({ models }) => {
  /* Handle newly loaded models */
});

state.hub.on("objects-selected", ({ objects, options }) => {
  /* Do something with selected objects */
});

← $viewer Global Context →