Class LinearConverter
- All Implemented Interfaces:
Serializable
,javax.measure.UnitConverter
,LenientComparable
isLinear()
method inherited from JSR-363.
Implementation note:
for performance reason we should create specialized subtypes for the case where there is only a scale to apply,
or only an offset, etc. But we don't do that in Apache SIS implementation because we will rarely use the
UnitConverter
for converting a lot of values. We rather use MathTransform
for operations on
n-dimensional tuples, and unit conversions are only a special case of those more generic operations.
The sis-referencing
module provided the specialized implementations needed for efficient operations
and know how to copy the UnitConverter
coefficients into an affine transform matrix.
- Since:
- 0.8
- Version:
- 1.0
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate final double
A divisor applied after the conversion.private LinearConverter
The inverse of this unit converter.private final double
The offset to apply after the scale, before division bydivisor
.private BigDecimal
The scale and offset factors represented in base 10, computed when first needed.private final double
The scale to apply for converting values, before division bydivisor
.private BigDecimal
The scale and offset factors represented in base 10, computed when first needed.private static final long
For cross-version compatibility. -
Constructor Summary
ConstructorsConstructorDescriptionLinearConverter
(double scale, double offset, double divisor) Creates a new linear converter for the given scale and offset. -
Method Summary
Modifier and TypeMethodDescription(package private) final boolean
Returnstrue
if this converter is close to an identity converter.(package private) final Number[]
Returns the coefficient of this linear conversion.javax.measure.UnitConverter
concatenate
(javax.measure.UnitConverter converter) Concatenates this converter with another converter.double
convert
(double value) Applies the linear conversion on the given IEEE 754 floating-point value.Applies the linear conversion on the given value.(package private) static AbstractConverter
Creates a linear converter from the given scale and offset, which may beBigDecimal
instances.double
derivative
(double value) Returns the derivative of the conversion at the given value.boolean
Compares this converter with the given object for equality.boolean
equals
(Object other, ComparisonMode mode) Compares this converter with the given object for equality, optionally ignoring rounding errors.(package private) final boolean
equivalent
(LinearConverter other) Returnstrue
if the given converter perform the same conversion than this converter, except for rounding errors.int
hashCode()
Returns a hash code value for this unit converter.javax.measure.UnitConverter
inverse()
Returns the inverse of this unit converter.boolean
Returnstrue
if the effective scale factor is 1 and the offset is zero.boolean
isLinear()
Indicates if this converter is linear.(package private) static LinearConverter
offset
(double numerator, double denominator) Returns a converter for the given shift.(package private) static LinearConverter
pow
(javax.measure.UnitConverter converter, int n, boolean root) Raises the given converter to the given power.private static Number
ratio
(double value, double divisor) (package private) static LinearConverter
scale
(double numerator, double denominator) Returns a linear converter for the given ratio.toString()
Returns a string representation of this converter for debugging purpose.Methods inherited from class org.apache.sis.measure.AbstractConverter
derivative, doubleValue, epsilonEquals, getConversionSteps, scale
-
Field Details
-
serialVersionUID
private static final long serialVersionUIDFor cross-version compatibility.- See Also:
-
scale
private final double scaleThe scale to apply for converting values, before division bydivisor
. -
offset
private final double offsetThe offset to apply after the scale, before division bydivisor
. -
divisor
private final double divisorA divisor applied after the conversion. The complete formula used by Apache SIS isy = (x*scale + offset) / divisor
. This division is mathematically unneeded since we could divide the offset and scale factor directly, but we keep it for accuracy reasons because most unit conversion factors are defined in base 10 and IEEE 754 cannot represent fractional values in base 10 accurately. -
scale10
The scale and offset factors represented in base 10, computed when first needed. Those terms are pre-divided by the divisor. -
offset10
The scale and offset factors represented in base 10, computed when first needed. Those terms are pre-divided by the divisor. -
inverse
The inverse of this unit converter. Computed when first needed.
-
-
Constructor Details
-
LinearConverter
LinearConverter(double scale, double offset, double divisor) Creates a new linear converter for the given scale and offset. The complete formula applied isy = (x*scale + offset) / divisor
.
-
-
Method Details
-
create
Creates a linear converter from the given scale and offset, which may beBigDecimal
instances. This is the implementation of publicUnits.converter(Number, Number)
method. -
scale
Returns a linear converter for the given ratio. The scale factor is specified as a ratio because the unit conversion factors are often defined with a value in base 10. That value is considered exact by definition, but IEEE 754 has no exact representation of decimal fraction digits.It is caller's responsibility to skip this method call when
numerator
=denominator
. This method does not perform this check because it is usually already done (indirectly) by the caller. -
offset
Returns a converter for the given shift. The translation is specified as a fraction because the unit conversion terms are often defined with a value in base 10. That value is considered exact by definition, but IEEE 754 has no exact representation of decimal fraction digits.It is caller's responsibility to skip this method call when
numerator
= 0. This method does not perform this check because it is usually already done by the caller. -
pow
Raises the given converter to the given power. This method assumes that the given converter is linear (this is not verified) and takes only the scale factor; the offset (if any) is ignored.It is caller's responsibility to skip this method call when
n
= 1. This method does not perform this check because it is usually already done (indirectly) by the caller.- Parameters:
converter
- the converter to raise to the given power.n
- the exponent.root
-true
for raising to 1/n instead of n.- Returns:
- the converter raised to the given power.
-
isLinear
public boolean isLinear()Indicates if this converter is linear. JSR-363 defines a converter as linear if:convert(u + v) == convert(u) + convert(v)
convert(r * u) == r * convert(u)
- Specified by:
isLinear
in interfacejavax.measure.UnitConverter
- Overrides:
isLinear
in classAbstractConverter
-
isIdentity
public boolean isIdentity()Returnstrue
if the effective scale factor is 1 and the offset is zero.- Specified by:
isIdentity
in interfacejavax.measure.UnitConverter
- Overrides:
isIdentity
in classAbstractConverter
-
almostIdentity
final boolean almostIdentity()Returnstrue
if this converter is close to an identity converter. -
inverse
public javax.measure.UnitConverter inverse()Returns the inverse of this unit converter. Given that the formula applied by this converter is: the inverse formula is:- Specified by:
inverse
in interfacejavax.measure.UnitConverter
-
coefficients
Returns the coefficient of this linear conversion.- Overrides:
coefficients
in classAbstractConverter
-
ratio
Returns the given ratio as aFraction
if possible, or as aDouble
otherwise. The use ofFraction
allows theorg.apache.sis.referencing.operation.matrix
package to perform more accurate calculations. -
convert
public double convert(double value) Applies the linear conversion on the given IEEE 754 floating-point value.- Specified by:
convert
in interfacejavax.measure.UnitConverter
-
convert
Applies the linear conversion on the given value. This method usesBigDecimal
arithmetic if the given value is an instance ofBigDecimal
, or IEEE 754 floating-point arithmetic otherwise.Apache SIS rarely uses
BigDecimal
arithmetic, so providing an efficient implementation of this method is not a goal.- Specified by:
convert
in interfacejavax.measure.UnitConverter
- Overrides:
convert
in classAbstractConverter
-
derivative
public double derivative(double value) Returns the derivative of the conversion at the given value. For a linear converter, the derivative is the same everywhere.- Specified by:
derivative
in classAbstractConverter
- Parameters:
value
- the point at which to compute the derivative. Ignored (can beDouble.NaN
) if the conversion is linear.
-
concatenate
public javax.measure.UnitConverter concatenate(javax.measure.UnitConverter converter) Concatenates this converter with another converter. The resulting converter is equivalent to first converting by the specified converter (right converter), and then converting by this converter (left converter). In the following equations, the 1 subscript is for the specified converter and the 2 subscript is for this converter: We rewrite as:- Specified by:
concatenate
in interfacejavax.measure.UnitConverter
- Overrides:
concatenate
in classAbstractConverter
-
hashCode
public int hashCode()Returns a hash code value for this unit converter. -
equals
Compares this converter with the given object for equality.- Specified by:
equals
in interfaceLenientComparable
- Overrides:
equals
in classObject
- Parameters:
other
- the object to compare tothis
.- Returns:
true
if both objects are strictly equal.- See Also:
-
equals
Compares this converter with the given object for equality, optionally ignoring rounding errors.- Specified by:
equals
in interfaceLenientComparable
- Parameters:
other
- the object to compare tothis
.mode
- the strictness level of the comparison.- Returns:
true
if both objects are equal according the given comparison mode.- See Also:
-
equivalent
Returnstrue
if the given converter perform the same conversion than this converter, except for rounding errors. -
toString
Returns a string representation of this converter for debugging purpose. This string representation may change in any future SIS release. Current format is of the form "y = scaleā x + offset".
-