- Enclosing class:
SampleDimension
SampleDimension.
The following properties can be set:
- An optional name for the
SampleDimension. - A single optional category for the background value.
- An arbitrary number of qualitative categories.
- An arbitrary number of quantitative categories.
A qualitative category is a range of sample values associated to a label.
For example, 0 = no data, 1 = cloud, 2 = sea, 3 = land, etc.
Missing values are also considered as a qualitative category and should be declared.
If the missing value can be used as a background value for filling empty spaces in
image resampling operations,
then it should be declared using setBackground(…) method instead of addQualitative(…).
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. A quantitative category has a transfer function (typically a scale factor and an offset) for converting sample values to values expressed in the unit of measurement.
Qualitative and quantitative categories can be mixed in the same SampleDimension,
provided that their ranges do not overlap.
After properties have been set, the sample dimension is created by invoking build().
Note for subclass implementations
Properties are ultimately set by the following methods:setName(GenericName)setBackground(CharSequence, Number)addQualitative(CharSequence, NumberRange)addQuantitative(CharSequence, NumberRange, MathTransform1D, Unit)
setName(…), addQualitative(…) and addQuantitative(…) methods
are convenience methods delegating to above-cited methods, thus providing single points that
subclasses can override.- Since:
- 1.0
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionaddQualitative(CharSequence name, boolean sample) Adds a qualitative category for samples of the given boolean value.addQualitative(CharSequence name, byte sample) Adds a qualitative category for samples of the given tiny (8 bits) integer value.addQualitative(CharSequence name, double sample) Adds a qualitative category for samples of the given double precision floating-point value.addQualitative(CharSequence name, float sample) Adds a qualitative category for samples of the given floating-point value.addQualitative(CharSequence name, int sample) Adds a qualitative category for samples of the given integer value.addQualitative(CharSequence name, short sample) Adds a qualitative category for samples of the given short (16 bits) integer value.addQualitative(CharSequence name, Number minimum, Number maximum) Adds a qualitative category for samples in the given range of values.addQualitative(CharSequence name, NumberRange<?> samples) Adds a qualitative category for all samples in the specified range of values.addQuantitative(CharSequence name, double minimum, double maximum, Unit<?> units) Adds a quantitative category for values ranging fromminimumtomaximuminclusive in the given units of measurement.addQuantitative(CharSequence name, float minimum, float maximum, Unit<?> units) Adds a quantitative category for values ranging fromminimumtomaximuminclusive in the given units of measurement.addQuantitative(CharSequence name, int lower, int upper, double scale, double offset, Unit<?> units) Adds a quantitative category for sample values ranging fromlowerinclusive toupperexclusive.addQuantitative(CharSequence name, NumberRange<?> samples, NumberRange<?> converted) Constructs a quantitative category mapping samples to real values in the specified range.addQuantitative(CharSequence name, NumberRange<?> samples, MathTransform1D toUnits, Unit<?> units) Constructs a quantitative category for all samples in the specified range of values.build()Creates a new sample with the properties defined to this builder.Returns the list of categories added so far.voidclear()Reset this builder to the same state than after construction.Returns the value specified by the last call to asetBackground(…)method.getName()Returns the name specified by the last call to asetName(…)method.mapQualitative(CharSequence name, Number sample, float converted) Adds a qualitative category for the given sample value mapped to the specified converted NaN value.mapQualitative(CharSequence name, NumberRange<?> samples, float converted) Adds a qualitative category for the given samples values mapped to the specified converted NaN value.setBackground(CharSequence name, Number sample) Adds a qualitative category and marks that category as the background value.setBackground(Number sample) Sets the background value without creating a category (typically for RGB images).setName(int band) Sets an identification of the sample dimension as a band number.setName(CharSequence name) Sets an identification of the sample dimension as a character sequence.setName(GenericName name) Sets an identification of the sample dimension.
-
Constructor Details
-
Builder
public Builder()Creates an initially empty builder for a sample dimension. Callers shall invoke at least oneaddFoo(…)method beforebuild().
-
-
Method Details
-
getName
Returns the name specified by the last call to asetName(…)method. IfsetName(…)has not been invoked or ifclear()has been invoked after, then this method returnsnull. In that case thebuild()method will default to the name of the first quantitative category if present, or "Untitled" (localized) otherwise.- Returns:
- the name explicitly set by last call to
setName(…), ornullif none or cleared. - Since:
- 1.2
- See Also:
-
setName
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
Sets an identification of the sample dimension as a character sequence. This is a convenience method for creating aGenericNamefrom the given characters.Default implementation
This convenience method delegates tosetName(GenericName).- Parameters:
name- identification of the sample dimension.- Returns:
this, for method call chaining.
-
setName
Sets an identification of the sample dimension as a band number. This method should be used only when no more descriptive name is available.Default implementation
This convenience method delegates tosetName(GenericName).- Parameters:
band- sequence identifier of the sample dimension to create.- Returns:
this, for method call chaining.
-
getBackground
Returns the value specified by the last call to asetBackground(…)method. IfsetBackground(…)has not been invoked or ifclear()has been invoked after, then this method returnsnull.- Returns:
- the value set by last call to
setBackground(…), ornullif none or cleared. - Since:
- 1.2
- See Also:
-
setBackground
Sets the background value without creating a category (typically for RGB images). An image without category is interpreted as an image for visualization purposes only, without values that we can associate to a unit of measurement or a qualitative meaning. ThissetBackground(Number)method can be invoked when the caller nevertheless wants to declare a background value used for filling empty spaces (e.g. in image corners).- Parameters:
sample- the background value, ornullif none.- Returns:
this, for method call chaining.- Since:
- 1.2
-
setBackground
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 aStringorInternationalStringobject, ornullfor a default "fill value" (localized) name.sample- the background value.- Returns:
this, for method call chaining.
-
addQualitative
Adds a qualitative category for samples of the given boolean value. Thetruevalue is represented by 1 and thefalsevalue is represented by 0.Usage note
ThesetBackground(CharSequence, Number)method should be used instead of this method when the aim is to define a default "no data" category to use when the missing value cannot be categorized more precisely (cloud, instrument error, etc).Default implementation
This convenience method delegates toaddQualitative(CharSequence, NumberRange).- Parameters:
name- the category name as aStringorInternationalStringobject, ornullfor a default "no data" name.sample- the sample value as a boolean.- Returns:
this, for method call chaining.
-
addQualitative
Adds a qualitative category for samples of the given tiny (8 bits) integer value. The argument is treated as a signed integer (0x80 to 0x7f).Usage note
ThesetBackground(CharSequence, Number)method should be used instead of this method when the aim is to define a default "no data" category to use when the missing value cannot be categorized more precisely (cloud, instrument error, etc).Default implementation
This convenience method delegates toaddQualitative(CharSequence, NumberRange).- Parameters:
name- the category name as aStringorInternationalStringobject, ornullfor a default "no data" name.sample- the sample value as an integer.- Returns:
this, for method call chaining.
-
addQualitative
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).Usage note
ThesetBackground(CharSequence, Number)method should be used instead of this method when the aim is to define a default "no data" category to use when the missing value cannot be categorized more precisely (cloud, instrument error, etc).Default implementation
This convenience method delegates toaddQualitative(CharSequence, NumberRange).- Parameters:
name- the category name as aStringorInternationalStringobject, ornullfor a default "no data" name.sample- the sample value as an integer.- Returns:
this, for method call chaining.
-
addQualitative
Adds a qualitative category for samples of the given integer value. The argument is treated as a signed integer (-2147483648 to 2147483647).Usage note
ThesetBackground(CharSequence, Number)method should be used instead of this method when the aim is to define a default "no data" category to use when the missing value cannot be categorized more precisely (cloud, instrument error, etc).Default implementation
This convenience method delegates toaddQualitative(CharSequence, NumberRange).- Parameters:
name- the category name as aStringorInternationalStringobject, ornullfor a default "no data" name.sample- the sample value as an integer.- Returns:
this, for method call chaining.
-
addQualitative
Adds a qualitative category for samples of the given floating-point value.Usage note
ThesetBackground(CharSequence, Number)method should be used instead of this method when the aim is to define a default "no data" category to use when the missing value cannot be categorized more precisely (cloud, instrument error, etc).Default implementation
This convenience method delegates toaddQualitative(CharSequence, NumberRange).- Parameters:
name- the category name as aStringorInternationalStringobject, ornullfor a default "no data" name.sample- the sample value as a real number or a NaN value.- Returns:
this, for method call chaining.
-
addQualitative
Adds a qualitative category for samples of the given double precision floating-point value.Usage note
ThesetBackground(CharSequence, Number)method should be used instead of this method when the aim is to define a default "no data" category to use when the missing value cannot be categorized more precisely (cloud, instrument error, etc).Default implementation
This convenience method delegates toaddQualitative(CharSequence, NumberRange).- Parameters:
name- the category name as aStringorInternationalStringobject, ornullfor a default "no data" name.sample- the sample value as a real number or a NaN value.- Returns:
this, for method call chaining.
-
addQualitative
Adds a qualitative category for samples in the given range of values.Usage note
ThesetBackground(CharSequence, Number)method should be used instead of this method when the aim is to define a default "no data" category to use when the missing value cannot be categorized more precisely (cloud, instrument error, etc).Default implementation
This convenience method delegates toaddQualitative(CharSequence, NumberRange).- Parameters:
name- the category name as aStringorInternationalStringobject, ornullfor 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
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.Usage note
ThesetBackground(CharSequence, Number)method should be used instead of this method when the aim is to define a default "no data" category to use when the missing value cannot be categorized more precisely (cloud, instrument error, etc).- Parameters:
name- the category name as aStringorInternationalStringobject, ornullfor 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.
-
mapQualitative
Adds a qualitative category for the given sample value mapped to the specified converted NaN value. The givenconvertedvalue must be a NaN value (not necessarily theFloat.NaNcanonical value) and that value shall not have been used by another category.Default implementation
This convenience method delegates tomapQualitative(CharSequence, NumberRange, float).- Parameters:
name- the category name as aStringorInternationalStringobject, ornullfor a default "no data" name.sample- the sample value as a real or integer number.converted- the converted value to map to the given sample value.Float.isNaN(converted)must betrue.- Returns:
this, for method call chaining.- Throws:
IllegalArgumentException- ifconvertedis not a NaN value.- Since:
- 1.1
- See Also:
-
mapQualitative
public SampleDimension.Builder mapQualitative(CharSequence name, NumberRange<?> samples, float converted) Adds a qualitative category for the given samples values mapped to the specified converted NaN value. The givenconvertedvalue must be a NaN value (not necessarily theFloat.NaNcanonical value) and that value shall not have been used by another category.The
addQualitative(…)methods select automatically a converted value. ThemapQualitative(…)methods are for the less common case where caller needs to control which converted NaN value is mapped to the samples values.- Parameters:
name- the category name as aStringorInternationalStringobject, ornullfor a default "no data" name.samples- the minimum and maximum sample values in the category.converted- the converted value to map to the given sample values.Float.isNaN(converted)must betrue.- Returns:
this, for method call chaining.- Throws:
IllegalArgumentException- ifconvertedis not a NaN value.- Since:
- 1.1
- See Also:
-
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 thesamplesrange will be mapped to real values in theconvertedrange 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 theconvertedrange 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.Default implementation
This convenience method delegates toaddQuantitative(CharSequence, NumberRange, MathTransform1D, Unit).- Parameters:
name- the category name as aStringorInternationalStringobject, ornullfor a default "data" name.samples- the minimum and maximum sample values in the category. Element class is usuallyInteger, butFloatandDoublevalues are accepted as well.converted- the range of real values for this category, as an instance ofMeasurementRangeif those values are associated to an unit of measurement.- Returns:
this, for method call chaining.- Throws:
ClassCastException- if the range element class is not aNumbersubclass.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 fromminimumtomaximuminclusive in the given units of measurement. The transfer function is set to identity.Default implementation
This convenience method delegates toaddQuantitative(CharSequence, NumberRange, MathTransform1D, Unit).- Parameters:
name- the category name as aStringorInternationalStringobject, ornullfor a default "data" name.minimum- the minimum value (inclusive) in the given units.maximum- the maximum value (inclusive) in the given units.units- the units of measurement, ornullif unknown or not applicable.- Returns:
this, for method call chaining.- Throws:
IllegalArgumentException- if a value is NaN or ifminimumis greater thanmaximum.
-
addQuantitative
public SampleDimension.Builder addQuantitative(CharSequence name, double minimum, double maximum, Unit<?> units) Adds a quantitative category for values ranging fromminimumtomaximuminclusive in the given units of measurement. The transfer function is set to identity.Default implementation
This convenience method delegates toaddQuantitative(CharSequence, NumberRange, MathTransform1D, Unit).- Parameters:
name- the category name as aStringorInternationalStringobject, ornullfor a default "data" name.minimum- the minimum value (inclusive) in the given units.maximum- the maximum value (inclusive) in the given units.units- the units of measurement, ornullif unknown or not applicable.- Returns:
this, for method call chaining.- Throws:
IllegalArgumentException- if a value is NaN or ifminimumis 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 fromlowerinclusive toupperexclusive. 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 theunitsargument.Default implementation
This convenience method delegates toaddQuantitative(CharSequence, NumberRange, MathTransform1D, Unit).- Parameters:
name- the category name as aStringorInternationalStringobject. ornullfor a default "data" name.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, ornullif unknown or not applicable.- Returns:
this, for method call chaining.- Throws:
IllegalArgumentException- ifloweris not smaller thanupper, or ifscaleoroffsetare not real numbers, or ifscaleis 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 thetoUnitstransform. Results of that conversion are measurements in the units specified by theunitsargument.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 aStringorInternationalStringobject, ornullfor a default "data" name.samples- the minimum and maximum sample values in the category. Element class is usuallyInteger, butFloatandDoubletypes 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, ornullif unknown or not applicable.- Returns:
this, for method call chaining.- Throws:
ClassCastException- if the range element class is not aNumbersubclass.IllegalArgumentException- if the range is invalid.- See Also:
-
categories
Returns the list of categories added so far. The returned list does not support theaddoperation, but supports theremoveoperation.- Returns:
- the current category list, read-only except for the
removeoperation.
-
build
Creates a new sample with the properties defined to this builder.- Returns:
- the sample dimension.
- Throws:
IllegalSampleDimensionException- if there is overlapping ranges of sample values or other problems that prevent the construction of sample dimensions.
-
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.
-