AbstractAffineTransformMatrix.java

  1. /*
  2.  * Licensed to the Apache Software Foundation (ASF) under one or more
  3.  * contributor license agreements.  See the NOTICE file distributed with
  4.  * this work for additional information regarding copyright ownership.
  5.  * The ASF licenses this file to You under the Apache License, Version 2.0
  6.  * (the "License"); you may not use this file except in compliance with
  7.  * the License.  You may obtain a copy of the License at
  8.  *
  9.  *      http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */
  17. package org.apache.commons.geometry.euclidean;

  18. /** Base class for affine transform matrices in Euclidean space.
  19.  *
  20.  * @param <V> Vector/point implementation type defining the space.
  21.  * @param <M> Matrix transform implementation type.
  22.  */
  23. public abstract class AbstractAffineTransformMatrix<
  24.         V extends EuclideanVector<V>,
  25.         M extends AbstractAffineTransformMatrix<V, M>>
  26.     implements EuclideanTransform<V> {

  27.     /** Apply this transform to the given vector, ignoring translations and normalizing the
  28.      * result. This is equivalent to {@code transform.applyVector(vec).normalize()} but without
  29.      * the intermediate vector instance.
  30.      *
  31.      * @param vec the vector to transform
  32.      * @return the new, transformed unit vector
  33.      * @throws IllegalArgumentException if the transformed vector coordinates cannot be normalized
  34.      * @see #applyVector(EuclideanVector)
  35.      */
  36.     public abstract V applyDirection(V vec);

  37.     /** Get the determinant of the matrix.
  38.      * @return the determinant of the matrix
  39.      */
  40.     public abstract double determinant();

  41.     /** {@inheritDoc}
  42.      * @throws IllegalStateException if the matrix cannot be inverted
  43.      */
  44.     @Override
  45.     public abstract M inverse();

  46.     /** Return a matrix containing only the linear portion of this transform.
  47.      * The returned instance contains the same matrix elements as this instance
  48.      * but with the translation component set to zero.
  49.      * @return a matrix containing only the linear portion of this transform
  50.      */
  51.     public abstract M linear();

  52.     /** Return a matrix containing the transpose of the linear portion of this transform.
  53.      * The returned instance is linear, meaning it has a translation component of zero.
  54.      * @return a matrix containing the transpose of the linear portion of this transform
  55.      */
  56.     public abstract M linearTranspose();

  57.     /** Return a transform suitable for transforming normals. The returned matrix is
  58.      * the inverse transpose of the linear portion of this instance, i.e.
  59.      * <code>N = (L<sup>-1</sup>)<sup>T</sup></code>, where <code>L</code> is the linear portion
  60.      * of this instance and <code>N</code> is the returned matrix. Note that normals
  61.      * transformed with the returned matrix may be scaled during transformation and require
  62.      * normalization.
  63.      * @return a transform suitable for transforming normals
  64.      * @throws IllegalStateException if the matrix cannot be inverted
  65.      * @see <a href="https://en.wikipedia.org/wiki/Normal_(geometry)#Transforming_normals">Transforming normals</a>
  66.      */
  67.     public M normalTransform() {
  68.         return inverse().linearTranspose();
  69.     }

  70.     /** {@inheritDoc}
  71.      *
  72.      * <p>This method returns true if the determinant of the matrix is positive.</p>
  73.      */
  74.     @Override
  75.     public boolean preservesOrientation() {
  76.         return determinant() > 0.0;
  77.     }
  78. }