001    /*
002     * Histogram3D
003     *
004     * Copyright (c) 2001, 2002 Marco Schmidt <marcoschmidt@users.sourceforge.net>
005     * All rights reserved.
006     */
007    
008    package net.sourceforge.jiu.color.data;
009    
010    /**
011     * An interface for classes that store three-dimensional histograms.
012     * Histograms count the occurrence of values, so a three-dimensional
013     * histogram has counters for three-dimensional values.
014     * The 3D histograms are used (as an example) to count the occurrence of 
015     * each color in an RGB image.
016     *
017     * @author Marco Schmidt
018     * @see Histogram1D
019     */
020    public interface Histogram3D
021    {
022            /**
023             * Sets all counters to zero.
024             */
025            void clear();
026    
027            /**
028             * Returns the counter value of (index1, index2, index3).
029             * @param index1 first of the three values forming the threedimensional index
030             * @param index2 second of the three values forming the threedimensional index
031             * @param index3 three of the three values forming the threedimensional index
032             * @return the counter value of the desired index
033             * @throws IllegalArgumentException if the index formed by the arguments is invalid
034             */
035            int getEntry(int index1, int index2, int index3);
036    
037            /**
038             * Returns the maximum index value for one of the three indexes.
039             * @throws IllegalArgumentException if the index formed by the arguments is invalid
040             */
041            int getMaxValue(int index);
042    
043            /**
044             * Returns the number of used entries (those entries with
045             * a counter value larger than zero).
046             * @return number of non-zero counter values
047             */
048            int getNumUsedEntries();
049    
050            /**
051             * Increases the counter value of (index1, index2, index3) by one.
052             * This method can easily be implemented by the one-liner
053             * <code>setEntry(index1, index2, index3, getEntry(index1, index2, index3) + 1);</code>
054             * However, this method is expected to be faster in some contexts.
055             *
056             * @param index1 first of the three values forming the threedimensional index
057             * @param index2 second of the three values forming the threedimensional index
058             * @param index3 three of the three values forming the threedimensional index
059             * @return the counter value of the desired index
060             * @throws IllegalArgumentException if the index formed by the arguments is invalid
061             */
062            void increaseEntry(int index1, int index2, int index3);
063    
064            /**
065             * Sets the counter value of (index1, index2, index3) to newValue.
066             *
067             * @param index1 first of the three values forming the threedimensional index
068             * @param index2 second of the three values forming the threedimensional index
069             * @param index3 three of the three values forming the threedimensional index
070             * @param newValue the counter value that is assigned to the argument index
071             * @throws IllegalArgumentException if the index formed by the first three arguments is invalid
072             */
073            void setEntry(int index1, int index2, int index3, int newValue);
074    }