Package com.luciad.multidimensional

Interface ILcdMultiDimensionalModel

All Superinterfaces:
AutoCloseable, ILcdDisposable, ILcdModel, ILcdMultiDimensional, Serializable
All Known Implementing Classes:
TLcdASTERIXFilteredModel, TLcdNetCDFFilteredModel, TLcdNVG20FilteredModel
public interface ILcdMultiDimensionalModel extends ILcdMultiDimensional, ILcdModel
Models that support dimensional filtering, such as NetCDF, NVG and some LuciadFusion models, should implement this interface.

In the simple case of a single model, a filter will usually contain exactly one interval for every axis the model supports. This allows a filter to be applied atomically: you can define all intervals for all axes in a single filter and apply them at once.

If a filter contains more axes than the model supports, the unknown axes should be ignored by the model. For example, if a model only has time dimension but the filter has a level and time interval, then the model should filter only on time. This allows instances of global filters to be defined: you can define a filter for every possible dimension in your view, even if different models in view support a different subset of axes, and all the models will behave according to the filter.

If a filter contains fewer axes than the model supports, the model should still apply the filter as much as it can for the axes the filter does contain. For the axes that the filter does not define, the model should reset to default. Resetting to default is slightly different for vector models compared to raster models. This is explained in more detail in applyDimensionFilter(com.luciad.multidimensional.TLcdDimensionFilter, int). For example, if a NetCDF raster model has axes defining time and vertical dimensions, but the filter only specifies a time axis, the implementation will pick typically the first raster at the given time.

A special case is when a filter contains no axes: then the model resets its filter to the default.

The model implementations may decide what the filters should look like. Most models only support single-valued intervals as filter values in practice. Models should match filters according to TLcdDimensionInterval.overlaps(com.luciad.multidimensional.TLcdDimensionInterval<T>, com.luciad.multidimensional.TLcdDimensionInterval<T>):

  • If for example the filter specifies an interval for that axis that doesn't match (overlap with) any of the axis values, the model should be 'empty' to indicate that nothing passes the filter. The semantics of 'empty' for vector and raster models differ slightly, and is explained in more detail in applyDimensionFilter(com.luciad.multidimensional.TLcdDimensionFilter, int).
  • If for example the filter specifies a regular interval that matches multiple of the possible axis values, the model may decide which of the matching values to use, but it should not behave as if nothing passes the filter.

Multi-dimensional object models

A typical implementation of a multi-dimensional model filters its elements when a dimensional filter is applied. Events will be fired for every element that was added to or removed from the model as a result of applying the filter. When no objects pass the filter, the model will be empty. Examples of such implementations are NVG and ASTERIX models.

Multi-dimensional raster models

Another typical implementation of a multi-dimensional model is a model that has a single ILcdDataObject that has an ALcdImage as property. When a filter is applied, the element remains the same, but the ALcdImage it owns changes. An event will be fired for the element. When no ALcdImage passes the filter, the ILcdDataObject will remain the same (not null), but its ALcdImage will be null. Examples of such implementations are NetCDF and LuciadFusion fused multi-dimensional raster models.

No snapping

Implementations should not 'snap' to the intervals defined by the filter in case no elements match. There shall be no snapping to nearest, previous or next. Instead, the result must be 'empty' (or 'image is null' in case of raster models). If you need to snap a filter interval to an actual interval the model has to offer, you should use TLcdDimensionFilter.createSnappingFilter(com.luciad.multidimensional.ILcdMultiDimensionalModel, com.luciad.multidimensional.TLcdDimensionFilter.SnapMode) instead.

