001/*
002 *                    BioJava development code
003 *
004 * This code may be freely distributed and modified under the
005 * terms of the GNU Lesser General Public Licence.  This should
006 * be distributed with the code.  If you do not have a copy,
007 * see:
008 *
009 *      http://www.gnu.org/copyleft/lesser.html
010 *
011 * Copyright for this code is held jointly by the individual
012 * authors.  These should be listed in @author doc comments.
013 *
014 * For more information on the BioJava project and its aims,
015 * or to join the biojava-l mailing list, visit the home page
016 * at:
017 *
018 *      http://www.biojava.org/
019 *
020 */
021package org.biojava.nbio.structure.geometry;
022
023import javax.vecmath.Matrix4d;
024import javax.vecmath.Point3d;
025
026/**
027 * The SuperPosition interface defines and documents the required methods for
028 * any superpostion algorithm implementation, so that the input and expected
029 * output are uniform.
030 *
031 * @author Aleix Lafita
032 * @since 5.0.0
033 *
034 */
035public interface SuperPosition {
036
037        /**
038         * Obtain the superposition matrix that minimizes the RMSD between two
039         * arrays of equivalent points.
040         * <p>
041         * The two point arrays have to be of the same length and the order of
042         * points have to be the same, so that a specific position in the one array
043         * is equivalent to the same position in the other array.
044         *
045         * @param fixed
046         *            point array as reference, onto which the other point array is
047         *            superposed. Original coordinates will not be modified.
048         * @param moved
049         *            point array to which the resulting transformation matrix is
050         *            applied. Original coordinates will not be modified.
051         * @return transformation matrix as a Matrix4d to superpose moved onto fixed
052         *         point arrays
053         */
054        public Matrix4d superpose(Point3d[] fixed, Point3d[] moved);
055
056        /**
057         * Transform an array of points so that the coordinates of its points
058         * minimize the RMSD to the other array of equivalent points, and return the
059         * transformation matrix applied.
060         * <p>
061         * The two point arrays have to be of the same length and the order of
062         * points have to be the same, so that a specific position in the one array
063         * is equivalent to the same position in the other array.
064         *
065         * @param fixed
066         *            point array as reference, onto which the other point array is
067         *            superposed. Original coordinates will not be modified.
068         * @param moved
069         *            point array to which the resulting transformation matrix is
070         *            applied. Original coordinates will be transformed.
071         * @return transformation matrix as a Matrix4d to superpose moved onto fixed
072         *         point arrays
073         */
074        public Matrix4d superposeAndTransform(Point3d[] fixed, Point3d[] moved);
075
076        /**
077         * Calculate the RMSD between two arrays of equivalent points that are not
078         * superposed.
079         * <p>
080         * This is equivalent to first superposing the point arrays with
081         * {@link SuperPosition#superposeAndTransform(Point3d[], Point3d[])} and
082         * then calculating the RMSD of the superposed point arrays with
083         * {@link CalcPoint#rmsd(Point3d[], Point3d[])}, but it will be faster when
084         * the transformation matrix is not needed.
085         * <p>
086         * The two point arrays have to be of the same length and the order of
087         * points have to be the same, so that a specific position in the one array
088         * is equivalent to the same position in the other array.
089         *
090         * @param x
091         *            an array of points. Original coordinates will not be modified.
092         * @param y
093         *            an array of points. Original coordinates will not be modified.
094         * @return the minimum RMSD between the equivalent point arrays (after
095         *         superposition)
096         */
097        public double getRmsd(Point3d[] x, Point3d[] y);
098
099}