001/*******************************************************************************
002 * This software is provided as a supplement to the authors' textbooks on digital
003 * image processing published by Springer-Verlag in various languages and editions.
004 * Permission to use and distribute this software is granted under the BSD 2-Clause
005 * "Simplified" License (see http://opensource.org/licenses/BSD-2-Clause).
006 * Copyright (c) 2006-2023 Wilhelm Burger, Mark J. Burge. All rights reserved.
007 * Visit https://imagingbook.com for additional details.
008 ******************************************************************************/
009
010package imagingbook.common.noise.hashing;
011
012import java.util.concurrent.ThreadLocalRandom;
013
014/**
015 * <p>
016 * Interface to all hash functions defined in this package. Typical usage example:
017 * </p>
018 * <pre>
019 * HashFun hf = new Hash32Ward(seed);
020 * double g = hf.hash(u); // g is in [-1,+1]
021 * double g = hf.hash(u, v);
022 * double[] g = hf.hash(u, v, w);
023 * </pre>
024 * <p>
025 * Omit seed in the constructor call or use seed = 0 to get a random seed hash function of the specified type.
026 * </p>
027 *
028 * @author WB
029 * @version 2022/11/24
030 */
031public interface HashFunction {
032        
033        static int getRandomSeed(int seed) {
034                int s = (seed == 0) ? ThreadLocalRandom.current().nextInt() : seed;
035                return 0x000fffff & s;
036        }
037
038        /**
039         * 1D hash function: maps a single {@code int} key to a {@code double} hash value in [0,1].
040         *
041         * @param u the key
042         * @return the hash value
043         */
044        public double hash(int u);                                      // 1D hash function
045
046        /**
047         * 2D hash function: maps a pair of {@code int} keys to a pair of {@code double} hash values in [0,1].
048         *
049         * @param u the 1st key
050         * @param v the 2nd key
051         * @return the hash values
052         */
053        public double[] hash(int u, int v);             // 2D hash function
054
055        /**
056         * 3D hash function: maps a triplet of {@code int} keys to a triplet of {@code double} hash values in [0,1].
057         *
058         * @param u the 1st key
059         * @param v the 2nd key
060         * @param w the 3rd key
061         * @return the hash values
062         */
063        public double[] hash(int u, int v, int w);
064
065        /**
066         * N-dimensional hash function: maps a N-vector of {@code int} keys to N-vector of {@code double} hash values in
067         * [0,1].
068         *
069         * @param p a N-vector of keys
070         * @return a N-vector of hash values
071         */
072        public double[] hash(int[] p);
073        
074}
075
076