DEV Community: Guillaume Beraudo

Creating a 3D config with types

Guillaume Beraudo — Thu, 05 Dec 2024 18:18:45 +0000

Good config system is not easy

We are building the NGV, a framework to create 3d applications, powered by the CesiumJS library.

How to design the configuration (file) mechanism?

how to type it?
how to anticipate / detect harmful changes in CesiumJS?
how to avoid writing tons of code?

JSON is not easily typed

JSON is simple and flexible, but has no typing information.
Sure it is possible to join a JSON schema file, but that needs to be taken care of and checked. Ex, with additional tooling like typescript-json-schema or ts-json-schema-generator.

It is also not standard yet to import JSON.

Typescript as config file

Typescript allows to write typed JSON, out of the box. Here is an example of config file in typescript that exports a typed JSON config:

import type {IPermitsConfig} from './ingv-config-permits.js';

export const config: IPermitsConfig = {
  // the supported languages
  languages: ['de', 'fr', 'en', 'it'],
  app: {
    cesiumContext: {
      // the catalogs, containing declarations of all existing layers
      // WMTS, 3d-tiles, gLTF models, terrain, ...
      catalogs: {
        '@demo': '../../catalogs/demoCatalog.json',
        '@cesium': '../../catalogs/cesiumCatalog.json',
        '@geoadmin': '../../catalogs/geoadminCatalog.json',
      },
      layers: {
        // tilesets: ['@cesium/googlePhotorealistic'],
        models: ['@demo/sofa', '@demo/thatopensmall'],
        imageries: ['@geoadmin/pixel-karte-farbe'],
        // terrain: '@geoadmin/terrain',
      },
      // the default position of the camera
      camera: {
        position: [6.628484, 46.5, 100],
        orientation: {
          heading: 0,
          pitch: -30.0,
        },
      },
      layerOptions: {},
      widgetOptions: {
        scene3DOnly: true,
      },
      globeOptions: {
        depthTestAgainstTerrain: true,
      },
    },
  },
};

Beyond static JSON

For a configuration defined at compile time, using typescript is straightforward and guarantees typing in the long run. That said, we are not limited to serializable structures: if we want we can as well make use of the dynamic nature of javascript by using functions, for example.

NGV: writing frontend plugins

Guillaume Beraudo — Mon, 28 Oct 2024 12:54:44 +0000

In this episode we will look at the approach of plugins for NGV, our Modern 3D Viewer framework. This is part of the NGV series.

Targeting developers

One approach is to target non-developer end users with a "just-click-to-enable" solution. The drawback is that you need to write and maintain a lot of extra code, documentation and that makes it both time consuming and rigid.
As a consequence, we target developers and focus on making it easy for them. There is actually a lot of technology around plugins and reusable code that we can leverage: git, ES modules, docker...
One other big simplification is to have no external plugins: to extend the software users should fork the project and build it.

Maintainability / reusability

Plugins are good for maintainable solutions. With plugins you are forced to think about what is core and what is not; what should be extensible or replaceable. You need to introduce abstractions, interfaces and that makes the code more isolated and easier to understand. In addition, you write documentation and instructions to help people outside of the core developers understand your APIs: that makes it really easier for everyone.

An example, we have created the plugin ngv-plugin-cesium-widget to isolate low-level Cesium code from applications code. We plan to have dozens of applications: having common code in a plugin allows us to share code but also concepts between applications. The plugin is generic and we expose interfaces for configuring it: the plugin can handle any configuration, it is future-proof.

@customElement('ngv-plugin-cesium-widget')
export class NgvPluginCesiumWidget extends LitElement {
  public viewer: CesiumWidget;

  @property({type: Object})
  cesiumContext: IngvCesiumContext;

  @property({type: Object})
  modelCallback: (name: string, model: Model) => void;

Extension / Customization

With a plugin system the user has the power to go beyond configuration. The solution can be customized and even extended.

For example, all geospatial applications have a search bar, but none have the same: different backends, different formats, different features.

A search plugin can come with predefined providers (ex: OpenstreetMap Nominatim) and allow you to provide yours (ex: Pelias, Photon, ...).

These providers are independent of that application and can easily be shared or contributed upstream.

In addition, the search plugin can be completely replaced by another implementation, as long as it obeys to the underlying interface.

    for (const pc of descr.config.providers) {
      const initialize = providerInitializers[pc.name];
      if (!initialize) {
        console.error("could not find provider", pc.name, "skipping it");
        continue;
      }
      const provider = initialize(pc.config);
      this.providers.push(provider);
    }

    this.autocomplete = new Autocomplete(this.autocompleteRef.value, {

      search: this.search.bind(this),
      onSubmit: this.onSubmit.bind(this),
      renderResult: this.renderResult.bind(this),
      getResultValue: this.getResultValue.bind(this),
    });

Standards

Very close to the idea of "plugins" is the concept of "modules". Indeed, Ecmascript modules are the technical way we "pack" and make available our plugins, internally, in the NGV framework.

In a similar way, web components, are the technical standard that allows us to expose UI plugins to the DOM.

We can also see git as the fundamental tool that allows our plugin strategy, by empowering users to fork, adapt, contribute.

Conclusion

Our solution to the plugin problem is an architecture relying on standard, leveraging developer know-how and ecosystem, it allows for easier to understand, isolated and more maintainable code.

Have you designed a plugin system? Or have you started thinking about it? Let me know your feedback in comments.

A modern 3D viewer framework series

Guillaume Beraudo — Mon, 28 Oct 2024 12:54:34 +0000

Hi,

Time ticks, the Javascript ecosystem and web browsers get new features; users want more and complexity sky rockets.

At some point one needs to take the time to assess the changes, think about a way forward and start experimenting.

In this series I will present ideas and findings on the topic of writing a modern 3D viewer framework.

Some things will end up in the project repository ; some may not, and that is precisely the point: understanding what should be done and what should not.

This 3d viewer will be a framework, allowing developers to customize or create new applications (more) easily. How? That's what we will find out.

Have you been thinking about re-usability? Maintenance cost? Extension? Developer experience? Don't hesitate to shout out.