Moving from an ILcyMapComponent to the Lightspeed view

Lucy allows you to move from an application using a GXY view in an ILcyMapComponent to an application based on a Lightspeed view. To complete such a migration, you need to:

  1. Replace the GXY-view-based map component, ILcyMapComponent, with a Lightspeed-view-based map component, ILcyLspMapComponent

  2. Replace all code interacting with the map or the view

  3. Replace some or all your custom GXY-based data formats with Lightspeed-based ones.

The first two steps are mandatory. The last step is optional, but recommended for optimal performance.

Each of those steps is explained in more detail below.

Replacing the GXY map component with a Lightspeed map component

You must replace ILcyMapComponent with ILcyLspMapComponent by replacing the map component factory, and by setting up interaction with the Lightspeed map manager.

Replace the map component factory

The components of a GXY map are created by the TLcyMapAddOn by means of an ALcyMapComponentFactory. You can customize many settings of that factory by altering the configuration file of the map add-on, map_addon.cfg. If those customizations are not sufficient, you can replace the default factory with a custom one. To replace the factory, either set the mapComponentFactoryName property in the configuration file, or use the API and call TLcyMapAddOn.setMapComponentFactory.

Lightspeed map components are created in a very similar fashion, and allow for the same customizations. They are created by the TLcyLspMapAddOn by means of a factory. In this case, the factory is an instance of ALcyGUIFactory<ILcyLspMapComponent>, and the default implementation is the TLcyLspMapComponentFactory class.

You can customize many settings by altering the configuration file of the Lightspeed map add-on. If those customizations are not sufficient, the Lightspeed map add-on allows replacing the default factory with a custom one. See the Lightspeed Map Add-on documentation for more information.

Interact with the Lightspeed map manager

The TLcyMapManager allows you to retrieve the GXY map components in your application: you can iterate over the available maps, and you can can query it for the active map component. It fires events when maps are added and removed, or when the active map component changes. This map manager is always available at the Lucy back-end. Call ILcyLucyEnv.getMapManager() to obtain it.

There is also a map manager available for Lightspeed maps: the TLcyLspMapManager. The manager has the same functionality as its GXY counterpart: you can iterate over the available maps, query it for the active map component, and it will fire events when maps are added and removed, or when the active map component changes.

There is a subtle difference between the Lightspeed map manager and its GXY variant: whereas the GXY map manager is always available at the Lucy backend, the Lightspeed map manager becomes available only after you have plugged in the TLcyLspMapAddOn. Once that is done, you can retrieve the map manager from the services using ILcyLucyEnv#getService( TLcyLspMapManager.class ).

You can also use the TLcyCombinedMapManager as an alternative to the TLcyLspMapManager. The combined map manager is a map manager for all types of maps: GXY maps and Lightspeed maps. You can retrieve the map manager from the Lucy back-end using ILcyLucyEnv#getCombinedMapManager(). The main benefit of using the combined map manager instead of the Lightspeed map manager is that it is always available at the Lucy back-end, even if the TLcyLspMapAddOn has not been loaded yet. The drawback is that it fires generic map events instead of events specific to Lightspeed maps. However, if your application only uses Lightspeed map components, it is safe to cast the map components in the generic events to Lightspeed map components.

Replace all code interacting with the map or view

A typical application contains a significant amount of code that interacts with the map, the view, and the layers. If you switch to a Lightspeed map component, the view no longer is an ILcdGXYView with ILcdGXYLayer instances, but an ILspView with ILspLayer instances. The code interacting with those components must be adjusted as such.

LuciadLightspeed offers documentation about migrating from a GXY view to a Lightspeed view. It provides more information on how to migrate to a Lightspeed view, and on the similarities and differences between the two view and layer types. See Moving from a GXY view to an ILspView and Using Lightspeed technology within a GXY view.

Replace a custom GXY-based data format with a custom Lightspeed-based data format

To visualize data, you must firstly decode the data into an ILcdModel, and secondly, create a layer for that model. The data is typically decoded by an ILcdModelDecoder, and the layer is typically created by a layer factory.

GXY layers and Lightspeed layers use the same ILcdModel instances. As such, you only need to create Lightspeed layer factories to visualize your data on a Lightspeed view. You can do this by implementing your own custom format, as explained in the Support Custom Data documentation.

The Lightspeed format adds support for layer creation, but not for model decoding. This means that you still need to plug in your GXY format, which is responsible for the model decoding.

