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.
This article describes the API that LuciadLightspeed provides to model multi-dimensional data, and how such models can be filtered.
Multi-dimensional LuciadLightspeed models implement the
Such models advertise the dimension axes and the supported values through
Multi-dimensional models allow you to apply a
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
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
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.
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.
In raster models, such as NetCDF models, the model element has multi-dimensional data: it is an
ILcdDataObject backed by several possible
In this case, the multi-dimensional data in this case is not the element itself, but it is the collection of backing images.
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
The default filter for raster models is typically the first filter As a result, only the first image passes the default filter.
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.
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
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 us 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
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
|applyDimensionFilter||createSnappingFilter → applyDimensionFilter|
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
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
Reset to default filter
Keep current filter, so that there are no model changes
ILcdModel which is not ILcdMultiDimensionalModel
Not supported. Throws
Checks instance of