001/*
002 *    GeoAPI - Java interfaces for OGC/ISO standards
003 *    Copyright © 2004-2023 Open Geospatial Consortium, Inc.
004 *    http://www.geoapi.org
005 *
006 *    Licensed under the Apache License, Version 2.0 (the "License");
007 *    you may not use this file except in compliance with the License.
008 *    You may obtain a copy of the License at
009 *
010 *        http://www.apache.org/licenses/LICENSE-2.0
011 *
012 *    Unless required by applicable law or agreed to in writing, software
013 *    distributed under the License is distributed on an "AS IS" BASIS,
014 *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 *    See the License for the specific language governing permissions and
016 *    limitations under the License.
017 */
018package org.opengis.referencing.operation;
019
020import org.opengis.annotation.UML;
021
022import static org.opengis.annotation.Specification.*;
023
024
025/**
026 * A two dimensional array of numbers. Row and column numbering begins with zero.
027 *
028 * @author  Martin Desruisseaux (IRD)
029 * @version 3.1
030 * @since   1.0
031 */
032@UML(identifier="PT_Matrix", specification=OGC_01009)
033public interface Matrix {
034    /**
035     * Returns the number of rows in this matrix.
036     *
037     * @return the number of rows in this matrix.
038     */
039    @UML(identifier="num_row", specification=OGC_01009)     // Defined in WKT 1
040    int getNumRow();
041
042    /**
043     * Returns the number of columns in this matrix.
044     *
045     * @return the number of columns in this matrix.
046     */
047    @UML(identifier="num_col", specification=OGC_01009)     // Defined in WKT 1
048    int getNumCol();
049
050    /**
051     * Returns {@code true} if this matrix is an identity matrix.
052     *
053     * <p>The default returns {@code true} if this matrix is square and if
054     * {@link #getElement(int, int)} returns 1 on the diagonal and 0 everywhere else.
055     * Otherwise this method returns {@code false}.</p>
056     *
057     * @return {@code true} if this matrix is an identity matrix.
058     *
059     * @departure easeOfUse
060     *   Added as a convenience for a frequently requested operation.
061     */
062    default boolean isIdentity() {
063        final int n = getNumRow();
064        if (getNumCol() != n) {
065            return false;
066        }
067        for (int row=0; row<n; row++) {
068            for (int column=0; column<n; column++) {
069                if (getElement(row, column) != (row == column ? 1 : 0)) {
070                    return false;
071                }
072            }
073        }
074        return true;
075    }
076
077    /**
078     * Retrieves the value at the specified row and column of this matrix.
079     *
080     * @param  row     the row number to be retrieved (zero indexed).
081     * @param  column  the column number to be retrieved (zero indexed).
082     * @return the value at the indexed element.
083     * @throws IndexOutOfBoundsException if the specified row or column is out of bounds.
084     */
085    @UML(identifier="elt", specification=OGC_01009)         // Defined in WKT 1
086    double getElement(int row, int column);
087
088    /**
089     * Modifies the value at the specified row and column of this matrix.
090     * This is an optional method.
091     *
092     * <p>The default throws {@link UnsupportedOperationException}.</p>
093     *
094     * @param  row     the row number of the value to set (zero indexed).
095     * @param  column  the column number of the value to set (zero indexed).
096     * @param  value   the new matrix element value.
097     * @throws IndexOutOfBoundsException if the specified row or column is out of bounds.
098     * @throws UnsupportedOperationException if this matrix is unmodifiable.
099     */
100    default void setElement(int row, int column, double value) {
101        throw new UnsupportedOperationException();
102    }
103
104    /**
105     * Returns a modifiable copy of this matrix.
106     *
107     * @return a modifiable copy of this matrix.
108     */
109    Matrix clone();
110}