Package org.apache.sis.coverage

Class SampleDimension.Builder

  • Enclosing class:
    SampleDimension
    public static class SampleDimension.Builder
extends Object
    A mutable builder for creating an immutable Sample­Dimension. The following properties can be set:
    • An optional name for the Sample­Dimension.
    • A single optional category for the background value.
    • An arbitrary amount of qualitative categories.
    • An arbitrary amount of quantitative categories.
    A qualitative category is a range of sample values associated to a label (not numbers). For example 0 = cloud, 1 = sea, 2 = land, etc. A quantitative category is a range of sample values associated to numbers with units of measurement. For example 10 = 1.0°C, 11 = 1.1°C, 12 = 1.2°C, etc. Those three kinds of category are created by the following methods: All other add­Qualitative(…) and add­Quantitative(…) methods are convenience methods delegating to above-cited methods. Qualitative and quantitative categories can be mixed in the same Sample­Dimension, provided that their ranges do not overlap. After properties have been set, the sample dimension is created by invoking build().
    Since:
    1.0

    Defined in the sis-feature module

    • Constructor Detail

      • Builder

        public Builder()
        Creates an initially empty builder for a sample dimension. Callers shall invoke at least one add­Foo(…) method before build().

    • Method Detail

      • setName

        public SampleDimension.Builder setName​(GenericName name)
        Sets an identification of the sample dimension. This is the value to be returned by Sample­Dimension​.get­Name(). If this method is invoked more than once, then the last specified name prevails (previous sample dimension names are discarded).
        Parameters:
        name - identification of the sample dimension.
        Returns:
        this, for method call chaining.

      • setName

        public SampleDimension.Builder setName​(CharSequence name)
        Sets an identification of the sample dimension as a character sequence. This is a convenience method for creating a Generic­Name from the given characters.
        Parameters:
        name - identification of the sample dimension.
        Returns:
        this, for method call chaining.

      • setName

        public SampleDimension.Builder setName​(int band)
        Sets an identification of the sample dimension as a band number. This method should be used only when no more descriptive name is available.
        Parameters:
        band - sequence identifier of the sample dimension to create.
        Returns:
        this, for method call chaining.

      • setBackground

        public SampleDimension.Builder setBackground​(CharSequence name,
                                             Number sample)
        Adds a qualitative category and marks that category as the background value. This is the value to be returned by Sample­Dimension​.get­Background(). If this method is invoked more than once, then the last specified value prevails (previous values become ordinary qualitative categories).
        Parameters:
        name - the category name as a String or International­String object, or null for a default "fill value" name.
        sample - the background value.
        Returns:
        this, for method call chaining.

      • addQualitative

        public SampleDimension.Builder addQualitative​(CharSequence name,
                                              boolean sample)
        Adds a qualitative category for samples of the given boolean value. The true value is represented by 1 and the false value is represented by 0.
        Implementation note: this convenience method delegates to add­Qualitative(Char­Sequence, Number­Range).
        Parameters:
        name - the category name as a String or International­String object, or null for a default "no data" name.
        sample - the sample value as a boolean.
        Returns:
        this, for method call chaining.

      • addQualitative

        public SampleDimension.Builder addQualitative​(CharSequence name,
                                              NumberRange<?> samples)
        Adds a qualitative category for all samples in the specified range of values. This is the most generic method for adding a qualitative category. All other add­Qualitative(name, …) methods are convenience methods delegating their work to this method.
        Parameters:
        name - the category name as a String or International­String object, or null for a default "no data" name.
        samples - the minimum and maximum sample values in the category.
        Returns:
        this, for method call chaining.
        Throws:
        Illegal­Argument­Exception - if the given range is empty.

      • addQuantitative

        public SampleDimension.Builder addQuantitative​(CharSequence name,
                                               NumberRange<?> samples,
                                               NumberRange<?> converted)
        Constructs a quantitative category mapping samples to real values in the specified range. Sample values in the samples range will be mapped to real values in the converted range through a linear equation of the form:
        measure = sample × scale + offset
        where scale and offset coefficients are computed from the ranges supplied in arguments. The units of measurement will be taken from the converted range if it is an instance of Measurement­Range.

        Warning: this method is provided for convenience when the scale and offset factors are not explicitly specified. If those factor are available, then the other add­Quantitative(name, samples, …) methods are more reliable.

        Implementation note: this convenience method delegates to add­Quantitative(Char­Sequence, Number­Range, Math­Transform1D, Unit).
        Parameters:
        name - the category name as a String or International­String object.
        samples - the minimum and maximum sample values in the category. Element class is usually Integer, but Float and Double values are accepted as well.
        converted - the range of real values for this category, as an instance of Measurement­Range if those values are associated to an unit of measurement.
        Returns:
        this, for method call chaining.
        Throws:
        Class­Cast­Exception - if the range element class is not a Number subclass.
        Illegal­Argument­Exception - if the range is invalid.

      • addQuantitative

        public SampleDimension.Builder addQuantitative​(CharSequence name,
                                               int lower,
                                               int upper,
                                               double scale,
                                               double offset,
                                               Unit<?> units)
        Adds a quantitative category for sample values ranging from lower inclusive to upper exclusive. Sample values are converted into real values using the following linear equation:
        measure = sample × scale + offset
        Results of above conversion are measurements in the units specified by the units argument.
        Implementation note: this convenience method delegates to add­Quantitative(Char­Sequence, Number­Range, Math­Transform1D, Unit).
        Parameters:
        name - the category name as a String or International­String object.
        lower - the lower sample value, inclusive.
        upper - the upper sample value, exclusive.
        scale - the scale value which is multiplied to sample values for the category. Must be different than zero.
        offset - the offset value to add to sample values for this category.
        units - the units of measurement of values after conversion by the scale factor and offset.
        Returns:
        this, for method call chaining.
        Throws:
        Illegal­Argument­Exception - if lower is not smaller than upper, or if scale or offset are not real numbers, or if scale is zero.

      • addQuantitative

        public SampleDimension.Builder addQuantitative​(CharSequence name,
                                               NumberRange<?> samples,
                                               MathTransform1D toUnits,
                                               Unit<?> units)
        Constructs a quantitative category for all samples in the specified range of values. Sample values (usually integers) will be converted into real values (usually floating-point numbers) through the to­Units transform. Results of that conversion are measurements in the units specified by the units argument.

        This is the most generic method for adding a quantitative category. All other add­Quantitative(name, …) methods are convenience methods delegating their work to this method.

        Parameters:
        name - the category name as a String or International­String object.
        samples - the minimum and maximum sample values in the category. Element class is usually Integer, but Float and Double types are accepted as well.
        to­Units - the transfer function from sample values to real values in the specified units.
        units - the units of measurement of values after conversion by the transfer function.
        Returns:
        this, for method call chaining.
        Throws:
        Class­Cast­Exception - if the range element class is not a Number subclass.
        Illegal­Argument­Exception - if the range is invalid.
        See Also:
        Transfer­Function

      • categories

        public List<Category> categories()
        Returns the list of categories added so far. The returned list does not support the add operation, but supports the remove operation.
        Returns:
        the current category list, read-only except for the remove operation.

      • build

        public SampleDimension build()
        Creates a new sample with the properties defined to this builder.
        Returns:
        the sample dimension.

      • clear

        public void clear()
        Reset this builder to the same state than after construction. The sample dimension name, background values and all categories are discarded. This method can be invoked when the same builder is reused for creating more than one sample dimension.