us.ihmc.euclid.referenceFrame.interfaces.FrameTuple2DReadOnly 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.tuple2D.interfaces.Tuple2DReadOnly;
/**
* Read-only interface for a 2D tuple expressed in a given reference frame.
*
* In addition to representing a {@link Tuple2DReadOnly}, a {@link ReferenceFrame} is associated to
* a {@code FrameTuple2DReadOnly}. This allows, for instance, to enforce, at runtime, that
* operations on tuples occur in the same coordinate system.
*
*
* Because a {@code FrameTuple2DReadOnly} extends {@code Tuple2DReadOnly}, it is compatible with
* methods only requiring {@code Tuple2DReadOnly}. 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 FrameTuple2DReadOnly}.
*
*/
public interface FrameTuple2DReadOnly extends Tuple2DReadOnly, 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]
*
*
* @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(FrameTuple2DReadOnly other)
{
checkReferenceFrameMatch(other);
return Tuple2DReadOnly.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
*
*
* @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(FrameTuple2DReadOnly other)
{
checkReferenceFrameMatch(other);
return Tuple2DReadOnly.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:2(pi * qi)
*
*
* @param other the other tuple 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 frame as
* {@code this}.
*/
default double dot(FrameTuple2DReadOnly other)
{
checkReferenceFrameMatch(other);
return Tuple2DReadOnly.super.dot(other);
}
/**
* Gets a representative {@code String} of this tuple 2D given a specific format to use.
*
* Using the default format {@link EuclidCoreIOTools#DEFAULT_FORMAT}, this provides a {@code String}
* as follows:
*
*
* (-0.675, -0.102 ) - worldFrame
*
*
*/
@Override
default String toString(String format)
{
return EuclidFrameIOTools.getFrameTuple2DString(format, this);
}
}