Asset Renderer SDK

The @sdk/asset-renderer SDK provides a set of utilities to render HxDR assets in a web application.

Installation

To install the library, run the following command in your project directory:

npm install @sdk/asset-renderer

Renderer Plugin System

The Renderer Plugin System is a modular and extensible framework designed to enhance a centralized 3D representation of scan data, such as point clouds and meshes. It allows developers to add features (e.g., measurements, navigation controls, or dollhouse modes) in a structured and maintainable way. The system promotes code organization, separation of concerns, and team collaboration by providing a unified API for plugin development.

Benefits of the Plugin System

1. Code Organization: Plugins encapsulate specific functionality, making the codebase modular and easier to maintain.
2. Separation of Concerns: Each plugin handles a distinct feature, reducing interdependencies and improving scalability.
3. Team Collaboration: Different teams can develop plugins independently, as long as they adhere to the unified API.
4. Extensibility: New features can be added without modifying the core rendering logic.
5. Isolation: Plugins are isolated from each other, ensuring that changes in one plugin do not inadvertently affect others.

Setting Up the Renderer Plugin System

1. Create a RendererPluginManager

The RendererPluginManager is the central hub for managing plugins. It requires a RendererPluginContext, which provides shared resources like the 3D canvas, asset data, and configuration.

const rendererPluginContext = RendererPluginContext.create({
  asset, // The asset (type `AssetCore.AssetViewable`) as loaded from the `@sdk/asset-core` library
  authTokenResolver, // A function to resolve authentication tokens
  canvas: htmlCanvasRef, // The HTML canvas element for rendering
  config, // A `Config.MandatoryConfig` from the `@sdk/config` library
  panoramaFloorTexture, // Optional texture for panoramic floors
});
 
const rendererPluginManager = new RendererPluginManager(rendererPluginContext);

2. Register Plugins

Plugins can be registered with the RendererPluginManager using the registerPlugin method.

rendererPluginManager.registerPlugin(new MyPlugin());

3. Initialize Plugins and Layers

After registering plugins, call the initialize method to initialize the plugins. This will also trigger the internal loading of the associated layers of the asset.

rendererPluginManager.initialize();

3a. Retrieve Plugins

Plugins can be retrieved using either getPlugin or getPluginSafe:

• getPlugin: Retrieves a plugin by its constructor. Throws an error (TypeError) if the plugin is not registered. This is useful when your code expects the plugin to be registered.

  const myPlugin = rendererPluginManager.getPlugin(MyPlugin);

• getPluginSafe: Retrieves a plugin by its constructor. Returns undefined if the plugin is not registered.

  const myPlugin = rendererPluginManager.getPluginSafe(MyPlugin);
  if (myPlugin) {
    // Use the plugin
  }

4. Teardown Plugins

When the renderer is no longer needed, call the teardown method to clean up resources and remove event listeners.

rendererPluginManager.teardown();

Plugin Isolation and Communication

Plugins are isolated from each other and cannot directly reference one another. To enable communication between plugins:

1. Use event listeners to react to changes in one plugin.
2. Call methods on another plugin within the event handler.

Example: Wiring Plugins Together

function wirePluginInteractions(rendererPluginManager: RendererPluginManager) {
  const controllerPlugin = rendererPluginManager.getPlugin(ControllerRenderPlugin);
  const panoramicsPlugin = rendererPluginManager.getPlugin(PanoramicsRenderPlugin);
 
  controllerPlugin.addEventListener('onNavigationControllerChanged', ({ mode }) => {
    if (mode !== 'PANORAMIC') {
      panoramicsPlugin.leavePanoramaMode();
    }
  });
}

In this example, we listen for changes to the currently active controller in ControllerRenderPlugin and call the leavePanoramaMode method on the PanoramicsRenderPlugin when the new mode is not panoramic.

Using Plugins in a React Context

Plugins can be passed as props to React components. Components can use the addEventListener method to react to changes in plugins.

Example: React Component with Plugins

function MyComponent({ progressPlugin }: { progressPlugin: ProgressPlugin }) {
  useEffect(() => {
    const handleDataLoaded = (event: { data: string }) => {
      console.log('Data loaded:', event.data);
    };
 
    const listener = progressPlugin.addEventListener('dataLoaded', handleDataLoaded);
    return () => listener.remove();
  }, [myPlugin]);
 
  return <div>My Component</div>;
}

In this example, the MyComponent component listens for the dataLoaded event from the ProgressPlugin and logs the loaded data to the console.

Writing a Plugin

Creating a Plugin Class

Plugins must implement the RendererPlugin interface. For common functionality like event management, extend the RendererPluginBase class.

Example: Basic Plugin

type CullingPluginEvents = {
  onChangeCullingAvailability: { isAvailable: boolean };
};
 
export class CullingPlugin extends RendererPluginBase<CullingPluginEvents> implements RendererPlugin {
  private readonly layerManager: LayerManager;
 
