Transform1S.java
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.commons.geometry.spherical.oned;
import org.apache.commons.geometry.core.Transform;
/** Implementation of the {@link Transform} interface for spherical 1D points.
*
* <p>Similar to the Euclidean 1D
* {@link org.apache.commons.geometry.euclidean.oned.AffineTransformMatrix1D AffineTransformMatrix1D},
* this class performs transformations using an internal 1D affine transformation matrix. In the
* Euclidean case, the matrix contains a scale factor and a translation. Here, the matrix contains
* a scale/negation factor that takes the values -1 or +1, and a rotation value. This restriction on
* the allowed values in the matrix is required in order to fulfill the geometric requirements
* of the {@link Transform} interface. For example, if arbitrary scaling is allowed, the point {@code 0.5pi}
* could be scaled by 4 to {@code 2pi}, which is equivalent to {@code 0pi}. However, if the inverse scaling
* of {@code 1/4} is applied to {@code 0pi}, the result is {@code 0pi} and not {@code 0.5pi}. This breaks
* the {@link Transform} requirement that transforms be inversible.
* </p>
*
* <p>Instances of this class are guaranteed to be immutable.</p>
*/
public final class Transform1S implements Transform<Point1S> {
/** Static instance representing the identity transform. */
private static final Transform1S IDENTITY = new Transform1S(1, 0);
/** Static instance that negates azimuth values. */
private static final Transform1S NEGATION = new Transform1S(-1, 0);
/** Value to scale the point azimuth by. This will only be +1/-1. */
private final double scale;
/** Value to rotate the point azimuth by. */
private final double rotate;
/** Construct a new instance from its transform components.
* @param scale scale value for the transform; must only be +1 or -1
* @param rotate rotation value
*/
private Transform1S(final double scale, final double rotate) {
this.scale = scale;
this.rotate = rotate;
}
/** Return true if the transform negates the azimuth values of transformed
* points, regardless of any rotation applied subsequently.
* @return true if the transform negates the azimuth values of transformed
* points
* @see #preservesOrientation()
*/
public boolean isNegation() {
return scale <= 0;
}
/** Get the rotation value applied by this instance, in radians.
* @return the rotation value applied by this instance, in radians.
*/
public double getRotation() {
return rotate;
}
/** {@inheritDoc} */
@Override
public Point1S apply(final Point1S pt) {
final double az = pt.getAzimuth();
final double resultAz = (az * scale) + rotate;
return Point1S.of(resultAz);
}
/** {@inheritDoc} */
@Override
public boolean preservesOrientation() {
return !isNegation();
}
/** Return a new transform created by pre-multiplying this instance by a transform
* producing a rotation with the given angle.
* @param angle angle to rotate, in radians
* @return a new transform created by pre-multiplying this instance by a transform
* producing a rotation with the given angle
* @see #createRotation(double)
*/
public Transform1S rotate(final double angle) {
return premultiply(createRotation(angle));
}
/** Return a new transform created by pre-multiplying this instance by a transform
* that negates azimuth values.
* @return a new transform created by pre-multiplying this instance by a transform
* that negates azimuth values
*/
public Transform1S negate() {
return premultiply(createNegation());
}
/** Multiply the underlying matrix of this instance by that of the argument, eg,
* {@code other * this}. The returned transform performs the equivalent of
* {@code other} followed by {@code this}.
* @param other transform to multiply with
* @return a new transform computed by multiplying the matrix of this
* instance by that of the argument
*/
public Transform1S multiply(final Transform1S other) {
return multiply(this, other);
}
/** Multiply the underlying matrix of the argument by that of this instance, eg,
* {@code this * other}. The returned transform performs the equivalent of {@code this}
* followed by {@code other}.
* @param other transform to multiply with
* @return a new transform computed by multiplying the matrix of the
* argument by that of this instance
*/
public Transform1S premultiply(final Transform1S other) {
return multiply(other, this);
}
/** {@inheritDoc} */
@Override
public Transform1S inverse() {
final double invScale = 1.0 / scale;
final double resultRotate = -(rotate * invScale);
return new Transform1S(invScale, resultRotate);
}
/** {@inheritDoc} */
@Override
public int hashCode() {
final int prime = 31;
int result = 1;
result = (result * prime) + Double.hashCode(scale);
result = (result * prime) + Double.hashCode(rotate);
return result;
}
/**
* Return true if the given object is an instance of {@link Transform1S}
* and all transform element values are exactly equal.
* @param obj object to test for equality with the current instance
* @return true if all transform elements are exactly equal; otherwise false
*/
@Override
public boolean equals(final Object obj) {
if (this == obj) {
return true;
}
if (!(obj instanceof Transform1S)) {
return false;
}
final Transform1S other = (Transform1S) obj;
return Double.compare(scale, other.scale) == 0 &&
Double.compare(rotate, other.rotate) == 0;
}
/** {@inheritDoc} */
@Override
public String toString() {
final StringBuilder sb = new StringBuilder();
sb.append(this.getClass().getSimpleName())
.append("[negate= ")
.append(isNegation())
.append(", rotate= ")
.append(getRotation())
.append(']');
return sb.toString();
}
/** Return a transform instance representing the identity transform.
* @return a transform instance representing the identity transform
*/
public static Transform1S identity() {
return IDENTITY;
}
/** Return a transform instance that negates azimuth values.
* @return a transform instance that negates azimuth values.
*/
public static Transform1S createNegation() {
return NEGATION;
}
/** Return a transform instance that performs a rotation with the given
* angle.
* @param angle angle of the rotation, in radians
* @return a transform instance that performs a rotation with the given
* angle
*/
public static Transform1S createRotation(final double angle) {
return new Transform1S(1, angle);
}
/** Multiply two transforms together as matrices.
* @param a first transform
* @param b second transform
* @return the transform computed as {@code a x b}
*/
private static Transform1S multiply(final Transform1S a, final Transform1S b) {
// calculate the matrix elements
final double resultScale = a.scale * b.scale;
final double resultRotate = (a.scale * b.rotate) + a.rotate;
return new Transform1S(resultScale, resultRotate);
}
}