ProjectManager

​

Import

import { ProjectManager } from '@opengeometry/floorkit';

​

Example

import type * as THREE from 'three';
import {
  GUIEditor,
  ProjectManager,
  type CameraControlsLike,
  type ManagedPlanEditor,
  type Sheet,
} from '@opengeometry/floorkit';

export async function showProject(
  text: string,
  scene: THREE.Scene,
  planContainer: HTMLElement,
  sceneContainer: HTMLElement,
  camera: THREE.Camera,
  controls: CameraControlsLike,
): Promise<{ manager: ProjectManager; plan: ManagedPlanEditor; sceneEditor: GUIEditor }> {
  const manager = ProjectManager.open(text);
  scene.add(manager.root);
  const plan = await manager.mountPlanEditor(planContainer, 'ground-plan');
  const sceneEditor = new GUIEditor(sceneContainer, camera, controls);
  manager.bindSceneEditor(sceneEditor);
  return { manager, plan, sceneEditor };
}

export async function addSheetAndExport(
  manager: ProjectManager,
  newSheet: Sheet,
): Promise<{ saved: string; pdf: Blob }> {
  manager.apply({ kind: 'add-project-item', list: 'sheets', item: newSheet });
  manager.undo();
  manager.redo();
  const saved = manager.save();
  const pdf = await manager.exportPdf();
  return { saved, pdf };
}

export function closeProject(
  scene: THREE.Scene,
  manager: ProjectManager,
  sceneEditor: GUIEditor,
): void {
  sceneEditor.dispose();
  scene.remove(manager.root);
  manager.dispose();
}

​

Notes

​

Project commands

import type { ProjectCommand } from '@opengeometry/floorkit';

export function renameSheet(manager: ProjectManager, sheet: Sheet, name: string): number {
  const command: ProjectCommand = {
    kind: 'replace-project-item',
    list: 'sheets',
    id: sheet.id,
    item: { ...sheet, name },
  };
  return manager.apply(command);
}

​

Checks of a command

• Floorkit checks a project command as save() checks the project. A command that fails throws ProjectFileError and changes nothing.
• The value -0, the value undefined and an object that is not plain give the code invalid-json-value.
• The other codes of a project command are duplicate-item, unknown-item, item-id-mismatch and invalid-command.
• You cannot remove a view that a mounted plan editor shows, and you cannot make it a view that is not a plan. The code is view-in-use.
• If a plan editor shows a view that you added in this session, an undo that reaches the “add view” step fails with view-in-use. Dispose that plan editor first.
• Through manager.apply you cannot remove a storey while a plan view names it. The manager throws ProjectFileError with the code storey-in-use and the path of the view. Remove the view first. A remove-storey in a batch has the same check, also when the batch adds the storey again.
• Through manager.apply you cannot remove a building while a saved view shows it: a plan view of one of its storeys, a section or elevation view with its buildingId, or a view whose elementIds lists anything the building holds. The code is building-in-use, with the path of the view. A bound 3D editor has the same check.
• Through manager.apply you cannot remove the site, or give it a new id, while the elementIds of a view lists it. The code is site-in-use.
• An undo or a redo of a step of the project lists is checked as save() checks the project. A step that fails throws ProjectFileError and changes nothing.

​

History

• apply, undo and redo return the new revision. undo and redo return null when there is no step.
• A drag in an editor is a building step in the same history. The undo key in each editor undoes the last step of the manager.
• subscribe reports each step with its revision, its part (building or project) and its cause (apply, undo, redo or restore). A restore is no new step and the revision stays as it was: a step of the building failed after it changed built elements, and the session built them again from the saved model.
• Do not call apply, undo or redo in a listener. The manager throws an error with the code reentrant-transition. dispose() in a listener during a building step throws the same code.
• After a project step, the manager draws each mounted plan again. Thus one project step costs one plan draw for each mounted plan editor.
• With a ProjectManager, call manager.apply, manager.undo and manager.redo. A direct manager.session.apply is counted as a step. A direct manager.session.undo or redo, and a storey command sent to the session while a view names that storey, can leave a step that the manager cannot undo, or a project that save() refuses. While a view names a missing storey, the undo of each project step is refused. To repair it, undo the building step, or remove the view with manager.apply.

​

Files and errors

• ProjectManager.open throws ProjectFileError for a bad file. A file that is valid, but whose building does not compile, throws BmBuildError or Error.
• A project file from an earlier version opens, and the project commands work on it. save() writes the current version.
• Add root to your scene one time. It stays the same object after each edit.
• You make the GUIEditor and you dispose it. dispose() of the manager removes the plan editors and the session.
• After dispose(), exportPdf gives a promise that rejects.
• A deployed site needs a valid hostname key for exports, including a non-commercial demo. See Licensing.

​

Constructor

constructor(project: ProjectFile, options?: ProjectManagerOptions);

​

Properties

​

Methods

​

open

static open(text: string, options?: ProjectManagerOptions): ProjectManager;

​

snapshot

snapshot(): ProjectFile;

​

save

save(): string;

​

apply

apply(command: ProjectCommand): number;

​

undo

undo(): number | null;

​

redo

redo(): number | null;

​

subscribe

subscribe(listener: (change: ProjectChange) => void): () => void;

​

mountPlanEditor

mountPlanEditor(container: HTMLElement, viewId: string): Promise<ManagedPlanEditor>;

​

bindSceneEditor

bindSceneEditor(editor: GUIEditor): void;

​

setBuildableEnvelope

setBuildableEnvelope(shown: boolean): void;

​

exportPdf

exportPdf(sheetIds?: string[], options?: ProjectExportOptions): Promise<Blob>;

​

dispose

dispose(): void;

​

Types

​

ProjectManagerOptions

interface ProjectManagerOptions {
  build?: Pick<BuildOptions, 'assetSources' | 'stampMembership' | 'massColors'>;
  hostedOpeningDetachTolerance?: number;
  onError?: (error: unknown) => void;
}

​

ProjectCommand

type ProjectCommand = BuildingEditCommand | ProjectListCommand;

​

ProjectListCommand

type ProjectListCommand =
  | {
      kind: 'add-project-item';
      list: 'views';
      item: SavedDrawingView;
    }
  | {
      kind: 'add-project-item';
      list: 'sheets';
      item: Sheet;
    }
  | {
      kind: 'add-project-item';
      list: 'markers';
      item: ProjectViewMarker;
    }
  | {
      kind: 'replace-project-item';
      list: 'views';
      id: string;
      item: SavedDrawingView;
    }
  | {
      kind: 'replace-project-item';
      list: 'sheets';
      id: string;
      item: Sheet;
    }
  | {
      kind: 'replace-project-item';
      list: 'markers';
      id: string;
      item: ProjectViewMarker;
    }
  | {
      kind: 'remove-project-item';
      list: 'views' | 'sheets' | 'markers';
      id: string;
    }
  | {
      kind: 'replace-paper-settings';
      settings: Omit<PaperDocument, 'version' | 'sheets'>;
    };

​

ProjectChange

interface ProjectChange {
  revision: number;
  part: 'building' | 'project';
  cause: 'apply' | 'undo' | 'redo' | 'restore';
  changed?: readonly string[];
}

​

Related

• BuildingSession
• GUIEditor
• ManagedPlanEditor
• BuildingEditCommand
• BuildOptions
• PaperDocument
• ProjectExportOptions
• ProjectFile
• ProjectViewMarker
• SavedDrawingView
• Sheet