Modeling multi-dimensional data

Typically, geospatial data has a location component: data is captured at a specific geographic location. In many cases though, geospatial data has more components than just a location component. The most common data dimension is the time dimension, which is often used in NVG, ASTERIX, and NetCDF data sets. Another common dimension is vertical position, which is often used in NetCDF data to model values recorded at distinct levels in the atmosphere.

Data that is captured along more than one dimension is called multi-dimensional data. Its data dimensions are represented by the axes of a chart, and the range of values captured in the various dimensions are represented as intervals along the chart axes.

multidimensionaldata
Figure 1. Image data captured along a time dimension and a vertical position dimension

This article describes the API that LuciadLightspeed provides to model multi-dimensional data, and how such models can be filtered.

Getting the dimensions and values of multi-dimensional models

Multi-dimensional LuciadLightspeed models implement the ILcdMultiDimensionalModel interface. Such models advertise the dimension axes and the supported values through ILcdMultiDimensional.getDimensions.

Filtering multi-dimensional data

Multi-dimensional models allow you to apply a TLcdDimensionFilter, using ILcdMultiDimensionalModel.applyDimensionFilter. In such a filter, you define filtering axes and intervals and match the multi-dimensional data against those. As a result of the filtering, only the data that passes the filter will be available in the model. If you apply the empty filter TLcdDimensionFilter.EMPTY_FILTER, the model resets to its default dimensional filter. To learn more about the default filters for vector models and raster models, see Filtering vector models and Filtering raster models.

You can also get the current filter by calling ILcdMultiDimensionalModel.getDimensionFilter. The returned filter is the one that was most recently applied to the model. If no filter was set, a default filter is returned. The returned filter may be the empty filter TLcdDimensionFilter.EMPTY_FILTER, but it must never be null.

If the returned filter defines intervals for more or fewer axes than the model supports, the model treats those filters gracefully:

  • When a filter contains more axes than the model supports, the model ignores those axes.

  • When a filter contains fewer axes than the model supports, the model resets its defaults for those axes.

If the multi-dimensional model is a vector model, the multi-dimensional data and its filtering is modeled slightly different than in the case of a raster model.

Filtering vector models

For vector models, such as NVG or ASTERIX models, the model elements themselves are the multi-dimensional data: the elements define the intervals for which they are valid.

When a filter is applied, the elements themselves are evaluated against the filter. Elements are added to or removed from the filtered model, and appropriate events are fired for all affected elements. If none of the elements pass the filter, the filtered model will be empty.

The default filter for vector models is typically the empty filter. As a result, all elements pass the default filter.

Filtering raster models

In raster models, such as NetCDF models, the model element has multi-dimensional data: it is an ILcdDataObject backed by several possible ALcdImage instances. In this case, the multi-dimensional data in this case is not the element itself, but it is the collection of backing images. The ILcdDataObject element itself is always present, but the image it points to may change as a result of filtering. The element can only point to one image at most, so even if multiple images pass the filter, only the first of the passing images will be made available.

If none of the elements pass the filter, the model will not be empty: the element itself remains, but the image it points to will be null.

The default filter for raster models is typically the first filter As a result, only the first image passes the default filter.

Value filtering by interval matching

The value range of a multi-dimensional data set is defined by its intervals, for example an interval between two times on a time axis. When you apply a filter, the filter also defines a specific interval. Models match their multi-dimensional data against a given filter based on the overlap between the data interval and the filter interval, as defined by TLcdDimensionInterval.overlaps. The model matches all data valid in the intervals defined by the filter. This means that if there is the slightest amount of overlap between the two intervals, the evaluated data is considered valid, and passes the filter.

Locking your model for filtering

You must apply a filter from within a write lock, using TLcdLockUtil.writeLock(model) and event mode ILcdModel.FIRE_LATER. As an exception, you do not need to lock your model when you are initially creating it. In that case, there are no references to it yet, and it is safe not to lock at all and use event mode ILcdModel.NO_EVENT.

Snapping to filter intervals supported by the model

The matching of multi-dimensional data against a filter happens in a strict manner, as defined by TLcdDimensionInterval.overlaps. There needs to be an exact match for filtering to occur. In practice, however, the validity of multi-dimensional data is often defined as a singular interval. For example, NetCDF data often offers multiple images, each of which is valid at one specific time. That may pose some difficulties when you are implementing a filter based on a time slider, for example: a time slider slides along the continuous spectrum of the time axis. More often than not, the filter will not match anything in the model.

In such a case, you may want the filter to snap to the nearest valid multi-dimensional data. Such functionality is offered by TLcdDimensionFilter.createSnappingFilter. It offers a more lenient form of filter matching, and ensures that multi-dimensional data matches are always available for any filter. You can choose between the NEAREST, NEXT, or PREVIOUS snapping modes, or even the no-snapping mode. You can create a filter and convert it to a snapping one with TLcdDimensionFilter.createSnappingFilter before invoking ILcdMultiDimensionalModel.applyDimensionFilter. Snapping only happens when there are no strict matches. If there is at least one strict match, snapping behaves identically to the no-snapping mode.

createSnappingFilter does more than just snapping. These are the differences of using and not using TLcdDimensionFilter.createSnappingFilter:

Table 1. Differences between applyDimensionFilter and applyAndSnapToDimensionFilter
  applyDimensionFilter createSnappingFilter → applyDimensionFilter

Snapping behavior

Never, possibly resulting in no matches

Snaps to intervals defined by the model if needed, such that there is always at least one match

Supported snap modes

None

Nearest, previous, next, none

Filter has fewer axes than supported by model

Reset to default for those axes

Keep the current filter value for those axes, so that there are minimal model changes

Empty filter

Reset to default filter

Keep current filter, so that there are no model changes

ILcdModel which is not ILcdMultiDimensionalModel

Not supported. Throws ClassCastException.

Checks instance of ILcdMultiDimensionalModel, leaves others alone