us.ihmc.euclid.referenceFrame.interfaces.FrameTuple4DReadOnly Maven / Gradle / Ivy
package us.ihmc.euclid.referenceFrame.interfaces;
import us.ihmc.euclid.referenceFrame.ReferenceFrame;
import us.ihmc.euclid.referenceFrame.exceptions.ReferenceFrameMismatchException;
import us.ihmc.euclid.referenceFrame.tools.EuclidFrameIOTools;
import us.ihmc.euclid.tools.EuclidCoreIOTools;
import us.ihmc.euclid.tuple4D.interfaces.Tuple4DReadOnly;
/**
* Read-only interface for a 4D tuple expressed in a given reference frame.
*
* In addition to representing a {@link Tuple4DReadOnly}, a {@link ReferenceFrame} is associated to
* a {@code FrameTuple4DReadOnly}. This allows, for instance, to enforce, at runtime, that
* operations on tuples occur in the same coordinate system.
*
*
* Because a {@code FrameTuple4DReadOnly} extends {@code Tuple4DReadOnly}, it is compatible with
* methods only requiring {@code Tuple4DReadOnly}. However, these methods do NOT assert that the
* operation occur in the proper coordinate system. Use this feature carefully and always prefer
* using methods requiring {@code FrameTuple4DReadOnly}.
*
*/
public interface FrameTuple4DReadOnly extends Tuple4DReadOnly, EuclidFrameGeometry
{
/**
* Calculates the norm of the difference between {@code this} and {@code other}.
*
* |{@code this} - {@code other}| = √[({@code this.x} - {@code other.x})2 +
* ({@code this.y} - {@code other.y})2 + ({@code this.z} - {@code other.z})2 +
* ({@code this.s} - {@code other.s})2]
*
*
* @param other the other tuple to compare to. Not modified.
* @return the norm squared of the difference.
* @throws ReferenceFrameMismatchException if {@code other} is not expressed in the same frame as
* {@code this}.
*/
default double differenceNorm(FrameTuple4DReadOnly other)
{
checkReferenceFrameMatch(other);
return Tuple4DReadOnly.super.differenceNorm(other);
}
/**
* Calculates the norm squared of the difference between {@code this} and {@code other}.
*
* |{@code this} - {@code other}|2 = ({@code this.x} - {@code other.x})2 +
* ({@code this.y} - {@code other.y})2 + ({@code this.z} - {@code other.z})2
* +({@code this.s} - {@code other.s})2
*
*
* @param other the other tuple to compare to. Not modified.
* @return the norm squared of the difference.
* @throws ReferenceFrameMismatchException if {@code other} is not expressed in the same frame as
* {@code this}.
*/
default double differenceNormSquared(FrameTuple4DReadOnly other)
{
checkReferenceFrameMatch(other);
return Tuple4DReadOnly.super.differenceNormSquared(other);
}
/**
* Calculates and returns the value of the dot product of this tuple with {@code other}.
*
* For instance, the dot product of two tuples p and q is defined as:
* p . q = ∑i=1:4(pi * qi)
*
*
* @param other the other vector used for the dot product. Not modified.
* @return the value of the dot product.
* @throws ReferenceFrameMismatchException if {@code other} is not expressed in the same reference
* frame as {@code this}.
*/
default double dot(FrameTuple4DReadOnly other)
{
checkReferenceFrameMatch(other);
return Tuple4DReadOnly.super.dot(other);
}
/**
* Gets a representative {@code String} of this tuple 4D given a specific format to use.
*
* Using the default format {@link EuclidCoreIOTools#DEFAULT_FORMAT}, this provides a {@code String}
* as follows:
*
*
* (-0.052, -0.173, -0.371, 0.087 ) - worldFrame
*
*
*/
@Override
default String toString(String format)
{
return EuclidFrameIOTools.getFrameTuple4DString(format, this);
}
}