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.
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
:
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 |
Checks instance of |