Package org.apache.sis.coverage
Class SampleDimension.Builder
- Object
-
- Builder
-
- Enclosing class:
- SampleDimension
public static class SampleDimension.Builder extends Object
A mutable builder for creating an immutableSampleDimension
. The following properties can be set:- An optional name for the
SampleDimension
. - A single optional category for the background value.
- An arbitrary amount of qualitative categories.
- An arbitrary amount of quantitative categories.
setBackground(CharSequence, Number)
addQualitative(CharSequence, NumberRange)
addQuantitative(CharSequence, NumberRange, MathTransform1D, Unit)
addQualitative(…)
andaddQuantitative(…)
methods are convenience methods delegating to above-cited methods. Qualitative and quantitative categories can be mixed in the sameSampleDimension
, provided that their ranges do not overlap. After properties have been set, the sample dimension is created by invokingbuild()
.- Since:
- 1.0
Defined in the
sis-feature
module
-
-
Constructor Summary
Constructors Constructor Description Builder()
Creates an initially empty builder for a sample dimension.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description SampleDimension.Builder
addQualitative(CharSequence name, boolean sample)
Adds a qualitative category for samples of the given boolean value.SampleDimension.Builder
addQualitative(CharSequence name, byte sample)
Adds a qualitative category for samples of the given tiny (8 bits) integer value.SampleDimension.Builder
addQualitative(CharSequence name, double sample)
Adds a qualitative category for samples of the given double precision floating-point value.SampleDimension.Builder
addQualitative(CharSequence name, float sample)
Adds a qualitative category for samples of the given floating-point value.SampleDimension.Builder
addQualitative(CharSequence name, int sample)
Adds a qualitative category for samples of the given integer value.SampleDimension.Builder
addQualitative(CharSequence name, short sample)
Adds a qualitative category for samples of the given short (16 bits) integer value.SampleDimension.Builder
addQualitative(CharSequence name, Number minimum, Number maximum)
Adds a qualitative category for samples in the given range of values.SampleDimension.Builder
addQualitative(CharSequence name, NumberRange<?> samples)
Adds a qualitative category for all samples in the specified range of values.SampleDimension.Builder
addQuantitative(CharSequence name, double minimum, double maximum, Unit<?> units)
Adds a quantitative category for values ranging fromminimum
tomaximum
inclusive in the given units of measurement.SampleDimension.Builder
addQuantitative(CharSequence name, float minimum, float maximum, Unit<?> units)
Adds a quantitative category for values ranging fromminimum
tomaximum
inclusive in the given units of measurement.SampleDimension.Builder
addQuantitative(CharSequence name, int lower, int upper, double scale, double offset, Unit<?> units)
Adds a quantitative category for sample values ranging fromlower
inclusive toupper
exclusive.SampleDimension.Builder
addQuantitative(CharSequence name, NumberRange<?> samples, NumberRange<?> converted)
Constructs a quantitative category mapping samples to real values in the specified range.SampleDimension.Builder
addQuantitative(CharSequence name, NumberRange<?> samples, MathTransform1D toUnits, Unit<?> units)
Constructs a quantitative category for all samples in the specified range of values.SampleDimension
build()
Creates a new sample with the properties defined to this builder.List<Category>
categories()
Returns the list of categories added so far.void
clear()
Reset this builder to the same state than after construction.SampleDimension.Builder
setBackground(CharSequence name, Number sample)
Adds a qualitative category and marks that category as the background value.SampleDimension.Builder
setName(int band)
Sets an identification of the sample dimension as a band number.SampleDimension.Builder
setName(CharSequence name)
Sets an identification of the sample dimension as a character sequence.SampleDimension.Builder
setName(GenericName name)
Sets an identification of the sample dimension.
-
-
-
Constructor Detail
-
Builder
public Builder()
Creates an initially empty builder for a sample dimension. Callers shall invoke at least oneaddFoo(…)
method beforebuild()
.
-
-
Method Detail
-
setName
public SampleDimension.Builder setName(GenericName name)
Sets an identification of the sample dimension. This is the value to be returned bySampleDimension.getName()
. 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 aGenericName
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 bySampleDimension.getBackground()
. 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 aString
orInternationalString
object, ornull
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. Thetrue
value is represented by 1 and thefalse
value is represented by 0.Implementation note: this convenience method delegates toaddQualitative(CharSequence, NumberRange)
.- Parameters:
name
- the category name as aString
orInternationalString
object, ornull
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, byte sample)
Adds a qualitative category for samples of the given tiny (8 bits) integer value. The argument is treated as a signed integer (-128 to 127).Implementation note: this convenience method delegates toaddQualitative(CharSequence, NumberRange)
.- Parameters:
name
- the category name as aString
orInternationalString
object, ornull
for a default "no data" name.sample
- the sample value as an integer.- Returns:
this
, for method call chaining.
-
addQualitative
public SampleDimension.Builder addQualitative(CharSequence name, short sample)
Adds a qualitative category for samples of the given short (16 bits) integer value. The argument is treated as a signed integer (-32768 to 32767).Implementation note: this convenience method delegates toaddQualitative(CharSequence, NumberRange)
.- Parameters:
name
- the category name as aString
orInternationalString
object, ornull
for a default "no data" name.sample
- the sample value as an integer.- Returns:
this
, for method call chaining.
-
addQualitative
public SampleDimension.Builder addQualitative(CharSequence name, int sample)
Adds a qualitative category for samples of the given integer value. The argument is treated as a signed integer (-2147483648 to 2147483647).Implementation note: this convenience method delegates toaddQualitative(CharSequence, NumberRange)
.- Parameters:
name
- the category name as aString
orInternationalString
object, ornull
for a default "no data" name.sample
- the sample value as an integer.- Returns:
this
, for method call chaining.
-
addQualitative
public SampleDimension.Builder addQualitative(CharSequence name, float sample)
Adds a qualitative category for samples of the given floating-point value.Implementation note: this convenience method delegates toaddQualitative(CharSequence, NumberRange)
.- Parameters:
name
- the category name as aString
orInternationalString
object, ornull
for a default "no data" name.sample
- the sample value as a real number.- Returns:
this
, for method call chaining.
-
addQualitative
public SampleDimension.Builder addQualitative(CharSequence name, double sample)
Adds a qualitative category for samples of the given double precision floating-point value.Implementation note: this convenience method delegates toaddQualitative(CharSequence, NumberRange)
.- Parameters:
name
- the category name as aString
orInternationalString
object, ornull
for a default "no data" name.sample
- the sample value as a real number.- Returns:
this
, for method call chaining.
-
addQualitative
public SampleDimension.Builder addQualitative(CharSequence name, Number minimum, Number maximum)
Adds a qualitative category for samples in the given range of values.Implementation note: this convenience method delegates toaddQualitative(CharSequence, NumberRange)
.- Parameters:
name
- the category name as aString
orInternationalString
object, ornull
for a default "no data" name.minimum
- the minimum sample value, inclusive.maximum
- the maximum sample value, inclusive.- Returns:
this
, for method call chaining.- Throws:
IllegalArgumentException
- if the range is empty.
-
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 otheraddQualitative(name, …)
methods are convenience methods delegating their work to this method.- Parameters:
name
- the category name as aString
orInternationalString
object, ornull
for a default "no data" name.samples
- the minimum and maximum sample values in the category.- Returns:
this
, for method call chaining.- Throws:
IllegalArgumentException
- 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 thesamples
range will be mapped to real values in theconverted
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 theconverted
range if it is an instance ofMeasurementRange
.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
addQuantitative(name, samples, …)
methods are more reliable.Implementation note: this convenience method delegates toaddQuantitative(CharSequence, NumberRange, MathTransform1D, Unit)
.- Parameters:
name
- the category name as aString
orInternationalString
object.samples
- the minimum and maximum sample values in the category. Element class is usuallyInteger
, butFloat
andDouble
values are accepted as well.converted
- the range of real values for this category, as an instance ofMeasurementRange
if those values are associated to an unit of measurement.- Returns:
this
, for method call chaining.- Throws:
ClassCastException
- if the range element class is not aNumber
subclass.IllegalArgumentException
- if the range is invalid.
-
addQuantitative
public SampleDimension.Builder addQuantitative(CharSequence name, float minimum, float maximum, Unit<?> units)
Adds a quantitative category for values ranging fromminimum
tomaximum
inclusive in the given units of measurement. The transfer function is set to identity.Implementation note: this convenience method delegates toaddQuantitative(CharSequence, NumberRange, MathTransform1D, Unit)
.- Parameters:
name
- the category name as aString
orInternationalString
object.minimum
- the minimum value (inclusive) in the given units.maximum
- the maximum value (inclusive) in the given units.units
- the units of measurement.- Returns:
this
, for method call chaining.- Throws:
IllegalArgumentException
- if a value is NaN or ifminimum
is greater thanmaximum
.
-
addQuantitative
public SampleDimension.Builder addQuantitative(CharSequence name, double minimum, double maximum, Unit<?> units)
Adds a quantitative category for values ranging fromminimum
tomaximum
inclusive in the given units of measurement. The transfer function is set to identity.Implementation note: this convenience method delegates toaddQuantitative(CharSequence, NumberRange, MathTransform1D, Unit)
.- Parameters:
name
- the category name as aString
orInternationalString
object.minimum
- the minimum value (inclusive) in the given units.maximum
- the maximum value (inclusive) in the given units.units
- the units of measurement.- Returns:
this
, for method call chaining.- Throws:
IllegalArgumentException
- if a value is NaN or ifminimum
is greater thanmaximum
.
-
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 fromlower
inclusive toupper
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 theunits
argument.Implementation note: this convenience method delegates toaddQuantitative(CharSequence, NumberRange, MathTransform1D, Unit)
.- Parameters:
name
- the category name as aString
orInternationalString
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:
IllegalArgumentException
- iflower
is not smaller thanupper
, or ifscale
oroffset
are not real numbers, or ifscale
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 thetoUnits
transform. Results of that conversion are measurements in the units specified by theunits
argument.This is the most generic method for adding a quantitative category. All other
addQuantitative(name, …)
methods are convenience methods delegating their work to this method.- Parameters:
name
- the category name as aString
orInternationalString
object.samples
- the minimum and maximum sample values in the category. Element class is usuallyInteger
, butFloat
andDouble
types are accepted as well.toUnits
- 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:
ClassCastException
- if the range element class is not aNumber
subclass.IllegalArgumentException
- if the range is invalid.- See Also:
TransferFunction
-
categories
public List<Category> categories()
Returns the list of categories added so far. The returned list does not support theadd
operation, but supports theremove
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.
-
-