If you include the TLcyLspFallbackFormatAddOn, you do not need to create a Lightspeed format for your custom data format. The TLcyLspFallbackFormatAddOn is included by default. The fallback add-on will re-use your GXY layer factory to create a GXY layer and adapt it to a Lightspeed layer, using a TLspGXYLayerAdapter instance. The benefit is that you do not need to write any new code to visualize your data on a Lightspeed view. The drawback is that you may not obtain as good a performance as with native Lightspeed layers. See the next section for more information.

Integrating a non-native Lightspeed layer in an Lightspeed view

Lucy allows you to easily integrate your own GXY layers in a Lightspeed view. More specifically, it is possible to visualize data on an ILspView for which only an ILcdGXYLayerFactory is available. The add-on responsible for this functionality is TLcyLspFallbackFormatAddOn. It is by default included in the addons_gxy.xml file, and works out-of-the-box. The benefit of using this add-on is that you do not have to write a Lightspeed equivalent of your own formats to view them in a Lightspeed view.

To make this work, the fallback add-on provides an ILspLayerFactory that tries to create an ILcdGXYLayer using the GXY layer factory registered to the Lucy environment. If such a layer can be created, it is wrapped in a TLspGXYLayerAdapter, which in turn can be added to a Lightspeed view. To make sure that the fallback layer factory is only used when no native Lightspeed factory is available, the GXY fallback addon is registered with ILcyLucyEnv.PRIORITY_FALLBACK. This imposes a strict order on the sequence in which the factory is consulted. If no native Lightspeed factory is available, the GXY fallback layer factory will be used. In addition to this, the fallback add-on also ensures (in a similar way) that your existing GXY layer customizer panels, style providers and layer workspace codecs will work in a Lightspeed view.

To benefit from this functionality, make sure that your existing own ILcdGXYLayerFactory is registered with your Lucy environment — see TLcyCompositeGXYLayerFactory. This works similarly for your layer customizer panels (ILcyCustomizerPanelFactory), layer style providers (ILcyLayerStyleProvider), and layer workspace codecs (ALcyWorkspaceObjectCodec). Now you should be able to open and customize your data on the Lightspeed view, and save it to a workspace. If you want to programmatically create a fallback Lightspeed layer for your model, you can make use of TLcyLspCompositeLayerFactory.

See Adapting GXY layers for more information about TLspGXYLayerAdapter.

Using Lightspeed technology within a GXY view

Lucy provides an easy way to benefit from Lightspeed technology without forcing an entire application to use Lightspeed views. Instead, you can also use Lightspeed within a ILcdGXYView. In some typical use cases, such as density plots, this can significantly speed up rendering.

To support Lightspeed layers within a GXY view, every synchronous ALcyFormat can be wrapped with a TLcyGXYLspAsynchronousFormatWrapper. This format wrapper focusses on supporting the asynchronous painting of layers using Lightspeed and ensures all layer-related concepts, such as customizer panels and workspace codecs, are properly wrapped. To do so, it requires a GXYLspLayerFactory, which creates Lightspeed layers, not based on a model, but based on the format’s GXY layers. The wrapper’s layer factory will eventually use both layers inside TLcdGXYLspAsynchronousLayerWrapper. See Adapting GXY layers for more information.

To include support for Lightspeed layer nodes within a GXY view, the format has to be wrapped with TLcyGXYLspAsynchronousLayerTreeNodeFormatWrapper, in addition to the one for regular layers. Consult the wrapper’s Javadoc for more information on how to setup such a construction.

The Lucy density sample, available as samples.lucy.density, illustrates how you can add Lightspeed support to your GXY format. The sample introduces DensityFormat, a small GXY format that can display one specific trajectories model as a density plot. This model contains thousands of trajectories and visualizing a density plot of such a model is typically an expensive operation. Therefore, DensityAddOn wraps the density format with TLcyGXYLspAsynchronousFormatWrapper to accelerate the painting, providing the Lightspeed density layer factory to be used as an argument. Program: Add support for Lightspeed to DensityFormat. illustrates this.

Program: Add support for Lightspeed to DensityFormat. (from samples/lucy/density/DensityAddOn)
@Override
protected ALcyFormat createFormatWrapper(ALcyFormat aBaseFormat) {
  TLcySafeGuardFormatWrapper formatWrapper = new TLcySafeGuardFormatWrapper(aBaseFormat);
  // Wrap the format with TLcyGXYLspAsynchronousFormatWrapper to add support
  // for visualizing layers using Lightspeed technology.
  LightspeedDensityLayerFactory densityLayerFactory = new LightspeedDensityLayerFactory();
  return new TLcyGXYLspAsynchronousFormatWrapper(formatWrapper, densityLayerFactory);
}