views management removal - STEMLab/geotools GitHub Wiki

Description

This proposal aims on removing the Views Management on the GridCoverage2D class. ViewsManager machinery has been introduced to deal with packed coverage data whilst, in the vast majority of the case, datasets contain geophysics values which can be rendered as the user needs through the powerful SLD capabilities.

This machinery introduces several complexities in the code, unneeded pre-processing steps to compute different views of the same data and so on. For this reason we aim to remove the ViewsManager related classes and deprecate the public methods involving sampleToGeophysic transformation, different views management and automatic scaling capabilities.

We will always deal with data values as they are stored in the underlying dataset: packed, native, photographic, geophysics concepts will no be supported anymore.

Implementation

These modifications involve for the major part the gt-coverage module and, specifically, the classes which are mostly changed in this proposals are:

  • Category
  • GridSampleDimension
  • GridCoverage2D
  • SampleDimension
  • ViewType
  • Calculator2D
  • CoverageUtilities

The changes affecting these classes will be described in the following paragraphs.

Generally speaking, our procedure is to remove the already deprecated *Views-management *methods and to deprecate old methods, asking for their removal in the next release version.

Package-private and hidden classes which are no more needed will be removed, since their change will not affect the public APIs.

It also should be pointed out that, since the getSampleToGeophysics method is not part of the OGC specification, it will be deprecated from the SampleDimension interface.

Status

Voting has not started yet:

Tasks

This section is used to make sure your proposal is complete (did you remember documentation?) and has enough paid or volunteer time lined up to be a success

  1. API changed based on BEFORE / AFTER ✅
  2. Remove Views Management code from GeoTools project ✅
  3. Deprecate methods from GeoTools project ✅
  4. Update the existing methods ✅
  5. Update Views Management Tests ✅
  6. Remove Views related documentation

API Changes

Category

BEFORE:

private Category(final CharSequence name,
                      final int[]        ARGB,
                      final Number       sample){...}

public Category(final CharSequence name,
                     final Color[]      colors,
                     final int          lower,
                     final int          upper,
                     final double       scale,
                     final double       offset) throws IllegalArgumentException{...}

public Category(final CharSequence name,
                     final Color[]     colors,
                     final NumberRange sampleValueRange,
                     final double      scale,
                     final double      offset) throws IllegalArgumentException{...}

public Category(final CharSequence name,
                     final Color[]     colors,
                     final NumberRange sampleValueRange,
                     final NumberRange geophysicsValueRange) throws IllegalArgumentException{...}

public Category(final CharSequence name,
                     final Color[]     colors,
                     final NumberRange sampleValueRange,
                     final MathTransform1D sampleToGeophysics) throws IllegalArgumentException{...}

private Category(final CharSequence name,
                     final int[]        ARGB,
                     final NumberRange  range,
                     MathTransform1D sampleToGeophysics) throws IllegalArgumentException{...}
 
public MathTransform1D getSampleToGeophysics() {...}

 
public Category rescale(final MathTransform1D sampleToGeophysics) {...}
 
public Category geophysics(final boolean geo) {...}

AFTER:

private Category(final CharSequence name,
                    final int[]        ARGB,
                    final Number       sample,
                    final boolean isQuantitative){...}
 
@Deprecated
public Category(final CharSequence name,
                     final Color[]      colors,
                     final int          lower,
                     final int          upper,
                     final double       scale,
                     final double       offset) throws IllegalArgumentException{...}

@Deprecated
public Category(final CharSequence name,
                     final Color[]     colors,
                     final NumberRange sampleValueRange,
                     final double      scale,
                     final double      offset) throws IllegalArgumentException{...}
 
@Deprecated
public Category(final CharSequence name,
                     final Color[]     colors,
                     final NumberRange sampleValueRange,
                     final NumberRange geophysicsValueRange) throws IllegalArgumentException{...}
 
@Deprecated
public Category(final CharSequence name,
                     final Color[]     colors,
                     final NumberRange sampleValueRange,
                     final MathTransform1D sampleToGeophysics) throws IllegalArgumentException{...}
 
private Category(final CharSequence name,
                     final int[]        ARGB,
                     final NumberRange  range,
                     final boolean isQuantitative) throws IllegalArgumentException{...}
 