  constructor(context: RendererPluginContext) {
    super();
    // Save instance of LayerManager for later use in enableCulling and disableCulling methods
    this.layerManager = context.getLayerManager();
  }
 
  // We hook into the ready event to notify listeners about culling availability.
  // This feature is only available if a mesh layer exists.
  public hookReadyToDisplay(): void {
    this.emitter.emit('onChangeCullingAvailability', { isAvailable: this.isCullingAvailable() });
  }
 
  public enableCulling(): void {
    const meshLayer = this.layerManager.getMeshLayer();
    if (Option.isSome(meshLayer)) {
      Option.unwrap(meshLayer).getInternalLayer().meshStyle.facetCulling = FacetCullingType.BACKFACE_CULLING;
    }
  }
 
  public disableCulling(): void {
    const meshLayer = this.layerManager.getMeshLayer();
    if (Option.isSome(meshLayer)) {
      Option.unwrap(meshLayer).getInternalLayer().meshStyle.facetCulling = FacetCullingType.NO_CULLING;
    }
  }
 
  public isCullingAvailable(): boolean {
    return Option.isSome(this.layerManager.getMeshLayer());
  }
}

In this example, the CullingPlugin class enables backface culling on the mesh layer when the enableCulling method is called. It also emits an event when the plugin is ready to notify listeners about the availability of culling.

Benefits of RendererPluginBase

• Event Management: Provides an event emitter for custom events.
• Teardown Handling: Automatically removes managed event listeners during teardown.

Using addManagedListener in RendererPluginBase

The addManagedListener method is a utility provided by RendererPluginBase to manage event listeners that need to be automatically removed when the plugin is torn down. This ensures proper cleanup and prevents memory leaks.

hookInitialize(): void {
  this.addManagedListener(this.toolbox.on('toolSelected', this.handleToolSelected));
}

In this example, the event listener is wrapped in addManagedListener, which automatically removes the listener when the plugin is torn down.

Plugin Lifecycle Hooks

Plugins have a well-defined lifecycle with the following hooks:

Initialization Phase (Called in Order)

1. hookRegister: Called when the plugin is registered. Determines whether the plugin should be enabled.
2. hookInitialize: Called when the renderer is manually initialized. Layer information is not yet available.
3. hookStartup: Called after initialization and layer creation. Scene dimensions are not yet available.
4. hookSceneDimensionsAvailable: Called after scene dimensions are calculated.
5. hookReadyToDisplay: Called when enough data is loaded to display the scene.

Event-Based Hooks (Called as Needed)

• hookLayerCreated: Called when a layer is created.
• hookAllLayersCreated: Called when all layers are created.
• hookLoadProgress: Called during incremental layer data loading.
• hookLoadError: Called when an error occurs during layer data loading.
• hookLayerShow: Called when a layer is shown.
• hookLayerHide: Called when a layer is hidden.

Teardown

• hookTeardown: Called when the plugin is torn down. Use this to clean up resources.

Plugin Context

The RendererPluginContext provides access to shared resources like the 3D canvas, asset data, and configuration. It is passed as a parameter to every plugin hook. It contains:

• RenderContext: The main rendering context providing access to the 3D canvas, configuration, authorization tokens, and the camera.
• AssetContext: The asset data loaded from the @sdk/asset-core library. Including information about the asset bounds.
• LayerManager: A manager for layers, including mesh, point cloud, and panoramic layers.
• LayerGroupsContext: A context for managing layer groups, like the main rendering group and the overlay/tool group.
• ControllerContext: A context for managing controllers, where plugins can register custom controllers.

class WASDControllerPlugin implements RendererPluginInterface {
  constructor(context: RendererPluginContext) {
    this.wasdController = new WASDController(context.getControllerContext().getEventContext());
  }
 
  hookInitialize(context: RendererPluginContext): void {
    context.getControllerContext().setNavigationController(this.wasdController);
  }
 
  hookTeardown(context: RendererPluginContext): void {
    context.getControllerContext().setNavigationController(null);
  }
}

In this imaginary example, the WASDControllerPlugin registers a custom WASD controller with the ControllerContext during initialization and removes it during teardown, showing the usage of the RenderPluginContext passed through the hooks.

Other Best Practices

Don't Leak Plugin Internals

A core principle of good software design is encapsulation: keeping internal details hidden and providing a clean, minimal API for external use. When a plugin reveals its internal helper objects or logic (for example, by returning them directly from a getSupport() method), it creates tight coupling between the plugin and the code that uses it. Instead, it is better to expose only the methods that callers truly need—methods that are part of the plugin’s public interface. This high-level API ensures that external code depends on stable, well-defined functionality, while the plugin remains free to evolve or refactor its internals as needed.

// ⛔️ Don't
myPlugin.getSupport().doTheThing();
 
// ✅ Do
myPlugin.doTheThing();

Always expose a clear and direct method that accomplishes the desired action, rather than returning internal components.