Since:
2016.0

  • Method Details

    • applyDimensionFilter

      void applyDimensionFilter(TLcdDimensionFilter aFilter, int aEventMode)
      Applies a given dimensional filter and fires an event accordingly. The given filter may specify one interval per axis. The filter may contain more or less axes than the model supports.
      • If the filter contains more axes than the model supports, the model should ignore those axes.
      • If the filter contains less axes than the model supports, the model should reset to its default for those axes.
      In particular, in case of the empty filter, the model should reset to the default filter. The default filter is typically an accept-all filter, but the specific behavior depends on the model implementation.

      Filtering behavior
      In practice, filtering behavior and the default filter depend on the type of the model:

      • Vector models, such as NVG or ASTERIX, have multiple elements, where every element is a domain object. Each element has a validity defined by an interval, for example a temporal interval on a time axis. The filtered model will only contain the elements that match the filter. When a new filter is applied, events will be fired as elements are removed or added based on the new filter. The default filter in this case is 'no filter', which means that all elements match the filter and the model behaves as if unfiltered. In case no elements match the filter, the model will be empty.
      • Raster models, such as NetCDF, have a single or a couple of model elements, where every model element corresponds with exactly one image. Internally, each element is possibly backed up by multiple ALcdImage instances, every one of which is valid within a certain interval. An implementation of this interface needs to make sure that
        • a model element only corresponds with exactly one of these images, based on the currently configured filter.
        • the model element's image is available through ALcdImage.fromDomainObject(java.lang.Object). We advise to use the 'has-an-image' paradigm to expose this image, because it allows for faster updates in a Lightspeed view.
        • changes in filtering are correctly applied. When a filter is changed, it must either replace the element with a new element, or when the 'has-an-image' paradigm is used, it must replace the image that is exposed by the model element. When a filter doesn't match anything, it must make sure that there is no element present in the model. Using 'has-an-image' with a null image is not a valid way to express this.
        Typically, the default image will be the 'first' image.
      Example: consider a NetCDF model with an initial filter which selects the 'first' image. The NetCDF model has two dimensions: time and vertical position. Suppose a filter is applied for a specific time and vertical position: the model's domain object selects the corresponding image and fires an appropriate event. Now suppose a filter is applied for a specific time but no vertical position: multiple images match for multiple vertical positions, but the model selects the 'first'.

      Filter matching
      Matching intervals happens based on TLcdDimensionInterval.overlaps(com.luciad.multidimensional.TLcdDimensionInterval<T>, com.luciad.multidimensional.TLcdDimensionInterval<T>). The rationale for this is the following:

      • Each element has a validity defined by an interval, for example on a time axis.
      • Using the filter, you're asking the model to "match everything which is valid in the filter interval(s)", which corresponds to the meaning of overlap.

      Locking
      This method should typically be called from within a write lock: 

      
    try (TLcdLockUtil.Lock lock = TLcdLockUtil.writeLock(model) {
      ...
      model.applyDimensionFilter(filter, ILcdModel.FIRE_LATER);
      ...
    } finally {
      model.fireCollectedModelChanges();
    }
      The most common exception to this rule is when you're creating a model initially and no-one has a reference to it yet: in that case, it's safe to not lock at all and use ILcdModel.NO_EVENT.

      No snapping
      Implementations should not 'snap' to the intervals defined by the filter in case no elements match. There shall be no snapping to nearest, previous or next. Instead, the result must be 'empty' (or 'image is null' in case of raster models). If you need to snap a filter interval to an actual interval the model has to offer, you should use TLcdDimensionFilter.createSnappingFilter(com.luciad.multidimensional.ILcdMultiDimensionalModel, com.luciad.multidimensional.TLcdDimensionFilter.SnapMode) to create a snapped filter.

      Differences with createSnappingFilter
      As its name suggests, the primary purpose of the utility method createSnappingFilter is to create a filter which 'snaps' to filter intervals so that there is always at least one match. But the method does more than just that. Here is a list of differences between using and not using createSnappingFilter:

      Behavior applyDimensionFilter createSnappingFilter->applyDimensionFilter
      Snapping 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, or none (null)
      Filter has less axes than supported by model Reset to default for those axes Keep the last 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 Checks instance of ILcdMultiDimensionalModel, leaves others alone
      Parameters:
      aFilter - The dimensional filter, possibly empty but never null.
      aEventMode - The mode of the event that should be triggered when the value of the filter parameters changes.
      See Also:

    • getDimensionFilter

      TLcdDimensionFilter getDimensionFilter()
      Gets the current dimensional filter, possibly empty but never null. The current dimensional filter is the last one that was set on this model using applyDimensionFilter(TLcdDimensionFilter, int). It may contain more or less dimensions than this model supports, and it may be empty (TLcdDimensionFilter.EMPTY_FILTER), but it must never be null. The filter intervals may but does not have to be one of the intervals given by getDimensions().getValues().

      When no dimensional filter has been set on this model yet, this method returns the default dimensional filter. The default dimensional filter depends on the implementation. Typical implementations:

      • Multi-dimensional raster models, such as NetCDF, typically define a default filter which matches exactly one combination of dimensional values, often the first combination. The reason for this is that the rasters are typically mutually exclusive: only one can be included in the filtered result. Intuitively, this corresponds to a "match any" or "match first" filter.
      • Multi-dimensional object models, such as NVG, typically define an unbounded default filter which matches all objects. The reason for this is that the objects are are not mutually exclusive: they can all be included in the filtered result. Intuitively, this corresponds to "no filter".

      The default filter is not necessarily constant. It may change as elements are added to or removed from the model, because the default filter is often computed from the dimensional information of the elements.

      Returns:
      The current dimensional filter, possibly the TLcdDimensionFilter.EMPTY_FILTER but never null.