/**
 * Constructs a qualitative or quantitative category for sample value {@code sample}.
 */
 public Category(final CharSequence name,
                    final Color        color,
                    final int          sample,
                    final boolean isQuantitative){...}

/**
  * Constructs a quantitative category for sample values ranging from {@code lower}
  * inclusive to {@code upper} exclusive.
  *
  * @throws IllegalArgumentException if {@code lower} is not smaller than {@code upper},
  *         or if {@code scale} or {@code offset} are not real numbers.
  */
public Category(final CharSequence name,
                    final Color[]      colors,
                    final int          lower,
                    final int          upper) throws IllegalArgumentException{...}

/**
  * Constructs a quantitative category for sample values in the specified range.
  * 
  * @throws IllegalArgumentException if {@code lower} is not smaller than {@code upper},
  *         or if {@code scale} or {@code offset} are not real numbers.
  */
public Category(final CharSequence name,
                    final Color[]     colors,
                    final NumberRange sampleValueRange) throws IllegalArgumentException{...}

/**
  * Constructs a qualitative or quantitative category for samples in the specified range.
  *
  * @throws ClassCastException if the range element class is not a {@link Number} subclass.
  * @throws IllegalArgumentException if the range is invalid.
  */
public Category(final CharSequence name,
                    final Color[]     colors,
                    final NumberRange sampleValueRange,
                    final boolean isQuantitative) throws IllegalArgumentException{...}
 
@Deprecated
public MathTransform1D getSampleToGeophysics() {...}

@Deprecated
public Category rescale(final MathTransform1D sampleToGeophysics) {...}

@Deprecated
public Category geophysics(final boolean geo) {...}

SampleDimension

AFTER:

@Deprecated
@Extension
MathTransform1D getSampleToGeophysics();

GridSampleDimension

BEFORE:

private GridSampleDimension(final CharSequence description, final CategoryList list) {...}
 
public MathTransform1D getSampleToGeophysics() {...}

public GridSampleDimension geophysics(final boolean geo) {...}

public GridSampleDimension rescale(final double scale, final double offset) {...}

AFTER:

private GridSampleDimension(final CharSequence description, final CategoryList list, double scale, double offset) {...}
 
public GridSampleDimension(String description, Category[] categories, double scale, double offset) {...}
 
@Deprecated
public MathTransform1D getSampleToGeophysics() {...}

@Deprecated
public GridSampleDimension geophysics(final boolean geo) {...}

@Deprecated
public GridSampleDimension rescale(final double scale, final double offset) {...}

Calculator2D

AFTER:

@Deprecated
public abstract class Calculator2D extends GridCoverage2D {...}

ViewType

AFTER:

@Deprecated
public enum ViewType {...}

GridCoverage2D

BEFORE:

public GridCoverage2D view(final ViewType type) {...}

public synchronized Set<ViewType> getViewTypes() {...}

AFTER:

@Deprecated
public GridCoverage2D view(final ViewType type) {...}
 
@Deprecated
public synchronized Set<ViewType> getViewTypes() {...}

CoverageUtilities

BEFORE:

public static boolean hasRenderingCategories(final GridCoverage gridCoverage) {...}

public static boolean hasTransform(final SampleDimension[] sampleDimensions) {...}

public static ViewType preferredViewForOperation(final GridCoverage2D coverage, final Interpolation interpolation, final boolean hasFilter, final RenderingHints hints) {...}

public static ViewType preferredViewAfterOperation(final GridCoverage2D coverage) {...}

AFTER:

@Deprecated
public static boolean hasRenderingCategories(final GridCoverage gridCoverage) {...}

@Deprecated
public static boolean hasTransform(final SampleDimension[] sampleDimensions) {...}

@Deprecated
public static ViewType preferredViewForOperation(final GridCoverage2D coverage, final Interpolation interpolation, final boolean hasFilter, final RenderingHints hints) {...}

@Deprecated
public static ViewType preferredViewAfterOperation(final GridCoverage2D coverage) {...}

Documentation Changes

list the pages effected by this proposal

Add a custom footer
⚠️ **GitHub.com Fallback** ⚠️